fix(cloud): migrate off deprecated /extract endpoint and stop misreading deprecation 429 as a quota error

[gbharg]

Summary

Cloud mode currently fails for users with a valid API key and unused quota, reporting a misleading Rate limit exceeded (10k/month) error. The root cause is a deprecated endpoint whose deprecation response is misread as a quota error.

Symptom

With a valid Nanonets key configured, any cloud extraction (e.g. extract_markdown(), parse_pdf) raises:

ConversionError: Rate limit exceeded (10k/month). Please try again later.

…even on a brand-new key that has never been used. OCR then silently fails.

Root cause

docstrange/processors/cloud_processor.py POSTs to nanonets' deprecated /extract endpoint:

self.api_url = "https://extraction-api.nanonets.com/extract"

Nanonets now returns HTTP 429 for that endpoint, but with a deprecation body — not a quota body:

{"detail": "The /extract endpoint is deprecated. Please migrate to /api/v1/extract."}

The 429 handler inspects only the status code and never reads the body, so whenever an API key is present it unconditionally raises Rate limit exceeded (10k/month). A deprecation notice is thus reported to the user as an exhausted quota.

Fix

1. Migrate to the current sync endpoint https://extraction-api.nanonets.com/api/v1/extract/sync.
2. Send output_format (required by the new endpoint), mapped from the legacy output_type vocabulary (markdown|html|csv pass through; flat-json and the specified-* variants map to json). output_type is still sent for backward compatibility.
3. Body-aware 429 handling — inspect the response body before assuming a quota problem:
   • a deprecation notice surfaces the real message and guidance to upgrade, instead of a fabricated quota error;
   • a genuine rate-limit body is still reported as a rate-limit error, and now includes the server's own detail.
4. Parse the new nested response shape result.<format>.content, while keeping backward compatibility with the legacy top-level content field.
5. Tests — added tests/test_cloud_deprecation.py, fully offline (HTTP + file I/O mocked; no API key or network needed), covering the endpoint, request params, deprecation-vs-quota 429 handling, and both response shapes.

Verification

Confirmed against the live API (key redacted):

• POST /extract (old) → HTTP 429, body {"detail": "The /extract endpoint is deprecated. Please migrate to /api/v1/extract."}.
• POST /api/v1/extract/sync without output_format → HTTP 422 (missing required field), key accepted (no 401/403).
• POST /api/v1/extract/sync with output_format=markdown + Bearer key → HTTP 200, "success": true, correct OCR of a scanned document.

After applying this change, cloud extraction returns real OCR content on a valid key, and a deprecation 429 (if it ever recurs) is no longer misreported as a quota error.

Backward compatibility

• The legacy top-level content response field is still handled.
• output_type is still sent alongside the new output_format.
• No public API or signature changes.

🤖 Generated with Claude Code

[gbharg]

Closing this one -- we are handling the change downstream for now. Thanks!