[developerEhsan]

Closes #37, #38, #39, #40, #41, #42, #43, #44, #45, #46.

All ten issues came from one production consumer. Three change existing defaults — in each case because the current default is the unsafe one — so this is a major release.

Breaking

#	Change	Migration
#40	Response cache defaults to off	cache: { enabled: true } to keep it
#42	Only idempotent methods retry	retry: { retryUnsafeMethods: true } to keep it
#41	Next.js helpers moved to /next	import … from '@developerehsan/api-client/next'

Full notes: docs/migrating-v2.md.

#40 — the cache was on with a 60s cache-first TTL and no mention in the README. A write would commit, the app's own query layer would refetch, and this client's cache would still serve the stale value underneath it. Apps pairing it with TanStack Query were silently double-cached.

#42 — a POST that fails with a 5xx or a dropped connection may already have committed server-side; retrying it creates the resource twice. Now only GET/HEAD/OPTIONS/TRACE/PUT/DELETE retry. http.idempotency generates one key per logical call and replays it across that call's retries, so an opted-in write retry is collapsible server-side.

#41 — the root entry carried a dynamic import('next/headers'), and Vite's optimizeDeps scan doesn't honor @vite-ignore inside a pre-bundled dependency. The specifier is now assembled at runtime and the helpers live behind /next, so no non-Next consumer pulls it in. Verified: dist/index.js, index.cjs and edge.js contain zero references to it.

Added

• Error classifier assumes flat {code,message} body — no hook for custom error envelopes #39 errorEnvelope — the classifier only knew flat { code, message }, so a nested envelope fell through to rawBody and error.message came out as stringified JSON (this rendered raw JSON into user-facing toasts in production). A parser that throws is caught and falls back; it can never mask the original failure.
• No built-in cursor-pagination iterator helper #43 paginate / paginateItems / collectPages — cursor pagination as an AsyncIterable. A server echoing the same cursor terminates the loop rather than spinning; maxPages (10,000) backstops the rest.
• IndexedDB persistent cache store doesn't implement cross-instance (multi-tab) invalidation #46 createIndexedDbStore({ crossTab: true }) — BroadcastChannel invalidation, bringing the browser L2 store to parity with Redis crossInstance. Degrades to a plain store where unavailable.
• Browser RPC-bridge client (createRpcClient/httpTransport) has no multipart/FormData support #38 FormData bodies. On the direct client they already passed through, but a configured Content-Type: application/json suppressed the multipart boundary and silently corrupted the body — fixed in both adapters. Over the bridge, httpTransport detects File/Blob args and switches that call to multipart; opt the route in with multipart: true.
• RPC bridge (createRpcRouteHandler/createRpcHandler) has no non-JSON response support (file downloads, binary) #37 Binary responses through the bridge, via a server-declared binary allowlist on createRpcHandler. The route streams the result with its own Content-Type/Content-Disposition and the transport surfaces a Blob.
• GlobalConfig.openapi is required even for consumers not using codegen or runtime validation #45 openapi is optional. Every field inside it already was, so requiring the block bought no type safety.
• createClient JSDoc says retry/cache/dedup/schema-loading are 'stubbed with TODOs' — contradicts README #44 Dropped the stale "stubbed with TODOs" line from createClient's shipped JSDoc.

Security notes

The RPC trust boundary is unchanged in shape — everything new is deny-by-default and server-declared:

• binary is a separate allowlist; a method must be in both expose and binary. A client-supplied responseType is still stripped by sanitizePerCall (S4), so the browser cannot turn a JSON method into a byte stream. There's a test for exactly that.
• multipart is opt-in and documented as leaning entirely on the Origin check, since a multipart body is a CORS "simple request" and so isn't covered by the JSON-content-type half of the CSRF defence. Keep csrf: true with it.
• Binary filenames are sanitized against Content-Disposition header injection.
• A binary method inside a batch is refused rather than JSON-mangled — a batch is one JSON array, with nowhere for a byte stream to go.

Two issues found while reviewing this diff and fixed in it:

• Unbounded body read. The size cap was enforced against the client-supplied Content-Length, which can lie or be absent under chunked encoding. Now bounded against the bytes actually read, aborting the stream past the cap. This bug pre-existed on the JSON path; raising the limit to 10 MB for uploads would have widened it considerably.
• Prototype-pollution bypass. Multipart envelope revival built objects with out[k] = v; with the key __proto__ that invokes the prototype setter, so the key disappears from Object.keys and slips past the handler's existing FORBIDDEN_KEYS guard. Now uses defineProperty, keeping it an own property so that guard still fires. Covered by a test verified to fail without the fix.

Verification

• 387 core tests pass (29 new, in packages/core/src/v2-consumer-issues.test.ts), plus tanstack-query, vite-plugin and the examples.
• tsc --noEmit and Biome clean across the workspace.
• Browser-bundle guard holds: dist/browser.js contains no axios, openapi, or backend detail.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated
api-client-nextjs	Skipped		Oct 21, 2026 12:14pm UTC
api-client-react-vite	Skipped		Oct 21, 2026 12:14pm UTC

[ehsan-platas]

LGTM