hookbase 3.1.0__tar.gz → 3.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hookbase
-Version: 3.1.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
@@ -98,7 +98,26 @@ 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")
+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
 
 # Destinations
 client.destinations.list()
@@ -111,7 +130,7 @@ client.routes.get_circuit_status("route_id")
 client.routes.reset_circuit("route_id")
 
 # Events & Deliveries
-client.events.list(source_id="src_id", from_date="2024-01-01")
+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.deliveries.replay("del_id")
 client.deliveries.bulk_replay(["del_1", "del_2"])
@@ -252,11 +271,14 @@ All responses are typed Pydantic models with camelCase alias support:
 from hookbase.models import Source, CreateSourceParams
 
 # Use Pydantic models for type safety
-params = CreateSourceParams(name="GitHub", provider="github")
+params = CreateSourceParams(name="GitHub", slug="github", provider="github")
 source = client.sources.create(params)
 
 # Or use plain dicts
-source = client.sources.create({"name": "GitHub", "provider": "github"})
+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.
 ```
 
 ## Development

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

@@ -63,7 +63,26 @@ 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")
+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
 
 # Destinations
 client.destinations.list()
@@ -76,7 +95,7 @@ client.routes.get_circuit_status("route_id")
 client.routes.reset_circuit("route_id")
 
 # Events & Deliveries
-client.events.list(source_id="src_id", from_date="2024-01-01")
+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.deliveries.replay("del_id")
 client.deliveries.bulk_replay(["del_1", "del_2"])
@@ -217,11 +236,14 @@ All responses are typed Pydantic models with camelCase alias support:
 from hookbase.models import Source, CreateSourceParams
 
 # Use Pydantic models for type safety
-params = CreateSourceParams(name="GitHub", provider="github")
+params = CreateSourceParams(name="GitHub", slug="github", provider="github")
 source = client.sources.create(params)
 
 # Or use plain dicts
-source = client.sources.create({"name": "GitHub", "provider": "github"})
+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.
 ```
 
 ## Development

{hookbase-3.1.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.1.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.1.0 → hookbase-3.3.0}/src/hookbase/client.py

@@ -26,6 +26,7 @@ from .resources import (
     AsyncMessages,
     AsyncOrganizations,
     AsyncPortalTokens,
+    AsyncProviders,
     AsyncRoutes,
     AsyncSchemas,
     AsyncSources,
@@ -43,6 +44,7 @@ from .resources import (
     Messages,
     Organizations,
     PortalTokens,
+    Providers,
     Routes,
     Schemas,
     Sources,
@@ -118,6 +120,8 @@ class Hookbase:
     transforms: Transforms
     filters: Filters
     schemas: Schemas
+    #: The public provider catalog (what each provider signs with, which secret it needs).
+    providers: Providers
 
     # Outbound
     outbound: _OutboundNamespace
@@ -160,6 +164,7 @@ class Hookbase:
         self.transforms = Transforms(self._transport)
         self.filters = Filters(self._transport)
         self.schemas = Schemas(self._transport)
+        self.providers = Providers(self._transport)
 
         # Outbound namespace
         self.outbound = _OutboundNamespace(self._transport)
@@ -210,6 +215,8 @@ class AsyncHookbase:
     transforms: AsyncTransforms
     filters: AsyncFilters
     schemas: AsyncSchemas
+    #: The public provider catalog (what each provider signs with, which secret it needs).
+    providers: AsyncProviders
 
     # Outbound
     outbound: _AsyncOutboundNamespace
@@ -252,6 +259,7 @@ class AsyncHookbase:
         self.transforms = AsyncTransforms(self._transport)
         self.filters = AsyncFilters(self._transport)
         self.schemas = AsyncSchemas(self._transport)
+        self.providers = AsyncProviders(self._transport)
 
         # Outbound namespace
         self.outbound = _AsyncOutboundNamespace(self._transport)

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

@@ -1,6 +1,16 @@
 from .analytics import AnalyticsTimeline, DashboardData
 from .api_keys import ApiKey, ApiKeyWithSecret, CreateApiKeyParams
 from .applications import Application, CreateApplicationParams, UpdateApplicationParams
+from .catalog import (
+    CatalogProvider,
+    CatalogProviderDetail,
+    ProviderCatalogList,
+    ProviderEvents,
+    ProviderEventType,
+    ProviderSignatureVerification,
+    ProviderSignatureVerificationSummary,
+    ProviderVerifyTokenInfo,
+)
 from .common import BulkDeleteResult, ImportResult, ImportResultItem
 from .cron_jobs import (
     CreateCronGroupParams,
@@ -89,9 +99,13 @@ from .routes import (
 )
 from .schemas import CreateSchemaParams, Schema, SchemaValidationResult, UpdateSchemaParams
 from .sources import (
+    CLEARABLE_SOURCE_FIELDS,
+    KNOWN_SOURCE_PROVIDERS,
+    ClearableSourceField,
     CreateSourceParams,
     DedupStrategy,
     IpFilterMode,
+    PendingVerification,
     Source,
     SourceProvider,
     SourceWithSecret,
@@ -119,6 +133,15 @@ __all__ = [
     "Application",
     "CreateApplicationParams",
     "UpdateApplicationParams",
+    # Catalog
+    "CatalogProvider",
+    "CatalogProviderDetail",
+    "ProviderCatalogList",
+    "ProviderEventType",
+    "ProviderEvents",
+    "ProviderSignatureVerification",
+    "ProviderSignatureVerificationSummary",
+    "ProviderVerifyTokenInfo",
     # Common
     "BulkDeleteResult",
     "ImportResult",
@@ -211,9 +234,13 @@ __all__ = [
     "SchemaValidationResult",
     "UpdateSchemaParams",
     # Sources
+    "CLEARABLE_SOURCE_FIELDS",
+    "KNOWN_SOURCE_PROVIDERS",
+    "ClearableSourceField",
     "CreateSourceParams",
     "DedupStrategy",
     "IpFilterMode",
+    "PendingVerification",
     "Source",
     "SourceProvider",
     "SourceWithSecret",

{hookbase-3.1.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/catalog.py

@@ -0,0 +1,120 @@
+"""The public provider catalog: GET /api/catalog/providers (no authentication needed).
+
+Every enumerated value here (category, kind, secret_source, secret_format) is a plain string
+rather than a Literal, for the reason ``SourceProvider`` is: the catalog grows server-side, and a
+value this package has not heard of must not make the whole response fail to parse.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import field_validator
+
+from ._base import HookbaseModel
+
+
+class ProviderEventType(HookbaseModel):
+    type: str
+    description: str = ""
+
+
+class ProviderVerifyTokenInfo(HookbaseModel):
+    """Meta's second, Hookbase-generated credential (see SourceWithSecret.verify_token)."""
+
+    label: str
+    instruction: str = ""
+
+
+class ProviderSignatureVerificationSummary(HookbaseModel):
+    """The secret fields a create flow needs, as the catalog list carries them.
+
+    ``secret_source`` says who produces the credential: "provider" (the vendor issues it; paste
+    it as signing_secret), "operator" (Hookbase generates it when omitted; paste it into the
+    vendor), "public_key" (paste the vendor's public key), "built_in" (nothing to enter; events
+    are still verified) or "none" (the vendor does not sign).
+    """
+
+    supported: bool = False
+    #: The scheme kind: "hmac", "shared_secret", "bespoke" or "asymmetric". None when no scheme.
+    kind: str | None = None
+    secret_source: str | None = None
+    secret_label: str | None = None
+    secret_placeholder: str | None = None
+    #: The vendor issues the secret only after the source's URL is registered with it.
+    secret_after_registration: bool = False
+
+
+class ProviderSignatureVerification(ProviderSignatureVerificationSummary):
+    """The full block from the provider detail call."""
+
+    algorithm: str | None = None
+    header_name: str | None = None
+    secret_location_hint: str | None = None
+    #: One sentence on where the value comes from or goes, in the vendor's own UI wording.
+    secret_instruction: str | None = None
+    #: "whsec" or "basic_auth" when the value has a required shape.
+    secret_format: str | None = None
+    #: Present for Meta providers, which also use a verify token.
+    verify_token: ProviderVerifyTokenInfo | None = None
+
+
+class CatalogProvider(HookbaseModel):
+    """A provider as the catalog list returns it.
+
+    ``id`` is the catalog's id; ``hookbase_provider`` is the value to use as a source's
+    ``provider``. They differ for some entries (catalog "mollie-nextgen" is provider "mollie",
+    and several catalog entries map to "custom").
+    """
+
+    id: str
+    name: str
+    category: str = ""
+    description: str = ""
+    icon: str | None = None
+    event_type_count: int = 0
+    hookbase_provider: str = ""
+    has_signature_verification: bool = False
+    has_ip_ranges: bool = False
+    #: None when the provider has no verification block, and also from API versions that
+    #: predate this summary on list items: fall back to client.providers.get(id) for it.
+    signature_verification: ProviderSignatureVerificationSummary | None = None
+
+
+class ProviderCatalogList(HookbaseModel):
+    providers: list[CatalogProvider] = []
+    categories: list[str] = []
+    total: int = 0
+
+
+class CatalogProviderDetail(HookbaseModel):
+    """One provider in full, from GET /api/catalog/providers/:id."""
+
+    id: str
+    name: str
+    category: str = ""
+    description: str = ""
+    website: str | None = None
+    docs_url: str | None = None
+    icon: str | None = None
+    hookbase_provider: str = ""
+    signature_verification: ProviderSignatureVerification | None = None
+    event_types: list[ProviderEventType] = []
+    #: Example payloads keyed by event type.
+    sample_payloads: dict[str, Any] = {}
+    ip_ranges: list[str] | None = None
+    setup_guide: list[str] = []
+
+    @field_validator("event_types", "setup_guide", mode="before")
+    @classmethod
+    def _none_to_list(cls, v: Any) -> Any:
+        return [] if v is None else v
+
+
+class ProviderEvents(HookbaseModel):
+    """GET /api/catalog/providers/:id/events."""
+
+    provider_id: str
+    provider_name: str = ""
+    event_types: list[ProviderEventType] = []
+    sample_payloads: 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"})