poststack 0.5.0__tar.gz → 0.9.0__tar.gz

{poststack-0.5.0 → poststack-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: poststack
-Version: 0.5.0
+Version: 0.9.0
 Summary: Official Python SDK for the PostStack Email API
 Project-URL: Homepage, https://poststack.dev
 Project-URL: Documentation, https://poststack.dev/docs
@@ -105,16 +105,28 @@ client = PostStack(api_key="sk_live_...")
 try:
     client.emails.send({"from": "x@y.com", "to": ["z@w.com"], "subject": "hi"})
 except PostStackError as e:
-    print(e.status_code, e.error, e.request_id)
+    print(e.status_code, e.error, e.code, e.request_id)
+    # e.headers holds the response headers; e.retry_after the Retry-After
+    # delay in seconds, when the API sent one.
 ```
 
+## Retries
+
+Network errors, timeouts, 408, 429 and 5xx responses are retried up to
+`max_retries` times (default 3) with full-jitter exponential backoff. A 429
+that carries `Retry-After` waits exactly that long (up to 60 seconds; a longer
+wait is raised instead). A 429 that is a quota rather than throttling — the
+monthly plan limit or the daily send cap, which carry an error code and no
+`Retry-After` — is raised immediately, since retrying cannot lift it.
+
 ## Configuration
 
 ```python
 client = PostStack(
     api_key="sk_live_...",
     base_url="https://api.poststack.dev",  # default
-    timeout=30.0,                           # default (seconds)
+    timeout=30.0,                           # default (seconds), per attempt
+    max_retries=3,                          # default; 0 disables retrying
 )
 ```
 
@@ -126,19 +138,21 @@ client.emails.send({...}, timeout=60.0)
 
 ## Resources
 
-- `client.emails` — send, get, list, cancel, reschedule, batch, events, insights
-- `client.domains` — create, list, get, verify, update, delete, DMARC
-- `client.contacts` — CRUD, import, export, unsubscribe
-- `client.contact_properties` — custom properties
-- `client.segments` — create, list, get, update, delete, contacts, preview
-- `client.templates` — CRUD, publish, duplicate, presets
-- `client.webhooks` — CRUD, test, deliveries, replay
-- `client.broadcasts` — CRUD, send, test, variants
+- `client.emails` — send, get, list, cancel, reschedule, batch, events, insights, preview, spam_preview
+- `client.domains` — create, list, get, verify, update, delete, DMARC, DKIM rotation, inbox placement
+- `client.contacts` — CRUD, import, export_csv (text; optional `segment_id`), unsubscribe
+- `client.contact_properties` — custom properties, option_usage
+- `client.segments` — create, list, get, update, delete, contacts, preview, members, growth, broadcasts
+- `client.templates` — CRUD, publish, duplicate, render, presets
+- `client.webhooks` — CRUD, test, deliveries, replay, batch_replay, rotate_secret
+- `client.broadcasts` — CRUD, send, test, variants, resend, performance, non_openers, non_clickers, end_ab_test
 - `client.suppressions` — list, add, remove
-- `client.api_keys` — CRUD
-- `client.mailboxes` — CRUD, aliases, password
-- `client.subscription_topics` — topics + contact subscriptions
-- `client.workflows` — CRUD, steps, activate, pause, trigger
+- `client.api_keys` — CRUD, rotate
+- `client.mailboxes` — CRUD, aliases, password, filters, signature, shares, unread_summary
+- `client.inbound_emails` — list, get, attachments, download, draft_reply, reply, forward
+- `client.subscription_topics` — topics (get, update, list_subscribers) + contact subscriptions
+- `client.workflows` — CRUD, graph (get_graph/put_graph/validate_graph), activate, pause, trigger, post_event
+- `client.notification_channels` — Slack/Discord/Telegram alert channels: CRUD, test, deliveries, replay
 - `client.signup_forms` — CRUD, submit
 - `client.email_validations` — validate, validate_batch
 

{poststack-0.5.0 → poststack-0.9.0}/README.md

@@ -74,16 +74,28 @@ client = PostStack(api_key="sk_live_...")
 try:
     client.emails.send({"from": "x@y.com", "to": ["z@w.com"], "subject": "hi"})
 except PostStackError as e:
-    print(e.status_code, e.error, e.request_id)
+    print(e.status_code, e.error, e.code, e.request_id)
+    # e.headers holds the response headers; e.retry_after the Retry-After
+    # delay in seconds, when the API sent one.
 ```
 
+## Retries
+
+Network errors, timeouts, 408, 429 and 5xx responses are retried up to
+`max_retries` times (default 3) with full-jitter exponential backoff. A 429
+that carries `Retry-After` waits exactly that long (up to 60 seconds; a longer
+wait is raised instead). A 429 that is a quota rather than throttling — the
+monthly plan limit or the daily send cap, which carry an error code and no
+`Retry-After` — is raised immediately, since retrying cannot lift it.
+
 ## Configuration
 
 ```python
 client = PostStack(
     api_key="sk_live_...",
     base_url="https://api.poststack.dev",  # default
-    timeout=30.0,                           # default (seconds)
+    timeout=30.0,                           # default (seconds), per attempt
+    max_retries=3,                          # default; 0 disables retrying
 )
 ```
 
@@ -95,19 +107,21 @@ client.emails.send({...}, timeout=60.0)
 
 ## Resources
 
-- `client.emails` — send, get, list, cancel, reschedule, batch, events, insights
-- `client.domains` — create, list, get, verify, update, delete, DMARC
-- `client.contacts` — CRUD, import, export, unsubscribe
-- `client.contact_properties` — custom properties
-- `client.segments` — create, list, get, update, delete, contacts, preview
-- `client.templates` — CRUD, publish, duplicate, presets
-- `client.webhooks` — CRUD, test, deliveries, replay
-- `client.broadcasts` — CRUD, send, test, variants
+- `client.emails` — send, get, list, cancel, reschedule, batch, events, insights, preview, spam_preview
+- `client.domains` — create, list, get, verify, update, delete, DMARC, DKIM rotation, inbox placement
+- `client.contacts` — CRUD, import, export_csv (text; optional `segment_id`), unsubscribe
+- `client.contact_properties` — custom properties, option_usage
+- `client.segments` — create, list, get, update, delete, contacts, preview, members, growth, broadcasts
+- `client.templates` — CRUD, publish, duplicate, render, presets
+- `client.webhooks` — CRUD, test, deliveries, replay, batch_replay, rotate_secret
+- `client.broadcasts` — CRUD, send, test, variants, resend, performance, non_openers, non_clickers, end_ab_test
 - `client.suppressions` — list, add, remove
-- `client.api_keys` — CRUD
-- `client.mailboxes` — CRUD, aliases, password
-- `client.subscription_topics` — topics + contact subscriptions
-- `client.workflows` — CRUD, steps, activate, pause, trigger
+- `client.api_keys` — CRUD, rotate
+- `client.mailboxes` — CRUD, aliases, password, filters, signature, shares, unread_summary
+- `client.inbound_emails` — list, get, attachments, download, draft_reply, reply, forward
+- `client.subscription_topics` — topics (get, update, list_subscribers) + contact subscriptions
+- `client.workflows` — CRUD, graph (get_graph/put_graph/validate_graph), activate, pause, trigger, post_event
+- `client.notification_channels` — Slack/Discord/Telegram alert channels: CRUD, test, deliveries, replay
 - `client.signup_forms` — CRUD, submit
 - `client.email_validations` — validate, validate_batch
 

{poststack-0.5.0 → poststack-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "poststack"
-version = "0.5.0"
+version = "0.9.0"
 description = "Official Python SDK for the PostStack Email API"
 readme = "README.md"
 requires-python = ">=3.10"

{poststack-0.5.0 → poststack-0.9.0}/src/poststack/__init__.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 
 from ._client import (
     DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
     AsyncPostStackClient,
     PostStackClient,
 )
@@ -25,7 +26,9 @@ from .resources import (
     AsyncDomainsResource,
     AsyncEmailsResource,
     AsyncEmailValidationsResource,
+    AsyncInboundEmailsResource,
     AsyncMailboxesResource,
+    AsyncNotificationChannelsResource,
     AsyncSegmentsResource,
     AsyncSignupFormsResource,
     AsyncSubscriptionTopicsResource,
@@ -39,7 +42,9 @@ from .resources import (
     DomainsResource,
     EmailsResource,
     EmailValidationsResource,
+    InboundEmailsResource,
     MailboxesResource,
+    NotificationChannelsResource,
     SegmentsResource,
     SignupFormsResource,
     SubscriptionTopicsResource,
@@ -49,7 +54,7 @@ from .resources import (
     WorkflowsResource,
 )
 
-__version__ = "0.5.0"
+__version__ = "0.9.0"
 
 __all__ = [
     "PostStack",
@@ -79,9 +84,13 @@ class PostStack:
         api_key: str,
         base_url: str = DEFAULT_BASE_URL,
         timeout: float = 30.0,
+        max_retries: int = DEFAULT_MAX_RETRIES,
     ) -> None:
         self._client = PostStackClient(
-            api_key=api_key, base_url=base_url, timeout=timeout
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
         )
         self.emails = EmailsResource(self._client)
         self.domains = DomainsResource(self._client)
@@ -94,10 +103,12 @@ class PostStack:
         self.suppressions = SuppressionsResource(self._client)
         self.api_keys = ApiKeysResource(self._client)
         self.mailboxes = MailboxesResource(self._client)
+        self.inbound_emails = InboundEmailsResource(self._client)
         self.subscription_topics = SubscriptionTopicsResource(self._client)
         self.workflows = WorkflowsResource(self._client)
         self.signup_forms = SignupFormsResource(self._client)
         self.email_validations = EmailValidationsResource(self._client)
+        self.notification_channels = NotificationChannelsResource(self._client)
 
     def close(self) -> None:
         self._client.close()
@@ -123,9 +134,13 @@ class AsyncPostStack:
         api_key: str,
         base_url: str = DEFAULT_BASE_URL,
         timeout: float = 30.0,
+        max_retries: int = DEFAULT_MAX_RETRIES,
     ) -> None:
         self._client = AsyncPostStackClient(
-            api_key=api_key, base_url=base_url, timeout=timeout
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
         )
         self.emails = AsyncEmailsResource(self._client)
         self.domains = AsyncDomainsResource(self._client)
@@ -138,10 +153,14 @@ class AsyncPostStack:
         self.suppressions = AsyncSuppressionsResource(self._client)
         self.api_keys = AsyncApiKeysResource(self._client)
         self.mailboxes = AsyncMailboxesResource(self._client)
+        self.inbound_emails = AsyncInboundEmailsResource(self._client)
         self.subscription_topics = AsyncSubscriptionTopicsResource(self._client)
         self.workflows = AsyncWorkflowsResource(self._client)
         self.signup_forms = AsyncSignupFormsResource(self._client)
         self.email_validations = AsyncEmailValidationsResource(self._client)
+        self.notification_channels = AsyncNotificationChannelsResource(
+            self._client
+        )
 
     async def aclose(self) -> None:
         await self._client.aclose()

{poststack-0.5.0 → poststack-0.9.0}/src/poststack/_client.py

@@ -6,7 +6,10 @@ resources can pick the transport they need. Auth is a simple Bearer token.
 Both clients apply:
   - a per-attempt timeout (default 30s, override per call)
   - exponential-backoff retries on transient failures (network errors, 408,
-    429, 5xx) up to ``max_retries`` (default 3)
+    429, 5xx) up to ``max_retries`` (default 3). A 429 that carries
+    ``Retry-After`` waits that long instead; a 429 that is a quota or cap
+    (monthly plan limit, daily send cap) is raised at once — waiting a few
+    seconds cannot lift it, so retrying only burns the caller's time
   - automatic ``Idempotency-Key`` injection on POSTs so that a retry after a
     network blip does not create a duplicate resource
 """
@@ -14,6 +17,7 @@ Both clients apply:
 from __future__ import annotations
 
 import asyncio
+import email.utils
 import random
 import time
 import uuid
@@ -48,7 +52,84 @@ def _sdk_version() -> str:
 
         return getattr(import_module("poststack"), "__version__", "0.0.0")
 
-RETRYABLE_STATUSES = {408, 429, 500, 502, 503, 504}
+# Explicit non-5xx statuses worth retrying; all 5xx are retried too (see
+# _should_retry_status). Keeps parity with the TS and Go SDKs, which retry the
+# full 5xx range — e.g. a 521/525/599 from an edge proxy.
+RETRYABLE_STATUSES = {408, 429}
+
+
+# The longest Retry-After the client will sleep through. A server asking for
+# more than this is describing a window the caller should hear about, not one
+# to block a thread on silently.
+MAX_RETRY_AFTER = 60.0
+
+# Error codes the API uses for a 429 that is a quota rather than throttling.
+# Not retried: the limit resets on a calendar boundary, not in seconds.
+QUOTA_ERROR_CODES = frozenset(
+    {
+        "quota_exceeded",
+        "monthly_limit_exceeded",
+        "daily_limit_exceeded",
+        "daily_cap_exceeded",
+        "send_limit_exceeded",
+    }
+)
+
+
+def _should_retry_status(status: int) -> bool:
+    return status in RETRYABLE_STATUSES or status >= 500
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    """Seconds from a ``Retry-After`` header (delta-seconds or HTTP-date)."""
+    if not value:
+        return None
+    value = value.strip()
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when is None:
+        return None
+    return max(0.0, when.timestamp() - time.time())
+
+
+def _error_code(response: httpx.Response) -> Optional[str]:
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    code = body.get("code") if isinstance(body, dict) else None
+    return code if isinstance(code, str) else None
+
+
+def _retry_wait(response: httpx.Response, attempt: int) -> Optional[float]:
+    """How long to wait before retrying ``response``, or None to not retry.
+
+    A 429 is the one status whose meaning depends on the body. The API's
+    throttling 429s always carry ``Retry-After`` (its rate limiter sets it),
+    and that delay is honoured. Its quota 429s (plan limit reached, daily send
+    cap) carry an error ``code`` and no ``Retry-After``: those are raised at
+    once. A 429 with neither — a proxy in front of the API, say — gets the
+    ordinary backoff.
+    """
+    status = response.status_code
+    if not _should_retry_status(status):
+        return None
+    retry_after = _parse_retry_after(response.headers.get("retry-after"))
+    if status == 429:
+        code = _error_code(response)
+        if code in QUOTA_ERROR_CODES:
+            return None
+        if retry_after is None and code is not None:
+            return None
+    if retry_after is not None:
+        return retry_after if retry_after <= MAX_RETRY_AFTER else None
+    return _retry_delay(attempt)
 
 
 def _build_headers(api_key: str) -> dict[str, str]:
@@ -89,6 +170,8 @@ def _raise_for_status(response: httpx.Response) -> None:
         error=error_message,
         code=code,
         request_id=request_id,
+        headers=dict(response.headers),
+        retry_after=_parse_retry_after(response.headers.get("retry-after")),
     )
 
 
@@ -158,6 +241,7 @@ class PostStackClient:
         body: Any = None,
         extra_headers: Optional[Mapping[str, str]] = None,
         timeout: Optional[float] = None,
+        raw: bool = False,
     ) -> Any:
         request_timeout = timeout if timeout is not None else self._timeout
 
@@ -179,15 +263,14 @@ class PostStackClient:
                     continue
                 raise
 
-            if (
-                response.status_code in RETRYABLE_STATUSES
-                and attempt < self._max_retries
-            ):
-                time.sleep(_retry_delay(attempt))
-                continue
+            if attempt < self._max_retries:
+                wait = _retry_wait(response, attempt)
+                if wait is not None:
+                    time.sleep(wait)
+                    continue
 
             _raise_for_status(response)
-            return _parse_body(response)
+            return response.content if raw else _parse_body(response)
 
         # If we exit the loop via `continue` on the final attempt, last_exc
         # holds the most recent error.
@@ -203,6 +286,27 @@ class PostStackClient:
     ) -> Any:
         return self._request("GET", path, params=params, timeout=timeout)
 
+    def get_bytes(
+        self,
+        path: str,
+        params: Optional[Mapping[str, Any]] = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> bytes:
+        """GET returning the raw response body (e.g. attachment downloads)."""
+        return self._request("GET", path, params=params, timeout=timeout, raw=True)
+
+    def get_text(
+        self,
+        path: str,
+        params: Optional[Mapping[str, Any]] = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> str:
+        """GET returning the body as text, never JSON-parsed (e.g. CSV)."""
+        raw = self._request("GET", path, params=params, timeout=timeout, raw=True)
+        return raw.decode("utf-8")
+
     def post(
         self,
         path: str,
@@ -227,6 +331,16 @@ class PostStackClient:
     ) -> Any:
         return self._request("PATCH", path, body=body, timeout=timeout)
 
+    def put(
+        self,
+        path: str,
+        body: Any = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        # PUT is idempotent by HTTP semantics, so no Idempotency-Key is needed.
+        return self._request("PUT", path, body=body, timeout=timeout)
+
     def delete(
         self,
         path: str,
@@ -275,6 +389,7 @@ class AsyncPostStackClient:
         body: Any = None,
         extra_headers: Optional[Mapping[str, str]] = None,
         timeout: Optional[float] = None,
+        raw: bool = False,
     ) -> Any:
         request_timeout = timeout if timeout is not None else self._timeout
 
@@ -296,15 +411,14 @@ class AsyncPostStackClient:
                     continue
                 raise
 
-            if (
-                response.status_code in RETRYABLE_STATUSES
-                and attempt < self._max_retries
-            ):
-                await asyncio.sleep(_retry_delay(attempt))
-                continue
+            if attempt < self._max_retries:
+                wait = _retry_wait(response, attempt)
+                if wait is not None:
+                    await asyncio.sleep(wait)
+                    continue
 
             _raise_for_status(response)
-            return _parse_body(response)
+            return response.content if raw else _parse_body(response)
 
         assert last_exc is not None  # noqa: S101
         raise last_exc
@@ -318,6 +432,31 @@ class AsyncPostStackClient:
     ) -> Any:
         return await self._request("GET", path, params=params, timeout=timeout)
 
+    async def get_bytes(
+        self,
+        path: str,
+        params: Optional[Mapping[str, Any]] = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> bytes:
+        """GET returning the raw response body (e.g. attachment downloads)."""
+        return await self._request(
+            "GET", path, params=params, timeout=timeout, raw=True
+        )
+
+    async def get_text(
+        self,
+        path: str,
+        params: Optional[Mapping[str, Any]] = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> str:
+        """GET returning the body as text, never JSON-parsed (e.g. CSV)."""
+        raw = await self._request(
+            "GET", path, params=params, timeout=timeout, raw=True
+        )
+        return raw.decode("utf-8")
+
     async def post(
         self,
         path: str,
@@ -342,6 +481,16 @@ class AsyncPostStackClient:
     ) -> Any:
         return await self._request("PATCH", path, body=body, timeout=timeout)
 
+    async def put(
+        self,
+        path: str,
+        body: Any = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        # PUT is idempotent by HTTP semantics, so no Idempotency-Key is needed.
+        return await self._request("PUT", path, body=body, timeout=timeout)
+
     async def delete(
         self,
         path: str,

{poststack-0.5.0 → poststack-0.9.0}/src/poststack/_errors.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import Mapping, Optional
 
 
 class PostStackError(Exception):
@@ -14,12 +14,19 @@ class PostStackError(Exception):
         error: str,
         code: Optional[str] = None,
         request_id: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        retry_after: Optional[float] = None,
     ) -> None:
         super().__init__(error)
         self.status_code = status_code
         self.error = error
+        #: Stable machine-readable code, e.g. ``rate_limit_exceeded``.
         self.code = code
         self.request_id = request_id
+        #: Response headers (lower-cased names), e.g. ``x-ratelimit-remaining``.
+        self.headers: dict[str, str] = dict(headers) if headers else {}
+        #: Seconds the server asked the caller to wait (``Retry-After``), if any.
+        self.retry_after = retry_after
 
     def __repr__(self) -> str:  # pragma: no cover - cosmetic
         return (

{poststack-0.5.0 → poststack-0.9.0}/src/poststack/resources/__init__.py

@@ -13,7 +13,12 @@ from .email_validations import (
     EmailValidationsResource,
 )
 from .emails import AsyncEmailsResource, EmailsResource
+from .inbound_emails import AsyncInboundEmailsResource, InboundEmailsResource
 from .mailboxes import AsyncMailboxesResource, MailboxesResource
+from .notification_channels import (
+    AsyncNotificationChannelsResource,
+    NotificationChannelsResource,
+)
 from .segments import AsyncSegmentsResource, SegmentsResource
 from .signup_forms import AsyncSignupFormsResource, SignupFormsResource
 from .subscription_topics import (
@@ -40,8 +45,12 @@ __all__ = [
     "AsyncEmailValidationsResource",
     "EmailsResource",
     "AsyncEmailsResource",
+    "InboundEmailsResource",
+    "AsyncInboundEmailsResource",
     "MailboxesResource",
     "AsyncMailboxesResource",
+    "NotificationChannelsResource",
+    "AsyncNotificationChannelsResource",
     "SegmentsResource",
     "AsyncSegmentsResource",
     "SignupFormsResource",

{poststack-0.5.0 → poststack-0.9.0}/src/poststack/resources/api_keys.py

@@ -14,6 +14,11 @@ class ApiKeysResource:
     def create(
         self, input: Dict[str, Any], *, timeout: Optional[float] = None
     ) -> Dict[str, Any]:
+        """Create a key: ``name``, ``permission`` (``full_access`` or
+        ``sending_access``), optional ``mode`` (``live``/``test``) and
+        ``domain_id``. Minting a ``full_access`` key with a ``full_access``
+        API key requires ``allow_full_access: True``. The plaintext ``key`` is
+        returned once."""
         return self._client.post("/api-keys", input, timeout=timeout)
 
     def list(
@@ -22,6 +27,8 @@ class ApiKeysResource:
         *,
         timeout: Optional[float] = None,
     ) -> Dict[str, Any]:
+        """Every API key on the team. The endpoint does not paginate and
+        ignores ``params``; kept only so existing callers do not break."""
         return self._client.get("/api-keys", params, timeout=timeout)
 
     def get(
@@ -34,6 +41,11 @@ class ApiKeysResource:
     ) -> Dict[str, Any]:
         return self._client.delete(f"/api-keys/{id}", timeout=timeout)
 
+    def rotate(
+        self, id: int, *, timeout: Optional[float] = None
+    ) -> Dict[str, Any]:
+        return self._client.post(f"/api-keys/{id}/rotate", timeout=timeout)
+
 
 class AsyncApiKeysResource:
     def __init__(self, client: AsyncPostStackClient) -> None:
@@ -42,6 +54,11 @@ class AsyncApiKeysResource:
     async def create(
         self, input: Dict[str, Any], *, timeout: Optional[float] = None
     ) -> Dict[str, Any]:
+        """Create a key: ``name``, ``permission`` (``full_access`` or
+        ``sending_access``), optional ``mode`` (``live``/``test``) and
+        ``domain_id``. Minting a ``full_access`` key with a ``full_access``
+        API key requires ``allow_full_access: True``. The plaintext ``key`` is
+        returned once."""
         return await self._client.post("/api-keys", input, timeout=timeout)
 
     async def list(
@@ -50,6 +67,8 @@ class AsyncApiKeysResource:
         *,
         timeout: Optional[float] = None,
     ) -> Dict[str, Any]:
+        """Every API key on the team. The endpoint does not paginate and
+        ignores ``params``; kept only so existing callers do not break."""
         return await self._client.get("/api-keys", params, timeout=timeout)
 
     async def get(
@@ -61,3 +80,10 @@ class AsyncApiKeysResource:
         self, id: int, *, timeout: Optional[float] = None
     ) -> Dict[str, Any]:
         return await self._client.delete(f"/api-keys/{id}", timeout=timeout)
+
+    async def rotate(
+        self, id: int, *, timeout: Optional[float] = None
+    ) -> Dict[str, Any]:
+        return await self._client.post(
+            f"/api-keys/{id}/rotate", timeout=timeout
+        )