streamgine 1.0.0__py3-none-any.whl

streamgine/__init__.py

@@ -0,0 +1,5 @@
+"""Streamgine Python SDK."""
+
+__version__ = "1.0.0"
+
+__all__ = ["__version__", "diff"]

streamgine/diff/__init__.py

@@ -0,0 +1,40 @@
+"""Diff by Streamgine — register webhooks and verify shared-secret events."""
+
+from streamgine.diff.client import DiffClient
+from streamgine.diff.constants import TEST_ROUTING_FILING_TYPE, TEST_ROUTING_STATE, TEST_TOPIC
+from streamgine.diff.credentials import (
+    API_KEY_ENV,
+    API_URL_ENV,
+    CREDENTIALS_FILE_ENV,
+    CUSTOMER_ID_ENV,
+    PROVIDER_API_KEY_ENV,
+    SIGNING_SECRET_ENV,
+    ClientConfig,
+    configure,
+    get_config,
+    reset_config,  # importable for tests; omitted from __all__
+)
+from streamgine.diff.exceptions import DiffError, WebhookVerificationError
+from streamgine.diff.models import WebhookEvent
+from streamgine.diff.webhooks import SIGNATURE_HEADER, verify_webhook
+
+__all__ = [
+    "DiffClient",
+    "DiffError",
+    "ClientConfig",
+    "configure",
+    "get_config",
+    "CREDENTIALS_FILE_ENV",
+    "API_URL_ENV",
+    "API_KEY_ENV",
+    "SIGNING_SECRET_ENV",
+    "PROVIDER_API_KEY_ENV",
+    "CUSTOMER_ID_ENV",
+    "WebhookVerificationError",
+    "WebhookEvent",
+    "TEST_ROUTING_STATE",
+    "TEST_ROUTING_FILING_TYPE",
+    "TEST_TOPIC",
+    "SIGNATURE_HEADER",
+    "verify_webhook",
+]

streamgine/diff/client.py

@@ -0,0 +1,188 @@
+"""HTTP client for the Diff by Streamgine API."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+from urllib.parse import quote
+
+import httpx
+
+from streamgine.diff.constants import TEST_ROUTING_FILING_TYPE, TEST_ROUTING_STATE
+from streamgine.diff.credentials import API_KEY_ENV, get_config
+from streamgine.diff.exceptions import DiffError
+
+DEFAULT_TIMEOUT = 30.0
+
+_AUTH_SETUP_HINT = "Call configure() once at startup (JSON file or DIFF_* env vars)."
+
+
+class DiffClient:
+    """
+    Register agents and inspect entity snapshots on Diff by Streamgine.
+
+    Credentials come from a single :func:`configure` call — not constructor args.
+
+    Use one ``DiffClient`` per thread for concurrent requests. Sharing a single
+    instance across threads is not safe (httpx ``Client`` is not thread-safe for
+    concurrent use).
+
+    Example::
+
+        from streamgine import diff
+
+        diff.configure("diff-streamgine-credentials.json")  # or source diff-streamgine-env.sh then configure()
+        client = diff.DiffClient()
+        client.register_test(callback_url="https://example.com/webhooks/diff")
+    """
+
+    def __init__(
+        self,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        verify_tls: bool = True,
+        headers: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        config = get_config()
+        self._base_url = config.api_url
+        self._provider_api_key = config.provider_api_key
+        merged_headers: dict[str, str] = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {config.api_key}",
+            **dict(headers or {}),
+        }
+        client_kwargs: dict[str, Any] = {
+            "base_url": self._base_url,
+            "timeout": timeout,
+            "verify": verify_tls,
+            "headers": merged_headers,
+        }
+        if transport is not None:
+            client_kwargs["transport"] = transport
+        self._client = httpx.Client(**client_kwargs)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> DiffClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def health(self) -> dict[str, Any]:
+        """GET /health — liveness check."""
+        return self._request("GET", "/health")
+
+    def register(
+        self,
+        *,
+        callback_url: str,
+        match: Mapping[str, str] | None = None,
+        actions: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """
+        POST /api/subscriptions — subscribe this account with field filters.
+
+        Prefer ``match`` (equality AND). Examples::
+
+            match={"state": "CA"}
+            match={"state": "CA", "principal_city": "San Francisco"}
+            match={"principal_city": "San Francisco"}
+
+        Optional ``actions`` (e.g. ``["INSERT"]``) refine after the match.
+
+        Re-registering replaces filters and callback URL for the same account.
+        """
+        body: dict[str, Any] = {"callbackUrl": callback_url}
+        if match is not None:
+            body["match"] = dict(match)
+        if actions is not None:
+            body["actions"] = actions
+        return self._request(
+            "POST",
+            "/api/subscriptions",
+            json=body,
+        )
+
+    def register_test(self, *, callback_url: str) -> dict[str, Any]:
+        """
+        Subscribe to developer test heartbeats on topic ``diff-event.test``.
+
+        Convenience wrapper for ``register()`` with test heartbeat filters —
+        same path as production subscriptions.
+        """
+        return self.register(
+            match={
+                "state": TEST_ROUTING_STATE,
+                "filing_type": TEST_ROUTING_FILING_TYPE,
+            },
+            callback_url=callback_url,
+        )
+
+    def search(
+        self,
+        *,
+        query: Mapping[str, Any],
+        from_: int = 0,
+        size: int = 10,
+        sort: Any | None = None,
+    ) -> dict[str, Any]:
+        """
+        POST /api/search — full-story company search (current snapshots).
+
+        ``query`` is a search query object (same shape as Elasticsearch Query DSL
+        ``query``). Results are current company bodies in snake_case — not live
+        webhook events. Max ``size`` is 100.
+        """
+        body: dict[str, Any] = {
+            "query": dict(query),
+            "from": from_,
+            "size": size,
+        }
+        if sort is not None:
+            body["sort"] = sort
+        return self._request("POST", "/api/search", json=body)
+
+    def get_state(self, entity_id: str) -> dict[str, Any]:
+        """GET /api/provider/entities/:id — read the current entity snapshot (provider key)."""
+        headers: dict[str, str] = {}
+        if self._provider_api_key:
+            headers["Authorization"] = f"Bearer {self._provider_api_key}"
+        encoded_id = quote(entity_id, safe="")
+        return self._request(
+            "GET",
+            f"/api/provider/entities/{encoded_id}",
+            headers=headers,
+        )
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        try:
+            response = self._client.request(method, path, **kwargs)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as err:
+            detail = err.response.text.strip() or err.response.reason_phrase
+            message = f"{method} {path} failed ({err.response.status_code}): {detail}"
+            if err.response.status_code == 401:
+                message += (
+                    f" — API key rejected. Regenerate credentials on /login or check "
+                    f"{API_KEY_ENV}. {_AUTH_SETUP_HINT}"
+                )
+            raise DiffError(message) from err
+        except httpx.HTTPError as err:
+            message = f"{method} {path} failed: {err}"
+            err_text = str(err)
+            if "WRONG_VERSION_NUMBER" in err_text or "SSL:" in err_text:
+                message += (
+                    " — TLS handshake failed, often because DIFF_API_URL uses https:// "
+                    "against an http-only server."
+                )
+            raise DiffError(message) from err
+
+        if not response.content:
+            return {}
+
+        data = response.json()
+        if not isinstance(data, dict):
+            raise DiffError(f"{method} {path} returned unexpected JSON")
+        return data

streamgine/diff/constants.py

@@ -0,0 +1,5 @@
+"""Public constants for Diff by Streamgine routing and test heartbeats."""
+
+TEST_ROUTING_STATE = "TEST"
+TEST_ROUTING_FILING_TYPE = "test"
+TEST_TOPIC = "diff-event.test"

streamgine/diff/credentials.py

@@ -0,0 +1,153 @@
+"""Single-point Diff credentials setup — JSON file or DIFF_* env, not both."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+SUPPORTED_CREDENTIALS_VERSION = 1
+
+CREDENTIALS_FILE_ENV = "DIFF_CREDENTIALS_FILE"
+API_URL_ENV = "DIFF_API_URL"
+API_KEY_ENV = "DIFF_API_KEY"
+SIGNING_SECRET_ENV = "DIFF_SIGNING_SECRET"
+PROVIDER_API_KEY_ENV = "DIFF_PROVIDER_API_KEY"
+CUSTOMER_ID_ENV = "DIFF_CUSTOMER_ID"
+
+# Customer-facing download page — full URL, never bare /account
+ACCOUNT_CREDENTIALS_URL = "https://diff.streamgine.com/account"
+CREDENTIALS_DOWNLOAD_HINT = (
+    f"diff-streamgine-credentials.json from {ACCOUNT_CREDENTIALS_URL}"
+)
+
+_REQUIRED_ENV = (API_URL_ENV, API_KEY_ENV, SIGNING_SECRET_ENV)
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Resolved Diff credentials (read-only after configure)."""
+
+    api_url: str
+    api_key: str
+    signing_secret: str
+    provider_api_key: str | None = None
+    customer_id: str | None = None
+
+
+_config: ClientConfig | None = None
+
+
+def configure(credentials: str | Path | None = None) -> ClientConfig:
+    """
+    Load credentials once at process startup from a JSON file **or** env vars.
+
+    When called with no path argument, **environment variables must already be
+    set** before this call: ``DIFF_API_URL``, ``DIFF_API_KEY``, and
+    ``DIFF_SIGNING_SECRET`` (e.g. ``source diff-streamgine-env.sh`` from
+    https://diff.streamgine.com/account). Alternatively set
+    ``DIFF_CREDENTIALS_FILE`` to a checkout JSON path and call ``configure()``
+    with no args.
+
+    Use **one** source only:
+
+    - ``configure("diff-streamgine-credentials.json")`` — checkout JSON file
+    - ``configure()`` — reads from ``DIFF_*`` env (must be exported first via
+      ``source diff-streamgine-env.sh``)
+
+    Call again only to replace credentials (e.g. tests). Every ``DiffClient()``
+    and ``verify_webhook()`` reads from this config.
+    """
+    global _config
+
+    path = credentials
+    if path is None:
+        path = os.environ.get(CREDENTIALS_FILE_ENV)
+
+    if path:
+        _config = _config_from_file(Path(path))
+    else:
+        _config = _config_from_env()
+
+    return _config
+
+
+def get_config() -> ClientConfig:
+    """Return configured credentials. Raises if ``configure()`` was not called."""
+    if _config is None:
+        raise RuntimeError(
+            "Diff credentials not configured — call configure() once at startup "
+            f"(JSON path or {', '.join(_REQUIRED_ENV)} env vars)."
+        )
+    return _config
+
+
+def reset_config() -> None:
+    """Clear configured credentials (tests only)."""
+    global _config
+    _config = None
+
+
+def _load_credentials_file(path: Path) -> dict[str, Any]:
+    try:
+        with path.open(encoding="utf-8") as handle:
+            data = json.load(handle)
+    except FileNotFoundError as err:
+        raise ValueError(
+            f"credentials file not found: {path} — download {CREDENTIALS_DOWNLOAD_HINT}"
+        ) from err
+    except OSError as err:
+        raise ValueError(
+            f"could not read credentials file {path}: {err} — download "
+            f"{CREDENTIALS_DOWNLOAD_HINT}"
+        ) from err
+    except json.JSONDecodeError as err:
+        raise ValueError(
+            f"credentials file is not valid JSON ({path}): {err.msg} — "
+            f"re-download {CREDENTIALS_DOWNLOAD_HINT}"
+        ) from err
+
+    if not isinstance(data, dict):
+        raise ValueError("credentials file must contain a JSON object")
+
+    version = data.get("version")
+    if version != SUPPORTED_CREDENTIALS_VERSION:
+        raise ValueError(f"unsupported credentials file version: {version!r}")
+
+    for key in ("customer_id", "api_key", "signing_secret", "api_url"):
+        if not data.get(key):
+            raise ValueError(f"credentials file missing required field: {key}")
+
+    return data
+
+
+def _config_from_file(path: Path) -> ClientConfig:
+    raw = _load_credentials_file(path)
+    env = raw.get("env") if isinstance(raw.get("env"), dict) else {}
+    api_url = str(raw["api_url"]).rstrip("/")
+    return ClientConfig(
+        api_url=api_url,
+        api_key=str(raw["api_key"]),
+        signing_secret=str(raw["signing_secret"]),
+        provider_api_key=env.get(PROVIDER_API_KEY_ENV) or None,
+        customer_id=str(raw["customer_id"]) if raw.get("customer_id") else None,
+    )
+
+
+def _config_from_env() -> ClientConfig:
+    missing = [name for name in _REQUIRED_ENV if not os.environ.get(name)]
+    if missing:
+        raise ValueError(
+            f"missing required env var(s): {', '.join(missing)} — "
+            f"export them or call configure('diff-streamgine-credentials.json')"
+        )
+
+    return ClientConfig(
+        api_url=os.environ[API_URL_ENV].rstrip("/"),
+        api_key=os.environ[API_KEY_ENV],
+        signing_secret=os.environ[SIGNING_SECRET_ENV],
+        provider_api_key=os.environ.get(PROVIDER_API_KEY_ENV) or None,
+        customer_id=os.environ.get(CUSTOMER_ID_ENV) or None,
+    )

streamgine/diff/exceptions.py

@@ -0,0 +1,9 @@
+"""Client and webhook errors."""
+
+
+class DiffError(Exception):
+    """Base error for Diff by Streamgine client failures."""
+
+
+class WebhookVerificationError(DiffError):
+    """Raised when an inbound webhook fails HMAC verification."""

streamgine/diff/models.py

@@ -0,0 +1,31 @@
+"""Typed webhook payloads."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Mapping
+
+CustomerAction = Literal["INSERT", "UPDATE", "DELETE"]
+
+
+@dataclass(frozen=True, slots=True)
+class WebhookEvent:
+    """Verified customer webhook from Diff by Streamgine."""
+
+    action: CustomerAction
+    entity_id: str | None = None
+    after: Mapping[str, str] | None = None
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> WebhookEvent:
+        after = data.get("after")
+        entity_id = data.get("entity_id")
+        return cls(
+            action=data["action"],
+            entity_id=str(entity_id) if entity_id is not None else None,
+            after=dict(after) if isinstance(after, Mapping) else None,
+        )
+
+    @property
+    def is_test_heartbeat(self) -> bool:
+        return self.after == {"test": "success"}

streamgine/diff/webhooks.py

@@ -0,0 +1,83 @@
+"""HMAC verification for inbound Diff by Streamgine webhooks."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Any
+
+from streamgine.diff.credentials import get_config
+from streamgine.diff.exceptions import WebhookVerificationError
+from streamgine.diff.models import WebhookEvent
+
+SIGNATURE_HEADER = "X-Diff-Signature"
+
+
+def _expected_signature(raw_body: bytes, signing_secret: str) -> str:
+    return hmac.new(
+        signing_secret.encode("utf-8"),
+        raw_body,
+        hashlib.sha256,
+    ).hexdigest()
+
+
+def _normalize_signature_header(header: str | None) -> str | None:
+    if not header:
+        return None
+    value = header.strip()
+    if value.lower().startswith("sha256="):
+        return value[7:]
+    return value
+
+
+def verify_webhook(
+    raw_body: bytes,
+    signature_header: str | None,
+    *,
+    signing_secret: str | None = None,
+) -> WebhookEvent:
+    """
+    Verify ``X-Diff-Signature`` over the exact raw JSON bytes, then parse the event.
+
+    Uses the signing secret from :func:`configure` unless ``signing_secret`` is
+    passed explicitly (rare — prefer a single ``configure()`` at startup).
+
+    Must run on the unmodified request body (before JSON parsing) so the HMAC matches
+    what the Diff by Streamgine worker signed.
+    """
+    secret = signing_secret if signing_secret is not None else get_config().signing_secret
+    if not secret:
+        raise WebhookVerificationError("signing_secret is required — call configure() first")
+
+    received = _normalize_signature_header(signature_header)
+    if not received:
+        raise WebhookVerificationError("missing X-Diff-Signature header")
+
+    expected = _expected_signature(raw_body, secret)
+
+    try:
+        valid = hmac.compare_digest(expected, received)
+    except TypeError as err:
+        raise WebhookVerificationError("invalid signature encoding") from err
+
+    if not valid:
+        raise WebhookVerificationError("invalid webhook signature")
+
+    try:
+        payload: dict[str, Any] = json.loads(raw_body)
+    except json.JSONDecodeError as err:
+        raise WebhookVerificationError("invalid JSON body") from err
+
+    if "action" not in payload:
+        raise WebhookVerificationError("missing webhook fields: action")
+
+    if payload.get("after") == {"test": "success"}:
+        pass
+    elif "entity_id" not in payload:
+        raise WebhookVerificationError("missing webhook fields: entity_id")
+
+    if payload["action"] not in ("INSERT", "UPDATE", "DELETE"):
+        raise WebhookVerificationError("invalid action")
+
+    return WebhookEvent.from_dict(payload)

streamgine-1.0.0.dist-info/METADATA

@@ -0,0 +1,323 @@
+Metadata-Version: 2.5
+Name: streamgine
+Version: 1.0.0
+Summary: Streamgine Python SDK — Diff by Streamgine webhooks client and future modules.
+Project-URL: Homepage, https://streamgine.com
+Project-URL: Documentation, https://diff.streamgine.com/docs.md
+Project-URL: Repository, https://github.com/scurtutech/diff-events-service
+Project-URL: Issues, https://github.com/scurtutech/diff-events-service/issues
+Project-URL: Changelog, https://github.com/scurtutech/diff-events-service/releases
+Author-email: Streamgine <hello@streamgine.com>
+License: MIT
+Keywords: agents,compliance,corporate-standing,diff,streamgine,webhooks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# streamgine — Python SDK
+
+**Diff by Streamgine** lives under the `diff` module. Install once; add more Streamgine modules (training data, etc.) under the same package later.
+
+This directory is the **customer package** published to PyPI. Repo-only load tests and dev agents live in [`tools/python/`](../../tools/python/README.md) — not shipped to customers.
+
+**Today:** one wheel `streamgine` = Diff (`from streamgine import diff`). **Next products** (e.g. training-data) get their own wheels (`streamgine-diff`, `streamgine-training`, …) under the same `streamgine` import namespace — see [PUBLISHING.md](PUBLISHING.md) and `.cursor/rules/python-client.mdc`. Do not grow a fat single package.
+
+**Product:** [diff.streamgine.com](https://diff.streamgine.com) · **Docs:** [docs.md](https://diff.streamgine.com/docs.md) · **California:** [coverage](https://diff.streamgine.com/california) · **Use cases:** [risk monitoring](https://diff.streamgine.com/use-cases/risk-monitoring), [AI agents](https://diff.streamgine.com/use-cases/ai-agents) · **Repo:** [github.com/scurtutech/diff-events-service](https://github.com/scurtutech/diff-events-service)
+
+```python
+from streamgine import diff
+
+# Once at startup — pick ONE download from /account:
+diff.configure("diff-streamgine-credentials.json")
+# OR: source diff-streamgine-env.sh  then  diff.configure()
+client = diff.DiffClient()
+```
+
+Install from PyPI:
+
+```bash
+python3 -m pip install streamgine
+```
+
+Or from this repo:
+
+```bash
+cd clients/python
+python3 -m venv .venv && source .venv/bin/activate
+python -m pip install .
+```
+
+Requires Python 3.10+. One dependency: [httpx](https://www.python-httpx.org/) (TLS verification enabled by default).
+
+## Credentials (one setup point)
+
+Call `diff.configure()` **once** at process startup. Every `DiffClient()` and `verify_webhook()` reads from that config.
+
+Download from `/account` or checkout — filenames are fixed:
+
+| Download                           | Then                                                    |
+| ---------------------------------- | ------------------------------------------------------- |
+| `diff-streamgine-credentials.json` | `diff.configure("diff-streamgine-credentials.json")`    |
+| `diff-streamgine-env.sh`           | `source diff-streamgine-env.sh` then `diff.configure()` |
+
+**Option A — credentials JSON:**
+
+```python
+diff.configure("diff-streamgine-credentials.json")
+```
+
+**Option B — env script:**
+
+```bash
+source diff-streamgine-env.sh
+```
+
+```python
+diff.configure()
+```
+
+Do **not** pass API keys or signing secrets to `DiffClient()` or `verify_webhook()` in normal use.
+
+## Zero-setup agent (copy-paste)
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e . fastapi uvicorn
+# Customer path: download from /account, then ONE of:
+#   source diff-streamgine-env.sh
+#   # or keep diff-streamgine-credentials.json next to the process
+# Local repo seed (AUTH_ENABLED): npm run seed:dev-customer, then export printed keys
+source diff-streamgine-env.sh   # or configure("diff-streamgine-credentials.json") in code
+python -m uvicorn examples.agent:app --port 8000
+```
+
+Runnable source: [`examples/agent.py`](examples/agent.py). Calls `register_test()` on startup; within ~1s you should see `after={'test': 'success'}` on topic `diff-event.test`.
+
+**Serverless (AWS Lambda):** [`examples/serverless/`](examples/serverless/README.md) — deploy `handler.py`, run `register.py` once, receive test heartbeats in CloudWatch.
+
+**Agent journey (production filters):** [`examples/agent_journey.py`](examples/agent_journey.py).
+
+Docker worker reaching a host agent:
+
+```bash
+export DIFF_CALLBACK_URL=http://host.docker.internal:8000/webhooks/diff
+```
+
+## Test heartbeats (start here)
+
+Before wiring real registry events, confirm your agent receives signed webhooks:
+
+```python
+from streamgine import diff
+
+diff.configure()  # after: source diff-streamgine-env.sh  OR  configure("diff-streamgine-credentials.json")
+client = diff.DiffClient()
+client.register_test(callback_url="https://your-agent.example/webhooks/diff")
+```
+
+Filter on **`event.is_test_heartbeat`** (or `after == {"test": "success"}`). The service sends this every second:
+
+```json
+{
+  "action": "INSERT",
+  "after": { "test": "success" }
+}
+```
+
+No `entity_id` on test events.
+
+## Quick start (production registry events)
+
+```python
+from streamgine import diff
+
+diff.configure()
+client = diff.DiffClient()
+client.register(
+    match={
+        "state": "CA",
+        "principal_city": "San Francisco",
+    },
+    actions=["INSERT"],
+    callback_url="https://your-agent.example/webhooks/diff",
+)
+client.close()
+```
+
+`INSERT` = newly added company, `UPDATE` = changed, `DELETE` = removed. Omit `actions` to receive every matching state/city event.
+
+### Search current companies (full story)
+
+Webhooks deliver changes. Search returns **current** snapshots:
+
+```python
+from streamgine import diff
+
+diff.configure()
+client = diff.DiffClient()
+result = client.search(
+    query={"match": {"principalCity": "San Francisco"}},
+    size=10,
+)
+for company in result["entities"]:
+    print(company.get("entity_name"), company.get("entity_number"))
+```
+
+Agent journey: **Search → Watch → Qualify → Act → Stay current** (see [`/docs.md`](../../public/docs.md)).
+
+### 2. Verify inbound webhooks (required)
+
+Always verify **raw request bytes** before trusting JSON. The worker signs the exact JSON body with HMAC-SHA256.
+
+```python
+from streamgine import diff
+
+diff.configure()
+
+def handle_webhook(raw_body: bytes, signature: str | None):
+    try:
+        event = diff.verify_webhook(raw_body, signature)
+    except diff.WebhookVerificationError:
+        return 401, {"error": "invalid signature"}
+
+    print(event.action, event.entity_id, event.after)
+    return 200, {"ok": True}
+```
+
+**FastAPI**
+
+```python
+from fastapi import FastAPI, Header, Request, Response
+
+from streamgine import diff
+
+app = FastAPI()
+
+@app.on_event("startup")
+def setup() -> None:
+    diff.configure()
+
+@app.post("/webhooks/diff")
+async def diff_webhook(
+    request: Request,
+    response: Response,
+    x_diff_signature: str | None = Header(default=None, alias="X-Diff-Signature"),
+):
+    raw = await request.body()
+    try:
+        event = diff.verify_webhook(raw, x_diff_signature)
+    except diff.WebhookVerificationError:
+        response.status_code = 401
+        return {"error": "invalid signature"}
+
+    # Your agent logic here
+    return {"ok": True, "entity_id": event.entity_id}
+```
+
+**Flask**
+
+```python
+from flask import Flask, request
+
+from streamgine import diff
+
+app = Flask(__name__)
+diff.configure()
+
+@app.post("/webhooks/diff")
+def webhook():
+    try:
+        event = diff.verify_webhook(
+            request.get_data(),
+            request.headers.get("X-Diff-Signature"),
+        )
+    except diff.WebhookVerificationError:
+        return {"error": "invalid signature"}, 401
+
+    return {"ok": True, "action": event.action}
+```
+
+## Security
+
+| Practice                     | How this client helps                                                                         |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| Verify every webhook         | `diff.verify_webhook()` uses `hmac.compare_digest` (timing-safe) on the raw body              |
+| Match worker algorithm       | Same as Node: `HMAC-SHA256(secret, raw_json_bytes)` → header `X-Diff-Signature: sha256=<hex>` |
+| Parse JSON only after verify | Tampered bodies fail before `WebhookEvent` is built                                           |
+| HTTPS in production          | `DiffClient(verify_tls=True)` (default); use `https://` callback URLs                         |
+| Keep secrets out of code     | One `configure()` from JSON or env — never scatter keys in constructors                       |
+
+Never log the signing secret or skip signature verification in production.
+
+### Credentials file (after checkout)
+
+Download **`diff-streamgine-credentials.json`** (or **`diff-streamgine-env.sh`**) from `/account` / checkout. JSON format (version `1`):
+
+```json
+{
+  "version": 1,
+  "service": "diff.streamgine.com",
+  "customer_id": "cus_…",
+  "api_key": "de_live_…",
+  "signing_secret": "whsec_…",
+  "api_url": "https://diff.streamgine.com",
+  "env": {
+    "DIFF_API_KEY": "de_live_…",
+    "DIFF_SIGNING_SECRET": "whsec_…",
+    "DIFF_API_URL": "https://diff.streamgine.com"
+  }
+}
+```
+
+```python
+from streamgine import diff
+
+diff.configure("diff-streamgine-credentials.json")
+client = diff.DiffClient()
+# diff.verify_webhook(...) uses the same signing secret automatically
+```
+
+## Auth
+
+| Env (via `configure()`) | Used for                                                        |
+| ----------------------- | --------------------------------------------------------------- |
+| `DIFF_API_KEY`          | `register()` / `register_test()` (customer Bearer)              |
+| `DIFF_PROVIDER_API_KEY` | `get_state()` and provider ingest when provider auth is enabled |
+
+Register responses are slim (`ok` / subscription fields only — no Redis index maps).
+
+## API surface (`streamgine.diff`)
+
+| Symbol                      | Role                                                       |
+| --------------------------- | ---------------------------------------------------------- |
+| `configure()`               | Load credentials once (JSON path or `DIFF_*` env)          |
+| `get_config()`              | Read configured `ClientConfig`                             |
+| `DiffClient`                | `register()`, `register_test()`, `health()`, `get_state()` |
+| `verify_webhook()`          | Verify signature + return `WebhookEvent`                   |
+| `DIFF_*` env name constants | `API_URL_ENV`, `API_KEY_ENV`, `SIGNING_SECRET_ENV`, …      |
+| `WebhookEvent`              | Parsed `action`, optional `entity_id`, optional `after`    |
+| `WebhookVerificationError`  | Invalid/missing signature or malformed payload             |
+| `SIGNATURE_HEADER`          | `"X-Diff-Signature"`                                       |
+
+Direct imports also work: `from streamgine.diff import DiffClient`.
+
+## Development
+
+```bash
+cd clients/python
+python -m pip install -e ".[dev]"
+pytest
+```

streamgine-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+streamgine/__init__.py,sha256=9uinvKB4w1UJZZiRLJ6v1isjYDS_SjQoWnHaxQXWAmw,87
+streamgine/diff/__init__.py,sha256=ugmS54EVUYNRv82jeEdq9WKCKfAqKt9qc9sX_T0Psc4,1125
+streamgine/diff/client.py,sha256=sPr56Vi1JtoSLhKZdRrwZ8AdFzSv4AKttnTNH7W8MUc,6414
+streamgine/diff/constants.py,sha256=eWVxwcN8Um3bVVANsnb4PBURT2mjFAykke0gxjSk1_U,169
+streamgine/diff/credentials.py,sha256=1rNsi-Vjlc3uuQqVNbBniII8xWNWiU35P927GC-fRO4,5034
+streamgine/diff/exceptions.py,sha256=5GYmvo0IYIpK9cUVGpDXxlhiQc43zvDc_kNwffz6wDc,235
+streamgine/diff/models.py,sha256=r3NyREFZ5SSmuWl07eFHLex90Nd_mL13_Kd0_4F2rl4,894
+streamgine/diff/webhooks.py,sha256=YzKhNEC-yjwdhW6aLJ7-qLKAjtNjPzZf8DV0jeHAwIc,2618
+streamgine-1.0.0.dist-info/METADATA,sha256=TH8lmn8rsfEaK1OmzHqKpDslyamtXLM0kXeMliqMeaw,11555
+streamgine-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+streamgine-1.0.0.dist-info/RECORD,,

streamgine-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any