@anthropic-ai/sdk 0.5.10 → 0.6.1

package/src/core.ts

@@ -10,6 +10,7 @@ import {
   type RequestInit,
   type Response,
 } from './_shims/fetch.js';
+export { type Response };
 import { isMultipartBody } from './uploads';
 export {
   maybeMultipartFormRequestOptions,
@@ -22,6 +23,106 @@ const MAX_RETRIES = 2;
 
 export type Fetch = (url: RequestInfo, init?: RequestInit) => Promise<Response>;
 
+type PromiseOrValue<T> = T | Promise<T>;
+
+type APIResponseProps = {
+  response: Response;
+  options: FinalRequestOptions;
+  controller: AbortController;
+};
+
+async function defaultParseResponse<T>(props: APIResponseProps): Promise<T> {
+  const { response } = props;
+  if (props.options.stream) {
+    // Note: there is an invariant here that isn't represented in the type system
+    // that if you set `stream: true` the response type must also be `Stream<T>`
+    return new Stream(response, props.controller) as any;
+  }
+
+  const contentType = response.headers.get('content-type');
+  if (contentType?.includes('application/json')) {
+    const json = await response.json();
+
+    debug('response', response.status, response.url, response.headers, json);
+
+    return json as T;
+  }
+
+  // TODO handle blob, arraybuffer, other content types, etc.
+  const text = await response.text();
+  debug('response', response.status, response.url, response.headers, text);
+  return text as T;
+}
+
+/**
+ * A subclass of `Promise` providing additional helper methods
+ * for interacting with the SDK.
+ */
+export class APIPromise<T> extends Promise<T> {
+  private parsedPromise: Promise<T> | undefined;
+
+  constructor(
+    private responsePromise: Promise<APIResponseProps>,
+    private parseResponse: (props: APIResponseProps) => PromiseOrValue<T> = defaultParseResponse,
+  ) {
+    super((resolve) => {
+      // this is maybe a bit weird but this has to be a no-op to not implicitly
+      // parse the response body; instead .then, .catch, .finally are overridden
+      // to parse the response
+      resolve(null as any);
+    });
+  }
+
+  _thenUnwrap<U>(transform: (data: T) => U): APIPromise<U> {
+    return new APIPromise(this.responsePromise, async (props) => transform(await this.parseResponse(props)));
+  }
+
+  /**
+   * Gets the raw `Response` instance instead of parsing the response
+   * data.
+   *
+   * If you want to parse the response body but still get the `Response`
+   * instance, you can use {@link withResponse()}.
+   */
+  asResponse(): Promise<Response> {
+    return this.responsePromise.then((p) => p.response);
+  }
+  /**
+   * Gets the parsed response data and the raw `Response` instance.
+   *
+   * If you just want to get the raw `Response` instance without parsing it,
+   * you can use {@link asResponse()}.
+   */
+  async withResponse(): Promise<{ data: T; response: Response }> {
+    const [data, response] = await Promise.all([this.parse(), this.asResponse()]);
+    return { data, response };
+  }
+
+  private parse(): Promise<T> {
+    if (!this.parsedPromise) {
+      this.parsedPromise = this.responsePromise.then(this.parseResponse);
+    }
+    return this.parsedPromise;
+  }
+
+  override then<TResult1 = T, TResult2 = never>(
+    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
+  ): Promise<TResult1 | TResult2> {
+    return this.parse().then(onfulfilled, onrejected);
+  }
+
+  override catch<TResult = never>(
+    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null,
+  ): Promise<T | TResult> {
+    return this.parse().catch(onrejected);
+  }
+
+  override finally(onfinally?: (() => void) | undefined | null): Promise<T> {
+    return this.parse().finally(onfinally);
+  }
+}
+
 export abstract class APIClient {
   baseURL: string;
   maxRetries: number;
@@ -34,7 +135,7 @@ export abstract class APIClient {
   constructor({
     baseURL,
     maxRetries,
-    timeout = 60 * 1000, // 60s
+    timeout = 600000, // 10 minutes
     httpAgent,
     fetch: overridenFetch,
   }: {
@@ -85,27 +186,39 @@ export abstract class APIClient {
     return `stainless-node-retry-${uuid4()}`;
   }
 
-  get<Req extends {}, Rsp>(path: string, opts?: RequestOptions<Req>): Promise<Rsp> {
-    return this.request({ method: 'get', path, ...opts });
+  get<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+    return this.methodRequest('get', path, opts);
   }
-  post<Req extends {}, Rsp>(path: string, opts?: RequestOptions<Req>): Promise<Rsp> {
-    return this.request({ method: 'post', path, ...opts });
+
+  post<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+    return this.methodRequest('post', path, opts);
   }
-  patch<Req extends {}, Rsp>(path: string, opts?: RequestOptions<Req>): Promise<Rsp> {
-    return this.request({ method: 'patch', path, ...opts });
+
+  patch<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+    return this.methodRequest('patch', path, opts);
   }
-  put<Req extends {}, Rsp>(path: string, opts?: RequestOptions<Req>): Promise<Rsp> {
-    return this.request({ method: 'put', path, ...opts });
+
+  put<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+    return this.methodRequest('put', path, opts);
   }
-  delete<Req extends {}, Rsp>(path: string, opts?: RequestOptions<Req>): Promise<Rsp> {
-    return this.request({ method: 'delete', path, ...opts });
+
+  delete<Req extends {}, Rsp>(path: string, opts?: PromiseOrValue<RequestOptions<Req>>): APIPromise<Rsp> {
+    return this.methodRequest('delete', path, opts);
+  }
+
+  private methodRequest<Req extends {}, Rsp>(
+    method: HTTPMethod,
+    path: string,
+    opts?: PromiseOrValue<RequestOptions<Req>>,
+  ): APIPromise<Rsp> {
+    return this.request(Promise.resolve(opts).then((opts) => ({ method, path, ...opts })));
   }
 
   getAPIList<Item, PageClass extends AbstractPage<Item> = AbstractPage<Item>>(
     path: string,
     Page: new (...args: any[]) => PageClass,
     opts?: RequestOptions<any>,
-  ): PagePromise<PageClass> {
+  ): PagePromise<PageClass, Item> {
     return this.requestAPIList(Page, { method: 'get', path, ...opts });
   }
 
@@ -141,7 +254,10 @@ export abstract class APIClient {
     const timeout = options.timeout ?? this.timeout;
     const httpAgent = options.httpAgent ?? this.httpAgent ?? getDefaultAgent(url);
     const minAgentTimeout = timeout + 1000;
-    if ((httpAgent as any)?.options && minAgentTimeout > ((httpAgent as any).options.timeout ?? 0)) {
+    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.
@@ -199,14 +315,27 @@ export abstract class APIClient {
     return APIError.generate(status, error, message, headers);
   }
 
-  async request<Req extends {}, Rsp>(
-    options: FinalRequestOptions<Req>,
-    retriesRemaining = options.maxRetries ?? this.maxRetries,
-  ): Promise<APIResponse<Rsp>> {
+  request<Req extends {}, Rsp>(
+    options: PromiseOrValue<FinalRequestOptions<Req>>,
+    remainingRetries: number | null = null,
+  ): APIPromise<Rsp> {
+    return new APIPromise(this.makeRequest(options, remainingRetries));
+  }
+
+  private async makeRequest(
+    optionsInput: PromiseOrValue<FinalRequestOptions>,
+    retriesRemaining: number | null,
+  ): Promise<APIResponseProps> {
+    const options = await optionsInput;
+    if (retriesRemaining == null) {
+      retriesRemaining = options.maxRetries ?? this.maxRetries;
+    }
+
     const { req, url, timeout } = this.buildRequest(options);
+
     await this.prepareRequest(req, { url });
 
-    this.debug('request', url, options, req.headers);
+    debug('request', url, options, req.headers);
 
     if (options.signal?.aborted) {
       throw new APIUserAbortError();
@@ -239,48 +368,21 @@ export abstract class APIClient {
       const errJSON = safeJSON(errText);
       const errMessage = errJSON ? undefined : errText;
 
-      this.debug('response', response.status, url, responseHeaders, errMessage);
+      debug('response', response.status, url, responseHeaders, errMessage);
 
       const err = this.makeStatusError(response.status, errJSON, errMessage, responseHeaders);
       throw err;
     }
 
-    if (options.stream) {
-      // Note: there is an invariant here that isn't represented in the type system
-      // that if you set `stream: true` the response type must also be `Stream<T>`
-      return new Stream(response, controller) as any;
-    }
-
-    const contentType = response.headers.get('content-type');
-    if (contentType?.includes('application/json')) {
-      const json = await response.json();
-
-      if (typeof json === 'object' && json != null) {
-        /** @deprecated – we expect to change this interface in the near future. */
-        Object.defineProperty(json, 'responseHeaders', {
-          enumerable: false,
-          writable: false,
-          value: responseHeaders,
-        });
-      }
-
-      this.debug('response', response.status, url, responseHeaders, json);
-
-      return json as APIResponse<Rsp>;
-    }
-
-    // TODO handle blob, arraybuffer, other content types, etc.
-    const text = response.text();
-    this.debug('response', response.status, url, responseHeaders, text);
-    return text as Promise<any>;
+    return { response, options, controller };
   }
 
   requestAPIList<Item = unknown, PageClass extends AbstractPage<Item> = AbstractPage<Item>>(
     Page: new (...args: ConstructorParameters<typeof AbstractPage>) => PageClass,
     options: FinalRequestOptions,
-  ): PagePromise<PageClass> {
-    const requestPromise = this.request(options) as Promise<APIResponse<unknown>>;
-    return new PagePromise(this, requestPromise, options, Page);
+  ): PagePromise<PageClass, Item> {
+    const request = this.makeRequest(options, null);
+    return new PagePromise<PageClass, Item>(this, request, Page);
   }
 
   buildURL<Req>(path: string, query: Req | undefined): string {
@@ -360,11 +462,11 @@ export abstract class APIClient {
     return false;
   }
 
-  private async retryRequest<Req extends {}, Rsp>(
-    options: FinalRequestOptions<Req>,
+  private async retryRequest(
+    options: FinalRequestOptions,
     retriesRemaining: number,
     responseHeaders?: Headers | undefined,
-  ): Promise<Rsp> {
+  ): Promise<APIResponseProps> {
     retriesRemaining -= 1;
 
     // About the Retry-After header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
@@ -377,7 +479,7 @@ export abstract class APIClient {
     const timeout = this.calculateRetryTimeoutSeconds(retriesRemaining, retryAfter, maxRetries) * 1000;
     await sleep(timeout);
 
-    return this.request(options, retriesRemaining);
+    return this.makeRequest(options, retriesRemaining);
   }
 
   private calculateRetryTimeoutSeconds(
@@ -408,12 +510,6 @@ export abstract class APIClient {
   private getUserAgent(): string {
     return `${this.constructor.name}/JS ${VERSION}`;
   }
-
-  private debug(action: string, ...args: any[]) {
-    if (typeof process !== 'undefined' && process.env['DEBUG'] === 'true') {
-      console.log(`${this.constructor.name}:DEBUG:${action}`, ...args);
-    }
-  }
 }
 
 export class APIResource {
@@ -443,9 +539,14 @@ export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
   #client: APIClient;
   protected options: FinalRequestOptions;
 
-  constructor(client: APIClient, response: APIResponse<unknown>, options: FinalRequestOptions) {
+  protected response: Response;
+  protected body: unknown;
+
+  constructor(client: APIClient, response: Response, body: unknown, options: FinalRequestOptions) {
     this.#client = client;
     this.options = options;
+    this.response = response;
+    this.body = body;
   }
 
   /**
@@ -502,35 +603,33 @@ export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
   }
 }
 
+/**
+ * This subclass of Promise will resolve to an instantiated Page once the request completes.
+ *
+ * It also implements AsyncIterable to allow auto-paginating iteration on an unawaited list call, eg:
+ *
+ *    for await (const item of client.items.list()) {
+ *      console.log(item)
+ *    }
+ */
 export class PagePromise<
     PageClass extends AbstractPage<Item>,
     Item = ReturnType<PageClass['getPaginatedItems']>[number],
   >
-  extends Promise<PageClass>
+  extends APIPromise<PageClass>
   implements AsyncIterable<Item>
 {
-  /**
-   * This subclass of Promise will resolve to an instantiated Page once the request completes.
-   */
   constructor(
     client: APIClient,
-    requestPromise: Promise<APIResponse<unknown>>,
-    options: FinalRequestOptions,
+    request: Promise<APIResponseProps>,
     Page: new (...args: ConstructorParameters<typeof AbstractPage>) => PageClass,
   ) {
-    super((resolve, reject) =>
-      requestPromise.then((response) => resolve(new Page(client, response, options))).catch(reject),
+    super(
+      request,
+      async (props) => new Page(client, props.response, await defaultParseResponse(props), props.options),
     );
   }
 
-  /**
-   * Enable subclassing Promise.
-   * Ref: https://stackoverflow.com/a/60328122
-   */
-  static get [Symbol.species]() {
-    return Promise;
-  }
-
   /**
    * Allow auto-paginating iteration on an unawaited list call, eg:
    *
@@ -617,11 +716,6 @@ export type FinalRequestOptions<Req extends {} = Record<string, unknown> | Reada
   path: string;
 };
 
-export type APIResponse<T> = T & {
-  /** @deprecated - we plan to add a different way to access raw response information shortly. */
-  responseHeaders: Headers;
-};
-
 declare const Deno: any;
 declare const EdgeRuntime: any;
 type Arch = 'x32' | 'x64' | 'arm' | 'arm64' | `other:${string}` | 'unknown';
@@ -635,12 +729,13 @@ type PlatformName =
   | 'Android'
   | `Other:${string}`
   | 'Unknown';
+type Browser = 'ie' | 'edge' | 'chrome' | 'firefox' | 'safari';
 type PlatformProperties = {
   'X-Stainless-Lang': 'js';
   'X-Stainless-Package-Version': string;
   'X-Stainless-OS': PlatformName;
   'X-Stainless-Arch': Arch;
-  'X-Stainless-Runtime': 'node' | 'deno' | 'edge' | 'unknown';
+  'X-Stainless-Runtime': 'node' | 'deno' | 'edge' | `browser:${Browser}` | 'unknown';
   'X-Stainless-Runtime-Version': string;
 };
 const getPlatformProperties = (): PlatformProperties => {
@@ -675,7 +770,20 @@ const getPlatformProperties = (): PlatformProperties => {
       'X-Stainless-Runtime-Version': process.version,
     };
   }
-  // TODO add support for Cloudflare workers, browsers, etc.
+
+  const browserInfo = getBrowserInfo();
+  if (browserInfo) {
+    return {
+      'X-Stainless-Lang': 'js',
+      'X-Stainless-Package-Version': VERSION,
+      'X-Stainless-OS': 'Unknown',
+      'X-Stainless-Arch': 'unknown',
+      'X-Stainless-Runtime': `browser:${browserInfo.browser}`,
+      'X-Stainless-Runtime-Version': browserInfo.version,
+    };
+  }
+
+  // TODO add support for Cloudflare workers, etc.
   return {
     'X-Stainless-Lang': 'js',
     'X-Stainless-Package-Version': VERSION,
@@ -686,6 +794,44 @@ const getPlatformProperties = (): PlatformProperties => {
   };
 };
 
+type BrowserInfo = {
+  browser: Browser;
+  version: string;
+};
+
+declare const navigator: { userAgent: string } | undefined;
+
+// Note: modified from https://github.com/JS-DevTools/host-environment/blob/b1ab79ecde37db5d6e163c050e54fe7d287d7c92/src/isomorphic.browser.ts
+function getBrowserInfo(): BrowserInfo | null {
+  if (typeof navigator === 'undefined' || !navigator) {
+    return null;
+  }
+
+  // NOTE: The order matters here!
+  const browserPatterns = [
+    { key: 'edge' as const, pattern: /Edge(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    { key: 'ie' as const, pattern: /MSIE(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    { key: 'ie' as const, pattern: /Trident(?:.*rv\:(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    { key: 'chrome' as const, pattern: /Chrome(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    { key: 'firefox' as const, pattern: /Firefox(?:\W+(\d+)\.(\d+)(?:\.(\d+))?)?/ },
+    { key: 'safari' as const, pattern: /(?:Version\W+(\d+)\.(\d+)(?:\.(\d+))?)?(?:\W+Mobile\S*)?\W+Safari/ },
+  ];
+
+  // Find the FIRST matching browser
+  for (const { key, pattern } of browserPatterns) {
+    const match = pattern.exec(navigator.userAgent);
+    if (match) {
+      const major = match[1] || 0;
+      const minor = match[2] || 0;
+      const patch = match[3] || 0;
+
+      return { browser: key, version: `${major}.${minor}.${patch}` };
+    }
+  }
+
+  return null;
+}
+
 const normalizeArch = (arch: string): Arch => {
   // Node docs:
   // - https://nodejs.org/api/process.html#processarch
@@ -767,14 +913,16 @@ export const ensurePresent = <T>(value: T | null | undefined): T => {
 /**
  * Read an environment variable.
  *
- * Will return an empty string if the environment variable doesn't exist or cannot be accessed.
+ * Will return undefined if the environment variable doesn't exist or cannot be accessed.
  */
 export const readEnv = (env: string): string | undefined => {
-  if (typeof process === 'undefined') {
-    return undefined;
+  if (typeof process !== 'undefined') {
+    return process.env?.[env] ?? undefined;
   }
-
-  return process.env[env] ?? undefined;
+  if (typeof Deno !== 'undefined') {
+    return Deno.env?.get?.(env);
+  }
+  return undefined;
 };
 
 export const coerceInteger = (value: unknown): number => {
@@ -830,6 +978,12 @@ export function hasOwn(obj: Object, key: string): boolean {
   return Object.prototype.hasOwnProperty.call(obj, key);
 }
 
+export function debug(action: string, ...args: any[]) {
+  if (typeof process !== 'undefined' && process.env['DEBUG'] === 'true') {
+    console.log(`Anthropic:DEBUG:${action}`, ...args);
+  }
+}
+
 /**
  * https://stackoverflow.com/a/2117523
  */
@@ -841,6 +995,17 @@ const uuid4 = () => {
   });
 };
 
+export const isRunningInBrowser = () => {
+  return (
+    // @ts-ignore
+    typeof window !== 'undefined' &&
+    // @ts-ignore
+    typeof window.document !== 'undefined' &&
+    // @ts-ignore
+    typeof navigator !== 'undefined'
+  );
+};
+
 export interface HeadersProtocol {
   get: (header: string) => string | null | undefined;
 }

package/src/index.ts

@@ -69,13 +69,26 @@ export interface ClientOptions {
   authToken?: string | null;
 }
 
-/** Instantiate the API Client. */
+/** API Client for interfacing with the Anthropic API. */
 export class Anthropic extends Core.APIClient {
   apiKey: string | null;
   authToken?: string | null;
 
   private _options: ClientOptions;
 
+  /**
+   * API Client for interfacing with the Anthropic API.
+   *
+   * @param {string | null} [opts.apiKey=process.env['ANTHROPIC_API_KEY']] - The API Key to send to the API.
+   * @param {string} [opts.baseURL] - 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 {Core.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 {Core.Headers} opts.defaultHeaders - Default headers to include with every request to the API.
+   * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.
+   * @param {string | null} [opts.authToken]
+   */
   constructor({
     apiKey = Core.readEnv('ANTHROPIC_API_KEY') ?? null,
     authToken = Core.readEnv('ANTHROPIC_AUTH_TOKEN') ?? null,
@@ -92,7 +105,7 @@ export class Anthropic extends Core.APIClient {
 
     super({
       baseURL: options.baseURL!,
-      timeout: options.timeout,
+      timeout: options.timeout ?? 600000 /* 10 minutes */,
       httpAgent: options.httpAgent,
       maxRetries: options.maxRetries,
       fetch: options.fetch,
@@ -206,9 +219,13 @@ export namespace Anthropic {
   export import toFile = Uploads.toFile;
   export import fileFromPath = Uploads.fileFromPath;
 
+  export import RequestOptions = Core.RequestOptions;
+
   export import Completions = API.Completions;
   export import Completion = API.Completion;
   export import CompletionCreateParams = API.CompletionCreateParams;
+  export import CompletionCreateParamsNonStreaming = API.CompletionCreateParamsNonStreaming;
+  export import CompletionCreateParamsStreaming = API.CompletionCreateParamsStreaming;
 }
 
 export default Anthropic;