hooka-relay-python 1.0.0__tar.gz

hooka_relay_python-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wael Fezari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hooka_relay_python-1.0.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: hooka-relay-python
+Version: 1.0.0
+Summary: Typed Hooka Relay event client and Standard Webhooks verification
+License-Expression: MIT
+Project-URL: Documentation, https://hooka-relay.vercel.app/docs
+Project-URL: Source, https://github.com/wauul/hooka-relay/tree/master/packages/python
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: standardwebhooks==1.1.0
+Dynamic: license-file
+
+# hooka-relay-python
+
+Python 3.11+ client for [Hooka Relay](https://hooka-relay.vercel.app/docs#api-reference).
+
+```sh
+pip install hooka-relay-python
+```
+
+```python
+import os
+from hooka_relay import HookaRelay
+relay = HookaRelay(os.environ["HOOKA_API_KEY"])
+event = relay.send_event({
+    "type": "order.created", "payload": {"orderId": "123"},
+    "idempotencyKey": "order-123-created",
+})
+print(event["id"])
+```
+
+Use an ingest-only or existing unscoped application key. Optional `base_url` and `timeout` (seconds, default 30) configure the client. Remote URLs require HTTPS; redirects are rejected to avoid credential forwarding. There are no implicit retries. Retry ambiguous network failures with the **same explicit idempotencyKey**; omitted keys are generated by the server, so resending without one can create another event.
+
+`HookaError` exposes `status`, parsed `body`, and `retry_after`. Rate limits return 429, oversized requests 413, and schema failures 400 with `failures: [{path, message}]`. Payload limits: 256 KiB / JSON depth 32. TypedDict models are generated from the repository's OpenAPI contract; runtime server validation remains authoritative.
+
+## Verify and queue, then drain
+
+`verify_webhook(raw_body, headers, secret)` uses the Standard Webhooks reference library. It raises on invalid signatures, a changed ID/body, or timestamps outside five minutes. Pass raw bytes and the displayed `whsec_` secret. During rotation either old or new key verifies the dual signatures. Existing LEGACY endpoints must explicitly migrate after their receiver supports Standard Webhooks.
+
+Minimal queue-and-drain receiver using the standard library (put a production HTTP server/reverse proxy in front of a real deployment). A bounded queue rejects overload with 503; accepted work is processed outside the request.
+
+```python
+import os
+import logging
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from queue import Queue, Full
+from threading import Thread
+from hooka_relay import verify_webhook
+
+queue = Queue(maxsize=1000)
+
+def process_event(item):
+    print(item["id"], item["payload"])
+
+def drain():
+    while True:
+        item = queue.get()
+        try:
+            process_event(item)
+        except Exception:
+            logging.exception("Persist failed item to your dead-letter store: %s", item["id"])
+        finally:
+            queue.task_done()
+
+class Receiver(BaseHTTPRequestHandler):
+    def do_POST(self):
+        if self.path != "/webhook":
+            self.send_error(404)
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "-1"))
+        except ValueError:
+            self.send_error(400)
+            return
+        if length < 0 or self.headers.get("Transfer-Encoding"):
+            self.send_error(411)
+            return
+        if length > 262144:
+            self.send_error(413)
+            return
+        try:
+            headers = {k: self.headers.get(k, "") for k in ("webhook-id", "webhook-timestamp", "webhook-signature")}
+            payload = verify_webhook(self.rfile.read(length), headers, os.environ["HOOKA_SIGNING_SECRET"])
+        except Exception:
+            self.send_error(400)
+            return
+        try:
+            queue.put_nowait({"id": headers["webhook-id"], "payload": payload})
+        except Full:
+            self.send_error(503)
+            return
+        self.send_response(202)
+        self.end_headers()
+
+Thread(target=drain, daemon=True).start()
+ThreadingHTTPServer(("127.0.0.1", 8080), Receiver).serve_forever()
+```
+
+The queue is **volatile**: a crash loses already acknowledged work. For production, persist to a durable inbox/queue before acknowledging. Atomically deduplicate the authenticated `webhook-id` with business changes. Persist processing failures for retry or dead-letter handling; a log entry is not durable recovery.
+
+## Event ordering
+
+Ordering is **not guaranteed across retries or replay generations**. The queue-and-drain example above separates acknowledgement from slow processing and isolates failures. It cannot restore producer order; apply per-entity sequence/version checks if required.
+
+[Interactive API reference](https://hooka-relay.vercel.app/docs#api-reference) · [Security and migration](https://github.com/wauul/hooka-relay/blob/master/SECURITY.md)

hooka_relay_python-1.0.0/README.md

@@ -0,0 +1,93 @@
+# hooka-relay-python
+
+Python 3.11+ client for [Hooka Relay](https://hooka-relay.vercel.app/docs#api-reference).
+
+```sh
+pip install hooka-relay-python
+```
+
+```python
+import os
+from hooka_relay import HookaRelay
+relay = HookaRelay(os.environ["HOOKA_API_KEY"])
+event = relay.send_event({
+    "type": "order.created", "payload": {"orderId": "123"},
+    "idempotencyKey": "order-123-created",
+})
+print(event["id"])
+```
+
+Use an ingest-only or existing unscoped application key. Optional `base_url` and `timeout` (seconds, default 30) configure the client. Remote URLs require HTTPS; redirects are rejected to avoid credential forwarding. There are no implicit retries. Retry ambiguous network failures with the **same explicit idempotencyKey**; omitted keys are generated by the server, so resending without one can create another event.
+
+`HookaError` exposes `status`, parsed `body`, and `retry_after`. Rate limits return 429, oversized requests 413, and schema failures 400 with `failures: [{path, message}]`. Payload limits: 256 KiB / JSON depth 32. TypedDict models are generated from the repository's OpenAPI contract; runtime server validation remains authoritative.
+
+## Verify and queue, then drain
+
+`verify_webhook(raw_body, headers, secret)` uses the Standard Webhooks reference library. It raises on invalid signatures, a changed ID/body, or timestamps outside five minutes. Pass raw bytes and the displayed `whsec_` secret. During rotation either old or new key verifies the dual signatures. Existing LEGACY endpoints must explicitly migrate after their receiver supports Standard Webhooks.
+
+Minimal queue-and-drain receiver using the standard library (put a production HTTP server/reverse proxy in front of a real deployment). A bounded queue rejects overload with 503; accepted work is processed outside the request.
+
+```python
+import os
+import logging
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from queue import Queue, Full
+from threading import Thread
+from hooka_relay import verify_webhook
+
+queue = Queue(maxsize=1000)
+
+def process_event(item):
+    print(item["id"], item["payload"])
+
+def drain():
+    while True:
+        item = queue.get()
+        try:
+            process_event(item)
+        except Exception:
+            logging.exception("Persist failed item to your dead-letter store: %s", item["id"])
+        finally:
+            queue.task_done()
+
+class Receiver(BaseHTTPRequestHandler):
+    def do_POST(self):
+        if self.path != "/webhook":
+            self.send_error(404)
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "-1"))
+        except ValueError:
+            self.send_error(400)
+            return
+        if length < 0 or self.headers.get("Transfer-Encoding"):
+            self.send_error(411)
+            return
+        if length > 262144:
+            self.send_error(413)
+            return
+        try:
+            headers = {k: self.headers.get(k, "") for k in ("webhook-id", "webhook-timestamp", "webhook-signature")}
+            payload = verify_webhook(self.rfile.read(length), headers, os.environ["HOOKA_SIGNING_SECRET"])
+        except Exception:
+            self.send_error(400)
+            return
+        try:
+            queue.put_nowait({"id": headers["webhook-id"], "payload": payload})
+        except Full:
+            self.send_error(503)
+            return
+        self.send_response(202)
+        self.end_headers()
+
+Thread(target=drain, daemon=True).start()
+ThreadingHTTPServer(("127.0.0.1", 8080), Receiver).serve_forever()
+```
+
+The queue is **volatile**: a crash loses already acknowledged work. For production, persist to a durable inbox/queue before acknowledging. Atomically deduplicate the authenticated `webhook-id` with business changes. Persist processing failures for retry or dead-letter handling; a log entry is not durable recovery.
+
+## Event ordering
+
+Ordering is **not guaranteed across retries or replay generations**. The queue-and-drain example above separates acknowledgement from slow processing and isolates failures. It cannot restore producer order; apply per-entity sequence/version checks if required.
+
+[Interactive API reference](https://hooka-relay.vercel.app/docs#api-reference) · [Security and migration](https://github.com/wauul/hooka-relay/blob/master/SECURITY.md)

hooka_relay_python-1.0.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hooka-relay-python"
+version = "1.0.0"
+description = "Typed Hooka Relay event client and Standard Webhooks verification"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = ["standardwebhooks==1.1.0"]
+
+[project.urls]
+Documentation = "https://hooka-relay.vercel.app/docs"
+Source = "https://github.com/wauul/hooka-relay/tree/master/packages/python"
+
+[tool.setuptools.package-data]
+hooka_relay = ["py.typed"]

hooka_relay_python-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hooka_relay_python-1.0.0/src/hooka_relay/__init__.py

@@ -0,0 +1,67 @@
+"""Server-side event client. API keys must never be shipped to a browser."""
+import json
+import math
+from urllib.error import HTTPError
+from urllib.parse import urlparse
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+from standardwebhooks.webhooks import Webhook
+from .generated import EventInput, EventResponse, ErrorResponse, JsonValue
+
+__all__ = ["HookaRelay", "HookaError", "verify_webhook", "EventInput", "EventResponse", "ErrorResponse", "JsonValue"]
+
+
+class HookaError(Exception):
+    def __init__(self, status: int, body: object, retry_after: str | None):
+        super().__init__(f"Hooka Relay returned HTTP {status}")
+        self.status = status
+        self.body = body
+        self.retry_after = retry_after
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    # Never forward a publishing credential to a redirected origin.
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+class HookaRelay:
+    def __init__(self, api_key: str, *, base_url: str = "https://hooka-relay.vercel.app", timeout: float = 30):
+        if not api_key or "\r" in api_key or "\n" in api_key:
+            raise ValueError("An API key is required")
+        url = urlparse(base_url)
+        if url.scheme not in ("https", "http") or not url.hostname or url.username or url.password:
+            raise ValueError("Invalid base URL")
+        if url.scheme == "http" and url.hostname not in ("localhost", "127.0.0.1", "::1"):
+            raise ValueError("Use HTTPS outside localhost")
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("Invalid timeout")
+        self._url = f"{url.scheme}://{url.netloc}/api/v1/events"
+        self._api_key = api_key
+        self._timeout = timeout
+        self._opener = build_opener(_NoRedirect())
+
+    def send_event(self, event: EventInput) -> EventResponse:
+        """Send once. For retries, reuse an explicit idempotencyKey."""
+        request = Request(self._url, data=json.dumps(event, allow_nan=False).encode(), method="POST", headers={
+            "Authorization": f"Bearer {self._api_key}", "Content-Type": "application/json",
+        })
+        try:
+            response = self._opener.open(request, timeout=self._timeout)
+        except HTTPError as error:
+            response = error
+        with response:
+            raw = response.read().decode("utf-8", errors="replace")
+            try:
+                body = json.loads(raw)
+            except ValueError:
+                body = raw
+            if response.status != 202:
+                raise HookaError(response.status, body, response.headers.get("Retry-After"))
+            if not isinstance(body, dict) or not isinstance(body.get("id"), str):
+                raise ValueError("Invalid Hooka Relay event response")
+            return body
+
+
+def verify_webhook(raw_body: str | bytes, headers: dict[str, str], secret: str) -> object:
+    """Verify exact raw bytes, signed event ID and the reference library's clock window."""
+    return Webhook(secret).verify(raw_body, headers)

hooka_relay_python-1.0.0/src/hooka_relay/generated.py

@@ -0,0 +1,31 @@
+# Generated from docs/openapi.json; run npm run sdk:generate.
+from typing import NotRequired, TypedDict, Union
+
+JsonValue = Union[None, bool, int, float, str, list["JsonValue"], dict[str, "JsonValue"]]
+
+
+class EventInput(TypedDict):
+    type: str
+    payload: JsonValue
+    idempotencyKey: NotRequired[str]
+
+
+class EventResponse(TypedDict):
+    id: str
+    applicationId: str
+    type: str
+    payload: JsonValue
+    idempotencyKey: str
+    operational: bool
+    createdAt: str
+
+
+class SchemaFailure(TypedDict):
+    path: str
+    message: str
+
+
+class ErrorResponse(TypedDict):
+    error: str
+    retryAfter: NotRequired[int]
+    failures: NotRequired[list[SchemaFailure]]

hooka_relay_python-1.0.0/src/hooka_relay_python.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: hooka-relay-python
+Version: 1.0.0
+Summary: Typed Hooka Relay event client and Standard Webhooks verification
+License-Expression: MIT
+Project-URL: Documentation, https://hooka-relay.vercel.app/docs
+Project-URL: Source, https://github.com/wauul/hooka-relay/tree/master/packages/python
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: standardwebhooks==1.1.0
+Dynamic: license-file
+
+# hooka-relay-python
+
+Python 3.11+ client for [Hooka Relay](https://hooka-relay.vercel.app/docs#api-reference).
+
+```sh
+pip install hooka-relay-python
+```
+
+```python
+import os
+from hooka_relay import HookaRelay
+relay = HookaRelay(os.environ["HOOKA_API_KEY"])
+event = relay.send_event({
+    "type": "order.created", "payload": {"orderId": "123"},
+    "idempotencyKey": "order-123-created",
+})
+print(event["id"])
+```
+
+Use an ingest-only or existing unscoped application key. Optional `base_url` and `timeout` (seconds, default 30) configure the client. Remote URLs require HTTPS; redirects are rejected to avoid credential forwarding. There are no implicit retries. Retry ambiguous network failures with the **same explicit idempotencyKey**; omitted keys are generated by the server, so resending without one can create another event.
+
+`HookaError` exposes `status`, parsed `body`, and `retry_after`. Rate limits return 429, oversized requests 413, and schema failures 400 with `failures: [{path, message}]`. Payload limits: 256 KiB / JSON depth 32. TypedDict models are generated from the repository's OpenAPI contract; runtime server validation remains authoritative.
+
+## Verify and queue, then drain
+
+`verify_webhook(raw_body, headers, secret)` uses the Standard Webhooks reference library. It raises on invalid signatures, a changed ID/body, or timestamps outside five minutes. Pass raw bytes and the displayed `whsec_` secret. During rotation either old or new key verifies the dual signatures. Existing LEGACY endpoints must explicitly migrate after their receiver supports Standard Webhooks.
+
+Minimal queue-and-drain receiver using the standard library (put a production HTTP server/reverse proxy in front of a real deployment). A bounded queue rejects overload with 503; accepted work is processed outside the request.
+
+```python
+import os
+import logging
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from queue import Queue, Full
+from threading import Thread
+from hooka_relay import verify_webhook
+
+queue = Queue(maxsize=1000)
+
+def process_event(item):
+    print(item["id"], item["payload"])
+
+def drain():
+    while True:
+        item = queue.get()
+        try:
+            process_event(item)
+        except Exception:
+            logging.exception("Persist failed item to your dead-letter store: %s", item["id"])
+        finally:
+            queue.task_done()
+
+class Receiver(BaseHTTPRequestHandler):
+    def do_POST(self):
+        if self.path != "/webhook":
+            self.send_error(404)
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "-1"))
+        except ValueError:
+            self.send_error(400)
+            return
+        if length < 0 or self.headers.get("Transfer-Encoding"):
+            self.send_error(411)
+            return
+        if length > 262144:
+            self.send_error(413)
+            return
+        try:
+            headers = {k: self.headers.get(k, "") for k in ("webhook-id", "webhook-timestamp", "webhook-signature")}
+            payload = verify_webhook(self.rfile.read(length), headers, os.environ["HOOKA_SIGNING_SECRET"])
+        except Exception:
+            self.send_error(400)
+            return
+        try:
+            queue.put_nowait({"id": headers["webhook-id"], "payload": payload})
+        except Full:
+            self.send_error(503)
+            return
+        self.send_response(202)
+        self.end_headers()
+
+Thread(target=drain, daemon=True).start()
+ThreadingHTTPServer(("127.0.0.1", 8080), Receiver).serve_forever()
+```
+
+The queue is **volatile**: a crash loses already acknowledged work. For production, persist to a durable inbox/queue before acknowledging. Atomically deduplicate the authenticated `webhook-id` with business changes. Persist processing failures for retry or dead-letter handling; a log entry is not durable recovery.
+
+## Event ordering
+
+Ordering is **not guaranteed across retries or replay generations**. The queue-and-drain example above separates acknowledgement from slow processing and isolates failures. It cannot restore producer order; apply per-entity sequence/version checks if required.
+
+[Interactive API reference](https://hooka-relay.vercel.app/docs#api-reference) · [Security and migration](https://github.com/wauul/hooka-relay/blob/master/SECURITY.md)

hooka_relay_python-1.0.0/src/hooka_relay_python.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/hooka_relay/__init__.py
+src/hooka_relay/generated.py
+src/hooka_relay/py.typed
+src/hooka_relay_python.egg-info/PKG-INFO
+src/hooka_relay_python.egg-info/SOURCES.txt
+src/hooka_relay_python.egg-info/dependency_links.txt
+src/hooka_relay_python.egg-info/requires.txt
+src/hooka_relay_python.egg-info/top_level.txt
+tests/test_client.py

hooka_relay_python-1.0.0/src/hooka_relay_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hooka_relay_python-1.0.0/src/hooka_relay_python.egg-info/requires.txt

@@ -0,0 +1 @@
+standardwebhooks==1.1.0

hooka_relay_python-1.0.0/src/hooka_relay_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+hooka_relay

hooka_relay_python-1.0.0/tests/test_client.py

@@ -0,0 +1,69 @@
+import base64
+import io
+import json
+import unittest
+from datetime import datetime, timedelta, timezone
+from unittest.mock import Mock
+from urllib.error import HTTPError
+from hooka_relay import HookaRelay, HookaError, verify_webhook
+from standardwebhooks.webhooks import Webhook
+
+
+class Response(io.BytesIO):
+    def __init__(self, body, status=202):
+        super().__init__(json.dumps(body).encode())
+        self.status = status
+        self.headers = {"Retry-After": "12"}
+
+
+class ClientTests(unittest.TestCase):
+    def test_send(self):
+        client = HookaRelay("test-key")
+        event = {"id": "evt_1", "type": "test", "payload": None}
+        client._opener = Mock()
+        client._opener.open.return_value = Response(event)
+        request = {"type": "test", "payload": None, "idempotencyKey": "stable"}
+        self.assertEqual(client.send_event(request), event)
+        sent = client._opener.open.call_args.args[0]
+        self.assertEqual(sent.full_url, "https://hooka-relay.vercel.app/api/v1/events")
+        self.assertEqual(json.loads(sent.data), request)
+        self.assertEqual(sent.get_header("Authorization"), "Bearer test-key")
+        client._opener.open.assert_called_once()
+
+    def test_errors_no_retries(self):
+        for status in (400, 401, 403, 413, 429, 503):
+            client = HookaRelay("secret-key")
+            client._opener = Mock()
+            client._opener.open.side_effect = HTTPError(client._url, status, "test", {"Retry-After": "12"}, io.BytesIO(b'{"error":"test"}'))
+            with self.assertRaises(HookaError) as caught:
+                client.send_event({"type": "test", "payload": None})
+            self.assertEqual(caught.exception.status, status)
+            self.assertEqual(caught.exception.retry_after, "12")
+            self.assertNotIn("secret-key", str(caught.exception))
+            client._opener.open.assert_called_once()
+
+    def test_invalid_urls_and_redirect(self):
+        for url in ("http://example.com", "https://user:pass@example.com", "file:///test"):
+            with self.assertRaises(ValueError):
+                HookaRelay("key", base_url=url)
+        client = HookaRelay("key")
+        redirect = next(h for h in client._opener.handlers if hasattr(h, "redirect_request"))
+        self.assertIsNone(redirect.redirect_request(None, None, 302, "", {}, "https://other.example"))
+
+    def test_reference_verification(self):
+        keys = ["whsec_" + base64.b64encode(bytes([n]) * 32).decode() for n in (1, 2)]
+        now = datetime.now(timezone.utc)
+        raw, event_id = '{"hello":"world"}', "evt_stable"
+        headers = {"webhook-id": event_id, "webhook-timestamp": str(int(now.timestamp())), "webhook-signature": " ".join(Webhook(k).sign(event_id, now, raw) for k in keys)}
+        for key in keys:
+            self.assertEqual(verify_webhook(raw, headers, key), {"hello": "world"})
+        for altered, body in (({**headers, "webhook-id": "forged"}, raw), (headers, raw + " ")):
+            with self.assertRaises(Exception):
+                verify_webhook(body, altered, keys[0])
+        old = now - timedelta(minutes=10)
+        with self.assertRaises(Exception):
+            verify_webhook(raw, {**headers, "webhook-timestamp": str(int(old.timestamp())), "webhook-signature": Webhook(keys[0]).sign(event_id, old, raw)}, keys[0])
+
+
+if __name__ == "__main__":
+    unittest.main()