# https://github.com/cloudflare/cloudflare-typescript Project Manual Generated at: 2026-06-06 08:19:16 UTC ## Table of Contents - [Installation and Basic Usage](#page-1) - [SDK Architecture, Shims, and Runtime Compatibility](#page-2) - [Request Patterns, Errors, Retries, and Pagination](#page-3) - [API Resources, Releases, and Known Issues](#page-4) ## Installation and Basic Usage ### Related Pages Related topics: [SDK Architecture, Shims, and Runtime Compatibility](#page-2), [Request Patterns, Errors, Retries, and Pagination](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md) - [src/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/index.ts) - [src/resources/ai/models/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/index.ts) - [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts) - [src/resources/ai/models/schema.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/schema.ts) - [src/resources/zero-trust/dex/commands/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/index.ts) - [src/resources/zero-trust/dex/commands/devices.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts) - [src/resources/zero-trust/dlp/profiles/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/index.ts)
# Installation and Basic Usage The `cloudflare` package is the official TypeScript SDK for the Cloudflare API. Every source file in the repository is generated from an OpenAPI specification by Stainless, so the public surface (resources, methods, types) tracks the upstream API one-to-one. This page documents how the package is consumed: importing the client, authenticating, calling resources, and handling the most common patterns (pagination, file uploads). Source: [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md) ## Installation and Import The default export is the `Cloudflare` client class. The README demonstrates the standard import alongside the `toFile` upload helper, which is exported from the same entry point: ```ts import Cloudflare, { toFile } from 'cloudflare'; ``` Source: [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md) > Note: the repository does not publish an explicit "Installation" section in `README.md` within the retrieved source. Community guidance ([Release Calendar, #2755](https://github.com/cloudflare/cloudflare-typescript/issues/2755)) and the [Upcoming major version upgrade, #2553](https://github.com/cloudflare/cloudflare-typescript/issues/2553) track indicate the package is distributed as `cloudflare` on npm, with major-version bumps used to signal breaking changes (v5 → v6 in April 2026). ## Client Construction and Authentication A client instance is created with `new Cloudflare()`. The constructor accepts options that set the authentication credential and transport behavior: ```ts const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN, }); ``` The Cloudflare API is reached over HTTPS and authentication is performed with a bearer API token. Once instantiated, every product area is reachable as a nested property on the client. ## Resource Navigation Resources mirror the Cloudflare API hierarchy exactly. Sub-resources are exported from per-folder `index.ts` barrels, then re-attached to the root client. For example, the DEX device-capture namespace is exposed as `client.zeroTrust.dex.commands.devices`: ```ts for await (const page of client.zeroTrust.dex.commands.devices.list({ account_id: '01a7362d577a6c3019a474fd6f485823', page: 1, per_page: 1, })) { // ... } ``` Source: [src/resources/zero-trust/dex/commands/devices.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts) Source: [src/resources/zero-trust/dex/commands/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/index.ts) The `Models` resource follows the same shape, with its own `schema` sub-resource attached at construction time: ```ts client.ai.models.schema.get({ account_id, model: '@cf/meta/llama-3-8b-instruct' }); ``` Source: [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts) Source: [src/resources/ai/models/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/index.ts) ### Request Anatomy Every list/get/create/update/delete method follows a consistent parameter convention: | Parameter kind | Example | Description | | --- | --- | --- | | Path param | `account_id` | URL path segment, required for almost all account-scoped endpoints | | Query param | `page`, `per_page`, `search` | Optional filters, forwarded as a query string | | Body param | arbitrary typed object | JSON payload for `POST`/`PUT`/`PATCH` | For instance, `SchemaGetParams` requires an `account_id` path param and accepts a `model` query param: ```ts export interface SchemaGetParams { account_id: string; // path model: string; // query } ``` Source: [src/resources/ai/models/schema.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/schema.ts) ## Common Usage Patterns ### Paginated Listing List endpoints return a `Core.PagePromise<...>` whose shape matches the pagination style advertised by the API. The SDK ships helpers such as `V4PagePagination` and `V4PagePaginationArray`, used like this: ```ts import { V4PagePagination } from 'cloudflare'; export class DeviceListResponsesV4PagePagination extends V4PagePagination {} ``` This is what enables the `for await (...)` loop above. `models.list` uses the array variant because Workers AI returns a flat array of models: ```ts export class ModelListResponsesV4PagePaginationArray extends V4PagePaginationArray {} ``` Source: [src/resources/zero-trust/dex/commands/devices.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts) Source: [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts) ### File Uploads The README is explicit that file-upload parameters accept several interchangeable forms: a web `File`, a `fetch` `Response`, an `fs.ReadStream`, or the value returned by the `toFile` helper. The pattern is: ```ts import fs from 'fs'; import Cloudflare, { toFile } from 'cloudflare'; const client = new Cloudflare(); await client.kv.namespaces.values.update( '0f2ac74b498b48028cb68387c421e279', 'My-Key', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', value: fs.createReadStream('/path/to/file'), }, ); ``` Source: [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md) This polymorphism is important: pick the form that best matches your runtime (Node `fs`, web `File`, or a streamed `Response`). ## Common Pitfalls and Community Notes A few recurring problems reported by the community are worth flagging up front because they affect the very first request a new user makes: - **Breaking changes across major versions.** v5.0.0 and v6.0.0 each shipped breaking changes, and the published changelogs were widely criticized as hard to use ([#2673](https://github.com/cloudflare/cloudflare-typescript/issues/2673)). Read [the v6.0.0 release notes](https://github.com/cloudflare/cloudflare-typescript/releases/tag/v6.0.0) before upgrading from a v5.x line. - **Deprecation warnings on Node 21+.** Older versions pulled in `node-fetch`, which transitively depends on the deprecated `punycode` module ([#2267](https://github.com/cloudflare/cloudflare-typescript/issues/2267)). Track [#2553](https://github.com/cloudflare/cloudflare-typescript/issues/2553) for the migration to native `fetch`. - **Transitive dependency deprecations.** The `formdata-node` → `node-domexception@1.0.0` chain produces npm deprecation warnings ([#2660](https://github.com/cloudflare/cloudflare-typescript/issues/2660)). - **Type-narrowing regressions.** The KV metadata type was tightened from `unknown` to `Record` in 3.3.0, breaking code that stored non-object JSON ([#1238](https://github.com/cloudflare/cloudflare-typescript/issues/1238)). - **Incorrect return types for paginated responses.** The return type of `client.pages.projects.list` has been reported as still incorrect even after fixes ([#2757](https://github.com/cloudflare/cloudflare-typescript/issues/2757)). Always cross-check page-promise generic parameters when the inferred element type looks wrong. ## See Also - [CHANGELOG.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/CHANGELOG.md) — historical change log - [Releases](https://github.com/cloudflare/cloudflare-typescript/releases) — version-by-version notes, including the [v6.0.0](https://github.com/cloudflare/cloudflare-typescript/releases/tag/v6.0.0) breaking-change summary - [Zero Trust DEX Commands](https://github.com/cloudflare/cloudflare-typescript/tree/main/src/resources/zero-trust/dex/commands) — example resource tree - [AI Models](https://github.com/cloudflare/cloudflare-typescript/tree/main/src/resources/ai/models) — example resource tree with sub-resource attachment - [Upcoming major version upgrade, #2553](https://github.com/cloudflare/cloudflare-typescript/issues/2553) — tracks the move off `node-fetch` --- ## SDK Architecture, Shims, and Runtime Compatibility ### Related Pages Related topics: [Installation and Basic Usage](#page-1), [Request Patterns, Errors, Retries, and Pagination](#page-3)
Related Source Files The following source files were used to generate this page: - [src/core.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/core.ts) - [src/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/index.ts) - [src/resource.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resource.ts) - [src/pagination.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/pagination.ts) - [src/_shims/README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/_shims/README.md) - [src/_shims/index.d.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/_shims/index.d.ts) - [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts) - [src/resources/ai/models/schema.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/schema.ts) - [src/resources/zero-trust/dex/commands/devices.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts) - [src/resources/zero-trust/dex/commands/downloads.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/downloads.ts) - [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md) - [src/resources/zero-trust/dlp/profiles/custom.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/custom.ts) - [src/resources/zero-trust/dlp/profiles/predefined.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/predefined.ts)
# SDK Architecture, Shims, and Runtime Compatibility ## Overview The `cloudflare-typescript` SDK is a generated client library that exposes the Cloudflare HTTP API as a hierarchical tree of TypeScript resource classes. Every resource module in `src/resources/**` is produced from the OpenAPI specification by the Stainless code generator, as indicated by the file header comment — "File generated from our OpenAPI spec by Stainless" — found in [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts), [src/resources/ai/models/schema.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/schema.ts), and every other resource file in the tree. Because the SDK targets multiple JavaScript runtimes (Node.js 18+, Cloudflare Workers, browsers, and edge runtimes), it relies on a small set of internal abstractions — `core`, `resource`, `pagination`, and a `_shims` layer — to insulate generated code from runtime-specific APIs. Understanding these layers is essential for contributing to the SDK, debugging transport issues, or extending it with custom fetch/retry behavior. ## Core Architecture ### The `Core` Module Every generated resource file imports a `Core` namespace, for example `import * as Core from '../../../core'` in [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts). The `Core` module (declared in [src/core.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/core.ts)) exposes the shared request, response, and pagination primitives that resource methods depend on, including: - `APIPromise` — the promise type returned by every endpoint method. - `PagePromise` — a lazily-evaluated async iterable for paginated list endpoints. - `RequestOptions` — the optional second argument that lets callers override `maxRetries`, `timeout`, `headers`, `signal`, and so on. Resource classes never call `fetch` directly. Instead, they invoke transport methods on a private `_client` (inherited from `APIResource`) such as `_client.get`, `_client.put`, and the higher-level helper `_client.getAPIList(...)` that wires pagination classes into a `PagePromise`. See [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts), where `Models.list` calls `this._client.getAPIList('/accounts/${account_id}/ai/models/search', ModelListResponsesV4PagePaginationArray, ...)` to drive the search endpoint. ### The `APIResource` Base Class All resource classes extend `APIResource` from [src/resource.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resource.ts). Sub-resources are composed by parent classes — for example, `Models` owns a `Schema` sub-resource instantiated in its constructor as `schema: SchemaAPI.Schema = new SchemaAPI.Schema(this._client)` in [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts). This composition yields the familiar `client.ai.models.list(...)` and `client.ai.models.schema.get(...)` access patterns without code duplication. ### Pagination Classes Paginated endpoints declare a dedicated pagination class extending either `V4PagePagination`, `V4PagePaginationArray`, or `SinglePage`, all defined in [src/pagination.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/pagination.ts). These classes encapsulate the per-API shape of pagination metadata (page numbers, cursors, single-page responses) and feed it to `getAPIList`. Examples include: | Pagination class | Source | | --- | --- | | `ModelListResponsesV4PagePaginationArray` | [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts) | | `DeviceListResponsesV4PagePagination` | [src/resources/zero-trust/dex/commands/devices.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts) | | `ProfilesSinglePage extends SinglePage` | [src/resources/zero-trust/dlp/profiles/custom.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/custom.ts) | The choice of `V4PagePagination` versus `V4PagePaginationArray` mirrors the underlying Cloudflare v4 API conventions (page/result envelopes vs. flat result arrays), and the `PagePromise` it returns can be iterated directly with `for await`. ```ts // Source: src/resources/zero-trust/dex/commands/devices.ts for await (const deviceListResponse of client.zeroTrust.dex.commands.devices.list( { account_id: '01a7362d577a6c3019a474fd6f485823', page: 1, per_page: 1 }, )) { // ... } ``` ## The `_shims` Layer and Runtime Compatibility The `_shims` directory is the SDK's runtime-compatibility surface. It re-exports a small set of web-standard types — most importantly `Response`, `Request`, `Headers`, `Blob`, and `File` — using the implementation that matches the active runtime. Generated resource code imports these types from `_shims` rather than from the global namespace, which keeps the SDK portable across Node, Workers, and the browser. A concrete example is in [src/resources/zero-trust/dex/commands/downloads.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/downloads.ts), where the `Downloads.get` method declares its return type as `Core.APIPromise` by importing `{ type Response }` from `'../../../../_shims/index'`. Because binary artifact downloads (DEX command outputs) are returned as `application/zip`, the request opts into binary transport with the `__binaryResponse: true` flag and an explicit `Accept: application/zip` header: ```ts // Source: src/resources/zero-trust/dex/commands/downloads.ts return this._client.get( `/accounts/${account_id}/dex/commands/${commandId}/downloads/${filename}`, { ...options, headers: { Accept: 'application/zip', ...options?.headers }, __binaryResponse: true }, ); ``` The `_shims` index documented in [src/_shims/index.d.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/_shims/index.d.ts) provides a uniform shape, and [src/_shims/README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/_shims/README.md) describes how the build selects the right implementation per target. File uploads follow the same pattern: the README documents `toFile`, the `fetch` `Response` conversion path, and the web `File` API, as shown in the [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md) "File uploads" section. ### Why a Shim Layer Exists Community issue [#2267](https://github.com/cloudflare/cloudflare-typescript/issues/2267) ("Punycode deprecation error in Node 21 and later") and the tracking issue [#2553](https://github.com/cloudflare/cloudflare-typescript/issues/2553) ("Upcoming major version upgrade") both stem from the SDK's previous reliance on `node-fetch`. Native `fetch` shipped in Node 18, which is the SDK's oldest supported version, so the v6.x line removes `node-fetch` in favor of native runtime fetch. The `_shims` layer is what makes that transition safe: code generated by Stainless still references the shim path, but the shim now resolves to the host's built-in `fetch`, `Response`, and `FormData` instead of polyfills. A second symptom of the same surface is issue [#2660](https://github.com/cloudflare/cloudflare-typescript/issues/2660), which reports that the SDK pulls in a deprecated transitive package (`node-domexception@1.0.0 via formdata-node`). Because that polyfill is only required on legacy runtimes, dropping it is part of the v6 cleanup tracked in [#2553](https://github.com/cloudflare/cloudflare-typescript/issues/2553). Together, these issues illustrate why the shim layer exists: it lets the generated surface stay stable while the underlying runtime polyfills are swapped out. ## Resource Tree Composition The SDK is structured as a directory tree that mirrors the API surface. Each directory contains an `index.ts` that re-exports its sub-resources and the shared types they return, so consumers can import everything they need from a single module path. For example, [src/resources/zero-trust/dlp/profiles/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/index.ts) re-exports `Custom`, `Predefined`, and `Profiles`, plus all of the `*Params` and response types they need; the public `Cloudflare` namespace in [src/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/index.ts) is what ties the top-level client (`client.zeroTrust.dlp.profiles`) to this layout. The same `Profile` namespace is also defined in [src/resources/zero-trust/dlp/profiles/custom.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/custom.ts) and reused in [src/resources/zero-trust/dlp/profiles/predefined.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/predefined.ts) via `import * as CustomAPI from './custom'`. The discriminated union `Profile = Profile.CustomProfile | Profile.PredefinedProfile | Profile.IntegrationProfile` is declared in the same file and exported upward, so consumers can pattern-match on the `type` discriminator to handle each DLP profile shape. ## Common Pitfalls and Best Practices - **Never import from `node-fetch` or `formdata-node` directly in your application code** — use the shim-re-exported `Response`, `Request`, `FormData`, and the helper `toFile` documented in [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md). Mixing polyfills is the most common cause of `punycode` deprecation warnings and runtime-only failures on Cloudflare Workers. - **Prefer `for await` over `.next()` for paginated responses.** The `PagePromise` returned by methods such as `client.ai.models.list` (see [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts)) auto-fetches subsequent pages only when iterated, so calling `.next()` once and dropping the iterator will silently truncate results. - **Use `RequestOptions` for per-call overrides** rather than mutating the global client. This keeps retries, timeouts, and abort signals scoped to the request that actually needs them, which matters for long-running Workers invocations. - **Type-narrow discriminated unions explicitly.** A profile of `type: 'predefined'` is not assignable to a `CustomProfile` even if you only read common fields; explicitly check the discriminator and switch on it, as the DLP profile unions in [src/resources/zero-trust/dlp/profiles/custom.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/custom.ts) require. ## See Also - [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md) — installation, configuration, and the file-upload guide. - [src/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/index.ts) — public `Cloudflare` namespace and `ClientOptions`. - [src/pagination.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/pagination.ts) — `PagePromise`, `V4PagePagination`, `V4PagePaginationArray`, and `SinglePage`. - [src/_shims/README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/_shims/README.md) — runtime shim selection per build target. - Issue [#2267](https://github.com/cloudflare/cloudflare-typescript/issues/2267) — `punycode` deprecation context. - Issue [#2553](https://github.com/cloudflare/cloudflare-typescript/issues/2553) — v6 major upgrade tracking the move off `node-fetch`. --- ## Request Patterns, Errors, Retries, and Pagination ### Related Pages Related topics: [Installation and Basic Usage](#page-1), [API Resources, Releases, and Known Issues](#page-4)
Related Source Files The following source files were used to generate this page: - [src/core.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/core.ts) - [src/error.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/error.ts) - [src/pagination.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/pagination.ts) - [src/internal/utils/query.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/internal/utils/query.ts) - [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md) - [src/resources/zero-trust/dex/commands/devices.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts) - [src/resources/zero-trust/dex/commands/commands.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/commands.ts) - [src/resources/zero-trust/dlp/profiles/profiles.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/profiles.ts) - [src/resources/zero-trust/dlp/profiles/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/index.ts) - [src/resources/ai/models/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/index.ts) - [package.json](https://github.com/cloudflare/cloudflare-typescript/blob/main/package.json) - [src/internal/qs/README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/internal/qs/README.md)
# Request Patterns, Errors, Retries, and Pagination The Cloudflare TypeScript SDK exposes a uniform surface for issuing HTTP requests to the Cloudflare API. Every generated resource method funnels through a small set of primitives defined in `src/core.ts` (request lifecycle, retries, error mapping) and `src/pagination.ts` (page-iteration abstractions). Understanding these primitives is essential for predicting SDK behavior, handling failures, and iterating over large result sets. ## Request Patterns ### Method and Path Construction Each resource method splits its parameters into path and query components. The pattern is visible in `src/resources/zero-trust/dex/commands/devices.ts`, where `account_id` is destructured from `params` and the rest is forwarded as `query`: ```ts list( params: DeviceListParams, options?: Core.RequestOptions, ): Core.PagePromise { const { account_id, ...query } = params; return this._client.getAPIList( `/accounts/${account_id}/dex/commands/devices`, DeviceListResponsesV4PagePagination, { query, ...options }, ); } ``` This separation is consistent across the SDK — path params are interpolated into the URL template, and remaining params are passed via the `query` option to `getAPIList` / `getAPI` / `post` / `put` / `patch` / `delete` (defined in `src/core.ts`). Query serialization uses a vendored `qs`-compatible library documented in `src/internal/qs/README.md`, which is "a TypeScript rewrite of `qs`, a query string library". ### File Uploads Endpoints that accept files accept multiple input shapes, as documented in `README.md`: ```ts await client.kv.namespaces.values.update('0f2ac74b498b48028cb68387c421e279', 'My-Key', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', value: fs.createReadStream('/path/to/file'), }); ``` Accepted forms include `File`, a `fetch` `Response`, an `fs.ReadStream`, or the return value of the `toFile` helper. The same multipart handling code path underlies all such methods. ### Runtime / Environment Selection `package.json` declares conditional `exports` keyed by runtime: `deno`, `bun`, `browser`, `worker`, `workerd`, and a Node default. The `sideEffects` array points to `_shims/index.{js,mjs}` and `shims/{node,web}.{js,mjs}`, which provide the polyfills (Web Streams, FormData, file-from utilities) needed for that runtime. Selecting a runtime is therefore a build-time, not API-level, concern. ## Pagination The SDK exposes two pagination shapes generated per endpoint: `SinglePage` (for endpoints that return a flat array) and `V4PagePagination` (for endpoints using the Cloudflare v4 `page` / `per_page` convention). `src/resources/zero-trust/dlp/profiles/profiles.ts` shows the single-page flavor: ```ts export class ProfilesSinglePage extends SinglePage {} ``` `src/resources/zero-trust/dex/commands/devices.ts` shows the v4 cursor style, backed by `V4PagePaginationParams`: ```ts export interface DeviceListParams extends V4PagePaginationParams { account_id: string; search?: string; } ``` Methods return `Core.PagePromise`, which is `await`-able for a single page **or** usable as an async iterator. The README example demonstrates auto-paginated iteration: ```ts for await (const device of client.zeroTrust.dex.commands.devices.list({ account_id, page: 1, per_page: 1 })) { // ... } ``` | Pagination class | Used when | Source | | --- | --- | --- | | `SinglePage` | Response is a flat array, no cursor | `src/pagination.ts`, used in `src/resources/zero-trust/dlp/profiles/profiles.ts` | | `V4PagePagination` | Endpoint accepts `page` / `per_page` | `src/pagination.ts`, used in `src/resources/zero-trust/dex/commands/devices.ts` | Endpoints such as `pages.projects.list` have produced a longstanding typing bug — community issue #2757 notes that the return type is "still wrong" and remains `PagePromise<...DeploymentsSinglePage, ...>`. When the inferred pagination class is wrong, manually awaiting a single page versus iterating may diverge; treat the return type as the source of truth for iteration shape. ## Errors and Retries `src/error.ts` defines the error hierarchy. All thrown errors extend `CloudflareError`, and HTTP responses with non-2xx status are mapped to typed subclasses (for example, `APIError`, `NotFoundError`, `RateLimitError`) carrying `status`, `headers`, and a parsed `error` body. Methods called via `getAPI` / `getAPIList` raise automatically; callers should wrap calls in `try/catch` and branch on the typed error. Retry behavior is configured per-request through `Core.RequestOptions`: - `maxRetries: number` — maximum retry attempts for transient errors (network failures, 5xx, 429). - `timeout: number` — request timeout in milliseconds. - `headers`, `signal`, `idempotencyKey` — standard fetch-style options. These options are accepted by every generated method because the implementations forward `options` directly to `_client.getAPIList` / `_client.getAPI` (see `src/resources/zero-trust/dex/commands/devices.ts`). A common pattern is to set defaults at client construction and override per call. ## Common Failure Modes and Community Notes 1. **Inferring the wrong page type** — As raised in #2757, generated return types occasionally do not match the actual Cloudflare response, leading to runtime mismatches between `for await` and `await` usage. 2. **Deprecated transitive dependencies** — Issue #2660 flags `node-domexception@1.0.0` via `formdata-node`; issue #2267 flags the `punycode` deprecation under Node 21+ through `node-fetch`. The major version upgrade discussed in #2553 targets removal of `node-fetch` in favor of native fetch. 3. **Type narrowing on user data** — Issue #1238 shows how SDK-side typing can be too strict (e.g., `Key['metadata']` as `Record` rather than `unknown`). When casting fails, prefer widening with a local interface or `as unknown as ...` rather than awaiting the SDK to change. For the broader client configuration surface (auth tokens, base URL overrides, custom fetch), see the `Cloudflare` class constructor in `src/client.ts` and the `README.md` "Configuration" section. ## See Also - [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md) — installation, configuration, file uploads. - [api.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/api.md) — full generated resource index. - [src/core.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/core.ts) — request options, error mapping internals. - [src/pagination.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/pagination.ts) — `SinglePage` and `V4PagePagination` definitions. --- ## API Resources, Releases, and Known Issues ### Related Pages Related topics: [Installation and Basic Usage](#page-1), [SDK Architecture, Shims, and Runtime Compatibility](#page-2), [Request Patterns, Errors, Retries, and Pagination](#page-3)
Related Source Files The following source files were used to generate this page: - [src/resources/ai/models/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/index.ts) - [src/resources/ai/models/models.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/models.ts) - [src/resources/ai/models/schema.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/ai/models/schema.ts) - [src/resources/zero-trust/dlp/profiles/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/index.ts) - [src/resources/zero-trust/dlp/profiles/profiles.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/profiles.ts) - [src/resources/zero-trust/dlp/profiles/custom.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/custom.ts) - [src/resources/zero-trust/dlp/profiles/predefined.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dlp/profiles/predefined.ts) - [src/resources/zero-trust/dex/commands/index.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/index.ts) - [src/resources/zero-trust/dex/commands/devices.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/devices.ts) - [src/resources/zero-trust/dex/commands/downloads.ts](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/resources/zero-trust/dex/commands/downloads.ts) - [README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/README.md) - [src/internal/qs/README.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/src/internal/qs/README.md) - [CHANGELOG.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/CHANGELOG.md) - [api.md](https://github.com/cloudflare/cloudflare-typescript/blob/main/api.md)
# API Resources, Releases, and Known Issues The `cloudflare-typescript` repository is the official TypeScript SDK for the Cloudflare API. It is a code-generated client produced by Stainless from the Cloudflare OpenAPI specification (`Source: [README.md:1-1]()`). The library exposes the entire Cloudflare control-plane surface — DNS, Workers, R2, KV, DLP, Zero Trust, Realtime, AI, and dozens of other product areas — through a deeply nested tree of typed `APIResource` classes. This page documents how those resources are organized, summarizes the recent release cadence, and consolidates the known issues most frequently raised by the community. ## API Resource Architecture ### Resource Tree and Code Generation Every Cloudflare product area is modeled as a directory under `src/resources/`. Each directory follows the same pattern: a top-level `index.ts` re-exports sub-resources, parameter types, and response types, and each sub-resource is implemented as its own `*.ts` file containing a class that extends `APIResource`. The Workers AI models area is a representative example. The entry point re-exports the paginated list class, the model type, and the `Schema` sub-resource: ```ts // Source: src/resources/ai/models/index.ts:1-7 export { ModelListResponsesV4PagePaginationArray, Models, type ModelListResponse, type ModelListParams, } from './models'; export { Schema, type SchemaGetResponse, type SchemaGetParams } from './schema'; ``` `Models` owns a nested `Schema` instance and exposes a `list()` method that returns a `PagePromise` (`Source: [src/resources/ai/models/models.ts:1-17]()`). The model list response type is currently surfaced as `unknown` because the OpenAPI schema is open-ended (`Source: [src/resources/ai/models/models.ts:1-17]()`), and the `Schema.get()` call unwraps the API envelope's `result` field to return a strongly typed `SchemaGetResponse` (`Source: [src/resources/ai/models/schema.ts:1-30]()`). ### Zero Trust Resources The Zero Trust sub-tree illustrates how complex products are broken into many sub-resources. The DLP profile area combines three siblings — `Custom`, `Predefined`, and `Profiles` — re-exported from a single barrel file: ```ts // Source: src/resources/zero-trust/dlp/profiles/index.ts:1-25 export { Custom, type CustomProfile, /* ... */ } from './custom'; export { Predefined, type PredefinedProfile, /* ... */ } from './predefined'; export { ProfilesSinglePage, Profiles, /* ... */ } from './profiles'; ``` The `Profile` type itself is a discriminated union of `CustomProfile | PredefinedProfile | IntegrationProfile`, and entries inside a profile are themselves unions of `CustomEntry`, `CustomPromptTopicEntry`, `PredefinedEntry`, `IntegrationEntry`, `ExactDataEntry`, `DocumentFingerprintEntry`, and `WordListEntry` (`Source: [src/resources/zero-trust/dlp/profiles/profiles.ts:1-50]()`). Several fields — including `enabled` on custom entries and the `ContextAwareness` block — are explicitly marked `@deprecated` (`Source: [src/resources/zero-trust/dlp/profiles/profiles.ts:1-50]()`). The DEX (Digital Experience Monitoring) area is organized similarly. Commands are dispatched via the `commands` resource, which re-exports four sub-resources: `Commands`, `Devices`, `Downloads`, and `Quota` (`Source: [src/resources/zero-trust/dex/commands/index.ts:1-17]()`). The `Devices.list()` method paginates with a `V4PagePagination` cursor and yields eligible WARP devices (`Source: [src/resources/zero-trust/dex/commands/devices.ts:1-25]()`), while `Downloads.get()` returns a binary `Response` by setting `Accept: application/zip` and the `__binaryResponse: true` flag (`Source: [src/resources/zero-trust/dex/commands/downloads.ts:1-30]()`). ### Resource Topology Diagram ```mermaid graph TD Client[Cloudflare Client] AI[ai] ZT[zeroTrust] DLP[dlp] Profiles[profiles] Custom[custom] Predefined[predefined] DEX[dex] Commands[commands] CmdList[Commands / Devices / Downloads / Quota] Models[models] Schema[schema] Client --> AI Client --> ZT AI --> Models Models --> Schema ZT --> DLP DLP --> Profiles Profiles --> Custom Profiles --> Predefined ZT --> DEX DEX --> Commands Commands --> CmdList ``` ## Release History and Cadence The SDK moves through a regular cadence. v5.x shipped in late 2025 and v6.0.0 was released on 2026-04-30 as a major version, with the total API surface growing from roughly 96 resource sections to a much larger count. v6.0.0 introduced 11 new top-level resources and added sub-resources/methods across 50+ existing resources. Two beta milestones preceded it: v6.0.0-beta.1 (2026-01-20) and v6.0.0-beta.2 (2026-04-15). Weekly minor releases follow the v6.0.0 line: | Version | Date | Highlight | |---------|------|-----------| | v6.0.0 | 2026-04-30 | Major version, 11 new top-level resources | | v6.1.0 | 2026-05-04 | New `securityCenter.insights` sub-resources (AuditLogs, etc.) | | v6.2.0 | 2026-05-14 | New `api` DDoS Protection resource with Advanced TCP Protection | | v6.3.0 | 2026-05-21 | New `dls` Data Localization Suite resource | The published release calendar in `cloudflare-typescript` issue #2755 plans further weekly drops through June 2026 (v6.4.0, v6.5.0, v6.6.0). The cadence is deliberate: smaller, more frequent releases lower the blast radius of any breaking change and keep the generated surface aligned with the upstream OpenAPI document. ## Known Issues and Community Concerns Several recurring issues affect users of the library. They fall into three buckets. ### Type-Correctness Bugs - `client.pages.projects.list` still returns `PagePromise` instead of the expected page type, so iteration yields the wrong shape (issue #2757). - `Key['metadata']` and `MetadataGetResponse` in the KV namespace are typed as `Record` even though the API accepts any valid JSON string; the narrower type rejects valid inputs (issue #1238). - The `Models.list()` response is typed as `unknown` because the upstream schema is open-ended (`Source: [src/resources/ai/models/models.ts:1-17]()`); callers must cast the result. - A missing RealtimeKit "Add Participant" endpoint was reported in issue #2737. ### Breaking Changes and Changelog Quality The v5.0.0 changelog was published retroactively and was described as "essentially unusable" by users who needed to understand which methods had changed (issue #2673). The v6.0.0 release notes acknowledged similar friction and are now generated directly from the OpenAPI diff, but historical releases between v3 and v5 lack a per-method migration guide (issue #1176). ### Runtime and Dependency Issues - The library depends on `node-fetch`, which pulls in a deprecated `punycode` polyfill. Node 21+ emits a deprecation warning on every import even though the SDK claims to support Node 18+, which has native `fetch` (issue #2267). This is the driver for the planned major version bump tracked in issue #2553, which removes the `node-fetch` dependency. - The SDK also pulls in `formdata-node`, which transitively depends on the deprecated `node-domexception@1.0.0` (issue #2660). Until the v6+ migration lands, the vendored query-string library (`neoqs`) is still required for serialization (`Source: [src/internal/qs/README.md:1-3]()`). ### Workarounds - Pin to the last v5.x minor (`5.2.0`) if you cannot tolerate weekly breaking changes. - For paginated `unknown` responses, wrap the result in a runtime validator (e.g., Zod) before accessing fields. - For KV metadata, cast to `string` or `Record` explicitly to match your write path. ## See Also - `src/resources/` — full resource tree - `api.md` — generated reference for every method, parameter, and response - `CHANGELOG.md` — full per-release notes - `README.md` — installation, configuration, and file-upload examples --- --- ## Pitfall Log Project: cloudflare/cloudflare-typescript Summary: Found 12 structured pitfall item(s), including 4 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Evidence: community_evidence:github | cevd_fd79754a428c425783f16ba5439e69bf | https://github.com/cloudflare/cloudflare-typescript/issues/2757 ## 2. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Evidence: community_evidence:github | cevd_e1faaf55476548078001738e87c00975 | https://github.com/cloudflare/cloudflare-typescript/issues/2553 ## 3. Maintenance risk - Maintenance risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Evidence: community_evidence:github | cevd_2ac3a8bda7d84bf4addc54959229466b | https://github.com/cloudflare/cloudflare-typescript/issues/2755 ## 4. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Evidence: community_evidence:github | cevd_988272604e4b47dfa6ac077e17e870c7 | https://github.com/cloudflare/cloudflare-typescript/issues/2737 ## 5. Identity risk - Identity risk requires verification - Severity: medium - Evidence strength: runtime_trace - Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Repro command: `npm install cloudflare` - Evidence: identity.distribution | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare ## 6. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Evidence: capability.assumptions | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare ## 7. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Evidence: packet_text.keyword_scan | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare ## 8. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Evidence: evidence.maintainer_signals | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare ## 9. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Evidence: downstream_validation.risk_items | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare ## 10. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Evidence: risks.scoring_risks | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare ## 11. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Evidence: evidence.maintainer_signals | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare ## 12. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Suggested check: Reproduce the official install and quickstart path in an isolated environment. - Evidence: evidence.maintainer_signals | npm_package:cloudflare | https://www.npmjs.com/package/cloudflare