form4api 0.10.0__tar.gz → 0.11.0__tar.gz

{form4api-0.10.0 → form4api-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: form4api
-Version: 0.10.0
+Version: 0.11.0
 Summary: Python client for the Form4API — real-time SEC Form 4 insider trading, Form 144 intent-to-sell, institutional 13F-HR, and congressional STOCK Act trading data, including the insider/Congress convergence signal
 License-Expression: MIT
 Project-URL: Homepage, https://www.form4api.com
@@ -94,7 +94,7 @@ asyncio.run(main())
 | `client.stats` | `.get()` — public, no key required |
 | `client.data_quality` | `.get()` — public, no key required |
 | `client.status` | `.history()` — takes no parameters |
-| `client.webhooks` | `.create(url, event_types, auth_header=None)`, `.list()`, `.delete(id)`, `.events(**params)`, `.enable(id)`, `.test(id)`, `.set_auth_header(id, name, value)`, `.delete_auth_header(id)` |
+| `client.webhooks` | `.create(url, event_types, auth_header=None)`, `.list()`, `.update(id, url)`, `.delete(id)`, `.events(**params)`, `.enable(id)`, `.test(id)`, `.set_auth_header(id, name, value)`, `.delete_auth_header(id)` |
 | `verify_webhook(body, signature, secret)` | Top-level function (not on the client) that checks the `X-Insider-Signature` header on a delivery |
 
 **Congress date quality.** Each congress trade (and convergence leg) has
@@ -234,6 +234,7 @@ sub = client.webhooks.create(
 )
 print(sub.secret)  # shown once; store it
 
+client.webhooks.update(sub.subscription_id, "https://example.com/new-hook")  # change the URL; returns WebhookSubscription incl. url_warning
 client.webhooks.test(sub.subscription_id)      # WebhookTestResult(delivered, status_code, duration_ms, error)
 client.webhooks.enable(sub.subscription_id)    # undo an auto-disable (disabled_reason == "delivery_failures")
 client.webhooks.set_auth_header(sub.subscription_id, "Authorization", "Bearer new")
@@ -262,6 +263,24 @@ body. `CongressTradeFiled` and `ConvergenceSignal` carry the full event body.
 write-only and never returned. `webhooks.test()` reports a failed send as
 `delivered=False` with an `error`, it does not raise.
 
+**Moving a webhook to a new URL.** `update(id, url)` changes the delivery URL
+and keeps the id, secret, event types and auth header. It does not re-enable a
+subscription the system disabled, so call `enable(id)` afterwards if needed.
+The `last_*` health fields come back `None` because they described the old URL.
+
+```python
+# Started on a tunnel, now moving to a stable endpoint
+moved = client.webhooks.update(sub.subscription_id, "https://example.com/hooks/form4api")
+if not moved.is_active:
+    client.webhooks.enable(moved.subscription_id)
+```
+
+**`url_warning`.** `create()`, `update()` and each `list()` item carry
+`url_warning`: a string when the URL's host is a temporary tunnel or test host
+(trycloudflare, ngrok, webhook.site, loca.lt, serveo), otherwise `None`. It is a
+warning only; the subscription is saved either way, and deliveries stop when the
+tunnel closes. URLs over 500 characters are rejected with 400 `INVALID_URL`.
+
 **Verifying deliveries.** Each delivery carries
 `X-Insider-Signature: sha256=<hex HMAC-SHA256(secret, raw body)>`. Verify it
 against the raw request body, before parsing JSON:

{form4api-0.10.0 → form4api-0.11.0}/README.md

@@ -75,7 +75,7 @@ asyncio.run(main())
 | `client.stats` | `.get()` — public, no key required |
 | `client.data_quality` | `.get()` — public, no key required |
 | `client.status` | `.history()` — takes no parameters |
-| `client.webhooks` | `.create(url, event_types, auth_header=None)`, `.list()`, `.delete(id)`, `.events(**params)`, `.enable(id)`, `.test(id)`, `.set_auth_header(id, name, value)`, `.delete_auth_header(id)` |
+| `client.webhooks` | `.create(url, event_types, auth_header=None)`, `.list()`, `.update(id, url)`, `.delete(id)`, `.events(**params)`, `.enable(id)`, `.test(id)`, `.set_auth_header(id, name, value)`, `.delete_auth_header(id)` |
 | `verify_webhook(body, signature, secret)` | Top-level function (not on the client) that checks the `X-Insider-Signature` header on a delivery |
 
 **Congress date quality.** Each congress trade (and convergence leg) has
@@ -215,6 +215,7 @@ sub = client.webhooks.create(
 )
 print(sub.secret)  # shown once; store it
 
+client.webhooks.update(sub.subscription_id, "https://example.com/new-hook")  # change the URL; returns WebhookSubscription incl. url_warning
 client.webhooks.test(sub.subscription_id)      # WebhookTestResult(delivered, status_code, duration_ms, error)
 client.webhooks.enable(sub.subscription_id)    # undo an auto-disable (disabled_reason == "delivery_failures")
 client.webhooks.set_auth_header(sub.subscription_id, "Authorization", "Bearer new")
@@ -243,6 +244,24 @@ body. `CongressTradeFiled` and `ConvergenceSignal` carry the full event body.
 write-only and never returned. `webhooks.test()` reports a failed send as
 `delivered=False` with an `error`, it does not raise.
 
+**Moving a webhook to a new URL.** `update(id, url)` changes the delivery URL
+and keeps the id, secret, event types and auth header. It does not re-enable a
+subscription the system disabled, so call `enable(id)` afterwards if needed.
+The `last_*` health fields come back `None` because they described the old URL.
+
+```python
+# Started on a tunnel, now moving to a stable endpoint
+moved = client.webhooks.update(sub.subscription_id, "https://example.com/hooks/form4api")
+if not moved.is_active:
+    client.webhooks.enable(moved.subscription_id)
+```
+
+**`url_warning`.** `create()`, `update()` and each `list()` item carry
+`url_warning`: a string when the URL's host is a temporary tunnel or test host
+(trycloudflare, ngrok, webhook.site, loca.lt, serveo), otherwise `None`. It is a
+warning only; the subscription is saved either way, and deliveries stop when the
+tunnel closes. URLs over 500 characters are rejected with 400 `INVALID_URL`.
+
 **Verifying deliveries.** Each delivery carries
 `X-Insider-Signature: sha256=<hex HMAC-SHA256(secret, raw body)>`. Verify it
 against the raw request body, before parsing JSON:

{form4api-0.10.0 → form4api-0.11.0}/form4api/_client.py

@@ -158,6 +158,10 @@ class Form4ApiClient:
         res = self._request("PUT", path, json=body)
         return _normalise(self._parse(res))
 
+    def _patch(self, path: str, body: Any = None) -> Any:
+        res = self._request("PATCH", path, json=body)
+        return _normalise(self._parse(res))
+
     def _delete(self, path: str) -> None:
         res = self._request("DELETE", path)
         if not res.is_success and res.status_code != 204:
@@ -290,6 +294,10 @@ class AsyncForm4ApiClient:
         res = await self._request("PUT", path, json=body)
         return _normalise(self._parse(res))
 
+    async def _patch(self, path: str, body: Any = None) -> Any:
+        res = await self._request("PATCH", path, json=body)
+        return _normalise(self._parse(res))
+
     async def _delete(self, path: str) -> None:
         res = await self._request("DELETE", path)
         if not res.is_success and res.status_code != 204:

{form4api-0.10.0 → form4api-0.11.0}/form4api/_generated.py

@@ -1377,6 +1377,21 @@ class TransactionResponse:
         return cls(**kwargs)
 
 
+@dataclass
+class UpdateWebhookRequest:
+    url: str | None = None
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "UpdateWebhookRequest":
+        """Build from an API payload, ignoring unknown keys.
+
+        Constructing with **data directly (as the hand-written resources do)
+        means the SDK raises TypeError the moment the backend adds a field.
+        Filtering keeps older SDK versions working against a newer API."""
+        known = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
 @dataclass
 class UptimeDayBucket:
     date: str | None = None

{form4api-0.10.0 → form4api-0.11.0}/form4api/_types.py

@@ -194,6 +194,10 @@ class WebhookCreated(_FromDictMixin):
     # events are still delivered). The auth header VALUE is never returned.
     is_read_only: bool | None = None
     auth_header_name: str | None = None
+    # Added 0.11.0. A string when the URL's host is a temporary tunnel or test
+    # host (ngrok, trycloudflare, webhook.site, ...), otherwise None. A warning
+    # only; the subscription is created either way.
+    url_warning: str | None = None
 
 
 @dataclass
@@ -215,6 +219,8 @@ class WebhookSubscription(_FromDictMixin):
     last_status_code: int | None = None
     last_error_class: str | None = None
     auth_header_name: str | None = None
+    # Added 0.11.0. Same meaning as on WebhookCreated; also returned by update().
+    url_warning: str | None = None
 
 
 @dataclass

{form4api-0.10.0 → form4api-0.11.0}/form4api/resources/_webhooks.py

@@ -47,6 +47,19 @@ class WebhooksResource:
         data = self._client._get("/v1/webhooks")
         return [WebhookSubscription._from_dict(item) for item in data]
 
+    def update(self, subscription_id: int, url: str) -> WebhookSubscription:
+        """Change the delivery URL of a subscription, keeping its id, secret,
+        event types and auth header. The URL is checked like `create` (HTTPS,
+        public address, at most 500 characters); a bad URL raises `Form4ApiError`
+        (HTTP 400) with `error_code` INVALID_REQUEST, INVALID_URL, INSECURE_URL,
+        PRIVATE_ADDRESS or UNRESOLVABLE_HOST. Works on active and auto-disabled
+        subscriptions but does NOT re-enable a disabled one: call `enable()`
+        afterwards. The `last_*` health fields come back `None` because they
+        described the old URL. Shares the 3-per-minute webhook budget with
+        `create`. All plans."""
+        data = self._client._patch(f"/v1/webhooks/{subscription_id}", {"url": url})
+        return WebhookSubscription._from_dict(data)
+
     def delete(self, subscription_id: int) -> None:
         self._client._delete(f"/v1/webhooks/{subscription_id}")
 
@@ -101,6 +114,11 @@ class AsyncWebhooksResource:
         data = await self._client._get("/v1/webhooks")
         return [WebhookSubscription._from_dict(item) for item in data]
 
+    async def update(self, subscription_id: int, url: str) -> WebhookSubscription:
+        """See `WebhooksResource.update`."""
+        data = await self._client._patch(f"/v1/webhooks/{subscription_id}", {"url": url})
+        return WebhookSubscription._from_dict(data)
+
     async def delete(self, subscription_id: int) -> None:
         await self._client._delete(f"/v1/webhooks/{subscription_id}")
 

{form4api-0.10.0 → form4api-0.11.0}/form4api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: form4api
-Version: 0.10.0
+Version: 0.11.0
 Summary: Python client for the Form4API — real-time SEC Form 4 insider trading, Form 144 intent-to-sell, institutional 13F-HR, and congressional STOCK Act trading data, including the insider/Congress convergence signal
 License-Expression: MIT
 Project-URL: Homepage, https://www.form4api.com
@@ -94,7 +94,7 @@ asyncio.run(main())
 | `client.stats` | `.get()` — public, no key required |
 | `client.data_quality` | `.get()` — public, no key required |
 | `client.status` | `.history()` — takes no parameters |
-| `client.webhooks` | `.create(url, event_types, auth_header=None)`, `.list()`, `.delete(id)`, `.events(**params)`, `.enable(id)`, `.test(id)`, `.set_auth_header(id, name, value)`, `.delete_auth_header(id)` |
+| `client.webhooks` | `.create(url, event_types, auth_header=None)`, `.list()`, `.update(id, url)`, `.delete(id)`, `.events(**params)`, `.enable(id)`, `.test(id)`, `.set_auth_header(id, name, value)`, `.delete_auth_header(id)` |
 | `verify_webhook(body, signature, secret)` | Top-level function (not on the client) that checks the `X-Insider-Signature` header on a delivery |
 
 **Congress date quality.** Each congress trade (and convergence leg) has
@@ -234,6 +234,7 @@ sub = client.webhooks.create(
 )
 print(sub.secret)  # shown once; store it
 
+client.webhooks.update(sub.subscription_id, "https://example.com/new-hook")  # change the URL; returns WebhookSubscription incl. url_warning
 client.webhooks.test(sub.subscription_id)      # WebhookTestResult(delivered, status_code, duration_ms, error)
 client.webhooks.enable(sub.subscription_id)    # undo an auto-disable (disabled_reason == "delivery_failures")
 client.webhooks.set_auth_header(sub.subscription_id, "Authorization", "Bearer new")
@@ -262,6 +263,24 @@ body. `CongressTradeFiled` and `ConvergenceSignal` carry the full event body.
 write-only and never returned. `webhooks.test()` reports a failed send as
 `delivered=False` with an `error`, it does not raise.
 
+**Moving a webhook to a new URL.** `update(id, url)` changes the delivery URL
+and keeps the id, secret, event types and auth header. It does not re-enable a
+subscription the system disabled, so call `enable(id)` afterwards if needed.
+The `last_*` health fields come back `None` because they described the old URL.
+
+```python
+# Started on a tunnel, now moving to a stable endpoint
+moved = client.webhooks.update(sub.subscription_id, "https://example.com/hooks/form4api")
+if not moved.is_active:
+    client.webhooks.enable(moved.subscription_id)
+```
+
+**`url_warning`.** `create()`, `update()` and each `list()` item carry
+`url_warning`: a string when the URL's host is a temporary tunnel or test host
+(trycloudflare, ngrok, webhook.site, loca.lt, serveo), otherwise `None`. It is a
+warning only; the subscription is saved either way, and deliveries stop when the
+tunnel closes. URLs over 500 characters are rejected with 400 `INVALID_URL`.
+
 **Verifying deliveries.** Each delivery carries
 `X-Insider-Signature: sha256=<hex HMAC-SHA256(secret, raw body)>`. Verify it
 against the raw request body, before parsing JSON:

{form4api-0.10.0 → form4api-0.11.0}/form4api.egg-info/SOURCES.txt

@@ -22,4 +22,5 @@ tests/test_client.py
 tests/test_generated.py
 tests/test_method_name.py
 tests/test_release_0_10_0.py
+tests/test_release_0_11_0.py
 tests/test_unknown_fields.py

{form4api-0.10.0 → form4api-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "form4api"
-version = "0.10.0"
+version = "0.11.0"
 description = "Python client for the Form4API — real-time SEC Form 4 insider trading, Form 144 intent-to-sell, institutional 13F-HR, and congressional STOCK Act trading data, including the insider/Congress convergence signal"
 keywords = ["insider-trading", "sec", "sec-edgar", "edgar", "form-4", "form4", "form-144", "13f", "13f-hr", "congress", "stock-act", "financial-data", "stock-market", "stocks", "fintech", "api", "sdk", "webhooks", "form4api"]
 requires-python = ">=3.11"

form4api-0.11.0/tests/test_release_0_11_0.py

@@ -0,0 +1,149 @@
+"""0.11.0 surface: webhooks.update(id, url) and url_warning, sync and async."""
+import asyncio
+import json
+
+import httpx
+import pytest
+import respx
+
+from form4api import Form4ApiClient
+from form4api._client import AsyncForm4ApiClient
+from form4api._errors import Form4ApiError, NotFoundError
+
+BASE = "https://api.form4api.com"
+UNKNOWN = {"somethingNewFromTheBackend": 1}
+
+
+def client() -> Form4ApiClient:
+    return Form4ApiClient("test-key", max_retries=0)
+
+
+def aclient() -> AsyncForm4ApiClient:
+    return AsyncForm4ApiClient("test-key", max_retries=0)
+
+
+SUB = {
+    "subscriptionId": 7,
+    "url": "https://abc.ngrok.io/h",
+    "eventTypes": ["ClusterBuy"],
+    "createdAt": "2026-10-01T00:00:00",
+    "isActive": False,
+    "isReadOnly": False,
+    "disabledAt": "2026-10-05T00:00:00",
+    "disabledReason": "delivery_failures",
+    "lastAttemptAt": None,
+    "lastSuccessAt": None,
+    "lastStatusCode": None,
+    "lastErrorClass": None,
+    "authHeaderName": None,
+    "urlWarning": "Temporary tunnel host",
+    **UNKNOWN,
+}
+
+
+@respx.mock
+def test_update_sends_patch_with_url_and_returns_parsed_row():
+    route = respx.patch(f"{BASE}/v1/webhooks/7").mock(return_value=httpx.Response(200, json=SUB))
+    sub = client().webhooks.update(7, "https://abc.ngrok.io/h")
+    req = route.calls.last.request
+    assert req.method == "PATCH"
+    assert req.url.path == "/v1/webhooks/7"
+    assert json.loads(req.content) == {"url": "https://abc.ngrok.io/h"}
+    assert sub.subscription_id == 7
+    assert sub.url == "https://abc.ngrok.io/h"
+    assert sub.url_warning == "Temporary tunnel host"
+    assert sub.disabled_reason == "delivery_failures"
+    assert sub.last_attempt_at is None
+
+
+@respx.mock
+def test_update_400_raises_with_error_code():
+    respx.patch(f"{BASE}/v1/webhooks/7").mock(
+        return_value=httpx.Response(
+            400, json={"error": {"code": "INSECURE_URL", "message": "URL must use HTTPS"}}
+        )
+    )
+    with pytest.raises(Form4ApiError) as exc:
+        client().webhooks.update(7, "http://example.com/h")
+    assert exc.value.status_code == 400
+    assert exc.value.error_code == "INSECURE_URL"
+
+
+@respx.mock
+def test_update_404_raises_not_found():
+    respx.patch(f"{BASE}/v1/webhooks/99").mock(
+        return_value=httpx.Response(404, json={"error": {"code": "NOT_FOUND", "message": "nope"}})
+    )
+    with pytest.raises(NotFoundError):
+        client().webhooks.update(99, "https://example.com/h")
+
+
+@respx.mock
+def test_update_async_sends_patch_and_parses():
+    route = respx.patch(f"{BASE}/v1/webhooks/7").mock(return_value=httpx.Response(200, json=SUB))
+
+    async def run():
+        c = aclient()
+        try:
+            return await c.webhooks.update(7, "https://abc.ngrok.io/h")
+        finally:
+            await c.close()
+
+    sub = asyncio.run(run())
+    req = route.calls.last.request
+    assert req.method == "PATCH"
+    assert json.loads(req.content) == {"url": "https://abc.ngrok.io/h"}
+    assert sub.url_warning == "Temporary tunnel host"
+
+
+@respx.mock
+def test_update_async_400_raises_with_error_code():
+    respx.patch(f"{BASE}/v1/webhooks/7").mock(
+        return_value=httpx.Response(
+            400, json={"error": {"code": "PRIVATE_ADDRESS", "message": "private"}}
+        )
+    )
+
+    async def run():
+        c = aclient()
+        try:
+            await c.webhooks.update(7, "https://10.0.0.1/h")
+        finally:
+            await c.close()
+
+    with pytest.raises(Form4ApiError) as exc:
+        asyncio.run(run())
+    assert exc.value.error_code == "PRIVATE_ADDRESS"
+
+
+@respx.mock
+def test_url_warning_parses_on_create():
+    respx.post(f"{BASE}/v1/webhooks").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "subscriptionId": 8,
+                "url": "https://x.trycloudflare.com/h",
+                "eventTypes": ["ClusterBuy"],
+                "secret": "s",
+                "createdAt": "2026-10-13T00:00:00",
+                "warning": "Store the secret securely",
+                "urlWarning": "Temporary tunnel host",
+                **UNKNOWN,
+            },
+        )
+    )
+    created = client().webhooks.create("https://x.trycloudflare.com/h", ["ClusterBuy"])
+    assert created.url_warning == "Temporary tunnel host"
+
+
+@respx.mock
+def test_url_warning_parses_on_list_and_defaults_to_none_for_old_payloads():
+    old = {k: v for k, v in SUB.items() if k != "urlWarning"}
+    respx.get(f"{BASE}/v1/webhooks").mock(
+        return_value=httpx.Response(200, json=[SUB, {**old, "subscriptionId": 9}, {**SUB, "subscriptionId": 10, "urlWarning": None}])
+    )
+    subs = client().webhooks.list()
+    assert subs[0].url_warning == "Temporary tunnel host"
+    assert subs[1].url_warning is None
+    assert subs[2].url_warning is None