webhookd-sdk 0.1.0__tar.gz → 0.2.0__tar.gz

{webhookd_sdk-0.1.0 → webhookd_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webhookd-sdk
-Version: 0.1.0
+Version: 0.2.0
 Summary: Official Python SDK for NimbusNexus Webhooks — publish events + verify webhook signatures.
 Project-URL: Homepage, https://github.com/NimbusNexus/Webhooks-sdks/tree/develop/python#readme
 Project-URL: Repository, https://github.com/NimbusNexus/Webhooks-sdks
@@ -28,7 +28,8 @@ Description-Content-Type: text/markdown
 
 # webhookd-sdk (Python)
 
-Official Python SDK for **NimbusNexus Webhooks** — publish events, and verify the webhooks you receive.
+Official Python SDK for **NimbusNexus Webhooks** — publish events, manage your endpoints / keys /
+deliveries, and verify the webhooks you receive.
 
 ```sh
 pip install webhookd-sdk
@@ -74,6 +75,47 @@ with Client("https://webhooks.example.com", api_key="whsk_…") as wh:
 Transient failures (connection errors, `429`, `5xx`) are retried with backoff (a `429` honours
 `Retry-After`); other `4xx` raise `WebhookdAPIError`.
 
+## Manage endpoints, keys & deliveries (operators)
+
+The same `Client` wraps the control-plane API — register receivers, mint keys, and drain the
+dead-letter queue from code (needs an **admin**-scoped key). Management methods return the raw JSON as
+`dict`s (snake_case, exactly as the API sends); list methods return a page —
+`{"items": [...], "next_offset": int | None}`; delete/revoke return `None` (a `204`).
+
+```python
+from webhookd_sdk import Client
+
+wh = Client("https://webhooks.example.com", api_key="whsk_admin_…")
+
+# --- Endpoints ----------------------------------------------------------------
+# Create a receiver — its signing secret is in the response exactly once, so persist it now.
+ep = wh.create_endpoint(
+    "https://your-app.example/webhooks",
+    subscriptions=[{"match_kind": "prefix", "pattern": "order."}],
+    description="orders service",
+)
+endpoint_id, signing_secret = ep["id"], ep["secret"]
+
+wh.list_endpoints(environment="prod")        # {"items": [...], "next_offset": ...}
+wh.get_endpoint(endpoint_id)
+
+# PATCH — send only the keys you want to change (omitted = unchanged, None = cleared):
+wh.update_endpoint(endpoint_id, {"max_attempts": 10, "status": "disabled"})
+
+wh.rotate_endpoint_secret(endpoint_id)       # returns the new secret, once
+wh.enable_endpoint(endpoint_id)              # recover an auto-disabled endpoint
+wh.delete_endpoint(endpoint_id)              # -> None (204)
+
+# --- API keys -----------------------------------------------------------------
+key = wh.create_api_key("ci-publisher", scope="publish", expires_in_days=90)
+print(key["key"])                            # shown once
+wh.revoke_api_key(key["id"])                 # -> None (204)
+
+# --- Deliveries / dead-letter recovery ----------------------------------------
+for d in wh.list_deliveries(status="dead")["items"]:
+    wh.redeliver(d["id"])
+```
+
 ## Develop
 
 ```sh

webhookd_sdk-0.2.0/README.md

@@ -0,0 +1,96 @@
+# webhookd-sdk (Python)
+
+Official Python SDK for **NimbusNexus Webhooks** — publish events, manage your endpoints / keys /
+deliveries, and verify the webhooks you receive.
+
+```sh
+pip install webhookd-sdk
+```
+
+## Verify an incoming webhook (subscribers)
+
+When webhookd delivers a webhook it signs the body with your endpoint's signing secret. **Always
+verify the signature** before trusting the payload — it proves the request really came from webhookd
+and wasn't tampered with or replayed.
+
+```python
+from webhookd_sdk import verify
+
+# In your webhook handler — pass the RAW request body bytes (do not re-serialize the JSON):
+ok = verify(
+    secret=ENDPOINT_SIGNING_SECRET,
+    raw_body=request.body,
+    signature=request.headers["X-Webhook-Signature"],
+    timestamp=request.headers["X-Webhook-Timestamp"],
+)
+if not ok:
+    return Response(status_code=400)  # forged, tampered, or outside the 300s replay window
+```
+
+## Publish an event (producers)
+
+```python
+from webhookd_sdk import Client, WebhookdAPIError
+
+with Client("https://webhooks.example.com", api_key="whsk_…") as wh:
+    try:
+        event = wh.publish(
+            "order.created",
+            {"order_id": "ord_123", "total": 4200},
+            idempotency_key="order-123",   # makes the publish safe to retry
+        )
+        print(event.event_uid, event.deliveries_created)
+    except WebhookdAPIError as e:
+        print(e.status_code, e.code, e.message)   # the stable {error:{code,message}} envelope
+```
+
+Transient failures (connection errors, `429`, `5xx`) are retried with backoff (a `429` honours
+`Retry-After`); other `4xx` raise `WebhookdAPIError`.
+
+## Manage endpoints, keys & deliveries (operators)
+
+The same `Client` wraps the control-plane API — register receivers, mint keys, and drain the
+dead-letter queue from code (needs an **admin**-scoped key). Management methods return the raw JSON as
+`dict`s (snake_case, exactly as the API sends); list methods return a page —
+`{"items": [...], "next_offset": int | None}`; delete/revoke return `None` (a `204`).
+
+```python
+from webhookd_sdk import Client
+
+wh = Client("https://webhooks.example.com", api_key="whsk_admin_…")
+
+# --- Endpoints ----------------------------------------------------------------
+# Create a receiver — its signing secret is in the response exactly once, so persist it now.
+ep = wh.create_endpoint(
+    "https://your-app.example/webhooks",
+    subscriptions=[{"match_kind": "prefix", "pattern": "order."}],
+    description="orders service",
+)
+endpoint_id, signing_secret = ep["id"], ep["secret"]
+
+wh.list_endpoints(environment="prod")        # {"items": [...], "next_offset": ...}
+wh.get_endpoint(endpoint_id)
+
+# PATCH — send only the keys you want to change (omitted = unchanged, None = cleared):
+wh.update_endpoint(endpoint_id, {"max_attempts": 10, "status": "disabled"})
+
+wh.rotate_endpoint_secret(endpoint_id)       # returns the new secret, once
+wh.enable_endpoint(endpoint_id)              # recover an auto-disabled endpoint
+wh.delete_endpoint(endpoint_id)              # -> None (204)
+
+# --- API keys -----------------------------------------------------------------
+key = wh.create_api_key("ci-publisher", scope="publish", expires_in_days=90)
+print(key["key"])                            # shown once
+wh.revoke_api_key(key["id"])                 # -> None (204)
+
+# --- Deliveries / dead-letter recovery ----------------------------------------
+for d in wh.list_deliveries(status="dead")["items"]:
+    wh.redeliver(d["id"])
+```
+
+## Develop
+
+```sh
+pip install -e '.[dev]'
+pytest && ruff check . && mypy webhookd_sdk
+```

{webhookd_sdk-0.1.0 → webhookd_sdk-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webhookd-sdk"
-version = "0.1.0"
+version = "0.2.0"
 description = "Official Python SDK for NimbusNexus Webhooks — publish events + verify webhook signatures."
 readme = "README.md"
 requires-python = ">=3.11"

webhookd_sdk-0.2.0/tests/test_client.py

@@ -0,0 +1,293 @@
+"""Publish client — exercised against an httpx MockTransport (no network)."""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from webhookd_sdk import Client, WebhookdAPIError
+
+_OK = {
+    "id": "evt_db",
+    "event_uid": "u1",
+    "event_type": "order.created",
+    "application": "default",
+    "environment": "prod",
+    "deliveries_created": 2,
+    "source": None,
+}
+
+
+def _client(handler, **kw) -> Client:
+    return Client("https://wh.example.com", "whsk_x", transport=httpx.MockTransport(handler), **kw)
+
+
+def test_publish_success_and_request_shape():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/v1/events"
+        assert request.headers["Authorization"] == "Bearer whsk_x"
+        body = json.loads(request.content)
+        assert body["event_type"] == "order.created"
+        assert body["payload"] == {"id": 1} and body["environment"] == "prod"
+        return httpx.Response(201, json=_OK)
+
+    with _client(handler) as c:
+        ev = c.publish("order.created", {"id": 1})
+    assert ev.event_uid == "u1" and ev.deliveries_created == 2
+
+
+def test_idempotency_key_header():
+    seen: dict[str, str | None] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["idem"] = request.headers.get("Idempotency-Key")
+        return httpx.Response(201, json=_OK)
+
+    with _client(handler) as c:
+        c.publish("order.created", {"id": 1}, idempotency_key="order-123")
+    assert seen["idem"] == "order-123"
+
+
+def test_api_error_carries_envelope():
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(422, json={"error": {"code": "validation_error", "message": "bad"}})
+
+    with _client(handler) as c, pytest.raises(WebhookdAPIError) as ei:
+        c.publish("order.created", {})
+    assert ei.value.status_code == 422 and ei.value.code == "validation_error"
+    assert ei.value.message == "bad"
+
+
+def test_retries_on_503_then_succeeds():
+    calls = {"n": 0}
+
+    def handler(_request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(503, json={"error": {"code": "unavailable", "message": "x"}})
+        return httpx.Response(201, json=_OK)
+
+    with _client(handler, max_retries=2) as c:
+        ev = c.publish("order.created", {})
+    assert calls["n"] == 2 and ev.event_uid == "u1"
+
+
+def test_does_not_retry_4xx():
+    calls = {"n": 0}
+
+    def handler(_request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        return httpx.Response(404, json={"error": {"code": "not_found", "message": "no app"}})
+
+    with _client(handler, max_retries=2) as c, pytest.raises(WebhookdAPIError):
+        c.publish("order.created", {})
+    assert calls["n"] == 1  # a 404 is terminal — not retried
+
+
+# -- management: endpoints ----------------------------------------------------
+
+_ENDPOINT = {
+    "id": "ep_1",
+    "url": "https://sub.example.com/hook",
+    "environment": "prod",
+    "application": "default",
+    "status": "enabled",
+    "secret": "whsec_shown_once",
+    "subscriptions": [{"match_kind": "prefix", "pattern": "order."}],
+}
+
+
+def test_create_endpoint_returns_secret_and_request_shape():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert request.url.path == "/v1/endpoints"
+        assert request.headers["Authorization"] == "Bearer whsk_x"
+        body = json.loads(request.content)
+        # always-sent keys
+        assert body["url"] == "https://sub.example.com/hook"
+        assert body["environment"] == "prod"
+        assert body["application"] == "default"
+        assert body["subscriptions"] == [{"match_kind": "prefix", "pattern": "order."}]
+        assert body["max_attempts"] == 5
+        # unset optional kwargs are dropped
+        assert "secret" not in body
+        assert "retry_schedule" not in body
+        assert "description" not in body
+        assert "custom_headers" not in body
+        assert "delivery_timeout_ms" not in body
+        return httpx.Response(201, json=_ENDPOINT)
+
+    with _client(handler) as c:
+        ep = c.create_endpoint(
+            "https://sub.example.com/hook",
+            subscriptions=[{"match_kind": "prefix", "pattern": "order."}],
+            max_attempts=5,
+        )
+    # returned as-is (snake_case), secret present exactly as the server sent it
+    assert ep["id"] == "ep_1" and ep["secret"] == "whsec_shown_once"
+
+
+def test_create_endpoint_defaults_subscriptions_to_empty_list():
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content)
+        assert body["subscriptions"] == []
+        return httpx.Response(201, json=_ENDPOINT)
+
+    with _client(handler) as c:
+        c.create_endpoint("https://sub.example.com/hook")
+
+
+def test_list_endpoints_passes_environment_and_returns_page():
+    page = {"items": [_ENDPOINT], "next_offset": 50}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert request.url.path == "/v1/endpoints"
+        assert request.url.params["environment"] == "staging"
+        assert request.url.params["offset"] == "0"
+        assert request.url.params["limit"] == "50"
+        return httpx.Response(200, json=page)
+
+    with _client(handler) as c:
+        result = c.list_endpoints(environment="staging", limit=50)
+    assert result["items"][0]["id"] == "ep_1"
+    assert result["next_offset"] == 50
+
+
+def test_get_endpoint_hits_path():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert request.url.path == "/v1/endpoints/ep_1"
+        return httpx.Response(200, json=_ENDPOINT)
+
+    with _client(handler) as c:
+        ep = c.get_endpoint("ep_1")
+    assert ep["id"] == "ep_1"
+
+
+def test_update_endpoint_sends_only_provided_keys():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "PATCH"
+        assert request.url.path == "/v1/endpoints/ep_1"
+        body = json.loads(request.content)
+        # explicit None clears; provided key present; omitted key absent
+        assert body == {"description": None, "max_attempts": 10}
+        assert "url" not in body  # omitted -> must not appear in the request body
+        return httpx.Response(200, json=_ENDPOINT)
+
+    with _client(handler) as c:
+        c.update_endpoint("ep_1", {"description": None, "max_attempts": 10})
+
+
+def test_delete_endpoint_handles_204():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "DELETE"
+        assert request.url.path == "/v1/endpoints/ep_1"
+        return httpx.Response(204)  # no body
+
+    with _client(handler) as c:
+        assert c.delete_endpoint("ep_1") is None
+
+
+def test_rotate_secret_hits_path_and_returns_new_secret():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert request.url.path == "/v1/endpoints/ep_1/rotate-secret"
+        assert not request.content  # no request body
+        return httpx.Response(200, json={**_ENDPOINT, "secret": "whsec_new"})
+
+    with _client(handler) as c:
+        ep = c.rotate_endpoint_secret("ep_1")
+    assert ep["secret"] == "whsec_new"
+
+
+def test_enable_endpoint_hits_path():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert request.url.path == "/v1/endpoints/ep_1/enable"
+        assert not request.content  # no request body
+        return httpx.Response(200, json=_ENDPOINT)
+
+    with _client(handler) as c:
+        ep = c.enable_endpoint("ep_1")
+    assert ep["status"] == "enabled"
+
+
+# -- management: api keys -----------------------------------------------------
+
+
+def test_create_api_key_returns_key_and_sends_scope_and_expiry():
+    out = {"id": "key_1", "name": "ci", "scope": "publish", "key": "whsk_secret_once"}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert request.url.path == "/v1/api-keys"
+        body = json.loads(request.content)
+        assert body == {"name": "ci", "scope": "publish", "expires_in_days": 30}
+        return httpx.Response(201, json=out)
+
+    with _client(handler) as c:
+        key = c.create_api_key("ci", "publish", expires_in_days=30)
+    assert key["key"] == "whsk_secret_once" and key["scope"] == "publish"
+
+
+def test_create_api_key_omits_expiry_when_absent():
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content)
+        assert body == {"name": "", "scope": "admin"}
+        assert "expires_in_days" not in body
+        return httpx.Response(201, json={"id": "key_2", "key": "whsk_x", "scope": "admin"})
+
+    with _client(handler) as c:
+        c.create_api_key()
+
+
+def test_revoke_api_key_handles_204():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "DELETE"
+        assert request.url.path == "/v1/api-keys/key_1"
+        return httpx.Response(204)
+
+    with _client(handler) as c:
+        assert c.revoke_api_key("key_1") is None
+
+
+# -- management: deliveries ---------------------------------------------------
+
+
+def test_list_deliveries_forwards_only_provided_params():
+    page = {"items": [{"id": "dlv_1", "status": "failed"}], "next_offset": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert request.url.path == "/v1/deliveries"
+        params = request.url.params
+        assert params["status"] == "failed"
+        assert params["endpoint_id"] == "ep_1"
+        assert params["offset"] == "0"
+        # unprovided filters must not be forwarded
+        assert "event_type" not in params
+        assert "since" not in params
+        assert "until" not in params
+        assert "q" not in params
+        assert "limit" not in params
+        return httpx.Response(200, json=page)
+
+    with _client(handler) as c:
+        result = c.list_deliveries(status="failed", endpoint_id="ep_1")
+    assert result["items"][0]["id"] == "dlv_1"
+    assert result["next_offset"] is None
+
+
+def test_redeliver_hits_path():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "POST"
+        assert request.url.path == "/v1/deliveries/dlv_1/redeliver"
+        assert not request.content  # no request body
+        return httpx.Response(200, json={"id": "dlv_1", "status": "queued"})
+
+    with _client(handler) as c:
+        dlv = c.redeliver("dlv_1")
+    assert dlv["status"] == "queued"

{webhookd_sdk-0.1.0 → webhookd_sdk-0.2.0}/tests/test_signature.py

@@ -58,6 +58,12 @@ def test_accepts_str_timestamp_header():
     assert verify(SECRET, BODY, sig, timestamp=str(TS), now=TS)
 
 
+def test_rejects_non_numeric_timestamp():
+    # A malformed X-Webhook-Timestamp header must be rejected cleanly, not raise (TS parity).
+    sig = sign(SECRET, BODY, TS)
+    assert not verify(SECRET, BODY, sig, timestamp="not-a-number", now=TS)
+
+
 def test_str_body_accepted():
     sig = sign(SECRET, BODY.decode(), TS)
     assert verify(SECRET, BODY.decode(), sig, timestamp=TS, now=TS)
@@ -70,3 +76,13 @@ def test_matches_delivery_core_server_signer():
     assert verify(SECRET, BODY, server_sig, timestamp=TS, now=TS)
     # ... and our sign matches theirs exactly.
     assert sign(SECRET, BODY, TS) == server_sig
+
+
+def test_dual_signature_accepts_any_matching_token():
+    # SEC-5(C): during a signing-secret rotation webhookd may send TWO comma-separated tokens
+    # (current + previous); a subscriber configured with EITHER secret must verify.
+    other = "whsec_previous_secret"
+    header = sign(SECRET, BODY, TS) + "," + sign(other, BODY, TS)
+    assert verify(SECRET, BODY, header, timestamp=TS, now=TS)  # matches the first token
+    assert verify(other, BODY, header, timestamp=TS, now=TS)  # matches the second token
+    assert not verify("whsec_neither", BODY, header, timestamp=TS, now=TS)  # matches neither

{webhookd_sdk-0.1.0 → webhookd_sdk-0.2.0}/webhookd_sdk/__init__.py

@@ -10,7 +10,8 @@ from webhookd_sdk.client import Client, Event
 from webhookd_sdk.errors import WebhookdAPIError, WebhookdError
 from webhookd_sdk.signature import DEFAULT_TOLERANCE_SECONDS, sign, verify
 
-__version__ = "0.1.0"
+# Keep in lockstep with pyproject.toml + the release tag (see publish.yml's bump checklist).
+__version__ = "0.2.0"
 
 __all__ = [
     "Client",

webhookd_sdk-0.2.0/webhookd_sdk/client.py

@@ -0,0 +1,301 @@
+"""Typed publish client for the webhookd API."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from webhookd_sdk.errors import WebhookdAPIError, WebhookdError
+
+_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+@dataclass
+class Event:
+    """The published event, as returned by ``POST /v1/events`` (webhookd's ``EventOut``)."""
+
+    id: str
+    event_uid: str
+    event_type: str
+    application: str
+    environment: str
+    deliveries_created: int
+    source: str | None = None
+
+    @classmethod
+    def _from_json(cls, d: dict[str, Any]) -> Event:
+        return cls(
+            id=d["id"],
+            event_uid=d["event_uid"],
+            event_type=d["event_type"],
+            application=d.get("application", "default"),
+            environment=d.get("environment", "prod"),
+            deliveries_created=d.get("deliveries_created", 0),
+            source=d.get("source"),
+        )
+
+
+class Client:
+    """Publish events to webhookd.
+
+    Authenticate with a per-tenant API key (``whsk_…``) or a service token::
+
+        with Client("https://webhooks.example.com", api_key="whsk_…") as wh:
+            event = wh.publish("order.created", {"id": 123}, idempotency_key="order-123")
+
+    Transient failures (connection errors, 429, 5xx) are retried with exponential backoff; a 429
+    honours its ``Retry-After`` header. Other 4xx raise :class:`WebhookdAPIError` carrying the
+    server's ``{error: {code, message}}`` envelope.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        timeout: float = 10.0,
+        max_retries: int = 2,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        self._base = base_url.rstrip("/")
+        self._key = api_key
+        self._max_retries = max_retries
+        self._client = httpx.Client(timeout=timeout, transport=transport)
+
+    def publish(
+        self,
+        event_type: str,
+        payload: dict[str, Any],
+        *,
+        environment: str = "prod",
+        application: str = "default",
+        source: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> Event:
+        """Publish one event. ``idempotency_key`` makes the publish safe to retry (a replay returns
+        the original event without re-fanning-out)."""
+        body: dict[str, Any] = {
+            "event_type": event_type,
+            "payload": payload,
+            "environment": environment,
+            "application": application,
+        }
+        if source is not None:
+            body["source"] = source
+        extra_headers = None
+        if idempotency_key is not None:
+            extra_headers = {"Idempotency-Key": idempotency_key}
+        resp = self._request("POST", "/v1/events", json=body, extra_headers=extra_headers)
+        return Event._from_json(resp.json())
+
+    # -- endpoints -------------------------------------------------------------
+    def create_endpoint(
+        self,
+        url: str,
+        *,
+        subscriptions: list[dict[str, Any]] | None = None,
+        environment: str = "prod",
+        application: str = "default",
+        secret: str | None = None,
+        max_attempts: int | None = None,
+        retry_schedule: list[int] | None = None,
+        description: str | None = None,
+        custom_headers: dict[str, str] | None = None,
+        delivery_timeout_ms: int | None = None,
+    ) -> dict[str, Any]:
+        """Create an endpoint (``POST /v1/endpoints``). The returned ``EndpointOut`` includes the
+        signing ``secret`` exactly ONCE — persist it now, it is never shown again.
+
+        ``subscriptions`` is a list of ``{"match_kind", "pattern"}`` (``match_kind`` in
+        ``exact|prefix|suffix|all``); it defaults to ``[]``. Only ``url``/``environment``/
+        ``application``/``subscriptions`` are always sent — any other ``None`` kwarg is omitted
+        so the server applies its own default.
+        """
+        body: dict[str, Any] = {
+            "url": url,
+            "environment": environment,
+            "application": application,
+            "subscriptions": subscriptions if subscriptions is not None else [],
+        }
+        optional: dict[str, Any] = {
+            "secret": secret,
+            "max_attempts": max_attempts,
+            "retry_schedule": retry_schedule,
+            "description": description,
+            "custom_headers": custom_headers,
+            "delivery_timeout_ms": delivery_timeout_ms,
+        }
+        for key, value in optional.items():
+            if value is not None:
+                body[key] = value
+        return self._request("POST", "/v1/endpoints", json=body).json()
+
+    def list_endpoints(
+        self, *, environment: str = "prod", offset: int = 0, limit: int | None = None
+    ) -> dict[str, Any]:
+        """List endpoints (``GET /v1/endpoints``). Returns a ``Page``:
+        ``{"items": [EndpointOut], "next_offset": int | None}``."""
+        params: dict[str, Any] = {"environment": environment, "offset": offset}
+        if limit is not None:
+            params["limit"] = limit
+        return self._request("GET", "/v1/endpoints", params=params).json()
+
+    def get_endpoint(self, endpoint_id: str) -> dict[str, Any]:
+        """Fetch one endpoint (``GET /v1/endpoints/{id}``) -> ``EndpointOut``."""
+        return self._request("GET", f"/v1/endpoints/{endpoint_id}").json()
+
+    def update_endpoint(self, endpoint_id: str, patch: dict[str, Any]) -> dict[str, Any]:
+        """Patch an endpoint (``PATCH /v1/endpoints/{id}``) -> ``EndpointOut``.
+
+        The ``patch`` mapping is sent AS-IS with snake_case keys (``url``, ``max_attempts``,
+        ``retry_schedule``, ``status``, ``description``, ``custom_headers``,
+        ``delivery_timeout_ms``). PATCH semantics: an omitted key is left unchanged, an explicit
+        ``None`` clears it. No defaults are injected — send only the keys you want to change.
+        """
+        return self._request("PATCH", f"/v1/endpoints/{endpoint_id}", json=patch).json()
+
+    def delete_endpoint(self, endpoint_id: str) -> None:
+        """Delete an endpoint (``DELETE /v1/endpoints/{id}``, 204). Returns ``None``."""
+        self._request("DELETE", f"/v1/endpoints/{endpoint_id}")
+
+    def rotate_endpoint_secret(self, endpoint_id: str) -> dict[str, Any]:
+        """Rotate an endpoint's signing secret (``POST /v1/endpoints/{id}/rotate-secret``).
+
+        Returns the ``EndpointOut`` with the NEW ``secret`` shown once.
+        """
+        return self._request("POST", f"/v1/endpoints/{endpoint_id}/rotate-secret").json()
+
+    def enable_endpoint(self, endpoint_id: str) -> dict[str, Any]:
+        """Re-enable an auto-disabled endpoint (``POST /v1/endpoints/{id}/enable``).
+
+        Returns ``EndpointOut``.
+        """
+        return self._request("POST", f"/v1/endpoints/{endpoint_id}/enable").json()
+
+    # -- api keys --------------------------------------------------------------
+    def create_api_key(
+        self, name: str = "", scope: str = "admin", *, expires_in_days: int | None = None
+    ) -> dict[str, Any]:
+        """Create an API key (``POST /v1/api-keys``). The returned ``ApiKeyOut`` includes the
+        plaintext ``key`` exactly ONCE. ``scope`` is ``"admin"`` or ``"publish"``."""
+        body: dict[str, Any] = {"name": name, "scope": scope}
+        if expires_in_days is not None:
+            body["expires_in_days"] = expires_in_days
+        return self._request("POST", "/v1/api-keys", json=body).json()
+
+    def revoke_api_key(self, key_id: str) -> None:
+        """Revoke an API key (``DELETE /v1/api-keys/{id}``, 204). Returns ``None``."""
+        self._request("DELETE", f"/v1/api-keys/{key_id}")
+
+    # -- deliveries ------------------------------------------------------------
+    def list_deliveries(
+        self,
+        *,
+        status: str | None = None,
+        endpoint_id: str | None = None,
+        event_type: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        q: str | None = None,
+        offset: int = 0,
+        limit: int | None = None,
+    ) -> dict[str, Any]:
+        """List deliveries (``GET /v1/deliveries``). Returns a ``Page``:
+        ``{"items": [DeliveryOut], "next_offset": int | None}``.
+
+        Every filter is optional and only forwarded when provided. ``status`` is one of
+        ``queued|sending|sent|failed|dead``.
+        """
+        params: dict[str, Any] = {"offset": offset}
+        optional: dict[str, Any] = {
+            "status": status,
+            "endpoint_id": endpoint_id,
+            "event_type": event_type,
+            "since": since,
+            "until": until,
+            "q": q,
+            "limit": limit,
+        }
+        for key, value in optional.items():
+            if value is not None:
+                params[key] = value
+        return self._request("GET", "/v1/deliveries", params=params).json()
+
+    def redeliver(self, delivery_id: str) -> dict[str, Any]:
+        """Re-enqueue a delivery (``POST /v1/deliveries/{id}/redeliver``) -> ``DeliveryOut``."""
+        return self._request("POST", f"/v1/deliveries/{delivery_id}/redeliver").json()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    # -- internals -------------------------------------------------------------
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Issue one authenticated request with the shared retry policy.
+
+        Retries connection errors, 429 (honouring ``Retry-After``) and 5xx with capped
+        exponential backoff; any other 4xx/5xx raises :class:`WebhookdAPIError`. ``json`` is
+        omitted for bodyless verbs (GET/DELETE, or POSTs with no body). The raw
+        :class:`httpx.Response` is returned — the caller decides whether to parse it (a 204 must
+        not be parsed).
+        """
+        url = f"{self._base}{path}"
+        headers = {"Authorization": f"Bearer {self._key}"}
+        if extra_headers:
+            headers.update(extra_headers)
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = self._client.request(method, url, json=json, params=params, headers=headers)
+            except httpx.HTTPError as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise WebhookdError(f"request failed: {exc}") from exc
+
+            if resp.status_code in _RETRY_STATUSES and attempt < self._max_retries:
+                time.sleep(_retry_after(resp) or _backoff(attempt))
+                continue
+            if resp.status_code >= 400:
+                raise _api_error(resp)
+            return resp
+        raise WebhookdError(f"request failed after retries: {last_exc}")
+
+
+def _backoff(attempt: int) -> float:
+    return min(2.0, 0.2 * (2**attempt))
+
+
+def _retry_after(resp: httpx.Response) -> float | None:
+    raw = resp.headers.get("Retry-After")
+    if raw and raw.isdigit():
+        return float(raw)
+    return None
+
+
+def _api_error(resp: httpx.Response) -> WebhookdAPIError:
+    code, message = "error", resp.text
+    try:
+        err = resp.json().get("error") or {}
+        code = err.get("code", code)
+        message = err.get("message", message)
+    except Exception:  # noqa: BLE001 - a non-JSON error body falls back to the raw text
+        pass
+    return WebhookdAPIError(resp.status_code, code, message)

{webhookd_sdk-0.1.0 → webhookd_sdk-0.2.0}/webhookd_sdk/signature.py

@@ -71,11 +71,24 @@ def verify(
     :param tolerance_seconds: replay window; webhookd's default is 300s.
     :param now: override the current unix time (for tests).
     """
-    ts = int(timestamp) if timestamp is not None else None
+    if timestamp is None:
+        ts = None
+    else:
+        try:
+            ts = int(timestamp)
+        except (ValueError, TypeError):
+            return False  # a malformed X-Webhook-Timestamp can't be valid — reject, don't raise
     if ts is not None:
         current = int(time.time()) if now is None else now
         if abs(current - ts) > tolerance_seconds:
             return False
     expected = sign(secret, raw_body, ts)
-    candidate = signature if signature.startswith(_PREFIX) else f"{_PREFIX}{signature}"
-    return hmac.compare_digest(expected, candidate)
+    # X-Webhook-Signature carries one token normally, or several comma-separated tokens during a
+    # signing-secret rotation (webhookd dual-sign overlap) — accept if ANY token verifies, so a
+    # subscriber configured with EITHER the current or the previous secret keeps working.
+    for token in signature.split(","):
+        token = token.strip()
+        candidate = token if token.startswith(_PREFIX) else f"{_PREFIX}{token}"
+        if hmac.compare_digest(expected, candidate):
+            return True
+    return False

webhookd_sdk-0.1.0/README.md

@@ -1,54 +0,0 @@
-# webhookd-sdk (Python)
-
-Official Python SDK for **NimbusNexus Webhooks** — publish events, and verify the webhooks you receive.
-
-```sh
-pip install webhookd-sdk
-```
-
-## Verify an incoming webhook (subscribers)
-
-When webhookd delivers a webhook it signs the body with your endpoint's signing secret. **Always
-verify the signature** before trusting the payload — it proves the request really came from webhookd
-and wasn't tampered with or replayed.
-
-```python
-from webhookd_sdk import verify
-
-# In your webhook handler — pass the RAW request body bytes (do not re-serialize the JSON):
-ok = verify(
-    secret=ENDPOINT_SIGNING_SECRET,
-    raw_body=request.body,
-    signature=request.headers["X-Webhook-Signature"],
-    timestamp=request.headers["X-Webhook-Timestamp"],
-)
-if not ok:
-    return Response(status_code=400)  # forged, tampered, or outside the 300s replay window
-```
-
-## Publish an event (producers)
-
-```python
-from webhookd_sdk import Client, WebhookdAPIError
-
-with Client("https://webhooks.example.com", api_key="whsk_…") as wh:
-    try:
-        event = wh.publish(
-            "order.created",
-            {"order_id": "ord_123", "total": 4200},
-            idempotency_key="order-123",   # makes the publish safe to retry
-        )
-        print(event.event_uid, event.deliveries_created)
-    except WebhookdAPIError as e:
-        print(e.status_code, e.code, e.message)   # the stable {error:{code,message}} envelope
-```
-
-Transient failures (connection errors, `429`, `5xx`) are retried with backoff (a `429` honours
-`Retry-After`); other `4xx` raise `WebhookdAPIError`.
-
-## Develop
-
-```sh
-pip install -e '.[dev]'
-pytest && ruff check . && mypy webhookd_sdk
-```

webhookd_sdk-0.1.0/tests/test_client.py

@@ -1,86 +0,0 @@
-"""Publish client — exercised against an httpx MockTransport (no network)."""
-
-from __future__ import annotations
-
-import json
-
-import httpx
-import pytest
-
-from webhookd_sdk import Client, WebhookdAPIError
-
-_OK = {
-    "id": "evt_db",
-    "event_uid": "u1",
-    "event_type": "order.created",
-    "application": "default",
-    "environment": "prod",
-    "deliveries_created": 2,
-    "source": None,
-}
-
-
-def _client(handler, **kw) -> Client:
-    return Client("https://wh.example.com", "whsk_x", transport=httpx.MockTransport(handler), **kw)
-
-
-def test_publish_success_and_request_shape():
-    def handler(request: httpx.Request) -> httpx.Response:
-        assert request.url.path == "/v1/events"
-        assert request.headers["Authorization"] == "Bearer whsk_x"
-        body = json.loads(request.content)
-        assert body["event_type"] == "order.created"
-        assert body["payload"] == {"id": 1} and body["environment"] == "prod"
-        return httpx.Response(201, json=_OK)
-
-    with _client(handler) as c:
-        ev = c.publish("order.created", {"id": 1})
-    assert ev.event_uid == "u1" and ev.deliveries_created == 2
-
-
-def test_idempotency_key_header():
-    seen: dict[str, str | None] = {}
-
-    def handler(request: httpx.Request) -> httpx.Response:
-        seen["idem"] = request.headers.get("Idempotency-Key")
-        return httpx.Response(201, json=_OK)
-
-    with _client(handler) as c:
-        c.publish("order.created", {"id": 1}, idempotency_key="order-123")
-    assert seen["idem"] == "order-123"
-
-
-def test_api_error_carries_envelope():
-    def handler(_request: httpx.Request) -> httpx.Response:
-        return httpx.Response(422, json={"error": {"code": "validation_error", "message": "bad"}})
-
-    with _client(handler) as c, pytest.raises(WebhookdAPIError) as ei:
-        c.publish("order.created", {})
-    assert ei.value.status_code == 422 and ei.value.code == "validation_error"
-    assert ei.value.message == "bad"
-
-
-def test_retries_on_503_then_succeeds():
-    calls = {"n": 0}
-
-    def handler(_request: httpx.Request) -> httpx.Response:
-        calls["n"] += 1
-        if calls["n"] == 1:
-            return httpx.Response(503, json={"error": {"code": "unavailable", "message": "x"}})
-        return httpx.Response(201, json=_OK)
-
-    with _client(handler, max_retries=2) as c:
-        ev = c.publish("order.created", {})
-    assert calls["n"] == 2 and ev.event_uid == "u1"
-
-
-def test_does_not_retry_4xx():
-    calls = {"n": 0}
-
-    def handler(_request: httpx.Request) -> httpx.Response:
-        calls["n"] += 1
-        return httpx.Response(404, json={"error": {"code": "not_found", "message": "no app"}})
-
-    with _client(handler, max_retries=2) as c, pytest.raises(WebhookdAPIError):
-        c.publish("order.created", {})
-    assert calls["n"] == 1  # a 404 is terminal — not retried

webhookd_sdk-0.1.0/webhookd_sdk/client.py

@@ -1,147 +0,0 @@
-"""Typed publish client for the webhookd API."""
-
-from __future__ import annotations
-
-import time
-from dataclasses import dataclass
-from typing import Any
-
-import httpx
-
-from webhookd_sdk.errors import WebhookdAPIError, WebhookdError
-
-_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
-
-
-@dataclass
-class Event:
-    """The published event, as returned by ``POST /v1/events`` (webhookd's ``EventOut``)."""
-
-    id: str
-    event_uid: str
-    event_type: str
-    application: str
-    environment: str
-    deliveries_created: int
-    source: str | None = None
-
-    @classmethod
-    def _from_json(cls, d: dict[str, Any]) -> Event:
-        return cls(
-            id=d["id"],
-            event_uid=d["event_uid"],
-            event_type=d["event_type"],
-            application=d.get("application", "default"),
-            environment=d.get("environment", "prod"),
-            deliveries_created=d.get("deliveries_created", 0),
-            source=d.get("source"),
-        )
-
-
-class Client:
-    """Publish events to webhookd.
-
-    Authenticate with a per-tenant API key (``whsk_…``) or a service token::
-
-        with Client("https://webhooks.example.com", api_key="whsk_…") as wh:
-            event = wh.publish("order.created", {"id": 123}, idempotency_key="order-123")
-
-    Transient failures (connection errors, 429, 5xx) are retried with exponential backoff; a 429
-    honours its ``Retry-After`` header. Other 4xx raise :class:`WebhookdAPIError` carrying the
-    server's ``{error: {code, message}}`` envelope.
-    """
-
-    def __init__(
-        self,
-        base_url: str,
-        api_key: str,
-        *,
-        timeout: float = 10.0,
-        max_retries: int = 2,
-        transport: httpx.BaseTransport | None = None,
-    ):
-        self._base = base_url.rstrip("/")
-        self._key = api_key
-        self._max_retries = max_retries
-        self._client = httpx.Client(timeout=timeout, transport=transport)
-
-    def publish(
-        self,
-        event_type: str,
-        payload: dict[str, Any],
-        *,
-        environment: str = "prod",
-        application: str = "default",
-        source: str | None = None,
-        idempotency_key: str | None = None,
-    ) -> Event:
-        """Publish one event. ``idempotency_key`` makes the publish safe to retry (a replay returns
-        the original event without re-fanning-out)."""
-        body: dict[str, Any] = {
-            "event_type": event_type,
-            "payload": payload,
-            "environment": environment,
-            "application": application,
-        }
-        if source is not None:
-            body["source"] = source
-        headers = {"Authorization": f"Bearer {self._key}"}
-        if idempotency_key is not None:
-            headers["Idempotency-Key"] = idempotency_key
-        resp = self._post("/v1/events", body, headers)
-        return Event._from_json(resp.json())
-
-    def close(self) -> None:
-        self._client.close()
-
-    def __enter__(self) -> Client:
-        return self
-
-    def __exit__(self, *_exc: object) -> None:
-        self.close()
-
-    # -- internals -------------------------------------------------------------
-    def _post(
-        self, path: str, json_body: dict[str, Any], headers: dict[str, str]
-    ) -> httpx.Response:
-        url = f"{self._base}{path}"
-        last_exc: Exception | None = None
-        for attempt in range(self._max_retries + 1):
-            try:
-                resp = self._client.post(url, json=json_body, headers=headers)
-            except httpx.HTTPError as exc:
-                last_exc = exc
-                if attempt < self._max_retries:
-                    time.sleep(_backoff(attempt))
-                    continue
-                raise WebhookdError(f"request failed: {exc}") from exc
-
-            if resp.status_code in _RETRY_STATUSES and attempt < self._max_retries:
-                time.sleep(_retry_after(resp) or _backoff(attempt))
-                continue
-            if resp.status_code >= 400:
-                raise _api_error(resp)
-            return resp
-        raise WebhookdError(f"request failed after retries: {last_exc}")
-
-
-def _backoff(attempt: int) -> float:
-    return min(2.0, 0.2 * (2**attempt))
-
-
-def _retry_after(resp: httpx.Response) -> float | None:
-    raw = resp.headers.get("Retry-After")
-    if raw and raw.isdigit():
-        return float(raw)
-    return None
-
-
-def _api_error(resp: httpx.Response) -> WebhookdAPIError:
-    code, message = "error", resp.text
-    try:
-        err = resp.json().get("error") or {}
-        code = err.get("code", code)
-        message = err.get("message", message)
-    except Exception:  # noqa: BLE001 - a non-JSON error body falls back to the raw text
-        pass
-    return WebhookdAPIError(resp.status_code, code, message)