release: 0.3.0 — request models, OAuth auth, DiscoGen cost metadata

.github/workflows/contract.yml

@@ -27,6 +27,8 @@ jobs:
               run: |
                   if [ "$BASE_REF" = "development" ] && [ -n "$DEV_SPEC_URL" ]; then
                       uv run python scripts/check_contract.py --spec-url "$DEV_SPEC_URL"
+                      uv run python scripts/gen_requests.py --check --spec-url "$DEV_SPEC_URL"
                   else
                       uv run python scripts/check_contract.py
+                      uv run python scripts/gen_requests.py --check
                   fi

CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.3.0 (2026-08-29)
+
+- SDK: OAuth login. `Discolike(auth=...)` / `AsyncDiscolike(auth=...)` accept an `ApiKeyCredential` or `OAuthCredential` (both exported from `discolike`); `api_key=`, `DISCOLIKE_API_KEY`, and the config file keep working unchanged, and `auth=` wins over all of them. OAuth credentials send `Authorization: Bearer`, refresh proactively within 60s of expiry and once more after a 401, and write rotated refresh tokens back to the config file when they were loaded from it (an injected `auth=` is never persisted). A refresh that fails raises `AuthenticationError("OAuth session expired; run `discolike auth login`")`. Config file gains the shape `{"auth_method": "oauth", "oauth": {...}}` next to the existing `api_key` shape.
+- SDK: `http_client=` now has its `.auth` set by the SDK (the `X-discolike-key` header moved from a static default header into an `httpx2.Auth`); an `auth` already set on a user-supplied client is replaced.
+- CLI: `discolike auth login` now logs in through the browser by default (PKCE authorization-code flow against the platform's OAuth server, loopback redirect on `127.0.0.1`). `--no-browser` prints the URL only, `--port` pins the loopback port for SSH forwarding, and `--method api_key` (or `--api-key KEY`) keeps the API-key flow, including the prompt. Login-flow failures (timeout, denied consent, state mismatch) exit 1 with `{"error": "LoginError", ...}` on stderr.
+- CLI: `discolike auth login` remembers the OAuth client it registered (`oauth_client` in the config file) and reuses it on the next login for the same server, so the browser consent screen is only asked once per machine. `auth logout` drops the credential but keeps the registration (a public PKCE client, not a secret), so the next login skips consent too. If PropelAuth no longer recognises the stored client (`invalid_client` / `unauthorized_client`), login registers a fresh one and retries once.
+- CLI: `discolike auth status` adds `method` (`api_key` / `oauth`); for OAuth it reports `expires_at` and `expired` instead of a masked key.
+
+- SDK: `JobStatus` gains `estimated_cost` and `cost_metadata` for DiscoGen-family jobs (`discogen`, `validate_icp`, contacts generate). `cost_metadata` has one entry per `provider/model` and a `search_provider` entry with `queries_executed` / `queries_succeeded` / `est_cost_usd` when a BYOS search provider ran. `search_calls` on the model entries counts only the model's built-in search tool and is `0` on every BYOS run; read `search_provider.queries_executed` to confirm web search happened.
+
+### Request models
+
+- SDK (breaking): every request-taking method now takes a single request model instead of keyword arguments, and validates it locally before any HTTP call — a bad enum value, an out-of-range number, or a missing required field raises `pydantic.ValidationError` instead of a server 422. Models live in `discolike.requests` and are generated from the platform OpenAPI spec (`scripts/gen_requests.py`); query-param routes use `<Resource><Method>Params` (`MatchCompanyParams`, `ContactsSearchParams`, `DiscoverParams`, `CountParams`, `AppendParams`, `SegmentParams`, ...) and JSON-body routes use the platform's own names (`FindEmailRequest`, `ContactFilters`, `DiscoGenProcessRequest`, `UpdateQueryRequest`, ...). Path params and file uploads stay keyword arguments next to the model. Unknown fields pass through to the wire, so the SDK never blocks a platform field it does not know about yet.
+
+  ```python
+  # before
+  client.match.company(name="Acme Inc", city="Austin", min_match_confidence=80)
+  client.email.find_batch(contacts=[{"first_name": "Ada", "last_name": "Lovelace", "domain": "acme.com"}])
+  client.queries.update(query_id="q3", query_name="New Name")
+  client.segment(domains=["acme.com", "beta.com"], max_segments=5)
+  client.segment(file="domains.csv", domain_column="domain")
+
+  # after
+  from discolike.requests import FindEmailBatchRequest, MatchCompanyParams, SegmentFileParams, SegmentParams, UpdateQueryRequest
+
+  client.match.company(MatchCompanyParams(name="Acme Inc", city="Austin", min_match_confidence=80))
+  client.email.find_batch(FindEmailBatchRequest.model_validate({"requests": [{"first_name": "Ada", "last_name": "Lovelace", "domain": "acme.com"}]}))
+  client.queries.update(UpdateQueryRequest(query_name="New Name"), query_id="q3")
+  client.segment(SegmentParams(domains="acme.com,beta.com", max_segments=5))
+  client.segment_file(SegmentFileParams(domain_column="domain"), file="domains.csv")
+  ```
+
+- SDK (breaking): `segment` is split into `client.segment(SegmentParams)` (`GET /segment`, `domains` is the comma-separated string the API takes) and `client.segment_file(SegmentFileParams, file=...)` (`POST /segment`). `email.find_batch` drops its `contacts=` alias for the platform's `requests` field. `append` requires `dataset`, matching the platform.
+- SDK (breaking): `GET /segment` sends `query_id` as repeated `query_id=` params (the spec declares it an array) instead of the old comma-joined single value.
+- SDK: deprecated parameters (`nl_match`, `min_score`, `negate_domain`, `exact_match`, `vendor`, `revenue_range` on contacts, `negate_icp_text`) are not part of the generated models; they still pass through as extra fields if set explicitly.
+- SDK: new `DiscolikeRequest` base (`discolike.DiscolikeRequest`) with `to_wire()`, which sends exactly the fields you set — an explicit `None` goes out as `null` (this is how `llm_providers.update` keeps the stored API key), and unset fields are omitted so server defaults keep governing.
+- CLI: request models are built from the same options as before, so no flags change. Two behavior changes: `--param KEY=VALUE` with an unknown key is forwarded to the API (previously exit 2), and any option or `--param` value outside the spec (an unknown `--department`, `--max-records` below the floor, `--match loose`) exits 2 with `{"error": "ValidationError", ...}` on stderr before the request is sent. `discolike append` without `--dataset` now fails this same client-side validation (was optional before; `AppendParams` requires it).
+- CI: the contract job also runs `scripts/gen_requests.py --check`, so the committed models fail the build when the platform spec moves.
+
 ## 0.2.0 (2026-08-21)
 
 - SDK + testkit (breaking): migrated from `httpx` to [`httpx2`](https://github.com/pydantic/httpx2), Pydantic's maintained continuation of httpx, for timely security updates. `httpx` types are part of the public surface (`http_client=`, `with_options(timeout=)`, the testkit `Handler` alias), so callers must swap `import httpx` for `import httpx2` and pass `httpx2.Client` / `httpx2.AsyncClient` / `httpx2.Timeout`. Note httpx2 verifies TLS against the OS trust store via `truststore` instead of bundled `certifi` roots.

CONTRIBUTING.md

@@ -36,6 +36,12 @@ CI also validates SDK routes against the live DiscoLike OpenAPI spec
 (`scripts/check_contract.py`). PRs from forks are checked against the
 production spec.
 
+CI also runs `scripts/gen_requests.py --check` against the dev spec
+(`https://api.dev.discolike.com/v1/openapi.json`) — the committed request
+models in `discolike.requests` track dev, not prod. The prod spec lags, so
+both `check_contract.py` and `gen_requests.py --check` against prod stay red
+until the platform deploys; don't regenerate against prod to "fix" it.
+
 ## Reporting bugs
 
 Open a GitHub issue with the package name, version, and a minimal

README.md

@@ -82,13 +82,16 @@ client = Discolike(api_key="dl_...")  # or pass it explicitly
 
 ```python
 from discolike import Discolike
+from discolike.requests import DiscoverParams
 
 client = Discolike()
 
 companies = client.discover(
-    icp_text="Cybersecurity for SMBs, managed IT services, endpoint protection",
-    country=["US"],
-    max_records=25,
+    DiscoverParams(
+        icp_text="Cybersecurity for SMBs, managed IT services, endpoint protection",
+        country=["US"],
+        max_records=25,
+    )
 )
 for company in companies:
     print(company.domain, company.name, company.similarity)
@@ -97,10 +100,14 @@ for company in companies:
 Run DiscoGen research over a set of domains and wait for the result:
 
 ```python
+from discolike.requests import DiscoGenProcessRequest
+
 job = client.discogen.process(
-    query="Recent funding rounds and headcount growth",
-    domains=["stripe.com", "adyen.com"],
-    web_search=True,
+    DiscoGenProcessRequest(
+        query="Recent funding rounds and headcount growth",
+        domains=["stripe.com", "adyen.com"],
+        web_search=True,
+    )
 )
 result = job.wait()
 print(result.results)
@@ -109,14 +116,18 @@ print(result.results)
 Size a segment before pulling it:
 
 ```python
-total = client.count(phrase_match=["book a demo"], country=["US"])
+from discolike.requests import CountParams
+
+total = client.count(CountParams(phrase_match=["book a demo"], country=["US"]))
 print(total.count)
 ```
 
 Pull a full company profile:
 
 ```python
-profile = client.companies.data(domain="stripe.com")
+from discolike.requests import CompaniesDataParams
+
+profile = client.companies.data(CompaniesDataParams(domain="stripe.com"))
 ```
 
 The client is a context manager if you want deterministic cleanup:
@@ -133,10 +144,11 @@ Every resource has an async twin on `AsyncDiscolike`:
 ```python
 import asyncio
 from discolike import AsyncDiscolike
+from discolike.requests import DiscoverParams
 
 async def main() -> None:
     async with AsyncDiscolike() as client:
-        companies = await client.discover(icp_text="B2B SaaS for logistics", max_records=10)
+        companies = await client.discover(DiscoverParams(icp_text="B2B SaaS for logistics", max_records=10))
         print([c.domain for c in companies])
 
 asyncio.run(main())
@@ -192,11 +204,12 @@ Top-level commands: `discover`, `count`, `match`, `extract`, `validate-icp`, `ap
 | `client.contacts` | Search, look up, match, and discover contacts at target companies |
 | `client.match` | Match company names (plus phone/city/state) to domains — single or bulk CSV |
 | `client.append()` | Enrich a CSV of domains with DiscoLike datasets |
-| `client.segment()` | Auto-segment a list of domains |
+| `client.segment()` / `client.segment_file()` | Auto-segment a list of domains (comma-separated string or CSV upload) |
 | `client.validate_icp()` | Validate a domain list against an ICP definition |
 | `client.queries` | Saved inclusion/exclusion lists for reusable targeting |
 | `client.search_providers` / `client.llm_providers` | Manage BYOK search and LLM provider integrations for DiscoGen |
 | `client.account` | Usage and quota |
+| `discolike.requests` | Request models for every call — generated from the platform OpenAPI spec, validated locally before the request is sent |
 
 All responses are typed [Pydantic](https://docs.pydantic.dev/) models.
 
@@ -205,11 +218,13 @@ All responses are typed [Pydantic](https://docs.pydantic.dev/) models.
 Bulk operations (`match.bulk`, `segment`, `validate_icp`, `contacts.bulk_match`) return a `Job` handle instead of blocking:
 
 ```python
-job = client.segment(domains=["stripe.com", "adyen.com", "checkout.com"])
+from discolike.requests import SegmentParams
+
+job = client.segment(SegmentParams(domains="stripe.com,adyen.com,checkout.com"))
 result = job.wait()
 ```
 
-`Job.status()` polls without blocking, `Job.cancel()` aborts, and `wait()` raises `JobFailedError` / `JobTimeoutError` on failure.
+`Job.status()` polls without blocking, `Job.cancel()` aborts, and `wait()` raises `JobFailedError` / `JobTimeoutError` on failure. On DiscoGen-family jobs the returned `JobStatus` also carries `warnings`, `estimated_cost` and `cost_metadata` (per-model usage plus a `search_provider` entry when a BYOS search provider ran; `search_calls` only counts the model's built-in search).
 
 `JobTimeoutError` is a client-side wait limit only — the task keeps running server-side (large DiscoGen runs can take hours), so call `wait()` again to resume or fetch `status()` later. Cancelled tasks still return results for every item that finished before cancellation. Send one job per list (up to 10,000 domains) rather than splitting into parallel jobs — concurrent DiscoGen jobs share your LLM provider key and slow each other down.
 
@@ -219,9 +234,10 @@ All errors inherit from `DiscolikeError`:
 
 ```python
 from discolike import Discolike, RateLimitError, ValidationError
+from discolike.requests import DiscoverParams
 
 try:
-    companies = Discolike().discover(icp_text="fintech infrastructure")
+    companies = Discolike().discover(DiscoverParams(icp_text="fintech infrastructure"))
 except RateLimitError as err:
     ...
 except ValidationError as err:
@@ -230,6 +246,18 @@ except ValidationError as err:
 
 `AuthenticationError`, `PlanAccessError`, `NotFoundError`, `ServerError`, and `APIConnectionError` cover the rest. Transient failures are retried automatically (3 attempts by default).
 
+```python
+import pydantic
+from discolike.requests import MatchCompanyParams
+
+try:
+    params = MatchCompanyParams(name="Acme", min_match_confidence=10)
+except pydantic.ValidationError as err:
+    ...  # raised locally: min_match_confidence must be 50-100
+```
+
+Request models validate before anything is sent, so a bad enum value or out-of-range number never costs a round trip. Unknown fields pass through untouched.
+
 ### Configuration
 
 | Option | Default | |
@@ -251,8 +279,12 @@ uv sync --all-packages
 uv run pytest packages/discolike/tests
 uv run pytest packages/discolike-cli/tests
 uv run ruff check .
+uv run python scripts/gen_requests.py --spec-url https://api.dev.discolike.com/v1/openapi.json  # regenerate request models
+uv run python scripts/gen_requests.py --check                                                    # fail on drift (CI)
 ```
 
+Committed request models track the dev spec (`--spec-url https://api.dev.discolike.com/v1/openapi.json`); the prod spec lags behind, so `--check` without a `--spec-url` (or against prod) stays red until the platform deploys — don't regenerate against prod to "fix" it.
+
 ## Support & contact
 
 - **API documentation**: [docs.discolike.com](https://docs.discolike.com)

examples/discover_and_enrich.py

@@ -2,9 +2,9 @@
 
 Two calls end to end:
 
-1. ``client.discover(icp_text=..., country=..., max_records=...)`` finds
-   lookalike companies from DiscoLike's index of 80M+ business websites.
-2. ``client.discogen.process(query=..., domains=[...], web_search=True)``
+1. ``client.discover(DiscoverParams(icp_text=..., country=..., max_records=...))``
+   finds lookalike companies from DiscoLike's index of 80M+ business websites.
+2. ``client.discogen.process(DiscoGenProcessRequest(query=..., domains=[...], web_search=True))``
    runs an AI research prompt over the discovered domains and returns one
    structured answer per company. ``job.wait()`` blocks until it finishes.
 
@@ -26,6 +26,8 @@
 import sys
 
 from discolike import Discolike
+from discolike.requests import DiscoGenProcessRequest
+from discolike.requests import DiscoverParams
 
 
 def parse_args() -> argparse.Namespace:
@@ -43,15 +45,15 @@ def main() -> None:
     client = Discolike()
 
     print(f"Discovering up to {args.max_records} companies for: {args.icp!r}")
-    companies = client.discover(icp_text=args.icp, country=args.country, max_records=args.max_records)
+    companies = client.discover(DiscoverParams(icp_text=args.icp, country=args.country, max_records=args.max_records))
     if not companies:
         sys.exit("No companies found for that ICP - try broadening it.")
     domains = [company.domain for company in companies if company.domain]
     for company in companies:
         print(f"  {company.domain}  {company.name or ''}  (similarity {company.similarity})")
 
     print(f"\nRunning DiscoGen over {len(domains)} domains: {args.query!r}")
-    job = client.discogen.process(query=args.query, domains=domains, web_search=True)
+    job = client.discogen.process(DiscoGenProcessRequest(query=args.query, domains=domains, web_search=True))
     status = job.wait(timeout=args.timeout, on_poll=lambda s: print(f"  status={s.status} progress={s.progress}%"))
 
     print("\nEnriched results:")

examples/find_emails_from_csv.py

@@ -2,7 +2,7 @@
 
 Reads people from a CSV with ``first_name``, ``last_name``, and ``domain``
 columns (names configurable), submits them with
-``client.email.find_batch(contacts=[...])`` in chunks of up to 500, waits for
+``client.email.find_batch(FindEmailBatchRequest(...))`` in chunks of up to 500, waits for
 each batch with ``batch.results()``, and writes the found emails plus status
 to an output CSV.
 
@@ -22,6 +22,8 @@
 from pathlib import Path
 
 from discolike import Discolike
+from discolike import EnumerationOutput
+from discolike.requests import FindEmailBatchRequest
 
 MAX_CONTACTS_PER_BATCH = 500
 
@@ -65,11 +67,11 @@ def main() -> None:
         for start in range(0, len(contacts), MAX_CONTACTS_PER_BATCH):
             chunk = contacts[start : start + MAX_CONTACTS_PER_BATCH]
             print(f"Submitting batch of {len(chunk)} contacts ({start + len(chunk)}/{len(contacts)})...")
-            batch = client.email.find_batch(contacts=chunk)
+            batch = client.email.find_batch(FindEmailBatchRequest.model_validate({"requests": chunk}))
             results = batch.results(timeout=args.timeout)
             for item in results.results:
                 output = item.result
-                if output is None:
+                if not isinstance(output, EnumerationOutput):
                     # Failed jobs carry no EnumerationOutput (so no identity),
                     # but must not vanish from the output: keep the status and
                     # error so the failure is visible and countable.
@@ -85,8 +87,7 @@ def main() -> None:
                         }
                     )
                     continue
-                match = getattr(output, "result", None)
-                email = match.email if match is not None else None
+                email = output.result.email if output.result is not None else None
                 if output.status == "found":
                     found += 1
                 writer.writerow(

examples/match_crm_contacts.py

@@ -1,7 +1,7 @@
 """Match a CSV of CRM contacts to DiscoLike persona IDs via bulk-match.
 
 Reads contacts from a CSV (column names are configurable), submits them to
-``client.contacts.bulk_match()`` in chunks, and writes an output CSV with the
+``client.contacts.bulk_match(BulkContactMatchRequest(...))`` in chunks, and writes an output CSV with the
 matched ``persona_id`` and ``match_score`` per row.
 
 Lessons baked in from production runs:
@@ -34,6 +34,7 @@
 from urllib.parse import urlparse
 
 from discolike import Discolike
+from discolike.requests import BulkContactMatchRequest
 
 MAX_QUERIES_PER_CALL = 500  # bulk_match accepts 1-500 queries per request
 
@@ -204,7 +205,9 @@ def main() -> None:
                 hits: dict[int, dict[str, Any] | None] = dict.fromkeys(row_ids)
             else:
                 try:
-                    job = client.contacts.bulk_match(queries=queries, limit=1)
+                    job = client.contacts.bulk_match(
+                        BulkContactMatchRequest.model_validate({"queries": queries, "limit": 1})
+                    )
                     status = job.wait(timeout=args.timeout)
                 except Exception as exc:  # leave the chunk un-checkpointed so a rerun retries it
                     failed_chunks += 1