hookbase 2.8.0__tar.gz → 3.0.0__tar.gz

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

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

hookbase-3.0.0/src/hookbase/_version.py

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

hookbase-3.0.0/src/hookbase/models/sources.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+from pydantic import field_validator
+
+from ._base import HookbaseModel
+
+# Providers the API will accept for a source.
+#
+# Mirrors SUPPORTED_SIGNATURE_PROVIDERS in the API (api/src/utils/signature-schemes.ts), which
+# is derived from the signature scheme table rather than restated. Regenerate with
+# `npx tsx scripts/print-source-enums.ts` in the api package; do not hand-extend this Literal,
+# because a value the API does not accept is a 400 the type promised would not happen.
+#
+# Removed in the 2026-09 correction: "sendgrid", "mailgun" and "linear". All three were
+# advertised here from the beginning and none was ever accepted by the API. SendGrid signs with
+# ECDSA and Mailgun puts the signature in the POST body, so neither fits this scheme model;
+# Linear's scheme is real but unverified against its docs. Use "custom" for all three.
+#
+# "svix" is an alias of "standard-webhooks"; both resolve to the same scheme server-side.
+SourceProvider = Literal[
+    "airtable", "asana", "bitbucket", "calendly", "custom", "generic",
+    "github", "gitlab", "heroku", "intercom", "lemonsqueezy", "notion",
+    "paddle", "razorpay", "sentry", "shopify", "slack", "standard-webhooks",
+    "stripe", "svix", "twilio", "typeform", "workos", "zoom",
+]
+# Corrected alongside SourceProvider: "header" and "event_id" were never accepted, and the three
+# values the API actually defaults to and documents were missing. "auto" is the default.
+DedupStrategy = Literal["auto", "provider_id", "payload_hash", "idempotency_key", "none"]
+IpFilterMode = Literal["none", "allowlist", "denylist", "both"]
+# HTTP verbs an ingest endpoint can be restricted to. OPTIONS is excluded: CORS preflight is
+# answered before ingest runs, so it is never gateable.
+IngestMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]
+
+
+class Source(HookbaseModel):
+    """A source as the API returns it.
+
+    The signing secret is not included. Responses carry ``has_signing_secret`` and the last four
+    characters; the full value comes back exactly twice, from :meth:`Sources.create` (which
+    returns a :class:`SourceWithSecret`) and from :meth:`Sources.reveal_secret`.
+    """
+
+    id: str
+    organization_id: str | None = None
+    name: str
+    slug: str
+    provider: SourceProvider | None = None
+    description: str | None = None
+    #: Whether a signing secret is set. The secret itself is not returned here.
+    has_signing_secret: bool = False
+    #: Last four characters of the signing secret, prefixed with "...", or None if unset.
+    signing_secret_last4: str | None = None
+    #: Reject events whose signature fails verification. Defaults to False, in which case a
+    #: failing event is flagged with signature_valid=False and delivered anyway.
+    reject_invalid_signatures: bool = False
+    rate_limit_per_minute: int | None = None
+    is_active: bool = True
+    custom_domain_id: str | None = None
+    ip_filter_mode: IpFilterMode = "none"
+    ip_allowlist: list[str] = []
+    ip_denylist: list[str] = []
+    #: JSONPath expressions whose values are encrypted at rest.
+    encrypt_fields: list[str] = []
+    #: JSONPath expressions whose values are masked in stored payloads.
+    mask_fields: list[str] = []
+    dedup_enabled: bool = False
+    dedup_strategy: DedupStrategy = "auto"
+    dedup_window_hours: int = 24
+    dedup_custom_header: str | None = None
+    transient_mode: bool = False
+    #: HTTP verbs the ingest endpoint accepts. Empty list means any method.
+    allowed_methods: list[str] = []
+    event_count: int = 0
+    route_count: int = 0
+    #: Returned by get() and create(). Not included in list() responses.
+    ingest_url: str | None = None
+    created_at: str = ""
+    updated_at: str = ""
+
+    @field_validator(
+        "is_active",
+        "reject_invalid_signatures",
+        "has_signing_secret",
+        "dedup_enabled",
+        "transient_mode",
+        mode="before",
+    )
+    @classmethod
+    def parse_bool_from_int(cls, v: Any) -> Any:
+        if isinstance(v, int):
+            return bool(v)
+        return v
+
+    @field_validator(
+        "ip_allowlist", "ip_denylist", "encrypt_fields", "mask_fields", mode="before"
+    )
+    @classmethod
+    def parse_json_list(cls, v: Any) -> Any:
+        if v is None:
+            return []
+        if isinstance(v, str):
+            try:
+                parsed = json.loads(v)
+                return parsed if isinstance(parsed, list) else []
+            except (json.JSONDecodeError, ValueError):
+                return []
+        return v
+
+    @field_validator("allowed_methods", mode="before")
+    @classmethod
+    def parse_allowed_methods(cls, v: Any) -> Any:
+        """Coerce null/JSON-string forms to a list; both mean "any method" when empty."""
+        if v is None:
+            return []
+        if isinstance(v, str):
+            try:
+                parsed = json.loads(v)
+                return parsed if isinstance(parsed, list) else []
+            except (json.JSONDecodeError, ValueError):
+                return []
+        return v
+
+
+class SourceWithSecret(Source):
+    """What create() returns: a source plus the one look at its signing secret you get."""
+
+    signing_secret: str = ""
+
+
+class CreateSourceParams(HookbaseModel):
+    name: str
+    #: Required: it forms the ingest URL, /ingest/<org>/<slug>, and cannot be changed later.
+    slug: str
+    provider: SourceProvider | None = None
+    description: str | None = None
+    #: Supply your own secret to match what the provider is already configured with. Omit it and
+    #: the API generates one, returned once on the created source.
+    signing_secret: str | None = None
+    #: Reject events whose signature fails verification. Defaults to False.
+    reject_invalid_signatures: bool | None = None
+    rate_limit_per_minute: int | None = None
+    ip_filter_mode: IpFilterMode | None = None
+    ip_allowlist: list[str] | None = None
+    ip_denylist: list[str] | None = None
+    encrypt_fields: list[str] | None = None
+    mask_fields: list[str] | None = None
+    dedup_enabled: bool | None = None
+    dedup_strategy: DedupStrategy | None = None
+    #: Deduplication window in hours, 1 to 168.
+    dedup_window_hours: int | None = None
+    #: Header to deduplicate on when dedup_strategy is "idempotency_key".
+    dedup_custom_header: str | None = None
+    transient_mode: bool | None = None
+    #: Restrict the ingest endpoint to these verbs. None/[] accepts any method.
+    allowed_methods: list[IngestMethod] | None = None
+
+
+class UpdateSourceParams(HookbaseModel):
+    name: str | None = None
+    description: str | None = None
+    provider: SourceProvider | None = None
+    is_active: bool | None = None
+    signing_secret: str | None = None
+    reject_invalid_signatures: bool | None = None
+    rate_limit_per_minute: int | None = None
+    ip_filter_mode: IpFilterMode | None = None
+    ip_allowlist: list[str] | None = None
+    ip_denylist: list[str] | None = None
+    encrypt_fields: list[str] | None = None
+    mask_fields: list[str] | None = None
+    dedup_enabled: bool | None = None
+    dedup_strategy: DedupStrategy | None = None
+    dedup_window_hours: int | None = None
+    dedup_custom_header: str | None = None
+    transient_mode: bool | None = None
+    #: Restrict the ingest endpoint to these verbs. Pass [] to accept any method again.
+    allowed_methods: list[IngestMethod] | None = None

hookbase-3.0.0/tests/resources/test_source_fields.py

@@ -0,0 +1,105 @@
+"""The field names this SDK puts on the wire, as POST/PATCH /api/sources accept them.
+
+These lists exist because they were wrong for months and nothing said so. The models named
+``verify_signature``, ``dedup_window``, ``dedup_header_name``, ``rate_limit`` and
+``rate_limit_window``, which the camelCase alias generator sent as ``verifySignature`` and
+friends. The API's create schema was a plain zod object, which strips unknown keys rather than
+refusing them, so every one of those calls returned 201 having quietly dropped the setting: a
+source created with ``verify_signature=True`` came back with verification off and raised no error.
+
+The create schema is strict now, so a stale name is a 400 rather than a silent drop — which is why
+a rename here has to be deliberate.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from hookbase.models.sources import (
+    CreateSourceParams,
+    Source,
+    SourceWithSecret,
+    UpdateSourceParams,
+)
+
+CREATE_FIELDS = {
+    "name", "slug", "provider", "description", "signingSecret",
+    "rejectInvalidSignatures", "rateLimitPerMinute", "ipFilterMode", "ipAllowlist",
+    "ipDenylist", "encryptFields", "maskFields", "dedupEnabled", "dedupStrategy",
+    "dedupWindowHours", "dedupCustomHeader", "transientMode", "allowedMethods",
+}
+
+UPDATE_FIELDS = (CREATE_FIELDS - {"slug"}) | {"isActive"}
+
+
+def _aliases(model: type) -> set[str]:
+    return {f.alias or name for name, f in model.model_fields.items()}
+
+
+def test_create_params_send_exactly_the_accepted_fields() -> None:
+    assert _aliases(CreateSourceParams) == CREATE_FIELDS
+
+
+def test_update_params_send_exactly_the_accepted_fields() -> None:
+    assert _aliases(UpdateSourceParams) == UPDATE_FIELDS
+
+
+def test_create_and_update_differ_only_by_slug_and_is_active() -> None:
+    create, update = _aliases(CreateSourceParams), _aliases(UpdateSourceParams)
+    assert create - update == {"slug"}
+    assert update - create == {"isActive"}
+
+
+def test_slug_is_required_on_create() -> None:
+    """slug forms the ingest URL and cannot be changed afterwards, so create demands it."""
+    with pytest.raises(ValidationError, match="slug"):
+        CreateSourceParams(name="No slug")
+
+
+def test_a_full_create_serializes_every_field_under_its_wire_name() -> None:
+    params = CreateSourceParams(
+        name="Stripe Production",
+        slug="stripe",
+        provider="stripe",
+        description="Live charge events",
+        signing_secret="whsec_abc",
+        reject_invalid_signatures=True,
+        rate_limit_per_minute=600,
+        ip_filter_mode="allowlist",
+        ip_allowlist=["203.0.113.0/24"],
+        ip_denylist=[],
+        encrypt_fields=["$.data.object.customer_email"],
+        mask_fields=["$.data.object.last4"],
+        dedup_enabled=True,
+        dedup_strategy="provider_id",
+        dedup_window_hours=24,
+        dedup_custom_header="X-Idempotency-Key",
+        transient_mode=False,
+        allowed_methods=["POST"],
+    )
+    assert set(params.model_dump(by_alias=True, exclude_none=True)) == CREATE_FIELDS
+
+
+def test_a_listed_source_carries_the_masked_pair_not_the_secret() -> None:
+    src = Source(
+        id="src_1", name="Stripe", slug="stripe",
+        hasSigningSecret=True, signingSecretLast4="...c123",
+        rejectInvalidSignatures=True, dedupWindowHours=24, routeCount=3,
+    )
+    assert src.has_signing_secret is True
+    assert src.signing_secret_last4 == "...c123"
+    assert src.reject_invalid_signatures is True
+    assert src.dedup_window_hours == 24
+    assert src.route_count == 3
+    assert not hasattr(src, "signing_secret")
+
+
+def test_a_created_source_carries_the_secret_and_the_ingest_url() -> None:
+    created = SourceWithSecret(
+        id="src_1", name="Stripe", slug="stripe",
+        signingSecret="whsec_abc",
+        ingestUrl="https://api.hookbase.app/ingest/acme/stripe",
+    )
+    assert created.signing_secret == "whsec_abc"
+    assert created.ingest_url is not None and "/ingest/" in created.ingest_url

{hookbase-2.8.0 → hookbase-3.0.0}/tests/resources/test_sources.py

@@ -30,10 +30,13 @@ SOURCE_DATA = {
     "slug": "github",
     "provider": "github",
     "isActive": True,
-    "verifySignature": True,
+    "hasSigningSecret": True,
+    "signingSecretLast4": "...c123",
+    "rejectInvalidSignatures": True,
     "dedupStrategy": "none",
     "ipFilterMode": "none",
     "eventCount": 42,
+    "routeCount": 3,
     "createdAt": "2024-01-01T00:00:00Z",
     "updatedAt": "2024-01-01T00:00:00Z",
 }
@@ -158,7 +161,7 @@ def test_create_source_with_transient_mode(mock_api, client):
 
 
 def test_create_source_params_serialization():
-    params = CreateSourceParams(name="test", transient_mode=True)
+    params = CreateSourceParams(name="test", slug="test", transient_mode=True)
     dumped = params.model_dump(by_alias=True, exclude_none=True)
     assert dumped["transientMode"] is True
 
@@ -227,7 +230,7 @@ def test_source_allowed_methods_malformed_fails_open():
 
 
 def test_create_source_params_serializes_allowed_methods():
-    params = CreateSourceParams(name="s", allowed_methods=["GET", "POST"])
+    params = CreateSourceParams(name="s", slug="s", allowed_methods=["GET", "POST"])
     assert params.model_dump(by_alias=True, exclude_none=True)["allowedMethods"] == ["GET", "POST"]
 
 

hookbase-2.8.0/src/hookbase/_version.py

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

hookbase-2.8.0/src/hookbase/models/sources.py

@@ -1,119 +0,0 @@
-from __future__ import annotations
-
-import json
-from typing import Any, Literal
-
-from pydantic import field_validator
-
-from ._base import HookbaseModel
-
-SourceProvider = Literal[
-    "generic", "github", "stripe", "shopify", "slack", "twilio",
-    "sendgrid", "mailgun", "paddle", "linear", "svix", "custom",
-]
-DedupStrategy = Literal["none", "header", "payload_hash", "event_id"]
-IpFilterMode = Literal["none", "allowlist", "denylist"]
-# HTTP verbs an ingest endpoint can be restricted to. OPTIONS is excluded: CORS preflight is
-# answered before ingest runs, so it is never gateable.
-IngestMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]
-
-
-class Source(HookbaseModel):
-    id: str
-    organization_id: str | None = None
-    name: str
-    slug: str
-    description: str | None = None
-    provider: SourceProvider = "generic"
-    is_active: bool = True
-    signing_secret: str | None = None
-    ingest_url: str | None = None
-    verify_signature: bool = False
-    dedup_strategy: str | None = "none"
-    dedup_window: int | None = None
-    dedup_header_name: str | None = None
-    ip_filter_mode: IpFilterMode = "none"
-    ip_allowlist: list[str] | None = None
-    ip_denylist: list[str] | None = None
-    rate_limit: int | None = None
-    rate_limit_window: int | None = None
-    transient_mode: bool = False
-    #: HTTP verbs the ingest endpoint accepts. Empty list means any method.
-    allowed_methods: list[str] = []
-    event_count: int = 0
-    last_event_at: str | None = None
-    created_at: str = ""
-    updated_at: str = ""
-
-    @field_validator("is_active", "verify_signature", "transient_mode", mode="before")
-    @classmethod
-    def parse_bool_from_int(cls, v: Any) -> Any:
-        if isinstance(v, int):
-            return bool(v)
-        return v
-
-    @field_validator("ip_allowlist", "ip_denylist", mode="before")
-    @classmethod
-    def parse_json_list(cls, v: Any) -> Any:
-        if isinstance(v, str):
-            try:
-                parsed = json.loads(v)
-                return parsed if isinstance(parsed, list) else None
-            except (json.JSONDecodeError, ValueError):
-                return None
-        return v
-
-    @field_validator("allowed_methods", mode="before")
-    @classmethod
-    def parse_allowed_methods(cls, v: Any) -> Any:
-        """Coerce null/JSON-string forms to a list; both mean "any method" when empty."""
-        if v is None:
-            return []
-        if isinstance(v, str):
-            try:
-                parsed = json.loads(v)
-                return parsed if isinstance(parsed, list) else []
-            except (json.JSONDecodeError, ValueError):
-                return []
-        return v
-
-
-class SourceWithSecret(Source):
-    signing_secret: str = ""
-
-
-class CreateSourceParams(HookbaseModel):
-    name: str
-    slug: str | None = None
-    description: str | None = None
-    provider: SourceProvider | None = None
-    verify_signature: bool | None = None
-    dedup_strategy: DedupStrategy | None = None
-    dedup_window: int | None = None
-    dedup_header_name: str | None = None
-    ip_filter_mode: IpFilterMode | None = None
-    ip_allowlist: list[str] | None = None
-    ip_denylist: list[str] | None = None
-    rate_limit: int | None = None
-    rate_limit_window: int | None = None
-    transient_mode: bool | None = None
-    #: Restrict the ingest endpoint to these verbs. None/[] accepts any method.
-    allowed_methods: list[IngestMethod] | None = None
-
-
-class UpdateSourceParams(HookbaseModel):
-    name: str | None = None
-    description: str | None = None
-    is_active: bool | None = None
-    verify_signature: bool | None = None
-    dedup_strategy: DedupStrategy | None = None
-    dedup_window: int | None = None
-    dedup_header_name: str | None = None
-    ip_filter_mode: IpFilterMode | None = None
-    ip_allowlist: list[str] | None = None
-    ip_denylist: list[str] | None = None
-    rate_limit: int | None = None
-    rate_limit_window: int | None = None
-    transient_mode: bool | None = None
-    #: Restrict the ingest endpoint to these verbs. Pass [] to accept any method again.
-    allowed_methods: list[IngestMethod] | None = None