form4api 0.8.0__tar.gz → 0.9.0__tar.gz

{form4api-0.8.0 → form4api-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: form4api
-Version: 0.8.0
+Version: 0.9.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
@@ -81,6 +81,7 @@ asyncio.run(main())
 
 | Resource | Methods |
 |---|---|
+| `client.search(q, limit=None)` | Combined company + insider lookup — not namespaced under a resource |
 | `client.transactions` | `.list(**params)`, `.paginate(**params)` |
 | `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.list(**params)`, `.directory(**params)`, `.transactions(cik, **params)`, `.summary(cik)` *(Pro)*, `.scorecard(cik)` *(Pro)*, `.leaderboard(**params)` *(Business)* |
 | `client.companies` | `.get(ticker)`, `.insiders(ticker)`, `.list(**params)` |
@@ -94,6 +95,19 @@ asyncio.run(main())
 | `client.status` | `.history(**params)` |
 | `client.webhooks` | `.create(url, event_types)`, `.list()`, `.delete(id)`, `.events(**params)` |
 
+**Congress date quality.** Each congress trade (and convergence leg) has
+`disclosure_lag_days: int | None` and `date_quality: str | None`. When the
+filing's own dates are impossible or implausible, the lag is `None` and
+`date_quality` is one of `"transaction_after_disclosure"`,
+`"future_transaction_date"` or `"implausible_lag"`; the raw dates are still
+returned. A lag over 45 days is not a legal finding.
+
+```python
+for t in client.congress.trades(ticker="NVDA"):
+    lag = f"dates unreliable ({t.date_quality})" if t.disclosure_lag_days is None else f"{t.disclosure_lag_days}d"
+    print(t.politician.full_name, t.transaction_date, lag)
+```
+
 Every plan-gated endpoint the API exposes has a typed method here. Calling one
 your key isn't entitled to raises `PlanError` (HTTP 402) carrying
 `required_plan`, `current_plan`, and `upgrade_url` rather than failing opaquely.
@@ -191,6 +205,27 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 | `state_of_incorporation` | `str \| None` | Two-letter state code |
 | `website` | `str \| None` | Company website as filed with SEC |
 
+### Search
+
+`client.search(q, limit=None)` looks up companies and insiders by name or
+ticker in a single call — useful for a combined search box where you don't
+know in advance whether the user typed a ticker or a person's name. `q` must
+be 2-64 characters; outside that range the API returns HTTP 400 and the SDK
+raises `Form4ApiError` with `error_code` `"QUERY_TOO_SHORT"` or
+`"QUERY_TOO_LONG"`. Insider matching is whitespace-tokenised, so `"tim cook"`
+matches an insider named `"Cook Timothy D"`. `limit` caps the number of
+results per array (1-20, API default 8).
+
+```python
+result = client.search("tim cook")
+for c in result.companies:
+    print(c.ticker, c.name, c.cik)
+for i in result.insiders:
+    # i.ticker is a ticker associated with the insider and may be None —
+    # its exact meaning is still settling on the backend.
+    print(i.cik, i.name, i.title, i.ticker)
+```
+
 ### Pagination
 
 `paginate()` pages through the data until it runs out (a short or empty page)

{form4api-0.8.0 → form4api-0.9.0}/README.md

@@ -62,6 +62,7 @@ asyncio.run(main())
 
 | Resource | Methods |
 |---|---|
+| `client.search(q, limit=None)` | Combined company + insider lookup — not namespaced under a resource |
 | `client.transactions` | `.list(**params)`, `.paginate(**params)` |
 | `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.list(**params)`, `.directory(**params)`, `.transactions(cik, **params)`, `.summary(cik)` *(Pro)*, `.scorecard(cik)` *(Pro)*, `.leaderboard(**params)` *(Business)* |
 | `client.companies` | `.get(ticker)`, `.insiders(ticker)`, `.list(**params)` |
@@ -75,6 +76,19 @@ asyncio.run(main())
 | `client.status` | `.history(**params)` |
 | `client.webhooks` | `.create(url, event_types)`, `.list()`, `.delete(id)`, `.events(**params)` |
 
+**Congress date quality.** Each congress trade (and convergence leg) has
+`disclosure_lag_days: int | None` and `date_quality: str | None`. When the
+filing's own dates are impossible or implausible, the lag is `None` and
+`date_quality` is one of `"transaction_after_disclosure"`,
+`"future_transaction_date"` or `"implausible_lag"`; the raw dates are still
+returned. A lag over 45 days is not a legal finding.
+
+```python
+for t in client.congress.trades(ticker="NVDA"):
+    lag = f"dates unreliable ({t.date_quality})" if t.disclosure_lag_days is None else f"{t.disclosure_lag_days}d"
+    print(t.politician.full_name, t.transaction_date, lag)
+```
+
 Every plan-gated endpoint the API exposes has a typed method here. Calling one
 your key isn't entitled to raises `PlanError` (HTTP 402) carrying
 `required_plan`, `current_plan`, and `upgrade_url` rather than failing opaquely.
@@ -172,6 +186,27 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 | `state_of_incorporation` | `str \| None` | Two-letter state code |
 | `website` | `str \| None` | Company website as filed with SEC |
 
+### Search
+
+`client.search(q, limit=None)` looks up companies and insiders by name or
+ticker in a single call — useful for a combined search box where you don't
+know in advance whether the user typed a ticker or a person's name. `q` must
+be 2-64 characters; outside that range the API returns HTTP 400 and the SDK
+raises `Form4ApiError` with `error_code` `"QUERY_TOO_SHORT"` or
+`"QUERY_TOO_LONG"`. Insider matching is whitespace-tokenised, so `"tim cook"`
+matches an insider named `"Cook Timothy D"`. `limit` caps the number of
+results per array (1-20, API default 8).
+
+```python
+result = client.search("tim cook")
+for c in result.companies:
+    print(c.ticker, c.name, c.cik)
+for i in result.insiders:
+    # i.ticker is a ticker associated with the insider and may be None —
+    # its exact meaning is still settling on the backend.
+    print(i.cik, i.name, i.title, i.ticker)
+```
+
 ### Pagination
 
 `paginate()` pages through the data until it runs out (a short or empty page)

{form4api-0.8.0 → form4api-0.9.0}/form4api/__init__.py

@@ -12,6 +12,9 @@ from form4api._types import (
     Insider,
     InsiderSignal,
     InstitutionalOwnership,
+    SearchCompany,
+    SearchInsider,
+    SearchResults,
     TopHolder,
     Transaction,
     WebhookCreated,
@@ -34,6 +37,9 @@ __all__ = [
     "Company",
     "InsiderSignal",
     "InstitutionalOwnership",
+    "SearchCompany",
+    "SearchInsider",
+    "SearchResults",
     "TopHolder",
     "WebhookCreated",
     "WebhookEvent",

{form4api-0.8.0 → form4api-0.9.0}/form4api/_client.py

@@ -9,6 +9,7 @@ from typing import Any, TypeVar
 import httpx
 
 from form4api._errors import AuthError, Form4ApiError, NotFoundError, PlanError, RateLimitError
+from form4api._types import SearchResults
 
 # Sent as the User-Agent so the backend can attribute traffic to the Python SDK
 # channel (the admin dashboard buckets by client). Read from installed package
@@ -105,6 +106,22 @@ class Form4ApiClient:
     def close(self) -> None:
         self._http.close()
 
+    def search(self, q: str, limit: int | None = None) -> SearchResults:
+        """Search companies and insiders by name or ticker in one call.
+
+        ``q`` must be 2-64 characters, or the API raises `Form4ApiError`
+        (HTTP 400) with `error_code` `QUERY_TOO_SHORT` or `QUERY_TOO_LONG`.
+        Insider matching is whitespace-tokenised, so `"tim cook"` matches an
+        insider named `"Cook Timothy D"`. `limit` caps the number of results
+        per array (1-20, API default 8) and defaults to the API's own default
+        when omitted. Free tier, no plan gate.
+        """
+        params: dict[str, str] = {"q": q}
+        if limit is not None:
+            params["limit"] = str(limit)
+        data = self._get("/v1/search", params)
+        return SearchResults._from_dict(data)
+
     def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
         url = self._base_url + path
         last_exc: Exception | None = None
@@ -224,6 +241,14 @@ class AsyncForm4ApiClient:
     async def close(self) -> None:
         await self._http.aclose()
 
+    async def search(self, q: str, limit: int | None = None) -> SearchResults:
+        """Async twin of `Form4ApiClient.search`. See there for parameter details."""
+        params: dict[str, str] = {"q": q}
+        if limit is not None:
+            params["limit"] = str(limit)
+        data = await self._get("/v1/search", params)
+        return SearchResults._from_dict(data)
+
     async def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
         url = self._base_url + path
         last_exc: Exception | None = None

{form4api-0.8.0 → form4api-0.9.0}/form4api/_generated.py

@@ -233,6 +233,7 @@ class CongressTradeDto:
     amount_low: float | None = None
     asset_name: str | None = None
     asset_type: str | None = None
+    date_quality: str | None = None
     disclosure_date: str | None = None
     disclosure_lag_days: int | None = None
     owner_type: str | None = None
@@ -260,6 +261,7 @@ class ConvergenceCongressLegDto:
     amount_high: float | None = None
     amount_low: float | None = None
     bioguide_id: str | None = None
+    date_quality: str | None = None
     disclosure_date: str | None = None
     disclosure_lag_days: int | None = None
     full_name: str | None = None
@@ -1108,6 +1110,62 @@ class ScorecardTradeRef:
         return cls(**{k: v for k, v in data.items() if k in known})
 
 
+@dataclass
+class SearchCompanyResult:
+    cik: str | None = None
+    name: str | None = None
+    ticker: str | None = None
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "SearchCompanyResult":
+        """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 SearchInsiderResult:
+    cik: str | None = None
+    name: str | None = None
+    ticker: str | None = None
+    title: str | None = None
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "SearchInsiderResult":
+        """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 SearchResponse:
+    companies: list[SearchCompanyResult] | None = None
+    insiders: list[SearchInsiderResult] | None = None
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "SearchResponse":
+        """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)}
+        kwargs = {k: v for k, v in data.items() if k in known}
+        if isinstance(kwargs.get("companies"), list):
+            kwargs["companies"] = [SearchCompanyResult._from_dict(i) if isinstance(i, dict) else i for i in kwargs["companies"]]
+        if isinstance(kwargs.get("insiders"), list):
+            kwargs["insiders"] = [SearchInsiderResult._from_dict(i) if isinstance(i, dict) else i for i in kwargs["insiders"]]
+        return cls(**kwargs)
+
+
 @dataclass
 class SentimentMonthEntry:
     buy_count: int | None = None
@@ -1445,7 +1503,7 @@ class GeneratedCongressResource:
     def trades(self, *, ticker: str | None = None, politician: str | None = None, party: str | None = None, chamber: str | None = None, state: str | None = None, transaction_type: str | None = None, min_amount: float | None = None, transaction_date_from: str | None = None, transaction_date_to: str | None = None, disclosure_date_from: str | None = None, disclosure_date_to: str | None = None, page: int | None = None, per_page: int | None = None, limit: int | None = None) -> list[CongressTradeDto]:
         """Query congressional STOCK Act trades (Free+, plan-clamped disclosure window)
 
-        Returns a paginated JSON list of congressional periodic-transaction-report trades, most recently DISCLOSED first, with non-superseded rows only (amended-away rows never appear). COVERAGE — HOUSE ONLY TODAY: every trade in this dataset comes from the U.S. House Clerk's PTR index. Senate eFD (efdsearch.senate.gov) returns 403 to datacenter traffic, so no Senate filings are ingested yet. chamber=Senate remains a valid filter but matches nothing and returns the response header X-Coverage-Note: chamber-not-covered, so an empty result is never ambiguous. Scanning by chamber should treat that header as "not covered", not as "no trades". PLAN-CLAMPED WINDOW: this endpoint is open to every plan, but how far back you can see is clamped on disclosureDate — Free sees only trades disclosed in the last 30 days, Starter the last 366 days, Pro/Business/Enterprise unlimited history. Passing an older disclosure_date_from than your plan allows does not extend the window — the floor always wins. Filters: ticker, politician (bioguideId, exact), party (free-text, case-insensitive exact match — not a fixed enum), chamber (House|Senate — see the coverage note above), state (2-letter code), transaction_type (purchase|sale|partial_sale|exchange), min_amount (range-aware — matches AmountLow >= value, never a fabricated midpoint), transaction_date_from/to, disclosure_date_from/to. Every row always carries BOTH amountLow and amountHigh (STOCK Act discloses ranges, never exact figures) and disclosureLagDays = (disclosureDate - transactionDate) — the STOCK Act allows up to 45 days of lag, so "real-time" here means minutes-after-disclosure, not minutes-after-trade. For per-politician or per-ticker rollups use GET /v1/congress/politicians, /v1/congress/politicians/{idOrSlug}, or /v1/congress/tickers/{ticker} (all Pro+). To check whether an insider cluster-buy lines up with a congressional purchase in the same ticker, use GET /v1/signals/convergence (Pro+); for the company's own profile use GET /v1/companies/{ticker} (Free). `limit` is accepted as an alias for `per_page`. Query runs live against the database — no caching."""
+        Returns a paginated JSON list of congressional periodic-transaction-report trades, most recently DISCLOSED first, with non-superseded rows only (amended-away rows never appear). COVERAGE — HOUSE ONLY TODAY: every trade in this dataset comes from the U.S. House Clerk's PTR index. Senate eFD (efdsearch.senate.gov) returns 403 to datacenter traffic, so no Senate filings are ingested yet. chamber=Senate remains a valid filter but matches nothing and returns the response header X-Coverage-Note: chamber-not-covered, so an empty result is never ambiguous. Scanning by chamber should treat that header as "not covered", not as "no trades". PLAN-CLAMPED WINDOW: this endpoint is open to every plan, but how far back you can see is clamped on disclosureDate — Free sees only trades disclosed in the last 30 days, Starter the last 366 days, Pro/Business/Enterprise unlimited history. Passing an older disclosure_date_from than your plan allows does not extend the window — the floor always wins. Filters: ticker, politician (bioguideId, exact), party (free-text, case-insensitive exact match — not a fixed enum), chamber (House|Senate — see the coverage note above), state (2-letter code), transaction_type (purchase|sale|partial_sale|exchange), min_amount (range-aware — matches AmountLow >= value, never a fabricated midpoint), transaction_date_from/to, disclosure_date_from/to. Every row always carries BOTH amountLow and amountHigh (STOCK Act discloses ranges, never exact figures) and disclosureLagDays = (disclosureDate - transactionDate) in whole days — the STOCK Act allows up to 45 days of lag, so "real-time" here means minutes-after-disclosure, not minutes-after-trade. DATE QUALITY: source dates are sometimes wrong. When a row's dates are impossible or implausible, disclosureLagDays is null and dateQuality names the reason: transaction_after_disclosure (transaction date later than disclosure date), future_transaction_date (transaction date in the future), or implausible_lag (lag above 1500 days, almost always a mistyped year). dateQuality is null on a normal row. Flagged rows are never dropped and their raw transactionDate and disclosureDate are returned unchanged. Genuine late filings with a long but plausible lag keep their disclosureLagDays. For per-politician or per-ticker rollups use GET /v1/congress/politicians, /v1/congress/politicians/{idOrSlug}, or /v1/congress/tickers/{ticker} (all Pro+). To check whether an insider cluster-buy lines up with a congressional purchase in the same ticker, use GET /v1/signals/convergence (Pro+); for the company's own profile use GET /v1/companies/{ticker} (Free). `limit` is accepted as an alias for `per_page`. Query runs live against the database — no caching."""
         params = {
             "ticker": ticker,
             "politician": politician,
@@ -1510,7 +1568,7 @@ class GeneratedAsyncCongressResource:
     async def trades(self, *, ticker: str | None = None, politician: str | None = None, party: str | None = None, chamber: str | None = None, state: str | None = None, transaction_type: str | None = None, min_amount: float | None = None, transaction_date_from: str | None = None, transaction_date_to: str | None = None, disclosure_date_from: str | None = None, disclosure_date_to: str | None = None, page: int | None = None, per_page: int | None = None, limit: int | None = None) -> list[CongressTradeDto]:
         """Query congressional STOCK Act trades (Free+, plan-clamped disclosure window)
 
-        Returns a paginated JSON list of congressional periodic-transaction-report trades, most recently DISCLOSED first, with non-superseded rows only (amended-away rows never appear). COVERAGE — HOUSE ONLY TODAY: every trade in this dataset comes from the U.S. House Clerk's PTR index. Senate eFD (efdsearch.senate.gov) returns 403 to datacenter traffic, so no Senate filings are ingested yet. chamber=Senate remains a valid filter but matches nothing and returns the response header X-Coverage-Note: chamber-not-covered, so an empty result is never ambiguous. Scanning by chamber should treat that header as "not covered", not as "no trades". PLAN-CLAMPED WINDOW: this endpoint is open to every plan, but how far back you can see is clamped on disclosureDate — Free sees only trades disclosed in the last 30 days, Starter the last 366 days, Pro/Business/Enterprise unlimited history. Passing an older disclosure_date_from than your plan allows does not extend the window — the floor always wins. Filters: ticker, politician (bioguideId, exact), party (free-text, case-insensitive exact match — not a fixed enum), chamber (House|Senate — see the coverage note above), state (2-letter code), transaction_type (purchase|sale|partial_sale|exchange), min_amount (range-aware — matches AmountLow >= value, never a fabricated midpoint), transaction_date_from/to, disclosure_date_from/to. Every row always carries BOTH amountLow and amountHigh (STOCK Act discloses ranges, never exact figures) and disclosureLagDays = (disclosureDate - transactionDate) — the STOCK Act allows up to 45 days of lag, so "real-time" here means minutes-after-disclosure, not minutes-after-trade. For per-politician or per-ticker rollups use GET /v1/congress/politicians, /v1/congress/politicians/{idOrSlug}, or /v1/congress/tickers/{ticker} (all Pro+). To check whether an insider cluster-buy lines up with a congressional purchase in the same ticker, use GET /v1/signals/convergence (Pro+); for the company's own profile use GET /v1/companies/{ticker} (Free). `limit` is accepted as an alias for `per_page`. Query runs live against the database — no caching."""
+        Returns a paginated JSON list of congressional periodic-transaction-report trades, most recently DISCLOSED first, with non-superseded rows only (amended-away rows never appear). COVERAGE — HOUSE ONLY TODAY: every trade in this dataset comes from the U.S. House Clerk's PTR index. Senate eFD (efdsearch.senate.gov) returns 403 to datacenter traffic, so no Senate filings are ingested yet. chamber=Senate remains a valid filter but matches nothing and returns the response header X-Coverage-Note: chamber-not-covered, so an empty result is never ambiguous. Scanning by chamber should treat that header as "not covered", not as "no trades". PLAN-CLAMPED WINDOW: this endpoint is open to every plan, but how far back you can see is clamped on disclosureDate — Free sees only trades disclosed in the last 30 days, Starter the last 366 days, Pro/Business/Enterprise unlimited history. Passing an older disclosure_date_from than your plan allows does not extend the window — the floor always wins. Filters: ticker, politician (bioguideId, exact), party (free-text, case-insensitive exact match — not a fixed enum), chamber (House|Senate — see the coverage note above), state (2-letter code), transaction_type (purchase|sale|partial_sale|exchange), min_amount (range-aware — matches AmountLow >= value, never a fabricated midpoint), transaction_date_from/to, disclosure_date_from/to. Every row always carries BOTH amountLow and amountHigh (STOCK Act discloses ranges, never exact figures) and disclosureLagDays = (disclosureDate - transactionDate) in whole days — the STOCK Act allows up to 45 days of lag, so "real-time" here means minutes-after-disclosure, not minutes-after-trade. DATE QUALITY: source dates are sometimes wrong. When a row's dates are impossible or implausible, disclosureLagDays is null and dateQuality names the reason: transaction_after_disclosure (transaction date later than disclosure date), future_transaction_date (transaction date in the future), or implausible_lag (lag above 1500 days, almost always a mistyped year). dateQuality is null on a normal row. Flagged rows are never dropped and their raw transactionDate and disclosureDate are returned unchanged. Genuine late filings with a long but plausible lag keep their disclosureLagDays. For per-politician or per-ticker rollups use GET /v1/congress/politicians, /v1/congress/politicians/{idOrSlug}, or /v1/congress/tickers/{ticker} (all Pro+). To check whether an insider cluster-buy lines up with a congressional purchase in the same ticker, use GET /v1/signals/convergence (Pro+); for the company's own profile use GET /v1/companies/{ticker} (Free). `limit` is accepted as an alias for `per_page`. Query runs live against the database — no caching."""
         params = {
             "ticker": ticker,
             "politician": politician,
@@ -1979,7 +2037,7 @@ class GeneratedSignalsResource:
     def convergence(self, *, ticker: str | None = None, window_days: int | None = None, lookback_days: int | None = None, page: int | None = None, per_page: int | None = None, limit: int | None = None) -> list[ConvergenceEntryDto]:
         """Insider cluster-buy x congressional-purchase convergence (Pro plan+)
 
-        Returns the tickers where an insider cluster-buy (InsiderSignal.IsClusterBuy) and at least one non-superseded congressional PURCHASE happened within window_days of EACH OTHER, restricted to convergences where the MORE RECENT of the pair's two dates is within a trailing lookback_days (so this surfaces CURRENT convergences, not ancient history). DEFINITION: for each result, insider.signalDate is the SignalDate of the qualifying cluster-buy signal with the most recent date (insider.insiderCount is that same signal's count — never summed or maxed across multiple signals), and congress is every non-superseded congressional purchase that paired with at least one qualifying cluster-buy (not every purchase in the window — only the ones that actually paired). firstSeen/lastSeen are the earliest/most recent dates among all qualifying insider and congress dates for that ticker. STRENGTH is documented arithmetic, NOT a black-box or predictive/ML score: strength = (distinct congressional purchasers among the qualifying legs) x (the representative signal's insiderCount) — a plain multiplication of two observed counts, nothing more. HONESTY: every congress leg always carries both amountLow and amountHigh (STOCK Act discloses ranges, never exact figures — never combined into a fabricated midpoint) and disclosureLagDays = (disclosureDate - transactionDate); congressional trades are disclosed up to 45 days after the actual trade under the STOCK Act, so this endpoint is detection/monitoring of what insiders AND members of Congress have DISCLOSED buying, not a claim of predictive edge, alpha, or win rate — no performance numbers are computed or implied anywhere in this response. window_days and lookback_days are both caller-overridable with clamps (see each parameter's own description for the exact bounds). Requires Pro plan or higher (402 PLAN_REQUIRED on Free/Starter). `limit` is accepted as an alias for `per_page`. Query runs live against the database — no caching."""
+        Returns the tickers where an insider cluster-buy (InsiderSignal.IsClusterBuy) and at least one non-superseded congressional PURCHASE happened within window_days of EACH OTHER, restricted to convergences where the MORE RECENT of the pair's two dates is within a trailing lookback_days (so this surfaces CURRENT convergences, not ancient history). DEFINITION: for each result, insider.signalDate is the SignalDate of the qualifying cluster-buy signal with the most recent date (insider.insiderCount is that same signal's count — never summed or maxed across multiple signals), and congress is every non-superseded congressional purchase that paired with at least one qualifying cluster-buy (not every purchase in the window — only the ones that actually paired). firstSeen/lastSeen are the earliest/most recent dates among all qualifying insider and congress dates for that ticker. STRENGTH is documented arithmetic, NOT a black-box or predictive/ML score: strength = (distinct congressional purchasers among the qualifying legs) x (the representative signal's insiderCount) — a plain multiplication of two observed counts, nothing more. HONESTY: every congress leg always carries both amountLow and amountHigh (STOCK Act discloses ranges, never exact figures — never combined into a fabricated midpoint) and disclosureLagDays = (disclosureDate - transactionDate). Congressional trades whose dates are impossible or implausible (a dateQuality flag: transaction_after_disclosure, future_transaction_date or implausible_lag) are excluded from detection, so they never appear as legs and never create a convergence; dateQuality is therefore null on every leg returned here and disclosureLagDays is always set. Congressional trades are disclosed up to 45 days after the actual trade under the STOCK Act, so this endpoint is detection/monitoring of what insiders AND members of Congress have DISCLOSED buying, not a claim of predictive edge, alpha, or win rate — no performance numbers are computed or implied anywhere in this response. window_days and lookback_days are both caller-overridable with clamps (see each parameter's own description for the exact bounds). Requires Pro plan or higher (402 PLAN_REQUIRED on Free/Starter). `limit` is accepted as an alias for `per_page`. Query runs live against the database — no caching."""
         params = {
             "ticker": ticker,
             "window_days": window_days,
@@ -2022,7 +2080,7 @@ class GeneratedAsyncSignalsResource:
     async def convergence(self, *, ticker: str | None = None, window_days: int | None = None, lookback_days: int | None = None, page: int | None = None, per_page: int | None = None, limit: int | None = None) -> list[ConvergenceEntryDto]:
         """Insider cluster-buy x congressional-purchase convergence (Pro plan+)
 
-        Returns the tickers where an insider cluster-buy (InsiderSignal.IsClusterBuy) and at least one non-superseded congressional PURCHASE happened within window_days of EACH OTHER, restricted to convergences where the MORE RECENT of the pair's two dates is within a trailing lookback_days (so this surfaces CURRENT convergences, not ancient history). DEFINITION: for each result, insider.signalDate is the SignalDate of the qualifying cluster-buy signal with the most recent date (insider.insiderCount is that same signal's count — never summed or maxed across multiple signals), and congress is every non-superseded congressional purchase that paired with at least one qualifying cluster-buy (not every purchase in the window — only the ones that actually paired). firstSeen/lastSeen are the earliest/most recent dates among all qualifying insider and congress dates for that ticker. STRENGTH is documented arithmetic, NOT a black-box or predictive/ML score: strength = (distinct congressional purchasers among the qualifying legs) x (the representative signal's insiderCount) — a plain multiplication of two observed counts, nothing more. HONESTY: every congress leg always carries both amountLow and amountHigh (STOCK Act discloses ranges, never exact figures — never combined into a fabricated midpoint) and disclosureLagDays = (disclosureDate - transactionDate); congressional trades are disclosed up to 45 days after the actual trade under the STOCK Act, so this endpoint is detection/monitoring of what insiders AND members of Congress have DISCLOSED buying, not a claim of predictive edge, alpha, or win rate — no performance numbers are computed or implied anywhere in this response. window_days and lookback_days are both caller-overridable with clamps (see each parameter's own description for the exact bounds). Requires Pro plan or higher (402 PLAN_REQUIRED on Free/Starter). `limit` is accepted as an alias for `per_page`. Query runs live against the database — no caching."""
+        Returns the tickers where an insider cluster-buy (InsiderSignal.IsClusterBuy) and at least one non-superseded congressional PURCHASE happened within window_days of EACH OTHER, restricted to convergences where the MORE RECENT of the pair's two dates is within a trailing lookback_days (so this surfaces CURRENT convergences, not ancient history). DEFINITION: for each result, insider.signalDate is the SignalDate of the qualifying cluster-buy signal with the most recent date (insider.insiderCount is that same signal's count — never summed or maxed across multiple signals), and congress is every non-superseded congressional purchase that paired with at least one qualifying cluster-buy (not every purchase in the window — only the ones that actually paired). firstSeen/lastSeen are the earliest/most recent dates among all qualifying insider and congress dates for that ticker. STRENGTH is documented arithmetic, NOT a black-box or predictive/ML score: strength = (distinct congressional purchasers among the qualifying legs) x (the representative signal's insiderCount) — a plain multiplication of two observed counts, nothing more. HONESTY: every congress leg always carries both amountLow and amountHigh (STOCK Act discloses ranges, never exact figures — never combined into a fabricated midpoint) and disclosureLagDays = (disclosureDate - transactionDate). Congressional trades whose dates are impossible or implausible (a dateQuality flag: transaction_after_disclosure, future_transaction_date or implausible_lag) are excluded from detection, so they never appear as legs and never create a convergence; dateQuality is therefore null on every leg returned here and disclosureLagDays is always set. Congressional trades are disclosed up to 45 days after the actual trade under the STOCK Act, so this endpoint is detection/monitoring of what insiders AND members of Congress have DISCLOSED buying, not a claim of predictive edge, alpha, or win rate — no performance numbers are computed or implied anywhere in this response. window_days and lookback_days are both caller-overridable with clamps (see each parameter's own description for the exact bounds). Requires Pro plan or higher (402 PLAN_REQUIRED on Free/Starter). `limit` is accepted as an alias for `per_page`. Query runs live against the database — no caching."""
         params = {
             "ticker": ticker,
             "window_days": window_days,

{form4api-0.8.0 → form4api-0.9.0}/form4api/_types.py

@@ -111,6 +111,49 @@ class Company:
     website: str | None
 
 
+@dataclass
+class SearchCompany:
+    ticker: str
+    name: str
+    cik: str
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "SearchCompany":
+        known = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class SearchInsider:
+    cik: str
+    name: str
+    title: str | None
+    # A ticker associated with the insider (may be None).
+    ticker: str | None
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "SearchInsider":
+        known = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class SearchResults:
+    companies: list[SearchCompany]
+    insiders: list[SearchInsider]
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "SearchResults":
+        """Build from the `/v1/search` payload, hydrating both arrays into
+        their own dataclasses rather than leaving them as raw dicts (see
+        Transaction._from_dict for why filtering unknown keys matters here
+        too — a field the backend adds later must not crash an older SDK)."""
+        return cls(
+            companies=[SearchCompany._from_dict(c) for c in (data.get("companies") or [])],
+            insiders=[SearchInsider._from_dict(i) for i in (data.get("insiders") or [])],
+        )
+
+
 @dataclass
 class InsiderSignal:
     ticker: str | None

{form4api-0.8.0 → form4api-0.9.0}/form4api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: form4api
-Version: 0.8.0
+Version: 0.9.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
@@ -81,6 +81,7 @@ asyncio.run(main())
 
 | Resource | Methods |
 |---|---|
+| `client.search(q, limit=None)` | Combined company + insider lookup — not namespaced under a resource |
 | `client.transactions` | `.list(**params)`, `.paginate(**params)` |
 | `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.list(**params)`, `.directory(**params)`, `.transactions(cik, **params)`, `.summary(cik)` *(Pro)*, `.scorecard(cik)` *(Pro)*, `.leaderboard(**params)` *(Business)* |
 | `client.companies` | `.get(ticker)`, `.insiders(ticker)`, `.list(**params)` |
@@ -94,6 +95,19 @@ asyncio.run(main())
 | `client.status` | `.history(**params)` |
 | `client.webhooks` | `.create(url, event_types)`, `.list()`, `.delete(id)`, `.events(**params)` |
 
+**Congress date quality.** Each congress trade (and convergence leg) has
+`disclosure_lag_days: int | None` and `date_quality: str | None`. When the
+filing's own dates are impossible or implausible, the lag is `None` and
+`date_quality` is one of `"transaction_after_disclosure"`,
+`"future_transaction_date"` or `"implausible_lag"`; the raw dates are still
+returned. A lag over 45 days is not a legal finding.
+
+```python
+for t in client.congress.trades(ticker="NVDA"):
+    lag = f"dates unreliable ({t.date_quality})" if t.disclosure_lag_days is None else f"{t.disclosure_lag_days}d"
+    print(t.politician.full_name, t.transaction_date, lag)
+```
+
 Every plan-gated endpoint the API exposes has a typed method here. Calling one
 your key isn't entitled to raises `PlanError` (HTTP 402) carrying
 `required_plan`, `current_plan`, and `upgrade_url` rather than failing opaquely.
@@ -191,6 +205,27 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 | `state_of_incorporation` | `str \| None` | Two-letter state code |
 | `website` | `str \| None` | Company website as filed with SEC |
 
+### Search
+
+`client.search(q, limit=None)` looks up companies and insiders by name or
+ticker in a single call — useful for a combined search box where you don't
+know in advance whether the user typed a ticker or a person's name. `q` must
+be 2-64 characters; outside that range the API returns HTTP 400 and the SDK
+raises `Form4ApiError` with `error_code` `"QUERY_TOO_SHORT"` or
+`"QUERY_TOO_LONG"`. Insider matching is whitespace-tokenised, so `"tim cook"`
+matches an insider named `"Cook Timothy D"`. `limit` caps the number of
+results per array (1-20, API default 8).
+
+```python
+result = client.search("tim cook")
+for c in result.companies:
+    print(c.ticker, c.name, c.cik)
+for i in result.insiders:
+    # i.ticker is a ticker associated with the insider and may be None —
+    # its exact meaning is still settling on the backend.
+    print(i.cik, i.name, i.title, i.ticker)
+```
+
 ### Pagination
 
 `paginate()` pages through the data until it runs out (a short or empty page)

{form4api-0.8.0 → form4api-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "form4api"
-version = "0.8.0"
+version = "0.9.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.8.0 → form4api-0.9.0}/tests/test_client.py

@@ -14,8 +14,12 @@ from form4api import (
     Insider,
     Company,
     InsiderSignal,
+    SearchCompany,
+    SearchInsider,
+    SearchResults,
     verify_webhook,
 )
+from form4api._client import AsyncForm4ApiClient
 
 BASE = "https://api.form4api.com"
 
@@ -412,6 +416,129 @@ def test_signals_list_returns_typed_objects(client):
     assert results[0].buy_sell_ratio == 2.5
 
 
+# ── search ───────────────────────────────────────────────────────────────────
+
+SEARCH_BODY = {
+    "companies": [{"ticker": "AAPL", "name": "Apple Inc.", "cik": "0000320193"}],
+    "insiders": [
+        {
+            "cik": "0001214156",
+            "name": "Cook Timothy D",
+            "title": "Chief Executive Officer",
+            "ticker": "AAPL",
+        }
+    ],
+}
+
+
+@respx.mock
+def test_search_returns_typed_companies_and_insiders(client):
+    respx.get(f"{BASE}/v1/search").mock(return_value=httpx.Response(200, json=SEARCH_BODY))
+    result = client.search("tim cook")
+    assert isinstance(result, SearchResults)
+    assert len(result.companies) == 1
+    assert isinstance(result.companies[0], SearchCompany)
+    assert result.companies[0].ticker == "AAPL"
+    assert result.companies[0].cik == "0000320193"
+    assert len(result.insiders) == 1
+    assert isinstance(result.insiders[0], SearchInsider)
+    assert result.insiders[0].name == "Cook Timothy D"
+    assert result.insiders[0].title == "Chief Executive Officer"
+    assert result.insiders[0].ticker == "AAPL"
+
+
+@respx.mock
+def test_search_sends_q_and_omits_limit_when_not_given(client):
+    route = respx.get(f"{BASE}/v1/search").mock(return_value=httpx.Response(200, json=SEARCH_BODY))
+    client.search("aapl")
+    qs = dict(route.calls.last.request.url.params)
+    assert qs["q"] == "aapl"
+    assert "limit" not in qs
+
+
+@respx.mock
+def test_search_sends_limit_when_given(client):
+    route = respx.get(f"{BASE}/v1/search").mock(return_value=httpx.Response(200, json=SEARCH_BODY))
+    client.search("aapl", limit=3)
+    qs = dict(route.calls.last.request.url.params)
+    assert qs["limit"] == "3"
+
+
+@respx.mock
+def test_search_tolerates_null_insider_title_and_ticker(client):
+    body = {
+        "companies": [],
+        "insiders": [{"cik": "0001", "name": "Someone Else", "title": None, "ticker": None}],
+    }
+    respx.get(f"{BASE}/v1/search").mock(return_value=httpx.Response(200, json=body))
+    result = client.search("someone")
+    assert result.insiders[0].title is None
+    assert result.insiders[0].ticker is None
+
+
+@respx.mock
+def test_search_400_query_too_short_raises_form4_api_error(client):
+    respx.get(f"{BASE}/v1/search").mock(
+        return_value=httpx.Response(
+            400,
+            json={"error": {"code": "QUERY_TOO_SHORT", "message": "q must be at least 2 characters"}},
+        )
+    )
+    with pytest.raises(Form4ApiError) as exc:
+        client.search("a")
+    assert exc.value.status_code == 400
+    assert exc.value.error_code == "QUERY_TOO_SHORT"
+
+
+@respx.mock
+def test_search_400_query_too_long_raises_form4_api_error(client):
+    respx.get(f"{BASE}/v1/search").mock(
+        return_value=httpx.Response(
+            400,
+            json={"error": {"code": "QUERY_TOO_LONG", "message": "q must be at most 64 characters"}},
+        )
+    )
+    with pytest.raises(Form4ApiError) as exc:
+        client.search("a" * 65)
+    assert exc.value.status_code == 400
+    assert exc.value.error_code == "QUERY_TOO_LONG"
+
+
+@respx.mock
+def test_search_works_on_the_async_client():
+    """The async twin, exercised directly rather than assumed from the sync
+    pass — see test_generated.py's history of the async client silently
+    breaking every hand-written resource while only sync tests existed."""
+    import asyncio
+
+    respx.get(f"{BASE}/v1/search").mock(return_value=httpx.Response(200, json=SEARCH_BODY))
+
+    async def go():
+        async with AsyncForm4ApiClient("test-key", max_retries=0) as c:
+            return await c.search("tim cook", limit=5)
+
+    result = asyncio.run(go())
+    assert isinstance(result, SearchResults)
+    assert result.companies[0].name == "Apple Inc."
+    assert result.insiders[0].cik == "0001214156"
+
+
+@respx.mock
+def test_search_async_sends_limit_param():
+    import asyncio
+
+    route = respx.get(f"{BASE}/v1/search").mock(return_value=httpx.Response(200, json=SEARCH_BODY))
+
+    async def go():
+        async with AsyncForm4ApiClient("test-key", max_retries=0) as c:
+            await c.search("aapl", limit=5)
+
+    asyncio.run(go())
+    qs = dict(route.calls.last.request.url.params)
+    assert qs["q"] == "aapl"
+    assert qs["limit"] == "5"
+
+
 # ── error handling ────────────────────────────────────────────────────────────
 
 @respx.mock

{form4api-0.8.0 → form4api-0.9.0}/tests/test_generated.py

@@ -17,7 +17,7 @@ import respx
 
 from form4api import Form4ApiClient
 from form4api._client import AsyncForm4ApiClient
-from form4api._generated import Form144Response
+from form4api._generated import CongressTradeDto, ConvergenceCongressLegDto, Form144Response
 
 BASE = "http://test.local"
 
@@ -431,3 +431,50 @@ def test_insiders_directory_does_not_shadow_insiders_list(client: Form4ApiClient
     route = respx.get(f"{BASE}/v1/insiders").mock(return_value=httpx.Response(200, json=[]))
     client.insiders.list()
     assert route.calls.last.request.url.path == "/v1/insiders"
+
+
+@respx.mock
+def test_congress_trades_parse_null_lag_and_date_quality(client: Form4ApiClient) -> None:
+    base = {
+        "ticker": "NVDA",
+        "assetName": "NVIDIA",
+        "transactionType": "Purchase",
+        "amountLow": 1001,
+        "amountHigh": 15000,
+        "disclosureDate": "2026-01-10",
+    }
+    respx.get(f"{BASE}/v1/congress/trades").mock(
+        return_value=httpx.Response(
+            200,
+            json=[
+                {**base, "transactionDate": "2026-01-01", "disclosureLagDays": 9, "dateQuality": None},
+                {
+                    **base,
+                    "transactionDate": "2026-02-01",
+                    "disclosureLagDays": None,
+                    "dateQuality": "transaction_after_disclosure",
+                },
+            ],
+        )
+    )
+    rows = client.congress.trades()
+
+    assert isinstance(rows[0], CongressTradeDto)
+    assert rows[0].disclosure_lag_days == 9
+    assert rows[0].date_quality is None
+    # A flagged row: no lag, a reason code, and the raw dates unchanged.
+    assert rows[1].disclosure_lag_days is None
+    assert rows[1].date_quality == "transaction_after_disclosure"
+    assert rows[1].transaction_date == "2026-02-01"
+    assert rows[1].disclosure_date == "2026-01-10"
+
+
+def test_convergence_leg_models_date_quality_as_nullable() -> None:
+    leg = ConvergenceCongressLegDto._from_dict(
+        {"full_name": "X", "disclosure_lag_days": 12, "date_quality": None, "brand_new_field": 1}
+    )
+    assert leg.disclosure_lag_days == 12
+    assert leg.date_quality is None
+    # Same fields on both congress DTOs, so the two stay in step with the spec.
+    assert {"disclosure_lag_days", "date_quality"} <= set(CongressTradeDto.__dataclass_fields__)
+    assert {"disclosure_lag_days", "date_quality"} <= set(ConvergenceCongressLegDto.__dataclass_fields__)