webhook-platform 2.2.1__tar.gz → 2.6.0__tar.gz

{webhook_platform-2.2.1 → webhook_platform-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webhook-platform
-Version: 2.2.1
+Version: 2.6.0
 Summary: Official Python SDK for Hookflow — reliable webhook infrastructure
 Author-email: Vadym Kykalo <vadymkykalo@gmail.com>
 License: MIT
@@ -31,6 +31,17 @@ Requires-Dist: types-requests>=2.28.0; extra == "dev"
 
 Official Python SDK for [Hookflow](https://github.com/vadymkykalo/webhook-platform).
 
+> The PyPI distribution is `webhook-platform`; the module you import is
+> `hookflow`. `pip install webhook-platform`, then `from hookflow import ...`.
+
+**Scope.** This SDK covers Events, Endpoints, Subscriptions, Deliveries,
+Incoming Sources, Incoming Events, and webhook signature verification —
+7 of the platform's 35 API controllers. It does not wrap
+Transformations, Rules, Workflows, Schemas, DLQ, Analytics, Usage, Alerts,
+Incidents, PII rules, Audit Log, Tunnels, API keys, Members, or Projects —
+use the [Generic Requests](#generic-requests) helpers for those until the
+SDK grows to cover them.
+
 ## Installation
 
 ```bash
@@ -40,10 +51,12 @@ pip install webhook-platform
 ## Quick Start
 
 ```python
+import os
+
 from hookflow import Hookflow, Event
 
 client = Hookflow(
-    api_key="wh_live_your_api_key",
+    api_key=os.environ["HOOKFLOW_API_KEY"],  # e.g. "Kz1uAIM8VeJUQN7yGSYCst64WxNLabBHfOYbrPlJ1yk"
     base_url="http://localhost:8080",  # optional
 )
 
@@ -92,8 +105,11 @@ endpoint = client.endpoints.create(
     ),
 )
 
-# List endpoints
-endpoints = client.endpoints.list(project_id)
+# List endpoints — the API paginates this one, so the endpoints are in .content
+# (iterating the page yields them directly)
+page = client.endpoints.list(project_id, page=0, size=20)
+for endpoint in page:
+    print(endpoint.url)
 
 # Update endpoint
 client.endpoints.update(
@@ -112,6 +128,7 @@ print(f"New secret: {updated.secret}")
 # Test endpoint connectivity
 result = client.endpoints.test(project_id, endpoint_id)
 print(f"Test {'passed' if result.success else 'failed'}: {result.latency_ms}ms")
+print(f"{result.http_status_code} — {result.message}")
 ```
 
 ### Subscriptions
@@ -129,7 +146,7 @@ subscription = client.subscriptions.create(
     ),
 )
 
-# List subscriptions
+# List subscriptions — a bare list; unlike endpoints, this one is not paginated
 subscriptions = client.subscriptions.list(project_id)
 
 # Update subscription
@@ -159,7 +176,7 @@ print(f"Total failed: {deliveries.total_elements}")
 # Get delivery attempts
 attempts = client.deliveries.get_attempts(delivery_id)
 for attempt in attempts:
-    print(f"Attempt {attempt.attempt_number}: {attempt.http_status} ({attempt.latency_ms}ms)")
+    print(f"Attempt {attempt.attempt_number}: {attempt.http_status_code} ({attempt.duration_ms}ms)")
 
 # Replay failed delivery
 client.deliveries.replay(delivery_id)
@@ -274,11 +291,12 @@ def handle_webhook():
         # Option 2: Verify and parse
         event = construct_event(payload, headers, secret)
 
-        print(f"Received {event.type}: {event.data}")
-
-        # Handle the event
-        if event.type == "order.completed":
-            handle_order_completed(event.data)
+        # event.data is the parsed body; event.event_id / event.delivery_id /
+        # event.timestamp come from the X-Event-Id / X-Delivery-Id /
+        # X-Timestamp headers. See "What lands on your endpoint" below for
+        # event.type.
+        print(f"Delivery {event.delivery_id} of event {event.event_id}: {event.data}")
+        handle_order_completed(event.data)
 
         return "OK", 200
 
@@ -287,6 +305,40 @@ def handle_webhook():
         return "Invalid signature", 400
 ```
 
+### What lands on your endpoint
+
+Hookflow PUTs the event's **payload** on the wire, not an envelope. This:
+
+```python
+client.events.send(Event(type="order.completed", data={"order_id": "ord_1"}))
+```
+
+arrives at your endpoint as the ``data`` object alone —
+
+```http
+POST /webhooks HTTP/1.1
+Content-Type: application/json
+X-Signature: t=1738000000000,v1=<hex hmac-sha256>
+X-Timestamp: 1738000000000
+X-Event-Id: 6f0e…
+X-Delivery-Id: 91ab…
+X-Sequence-Number: 0
+Idempotency-Key: 6f0e…-<endpoint-id>
+
+{"order_id":"ord_1"}
+```
+
+So `construct_event` fills `event_id`, `delivery_id` and `timestamp` from the
+headers and `data` from the body, but **`type` is empty**: the event type is
+not on the wire for a default subscription. Route on the payload, on the
+endpoint you registered, or set the subscription's `payload_template` to wrap
+the event so `type` becomes part of the body.
+
+The signature is computed over `f"{timestamp}.{raw_body}"` with HMAC-SHA256 and
+the endpoint secret, and the server rejects timestamps more than **300
+seconds** old — verify against the *raw* body bytes, before any JSON parse and
+re-serialize.
+
 ### FastAPI Example
 
 ```python
@@ -327,7 +379,8 @@ from hookflow import (
 try:
     client.events.send(Event(type="test", data={}))
 except RateLimitError as e:
-    # Wait and retry
+    # retry_after_ms is milliseconds. e.rate_limit_info.reset is the raw
+    # X-RateLimit-Reset header, which the API sends in Unix *seconds*.
     print(f"Rate limited. Retry after {e.retry_after_ms}ms")
     time.sleep(e.retry_after_ms / 1000)
 except AuthenticationError:
@@ -400,12 +453,35 @@ All generic methods use the same authentication, error handling, and rate-limit
 
 ```python
 client = Hookflow(
-    api_key="wh_live_xxx",          # Required: Your API key
-    base_url="https://api.example.com",  # Optional: API base URL
+    api_key=os.environ["HOOKFLOW_API_KEY"],  # Required: Your project API key
+    base_url="https://api.example.com",  # Optional (default: http://localhost:8080)
     timeout=30,                     # Optional: Request timeout in seconds (default: 30)
 )
 ```
 
+### Timeouts and retries
+
+`timeout` is passed straight to `requests`; hitting it raises `HookflowError`
+with `code="timeout"` and `status=0`. A connection-level failure raises the
+same class with `code="network_error"`.
+
+**The client does not retry.** One SDK call is exactly one HTTP request — no
+backoff, no idempotent replay, and no `urllib3` `Retry` adapter is installed.
+That is deliberate: `events.send` accepts an `idempotency_key`, so a retry
+policy belongs to the caller who knows whether reissuing the request is safe.
+What *is* retried is the delivery itself, by the platform, on the
+subscription's `retry_delays` ladder.
+
+## Authentication
+
+Every request the client makes carries `X-API-Key: <your key>` — the project
+API key, created in the dashboard or via
+`POST /api/v1/projects/{project_id}/api-keys`. The SDK never sends a bearer
+token and has no login surface: JWT-authenticated endpoints (auth, projects,
+organizations, members, API keys) are not part of it. Bootstrapping a project
+and a key is a one-time step you do with the dashboard, the CLI, or plain
+HTTP.
+
 ## Type Hints
 
 This SDK includes full type hints for better IDE support:
@@ -435,6 +511,22 @@ pytest
 docker run --rm -v $(pwd):/app -w /app python:3.11-slim sh -c "pip install -e '.[dev]' && pytest"
 ```
 
+### Live-API smoke check
+
+`pytest` stubs the transport, so it cannot see a renamed field. To drive the
+SDK against a real instance:
+
+```bash
+make up                          # from the repo root
+python scripts/live_api_smoke.py # SMOKE_API_BASE_URL overrides the target
+```
+
+It registers a throwaway org, walks endpoint → subscription → event →
+deliveries → attempts → incoming, checks each error envelope, and verifies a
+signature the running server itself produced. It is not collected by `pytest`
+(`testpaths = tests`, `python_files = test_*.py`), so the unit suite still
+passes with no backend.
+
 ## License
 
 MIT

{webhook_platform-2.2.1 → webhook_platform-2.6.0}/README.md

@@ -2,6 +2,17 @@
 
 Official Python SDK for [Hookflow](https://github.com/vadymkykalo/webhook-platform).
 
+> The PyPI distribution is `webhook-platform`; the module you import is
+> `hookflow`. `pip install webhook-platform`, then `from hookflow import ...`.
+
+**Scope.** This SDK covers Events, Endpoints, Subscriptions, Deliveries,
+Incoming Sources, Incoming Events, and webhook signature verification —
+7 of the platform's 35 API controllers. It does not wrap
+Transformations, Rules, Workflows, Schemas, DLQ, Analytics, Usage, Alerts,
+Incidents, PII rules, Audit Log, Tunnels, API keys, Members, or Projects —
+use the [Generic Requests](#generic-requests) helpers for those until the
+SDK grows to cover them.
+
 ## Installation
 
 ```bash
@@ -11,10 +22,12 @@ pip install webhook-platform
 ## Quick Start
 
 ```python
+import os
+
 from hookflow import Hookflow, Event
 
 client = Hookflow(
-    api_key="wh_live_your_api_key",
+    api_key=os.environ["HOOKFLOW_API_KEY"],  # e.g. "Kz1uAIM8VeJUQN7yGSYCst64WxNLabBHfOYbrPlJ1yk"
     base_url="http://localhost:8080",  # optional
 )
 
@@ -63,8 +76,11 @@ endpoint = client.endpoints.create(
     ),
 )
 
-# List endpoints
-endpoints = client.endpoints.list(project_id)
+# List endpoints — the API paginates this one, so the endpoints are in .content
+# (iterating the page yields them directly)
+page = client.endpoints.list(project_id, page=0, size=20)
+for endpoint in page:
+    print(endpoint.url)
 
 # Update endpoint
 client.endpoints.update(
@@ -83,6 +99,7 @@ print(f"New secret: {updated.secret}")
 # Test endpoint connectivity
 result = client.endpoints.test(project_id, endpoint_id)
 print(f"Test {'passed' if result.success else 'failed'}: {result.latency_ms}ms")
+print(f"{result.http_status_code} — {result.message}")
 ```
 
 ### Subscriptions
@@ -100,7 +117,7 @@ subscription = client.subscriptions.create(
     ),
 )
 
-# List subscriptions
+# List subscriptions — a bare list; unlike endpoints, this one is not paginated
 subscriptions = client.subscriptions.list(project_id)
 
 # Update subscription
@@ -130,7 +147,7 @@ print(f"Total failed: {deliveries.total_elements}")
 # Get delivery attempts
 attempts = client.deliveries.get_attempts(delivery_id)
 for attempt in attempts:
-    print(f"Attempt {attempt.attempt_number}: {attempt.http_status} ({attempt.latency_ms}ms)")
+    print(f"Attempt {attempt.attempt_number}: {attempt.http_status_code} ({attempt.duration_ms}ms)")
 
 # Replay failed delivery
 client.deliveries.replay(delivery_id)
@@ -245,11 +262,12 @@ def handle_webhook():
         # Option 2: Verify and parse
         event = construct_event(payload, headers, secret)
 
-        print(f"Received {event.type}: {event.data}")
-
-        # Handle the event
-        if event.type == "order.completed":
-            handle_order_completed(event.data)
+        # event.data is the parsed body; event.event_id / event.delivery_id /
+        # event.timestamp come from the X-Event-Id / X-Delivery-Id /
+        # X-Timestamp headers. See "What lands on your endpoint" below for
+        # event.type.
+        print(f"Delivery {event.delivery_id} of event {event.event_id}: {event.data}")
+        handle_order_completed(event.data)
 
         return "OK", 200
 
@@ -258,6 +276,40 @@ def handle_webhook():
         return "Invalid signature", 400
 ```
 
+### What lands on your endpoint
+
+Hookflow PUTs the event's **payload** on the wire, not an envelope. This:
+
+```python
+client.events.send(Event(type="order.completed", data={"order_id": "ord_1"}))
+```
+
+arrives at your endpoint as the ``data`` object alone —
+
+```http
+POST /webhooks HTTP/1.1
+Content-Type: application/json
+X-Signature: t=1738000000000,v1=<hex hmac-sha256>
+X-Timestamp: 1738000000000
+X-Event-Id: 6f0e…
+X-Delivery-Id: 91ab…
+X-Sequence-Number: 0
+Idempotency-Key: 6f0e…-<endpoint-id>
+
+{"order_id":"ord_1"}
+```
+
+So `construct_event` fills `event_id`, `delivery_id` and `timestamp` from the
+headers and `data` from the body, but **`type` is empty**: the event type is
+not on the wire for a default subscription. Route on the payload, on the
+endpoint you registered, or set the subscription's `payload_template` to wrap
+the event so `type` becomes part of the body.
+
+The signature is computed over `f"{timestamp}.{raw_body}"` with HMAC-SHA256 and
+the endpoint secret, and the server rejects timestamps more than **300
+seconds** old — verify against the *raw* body bytes, before any JSON parse and
+re-serialize.
+
 ### FastAPI Example
 
 ```python
@@ -298,7 +350,8 @@ from hookflow import (
 try:
     client.events.send(Event(type="test", data={}))
 except RateLimitError as e:
-    # Wait and retry
+    # retry_after_ms is milliseconds. e.rate_limit_info.reset is the raw
+    # X-RateLimit-Reset header, which the API sends in Unix *seconds*.
     print(f"Rate limited. Retry after {e.retry_after_ms}ms")
     time.sleep(e.retry_after_ms / 1000)
 except AuthenticationError:
@@ -371,12 +424,35 @@ All generic methods use the same authentication, error handling, and rate-limit
 
 ```python
 client = Hookflow(
-    api_key="wh_live_xxx",          # Required: Your API key
-    base_url="https://api.example.com",  # Optional: API base URL
+    api_key=os.environ["HOOKFLOW_API_KEY"],  # Required: Your project API key
+    base_url="https://api.example.com",  # Optional (default: http://localhost:8080)
     timeout=30,                     # Optional: Request timeout in seconds (default: 30)
 )
 ```
 
+### Timeouts and retries
+
+`timeout` is passed straight to `requests`; hitting it raises `HookflowError`
+with `code="timeout"` and `status=0`. A connection-level failure raises the
+same class with `code="network_error"`.
+
+**The client does not retry.** One SDK call is exactly one HTTP request — no
+backoff, no idempotent replay, and no `urllib3` `Retry` adapter is installed.
+That is deliberate: `events.send` accepts an `idempotency_key`, so a retry
+policy belongs to the caller who knows whether reissuing the request is safe.
+What *is* retried is the delivery itself, by the platform, on the
+subscription's `retry_delays` ladder.
+
+## Authentication
+
+Every request the client makes carries `X-API-Key: <your key>` — the project
+API key, created in the dashboard or via
+`POST /api/v1/projects/{project_id}/api-keys`. The SDK never sends a bearer
+token and has no login surface: JWT-authenticated endpoints (auth, projects,
+organizations, members, API keys) are not part of it. Bootstrapping a project
+and a key is a one-time step you do with the dashboard, the CLI, or plain
+HTTP.
+
 ## Type Hints
 
 This SDK includes full type hints for better IDE support:
@@ -406,6 +482,22 @@ pytest
 docker run --rm -v $(pwd):/app -w /app python:3.11-slim sh -c "pip install -e '.[dev]' && pytest"
 ```
 
+### Live-API smoke check
+
+`pytest` stubs the transport, so it cannot see a renamed field. To drive the
+SDK against a real instance:
+
+```bash
+make up                          # from the repo root
+python scripts/live_api_smoke.py # SMOKE_API_BASE_URL overrides the target
+```
+
+It registers a throwaway org, walks endpoint → subscription → event →
+deliveries → attempts → incoming, checks each error envelope, and verifies a
+signature the running server itself produced. It is not collected by `pytest`
+(`testpaths = tests`, `python_files = test_*.py`), so the unit suite still
+passes with no backend.
+
 ## License
 
 MIT

{webhook_platform-2.2.1 → webhook_platform-2.6.0}/hookflow/__init__.py

@@ -36,7 +36,7 @@ from .types import (
     ReplayEventResponse,
 )
 
-__version__ = "2.2.1"
+__version__ = "2.6.0"
 
 # Backward-compatible aliases
 WebhookPlatform = Hookflow

{webhook_platform-2.2.1 → webhook_platform-2.6.0}/hookflow/client.py

@@ -37,7 +37,7 @@ from .errors import (
 
 DEFAULT_BASE_URL = "http://localhost:8080"
 DEFAULT_TIMEOUT = 30
-SDK_VERSION = "2.2.1"
+SDK_VERSION = "2.6.0"
 
 
 class Hookflow:
@@ -165,8 +165,10 @@ class Hookflow:
             return NotFoundError(message)
         elif status == 429:
             import time
+            # `reset` is a Unix timestamp in seconds (see RateLimitInfo), so the
+            # fallback has to be in seconds too.
             info = rate_limit_info or RateLimitInfo(
-                limit=0, remaining=0, reset=int(time.time() * 1000) + 60000
+                limit=0, remaining=0, reset=int(time.time()) + 60
             )
             return RateLimitError(message, info)
         elif status == 400:
@@ -217,13 +219,21 @@ class Endpoints:
         )
         return Endpoint.from_dict(data)
 
-    def list(self, project_id: str) -> List[Endpoint]:
-        """List all endpoints for a project."""
+    def list(
+        self, project_id: str, page: int = 0, size: int = 20
+    ) -> PaginatedResponse:
+        """List a project's endpoints.
+
+        The API returns a Spring page envelope here, not a bare array — the
+        endpoints themselves are in ``.content`` (iterating the page yields
+        them directly).
+        """
         data = self._client._request(
             "GET",
             f"/api/v1/projects/{project_id}/endpoints",
+            params={"page": page, "size": size},
         )
-        return [Endpoint.from_dict(e) for e in data]
+        return PaginatedResponse.from_dict(data, Endpoint)
 
     def update(
         self, project_id: str, endpoint_id: str, params: EndpointUpdateParams
@@ -305,6 +315,7 @@ class Subscriptions:
         retry_delays: Optional[str] = None,
         payload_template: Optional[str] = None,
         custom_headers: Optional[str] = None,
+        transformation_id: Optional[str] = None,
     ) -> Subscription:
         """Update subscription."""
         body: Dict[str, Any] = {}
@@ -324,6 +335,8 @@ class Subscriptions:
             body["payloadTemplate"] = payload_template
         if custom_headers is not None:
             body["customHeaders"] = custom_headers
+        if transformation_id is not None:
+            body["transformationId"] = transformation_id
 
         data = self._client._request(
             "PUT",

{webhook_platform-2.2.1 → webhook_platform-2.6.0}/hookflow/errors.py

@@ -35,10 +35,15 @@ class RateLimitError(HookflowError):
 
     @property
     def retry_after_ms(self) -> int:
-        """Milliseconds to wait before retrying."""
+        """Milliseconds to wait before retrying.
+
+        ``rate_limit_info.reset`` is the raw ``X-RateLimit-Reset`` header, which
+        the API sends as a Unix timestamp in **seconds**; subtracting a
+        millisecond clock from it directly always yields 0.
+        """
         import time
         now_ms = int(time.time() * 1000)
-        return max(0, self.rate_limit_info.reset - now_ms)
+        return max(0, self.rate_limit_info.reset * 1000 - now_ms)
 
 
 class ValidationError(HookflowError):