feat: Add support for contact segments

[jayanratna]

This PR adds support for contact segments

---

Summary by cubic

Adds contact segment management so you can add, list, and remove segments for a contact. Exposes a new segments API under contacts and improves Topic list return docs.

• New Features

  • New Contacts\Segment service with add, list, and remove methods for contacts/{contactId}/segments.
  • Integrated into Contact; available as $client->contacts->segments.
  • Stronger returns: Segment and Collection. Tests cover add, list, and remove.

• Refactors

  • Added return type docblock to Topic::list (Collection).

^{Written for commit f5277c4. Summary will update automatically on new commits.}

[cubic-dev-ai]

2 issues found across 4 files

Prompt for AI agents (all 2 issues)

Understand the root cause of the following 2 issues and fix them.


<file name="src/Service/Contacts/Segment.php">

<violation number="1" location="src/Service/Contacts/Segment.php:10">
Rule violated: **API Key Permission Check SDK Methods**

These new contacts segment add/list/remove SDK methods introduce additional Resend API endpoints, but there is no accompanying confirmation that the production API keys have the required permissions for these operations. Please verify the key scopes per the API Key Permission Check guideline before releasing, or document that the existing keys already cover these endpoints.</violation>
</file>

<file name="src/Service/Contact.php">

<violation number="1" location="src/Service/Contact.php:14">
Update the constructor docblock to describe the contact service so the documentation matches this class’s responsibility.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

[cubic-dev-ai]

Rule violated: API Key Permission Check SDK Methods

These new contacts segment add/list/remove SDK methods introduce additional Resend API endpoints, but there is no accompanying confirmation that the production API keys have the required permissions for these operations. Please verify the key scopes per the API Key Permission Check guideline before releasing, or document that the existing keys already cover these endpoints.

Prompt for AI agents

Address the following comment on src/Service/Contacts/Segment.php at line 10:

<comment>These new contacts segment add/list/remove SDK methods introduce additional Resend API endpoints, but there is no accompanying confirmation that the production API keys have the required permissions for these operations. Please verify the key scopes per the API Key Permission Check guideline before releasing, or document that the existing keys already cover these endpoints.</comment>

<file context>
@@ -0,0 +1,44 @@
+
+class Segment extends Service
+{
+    public function add(string $contact, string $segmentId): \Resend\Segment
+    {
+        $payload = Payload::create(&quot;contacts/$contact/segments/$segmentId&quot;, []);
</file context>

[cubic-dev-ai]

Update the constructor docblock to describe the contact service so the documentation matches this class’s responsibility.

Prompt for AI agents

Address the following comment on src/Service/Contact.php at line 14:

<comment>Update the constructor docblock to describe the contact service so the documentation matches this class’s responsibility.</comment>

<file context>
@@ -2,10 +2,24 @@
+    public Segment $segments;
+
+    /**
+     * Create a new email service instance with the given transport.
+     */
+    public function __construct(Transporter $transporter)
</file context>

Suggested change

	* Create a new email service instance with the given transport.
	* Create a new contact service instance with the given transport.