feat!: 3.0.0 reads the API's 2026-10-11 shape; 2.x names kept, deprecated

[lenzhq]

What changes

3.0.0 reads the API's 2026-10-11 response shape. Every request sends X-Lenz-API-Version: 2026-10-11 (also with a caller-supplied HTTP client), and the SDK reads only that shape for its own calls.

• Webhooks still parse both shapes. A receiver gets events in the version of the request that started the work, which may come from an older client.
• 2.x code keeps working. Every 2.x name is kept with its 2.x value, computed from the new shape, and marked deprecated with its replacement (table in the CHANGELOG). Error classes and their fields keep their 2.x values. The new names are the primary documented interface.
• New LenzApiVersionError: a response whose X-Lenz-API-Version header names another version (in practice 2026-05-13) is refused instead of misread. It is never retried, never swallowed by a 404 shortcut or a poll, and never applied to webhooks.
• Breaking (all in the CHANGELOG):
  • raw bodies show the wire shape;
  • recorded 2.x response fixtures must be re-recorded;
  • webhook receivers older than 2.21 must upgrade before their senders move to 3.0;
  • values the API no longer sends: chain_id, the review/citation-check webhook task_id, some reworded failure sentences and hints.

Developer-experience pass (in this PR)

Reviewed with fresh-eye DX reviews, an engineering plan review, Codex and adversarial reviews.

Fixes:

• Batch submit and ask.send send an automatic Idempotency-Key, like the other paid calls. A retry reuses it. An in-flight 409 idempotency_conflict is retried with the same key, and idempotency=False opts out.
• Every error from a keyed call carries idempotency_key. A resend is safe only with that key.
• New error classes: LenzNotFoundError (404), LenzConnectionError and LenzRequestTimeoutError. They are subclasses of what was raised before, so existing except/catch clauses still match.
• retryable on every error: the server's value when it sends one, else derived from the status.
• Waits stop on 401/403/404 and version errors instead of polling to a misleading timeout. In a batch, a 404 or version error fails only that item.
• Poll requests never pass the wait's deadline.
• Typed values: verdict, confidence and depth are typed for autocomplete, and any string is still accepted.
• Webhooks: a typed .verification on verification events. Node gets isEvent() narrowing and eventId on every event.
• Pagination: iterators over verifications and library (iter() / listAll()).
• Docs: a "first call" at the top of the README, an "Upgrading from 2.x" box in the CHANGELOG, and runnable, type-checked review and citecheck examples.

The CHANGELOG lists every intentional behaviour change under "Changed". Everything else behaves as on 2.21. Request bodies are byte-identical, checked across 100+ call variants.

Cancelled tasks (in this PR)

In API version 2026-10-11 a task can end as cancelled (stopped from the website or another client). 3.0 treats it as final everywhere:

• wait, verify_and_wait, verify_batch_and_wait, review_and_wait, citecheck_and_wait and the CLI end at once with the same error class and failure fields as 2.x (failure_class cancelled, retryable False). A batch item is failed with the cancelled status in status_detail.
• Getters return the object with status == "cancelled"; TaskStatus keeps the 2.x flat fields filled.
• VerificationCancelled and the review.cancelled / citecheck.cancelled webhook events are typed. Older-shape cancellations still arrive as *.failed.
• CHANGELOG lists this under Breaking: hand-written polling loops must treat cancelled as final, and webhook receivers must handle *.cancelled. A 2.21 receiver reads them as a plain WebhookEvent.

Stopping a run (in this PR)

• client.cancel(task_id) -> CancelResult, client.cancel_review(review_id) -> ReviewFull and client.cancel_citecheck(citecheck_id) -> Citecheck call the API's cancel endpoints. They send no body and no Idempotency-Key; repeating one is safe.
• cancelled is True whenever the run is cancelled, by this call or an earlier one. False comes with the run's status, normally completed or failed.
• A 404 keeps the server's code (not_found). A review's deep check answers 409 use_review_cancel: it is sent once, never retried, and its fix names cancel_review.
• Every id in a request path is now sent as one percent-encoded segment, and an empty id, . or .. raises ValueError before any request (CHANGELOG, Changed).
• The live smoke test cancels a low-depth verify and checks both outcomes, so the release gate exercises the endpoint.
• openapi.json refreshed (version 2026-10-11 and the cancel endpoints), byte-identical with the Node SDK's copy.

Tests

ruff, strict mypy and the full suite pass (93.5% coverage). Parity fixtures are synced with the API's recorded responses. Every 2.x attribute is compared against 2.21.0's value. The guard is tested on success and error responses, stored replays, a custom client, polling, delete and webhooks. Deprecated fields carry PEP 702 or JSON-schema markers.

Release

Publish only once lenz.io serves 2026-10-11. Before that, the release workflow's live smoke run fails and the tag does not publish.

Post-release actions and prod checks

1. Mark ready, date the CHANGELOG section, merge, tag v3.0.0. The release runs the live smoke first.
2. Check the package page shows 3.0.0, then run one extract, assess and verify against lenz.io with a real key.
3. Bump the demo apps to 3.0.

🤖 Generated with Claude Code