hookbase 3.2.0__tar.gz → 4.0.0__tar.gz

{hookbase-3.2.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.2.0 → hookbase-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hookbase
-Version: 3.2.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.2.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.2.0 → hookbase-4.0.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-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,13 +157,14 @@ 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]:
         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()
 
@@ -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,129 @@ 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]:
+        page = self
+        while True:
+            for item in page.data:
+                yield item
+            if not page.has_more or not page.next_cursor:
+                break
+            page = await page.next_page()
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.data)
+
+    def __len__(self) -> int:
+        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]:
@@ -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.2.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-3.2.0 → hookbase-4.0.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-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