hookbase 3.0.0__tar.gz → 3.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hookbase
-Version: 3.0.0
+Version: 3.2.0
 Summary: Official Python SDK for the Hookbase webhook management platform
 Project-URL: Homepage, https://hookbase.app
 Project-URL: Documentation, https://www.hookbase.app/docs/send/sdk
@@ -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"])
@@ -129,13 +148,17 @@ client.schemas.create({"name": "OrderSchema", "jsonSchema": {"type": "object", .
 
 ```python
 # Applications
-client.outbound.applications.create({"name": "Acme", "uid": "cust_123"})
+client.outbound.applications.create({"name": "Acme", "externalId": "cust_123"})
 client.outbound.applications.get_by_external_id("cust_123")
 
 # Endpoints
 client.outbound.endpoints.create("app_id", {"url": "https://..."})
 client.outbound.endpoints.rotate_secret("ep_id", grace_period=3600)
 
+# An unset field is left alone by an update, so `None` cannot also mean "reset
+# this". Name the setting in `clear` to send an explicit null for it:
+client.outbound.endpoints.update("ep_id", {"clear": ["retryDelays"]})
+
 # Event Types & Subscriptions
 client.outbound.event_types.create({"name": "order.created", "category": "orders"})
 client.outbound.subscriptions.create({"endpointId": "ep_id", "eventTypeId": "et_id"})
@@ -248,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.0.0 → hookbase-3.2.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"])
@@ -94,13 +113,17 @@ client.schemas.create({"name": "OrderSchema", "jsonSchema": {"type": "object", .
 
 ```python
 # Applications
-client.outbound.applications.create({"name": "Acme", "uid": "cust_123"})
+client.outbound.applications.create({"name": "Acme", "externalId": "cust_123"})
 client.outbound.applications.get_by_external_id("cust_123")
 
 # Endpoints
 client.outbound.endpoints.create("app_id", {"url": "https://..."})
 client.outbound.endpoints.rotate_secret("ep_id", grace_period=3600)
 
+# An unset field is left alone by an update, so `None` cannot also mean "reset
+# this". Name the setting in `clear` to send an explicit null for it:
+client.outbound.endpoints.update("ep_id", {"clear": ["retryDelays"]})
+
 # Event Types & Subscriptions
 client.outbound.event_types.create({"name": "order.created", "category": "orders"})
 client.outbound.subscriptions.create({"endpointId": "ep_id", "eventTypeId": "et_id"})
@@ -213,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.0.0 → hookbase-3.2.0}/examples/async_usage.py

@@ -29,7 +29,7 @@ async def main():
         # Paginate through all applications
         page = await client.outbound.applications.list(limit=10)
         async for app in page.auto_paging_iter():
-            print(f"  App: {app.name} (uid={app.uid})")
+            print(f"  App: {app.name} (externalId={app.external_id})")
 
 
 if __name__ == "__main__":

{hookbase-3.0.0 → hookbase-3.2.0}/examples/basic_inbound.py

@@ -21,7 +21,7 @@ dest = client.destinations.create({
     "slug": "backend",
     "url": "https://api.example.com/webhooks",
     "method": "POST",
-    "retryCount": 3,
+    "timeoutMs": 30000,
 })
 print(f"Destination created: {dest.id}")
 

{hookbase-3.0.0 → hookbase-3.2.0}/examples/send_webhooks.py

@@ -7,7 +7,7 @@ client = Hookbase(api_key="whr_your_api_key")
 # Create an application (represents a customer/tenant)
 app = client.outbound.applications.create({
     "name": "Acme Corp",
-    "uid": "cust_123",
+    "externalId": "cust_123",
     "metadata": {"plan": "pro"},
 })
 print(f"Application: {app.id}")

hookbase-3.2.0/src/hookbase/_version.py

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

{hookbase-3.0.0 → hookbase-3.2.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.0.0 → hookbase-3.2.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,
@@ -42,7 +52,11 @@ from .dlq import (
     DlqStats,
 )
 from .endpoints import (
+    CLEARABLE_ENDPOINT_FIELDS,
+    BackoffType,
+    ClearableEndpointField,
     CreateEndpointParams,
+    CustomHeader,
     EndpointStats,
     EndpointWithSecret,
     RotateSecretResult,
@@ -85,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,
@@ -115,6 +133,15 @@ __all__ = [
     "Application",
     "CreateApplicationParams",
     "UpdateApplicationParams",
+    # Catalog
+    "CatalogProvider",
+    "CatalogProviderDetail",
+    "ProviderCatalogList",
+    "ProviderEventType",
+    "ProviderEvents",
+    "ProviderSignatureVerification",
+    "ProviderSignatureVerificationSummary",
+    "ProviderVerifyTokenInfo",
     # Common
     "BulkDeleteResult",
     "ImportResult",
@@ -155,7 +182,11 @@ __all__ = [
     "DlqRetryResult",
     "DlqStats",
     # Endpoints
+    "CLEARABLE_ENDPOINT_FIELDS",
+    "BackoffType",
+    "ClearableEndpointField",
     "CreateEndpointParams",
+    "CustomHeader",
     "EndpointStats",
     "EndpointWithSecret",
     "RotateSecretResult",
@@ -203,9 +234,13 @@ __all__ = [
     "SchemaValidationResult",
     "UpdateSchemaParams",
     # Sources
+    "CLEARABLE_SOURCE_FIELDS",
+    "KNOWN_SOURCE_PROVIDERS",
+    "ClearableSourceField",
     "CreateSourceParams",
     "DedupStrategy",
     "IpFilterMode",
+    "PendingVerification",
     "Source",
     "SourceProvider",
     "SourceWithSecret",

hookbase-3.2.0/src/hookbase/models/_wire.py

@@ -0,0 +1,254 @@
+"""Normalization of request bodies onto the shapes the API actually accepts.
+
+The SDK has historically put field names on the wire that the API never
+accepted (endpoint `filterTypes`/`rateLimitPeriod`/`metadata`, destination
+`description`/`retryCount`/`retryInterval`) alongside a few it renamed
+(`rateLimit` -> `rateLimitPerSecond`, `timeout` -> `timeoutMs`, `uid` ->
+`externalId`). The API validates with `z.object()`, which silently strips
+unknown keys, so those requests came back 2xx with the field quietly ignored —
+and the resource configured differently from what the caller asked for. Those
+schemas are moving to `.strict()`, at which point the same requests become
+400s.
+
+Deleting the public fields would break callers, so the models keep them,
+document them as deprecated, and these helpers translate them at the wire
+boundary. They deliberately operate on the already-serialized body rather than
+on the model, so a caller who passes a plain dict — which every resource method
+accepts, and which skips model validation entirely — gets the same translation.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+from collections.abc import Iterable
+from typing import Any
+
+from ..errors import HookbaseError
+
+# Params models serialize through `to_camel`, but `populate_by_name` means a
+# caller may also use the snake_case field name, and a caller passing a plain
+# dict can put that spelling straight on the wire.
+_CAMEL_BOUNDARY = re.compile(r"(?<!^)(?=[A-Z])")
+
+# Slug derivation mirrors `deriveDestinationSlug` in
+# sdk/node-sdk/src/resources/wire.ts step for step, so all four SDKs derive
+# byte-identical slugs from the same name. Keep the two in sync.
+
+_SLUG_SEPARATORS = re.compile(r"[^a-z0-9]+")
+_SLUG_EDGE_HYPHENS = re.compile(r"^-+|-+$")
+_SLUG_TRAILING_HYPHENS = re.compile(r"-+$")
+SLUG_MAX_LENGTH = 50
+
+# Which characters count as combining marks is a function of the Unicode version the *runtime*
+# ships, and the four SDKs' runtimes do not agree: CPython 3.12's `unicodedata` is Unicode 15.0,
+# while the reference implementation's `\p{Mn}` (V8) is a version ahead. Reading the category alone
+# therefore makes the same name slug differently depending on which SDK created the destination,
+# which is the thing this derivation exists to prevent.
+#
+# These two tables close that gap, generated from the reference runtime's own `\p{Mn}` compared
+# against Unicode 15.0's. Both self-heal: once this interpreter's tables cover the additions, the
+# set is redundant but harmless, and `test_slug_contract.py` says so when that happens.
+#
+# 75 code points in 21 ranges, the same table `slugMarkAdditions` carries in
+# sdk/go-sdk/slug_fold.go. Change one and you change both.
+_SLUG_MARK_ADDITIONS: frozenset[str] = frozenset(
+    chr(cp)
+    for lo, hi in (
+        ("\u0897", "\u0897"),
+        ("\u1acf", "\u1add"),
+        ("\u1ae0", "\u1aeb"),
+        ("\U00010d69", "\U00010d6d"),
+        ("\U00010efa", "\U00010efc"),
+        ("\U000113bb", "\U000113c0"),
+        ("\U000113ce", "\U000113ce"),
+        ("\U000113d0", "\U000113d0"),
+        ("\U000113d2", "\U000113d2"),
+        ("\U000113e1", "\U000113e2"),
+        ("\U00011b60", "\U00011b60"),
+        ("\U00011b62", "\U00011b64"),
+        ("\U00011b66", "\U00011b66"),
+        ("\U00011f5a", "\U00011f5a"),
+        ("\U0001611e", "\U00016129"),
+        ("\U0001612d", "\U0001612f"),
+        ("\U0001e5ee", "\U0001e5ef"),
+        ("\U0001e6e3", "\U0001e6e3"),
+        ("\U0001e6e6", "\U0001e6e6"),
+        ("\U0001e6ee", "\U0001e6ef"),
+        ("\U0001e6f5", "\U0001e6f5"),
+    )
+    for cp in range(ord(lo), ord(hi) + 1)
+)
+
+# The correction in the other direction: AHOM CONSONANT SIGN MEDIAL RA was Mn in Unicode 15.0 and
+# is Mc (a *spacing* mark) from 15.1, so the reference does not strip it and neither may this
+# SDK -- it has to separate, the way any other non-alphanumeric does.
+_SLUG_MARK_RECLASSIFIED = "\U0001171e"
+
+
+# The same version skew, one layer down: NFKD itself. These characters are unassigned in Unicode
+# 15.0, so this interpreter leaves them alone and they become hyphen separators, while the
+# reference runtime decomposes them to ASCII letters and digits. Folding them first makes NFKD's
+# answer the same on both. Every mapping is the reference's own NFKD output, not a guess at the
+# character's meaning; a later interpreter that knows them decomposes them identically, so this
+# stays a no-op rather than a divergence of its own.
+#
+#   U+A7F1              Latin Extended-D, decomposes to "S"
+#   U+1CCD6 - U+1CCF9   36 contiguous additions in Symbols for Legacy Computing Supplement,
+#                       decomposing to A-Z and then 0-9 in order
+_SLUG_FOLD_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+_SLUG_FOLD_ADDITIONS = {
+    0xA7F1: "S",
+    **{0x1CCD6 + offset: char for offset, char in enumerate(_SLUG_FOLD_ALPHABET)},
+}
+
+
+def _is_slug_mark(char: str) -> bool:
+    """Whether `char` is a combining mark the slug fold drops. See the tables above."""
+    if char == _SLUG_MARK_RECLASSIFIED:
+        return False
+    return unicodedata.category(char) == "Mn" or char in _SLUG_MARK_ADDITIONS
+
+
+def dump(params: Any) -> dict[str, Any]:
+    """Serialize a params model into a wire body, or copy a caller's dict.
+
+    The copy matters: these helpers mutate the body in place and callers hand
+    us dicts they may reuse.
+    """
+    if hasattr(params, "model_dump"):
+        body: dict[str, Any] = params.model_dump(by_alias=True, exclude_none=True)
+        return body
+    return dict(params or {})
+
+
+def _spellings(key: str) -> tuple[str, ...]:
+    """Every spelling of one wire key a caller may have used."""
+    snake = _CAMEL_BOUNDARY.sub("_", key).lower()
+    return (key,) if snake == key else (key, snake)
+
+
+def drop(body: dict[str, Any], *keys: str) -> None:
+    """Remove keys the API never accepted."""
+    for key in keys:
+        for spelling in _spellings(key):
+            body.pop(spelling, None)
+
+
+def canonicalize(body: dict[str, Any], *keys: str) -> None:
+    """Move any snake_case spelling of `keys` onto its camelCase wire key."""
+    for key in keys:
+        for spelling in _spellings(key)[1:]:
+            if spelling in body:
+                body.setdefault(key, body.pop(spelling))
+
+
+def rename(body: dict[str, Any], old: str, new: str) -> None:
+    """Send `old`'s value under `new`; an explicit `new` wins over `old`."""
+    canonicalize(body, new)
+    value: Any = None
+    found = False
+    for spelling in _spellings(old):
+        if spelling in body:
+            if not found:
+                value = body[spelling]
+                found = True
+            del body[spelling]
+    if found and new not in body:
+        body[new] = value
+
+
+def apply_clear(body: dict[str, Any], allowed: tuple[str, ...], what: str) -> None:
+    """Turn a params model's `clear` list into explicit JSON nulls on the body.
+
+    Every optional field on every params model is `X | None = None`, and `dump`
+    excludes `None` -- so `None` means "leave this setting alone" and there is
+    nothing left to mean "reset it", even where the API accepts an explicit
+    null. A caller who had set a custom retry schedule could not remove it.
+
+    `clear` closes that: naming a field puts `null` on the wire for it. Only
+    the fields in `allowed` are accepted, and a field both set and cleared is
+    an error rather than a silent choice between the two. `clear` itself never
+    reaches the API.
+    """
+    requested: Any = None
+    for spelling in _spellings("clear"):
+        if spelling in body:
+            requested = body.pop(spelling)
+
+    if requested is None:
+        return
+    if isinstance(requested, str) or not isinstance(requested, Iterable):
+        raise HookbaseError(
+            f"`clear` takes a list of {what} field names, not {type(requested).__name__}."
+        )
+
+    for field in requested:
+        key = _CAMEL_BOUNDARY.sub("_", str(field)).lower()
+        wire = {_CAMEL_BOUNDARY.sub("_", name).lower(): name for name in allowed}.get(key)
+        if wire is None:
+            raise HookbaseError(
+                f"`clear` names {str(field)!r}, which is not one of the {what} fields the API "
+                f"accepts a null for. It accepts: {', '.join(sorted(allowed))}."
+            )
+        if wire in body:
+            raise HookbaseError(
+                f"`clear` names {str(field)!r} but that field is also set; clear it or set it, "
+                "not both."
+            )
+        body[wire] = None
+
+
+def headers_to_pairs(body: dict[str, Any]) -> None:
+    """Convert endpoint `headers` from a mapping to the array the API takes.
+
+    `POST`/`PATCH /api/webhook-endpoints` validate headers as
+    `z.array({name, value}).max(10)`, so the mapping the SDK has always typed
+    here is rejected outright — a 400 today rather than a silently stripped
+    field. A mapping is converted in insertion order; an array a caller built
+    themselves passes through untouched.
+    """
+    value = body.get("headers")
+    if isinstance(value, dict):
+        body["headers"] = [{"name": str(name), "value": str(v)} for name, v in value.items()]
+
+
+def derive_destination_slug(name: str) -> str:
+    """Derive a slug the API accepts (`^[a-z0-9-]+$`, max 50) from a name.
+
+    The API requires `slug` on create; this SDK has always had it optional, so
+    every call that left it out was a 400. Deriving one keeps those calls
+    working. Accents are folded first, so `Café EU` gives `cafe-eu` rather than
+    `caf-eu`.
+
+    Every step mirrors `deriveDestinationSlug` in the Node SDK
+    (sdk/node-sdk/src/resources/wire.ts) so all four SDKs agree byte for byte:
+    NFKD normalize, drop the combining marks the decomposition leaves behind,
+    lowercase, collapse each run of non-alphanumerics to one hyphen, trim the
+    ends, then cut to 50 characters. The cut is plain and may land mid-word —
+    that is what keeps the implementations identical, so do not trim back to a
+    word boundary — and can leave a trailing hyphen to remove.
+
+    Raises:
+        HookbaseError: if the name has no alphanumeric characters to derive
+            from, rather than sending a slug the API would reject.
+    """
+    # Drop the whole Mn category, not just the U+0300-U+036F block: a mark outside that block
+    # (Arabic, Hebrew, Devanagari) would otherwise survive to become a hyphen separator, and the
+    # same name would slug differently depending on which SDK created the destination.
+    # `_is_slug_mark` rather than the category alone, because the category answer depends on this
+    # interpreter's Unicode version -- see the tables above it.
+    decomposed = unicodedata.normalize("NFKD", name.translate(_SLUG_FOLD_ADDITIONS))
+    folded = "".join(ch for ch in decomposed if not _is_slug_mark(ch)).lower()
+    slug = _SLUG_EDGE_HYPHENS.sub("", _SLUG_SEPARATORS.sub("-", folded))
+    slug = _SLUG_TRAILING_HYPHENS.sub("", slug[:SLUG_MAX_LENGTH])
+
+    if not slug:
+        raise HookbaseError(
+            "Cannot derive a destination slug from name "
+            f"{json.dumps(name, ensure_ascii=False)}: pass "
+            "`slug` explicitly, as a string matching ^[a-z0-9-]+$ (max 50 characters)."
+        )
+
+    return slug

hookbase-3.2.0/src/hookbase/models/applications.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import model_validator
+
+from . import _wire
+from ._base import HookbaseModel
+
+
+class Application(HookbaseModel):
+    id: str
+    name: str
+    organization_id: str
+    external_id: str = ""
+    metadata: dict[str, Any] | None = None
+    created_at: str = ""
+    updated_at: str = ""
+
+    uid: str = ""
+    """Deprecated: the API calls this `externalId`; read `external_id` instead.
+    Kept in step with it so existing attribute access keeps working."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _mirror_external_id(cls, data: Any) -> Any:
+        """Keep `uid` and `external_id` showing the same value.
+
+        Application responses carry the field as `externalId`; `uid` is only
+        the SDK's older name for it, so populate both from whichever spelling
+        the response used. `externalId` is null for applications created
+        without one, so fall back to the empty string both fields default to.
+        """
+        if not isinstance(data, dict):
+            return data
+        value = data.get("externalId")
+        if value is None:
+            value = data.get("external_id")
+        if value is None:
+            value = data.get("uid")
+        return {**data, "externalId": value or "", "uid": value or ""}
+
+
+class CreateApplicationParams(HookbaseModel):
+    name: str
+    external_id: str | None = None
+    metadata: dict[str, Any] | None = None
+
+    uid: str | None = None
+    """Deprecated: renamed to `external_id`, which is the only name the API
+    accepts. The value is sent under that name, and `external_id` wins if both
+    are set."""
+
+
+class UpdateApplicationParams(HookbaseModel):
+    name: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+def application_body(params: CreateApplicationParams | dict[str, Any]) -> dict[str, Any]:
+    """Build the request body for an application create or upsert.
+
+    The API has always called the caller's own identifier `externalId`; the SDK
+    sent `uid`, which `z.object()` stripped, so every application the Python
+    SDK created came back with no external ID at all. Map the old name onto the
+    new one the way the Node SDK already does.
+    """
+    body = _wire.dump(params)
+    _wire.rename(body, "uid", "externalId")
+    return body