webhooks-cc 0.2.0__tar.gz → 0.3.0__tar.gz

{webhooks_cc-0.2.0 → webhooks_cc-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: webhooks-cc
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python SDK for webhooks.cc: capture, wait for, sign and verify webhooks and test emails
 Project-URL: Homepage, https://webhooks.cc
 Project-URL: Documentation, https://github.com/kroqdotdev/webhooks-cc/tree/main/packages/sdk-python#readme
@@ -31,7 +31,7 @@ pip install webhooks-cc
 pip install "webhooks-cc[crypto]"  # also verify Discord (Ed25519) and PayPal (RSA) signatures
 ```
 
-Python 3.10 or later. Get an API key at [webhooks.cc/account/api-keys](https://webhooks.cc/account/api-keys) and set `WHK_API_KEY`, or pass `api_key=`.
+Python 3.10 or later. Get an API key at [webhooks.cc/account/api-keys](https://webhooks.cc/account/api-keys) and set `WHK_API_KEY`, or pass `api_key=`. An AI agent without an account can start in [the agent sandbox](#no-account-the-agent-sandbox).
 
 ## Wait for a webhook
 
@@ -209,6 +209,35 @@ for request in client.requests.subscribe(endpoint.slug, timeout="10m", reconnect
     print(request.method, request.path)
 ```
 
+## No account: the agent sandbox
+
+An AI agent can capture webhooks before anyone signs up. `WebhooksCC.sandbox()` registers through [auth.md](https://webhooks.cc/auth.md), solves a short proof of work (a few seconds of CPU) and returns a sandbox: up to 3 endpoints, 25 captured requests each and 100 in all, for 24 hours. Sandbox endpoints only capture: no mock responses, forwarding or email.
+
+```python
+from webhooks_cc import WebhooksCC
+
+with WebhooksCC.sandbox(client_name="my-agent") as sandbox:
+    endpoint = sandbox.endpoints.create()
+    trigger_checkout(webhook_url=endpoint.url)
+    request = sandbox.requests.wait_for(endpoint.slug, timeout="60s")
+
+    # To keep the endpoints, a human connects the agent to their account.
+    claim = sandbox.claim("dev@example.com")
+    print(f"Open {claim.verification_uri} and enter {claim.user_code}")
+    client = sandbox.wait_for_claim()  # a WebhooksCC for that account
+```
+
+The registration is saved in the agent credential file the MCP server, the other SDKs and the `whk` CLI share: `~/.config/whk/agent.json` on Linux (in `$XDG_CONFIG_HOME` when that is set), `~/Library/Application Support/whk/agent.json` on macOS, `%APPDATA%\whk\agent.json` on Windows, or the path in `WHK_AGENT_FILE`. The next `WebhooksCC.sandbox()` reuses a live sandbox instead of registering again, and `credentials_file=False` leaves the file alone. The claim token is never saved, so only the process that registered moves the sandbox endpoints into the account; a sandbox reused from the file starts a new code for the email instead (`claim.moves_endpoints` is false), and its endpoints stay in the sandbox until they expire.
+
+A connection lasts 90 days, and any process picks it up:
+
+```python
+client = WebhooksCC.connected()  # None when no agent is connected
+client = WebhooksCC()            # without WHK_API_KEY, acts for the connected account
+```
+
+`WebhooksCC.connect(email)` connects an agent without a sandbox: show the human `pending.verification_uri` and `pending.user_code`, then `pending.wait()` returns the client. An API key always wins over the file. A refused sandbox call raises `SandboxError` with the server's `code`; the protocol steps themselves are in `webhooks_cc.agent`.
+
 ## Errors
 
 API errors raise `WebhooksCCError` with a `status_code`, or one of its subclasses: `UnauthorizedError` (401), `NotFoundError` (404), `RateLimitError` (429, with `retry_after`) and `TimeoutError`, which is also Python's built-in `TimeoutError`. Network failures raise httpx's exceptions. Retries are off unless you pass `retry=RetryOptions(max_attempts=3)`. They repeat GET, PUT and DELETE calls after a network error, a timeout or a status in `retry_on` (429, 500, 502, 503 and 504 by default), and any call after a 429; a POST or PATCH that failed any other way may have gone through, so it is not repeated, and neither is `requests.clear()` without `before`.

{webhooks_cc-0.2.0 → webhooks_cc-0.3.0}/README.md

@@ -7,7 +7,7 @@ pip install webhooks-cc
 pip install "webhooks-cc[crypto]"  # also verify Discord (Ed25519) and PayPal (RSA) signatures
 ```
 
-Python 3.10 or later. Get an API key at [webhooks.cc/account/api-keys](https://webhooks.cc/account/api-keys) and set `WHK_API_KEY`, or pass `api_key=`.
+Python 3.10 or later. Get an API key at [webhooks.cc/account/api-keys](https://webhooks.cc/account/api-keys) and set `WHK_API_KEY`, or pass `api_key=`. An AI agent without an account can start in [the agent sandbox](#no-account-the-agent-sandbox).
 
 ## Wait for a webhook
 
@@ -185,6 +185,35 @@ for request in client.requests.subscribe(endpoint.slug, timeout="10m", reconnect
     print(request.method, request.path)
 ```
 
+## No account: the agent sandbox
+
+An AI agent can capture webhooks before anyone signs up. `WebhooksCC.sandbox()` registers through [auth.md](https://webhooks.cc/auth.md), solves a short proof of work (a few seconds of CPU) and returns a sandbox: up to 3 endpoints, 25 captured requests each and 100 in all, for 24 hours. Sandbox endpoints only capture: no mock responses, forwarding or email.
+
+```python
+from webhooks_cc import WebhooksCC
+
+with WebhooksCC.sandbox(client_name="my-agent") as sandbox:
+    endpoint = sandbox.endpoints.create()
+    trigger_checkout(webhook_url=endpoint.url)
+    request = sandbox.requests.wait_for(endpoint.slug, timeout="60s")
+
+    # To keep the endpoints, a human connects the agent to their account.
+    claim = sandbox.claim("dev@example.com")
+    print(f"Open {claim.verification_uri} and enter {claim.user_code}")
+    client = sandbox.wait_for_claim()  # a WebhooksCC for that account
+```
+
+The registration is saved in the agent credential file the MCP server, the other SDKs and the `whk` CLI share: `~/.config/whk/agent.json` on Linux (in `$XDG_CONFIG_HOME` when that is set), `~/Library/Application Support/whk/agent.json` on macOS, `%APPDATA%\whk\agent.json` on Windows, or the path in `WHK_AGENT_FILE`. The next `WebhooksCC.sandbox()` reuses a live sandbox instead of registering again, and `credentials_file=False` leaves the file alone. The claim token is never saved, so only the process that registered moves the sandbox endpoints into the account; a sandbox reused from the file starts a new code for the email instead (`claim.moves_endpoints` is false), and its endpoints stay in the sandbox until they expire.
+
+A connection lasts 90 days, and any process picks it up:
+
+```python
+client = WebhooksCC.connected()  # None when no agent is connected
+client = WebhooksCC()            # without WHK_API_KEY, acts for the connected account
+```
+
+`WebhooksCC.connect(email)` connects an agent without a sandbox: show the human `pending.verification_uri` and `pending.user_code`, then `pending.wait()` returns the client. An API key always wins over the file. A refused sandbox call raises `SandboxError` with the server's `code`; the protocol steps themselves are in `webhooks_cc.agent`.
+
 ## Errors
 
 API errors raise `WebhooksCCError` with a `status_code`, or one of its subclasses: `UnauthorizedError` (401), `NotFoundError` (404), `RateLimitError` (429, with `retry_after`) and `TimeoutError`, which is also Python's built-in `TimeoutError`. Network failures raise httpx's exceptions. Retries are off unless you pass `retry=RetryOptions(max_attempts=3)`. They repeat GET, PUT and DELETE calls after a network error, a timeout or a status in `retry_on` (429, 500, 502, 503 and 504 by default), and any call after a 429; a POST or PATCH that failed any other way may have gone through, so it is not repeated, and neither is `requests.clear()` without `before`.

{webhooks_cc-0.2.0 → webhooks_cc-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webhooks-cc"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK for webhooks.cc: capture, wait for, sign and verify webhooks and test emails"
 readme = "README.md"
 license = "MIT"

{webhooks_cc-0.2.0 → webhooks_cc-0.3.0}/src/webhooks_cc/__init__.py

@@ -13,11 +13,16 @@ your own handlers, and verify provider and forwarding signatures.
             endpoint.slug, timeout="30s", match=match_body_path("type", "invoice.paid")
         )
 
+Without an API key, ``WebhooksCC.sandbox()`` gives an AI agent a sandbox for 24
+hours, and ``WebhooksCC.connect(email)`` connects it to a human's account; see
+:mod:`webhooks_cc.sandbox` and :mod:`webhooks_cc.agent`.
+
 Every signature check for each provider is in :mod:`webhooks_cc.verify`.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
+from .agent import AgentAuthError, ClaimAttempt
 from .client import (
     Destinations,
     Emails,
@@ -27,6 +32,7 @@ from .client import (
     RetryOptions,
     WebhooksCC,
 )
+from .credentials import agent_credentials_path
 from .durations import Duration, parse_duration
 from .email import (
     DEFAULT_EMAIL_DOMAIN,
@@ -87,11 +93,14 @@ from .models import (
     Request,
     RequestPage,
     ResponsePreview,
+    SandboxEndpoint,
+    SandboxLimits,
     SenderTime,
     SendTestEmailResult,
     TeamShare,
     UsageInfo,
 )
+from .sandbox import PendingConnection, SandboxClaim, SandboxClient, SandboxError
 from .templates import (
     TEMPLATE_METADATA,
     TEMPLATE_PROVIDERS,
@@ -115,7 +124,9 @@ __all__ = [
     "TEMPLATE_METADATA",
     "TEMPLATE_PROVIDERS",
     "VERIFY_PROVIDERS",
+    "AgentAuthError",
     "BuiltRequest",
+    "ClaimAttempt",
     "DeliveryCounts",
     "Destination",
     "DestinationFilter",
@@ -139,6 +150,7 @@ __all__ = [
     "Forwarding",
     "Matcher",
     "NotFoundError",
+    "PendingConnection",
     "PreviewRequest",
     "PreviewRule",
     "PreviewedDelivery",
@@ -151,6 +163,11 @@ __all__ = [
     "Requests",
     "ResponsePreview",
     "RetryOptions",
+    "SandboxClaim",
+    "SandboxClient",
+    "SandboxEndpoint",
+    "SandboxError",
+    "SandboxLimits",
     "SendTestEmailResult",
     "SenderTime",
     "TeamShare",
@@ -162,6 +179,7 @@ __all__ = [
     "WebhooksCC",
     "WebhooksCCError",
     "__version__",
+    "agent_credentials_path",
     "build_template_request",
     "capture_during",
     "capture_email_during",

webhooks_cc-0.3.0/src/webhooks_cc/_agent_tokens.py

@@ -0,0 +1,126 @@
+"""Access tokens kept fresh from an agent's identity assertion."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+import httpx
+
+from .agent import AccessToken, AgentAuthError, exchange
+from .credentials import AgentCredentialStore, AgentSlot, SlotName, parse_timestamp
+
+# Exchange again this long before a token expires.
+_REFRESH_MARGIN_S = 60
+
+
+@dataclass(frozen=True)
+class SlotBinding:
+    """The credential-file slot a registration lives in, for writing tokens back."""
+
+    store: AgentCredentialStore
+    base_url: str
+    name: SlotName
+    registration_id: str
+
+    def save_token(self, token: AccessToken | None) -> None:
+        self.store.save_token(
+            self.base_url,
+            self.name,
+            self.registration_id,
+            token.access_token if token else None,
+            token.expires_at if token else None,
+        )
+
+    def remove(self) -> None:
+        self.store.remove(self.base_url, self.name, registration_id=self.registration_id)
+
+
+def cached_token(slot: AgentSlot) -> AccessToken | None:
+    """The slot's cached access token, when it is still usable."""
+    token = slot.usable_token()
+    millis = parse_timestamp(slot.access_token_expires)
+    if token is None or millis is None:
+        return None
+    return AccessToken(
+        access_token=token,
+        scope=slot.scope or "",
+        expires_at=datetime.fromtimestamp(millis / 1000, tz=timezone.utc),
+    )
+
+
+class AgentTokens:
+    """Exchanges the assertion on first use, again shortly before the token expires,
+    and on demand after a 401. With a ``binding``, each new token is cached in the
+    credential file, and ``invalid_grant`` removes the slot before it is raised.
+    ``revoked`` is set once the server refused the assertion that way."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        assertion: str,
+        http: httpx.Client,
+        timeout_ms: float,
+        token: AccessToken | None = None,
+        binding: SlotBinding | None = None,
+    ) -> None:
+        self._base_url = base_url
+        self._assertion = assertion
+        self._http = http
+        self._timeout_ms = timeout_ms
+        self._token = token
+        self._binding = binding
+        self._lock = threading.Lock()
+        self.revoked = False
+
+    def get(self, force_refresh: bool = False) -> str:
+        with self._lock:
+            current = self._token
+            if (
+                not force_refresh
+                and current is not None
+                and current.expires_at.timestamp() - time.time() > _REFRESH_MARGIN_S
+            ):
+                return current.access_token
+            try:
+                token = exchange(
+                    self._assertion,
+                    base_url=self._base_url,
+                    timeout=self._timeout_ms,
+                    http_client=self._http,
+                )
+            except AgentAuthError as error:
+                if error.code == "invalid_grant":
+                    self._token = None
+                    self.revoked = True
+                    self._forget_slot()
+                raise
+            self._token = token
+            if self._binding is not None:
+                self._binding.save_token(token)
+            return token.access_token
+
+    def peek(self) -> str | None:
+        """The current token, without exchanging."""
+        return self._token.access_token if self._token is not None else None
+
+    def drop(self) -> None:
+        """Forget the current token (it was revoked), here and in the file."""
+        with self._lock:
+            self._token = None
+            if self._binding is not None:
+                self._binding.save_token(None)
+
+    def forget_slot(self) -> None:
+        """Remove the slot from the credential file (the registration is over), unless
+        another process has put another registration there since."""
+        with self._lock:
+            self._forget_slot()
+
+    def _forget_slot(self) -> None:
+        if self._binding is not None:
+            self._binding.remove()
+            self._binding = None