hookbase 3.3.0__tar.gz → 4.0.0__tar.gz

{hookbase-3.3.0 → hookbase-4.0.0}/.github/workflows/python-publish.yml

@@ -13,7 +13,9 @@ permissions:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    # ubuntu-latest (26.04) has no Python 3.9 build for setup-python; 24.04 does, and 3.9 is
+    # still in requires-python.
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hookbase
-Version: 3.3.0
+Version: 4.0.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
@@ -137,7 +137,7 @@ client.deliveries.bulk_replay(["del_1", "del_2"])
 
 # Transforms & Filters
 client.transforms.create({"name": "Extract", "transformType": "jsonata", "code": "$.data"})
-client.transforms.test("txf_id", payload={"data": {"key": "value"}})
+client.transforms.test(code="$.data", payload={"data": {"key": "value"}})  # .result
 client.filters.test([{"field": "$.type", "operator": "eq", "value": "order"}], payload={...})
 
 # Schemas
@@ -213,10 +213,16 @@ for source in page.auto_paging_iter():
 while page.has_more:
     page = page.next_page()
 
-# Cursor-based (applications, endpoints, subscriptions, etc.)
+# Cursor-based (inbound events, applications, endpoints, subscriptions, etc.)
 page = client.outbound.applications.list(limit=50)
 for app in page.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

{hookbase-3.3.0 → hookbase-4.0.0}/README.md

@@ -102,7 +102,7 @@ client.deliveries.bulk_replay(["del_1", "del_2"])
 
 # Transforms & Filters
 client.transforms.create({"name": "Extract", "transformType": "jsonata", "code": "$.data"})
-client.transforms.test("txf_id", payload={"data": {"key": "value"}})
+client.transforms.test(code="$.data", payload={"data": {"key": "value"}})  # .result
 client.filters.test([{"field": "$.type", "operator": "eq", "value": "order"}], payload={...})
 
 # Schemas
@@ -178,10 +178,16 @@ for source in page.auto_paging_iter():
 while page.has_more:
     page = page.next_page()
 
-# Cursor-based (applications, endpoints, subscriptions, etc.)
+# Cursor-based (inbound events, applications, endpoints, subscriptions, etc.)
 page = client.outbound.applications.list(limit=50)
 for app in page.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

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

@@ -140,6 +140,7 @@ class SyncCursorPage(Generic[T]):
         path: str,
         params: dict[str, Any],
         model: type[T],
+        data_key: str | None = None,
     ) -> None:
         self.data = data
         self.has_more = has_more
@@ -148,6 +149,7 @@ class SyncCursorPage(Generic[T]):
         self._path = path
         self._params = params
         self._model = model
+        self._data_key = data_key
 
     def next_page(self) -> SyncCursorPage[T]:
         return _fetch_cursor_page(
@@ -155,6 +157,7 @@ class SyncCursorPage(Generic[T]):
             self._path,
             {**self._params, "cursor": self.next_cursor},
             self._model,
+            data_key=self._data_key,
         )
 
     def auto_paging_iter(self) -> Iterator[T]:
@@ -189,6 +192,7 @@ class AsyncCursorPage(Generic[T]):
         path: str,
         params: dict[str, Any],
         model: type[T],
+        data_key: str | None = None,
     ) -> None:
         self.data = data
         self.has_more = has_more
@@ -197,6 +201,7 @@ class AsyncCursorPage(Generic[T]):
         self._path = path
         self._params = params
         self._model = model
+        self._data_key = data_key
 
     async def next_page(self) -> AsyncCursorPage[T]:
         return await _async_fetch_cursor_page(
@@ -204,6 +209,7 @@ class AsyncCursorPage(Generic[T]):
             self._path,
             {**self._params, "cursor": self.next_cursor},
             self._model,
+            data_key=self._data_key,
         )
 
     async def auto_paging_iter(self) -> AsyncIterator[T]:
@@ -222,6 +228,128 @@ class AsyncCursorPage(Generic[T]):
         return len(self.data)
 
 
+class SyncLimitOffsetPage(Generic[T]):
+    """`limit`/`offset` paginated response with no total (sync).
+
+    The API reports no total for these lists, so another page is assumed while
+    pages come back full. The next page starts after the rows actually
+    returned, not after the requested `limit`: the API clamps `limit`, and
+    advancing by the requested size would skip the rows in between.
+    """
+
+    data: list[T]
+    limit: int
+    offset: int
+
+    def __init__(
+        self,
+        data: list[T],
+        limit: int,
+        offset: int,
+        *,
+        transport: SyncTransport,
+        path: str,
+        params: dict[str, Any],
+        model: type[T],
+        data_key: str,
+    ) -> None:
+        self.data = data
+        self.limit = limit
+        self.offset = offset
+        self._transport = transport
+        self._path = path
+        self._params = params
+        self._model = model
+        self._data_key = data_key
+
+    @property
+    def has_more(self) -> bool:
+        return len(self.data) > 0 and len(self.data) >= self.limit
+
+    def next_page(self) -> SyncLimitOffsetPage[T]:
+        return _fetch_limit_offset_page(
+            self._transport,
+            self._path,
+            {**self._params, "offset": self.offset + len(self.data)},
+            self._model,
+            data_key=self._data_key,
+        )
+
+    def auto_paging_iter(self) -> Iterator[T]:
+        page = self
+        while True:
+            yield from page.data
+            if not page.has_more:
+                break
+            page = page.next_page()
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.data)
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+
+class AsyncLimitOffsetPage(Generic[T]):
+    """`limit`/`offset` paginated response with no total (async).
+
+    See :class:`SyncLimitOffsetPage`.
+    """
+
+    data: list[T]
+    limit: int
+    offset: int
+
+    def __init__(
+        self,
+        data: list[T],
+        limit: int,
+        offset: int,
+        *,
+        transport: AsyncTransport,
+        path: str,
+        params: dict[str, Any],
+        model: type[T],
+        data_key: str,
+    ) -> None:
+        self.data = data
+        self.limit = limit
+        self.offset = offset
+        self._transport = transport
+        self._path = path
+        self._params = params
+        self._model = model
+        self._data_key = data_key
+
+    @property
+    def has_more(self) -> bool:
+        return len(self.data) > 0 and len(self.data) >= self.limit
+
+    async def next_page(self) -> AsyncLimitOffsetPage[T]:
+        return await _async_fetch_limit_offset_page(
+            self._transport,
+            self._path,
+            {**self._params, "offset": self.offset + len(self.data)},
+            self._model,
+            data_key=self._data_key,
+        )
+
+    async def auto_paging_iter(self) -> AsyncIterator[T]:
+        page = self
+        while True:
+            for item in page.data:
+                yield item
+            if not page.has_more:
+                break
+            page = await page.next_page()
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.data)
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+
 # --- Helper functions for fetching pages ---
 
 
@@ -279,9 +407,11 @@ def _fetch_cursor_page(
     path: str,
     params: dict[str, Any],
     model: type[T],
+    *,
+    data_key: str | None = None,
 ) -> SyncCursorPage[T]:
     resp = transport.request("GET", path, params=params)
-    items, has_more, next_cursor = _extract_cursor_data(resp)
+    items, has_more, next_cursor = _extract_cursor_data(resp, data_key)
     return SyncCursorPage(
         data=_parse_list(items, model),
         has_more=has_more,
@@ -290,6 +420,7 @@ def _fetch_cursor_page(
         path=path,
         params=params,
         model=model,
+        data_key=data_key,
     )
 
 
@@ -298,9 +429,11 @@ async def _async_fetch_cursor_page(
     path: str,
     params: dict[str, Any],
     model: type[T],
+    *,
+    data_key: str | None = None,
 ) -> AsyncCursorPage[T]:
     resp = await transport.request("GET", path, params=params)
-    items, has_more, next_cursor = _extract_cursor_data(resp)
+    items, has_more, next_cursor = _extract_cursor_data(resp, data_key)
     return AsyncCursorPage(
         data=_parse_list(items, model),
         has_more=has_more,
@@ -309,6 +442,51 @@ async def _async_fetch_cursor_page(
         path=path,
         params=params,
         model=model,
+        data_key=data_key,
+    )
+
+
+def _fetch_limit_offset_page(
+    transport: SyncTransport,
+    path: str,
+    params: dict[str, Any],
+    model: type[T],
+    *,
+    data_key: str,
+) -> SyncLimitOffsetPage[T]:
+    resp = transport.request("GET", path, params=params)
+    items, limit, offset = _extract_limit_offset_data(resp, data_key, params)
+    return SyncLimitOffsetPage(
+        data=_parse_list(items, model),
+        limit=limit,
+        offset=offset,
+        transport=transport,
+        path=path,
+        params=params,
+        model=model,
+        data_key=data_key,
+    )
+
+
+async def _async_fetch_limit_offset_page(
+    transport: AsyncTransport,
+    path: str,
+    params: dict[str, Any],
+    model: type[T],
+    *,
+    data_key: str,
+) -> AsyncLimitOffsetPage[T]:
+    resp = await transport.request("GET", path, params=params)
+    items, limit, offset = _extract_limit_offset_data(resp, data_key, params)
+    return AsyncLimitOffsetPage(
+        data=_parse_list(items, model),
+        limit=limit,
+        offset=offset,
+        transport=transport,
+        path=path,
+        params=params,
+        model=model,
+        data_key=data_key,
     )
 
 
@@ -342,14 +520,38 @@ def _extract_offset_data(
     return items if isinstance(items, list) else [], total, page, page_size
 
 
-def _extract_cursor_data(resp: Any) -> tuple[list[Any], bool, str | None]:
-    """Extract items + pagination from a cursor-based API response."""
+def _extract_cursor_data(
+    resp: Any, data_key: str | None = None
+) -> tuple[list[Any], bool, str | None]:
+    """Extract items + pagination from a cursor-based API response.
+
+    Most cursor lists nest `hasMore`/`nextCursor` under `pagination`; inbound
+    events (`GET /api/events`) put them at the top level next to `events`.
+    """
     if not isinstance(resp, dict):
         return [], False, None
 
-    items = resp.get("data", [])
-    pagination = resp.get("pagination", {})
+    items = resp[data_key] if data_key and data_key in resp else resp.get("data", [])
+    pagination = resp.get("pagination")
+    if not isinstance(pagination, dict):
+        pagination = resp
     has_more = pagination.get("hasMore", pagination.get("has_more", False))
     next_cursor = pagination.get("nextCursor", pagination.get("next_cursor"))
 
-    return items if isinstance(items, list) else [], has_more, next_cursor
+    return items if isinstance(items, list) else [], bool(has_more), next_cursor
+
+
+def _extract_limit_offset_data(
+    resp: Any, data_key: str, params: dict[str, Any]
+) -> tuple[list[Any], int, int]:
+    """Extract items + the limit/offset the API actually applied.
+
+    The API clamps `limit` (deliveries cap it at 100) and echoes the values it
+    used, so read those back rather than trusting what was requested.
+    """
+    if not isinstance(resp, dict):
+        return [], int(params.get("limit") or 50), int(params.get("offset") or 0)
+    items = resp.get(data_key, resp.get("data", []))
+    limit = resp.get("limit", params.get("limit") or 50)
+    offset = resp.get("offset", params.get("offset") or 0)
+    return items if isinstance(items, list) else [], int(limit), int(offset)

hookbase-4.0.0/src/hookbase/_version.py

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

{hookbase-3.3.0 → hookbase-4.0.0}/src/hookbase/models/__init__.py

@@ -11,7 +11,15 @@ from .catalog import (
     ProviderSignatureVerificationSummary,
     ProviderVerifyTokenInfo,
 )
-from .common import BulkDeleteResult, ImportResult, ImportResultItem
+from .common import (
+    BulkDeleteResult,
+    ImportDetails,
+    ImportFailure,
+    ImportResult,
+    ImportResultItem,
+    ImportSummary,
+    ImportValidationResult,
+)
 from .cron_jobs import (
     CreateCronGroupParams,
     CreateCronJobParams,
@@ -146,6 +154,10 @@ __all__ = [
     "BulkDeleteResult",
     "ImportResult",
     "ImportResultItem",
+    "ImportSummary",
+    "ImportDetails",
+    "ImportFailure",
+    "ImportValidationResult",
     # Cron Jobs
     "CreateCronGroupParams",
     "CreateCronJobParams",

hookbase-4.0.0/src/hookbase/models/common.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import HookbaseModel
+
+
+class ImportResultItem(HookbaseModel):
+    """Deprecated: no import response carries per-item results in this shape.
+    See :class:`ImportResult`."""
+
+    name: str
+    status: str
+    error: str | None = None
+
+
+class ImportFailure(HookbaseModel):
+    """An item that failed to import, and why."""
+
+    name: str = ""
+    error: str = ""
+
+
+class ImportSummary(HookbaseModel):
+    """Counts for an import. Which keys are set depends on the resource and on
+    whether it was a `validate_only` run."""
+
+    total: int | None = None
+    imported: int | None = None
+    skipped: int | None = None
+    overwritten: int | None = None
+    failed: int | None = None
+    errors: int | None = None
+    to_create: int | None = None
+    to_overwrite: int | None = None
+    to_skip: int | None = None
+    valid: int | None = None
+    overwrite: int | None = None
+
+
+class ImportDetails(HookbaseModel):
+    """Names of the items in each outcome (sources and destinations imports)."""
+
+    imported: list[str] = []
+    skipped: list[str] = []
+    overwritten: list[str] = []
+    failed: list[ImportFailure] = []
+
+
+class ImportValidationResult(HookbaseModel):
+    """How one item fared in validation."""
+
+    index: int = 0
+    name: str = ""
+    slug: str | None = None
+    status: str = ""
+    """`valid`, `error`, `skip`, `rename` or `overwrite`."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    resolved_slug: str | None = None
+    resolved_name: str | None = None
+
+
+class ImportResult(HookbaseModel):
+    """The result of `import_sources`, `import_destinations` or `import_routes`.
+
+    A `validate_only` run sets `valid` (sources, destinations), `validation_results`
+    and a `summary` of what would happen. A real import sets `success` and a
+    `summary`; sources and destinations list the item names in `details`, while
+    routes put them in `imported`, `skipped` and `errors`.
+    """
+
+    success: bool = False
+    valid: bool | None = None
+    validate_only: bool = False
+    summary: ImportSummary | None = None
+    details: ImportDetails | None = None
+    validation_results: list[ImportValidationResult] = []
+    imported: list[str] = []
+    """Route imports only; sources and destinations use `details.imported`."""
+    skipped: list[str] = []
+    """Route imports only; sources and destinations use `details.skipped`."""
+    errors: list[ImportFailure] = []
+    """Route imports only; sources and destinations use `details.failed`."""
+
+
+class BulkDeleteResult(HookbaseModel):
+    success: bool = True
+    deleted: int = 0
+
+
+class PaginationInfo(HookbaseModel):
+    total: int = 0
+    page: int = 1
+    page_size: int = 20
+
+
+class CursorPaginationInfo(HookbaseModel):
+    has_more: bool = False
+    next_cursor: str | None = None
+
+
+class ApiListResponse(HookbaseModel):
+    """Generic wrapper for paginated list API responses."""
+
+    data: list[Any] = []
+    pagination: PaginationInfo | None = None

hookbase-4.0.0/src/hookbase/models/deliveries.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pydantic import field_validator, model_validator
+from pydantic.alias_generators import to_camel
+
+from ._base import HookbaseModel
+
+# API may return: pending, success, failed, retrying, delivered,
+# failed_over, schema_failed, exhausted, etc.
+DeliveryStatus = str
+
+
+class Delivery(HookbaseModel):
+    id: str
+    event_id: str
+    route_id: str
+    destination_id: str
+    organization_id: str
+    status: DeliveryStatus = "pending"
+    attempt_count: int = 0
+    max_attempts: int = 5
+    next_retry_at: str | None = None
+    response_status: int | None = None
+    response_key: str | None = None
+    response_headers: dict[str, Any] | None = None
+    response_body: str | None = None
+    latency_ms: int | None = None
+    error_message: str | None = None
+    delivered_at: str | None = None
+    created_at: str = ""
+    updated_at: str | None = None
+    destination_name: str | None = None
+    destination_url: str | None = None
+    """Set by `deliveries.get` and on `events.get` deliveries; not by `deliveries.list`."""
+    event_type: str | None = None
+    """Set by `deliveries.list` only."""
+
+    # Deprecated: the SDK's older names for fields the API returns as
+    # `responseStatus`, `attemptCount`, `errorMessage`, `latencyMs` and
+    # `deliveredAt`. Never sent by the API, so they used to be always empty;
+    # now kept in step with the real fields so existing attribute access works.
+    status_code: int | None = None
+    """Deprecated: read `response_status`."""
+    attempts: int = 0
+    """Deprecated: read `attempt_count`."""
+    error: str | None = None
+    """Deprecated: read `error_message`."""
+    duration: float | None = None
+    """Deprecated: read `latency_ms`."""
+    completed_at: str | None = None
+    """Deprecated: read `delivered_at`."""
+
+    @field_validator("attempt_count", "max_attempts", mode="before")
+    @classmethod
+    def _null_counts_to_default(cls, v: Any, info: Any) -> Any:
+        # The API sends null for a delivery the worker has not counted yet; a field default only
+        # covers a missing key, so without this every list/get containing one failed to validate.
+        if v is None:
+            return cls.model_fields[info.field_name].default
+        return v
+
+    @field_validator("response_headers", mode="before")
+    @classmethod
+    def _parse_response_headers(cls, v: Any) -> Any:
+        # Stored as JSON text, so the API usually sends a string.
+        if isinstance(v, str):
+            try:
+                parsed = json.loads(v)
+            except (json.JSONDecodeError, ValueError):
+                return None
+            return parsed if isinstance(parsed, dict) else None
+        return v
+
+    @model_validator(mode="before")
+    @classmethod
+    def _mirror_deprecated(cls, data: Any) -> Any:
+        """Copy each real field onto its deprecated name, whichever spelling it came in."""
+        if not isinstance(data, dict):
+            return data
+        out = dict(data)
+        for new, old in _DEPRECATED_DELIVERY_FIELDS:
+            value = out.get(to_camel(new))
+            if value is None:
+                value = out.get(new)
+            if value is not None:
+                out.pop(old, None)
+                out[to_camel(old)] = value
+        return out
+
+
+# (current field, deprecated field kept in step with it)
+_DEPRECATED_DELIVERY_FIELDS = (
+    ("response_status", "status_code"),
+    ("attempt_count", "attempts"),
+    ("error_message", "error"),
+    ("latency_ms", "duration"),
+    ("delivered_at", "completed_at"),
+)
+
+
+class DeliveryEvent(HookbaseModel):
+    id: str
+    event_type: str | None = None
+    received_at: str = ""
+
+
+class DeliveryDestination(HookbaseModel):
+    name: str
+    url: str
+
+
+class DeliveryDetail(Delivery):
+    # Deprecated: `GET /api/deliveries/:id` has never returned nested `event` or
+    # `destination` objects, so these are always None. Read `event_id`,
+    # `destination_name` and `destination_url` instead.
+    event: DeliveryEvent | None = None
+    destination: DeliveryDestination | None = None
+
+
+class ReplayResult(HookbaseModel):
+    delivery_id: str
+    message: str = ""
+
+
+class BulkReplayResult(HookbaseModel):
+    message: str = ""
+    queued: int = 0
+    skipped: int = 0
+    events_processed: int | None = None
+    """Set by `bulk_replay_events` only."""
+    overrides: dict[str, Any] | None = None
+    """Set by `bulk_replay_events` only."""
+    results: list[dict[str, Any]] = []

{hookbase-3.3.0 → hookbase-4.0.0}/src/hookbase/models/destinations.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import json
 from typing import Any, Literal
 
-from pydantic import Field, field_validator, model_validator
+from pydantic import field_validator, model_validator
 
 from . import _wire
 from ._base import HookbaseModel
@@ -317,10 +317,28 @@ def update_destination_body(
 
 class TestResult(HookbaseModel):
     success: bool
-    # The API answers with `status`/`latencyMs` (api/src/routes/destinations.ts), not the
-    # `statusCode`/`duration` that HookbaseModel's to_camel alias_generator would otherwise
-    # expect for these field names — override the alias explicitly rather than rely on it.
-    status_code: int | None = Field(default=None, alias="status")
-    duration: float | None = Field(default=None, alias="latencyMs")
+    status: int | None = None
+    """The HTTP status the destination answered with."""
+    latency_ms: int | None = None
     response_body: str | None = None
     error: str | None = None
+
+    status_code: int | None = None
+    """Deprecated: the API calls this `status`; read `status` instead. Kept in
+    step with it so existing attribute access keeps working."""
+    duration: float | None = None
+    """Deprecated: the API calls this `latencyMs`; read `latency_ms` instead.
+    Kept in step with it so existing attribute access keeps working."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _mirror_deprecated(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        out = dict(data)
+        if out.get("status") is not None:
+            out["statusCode"] = out["status"]
+        latency = out.get("latencyMs", out.get("latency_ms"))
+        if latency is not None:
+            out["duration"] = latency
+        return out