feat(sdk): add production HTTP controls and fix review findings

[fahreddinozcan]

Summary

• fix SDK response inference for runtime-selected formats and preserve optional/undefined option forwarding
• honor retry: false as exactly one request
• add production HTTP controls while keeping API-key authentication required
• align shared HTTP conventions with the latest @upstash/redis SDK
• decompose transport types, cancellation, retry policy, response decoding, and orchestration
• split deterministic unit tests from live API integration tests

Production SDK controls

• client and per-request timeouts and abort signals, including a fresh signal factory per request
• configurable transient retries with the @upstash/redis retry shape and default backoff
• Retry-After support and GET-only retries; mutating requests remain single-attempt
• configurable keepAlive, custom fetch, baseUrl, additional headers, and native fetch cache settings
• HTTP(S) URL validation and typed JSON parse failures with truncated bodies and causes
• response metadata hooks for request IDs, rate limits, status, and attempt count
• structured Context7Error fields including status, code, request ID, rate limits, retryability, and cause
• protected Authorization header sourced from the required API key

Maintainability

• reduce http/index.ts from 521 lines to 184 focused orchestration lines
• isolate cancellation, response parsing, retry policy, and public transport types
• use the canonical request contract in commands instead of duplicating transport fields
• fix timeout classification when a deadline expires during retry backoff
• remove speculative retry-method configuration from the public API

Verification

• pnpm --filter @upstash/context7-sdk test (36 tests)
• pnpm --filter @upstash/context7-sdk test:integration
• pnpm --filter @upstash/context7-sdk typecheck
• pnpm --filter @upstash/context7-sdk lint:check
• pnpm --filter @upstash/context7-sdk build
• pnpm --filter @upstash/context7-tools-ai-sdk typecheck
• pnpm --filter @upstash/context7-tools-ai-sdk build

Authentication remains mandatory. Context7 intentionally extends the Redis transport convention by retrying selected transient HTTP statuses, honoring Retry-After, and restricting automatic retries to safe requests.

[linear-code]

CTX7-2663

[enesgules]

Requesting changes for one type regression. The rest looks good.

Must fix: the new overloads reject undefined options. Overloads 1 and 4 now require options, and overload 3 takes only two arguments. A caller that forwards an optional value no longer compiles (verified with tsc --strict):

const o: SearchLibraryOptions | undefined = ...;
client.searchLibrary("q", "react", o);          // TS2769: No overload matches this call
client.searchLibrary("q", "react", undefined);  // TS2769

Both compiled before this PR. Suggested fix (inline comments below): make options optional in the JSON overload and the runtime-union overload, and drop the two-argument overload. Three overloads instead of four, and all call shapes compile. Same for getContext. Please add a type test for the Options | undefined case.

Flag: changeset is patch, but this is a breaking type change. Consumers that pass runtime-selected options and use the result as an array will fail to compile after upgrading. The new type is correct, but say so in the changeset text so users know why their build broke. At 0.x, patch is acceptable.

Verified correct:

• retry: false → attempts: 0 is exactly one fetch with the i <= attempts loop. The new test proves it.
• Unit/integration split is clean; fork PRs no longer need the API secret. CI is green.
• requesterWith is the right size for a test double.

Nits (optional):

• The empty-input rejection is tested twice (client.test.ts and search-library/index.test.ts). Keep one.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
context7	🟢 Ready	View Preview	Sep 4, 2026, 7:29 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[context7]

Docs7 for context7.com

Result	Status	Action
Deployment	✅ Ready	Open preview
Content review	✅ Passed. No problems found.	View findings

Commit 813bb6a · Updated 2026-09-04 13:15 UTC · View build details

[enesgules]

All seven earlier comments are addressed in 097d280 (optional options overloads, the | undefined type test, retry === false in one place, dead API_KEY fallback removed). I resolved those threads.

I also reviewed the four feature commits added after the first review (HTTP controls, redis-js alignment, transport split, retry API). Typecheck, lint, build, 36 unit tests, and the ai-sdk typecheck pass locally. The design is sound: GET-only retries, Retry-After, timeout classification during backoff, protected Authorization, and the abort-state cleanup all check out.

Must fix (one line): an error response whose body is the JSON literal null throws a raw TypeError instead of a Context7Error. Repro:

const client = new HttpClient({ baseUrl: "https://x.test", retry: false,
  fetch: async () => new Response("null", { status: 500, headers: { "content-type": "application/json" } }) });
await client.request({ method: "GET", path: ["a"] });
// TypeError: Cannot read properties of null (reading 'message')

Suggestion inline. A unit test next to "falls back to statusText on empty error body" would lock it in.

Non-blocking

• The changeset says timeouts are configurable but not that a 30 s default now applies to every request. Master had no timeout. One sentence in the changeset would help users who see new request_timeout errors.
• Command.requestResult now throws TypeError for a missing result where master threw Context7Error. The path is unreachable today, but Context7Error keeps the public contract consistent.

[enesgules]

813bb6a addresses everything: non-object JSON error bodies are shape-checked with a regression test for the null literal, Command.requestResult throws Context7Error again, and the changeset documents the 30 s default timeout. Verified locally: typecheck, lint, build, ai-sdk typecheck, and 38 unit tests pass. CI is green.