webhookd-sdk 0.1.1__tar.gz → 0.3.0__tar.gz

webhookd_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: webhookd-sdk
+Version: 0.3.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
+Project-URL: Issues, https://github.com/NimbusNexus/Webhooks-sdks/issues
+Author: NimbusNexus
+License: MIT
+License-File: LICENSE
+Keywords: hmac,nimbusnexus,sdk,signature,verify,webhook,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# 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`.
+
+## Outbox / durable buffering (producers)
+
+`publish()` calls webhookd synchronously — if webhookd is unreachable it raises and the event is
+lost. The **write-first outbox** decouples the two: `enqueue()` durably persists the event to a
+pluggable `Store` and returns IMMEDIATELY (no network); `drain()` (or a background drainer) ships the
+buffered events later. Every send carries `Idempotency-Key = record.id`, so a re-drain after a crash
+or a lost response never double-publishes — webhookd dedupes. Delivery is **at-least-once**: nothing
+is lost while webhookd is down.
+
+```python
+from webhookd_sdk import Client, SQLiteStore
+
+# 1. Configure a durable store (survives process restarts).
+store = SQLiteStore("outbox.db")
+
+with Client("https://webhooks.example.com", api_key="whsk_…", store=store) as wh:
+    # 2. enqueue() instead of publish() — writes to the store and returns at once, NO network call.
+    record_id = wh.enqueue("order.created", {"order_id": "ord_123", "total": 4200})
+
+    # 3a. Drain on demand (returns {"sent", "failed", "remaining"}):
+    wh.drain()
+
+    # 3b. …or run a background drainer that calls drain() every 5s until the client closes.
+    wh.start_drainer(interval_seconds=5)
+    # ... your app keeps enqueuing; the drainer ships in the background ...
+    wh.stop_drainer()   # also called automatically by Client.close()/__exit__
+```
+
+**Idempotency guarantee.** `record_id` is the `idempotency_key` you pass (or a generated UUID v4) and
+becomes the `Idempotency-Key` header on every delivery attempt for that record. If the process
+crashes after a send but before the response is recorded, the next `drain()` re-sends with the *same*
+key and webhookd returns the original event without re-fanning-out. A record that keeps failing is
+retried with capped exponential backoff up to `max_attempts` (default 10), then flagged **dead**
+(never retried again) and handed to the optional `on_dead` callback.
+
+**Built-in stores** — pick one for `Client(..., store=...)`:
+
+| Store | Durable? | Extra needed |
+| --- | --- | --- |
+| `MemoryStore` | No (in-process) | — (stdlib) |
+| `FileStore(dir)` | Yes (per-record JSON files) | — (stdlib) |
+| `SQLiteStore(path)` | Yes (transactional) | — (stdlib `sqlite3`) |
+| `RedisStore(url)` | Yes | `pip install 'webhookd-sdk[redis]'` |
+| `PostgresStore(dsn)` | Yes | `pip install 'webhookd-sdk[postgres]'` |
+
+The core SDK stays zero-dependency; `RedisStore` / `PostgresStore` lazily import their driver only
+when you construct them.
+
+## 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.3.0/README.md

@@ -0,0 +1,144 @@
+# 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`.
+
+## Outbox / durable buffering (producers)
+
+`publish()` calls webhookd synchronously — if webhookd is unreachable it raises and the event is
+lost. The **write-first outbox** decouples the two: `enqueue()` durably persists the event to a
+pluggable `Store` and returns IMMEDIATELY (no network); `drain()` (or a background drainer) ships the
+buffered events later. Every send carries `Idempotency-Key = record.id`, so a re-drain after a crash
+or a lost response never double-publishes — webhookd dedupes. Delivery is **at-least-once**: nothing
+is lost while webhookd is down.
+
+```python
+from webhookd_sdk import Client, SQLiteStore
+
+# 1. Configure a durable store (survives process restarts).
+store = SQLiteStore("outbox.db")
+
+with Client("https://webhooks.example.com", api_key="whsk_…", store=store) as wh:
+    # 2. enqueue() instead of publish() — writes to the store and returns at once, NO network call.
+    record_id = wh.enqueue("order.created", {"order_id": "ord_123", "total": 4200})
+
+    # 3a. Drain on demand (returns {"sent", "failed", "remaining"}):
+    wh.drain()
+
+    # 3b. …or run a background drainer that calls drain() every 5s until the client closes.
+    wh.start_drainer(interval_seconds=5)
+    # ... your app keeps enqueuing; the drainer ships in the background ...
+    wh.stop_drainer()   # also called automatically by Client.close()/__exit__
+```
+
+**Idempotency guarantee.** `record_id` is the `idempotency_key` you pass (or a generated UUID v4) and
+becomes the `Idempotency-Key` header on every delivery attempt for that record. If the process
+crashes after a send but before the response is recorded, the next `drain()` re-sends with the *same*
+key and webhookd returns the original event without re-fanning-out. A record that keeps failing is
+retried with capped exponential backoff up to `max_attempts` (default 10), then flagged **dead**
+(never retried again) and handed to the optional `on_dead` callback.
+
+**Built-in stores** — pick one for `Client(..., store=...)`:
+
+| Store | Durable? | Extra needed |
+| --- | --- | --- |
+| `MemoryStore` | No (in-process) | — (stdlib) |
+| `FileStore(dir)` | Yes (per-record JSON files) | — (stdlib) |
+| `SQLiteStore(path)` | Yes (transactional) | — (stdlib `sqlite3`) |
+| `RedisStore(url)` | Yes | `pip install 'webhookd-sdk[redis]'` |
+| `PostgresStore(dsn)` | Yes | `pip install 'webhookd-sdk[postgres]'` |
+
+The core SDK stays zero-dependency; `RedisStore` / `PostgresStore` lazily import their driver only
+when you construct them.
+
+## 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.1 → webhookd_sdk-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webhookd-sdk"
-version = "0.1.1"
+version = "0.3.0"
 description = "Official Python SDK for NimbusNexus Webhooks — publish events + verify webhook signatures."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,6 +30,8 @@ Repository = "https://github.com/NimbusNexus/Webhooks-sdks"
 Issues = "https://github.com/NimbusNexus/Webhooks-sdks/issues"
 
 [project.optional-dependencies]
+redis = ["redis>=5"]
+postgres = ["psycopg[binary]>=3"]
 dev = ["pytest", "ruff", "mypy"]
 
 [tool.hatch.build.targets.wheel]

webhookd_sdk-0.3.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"