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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webhook-co
-Version: 0.2.1
+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.1 → webhook_co-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webhook-co"
-version = "0.2.1"
+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/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.1 → 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.1 → 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
@@ -674,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__(
@@ -686,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:
@@ -708,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 == []