webhook-co 0.2.0__tar.gz → 0.3.0__tar.gz

{webhook_co-0.2.0 → webhook_co-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webhook-co
-Version: 0.2.0
+Version: 0.3.0
 Summary: The official Python SDK for the webhook.co API — a typed client with retries, cursor pagination, idempotency, and secret redaction.
 Project-URL: Homepage, https://webhook.co
 Project-URL: Repository, https://github.com/webhook-co/webhook

{webhook_co-0.2.0 → webhook_co-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webhook-co"
-version = "0.2.0"
+version = "0.3.0"
 description = "The official Python SDK for the webhook.co API — a typed client with retries, cursor pagination, idempotency, and secret redaction."
 readme = "README.md"
 requires-python = ">=3.10"

webhook_co-0.3.0/scripts/packaged_smoke.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""PACKAGED-ARTIFACT SMOKE TEST for the Python SDK.
+
+The pytest suite imports from ``src/``. That proves the CODE works; it proves NOTHING about the WHEEL users
+actually install — a missing package in ``[tool.hatch.build]``, an absent ``py.typed``, or a module that
+never made it into the archive all ship green, because no test touches the built artifact.
+
+So: build the real wheel, install it into a throwaway venv, import it as a user would, and drive it against
+a live stub server. If the published artifact is unusable, this fails.
+
+Run:  python scripts/packaged_smoke.py    (from sdks/python)
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+import shutil
+import subprocess
+import sys
+import tempfile
+
+HERE = pathlib.Path(__file__).resolve().parent
+PKG = HERE.parent
+
+# The client script that runs INSIDE the throwaway venv, against the installed wheel.
+CLIENT = r"""
+import json, threading, sys
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from webhook_co import WebhookClient
+
+# A faithful trigger event: the SDK validates responses through pydantic, so a thin stub is (correctly)
+# rejected. That strictness is a feature — the SDK will not hand you a half-parsed event.
+EVENT = {
+    "id": "11111111-1111-4111-8111-111111111111",
+    "orgId": "22222222-2222-4222-8222-222222222222",
+    "endpointId": "11111111-1111-4111-8111-111111111111",
+    "receivedAt": "2026-07-13T00:00:00Z",
+    "provider": "stripe",
+    "dedupKey": "dk",
+    "dedupStrategy": "content_hash",
+    "verified": True,
+    "vouched": True,
+}
+CALLS = []
+
+class H(BaseHTTPRequestHandler):
+    def log_message(self, *a):
+        pass
+
+    def _send(self, obj):
+        b = json.dumps(obj).encode()
+        self.send_response(200)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(b)))
+        self.end_headers()
+        self.wfile.write(b)
+
+    def _handle(self):
+        n = int(self.headers.get("content-length") or 0)
+        if n:
+            self.rfile.read(n)
+        CALLS.append({"method": self.command, "path": self.path, "auth": self.headers.get("authorization")})
+        path, _, qs = self.path.partition("?")
+        q = dict(p.split("=", 1) for p in qs.split("&") if "=" in p)
+        if path == "/v1/endpoints" and self.command == "POST":
+            return self._send({
+                "id": "11111111-1111-4111-8111-111111111111",
+                "orgId": "22222222-2222-4222-8222-222222222222",
+                "name": "orders", "paused": False, "createdAt": "2026-07-13T00:00:00Z",
+                "dedupConfig": None, "ingestUrl": "https://wbhk.my/whep_SEALED",
+            })
+        if path.endswith("/reveal-ingest-url"):
+            return self._send({"ingestUrl": "https://wbhk.my/whep_SEALED"})
+        if path == "/v1/usage":
+            return self._send({
+                "periodStart": "2026-07-01T00:00:00Z", "periodEnd": None, "capKind": "lifetime",
+                "events": 42, "eventCap": 5000, "pausePolicy": "pause", "paused": False,
+            })
+        if path.endswith("/wait"):
+            # Faithful to the server: a page WITH events returns a fresh cursor; an EMPTY page ECHOES the
+            # cursor you sent; null only when you sent none. So null means "from the oldest", not "caught up".
+            cur = q.get("cursor")
+            if cur is None:
+                return self._send({"events": [EVENT], "nextCursor": "c1", "caughtUp": False})
+            return self._send({"events": [], "nextCursor": cur, "caughtUp": True})
+        if path == "/v1/triggers" and self.command == "POST":
+            return self._send({
+                "id": "11111111-1111-4111-8111-111111111111",
+                "orgId": "22222222-2222-4222-8222-222222222222",
+                "endpointId": "11111111-1111-4111-8111-111111111111",
+                "name": None, "createdAt": "2026-07-13T00:00:00Z", "revokedAt": None,
+            })
+        self._send({})
+
+    do_GET = do_POST = do_PATCH = do_DELETE = _handle
+
+srv = HTTPServer(("127.0.0.1", 0), H)
+threading.Thread(target=srv.serve_forever, daemon=True).start()
+client = WebhookClient(api_key="whk_smoke_test_key_abcdefgh", base_url=f"http://127.0.0.1:{srv.server_address[1]}")
+
+fails = []
+def check(name, cond, extra=""):
+    print(f"  {'PASS' if cond else 'FAIL'}  {name}" + ("" if cond else f"  <- {extra}"))
+    if not cond:
+        fails.append(name)
+
+import webhook_co
+check("the installed wheel imports and exposes WebhookClient", callable(WebhookClient))
+
+ep = client.endpoints.create(name="orders")
+check("endpoints.create returns the ingest url", str(ep.ingest_url) == "https://wbhk.my/whep_SEALED", ep.ingest_url)
+
+rev = client.endpoints.reveal_ingest_url(ep.id)
+check("endpoints.reveal_ingest_url recovers the SAME url (no rotation)", str(rev.ingest_url) == str(ep.ingest_url))
+
+check("usage.get works", client.usage.get().events == 42)
+
+trig = client.triggers.create(endpoint_id=ep.id)
+cursor, seen = None, []
+for _ in range(3):
+    page = client.triggers.wait(trig.id, cursor=cursor)
+    seen.extend(page.events)
+    cursor = page.next_cursor
+check("triggers.wait drains events and terminates", len(seen) == 1, len(seen))
+
+waits = [c for c in CALLS if "/wait" in c["path"]]
+check("triggers.wait never sends a literal null cursor",
+      not any("cursor=None" in c["path"] or "cursor=null" in c["path"] for c in waits),
+      [c["path"] for c in waits])
+
+client.triggers.wait(trig.id, include_body=False)
+last = [c for c in CALLS if "/wait" in c["path"]][-1]
+check("include_body=False serialises lowercase (the API silently ignores 'False')",
+      "includeBody=false" in last["path"], last["path"])
+
+reveal = next(c for c in CALLS if "reveal-ingest-url" in c["path"])
+check("reveal is a POST carrying the bearer",
+      reveal["method"] == "POST" and reveal["auth"] == "Bearer whk_smoke_test_key_abcdefgh")
+
+srv.shutdown()
+print("\npackaged Python SDK: ALL PASS" if not fails else f"\npackaged Python SDK: {len(fails)} FAILURE(S)")
+sys.exit(1 if fails else 0)
+"""
+
+
+def main() -> int:
+    scratch = pathlib.Path(tempfile.mkdtemp(prefix="py-sdk-smoke-"))
+    try:
+        print("building the real wheel …")
+        subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "pip",
+                "wheel",
+                "--no-deps",
+                "-w",
+                str(scratch),
+                str(PKG),
+            ],
+            check=True,
+            stdout=subprocess.DEVNULL,
+        )
+        wheel = next(scratch.glob("webhook_co-*.whl"))
+
+        print(f"installing {wheel.name} into a throwaway venv …")
+        venv = scratch / "venv"
+        subprocess.run([sys.executable, "-m", "venv", str(venv)], check=True)
+        py = venv / "bin" / "python"
+        subprocess.run([str(py), "-m", "pip", "-q", "install", str(wheel)], check=True)
+
+        script = scratch / "smoke.py"
+        script.write_text(CLIENT)
+        # cwd=scratch so `webhook_co` can only resolve from the INSTALLED WHEEL, never from ../src.
+        return subprocess.run([str(py), str(script)], cwd=scratch).returncode
+    finally:
+        shutil.rmtree(scratch, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

webhook_co-0.3.0/src/webhook_co/_advisory.py

@@ -0,0 +1,133 @@
+"""CLIENT VERSION ADVISORIES (receiving end) + the versioned User-Agent.
+
+The SDK identifies itself in its User-Agent; when this version is behind, the API answers with an
+``x-webhook-advisory`` header ON A RESPONSE THE CALLER ALREADY ASKED FOR. So the SDK never polls PyPI,
+never makes an unsolicited network call from inside your Lambda, and works fine offline — you simply hear
+nothing.
+
+House rules for surfacing it, because a library that nags is a library people vendor to shut it up:
+  - report ONCE per client, not once per request;
+  - prefer the caller's own handler; only fall back to a single ``warnings`` emission;
+  - be silenceable, and never break a request if any of this goes wrong.
+"""
+
+from __future__ import annotations
+
+import platform
+import re
+import sys
+import warnings
+from dataclasses import dataclass
+from typing import Callable
+
+ADVISORY_HEADER = "x-webhook-advisory"
+DEPRECATION_HEADER = "deprecation"
+
+
+def _sdk_version() -> str:
+    """The installed version, read from package metadata.
+
+    Unlike the TS and Go SDKs, Python does not need a stamped constant: the wheel's own metadata IS the
+    version, so the User-Agent physically cannot disagree with what is installed. Falls back to 0.0.0 when
+    running from a source tree with no metadata (a dev checkout).
+    """
+    try:
+        from importlib.metadata import version
+
+        return version("webhook-co")
+    except (
+        Exception
+    ):  # pragma: no cover - defensive: never let identifying ourselves break a request
+        return "0.0.0"
+
+
+SDK_VERSION = _sdk_version()
+
+
+def user_agent() -> str:
+    """``webhook-co-python/0.2.1 (python/3.12.3; darwin)`` — client, version, runtime. Nothing about you."""
+    try:
+        py = platform.python_version()
+        os_name = sys.platform
+        return f"webhook-co-python/{SDK_VERSION} (python/{py}; {os_name})"
+    except Exception:  # pragma: no cover
+        return f"webhook-co-python/{SDK_VERSION}"
+
+
+@dataclass(frozen=True)
+class WebhookAdvisory:
+    """A version advisory from the server. ``deprecated`` = BELOW the supported floor: broken, not just old."""
+
+    deprecated: bool
+    current: str
+    latest: str
+    message: str
+
+
+_KIND = re.compile(
+    r"^(update-available|deprecated);\s*current=([\w.+-]+);\s*latest=([\w.+-]+)$"
+)
+
+
+def parse_advisory(
+    header: str | None, deprecation: str | None
+) -> WebhookAdvisory | None:
+    """Parse the advisory header. Returns None for absent OR malformed input.
+
+    The server is not this SDK's parser: a garbled or hostile header must never raise inside a caller's
+    request path. The worst it can do is say nothing.
+    """
+    if not header:
+        return None
+    m = _KIND.match(header.strip())
+    if not m:
+        return None
+    kind, current, latest = m.group(1), m.group(2), m.group(3)
+    deprecated = kind == "deprecated" or deprecation == "true"
+    if deprecated:
+        message = (
+            f"webhook.co: this SDK version ({current}) is no longer supported and may misbehave. "
+            f"Upgrade to {latest}: pip install --upgrade webhook-co"
+        )
+    else:
+        message = (
+            f"webhook.co: a newer SDK is available ({current} -> {latest}). "
+            f"Upgrade with: pip install --upgrade webhook-co"
+        )
+    return WebhookAdvisory(
+        deprecated=deprecated, current=current, latest=latest, message=message
+    )
+
+
+def make_advisory_reporter(
+    on_advisory: Callable[[WebhookAdvisory], None] | None = None,
+    *,
+    silent: bool = False,
+    warn: Callable[[str], None] | None = None,
+) -> Callable[[str | None, str | None], None]:
+    """Build the per-client reporter: fires AT MOST ONCE, swallows a caller handler's exception.
+
+    A per-request nag would be a bug, not a feature. And if the caller's handler raises, that is their bug —
+    it must not surface as a failed API call.
+    """
+    state = {"reported": False}
+    emit = warn or (lambda message: warnings.warn(message, UserWarning, stacklevel=2))
+
+    def report(header: str | None, deprecation: str | None) -> None:
+        if state["reported"] or silent:
+            return
+        advisory = parse_advisory(header, deprecation)
+        if advisory is None:
+            return
+        state["reported"] = True
+        try:
+            if on_advisory is not None:
+                on_advisory(advisory)
+            else:
+                emit(advisory.message)
+        except (
+            Exception
+        ):  # noqa: BLE001 - the caller's logging bug must not fail their request
+            pass
+
+    return report

{webhook_co-0.2.0 → webhook_co-0.3.0}/src/webhook_co/_http.py

@@ -18,6 +18,7 @@ from typing import Any
 
 import httpx
 
+from ._advisory import ADVISORY_HEADER, DEPRECATION_HEADER, user_agent
 from ._errors import (
     WebhookErrorCode,
     WebhookUnexpectedResponseError,
@@ -68,10 +69,12 @@ class HttpClient:
         on_debug: Callable[[str], None] | None = None,
         sleep: Callable[[float], None] | None = None,
         rand: Callable[[], float] | None = None,
+        report_advisory: Callable[[str | None, str | None], None] | None = None,
     ) -> None:
         self._base_url = base_url
         self._api_key = api_key
         self._client = http_client
+        self._report_advisory = report_advisory
         self._max_retries = DEFAULT_MAX_RETRIES if max_retries is None else max_retries
         self._timeout_s = timeout_s
         self._refresh_auth = refresh_auth
@@ -108,6 +111,10 @@ class HttpClient:
             headers = {
                 "authorization": f"Bearer {bearer}",
                 "accept": "application/json",
+                # Identify the client + version. This is what lets the server answer with a version
+                # advisory on a response you already asked for, instead of the SDK polling PyPI behind
+                # your back.
+                "user-agent": user_agent(),
             }
             content: bytes | None = None
             if body is not None:
@@ -137,6 +144,14 @@ class HttpClient:
                     continue
                 raise error_from_transport(self._base_url) from None
 
+            # The server rides a version advisory on a response we already asked for. Surface it (at most
+            # once) regardless of status: a client too old to work is precisely the one seeing errors.
+            if self._report_advisory is not None:
+                self._report_advisory(
+                    res.headers.get(ADVISORY_HEADER),
+                    res.headers.get(DEPRECATION_HEADER),
+                )
+
             if res.is_success:
                 return self._parse_success(res)
 

{webhook_co-0.2.0 → webhook_co-0.3.0}/src/webhook_co/client.py

@@ -19,6 +19,7 @@ from urllib.parse import quote
 import httpx
 import pydantic
 
+from ._advisory import WebhookAdvisory, make_advisory_reporter
 from ._config import resolve_base_url
 from ._errors import WebhookConfigError, WebhookUnexpectedResponseError
 from ._generated import models as m
@@ -619,15 +620,19 @@ class _TriggersResource:
         held connection and no special timeout handling. Drain a backlog by re-calling promptly while
         ``caught_up`` is False, then poll on your own cadence once caught up.
 
-        ``cursor`` accepts None so the ``next_cursor`` of a caught-up page round-trips straight back in::
+        ``cursor`` accepts None so a None ``next_cursor`` round-trips straight back in. Read the semantics
+        carefully: ``next_cursor`` is None ONLY when you sent no cursor and there were no events — an empty
+        page ECHOES the cursor you sent. So None means "start from the oldest retained event", NOT "caught
+        up". ``caught_up`` is the caught-up signal; never infer it from a None cursor. (Passing None back is
+        safe: you re-read from the oldest, which is at-least-once by design — dedup on the event id.)::
 
             cursor = None
             while True:
                 page = client.triggers.wait(trigger_id, cursor=cursor)
                 for event in page.events:
                     handle(event)
-                cursor = page.next_cursor  # None when caught up — safe to pass right back
-                if page.caught_up:
+                cursor = page.next_cursor  # feed straight back in
+                if page.caught_up:  # <- the caught-up signal
                     time.sleep(1)
 
         At-least-once: a crash before you persist ``next_cursor`` re-reads, never loses — dedup on the event
@@ -670,6 +675,11 @@ class WebhookClient:
             default 30. Not a single total-wall-clock deadline.
         refresh_auth: Hook to swap in a rotated bearer on a 401 (OAuth flows).
         on_debug: Optional sink for redacted, single-line diagnostics (never the raw key).
+        on_advisory: Called AT MOST ONCE if the server reports this SDK version is behind. The advisory
+            rides an ``x-webhook-advisory`` header on a response you already made — the SDK never polls
+            PyPI on your behalf. Give a handler and it is yours to log; give none and the SDK emits a
+            single ``UserWarning``.
+        silence_advisories: Suppress version advisories entirely, including the warning.
     """
 
     def __init__(
@@ -682,6 +692,8 @@ class WebhookClient:
         timeout_s: float | None = None,
         refresh_auth: Callable[[], str | None] | None = None,
         on_debug: Callable[[str], None] | None = None,
+        on_advisory: Callable[[WebhookAdvisory], None] | None = None,
+        silence_advisories: bool = False,
         sleep: Callable[[float], None] | None = None,
         rand: Callable[[], float] | None = None,
     ) -> None:
@@ -704,6 +716,10 @@ class WebhookClient:
             timeout_s=timeout_s if timeout_s is not None else DEFAULT_TIMEOUT_S,
             refresh_auth=refresh_auth,
             on_debug=on_debug,
+            # One reporter per client: the advisory fires at most once, not once per request.
+            report_advisory=make_advisory_reporter(
+                on_advisory, silent=silence_advisories
+            ),
             sleep=sleep,
             rand=rand,
         )

webhook_co-0.3.0/tests/test_advisory.py

@@ -0,0 +1,131 @@
+"""The server-driven version advisory: the SDK identifies itself, the server answers on a response the
+caller already made. No PyPI polling from inside someone's Lambda, no extra request."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from webhook_co import WebhookClient
+from webhook_co._advisory import (
+    make_advisory_reporter,
+    parse_advisory,
+    user_agent,
+)
+
+
+class TestUserAgent:
+    def test_identifies_client_and_version(self):
+        ua = user_agent()
+        assert ua.startswith("webhook-co-python/")
+        assert "python/" in ua
+
+
+class TestParseAdvisory:
+    def test_parses_an_update(self):
+        a = parse_advisory("update-available; current=0.2.0; latest=0.3.0", None)
+        assert a is not None and a.current == "0.2.0" and a.latest == "0.3.0"
+        assert a.deprecated is False
+
+    def test_deprecation_is_louder_than_an_update(self):
+        a = parse_advisory("deprecated; current=0.1.0; latest=0.3.0", "true")
+        assert a is not None and a.deprecated is True
+        assert "no longer supported" in a.message
+
+    def test_absent_or_malformed_returns_none_and_never_raises(self):
+        # The server is not this SDK's parser. A garbled header must never raise in a caller's request path.
+        for bad in [
+            None,
+            "",
+            "garbage",
+            "update-available",
+            "update-available; current=; latest=",
+        ]:
+            assert parse_advisory(bad, None) is None
+
+
+class TestReporter:
+    def test_reports_once_however_many_requests(self):
+        seen = []
+        report = make_advisory_reporter(seen.append)
+        for _ in range(5):
+            report("update-available; current=0.2.0; latest=0.3.0", None)
+        assert len(seen) == 1  # a per-request nag is a bug, not a feature
+
+    def test_falls_back_to_a_single_warning_with_no_handler(self):
+        warned = []
+        report = make_advisory_reporter(None, warn=warned.append)
+        report("update-available; current=0.2.0; latest=0.3.0", None)
+        report("update-available; current=0.2.0; latest=0.3.0", None)
+        assert len(warned) == 1 and "0.2.0 -> 0.3.0" in warned[0]
+
+    def test_silent_says_nothing_at_all(self):
+        warned = []
+        report = make_advisory_reporter(None, silent=True, warn=warned.append)
+        report("deprecated; current=0.1.0; latest=0.3.0", "true")
+        assert warned == []
+
+    def test_a_throwing_handler_never_breaks_the_request(self):
+        def boom(_a):
+            raise RuntimeError("caller's logging bug")
+
+        report = make_advisory_reporter(boom)
+        report("update-available; current=0.2.0; latest=0.3.0", None)  # must not raise
+
+
+class TestEndToEnd:
+    """Through the real client: we send the UA, the server rides an advisory, we surface it ONCE."""
+
+    # A valid whoami body: the SDK validates responses, so a thin stub is (correctly) rejected.
+    WHOAMI = {
+        "orgId": "22222222-2222-4222-8222-222222222222",
+        "userId": None,
+        "scopes": [],
+    }
+
+    def _client(self, headers, seen, **kw):
+        def handler(request: httpx.Request) -> httpx.Response:
+            seen.append(request)
+            return httpx.Response(200, json=self.WHOAMI, headers=headers)
+
+        return WebhookClient(
+            api_key="whk_advisory_test_key_abc",
+            http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+            **kw,
+        )
+
+    def test_sends_a_versioned_user_agent(self):
+        seen = []
+        client = self._client({}, seen)
+        client.whoami()
+        assert seen[0].headers["user-agent"].startswith("webhook-co-python/")
+
+    def test_surfaces_the_advisory_exactly_once(self):
+        got, seen = [], []
+        client = self._client(
+            {"x-webhook-advisory": "update-available; current=0.0.0; latest=9.9.9"},
+            seen,
+            on_advisory=got.append,
+        )
+        client.whoami()
+        client.whoami()
+        client.whoami()
+        assert len(got) == 1  # once per client, not once per request
+        assert got[0].latest == "9.9.9"
+
+    def test_silent_when_the_server_sends_no_advisory(self):
+        got, seen = [], []
+        client = self._client({}, seen, on_advisory=got.append)
+        client.whoami()
+        assert got == []
+
+    def test_can_be_silenced(self):
+        got, seen = [], []
+        client = self._client(
+            {"x-webhook-advisory": "update-available; current=0.0.0; latest=9.9.9"},
+            seen,
+            on_advisory=got.append,
+            silence_advisories=True,
+        )
+        client.whoami()
+        assert got == []