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

* ctx7-2663: address SDK review findings

* ctx7-2663: tighten SDK test architecture

* ctx7-2663: address SDK type review

* feat(sdk): add production HTTP controls

* refactor(sdk): align HTTP conventions with redis-js

* refactor(sdk): decompose HTTP transport

* refactor(sdk): tighten retry API

* ctx7-2663: address latest SDK review

Author: fahreddinozcan

.changeset/ctx7-2663-sdk-reviews.md

@@ -0,0 +1,9 @@
+---
+"@upstash/context7-sdk": minor
+---
+
+Fix response type inference for runtime-selected formats, honor disabled retries, and separate deterministic SDK tests from live API integration tests. Calls that forward options whose response format is selected at runtime now correctly return an array-or-string union and may require result narrowing.
+
+Add production HTTP controls while keeping API-key authentication required: client and per-request timeouts, abort signals, configurable transient HTTP retries, native fetch cache settings, custom fetch/base URL/header/keepalive support, URL validation, response metadata hooks, and structured `Context7Error` fields for status, code, request ID, rate limits, retryability, malformed JSON, and cause.
+
+Requests now time out after 30 seconds by default. Set `timeout: false` on the client or an individual request to disable the timeout.

.github/workflows/test.yml

@@ -82,3 +82,9 @@ jobs:
         run: pnpm test
         env:
           CONTEXT7_API_KEY: ${{ secrets.CONTEXT7_API_KEY }}
+
+      - name: SDK Integration Test
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        run: pnpm --filter @upstash/context7-sdk test:integration
+        env:
+          CONTEXT7_API_KEY: ${{ secrets.CONTEXT7_API_KEY }}

docs/sdks/ts/commands/get-context.mdx

@@ -26,6 +26,15 @@ Retrieve documentation context for a specific library. Returns documentation as
 
       Default: `"json"`
     </ParamField>
+    <ParamField path="signal" type="AbortSignal">
+      Abort signal for cancelling this request.
+    </ParamField>
+    <ParamField path="timeout" type="number | false">
+      Per-request timeout in milliseconds. Use `false` to disable the client timeout.
+    </ParamField>
+    <ParamField path="cache" type="CacheSetting">
+      Native fetch cache mode. Use `false` to omit the cache option.
+    </ParamField>
   </Expandable>
 </ParamField>
 

docs/sdks/ts/commands/search-library.mdx

@@ -17,6 +17,23 @@ Search across available libraries. Returns an array of matching libraries with m
   The library name to search for
 </ParamField>
 
+<ParamField path="options" type="SearchLibraryOptions">
+  <Expandable title="properties">
+    <ParamField path="type" type="'json' | 'txt'">
+      Format of the response. Defaults to `json`.
+    </ParamField>
+    <ParamField path="signal" type="AbortSignal">
+      Abort signal for cancelling this request.
+    </ParamField>
+    <ParamField path="timeout" type="number | false">
+      Per-request timeout in milliseconds. Use `false` to disable the client timeout.
+    </ParamField>
+    <ParamField path="cache" type="CacheSetting">
+      Native fetch cache mode. Use `false` to omit the cache option.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
 ## Response
 
 Returns `Library[]` - an array of library objects.

docs/sdks/ts/getting-started.mdx

@@ -79,6 +79,42 @@ const client = new Context7({
   `process.env.CONTEXT7_API_KEY`
 </Note>
 
+#### Production HTTP configuration
+
+The SDK applies a 30-second request timeout and retries transient network failures, `408`, `425`,
+`429`, and `5xx` responses. Only `GET` requests are retried; mutating requests remain
+single-attempt.
+
+```typescript
+const client = new Context7({
+  apiKey: "YOUR_API_KEY",
+  timeout: 10_000,
+  retry: {
+    retries: 3,
+    backoff: (attempt) => 100 * 2 ** attempt,
+  },
+  onResponse: ({ status, requestId, rateLimit, attempt }) => {
+    console.log({ status, requestId, rateLimit, attempt });
+  },
+});
+```
+
+You can also configure `baseUrl`, additional `headers`, `keepAlive`, the native fetch `cache` mode,
+a client-wide abort `signal`, or a custom `fetch` implementation. The SDK always sets
+`Authorization` from the configured API key; additional headers cannot override it.
+
+Following the same convention as `@upstash/redis`, a signal factory can provide a fresh timeout
+signal for each request:
+
+```typescript
+const client = new Context7({
+  apiKey: "YOUR_API_KEY",
+  signal: () => AbortSignal.timeout(10_000),
+});
+```
+
+Set `retry: false` to make exactly one request or `timeout: false` to disable the default timeout.
+
 ## Quick Start Example
 
 ```typescript
@@ -104,6 +140,7 @@ console.log(docs[0].title, docs[0].content);
 // Get documentation context as plain text
 const context = await client.getContext("How do I use hooks?", "/facebook/react", {
   type: "txt",
+  timeout: 5_000,
 });
 console.log(context);
 ```
@@ -121,7 +158,14 @@ try {
   const context = await client.getContext("query", "/invalid/library");
 } catch (error) {
   if (error instanceof Context7Error) {
-    console.error("Context7 API Error:", error.message);
+    console.error("Context7 API Error:", {
+      message: error.message,
+      code: error.code,
+      status: error.status,
+      requestId: error.requestId,
+      rateLimit: error.rateLimit,
+      retryable: error.retryable,
+    });
   } else {
     console.error("Unexpected error:", error);
   }

packages/sdk/README.md

@@ -40,22 +40,15 @@ const client = new Context7({
 });
 
 // Search for libraries
-const libraries = await client.searchLibrary(
-  "I need to build a UI with components",
-  "react"
-);
+const libraries = await client.searchLibrary("I need to build a UI with components", "react");
 console.log(libraries[0].id); // "/facebook/react"
 
 // Get documentation as JSON array (default)
 const docs = await client.getContext("How do I use hooks?", "/facebook/react");
 console.log(docs[0].title, docs[0].content);
 
 // Get documentation context as plain text
-const context = await client.getContext(
-  "How do I use hooks?",
-  "/facebook/react",
-  { type: "txt" }
-);
+const context = await client.getContext("How do I use hooks?", "/facebook/react", { type: "txt" });
 console.log(context);
 ```
 
@@ -75,6 +68,61 @@ Then initialize without options:
 const client = new Context7();
 ```
 
+### Production HTTP options
+
+Requests time out after 30 seconds and retry transient network errors, `408`, `425`, `429`,
+and `5xx` responses by default. You can configure those defaults for the client and override
+timeout, cancellation, and native fetch caching per request:
+
+```ts
+import { Context7, Context7Error } from "@upstash/context7-sdk";
+
+const client = new Context7({
+  apiKey: process.env.CONTEXT7_API_KEY,
+  timeout: 10_000,
+  retry: {
+    retries: 3,
+    backoff: (attempt) => 100 * 2 ** attempt,
+  },
+  onResponse: ({ status, requestId, rateLimit, attempt }) => {
+    console.log({ status, requestId, rateLimit, attempt });
+  },
+});
+
+const controller = new AbortController();
+
+try {
+  const docs = await client.getContext("How do I use hooks?", "/facebook/react", {
+    signal: controller.signal,
+    timeout: 5_000,
+    cache: "no-store",
+  });
+  console.log(docs);
+} catch (error) {
+  if (error instanceof Context7Error) {
+    console.error(error.code, error.status, error.requestId, error.rateLimit);
+  }
+}
+```
+
+The client also accepts `baseUrl`, `headers`, `keepAlive`, and a custom `fetch` implementation for
+proxies, instrumentation, tests, and runtimes that do not expose a global `fetch`. The configured
+API key always controls the `Authorization` header.
+
+As in `@upstash/redis`, you can express a timeout with a fresh signal for every request:
+
+```ts
+const client = new Context7({
+  apiKey: process.env.CONTEXT7_API_KEY,
+  signal: () => AbortSignal.timeout(10_000),
+});
+```
+
+Set `retry: false` to make exactly one request, `timeout: false` to disable the request timeout,
+or `cache: false` to omit the native fetch cache option.
+
+Only `GET` requests are retried. Mutating requests remain single-attempt.
+
 ## Docs
 
 See the [documentation](https://context7.com/docs/sdks/ts/getting-started) for details.
@@ -87,6 +135,12 @@ See the [documentation](https://context7.com/docs/sdks/ts/getting-started) for d
 pnpm test
 ```
 
+Run the live API integration tests separately with a configured API key:
+
+```sh
+pnpm test:integration
+```
+
 ### Building
 
 ```sh

packages/sdk/package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "dev": "tsup --watch",

packages/sdk/src/client.integration.test.ts

@@ -0,0 +1,120 @@
+import { describe, test, expect } from "vitest";
+import { Context7 } from "./client";
+
+describe("Context7 Client integration", () => {
+  const apiKey = process.env.CONTEXT7_API_KEY!;
+
+  describe("searchLibrary", () => {
+    const client = new Context7({ apiKey });
+
+    test("should search for libraries and return array directly", async () => {
+      const result = await client.searchLibrary("I need to build a UI", "react");
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    test("should return Library objects with all fields", async () => {
+      const result = await client.searchLibrary("I want to use TypeScript", "typescript");
+
+      expect(result.length).toBeGreaterThan(0);
+      const library = result[0];
+
+      expect(library).toHaveProperty("id");
+      expect(library).toHaveProperty("name");
+      expect(library).toHaveProperty("description");
+      expect(library).toHaveProperty("totalSnippets");
+      expect(library).toHaveProperty("trustScore");
+      expect(library).toHaveProperty("benchmarkScore");
+    });
+
+    test("should search with different queries", async () => {
+      const queries = ["vue", "express", "next"];
+
+      for (const query of queries) {
+        const result = await client.searchLibrary(`I want to use ${query}`, query);
+        expect(result.length).toBeGreaterThan(0);
+      }
+    }, 15000);
+  });
+
+  describe("getContext - JSON format (default)", () => {
+    const client = new Context7({ apiKey });
+
+    test("should get context as Documentation array (default)", async () => {
+      const result = await client.getContext("How to use hooks", "/react/react");
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    test("should get context with explicit json type", async () => {
+      const result = await client.getContext("How to use hooks", "/react/react", {
+        type: "json",
+      });
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    test("should have correct Documentation structure", async () => {
+      const result = await client.getContext("How to use hooks", "/react/react", {
+        type: "json",
+      });
+
+      expect(result.length).toBeGreaterThan(0);
+      const doc = result[0];
+      expect(doc).toHaveProperty("title");
+      expect(doc).toHaveProperty("content");
+      expect(doc).toHaveProperty("source");
+      expect(typeof doc.title).toBe("string");
+      expect(typeof doc.content).toBe("string");
+      expect(typeof doc.source).toBe("string");
+    });
+  });
+
+  describe("getContext - text format", () => {
+    const client = new Context7({ apiKey });
+
+    test("should get context as text string with type: txt", async () => {
+      const result = await client.getContext("How to use hooks", "/react/react", {
+        type: "txt",
+      });
+
+      expect(result).toBeDefined();
+      expect(typeof result).toBe("string");
+      expect(result.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("getContext - different libraries", () => {
+    const client = new Context7({ apiKey });
+
+    test("should get context for Vue", async () => {
+      const result = await client.getContext("How to create components", "/vuejs/core");
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    test("should get context for Express", async () => {
+      const result = await client.getContext("How to create routes", "/expressjs/express");
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("live error handling", () => {
+    const client = new Context7({ apiKey });
+
+    test("should handle invalid library ID gracefully", async () => {
+      await expect(client.getContext("test query", "/nonexistent/library")).rejects.toThrow();
+    });
+  });
+});