hookbase 4.0.0__tar.gz → 4.2.0__tar.gz

{hookbase-4.0.0 → hookbase-4.2.0}/.gitignore

@@ -11,3 +11,6 @@ build/
 *.so
 .venv/
 venv/
+.coverage
+.coverage.*
+htmlcov/

hookbase-4.2.0/PKG-INFO

@@ -0,0 +1,530 @@
+Metadata-Version: 2.5
+Name: hookbase
+Version: 4.2.0
+Summary: Official Python SDK for the Hookbase webhook management platform
+Project-URL: Homepage, https://hookbase.app
+Project-URL: Documentation, https://www.hookbase.app/docs/send/sdk
+Project-URL: Repository, https://github.com/HookbaseApp/hookbase-python
+Project-URL: Issues, https://github.com/HookbaseApp/hookbase-python/issues
+Author-email: Hookbase <support@hookbase.app>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: eval-type-backport>=0.2.0; python_version < '3.10'
+Requires-Dist: httpx<1.0.0,>=0.25.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: cryptography>=38.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: ed25519
+Requires-Dist: cryptography>=38.0; extra == 'ed25519'
+Description-Content-Type: text/markdown
+
+# Hookbase Python SDK
+
+The official Python SDK for the [Hookbase](https://hookbase.app) webhook management platform.
+
+## Installation
+
+```bash
+pip install hookbase
+# To verify Ed25519 (v1a) signed webhooks, include the optional extra:
+pip install 'hookbase[ed25519]'
+```
+
+## Quick Start
+
+```python
+from hookbase import Hookbase
+
+client = Hookbase(api_key="whr_your_api_key")
+
+# List webhook sources
+sources = client.sources.list()
+for source in sources.data:
+    print(f"{source.name} ({source.provider})")
+
+# Send an outbound webhook
+result = client.outbound.messages.send(
+    "app_123",
+    event_type="order.created",
+    payload={"orderId": "456", "amount": 99.99},
+)
+print(f"Sent: {result.event_id}")
+```
+
+## Async Support
+
+```python
+from hookbase import AsyncHookbase
+
+async with AsyncHookbase(api_key="whr_...") as client:
+    sources = await client.sources.list()
+```
+
+## API Reference
+
+### Client Initialization
+
+```python
+from hookbase import Hookbase
+
+client = Hookbase(
+    api_key="whr_...",           # Required
+    base_url="https://...",      # Default: https://api.hookbase.app
+    timeout=30.0,                # Seconds or httpx.Timeout (default: 30); None = no timeout
+    max_retries=3,               # Default: 3
+    debug=False,                 # Log requests
+)
+```
+
+#### Custom `httpx` client
+
+Pass your own `httpx.Client` (or `httpx.AsyncClient` for `AsyncHookbase`) for proxies, custom
+transports or TLS settings. The SDK uses it as given and never modifies it: every request is
+sent to an absolute URL built from `base_url`, with the SDK's `Authorization` (an `auth=` set on
+your client is not applied to Hookbase requests) and `User-Agent` headers. If you pass `timeout`
+(a number, an `httpx.Timeout`, or `None` for no timeout), it is applied to each request; if you
+leave it out, the client's own timeout applies. `close()` (and the context manager) leaves a client you supplied open, so close
+it yourself.
+
+```python
+import httpx
+from hookbase import Hookbase
+
+http = httpx.Client(verify="/etc/ssl/corp-ca.pem", timeout=10.0)
+client = Hookbase(api_key="whr_...", http_client=http)  # uses the 10s client timeout
+...
+client.close()
+http.close()
+```
+
+### Inbound Webhooks
+
+```python
+# Sources
+client.sources.list(page_size=50)  # the API has no search/provider filter on this list
+client.sources.create({"name": "GitHub", "slug": "github", "provider": "github"})
+client.sources.get("src_id")
+client.sources.update("src_id", {"name": "Updated"})
+client.sources.delete("src_id")
+client.sources.rotate_secret("src_id")  # 400 for vendor-issued/public-key/built-in secrets
+client.sources.reveal_secret("src_id")
+
+# A provider that verifies with no secret: signing_secret comes back None
+wise = client.sources.create({"name": "Wise", "slug": "wise", "provider": "wise"})
+assert wise.verifies_without_secret and wise.signing_secret is None
+
+# WhatsApp (Meta) sources also carry a verify token
+wa = client.sources.create({"name": "WhatsApp", "slug": "whatsapp", "provider": "whatsapp"})
+print(wa.verify_token)
+client.sources.rotate_verify_token(wa.id)
+
+# Notion parks its verification token until you adopt it
+pending = client.sources.get_pending_verification("notion")
+client.sources.adopt_pending_verification("notion")
+
+# Provider catalog: which secret each provider needs (public, no auth needed)
+for p in client.providers.list(category="payments").providers:
+    print(p.hookbase_provider, p.signature_verification and p.signature_verification.secret_source)
+client.providers.get("stripe").signature_verification
+
+# Record the catalog entry a source is made from (create only). Entries with no verifier of
+# their own, such as Salesforce, save as Custom HMAC:
+client.sources.create({"name": "Salesforce", "slug": "salesforce", "provider": "custom",
+                       "catalogProvider": "salesforce"})
+
+# Destinations
+client.destinations.list()
+dest = client.destinations.create({"name": "Backend", "url": "https://..."})
+client.destinations.test("dst_id")
+
+# HTTP destinations sign every delivery (Standard Webhooks headers), so the receiver can check
+# it with Webhook(secret).verify(). Create returns the secret once: put it in your secret store.
+# repr() and str() leave it out, so logging the destination doesn't leak it.
+signing_secret = dest.signing_secret            # whsec_...; dest.has_signing_secret is True
+client.destinations.reveal_secret("dst_id").signing_secret
+rotated = client.destinations.rotate_secret("dst_id", grace_period_seconds=3600)
+rotated.previous_secret_expires_at              # until then the old secret signs too
+
+# Bridge destinations publish each delivery they receive as an outbound event
+from hookbase.models import BridgeConfig, CreateDestinationParams
+
+bridge = client.destinations.create(CreateDestinationParams(
+    name="Orders to customers",
+    type="bridge",
+    config=BridgeConfig(event_type_source="field", event_type_field="type",
+                        event_type_prefix="order."),
+))
+# A bridge's test is a dry run: nothing is published
+result = client.destinations.test(bridge.id, payload={"type": "created"})
+result.event_type, result.event_type_exists, result.matching_endpoints
+
+# Routes
+client.routes.create({"name": "Route", "sourceId": "src_id", "destinationId": "dst_id"})
+client.routes.get_circuit_status("route_id")
+client.routes.reset_circuit("route_id")
+
+# While a route's circuit is open its deliveries are held (status "held", hold_expires_at set)
+# and go out when it closes. hold_on_circuit_open=False dead-letters them as soon as the circuit
+# opens instead.
+client.routes.update("route_id", {"holdOnCircuitOpen": False})
+client.routes.get("route_id").held_count  # get only; held_count_capped past 10,000
+
+# Events & Deliveries
+client.events.list(source_id="src_id", from_date="2024-01-01")  # id or slug; unknown -> 404
+client.events.get("evt_id")  # Includes payload and deliveries
+client.events.debug("evt_id").curl_command  # plus typed deliveries, pattern hints, circuit state
+client.deliveries.replay("del_id")
+client.deliveries.bulk_replay(["del_1", "del_2"])
+
+# Replay with edits. payload_patch is an RFC 7386 merge patch on the stored payload (None
+# removes a key), so it works on sources that mask fields; modified_payload replaces it. An
+# argument left as None is not sent.
+client.deliveries.replay(
+    "del_id",
+    payload_patch={"amount": 10, "coupon": None},
+    destination_override="backup-destination",   # id or slug
+    headers_override={"X-Replay": "1"},
+)
+
+# Transforms & Filters
+client.transforms.engines()  # languages this deployment runs, and which are available
+client.transforms.create({"name": "Extract", "transformType": "jsonata", "code": "$.data"})
+client.transforms.test(code="$.data", payload={"data": {"key": "value"}})  # .result
+client.filters.test(
+    [{"field": "type", "operator": "equals", "value": "order"}],  # dot paths: "data.status"
+    payload={"type": "order"},
+    logic="AND",  # or "OR"; sent uppercase
+)
+
+# Schemas
+client.schemas.create({"name": "OrderSchema", "jsonSchema": {"type": "object", "required": ["orderId"]}})
+```
+
+### Outbound Webhooks
+
+```python
+# Applications
+client.outbound.applications.create({"name": "Acme", "externalId": "cust_123"})
+client.outbound.applications.get_by_external_id("cust_123")
+
+# Endpoints
+client.outbound.endpoints.create("app_id", {"url": "https://..."})
+client.outbound.endpoints.rotate_secret("ep_id", grace_period=3600)
+
+# An unset field is left alone by an update, so `None` cannot also mean "reset
+# this". Name the setting in `clear` to send an explicit null for it:
+client.outbound.endpoints.update("ep_id", {"clear": ["retryDelays"]})
+
+# While an endpoint's circuit is open its messages are held (status "held") and go out when it
+# recovers; hold_on_circuit_open=False dead-letters them instead. FIFO endpoints never hold.
+client.outbound.endpoints.update("ep_id", {"holdOnCircuitOpen": False})
+client.outbound.endpoints.get("ep_id").held_count
+
+# Event Types & Subscriptions
+client.outbound.event_types.create({"name": "order.created", "category": "orders"})
+client.outbound.subscriptions.create({"endpointId": "ep_id", "eventTypeId": "et_id"})
+client.outbound.subscriptions.bulk_create("ep_id", ["et_1", "et_2"])
+
+# Send Events
+sent = client.outbound.messages.send("app_id", event_type="order.created",
+                                     payload={"orderId": "ord_1"})
+sent.messages_held  # of messages_queued, those held behind an open circuit (None if none)
+
+# Message Log
+client.outbound.message_log.list(application_id="app_id", status="held")  # .hold_expires_at
+client.outbound.message_log.get("msg_id").bridge  # set when a bridge destination published it
+client.outbound.message_log.list_attempts("msg_id")
+client.outbound.message_log.stats()  # .held among the counts
+
+# Dead Letter Queue
+client.outbound.dlq.list()
+client.outbound.dlq.stats()
+client.outbound.dlq.retry("dlq_id")
+client.outbound.dlq.retry_bulk(["dlq_1", "dlq_2"])
+```
+
+### Admin
+
+```python
+# Organizations and creating API keys need a user session: with a whr_ API key the
+# API answers 403 (ForbiddenError).
+client.organizations.list()
+client.organizations.list_members("org_id")
+client.organizations.invite("org_id", "user@example.com", "member")
+client.api_keys.create({"name": "CI Key", "scopes": ["read", "write"]})
+
+# Analytics: range 1h, 24h, 7d or 30d (or "custom" with start_date/end_date)
+stats = client.analytics.dashboard(range="30d", tz="America/New_York")
+stats.overview.total_events, stats.latency.percentiles.p95, stats.errors.by_status_code
+
+# Schemas
+client.schemas.validate("sch_id", {"orderId": "ord_1"})  # .valid, .errors[].path/.message
+
+# Cron jobs
+client.cron_jobs.list()
+client.cron_jobs.trigger("cron_id")  # .status, .response_status, .error
+client.cron_jobs.list_executions("cron_id", limit=10)
+
+# Tunnels: the auth token is returned once, on create
+tunnel = client.tunnels.create({"name": "dev"})
+tunnel.auth_token, tunnel.tunnel_url, tunnel.ws_url
+client.tunnels.regenerate_token(tunnel.id)  # new token; old connections are dropped
+client.tunnels.delete(tunnel.id)
+```
+
+### Pagination
+
+```python
+# Offset-based (sources, destinations, routes, etc.)
+page = client.sources.list(page_size=10)
+print(f"Total: {page.total}, Page: {page.page}")
+
+# Auto-paginate through all items
+for source in page.auto_paging_iter():
+    print(source.name)
+
+# Manual pagination
+while page.has_more:
+    page = page.next_page()
+
+# Schemas and cron jobs are not paginated by the API: one page holding everything
+schemas = client.schemas.list()
+
+# Cursor-based (inbound events, applications, endpoints, subscriptions, etc.)
+apps = client.outbound.applications.list(limit=50)
+for app in apps.auto_paging_iter():
+    print(app.name)
+for event in client.events.list(limit=100).auto_paging_iter():
+    print(event.id)
+
+# Limit/offset with no total (deliveries): pages until one comes back short
+for delivery in client.deliveries.list(status="failed", limit=100).auto_paging_iter():
+    print(delivery.id, delivery.response_status)
+```
+
+### Webhook Verification
+
+```python
+from hookbase import Webhook, WebhookVerificationError
+
+wh = Webhook("whsec_your_secret")
+
+try:
+    payload = wh.verify(request_body, request_headers)
+    print(f"Verified: {payload}")
+except WebhookVerificationError as e:
+    print(f"Invalid: {e}")
+
+# Generate test headers
+headers = wh.generate_test_headers('{"test": true}')
+```
+
+#### Ed25519 (`v1a`) endpoints
+
+Endpoints created with `signature_scheme="ed25519"` are signed with Ed25519
+(Standard Webhooks `v1a,<sig>`). Hookbase keeps the private key; verify with the
+endpoint's `whpk_` public key. This needs `pip install 'hookbase[ed25519]'`.
+
+```python
+from hookbase.models import CreateEndpointParams
+
+ep = client.outbound.endpoints.create(
+    "app_id", CreateEndpointParams(url="https://example.com/hook", signature_scheme="ed25519")
+)
+assert ep.public_key is not None  # set for Ed25519 endpoints
+wh = Webhook(ep.public_key)  # "whpk_..."; same verify() API, tolerance and errors as v1
+payload = wh.verify(request_body, request_headers)
+
+# Rotation returns the new public key (no secret). During the grace period
+# deliveries carry `v1a,<old> v1a,<new>`, so either key verifies them.
+rotated = client.outbound.endpoints.rotate_secret(ep.id, grace_period=3600)
+rotated.public_key, rotated.previous_public_key
+```
+
+The key decides the scheme (`wh.signature_scheme`): a `whsec_` secret checks
+`v1` entries only and a `whpk_` key checks `v1a` entries only, so a header that
+mixes both verifies with either.
+
+### Error Handling
+
+```python
+from hookbase import (
+    HookbaseError,          # Base error
+    APIError,               # API returned an error
+    AuthenticationError,    # 401
+    ForbiddenError,         # 403
+    NotFoundError,          # 404
+    ValidationError,        # 400/422
+    ConflictError,          # 409
+    RateLimitError,         # 429 (has retry_after)
+    TimeoutError,           # Request timed out
+    NetworkError,           # Connection failed
+    WebhookVerificationError,
+)
+
+try:
+    client.sources.get("src_id")
+except NotFoundError:
+    print("Not found")
+except RateLimitError as e:
+    print(f"Retry after {e.retry_after}s")
+except APIError as e:
+    print(f"{e.status_code}: {e} (request_id={e.request_id})")
+```
+
+Every `APIError` carries:
+
+- `status_code`: the HTTP status actually returned (a `ValidationError` is 400 or 422).
+- `code`: the `code` from the response body, e.g. `LIMIT_EXCEEDED` or `FEATURE_DISABLED` on a
+  `ForbiddenError`. When the body has no `code`, it is the class default (`forbidden`,
+  `not_found`, `validation_error`, ...).
+- `details`: the body's `details` object (for validation failures, `{"fieldErrors": ...,
+  "formErrors": ...}`), or any extra fields the error sent (such as `current` and `max` on
+  `LIMIT_EXCEEDED`); `None` when there are none. `ValidationError.validation_errors` is the
+  `fieldErrors` map.
+- `request_id`: the `x-request-id` response header.
+
+`TimeoutError` and `NetworkError` (connection failures, and a `base_url` that is not an
+absolute http(s) URL) are raised for requests that got no response.
+
+### Retries
+
+Up to `max_retries` retries (default 3):
+
+- **429** is retried for every method after `Retry-After` (seconds or an HTTP date; 60 s
+  when the header is missing or unusable), as long as that wait is at most 60 s. A longer
+  `Retry-After` is not waited for: the `RateLimitError` is raised at once with `retry_after`
+  set, so you decide how to spend that time.
+- **Any 5xx, read timeouts and dropped connections** are retried with exponential backoff
+  (1, 2, 4 ... s, capped at 10 s, plus up to 1 s jitter) for every method except POST. A POST
+  is retried only when it carries an idempotency key (`outbound.messages.send` always does).
+- **A connection that was never made** is always retried.
+- **Other 4xx** responses are never retried.
+
+### Pydantic Models
+
+All responses are typed Pydantic models with camelCase alias support:
+
+```python
+from hookbase.models import Source, CreateSourceParams
+
+# Use Pydantic models for type safety
+params = CreateSourceParams(name="GitHub", slug="github", provider="github")
+source = client.sources.create(params)
+
+# Or use plain dicts
+source = client.sources.create({"name": "GitHub", "slug": "github", "provider": "github"})
+
+# `provider` is any string (hookbase.models.KNOWN_SOURCE_PROVIDERS lists today's values), so a
+# source with a provider newer than this package still parses.
+```
+
+## Upgrading to 4.2
+
+- **Fix:** `destinations.list()` and `get()` raised a `ValidationError` when the organization had
+  a destination of a type other than `http`, `s3`, `r2`, `gcs` or `azure_blob` (`sqs`,
+  `eventbridge`, `servicebus`, `pubsub`, `oci_queue`, `bridge`). `DestinationType`,
+  `TransformType` and `ContentFormat` now accept any string, as `MessageStatus` does, so types
+  added later parse too. `"form"`, which the API never accepted, is gone from `ContentFormat`.
+- **Fix:** `events.debug()` returned an empty `curl_command`, `event.headers` and
+  `event.payload`; they are filled in now. Its `deliveries` are typed (`EventDebugDelivery`).
+- `destinations.create()` returns a `DestinationWithSecret`, whose `signing_secret` is the only
+  time the secret is returned; afterwards use `reveal_secret()`. `rotate_secret()` takes
+  `grace_period_seconds`. `Destination.has_signing_secret` says whether deliveries are signed.
+- Bridge destinations: `BridgeConfig` for `config`, `Destination.bridge_config` to read it,
+  `destinations.test(id, payload=...)` for a dry run, and the dry-run fields on `TestResult`.
+- `deliveries.replay()` takes `modified_payload`, `payload_patch`, `destination_override`,
+  `transform_override`, `headers_override` and `persist_transform`; `ReplayResult` reports what
+  changed. Passing both payload edits raises `ValueError`. An argument left as None is not sent,
+  so `modified_payload` can be any JSON value but null. The same goes for `payload` on
+  `destinations.test()`.
+- Holds: the `held` status on deliveries and outbound messages, with `hold_expires_at`;
+  `hold_on_circuit_open`, `held_count` and `held_count_capped` on routes and webhook endpoints;
+  `messages_held` on `SendEventResponse` and `held` on `StatsSummary`. `MessageStatus` also
+  gains `awaiting_pull` and `fifo_waiting`.
+- `transforms.engines()` lists the transform languages the deployment runs.
+- `catalog_provider` on sources (set on create only).
+- `sources.export()` returns a raw dict, and the API now sends its `ipAllowlist`, `ipDenylist`,
+  `encryptFields` and `maskFields` as JSON arrays; they used to be JSON-encoded strings. Code
+  that calls `json.loads` on them must stop. The `Source` model already read either form.
+- Secrets and credentials no longer appear in `repr()` or `str()`:
+  - The secrets the API returns, on `DestinationWithSecret`, `DestinationSecret`,
+    `SourceWithSecret`, `PendingVerification`, `WebhookEndpoint`, `EndpointWithSecret`,
+    `RotateSecretResult`, `ApiKeyWithSecret`, `Tunnel`, `TunnelToken` and `PortalToken`.
+  - The headers and auth configs the API returns in full to a key with the `write` scope:
+    `Destination.headers` and `auth_config`, `WebhookEndpoint.headers` (and each
+    `CustomHeader.value`), and `CronJob.headers`.
+  - The credentials you pass in: `signing_secret` and `verify_token` on `CreateSourceParams`
+    and `UpdateSourceParams`; `headers`, `auth_config` and `config` on `CreateDestinationParams`
+    and `UpdateDestinationParams`; `headers` on the endpoint and cron job params; and the keys
+    on `S3Config`, `GCSConfig` and `AzureBlobConfig`.
+
+  A `pydantic.ValidationError` from one of these models, or from a list of them, leaves out the
+  input it was given. The values are still sent and still readable from their attributes
+  (`dest.signing_secret`).
+- **Typing:** `CreateDestinationParams.config` and `UpdateDestinationParams.config` are now
+  `dict[str, Any] | BridgeConfig | None`, so `params.config["bucket"]` no longer type-checks
+  until you narrow it with `isinstance(params.config, dict)`. Because `DestinationType`,
+  `TransformType` and `ContentFormat` now include `str`, mypy reads `Destination.type`,
+  `Transform.transform_type`, `input_format` and `output_format` as plain `str`. An exhaustive
+  `match` or `assert_never` over their literals no longer type-checks.
+
+## Upgrading to 4.1
+
+- `APIError.code` now carries the API's `code` from the response body (for example
+  `FEATURE_DISABLED` or `LIMIT_EXCEEDED` on a `ForbiddenError`, `DUPLICATE_NAME` on a
+  `ConflictError`) instead of a fixed string such as `"forbidden"` or `"conflict"`. The fixed
+  string is still used when the body has no `code`. Check code that compares `.code` to those
+  strings; `isinstance` checks on the error classes are unaffected.
+- `ValidationError.status_code` is the status actually returned (400 or 422); it used to be
+  always 400.
+- `APIError.details` is now populated (see [Error Handling](#error-handling)).
+- A custom `http_client` no longer needs `base_url`, auth headers or a timeout configured on it,
+  and `close()` no longer closes it.
+- `timeout=None` now means no timeout; leave `timeout` out to get the default.
+- Every 5xx (not only 500/502/503/504) is retried for retry-safe requests, and `Retry-After`
+  may be an HTTP date. A 429 whose `Retry-After` is longer than 60 s is no longer slept
+  through: `RateLimitError` is raised at once, `retry_after` set. An empty 2xx body returns
+  `None`; a 2xx body that is not valid JSON raises `APIError` (`code="invalid_response"`).
+- `Webhook("whsec_...")` raises `ValueError` for a secret that is not valid base64, at
+  construction rather than on the first `verify()`.
+- `analytics.dashboard()` returns the API's real shape (`overview`, `latency`, `errors`, ...).
+  The old top-level fields (`events_received`, `delivery_success_rate`, ...) are now
+  read-only properties derived from `overview`; before, they were always 0.
+- `sources.list(search=, provider=, is_active=)`, `destinations.list(search=, is_active=)` and
+  `routes.list(source_id=, destination_id=, is_active=)` warn (`DeprecationWarning`) and do
+  not send those filters, which the API never applied.
+- `transforms.update()` and `organizations.update()` make a second request to return the
+  stored object (they used to raise on the API's `{"success": true}` reply).
+- `SchemaValidationResult.errors` is a list of `SchemaValidationError` (`path`, `message`).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+mypy src/hookbase
+ruff check src/ tests/
+```
+
+## License
+
+MIT