Add extension rate limit helper

Author: akovari

README.md

@@ -11,6 +11,7 @@
 - 🔁 **Version-aware routing** – register multiple handlers per event (`@sdk.webhook(..., version="v2")`) and propagate version headers on outbound calls.
 - 📦 **Manifest-aware defaults** – automatically loads `extension.yaml`/`manifest.yaml`, applies configuration defaults, and hydrates secrets from `KIKET_SECRET_*` environment variables.
 - 📇 **Custom data client** – call `/api/v1/ext/custom_data/...` with `context.endpoints.custom_data(project_id)` using the configured extension API key.
+- 📉 **Rate-limit helper** – introspect `/api/v1/ext/rate_limit` before enqueueing large jobs or retries.
 - 🧱 **Typed & documented** – designed for Python 3.11+ with Ruff linting, MyPy type hints, and rich docstrings.
 - 📊 **Telemetry & feedback hooks** – capture handler duration/success metrics automatically and forward them to your own feedback callback or a hosted endpoint.
 
@@ -148,3 +149,22 @@ When you are ready to cut a release:
 - **Sample extension:** ship a production-grade marketing automation example demonstrating multi-event handlers, manifest-driven configuration, and deployment templates.
 - **Documentation:** publish quickstart, reference, cookbook, and tutorial content alongside SDK release.
 - **Early access:** package for PyPI, collect telemetry/feedback before general availability (telemetry hooks + publishing checklist now available).
+### Rate-Limit Helper
+
+Need to throttle expensive work? Ask the runtime for the current window and remaining calls:
+
+```python
+@sdk.webhook("automation.dispatch", version="v1")
+async def handle_dispatch(payload, context):
+    limits = await context.endpoints.rate_limit()
+    if limits["remaining"] < 5:
+        await context.endpoints.notify(
+            "Rate limit warning",
+            f"Only {limits['remaining']} calls remain in this window",
+            level="warning",
+        )
+        return {"deferred": True, "reset_in": limits["reset_in"]}
+
+    # Continue with the expensive call
+    return {"ok": True}
+```

kiket_sdk/__init__.py

@@ -3,7 +3,7 @@
 from .client import KiketClient
 from .config import ExtensionConfig
 from .custom_data import ExtensionCustomDataClient
-from .endpoints import ExtensionEndpoints
+from .endpoints import ExtensionEndpoints, RateLimitInfo
 from .notifications import (
     ChannelValidationRequest,
     ChannelValidationResponse,
@@ -25,6 +25,7 @@
     "KiketClient",
     "ExtensionConfig",
     "ExtensionEndpoints",
+    "RateLimitInfo",
     "ExtensionCustomDataClient",
     "ExtensionSlaEventsClient",
     "ExtensionSecretManager",

kiket_sdk/endpoints.py

@@ -1,14 +1,23 @@
 """High-level client for Kiket extension endpoints."""
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, TypedDict
 
 from .client import KiketClient
 from .custom_data import ExtensionCustomDataClient
 from .secrets import ExtensionSecretManager
 from .sla import ExtensionSlaEventsClient
 
 
+class RateLimitInfo(TypedDict):
+    """Shape of the `/api/v1/ext/rate_limit` response."""
+
+    limit: int
+    remaining: int
+    window_seconds: int
+    reset_in: int
+
+
 class ExtensionEndpoints:
     """Typed helpers for calling common Kiket extension endpoints."""
 
@@ -55,6 +64,18 @@ def sla_events(self, project_id: int | str) -> ExtensionSlaEventsClient:
         """Return a helper for querying SLA alerts for a project."""
         return ExtensionSlaEventsClient(self._client, project_id)
 
+    async def rate_limit(self) -> RateLimitInfo:
+        """Fetch the current extension-specific rate limit window."""
+        response = await self._client.get("/api/v1/ext/rate_limit")
+        payload = response.json()
+        data = payload.get("rate_limit") or {}
+        return {
+            "limit": int(data.get("limit", 0) or 0),
+            "remaining": int(data.get("remaining", 0) or 0),
+            "window_seconds": int(data.get("window_seconds", 0) or 0),
+            "reset_in": int(data.get("reset_in", 0) or 0),
+        }
+
     def _version_headers(self) -> dict[str, str]:
         if not self._event_version:
             return {}

tests/test_endpoints.py

@@ -73,3 +73,31 @@ def test_sla_helper_returns_client():
     endpoints = ExtensionEndpoints(client)  # type: ignore[arg-type]
     helper = endpoints.sla_events(project_id="proj-1")
     assert isinstance(helper, ExtensionSlaEventsClient)
+
+
+@pytest.mark.asyncio
+async def test_rate_limit_returns_payload():
+    async def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            status_code=200,
+            json={
+                "rate_limit": {
+                    "limit": 600,
+                    "remaining": 42,
+                    "window_seconds": 60,
+                    "reset_in": 12,
+                }
+            },
+        )
+
+    client = KiketClient(base_url="https://example.invalid", workspace_token="wk_test")
+    client._client = httpx.AsyncClient(transport=MockTransport(handler), base_url=client.base_url)  # type: ignore[attr-defined]
+
+    async with client as http_client:
+        endpoints = ExtensionEndpoints(http_client)
+        info = await endpoints.rate_limit()
+
+    assert info["limit"] == 600
+    assert info["remaining"] == 42
+    assert info["window_seconds"] == 60
+    assert info["reset_in"] == 12

tests/test_telemetry.py

@@ -81,4 +81,4 @@ async def handler(payload, context):  # noqa: ARG001
     assert len(events) == 1
     record = events[0]
     assert record.status == "error"
-    assert record.metadata["message"] == "boom"
+    assert record.metadata["error_message"] == "boom"