MT-23076: support api token expiration in create and reset

README.md

@@ -262,6 +262,7 @@ Contact management:
 
 General API:
 - Templates CRUD – [`templates/all.php`](examples/templates/all.php)
+- API tokens CRUD – [`api-tokens/all.php`](examples/api-tokens/all.php)
 - Billing info – [`general/billing.php`](examples/general/billing.php)
 - Accounts info – [`general/accounts.php`](examples/general/accounts.php)
 - Permissions listing – [`general/permissions.php`](examples/general/permissions.php)

examples/README.md

@@ -54,6 +54,7 @@ Central index of runnable example scripts demonstrating Mailtrap PHP SDK feature
 ### 6. General API
 | Purpose | File |
 |---------|------|
+| API tokens CRUD | [`api-tokens/all.php`](api-tokens/all.php) |
 | Accounts info | [`general/accounts.php`](general/accounts.php) |
 | Billing info | [`general/billing.php`](general/billing.php) |
 | Permissions listing | [`general/permissions.php`](general/permissions.php) |

examples/api-tokens/all.php

@@ -1,6 +1,7 @@
 <?php
 
 use Mailtrap\Config;
+use Mailtrap\DTO\Request\ApiToken\TokenExpiration;
 use Mailtrap\DTO\Request\Permission\CreateOrUpdatePermission;
 use Mailtrap\DTO\Request\Permission\PermissionInterface;
 use Mailtrap\DTO\Request\Permission\Permissions;
@@ -44,6 +45,10 @@
 /**
  * Create a new API token. The full token value is returned only in this response.
  *
+ * Expiration is optional: omit the argument for the server default (a 1-year default is being
+ * rolled out), pass TokenExpiration::at(...) for a specific ISO 8601 date-time, or
+ * TokenExpiration::never() for a token that never expires.
+ *
  * POST https://mailtrap.io/api/accounts/{account_id}/api_tokens
  */
 try {
@@ -55,7 +60,11 @@
         )
     );
 
-    $response = $apiTokens->createApiToken('My new API token', $permissions);
+    $response = $apiTokens->createApiToken(
+        'My new API token',
+        $permissions,
+        TokenExpiration::at(new DateTimeImmutable('+1 year')) // or TokenExpiration::never(), or omit
+    );
 
     var_dump(ResponseHelper::toArray($response));
 } catch (Exception $e) {
@@ -65,12 +74,16 @@
 /**
  * Reset an API token by ID. Returns a new token value; the previous value stops working.
  *
+ * Expiration of the new token is optional: omit the argument for the server default (a 1-year
+ * default is being rolled out), pass TokenExpiration::at(...) for a specific ISO 8601 date-time,
+ * or TokenExpiration::never() for a token that never expires.
+ *
  * POST https://mailtrap.io/api/accounts/{account_id}/api_tokens/{id}/reset
  */
 try {
     $apiTokenId = 1;
 
-    $response = $apiTokens->resetApiToken($apiTokenId);
+    $response = $apiTokens->resetApiToken($apiTokenId, TokenExpiration::never());
 
     var_dump(ResponseHelper::toArray($response));
 } catch (Exception $e) {

src/Api/General/ApiToken.php

@@ -6,6 +6,7 @@
 
 use Mailtrap\Api\AbstractApi;
 use Mailtrap\ConfigInterface;
+use Mailtrap\DTO\Request\ApiToken\TokenExpiration;
 use Mailtrap\DTO\Request\Permission\Permissions;
 use Psr\Http\Message\ResponseInterface;
 
@@ -47,19 +48,29 @@ public function getApiToken(int $apiTokenId): ResponseInterface
     /**
      * Create a new API token. The full token value is returned only in this response.
      *
-     * @param string      $name
-     * @param Permissions $permissions
+     * @param string               $name
+     * @param Permissions          $permissions
+     * @param TokenExpiration|null $expiration Optional token expiration as an ISO 8601 date-time.
+     *                                         Omit for the server default (a 1-year default is being rolled out).
+     *                                         Use TokenExpiration::never() for a token that never expires.
+     *                                         Past or more-than-5-years-ahead values are rejected with 422.
      *
      * @return ResponseInterface
      */
-    public function createApiToken(string $name, Permissions $permissions): ResponseInterface
+    public function createApiToken(string $name, Permissions $permissions, ?TokenExpiration $expiration = null): ResponseInterface
     {
+        $body = [
+            'name' => $name,
+            'resources' => $permissions->toPayload(),
+        ];
+
+        if ($expiration !== null) {
+            $body['expires_at'] = $expiration->getValue();
+        }
+
         return $this->handleResponse($this->httpPost(
             path: $this->getBasePath(),
-            body: [
-                'name' => $name,
-                'resources' => $permissions->toPayload(),
-            ]
+            body: $body
         ));
     }
 
@@ -79,14 +90,28 @@ public function deleteApiToken(int $apiTokenId): ResponseInterface
     /**
      * Reset an API token by ID. Returns a new token value; the previous value stops working.
      *
-     * @param int $apiTokenId
+     * @param int                  $apiTokenId
+     * @param TokenExpiration|null $expiration Optional expiration of the new token as an ISO 8601 date-time.
+     *                                         Omit for the server default (a 1-year default is being rolled out).
+     *                                         Use TokenExpiration::never() for a token that never expires.
+     *                                         Past or more-than-5-years-ahead values are rejected with 422.
+     *
      * @return ResponseInterface
      */
-    public function resetApiToken(int $apiTokenId): ResponseInterface
+    public function resetApiToken(int $apiTokenId, ?TokenExpiration $expiration = null): ResponseInterface
     {
-        return $this->handleResponse(
-            $this->httpPost($this->getBasePath() . '/' . $apiTokenId . '/reset')
-        );
+        $path = $this->getBasePath() . '/' . $apiTokenId . '/reset';
+
+        if ($expiration === null) {
+            return $this->handleResponse(
+                $this->httpPost($path)
+            );
+        }
+
+        return $this->handleResponse($this->httpPost(
+            path: $path,
+            body: ['expires_at' => $expiration->getValue()]
+        ));
     }
 
     public function getAccountId(): int

src/DTO/Request/ApiToken/TokenExpiration.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\ApiToken;
+
+use DateTimeInterface;
+
+/**
+ * Optional token expiration as an ISO 8601 date-time.
+ * Omit the argument for the server default (a 1-year default is being rolled out).
+ * Use TokenExpiration::never() for a token that never expires.
+ * Past or more-than-5-years-ahead values are rejected with 422.
+ *
+ * Class TokenExpiration
+ */
+final class TokenExpiration
+{
+    private function __construct(private ?string $value)
+    {
+    }
+
+    /**
+     * Expire the token at the given ISO 8601 date-time.
+     *
+     * @param DateTimeInterface|string $value
+     *
+     * @return self
+     */
+    public static function at(DateTimeInterface|string $value): self
+    {
+        return new self(
+            $value instanceof DateTimeInterface ? $value->format(DateTimeInterface::ATOM) : $value
+        );
+    }
+
+    /**
+     * Token never expires.
+     *
+     * @return self
+     */
+    public static function never(): self
+    {
+        return new self(null);
+    }
+
+    public function getValue(): ?string
+    {
+        return $this->value;
+    }
+}