Merge pull request #55 from stainless-api/release-please--branches--main--changes--next--components--stainless

release: 0.1.0-alpha.16

Author: meorphis

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.15"
+  ".": "0.1.0-alpha.16"
 }

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.0-alpha.16 (2025-01-22)
+
+Full Changelog: [v0.1.0-alpha.15...v0.1.0-alpha.16](https://github.com/stainless-api/builds-node-api/compare/v0.1.0-alpha.15...v0.1.0-alpha.16)
+
+### ⚠ BREAKING CHANGES
+
+* **client:** document proxy use + clean up old code ([#57](https://github.com/stainless-api/builds-node-api/issues/57))
+
+### Bug Fixes
+
+* correctly send default header values ([#58](https://github.com/stainless-api/builds-node-api/issues/58)) ([6818d5a](https://github.com/stainless-api/builds-node-api/commit/6818d5a92cfa3edeeb88797b7f5e567cee31dcc4))
+
+
+### Chores
+
+* **client:** document proxy use + clean up old code ([#57](https://github.com/stainless-api/builds-node-api/issues/57)) ([18f95e7](https://github.com/stainless-api/builds-node-api/commit/18f95e7c13d5920a88aee790477824c66989cc05))
+* **client:** improve node-fetch file upload errors ([#56](https://github.com/stainless-api/builds-node-api/issues/56)) ([1f48b98](https://github.com/stainless-api/builds-node-api/commit/1f48b98aaf358183b517d07da5fd44909119f1c1))
+* **internal:** codegen related update ([#54](https://github.com/stainless-api/builds-node-api/issues/54)) ([a0504f2](https://github.com/stainless-api/builds-node-api/commit/a0504f2230fb783e10b1443645f5d26fdde13987))
+* **internal:** minor restructuring ([#59](https://github.com/stainless-api/builds-node-api/issues/59)) ([a03e6ca](https://github.com/stainless-api/builds-node-api/commit/a03e6ca28992147f6aac63493ec28f3f99ac6e33))
+
 ## 0.1.0-alpha.15 (2025-01-17)
 
 Full Changelog: [v0.1.0-alpha.14...v0.1.0-alpha.15](https://github.com/stainless-api/builds-node-api/compare/v0.1.0-alpha.14...v0.1.0-alpha.15)

README.md

@@ -250,30 +250,62 @@ const client = new Stainless({
 Note that if given a `STAINLESS_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 Stainless from 'stainless';
+
+const client = new Stainless({
+  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 Stainless from 'stainless';
+import * as undici from 'undici';
+
+const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
+const client = new Stainless({
+  fetchOptions: {
+    dispatcher: proxyAgent,
+  },
+});
+```
+
+<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 Stainless from 'stainless';
 
-// Configure the default for all requests:
 const client = new Stainless({
-  httpAgent: new HttpsProxyAgent(process.env.PROXY_URL),
+  fetchOptions: {
+    proxy: 'http://localhost:8888',
+  },
 });
+```
 
-// Override per-request:
-await client.builds.outputs.retrieve(
-  'bui_123',
-  { target: 'node' },
-  {
-    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 Stainless from 'npm:stainless';
+
+const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
+const client = new Stainless({
+  fetchOptions: {
+    client: httpClient,
   },
-);
+});
 ```
 
 ## Frequently Asked Questions

package.json

@@ -1,6 +1,6 @@
 {
   "name": "stainless",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.16",
   "description": "The official TypeScript library for the Stainless API",
   "author": "Stainless <[email protected]>",
   "types": "dist/index.d.ts",

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';
@@ -11,14 +11,12 @@ import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
 import { VERSION } from './version';
-import { isBlobLike } from './uploads';
-import { buildHeaders } from './internal/headers';
 import * as Errors from './error';
 import * as Uploads from './uploads';
 import * as API from './resources/index';
 import { APIPromise } from './api-promise';
 import { type Fetch } from './internal/builtin-types';
-import { HeadersLike, NullableHeaders } from './internal/headers';
+import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
 import { readEnv } from './internal/utils/env';
 import { logger } from './internal/utils/log';
@@ -78,15 +76,12 @@ export interface ClientOptions {
    * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
    * much longer than this timeout before the promise succeeds or fails.
    */
-  timeout?: number;
-
+  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;
+  fetchOptions?: MergedRequestInit | undefined;
 
   /**
    * Specify a custom `fetch` function implementation.
@@ -101,23 +96,23 @@ export interface ClientOptions {
    *
    * @default 2
    */
-  maxRetries?: number;
+  maxRetries?: number | undefined;
 
   /**
    * Default headers to include with every request to the API.
    *
    * These can be removed in individual requests by explicitly setting the
    * header to `null` in request options.
    */
-  defaultHeaders?: HeadersLike;
+  defaultHeaders?: HeadersLike | undefined;
 
   /**
    * Default query parameters to include with every request to the API.
    *
    * These can be removed in individual requests by explicitly setting the
    * param to `undefined` in request options.
    */
-  defaultQuery?: Record<string, string | undefined>;
+  defaultQuery?: Record<string, string | undefined> | undefined;
 
   /**
    * Set the log level.
@@ -147,7 +142,7 @@ export class Stainless {
   timeout: number;
   logger: Logger | undefined;
   logLevel: LogLevel | undefined;
-  httpAgent: Shims.Agent | undefined;
+  fetchOptions: MergedRequestInit | undefined;
 
   private fetch: Fetch;
   #encoder: Opts.RequestEncoder;
@@ -160,7 +155,7 @@ export class Stainless {
    * @param {string | undefined} [opts.apiKey=process.env['API_KEY'] ?? undefined]
    * @param {string} [opts.baseURL=process.env['STAINLESS_BASE_URL'] ?? https://api.stainlessapi.com] - Override the default base URL for the API.
    * @param {number} [opts.timeout=1 minute] - 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.
@@ -194,7 +189,7 @@ export class Stainless {
         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;
@@ -331,14 +326,8 @@ export class Stainless {
     opts?: PromiseOrValue<RequestOptions>,
   ): APIPromise<Rsp> {
     return this.request(
-      Promise.resolve(opts).then(async (opts) => {
-        const body =
-          opts && isBlobLike(opts?.body) ? new DataView(await opts.body.arrayBuffer())
-          : opts?.body instanceof DataView ? opts.body
-          : opts?.body instanceof ArrayBuffer ? new DataView(opts.body)
-          : opts && ArrayBuffer.isView(opts?.body) ? new DataView(opts.body.buffer)
-          : opts?.body;
-        return { method, path, ...opts, body };
+      Promise.resolve(opts).then((opts) => {
+        return { method, path, ...opts };
       }),
     );
   }
@@ -533,30 +522,18 @@ export class Stainless {
     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/index.ts

@@ -2,13 +2,7 @@
 
 export { Stainless as default } from './client';
 
-export {
-  multipartFormRequestOptions,
-  maybeMultipartFormRequestOptions,
-  type Uploadable,
-  createForm,
-  toFile,
-} from './uploads';
+export { type Uploadable, toFile } from './uploads';
 export { APIPromise } from './api-promise';
 export { Stainless, type ClientOptions } from './client';
 export {

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,10 +2,9 @@
 
 import { NullableHeaders } from './headers';
 
-import type { Agent } from './shims';
 import type { BodyInit } from './builtin-types';
 import { isEmptyObj, hasOwn } from './utils/values';
-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 };
@@ -19,7 +18,7 @@ export type RequestOptions = {
   maxRetries?: number;
   stream?: boolean | undefined;
   timeout?: number;
-  httpAgent?: Agent;
+  fetchOptions?: MergedRequestInit;
   signal?: AbortSignal | undefined | null;
   idempotencyKey?: string;
 
@@ -39,7 +38,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;
@@ -122,3 +110,36 @@ export function ReadableStreamFrom<T>(iterable: Iterable<T> | AsyncIterable<T>):
     },
   });
 }
+
+/**
+ * Most browsers don't yet have async iterable support for ReadableStream,
+ * and Node has a very different way of reading bytes from its "ReadableStream".
+ *
+ * This polyfill was pulled from https://github.com/MattiasBuelens/web-streams-polyfill/pull/122#issuecomment-1627354490
+ */
+export function ReadableStreamToAsyncIterable<T>(stream: any): AsyncIterableIterator<T> {
+  if (stream[Symbol.asyncIterator]) return stream;
+
+  const reader = stream.getReader();
+  return {
+    async next() {
+      try {
+        const result = await reader.read();
+        if (result?.done) reader.releaseLock(); // release lock when stream becomes closed
+        return result;
+      } catch (e) {
+        reader.releaseLock(); // release lock when stream becomes errored
+        throw e;
+      }
+    },
+    async return() {
+      const cancelPromise = reader.cancel();
+      reader.releaseLock();
+      await cancelPromise;
+      return { done: true, value: undefined };
+    },
+    [Symbol.asyncIterator]() {
+      return this;
+    },
+  };
+}