chore(client)!: document proxy use + clean up old code

chore: unknown commit message

Author: stainless-bot

README.md

@@ -454,33 +454,62 @@ const client = new Anthropic({
 Note that if given a `ANTHROPIC_LOG=debug` environment variable, this library will log all requests and responses automatically.
 This is intended for debugging purposes only and may change in the future without notice.
 
-### Configuring an HTTP(S) Agent (e.g., for proxies)
+### Fetch options
 
-By default, this library uses a stable agent for all http/https requests to reuse TCP connections, eliminating many TCP & TLS handshakes and shaving around 100ms off most requests.
+If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
 
-If you would like to disable or customize this behavior, for example to use the API behind a proxy, you can pass an `httpAgent` which is used for all requests (be they http or https), for example:
+```ts
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic({
+  fetchOptions: {
+    // `RequestInit` options
+  },
+});
+```
+
+#### Configuring proxies
+
+To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
+options to requests:
+
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
 
-<!-- prettier-ignore -->
 ```ts
-import http from 'http';
-import { HttpsProxyAgent } from 'https-proxy-agent';
+import Anthropic from '@anthropic-ai/sdk';
+import * as undici from 'undici';
 
-// Configure the default for all requests:
+const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
 const client = new Anthropic({
-  httpAgent: new HttpsProxyAgent(process.env.PROXY_URL),
+  fetchOptions: {
+    dispatcher: proxyAgent,
+  },
 });
+```
 
-// Override per-request:
-await client.messages.create(
-  {
-    max_tokens: 1024,
-    messages: [{ role: 'user', content: 'Hello, Claude' }],
-    model: 'claude-3-5-sonnet-latest',
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
+
+```ts
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic({
+  fetchOptions: {
+    proxy: 'http://localhost:8888',
   },
-  {
-    httpAgent: new http.Agent({ keepAlive: false }),
+});
+```
+
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
+
+```ts
+import Anthropic from 'npm:@anthropic-ai/sdk';
+
+const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
+const client = new Anthropic({
+  fetchOptions: {
+    client: httpClient,
   },
-);
+});
 ```
 
 ## Frequently Asked Questions

scripts/utils/attw-report.cjs

@@ -8,7 +8,10 @@ const problems = Object.values(JSON.parse(fs.readFileSync('.attw.json', 'utf-8')
         (
           (problem.kind === 'CJSResolvesToESM' && problem.entrypoint.endsWith('.mjs')) ||
           // This is intentional for backwards compat reasons.
-          (problem.kind === 'MissingExportEquals' && problem.implementationFileName.endsWith('/index.js'))
+          (problem.kind === 'MissingExportEquals' && problem.implementationFileName.endsWith('/index.js')) ||
+          // this is intentional, we deliberately attempt to import types that may not exist from parent node_modules
+          // folders to better support various runtimes without triggering automatic type acquisition.
+          (problem.kind === 'InternalResolutionError' && problem.moduleSpecifier.includes('node_modules'))
         )
       ),
   );

src/client.ts

@@ -1,7 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import type { RequestInit, RequestInfo, BodyInit } from './internal/builtin-types';
-import type { HTTPMethod, PromiseOrValue } from './internal/types';
+import type { HTTPMethod, PromiseOrValue, MergedRequestInit } from './internal/types';
 import { uuid4 } from './internal/utils/uuid';
 import { validatePositiveInteger, isAbsoluteURL } from './internal/utils/values';
 import { sleep } from './internal/utils/sleep';
@@ -149,14 +149,11 @@ export interface ClientOptions {
    * much longer than this timeout before the promise succeeds or fails.
    */
   timeout?: number | undefined;
-
   /**
-   * An HTTP agent used to manage HTTP(S) connections.
-   *
-   * If not provided, an agent will be constructed by default in the Node.js environment,
-   * otherwise no agent is used.
+   * Additional `RequestInit` options to be passed to `fetch` calls.
+   * Properties will be overridden by per-request `fetchOptions`.
    */
-  httpAgent?: Shims.Agent | undefined;
+  fetchOptions?: MergedRequestInit | undefined;
 
   /**
    * Specify a custom `fetch` function implementation.
@@ -221,7 +218,7 @@ export class BaseAnthropic {
   timeout: number;
   logger: Logger | undefined;
   logLevel: LogLevel | undefined;
-  httpAgent: Shims.Agent | undefined;
+  fetchOptions: MergedRequestInit | undefined;
 
   private fetch: Fetch;
   #encoder: Opts.RequestEncoder;
@@ -235,7 +232,7 @@ export class BaseAnthropic {
    * @param {string | null | undefined} [opts.authToken=process.env['ANTHROPIC_AUTH_TOKEN'] ?? null]
    * @param {string} [opts.baseURL=process.env['ANTHROPIC_BASE_URL'] ?? https://api.anthropic.com] - Override the default base URL for the API.
    * @param {number} [opts.timeout=10 minutes] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
-   * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
+   * @param {MergedRequestInit} [opts.fetchOptions] - Additional `RequestInit` options to be passed to `fetch` calls.
    * @param {Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
    * @param {number} [opts.maxRetries=2] - The maximum number of times the client will retry a request.
    * @param {HeadersLike} opts.defaultHeaders - Default headers to include with every request to the API.
@@ -272,7 +269,7 @@ export class BaseAnthropic {
         this.logLevel = envLevel;
       }
     }
-    this.httpAgent = options.httpAgent;
+    this.fetchOptions = options.fetchOptions;
     this.maxRetries = options.maxRetries ?? 2;
     this.fetch = options.fetch ?? Shims.getDefaultFetch();
     this.#encoder = Opts.FallbackEncoder;
@@ -665,30 +662,18 @@ export class BaseAnthropic {
     const url = this.buildURL(path!, query as Record<string, unknown>);
     if ('timeout' in options) validatePositiveInteger('timeout', options.timeout);
     const timeout = options.timeout ?? this.timeout;
-    const httpAgent = options.httpAgent ?? this.httpAgent;
-    const minAgentTimeout = timeout + 1000;
-    if (
-      typeof (httpAgent as any)?.options?.timeout === 'number' &&
-      minAgentTimeout > ((httpAgent as any).options.timeout ?? 0)
-    ) {
-      // Allow any given request to bump our agent active socket timeout.
-      // This may seem strange, but leaking active sockets should be rare and not particularly problematic,
-      // and without mutating agent we would need to create more of them.
-      // This tradeoff optimizes for performance.
-      (httpAgent as any).options.timeout = minAgentTimeout;
-    }
-
     const { bodyHeaders, body } = this.buildBody({ options });
     const reqHeaders = this.buildHeaders({ options, method, bodyHeaders, retryCount });
 
     const req: FinalizedRequestInit = {
       method,
       headers: reqHeaders,
-      ...(httpAgent && { agent: httpAgent }),
       ...(options.signal && { signal: options.signal }),
       ...((globalThis as any).ReadableStream &&
         body instanceof (globalThis as any).ReadableStream && { duplex: 'half' }),
       ...(body && { body }),
+      ...((this.fetchOptions as any) ?? {}),
+      ...((options.fetchOptions as any) ?? {}),
     };
 
     return { req, url, timeout };

src/internal/builtin-types.ts

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export type Fetch = typeof fetch;
+export type Fetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 
 /**
  * An alias to the builtin `RequestInit` type so we can

src/internal/request-options.ts

@@ -2,11 +2,10 @@
 
 import { NullableHeaders } from './headers';
 
-import type { Agent } from './shims';
 import type { BodyInit } from './builtin-types';
 import { isEmptyObj, hasOwn } from './utils/values';
 import { Stream } from '../streaming';
-import type { HTTPMethod, KeysEnum } from './types';
+import type { HTTPMethod, KeysEnum, MergedRequestInit } from './types';
 import { type HeadersLike } from './headers';
 
 export type FinalRequestOptions = RequestOptions & { method: HTTPMethod; path: string };
@@ -20,7 +19,7 @@ export type RequestOptions = {
   maxRetries?: number;
   stream?: boolean | undefined;
   timeout?: number;
-  httpAgent?: Agent;
+  fetchOptions?: MergedRequestInit;
   signal?: AbortSignal | undefined | null;
   idempotencyKey?: string;
 
@@ -41,7 +40,7 @@ const requestOptionsKeys: KeysEnum<RequestOptions> = {
   maxRetries: true,
   stream: true,
   timeout: true,
-  httpAgent: true,
+  fetchOptions: true,
   signal: true,
   idempotencyKey: true,
 

src/internal/shims.ts

@@ -10,18 +10,6 @@
 import { type Fetch } from './builtin-types';
 import { type ReadableStream } from './shim-types';
 
-/**
- * A minimal copy of the `Agent` type from `undici-types` so we can
- * use it in the `ClientOptions` type.
- *
- * https://nodejs.org/api/http.html#class-httpagent
- */
-export interface Agent {
-  dispatch(options: any, handler: any): boolean;
-  closed: boolean;
-  destroyed: boolean;
-}
-
 export function getDefaultFetch(): Fetch {
   if (typeof fetch !== 'undefined') {
     return fetch;

src/internal/types.ts

@@ -4,3 +4,95 @@ export type PromiseOrValue<T> = T | Promise<T>;
 export type HTTPMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
 
 export type KeysEnum<T> = { [P in keyof Required<T>]: true };
+
+type NotAny<T> = [unknown] extends [T] ? never : T;
+type Literal<T> = PropertyKey extends T ? never : T;
+type MappedLiteralKeys<T> = T extends any ? Literal<keyof T> : never;
+type MappedIndex<T, K> =
+  T extends any ?
+    K extends keyof T ?
+      T[K]
+    : never
+  : never;
+
+/**
+ * Some environments overload the global fetch function, and Parameters<T> only gets the last signature.
+ */
+type OverloadedParameters<T> =
+  T extends (
+    {
+      (...args: infer A): unknown;
+      (...args: infer B): unknown;
+      (...args: infer C): unknown;
+      (...args: infer D): unknown;
+    }
+  ) ?
+    A | B | C | D
+  : T extends (
+    {
+      (...args: infer A): unknown;
+      (...args: infer B): unknown;
+      (...args: infer C): unknown;
+    }
+  ) ?
+    A | B | C
+  : T extends (
+    {
+      (...args: infer A): unknown;
+      (...args: infer B): unknown;
+    }
+  ) ?
+    A | B
+  : T extends (...args: infer A) => unknown ? A
+  : never;
+
+/* eslint-disable */
+/**
+ * These imports attempt to get types from a parent package's dependencies.
+ * Unresolved bare specifiers can trigger [automatic type acquisition][1] in some projects, which
+ * would cause typescript to show types not present at runtime. To avoid this, we import
+ * directly from parent node_modules folders.
+ *
+ * We need to check multiple levels because we don't know what directory structure we'll be in.
+ * For example, pnpm generates directories like this:
+ * ```
+ * node_modules
+ * ├── .pnpm
+ * │   └── [email protected]
+ * │       └── node_modules
+ * │           └── pkg
+ * │               └── internal
+ * │                   └── types.d.ts
+ * ├── pkg -> .pnpm/[email protected]/node_modules/pkg
+ * └── undici
+ * ```
+ *
+ * [1]: https://www.typescriptlang.org/tsconfig/#typeAcquisition
+ */
+/** @ts-ignore For users with \@types/node */
+type UndiciTypesRequestInit = NotAny<import('../node_modules/undici-types').RequestInit> | NotAny<import('../../node_modules/undici-types').RequestInit> | NotAny<import('../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici-types').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici-types').RequestInit>;
+/** @ts-ignore For users with undici */
+type UndiciRequestInit = NotAny<import('../node_modules/undici').RequestInit> | NotAny<import('../../node_modules/undici').RequestInit> | NotAny<import('../../../node_modules/undici').RequestInit> | NotAny<import('../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici').RequestInit>;
+/** @ts-ignore For users with \@types/bun */
+type BunRequestInit = globalThis.FetchRequestInit;
+/** @ts-ignore For users with node-fetch */
+type NodeFetchRequestInit = NotAny<import('../node_modules/node-fetch').RequestInit> | NotAny<import('../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/node-fetch').RequestInit>;
+/** @ts-ignore For users who use Deno */
+type FetchRequestInit = NonNullable<OverloadedParameters<typeof fetch>[1]>;
+/* eslint-enable */
+
+type RequestInits =
+  | NotAny<UndiciTypesRequestInit>
+  | NotAny<UndiciRequestInit>
+  | NotAny<BunRequestInit>
+  | NotAny<NodeFetchRequestInit>
+  | NotAny<RequestInit>
+  | NotAny<FetchRequestInit>;
+
+/**
+ * This type contains `RequestInit` options that may be available on the current runtime,
+ * including per-platform extensions like `dispatcher`, `agent`, `client`, etc.
+ */
+export type MergedRequestInit = {
+  [K in MappedLiteralKeys<RequestInits>]?: MappedIndex<RequestInits, K> | undefined;
+};

tests/index.test.ts

@@ -179,6 +179,15 @@ describe('instantiate client', () => {
     expect(response).toEqual({ url: 'http://localhost:5000/foo', custom: true });
   });
 
+  test('explicit global fetch', async () => {
+    // make sure the global fetch type is assignable to our Fetch type
+    const client = new Anthropic({
+      baseURL: 'http://localhost:5000/',
+      apiKey: 'my-anthropic-api-key',
+      fetch: defaultFetch,
+    });
+  });
+
   test('custom signal', async () => {
     const client = new Anthropic({
       baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010',