wip

Author: bjarn

README.md

@@ -29,14 +29,14 @@ Initialize the Lettermint client with your Sending API token:
 $lettermint = new Lettermint\Lettermint('your-api-token');
 ```
 
-For new integrations, prefer the explicit Sending and Team clients:
+For new integrations, prefer explicit clients for the two API surfaces:
 
 ```php
-$sending = Lettermint\Lettermint::sending(getenv('LETTERMINT_SENDING_TOKEN'));
-$team = Lettermint\Lettermint::team(getenv('LETTERMINT_TEAM_TOKEN'));
+$email = Lettermint\Lettermint::email(getenv('LETTERMINT_SENDING_TOKEN'));
+$api = Lettermint\Lettermint::api(getenv('LETTERMINT_API_TOKEN'));
 ```
 
-Sending API tokens are project-specific and authenticate with the `x-lettermint-token` header. Team API tokens are team-scoped and authenticate with `Authorization: Bearer ...`. Keep these tokens separate and never reuse a Team token for sending-only workloads.
+Sending API tokens are project-specific and authenticate with the `x-lettermint-token` header. API tokens are team-scoped and authenticate with `Authorization: Bearer ...`. Keep these tokens separate and never reuse an API token for sending-only workloads.
 
 ### Sending Emails
 
@@ -75,7 +75,7 @@ $lettermint->email
 You can also send with an array payload:
 
 ```php
-$response = $sending->email->send([
+$response = $email->send([
     'from' => 'sender@example.com',
     'to' => ['recipient@example.com'],
     'subject' => 'Hello from Lettermint!',
@@ -86,7 +86,7 @@ $response = $sending->email->send([
 ### Batch Sending
 
 ```php
-$response = $sending->email->sendBatch([
+$response = $email->sendBatch([
     [
         'from' => 'sender@example.com',
         'to' => ['recipient@example.com'],
@@ -135,46 +135,46 @@ same request with the same idempotency key, the API will return the same respons
 
 For more information, refer to the [documentation](https://docs.lettermint.co/platform/emails/idempotency).
 
-### Team API
+### API Client
 
-Use the Team API client for team-scoped resources such as projects, domains, routes, suppressions, stats, messages, and webhooks:
+Use the API client for team-scoped resources such as projects, domains, routes, suppressions, stats, messages, and webhooks:
 
 ```php
-$team = Lettermint\Lettermint::team(getenv('LETTERMINT_TEAM_TOKEN'));
+$api = Lettermint\Lettermint::api(getenv('LETTERMINT_API_TOKEN'));
 
-$projects = $team->projects->list(['filter[search]' => 'production']);
+$projects = $api->projects->list(['filter[search]' => 'production']);
 
-$project = $team->projects->create([
+$project = $api->projects->create([
     'name' => 'Production',
     'smtp_enabled' => false,
 ]);
 
-$team->domains->verifyDnsRecords('domain-id');
+$api->domains->verifyDnsRecords('domain-id');
 
-$stats = $team->stats->retrieve([
+$stats = $api->stats->retrieve([
     'from' => '2026-05-01',
     'to' => '2026-05-09',
 ]);
 
-$team->suppressions->create([
+$api->suppressions->create([
     'email' => 'user@example.com',
     'reason' => 'manual',
     'scope' => 'team',
 ]);
 
-$team->webhooks->create([
+$api->webhooks->create([
     'route_id' => 'route-id',
     'name' => 'Production webhook',
     'url' => 'https://example.com/lettermint/webhook',
     'events' => ['message.sent', 'message.delivered'],
 ]);
 ```
 
-Both clients support `ping()`:
+Both API surfaces support `ping()`:
 
 ```php
-$sending->ping();
-$team->ping();
+$email->ping();
+$api->ping();
 ```
 
 ## Testing

src/Client/TeamClient.php src/Client/ApiClient.phpsrc/Client/TeamClient.php renamed to src/Client/ApiClient.php

@@ -22,7 +22,7 @@
  * @property-read TeamEndpoint $team Access team operations.
  * @property-read WebhooksEndpoint $webhooks Access webhook operations.
  */
-class TeamClient
+class ApiClient
 {
     private HttpClient $httpClient;
 

src/Client/SendingClient.php

@@ -2,64 +2,60 @@
 
 namespace Lettermint\Endpoints;
 
+use Lettermint\Responses\DeleteDomainResponse;
+use Lettermint\Responses\DomainListResponse;
+use Lettermint\Responses\DomainResponse;
+use Lettermint\Responses\UpdateDomainProjectsResponse;
+use Lettermint\Responses\VerifyDnsRecordResponse;
+use Lettermint\Responses\VerifyDnsRecordsResponse;
+
 /**
- * @phpstan-import-type CursorPage from \Lettermint\Types\ApiTypes
- * @phpstan-import-type ApiObject from \Lettermint\Types\ApiTypes
  * @phpstan-import-type StoreDomainData from \Lettermint\Types\ApiTypes
  * @phpstan-import-type UpdateDomainProjectsData from \Lettermint\Types\ApiTypes
  */
 class DomainsEndpoint extends Endpoint
 {
-    /** @phpstan-return CursorPage */
-    public function list(array $query = []): array
+    public function list(array $query = []): DomainListResponse
     {
-        return $this->getArray($this->path('/domains'), $query);
+        return $this->hydrate(DomainListResponse::class, $this->getArray($this->path('/domains'), $query));
     }
 
     /**
      * @phpstan-param StoreDomainData $data
-     *
-     * @phpstan-return ApiObject
      */
-    public function create(array $data): array
+    public function create(array $data): DomainResponse
     {
-        return $this->postArray($this->path('/domains'), $data, []);
+        return $this->hydrate(DomainResponse::class, $this->postArray($this->path('/domains'), $data, []));
     }
 
-    /** @phpstan-return ApiObject */
-    public function retrieve(string $domainId, array $query = []): array
+    public function retrieve(string $domainId, array $query = []): DomainResponse
     {
-        return $this->getArray($this->path('/domains/{domainId}', ['domainId' => $domainId]), $query);
+        return $this->hydrate(DomainResponse::class, $this->getArray($this->path('/domains/{domainId}', ['domainId' => $domainId]), $query));
     }
 
-    /** @phpstan-return ApiObject */
-    public function delete(string $domainId): array
+    public function delete(string $domainId): DeleteDomainResponse
     {
-        return $this->deleteArray($this->path('/domains/{domainId}', ['domainId' => $domainId]), []);
+        return $this->hydrate(DeleteDomainResponse::class, $this->deleteArray($this->path('/domains/{domainId}', ['domainId' => $domainId]), []));
     }
 
-    /** @phpstan-return ApiObject */
-    public function verifyDnsRecords(string $domainId): array
+    public function verifyDnsRecords(string $domainId): VerifyDnsRecordsResponse
     {
-        return $this->postArray($this->path('/domains/{domainId}/dns-records/verify', ['domainId' => $domainId]), [], []);
+        return $this->hydrate(VerifyDnsRecordsResponse::class, $this->postArray($this->path('/domains/{domainId}/dns-records/verify', ['domainId' => $domainId]), [], []));
     }
 
-    /** @phpstan-return ApiObject */
-    public function verifyDnsRecord(string $domainId, string $recordId): array
+    public function verifyDnsRecord(string $domainId, string $recordId): VerifyDnsRecordResponse
     {
-        return $this->postArray($this->path('/domains/{domainId}/dns-records/{recordId}/verify', [
+        return $this->hydrate(VerifyDnsRecordResponse::class, $this->postArray($this->path('/domains/{domainId}/dns-records/{recordId}/verify', [
             'domainId' => $domainId,
             'recordId' => $recordId,
-        ]), [], []);
+        ]), [], []));
     }
 
     /**
      * @phpstan-param UpdateDomainProjectsData $data
-     *
-     * @phpstan-return ApiObject
      */
-    public function updateProjects(string $domainId, array $data): array
+    public function updateProjects(string $domainId, array $data): UpdateDomainProjectsResponse
     {
-        return $this->putArray($this->path('/domains/{domainId}/projects', ['domainId' => $domainId]), $data, []);
+        return $this->hydrate(UpdateDomainProjectsResponse::class, $this->putArray($this->path('/domains/{domainId}/projects', ['domainId' => $domainId]), $data, []));
     }
 }

src/Endpoints/DomainsEndpoint.php

@@ -2,11 +2,12 @@
 
 namespace Lettermint\Endpoints;
 
+use Lettermint\Responses\SendBatchMailResponse;
+use Lettermint\Responses\SendMailResponse;
+
 /**
  * @phpstan-import-type SendMailRequest from \Lettermint\Types\ApiTypes
  * @phpstan-import-type SendBatchMailRequest from \Lettermint\Types\ApiTypes
- * @phpstan-import-type SendMailResponse from \Lettermint\Types\ApiTypes
- * @phpstan-import-type SendBatchMailResponse from \Lettermint\Types\ApiTypes
  *
  * @phpstan-type AttachmentPayload array{
  *     filename: string,
@@ -34,10 +35,6 @@
  *     settings?: EmailSettings|null,
  *     headers?: array<string, string>
  * }
- * @phpstan-type SendResponse array{
- *     message_id: string,
- *     status: string
- * }
  */
 class EmailEndpoint extends Endpoint
 {
@@ -272,25 +269,21 @@ public function ping(): int
      *
      * @phpstan-param SendBatchMailRequest $messages
      *
-     * @phpstan-return SendBatchMailResponse
-     *
      * @throws \Exception On HTTP or API failure.
      */
-    public function sendBatch(array $messages): array
+    public function sendBatch(array $messages): SendBatchMailResponse
     {
-        return $this->postArray('/v1/send/batch', $messages, []);
+        return $this->hydrateList(SendBatchMailResponse::class, $this->postArray('/v1/send/batch', $messages, []));
     }
 
     /**
      * Send the composed email using the current payload.
      *
      * @phpstan-param SendMailRequest|null $payload
      *
-     * @phpstan-return SendMailResponse
-     *
      * @throws \Exception On HTTP or API failure.
      */
-    public function send(?array $payload = null): array
+    public function send(?array $payload = null): SendMailResponse
     {
         $headers = [];
 
@@ -303,6 +296,6 @@ public function send(?array $payload = null): array
         $this->payload = [];
         $this->idempotencyKey = null;
 
-        return $result;
+        return $this->hydrate(SendMailResponse::class, $result);
     }
 }

src/Endpoints/EmailEndpoint.php

@@ -3,6 +3,7 @@
 namespace Lettermint\Endpoints;
 
 use Lettermint\Client\HttpClient;
+use Lettermint\Resource;
 
 abstract class Endpoint
 {
@@ -102,4 +103,31 @@ private function expectArray(mixed $response): array
 
         return $response;
     }
+
+    /**
+     * @template T of Resource
+     *
+     * @param  class-string<T>  $class
+     * @param  array<array-key, mixed>  $response
+     * @return T
+     */
+    protected function hydrate(string $class, array $response): Resource
+    {
+        /** @var T $resource */
+        $resource = new $class($response);
+
+        return $resource;
+    }
+
+    /**
+     * @template T of Resource
+     *
+     * @param  class-string<T>  $class
+     * @param  array<array-key, mixed>  $response
+     * @return T
+     */
+    protected function hydrateList(string $class, array $response): Resource
+    {
+        return $this->hydrate($class, array_is_list($response) ? ['data' => $response] : $response);
+    }
 }

src/Endpoints/Endpoint.php

@@ -2,28 +2,25 @@
 
 namespace Lettermint\Endpoints;
 
-/**
- * @phpstan-import-type CursorPage from \Lettermint\Types\ApiTypes
- * @phpstan-import-type ApiObject from \Lettermint\Types\ApiTypes
- */
+use Lettermint\Responses\MessageEventsResponse;
+use Lettermint\Responses\MessageListResponse;
+use Lettermint\Responses\MessageResponse;
+
 class MessagesEndpoint extends Endpoint
 {
-    /** @phpstan-return CursorPage|list<ApiObject> */
-    public function list(array $query = []): array
+    public function list(array $query = []): MessageListResponse
     {
-        return $this->getArray($this->path('/messages'), $query);
+        return $this->hydrateList(MessageListResponse::class, $this->getArray($this->path('/messages'), $query));
     }
 
-    /** @phpstan-return ApiObject */
-    public function retrieve(string $messageId): array
+    public function retrieve(string $messageId): MessageResponse
     {
-        return $this->getArray($this->path('/messages/{messageId}', ['messageId' => $messageId]), []);
+        return $this->hydrate(MessageResponse::class, $this->getArray($this->path('/messages/{messageId}', ['messageId' => $messageId]), []));
     }
 
-    /** @phpstan-return ApiObject */
-    public function events(string $messageId, array $query = []): array
+    public function events(string $messageId, array $query = []): MessageEventsResponse
     {
-        return $this->getArray($this->path('/messages/{messageId}/events', ['messageId' => $messageId]), $query);
+        return $this->hydrate(MessageEventsResponse::class, $this->getArray($this->path('/messages/{messageId}/events', ['messageId' => $messageId]), $query));
     }
 
     public function source(string $messageId): string