hookbase 3.2.0__tar.gz → 3.3.0__tar.gz

{hookbase-3.2.0 → hookbase-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hookbase
-Version: 3.2.0
+Version: 3.3.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

{hookbase-3.2.0 → hookbase-3.3.0}/src/hookbase/_client.py

@@ -76,6 +76,31 @@ def _should_retry(status_code: int) -> bool:
     return status_code in RETRY_STATUS_CODES
 
 
+# A POST creates something or triggers work, so repeating one that may already have reached the
+# server (a 5xx, a read timeout, a dropped connection) can do it twice. Only retry those when the
+# request carries an idempotency key the server can deduplicate on. A 429 was rejected before any
+# work was done, and a connect failure never reached the server, so those stay retryable.
+_NON_IDEMPOTENT_METHODS = frozenset({"POST"})
+
+
+def _may_repeat(method: str, idempotency_key: str | None) -> bool:
+    """Whether a request that may already have been processed is safe to send again."""
+    return method.upper() not in _NON_IDEMPOTENT_METHODS or bool(idempotency_key)
+
+
+def _never_sent(exc: httpx.HTTPError) -> bool:
+    """Whether the transport failed before the request reached the server."""
+    return isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout))
+
+
+def _decode_body(resp: httpx.Response) -> Any:
+    """JSON for JSON responses; the text for anything else (e.g. a CSV export)."""
+    content_type = resp.headers.get("content-type", "")
+    if content_type and "json" not in content_type.lower():
+        return resp.text
+    return resp.json()
+
+
 def _backoff(attempt: int) -> float:
     base = min(1.0 * (2**attempt), 10.0)
     jitter = random.random()  # noqa: S311
@@ -126,6 +151,7 @@ class SyncTransport:
         headers: dict[str, str] = {}
         if idempotency_key:
             headers["Idempotency-Key"] = idempotency_key
+        repeatable = _may_repeat(method, idempotency_key)
 
         if self._debug:
             logger.debug("[Hookbase] %s %s params=%s", method, path, cleaned)
@@ -143,13 +169,13 @@ class SyncTransport:
             except httpx.TimeoutException as exc:
                 last_exc = TimeoutError(f"Request timed out after {self._timeout}s")
                 last_exc.__cause__ = exc
-                if attempt < self._max_retries:
+                if attempt < self._max_retries and (repeatable or _never_sent(exc)):
                     time.sleep(_backoff(attempt))
                     continue
                 raise last_exc from exc
             except httpx.HTTPError as exc:
                 last_exc = NetworkError(str(exc), cause=exc)
-                if attempt < self._max_retries:
+                if attempt < self._max_retries and (repeatable or _never_sent(exc)):
                     time.sleep(_backoff(attempt))
                     continue
                 raise last_exc from exc
@@ -160,7 +186,7 @@ class SyncTransport:
                 return None
 
             if resp.is_success:
-                return resp.json()
+                return _decode_body(resp)
 
             # Parse error body
             try:
@@ -179,9 +205,12 @@ class SyncTransport:
                     except ValueError:
                         pass
 
-            # Don't retry client errors (except 429 and 409)
+            # Don't retry client errors (except 429), nor a 5xx on a request
+            # that is not safe to repeat (see `_may_repeat`).
             if not _should_retry(resp.status_code):
                 raise error
+            if not repeatable and not isinstance(error, RateLimitError):
+                raise error
 
             last_exc = error
 
@@ -242,6 +271,7 @@ class AsyncTransport:
         headers: dict[str, str] = {}
         if idempotency_key:
             headers["Idempotency-Key"] = idempotency_key
+        repeatable = _may_repeat(method, idempotency_key)
 
         if self._debug:
             logger.debug("[Hookbase] %s %s params=%s", method, path, cleaned)
@@ -259,13 +289,13 @@ class AsyncTransport:
             except httpx.TimeoutException as exc:
                 last_exc = TimeoutError(f"Request timed out after {self._timeout}s")
                 last_exc.__cause__ = exc
-                if attempt < self._max_retries:
+                if attempt < self._max_retries and (repeatable or _never_sent(exc)):
                     await asyncio.sleep(_backoff(attempt))
                     continue
                 raise last_exc from exc
             except httpx.HTTPError as exc:
                 last_exc = NetworkError(str(exc), cause=exc)
-                if attempt < self._max_retries:
+                if attempt < self._max_retries and (repeatable or _never_sent(exc)):
                     await asyncio.sleep(_backoff(attempt))
                     continue
                 raise last_exc from exc
@@ -276,7 +306,7 @@ class AsyncTransport:
                 return None
 
             if resp.is_success:
-                return resp.json()
+                return _decode_body(resp)
 
             try:
                 body = resp.json()
@@ -295,6 +325,8 @@ class AsyncTransport:
 
             if not _should_retry(resp.status_code):
                 raise error
+            if not repeatable and not isinstance(error, RateLimitError):
+                raise error
 
             last_exc = error
 

{hookbase-3.2.0 → hookbase-3.3.0}/src/hookbase/_pagination.py

@@ -161,7 +161,7 @@ class SyncCursorPage(Generic[T]):
         page = self
         while True:
             yield from page.data
-            if not page.has_more:
+            if not page.has_more or not page.next_cursor:
                 break
             page = page.next_page()
 
@@ -211,7 +211,7 @@ class AsyncCursorPage(Generic[T]):
         while True:
             for item in page.data:
                 yield item
-            if not page.has_more:
+            if not page.has_more or not page.next_cursor:
                 break
             page = await page.next_page()
 

hookbase-3.3.0/src/hookbase/_version.py

@@ -0,0 +1 @@
+__version__ = "3.3.0"

{hookbase-3.2.0 → hookbase-3.3.0}/src/hookbase/models/applications.py

@@ -14,6 +14,19 @@ class Application(HookbaseModel):
     organization_id: str
     external_id: str = ""
     metadata: dict[str, Any] | None = None
+    rate_limit_per_second: int | None = None
+    rate_limit_per_minute: int | None = None
+    rate_limit_per_hour: int | None = None
+    is_disabled: bool = False
+    disabled_at: str | None = None
+    disabled_reason: str | None = None
+    total_endpoints: int | None = None
+    total_messages_sent: int | None = None
+    total_messages_failed: int | None = None
+    last_event_at: str | None = None
+    send_event_url: str | None = None
+    created_by: str | None = None
+    api_key_id: str | None = None
     created_at: str = ""
     updated_at: str = ""
 
@@ -45,6 +58,9 @@ class CreateApplicationParams(HookbaseModel):
     name: str
     external_id: str | None = None
     metadata: dict[str, Any] | None = None
+    rate_limit_per_second: int | None = None
+    rate_limit_per_minute: int | None = None
+    rate_limit_per_hour: int | None = None
 
     uid: str | None = None
     """Deprecated: renamed to `external_id`, which is the only name the API
@@ -55,6 +71,11 @@ class CreateApplicationParams(HookbaseModel):
 class UpdateApplicationParams(HookbaseModel):
     name: str | None = None
     metadata: dict[str, Any] | None = None
+    rate_limit_per_second: int | None = None
+    rate_limit_per_minute: int | None = None
+    rate_limit_per_hour: int | None = None
+    is_disabled: bool | None = None
+    disabled_reason: str | None = None
 
 
 def application_body(params: CreateApplicationParams | dict[str, Any]) -> dict[str, Any]:

hookbase-3.3.0/src/hookbase/models/dlq.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import model_validator
+
+from ._base import HookbaseModel
+from .messages import _mirror
+
+
+class DlqMessage(HookbaseModel):
+    """A dead-lettered message, as `GET /api/outbound-messages/dlq/messages` returns it."""
+
+    id: str
+    event_id: str = ""
+    endpoint_id: str = ""
+    endpoint_url: str | None = None
+    application_id: str = ""
+    application_name: str | None = None
+    event_type: str = ""
+    status: str = ""
+    dlq_reason: str | None = None
+    dlq_moved_at: str | None = None
+    dlq_retry_count: int | None = None
+    dlq_last_retry_at: str | None = None
+    attempts: int = 0
+    max_attempts: int = 5
+    last_response_status: int | None = None
+    last_error_type: str | None = None
+    last_error_message: str | None = None
+    created_at: str = ""
+    completed_at: str | None = None
+
+    # Deprecated: names the API never sent.
+    message_id: str = ""
+    """Deprecated: read `event_id`."""
+    last_error: str | None = None
+    """Deprecated: read `last_error_message`."""
+    last_attempt_at: str | None = None
+    """Deprecated: not returned by the API; always `None`."""
+    updated_at: str = ""
+    """Deprecated: not returned by the API; always empty."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _fill_deprecated(cls, data: Any) -> Any:
+        return _mirror(data, {"messageId": "eventId", "lastError": "lastErrorMessage"})
+
+
+class DlqEndpointStat(HookbaseModel):
+    endpoint_id: str
+    endpoint_url: str | None = ""
+    count: int = 0
+
+
+class DlqEventTypeStat(HookbaseModel):
+    event_type: str
+    count: int = 0
+
+
+class DlqStats(HookbaseModel):
+    total: int = 0
+    by_reason: dict[str, int] = {}
+    by_endpoint: list[DlqEndpointStat] = []
+    """The ten endpoints with the most dead-lettered messages."""
+    by_event_type: list[DlqEventTypeStat] = []
+    """The ten event types with the most dead-lettered messages."""
+
+    top_failing_endpoints: list[DlqEndpointStat] = []
+    """Deprecated: read `by_endpoint`; this mirrors it."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _fill_deprecated(cls, data: Any) -> Any:
+        return _mirror(data, {"topFailingEndpoints": "byEndpoint"})
+
+
+class DlqRetryResult(HookbaseModel):
+    original_message_id: str = ""
+    new_message_id: str = ""
+    status: str = ""
+
+
+class DlqBulkRetryResultItem(HookbaseModel):
+    original_message_id: str = ""
+    new_message_id: str | None = None
+
+    message_id: str = ""
+    """Deprecated: read `original_message_id`; this mirrors it."""
+    status: str = ""
+    """Deprecated: the API returns only the messages it queued, so this is always `"queued"`."""
+    error: str | None = None
+    """Deprecated: not returned by the API; always `None`."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _fill_deprecated(cls, data: Any) -> Any:
+        data = _mirror(data, {"messageId": "originalMessageId"})
+        if isinstance(data, dict) and not data.get("status"):
+            data["status"] = "queued"
+        return data
+
+
+class DlqBulkRetryResult(HookbaseModel):
+    """The result of `POST /api/outbound-messages/dlq/retry-bulk`."""
+
+    queued: int = 0
+    """Messages re-queued for delivery."""
+    skipped: int = 0
+    """Requested IDs that were not in the DLQ (or not found)."""
+    messages: list[DlqBulkRetryResultItem] = []
+
+    # Deprecated: names the API never sent, derived from the fields above.
+    total: int = 0
+    """Deprecated: `queued + skipped`."""
+    retried: int = 0
+    """Deprecated: read `queued`."""
+    failed: int = 0
+    """Deprecated: read `skipped`."""
+    results: list[DlqBulkRetryResultItem] = []
+    """Deprecated: read `messages`."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _fill_deprecated(cls, data: Any) -> Any:
+        data = _mirror(data, {"retried": "queued", "failed": "skipped", "results": "messages"})
+        if isinstance(data, dict) and data.get("total") is None:
+            data["total"] = int(data.get("queued") or 0) + int(data.get("skipped") or 0)
+        return data
+
+
+class DlqBulkDeleteResult(HookbaseModel):
+    deleted: int = 0
+    """How many IDs were submitted; the API does not report how many were actually in the DLQ."""
+
+    total: int = 0
+    """Deprecated: mirrors `deleted`."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _fill_deprecated(cls, data: Any) -> Any:
+        return _mirror(data, {"total": "deleted"})

{hookbase-3.2.0 → hookbase-3.3.0}/src/hookbase/models/endpoints.py

@@ -271,5 +271,22 @@ class EndpointStats(HookbaseModel):
 
 
 class RotateSecretResult(HookbaseModel):
+    """The result of `POST /api/webhook-endpoints/:id/rotate-secret`."""
+
     secret: str
+    """The new signing secret. Save it now; no later response repeats it."""
+    previous_secret_expires_at: str | None = None
+    """Until when deliveries are also signed with the previous secret."""
+    secret_version: int | None = None
+
     previous_secret_valid_until: str | None = None
+    """Deprecated: read `previous_secret_expires_at`; this mirrors it."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _mirror_expiry(cls, data: Any) -> Any:
+        if isinstance(data, dict) and data.get("previousSecretValidUntil") is None:
+            expires = data.get("previousSecretExpiresAt")
+            if expires is not None:
+                return {**data, "previousSecretValidUntil": expires}
+        return data

hookbase-3.3.0/src/hookbase/models/event_types.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pydantic import Field, model_validator
+
+from . import _wire
+from ._base import HookbaseModel
+
+
+class EventType(HookbaseModel):
+    id: str
+    organization_id: str
+    name: str
+    display_name: str | None = None
+    description: str | None = None
+    category: str | None = None
+    schema_: Any = Field(default=None, alias="schema")
+    """The JSON Schema, decoded. The API stores it as JSON, so this is usually a dict."""
+    schema_version: int | None = None
+    example_payload: Any = None
+    documentation_url: str | None = None
+    default_priority: int | None = None
+    is_enabled: bool = True
+    is_deprecated: bool = False
+    deprecated_at: str | None = None
+    deprecated_message: str | None = None
+    is_public: bool = False
+    published_at: str | None = None
+    subscription_count: int | None = None
+    """Set on `list` responses only."""
+    created_at: str = ""
+    updated_at: str = ""
+
+    is_archived: bool = False
+    """Deprecated: not returned by the API; always false. See `is_deprecated`."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _decode_json_strings(cls, data: Any) -> Any:
+        """Decode `schema`/`examplePayload` if the API returned them as JSON text."""
+        if not isinstance(data, dict):
+            return data
+        out = dict(data)
+        for key in ("schema", "examplePayload"):
+            value = out.get(key)
+            if isinstance(value, str):
+                try:
+                    out[key] = json.loads(value)
+                except ValueError:
+                    pass
+        return out
+
+
+class CreateEventTypeParams(HookbaseModel):
+    name: str
+    display_name: str | None = None
+    description: str | None = None
+    category: str | None = None
+    schema_: dict[str, Any] | str | None = Field(default=None, alias="schema")
+    """A JSON Schema, as a dict or as JSON text."""
+    example_payload: Any = None
+    """An example payload, as a value or as JSON text."""
+    documentation_url: str | None = None
+    is_enabled: bool | None = None
+    default_priority: int | None = None
+
+
+class UpdateEventTypeParams(HookbaseModel):
+    display_name: str | None = None
+    description: str | None = None
+    category: str | None = None
+    schema_: dict[str, Any] | str | None = Field(default=None, alias="schema")
+    """A JSON Schema, as a dict or as JSON text."""
+    example_payload: Any = None
+    """An example payload, as a value or as JSON text."""
+    documentation_url: str | None = None
+    is_enabled: bool | None = None
+    is_deprecated: bool | None = None
+    deprecated_message: str | None = None
+    is_public: bool | None = None
+    default_priority: int | None = None
+
+
+def event_type_body(
+    params: CreateEventTypeParams | UpdateEventTypeParams | dict[str, Any],
+) -> dict[str, Any]:
+    """Build the body for `POST /api/event-types` or `PATCH /api/event-types/:id`.
+
+    The API validates `schema` and `examplePayload` as JSON *strings*
+    (`z.string()` in event-types.ts) and its schemas are `.strict()`, so a dict
+    there is a 400. Serialize anything that is not already a string.
+    """
+    body = _wire.dump(params)
+    _wire.canonicalize(body, "examplePayload")
+    if "schema_" in body:
+        body.setdefault("schema", body.pop("schema_"))
+    for key in ("schema", "examplePayload"):
+        value = body.get(key)
+        if value is not None and not isinstance(value, str):
+            body[key] = json.dumps(value)
+    return body

hookbase-3.3.0/src/hookbase/models/messages.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from typing import Any, Literal, Union
+
+from pydantic import model_validator
+
+from ._base import HookbaseModel
+
+# Every status `outbound_messages.status` takes. The field accepts any string so a status the
+# API adds later does not make a whole list page fail to decode, which a closed Literal did for
+# `processing`, `awaiting_retry` and `dlq`.
+MessageStatus = Union[
+    Literal[
+        "pending", "processing", "success", "failed", "awaiting_retry", "exhausted", "dlq",
+    ],
+    str,
+]
+
+
+def _mirror(data: Any, pairs: dict[str, str]) -> Any:
+    """Fill each deprecated field (key) from the API field it was a misspelling of (value)."""
+    if not isinstance(data, dict):
+        return data
+    out = dict(data)
+    for old, new in pairs.items():
+        if out.get(new) is not None and out.get(old) is None:
+            out[old] = out[new]
+    return out
+
+
+class SendEventParams(HookbaseModel):
+    event_type: str
+    payload: Any
+    event_id: str | None = None
+    metadata: dict[str, Any] | None = None
+    endpoint_ids: list[str] | None = None
+
+
+class SendEventEndpoint(HookbaseModel):
+    id: str
+    url: str = ""
+
+
+class SendEventResponse(HookbaseModel):
+    event_id: str = ""
+    messages_queued: int = 0
+    endpoints: list[SendEventEndpoint] = []
+
+
+class OutboundMessage(HookbaseModel):
+    """An outbound message as `GET /api/outbound-messages[/:id]` returns it.
+
+    `list` returns the summary fields; `get` adds the subscription, payload and
+    error-type fields, which are `None` on list items.
+    """
+
+    id: str
+    event_id: str = ""
+    event_type: str = ""
+    application_id: str = ""
+    application_name: str | None = None
+    endpoint_id: str = ""
+    endpoint_url: str | None = ""
+    status: MessageStatus = "pending"
+    attempts: int = 0
+    max_attempts: int = 5
+    last_response_status: int | None = None
+    last_error_message: str | None = None
+    created_at: str = ""
+    completed_at: str | None = None
+
+    # `get` only.
+    subscription_id: str | None = None
+    event_type_id: str | None = None
+    last_error_type: str | None = None
+    payload_key: str | None = None
+    payload_size_bytes: int | None = None
+    payload_hash: str | None = None
+    metadata: Any = None
+    priority: int | None = None
+    endpoint_description: str | None = None
+    payload: Any = None
+
+    # Deprecated: names the API never sent. The three with an API equivalent mirror it.
+    message_id: str = ""
+    """Deprecated: read `event_id`."""
+    last_error: str | None = None
+    """Deprecated: read `last_error_message`."""
+    delivered_at: str | None = None
+    """Deprecated: read `completed_at`."""
+    last_attempt_at: str | None = None
+    """Deprecated: not returned by the API; always `None`."""
+    next_attempt_at: str | None = None
+    """Deprecated: not returned by the API; always `None`."""
+    last_response_body: str | None = None
+    """Deprecated: not returned by the API; read the attempts instead."""
+    updated_at: str = ""
+    """Deprecated: not returned by the API; always empty."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _fill_deprecated(cls, data: Any) -> Any:
+        return _mirror(data, {
+            "messageId": "eventId",
+            "lastError": "lastErrorMessage",
+            "deliveredAt": "completedAt",
+        })
+
+
+class OutboundAttempt(HookbaseModel):
+    """One delivery attempt, as `GET /api/outbound-messages/:id/attempts` returns it."""
+
+    id: str
+    message_id: str = ""
+    attempt_number: int = 0
+    status: str = ""
+    response_status: int | None = None
+    response_headers: dict[str, Any] | None = None
+    response_body: str | None = None
+    response_time_ms: int | None = None
+    total_time_ms: int | None = None
+    error_type: str | None = None
+    error_message: str | None = None
+    error_code: str | None = None
+    request_url: str | None = None
+    request_headers: dict[str, Any] | None = None
+    request_body_size: int | None = None
+    triggered_by: str | None = None
+    triggered_by_user: str | None = None
+    created_at: str = ""
+    completed_at: str | None = None
+
+    # Deprecated: names the API never sent, each mirroring its API equivalent.
+    outbound_message_id: str = ""
+    """Deprecated: read `message_id`."""
+    error: str | None = None
+    """Deprecated: read `error_message`."""
+    latency_ms: float | None = None
+    """Deprecated: read `response_time_ms`."""
+    attempted_at: str = ""
+    """Deprecated: read `created_at`."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _fill_deprecated(cls, data: Any) -> Any:
+        return _mirror(data, {
+            "outboundMessageId": "messageId",
+            "error": "errorMessage",
+            "latencyMs": "responseTimeMs",
+            "attemptedAt": "createdAt",
+        })
+
+
+class StatsSummary(HookbaseModel):
+    pending: int = 0
+    processing: int = 0
+    success: int = 0
+    failed: int = 0
+    awaiting_retry: int = 0
+    exhausted: int = 0
+    dlq: int = 0
+    total: int = 0
+
+
+class ReplayResult(HookbaseModel):
+    original_message_id: str = ""
+    new_message_id: str = ""
+    status: str = ""