Cloudflare TypeScript API Library

Cloudflare API list methods are paginated. You have two ways to handle this:

1. Auto-pagination: Use the for await ... of syntax to automatically fetch all pages as you iterate.
2. Manual pagination: Request a single page and use .hasNextPage() and .getNextPage() to navigate manually.

// Option 1: Auto-pagination
async function fetchAllAccounts(params) {
  const allAccounts = [];
  for await (const account of client.accounts.list()) {
    allAccounts.push(account);
  }
  return allAccounts;
}

// Option 2: Manual pagination
let page = await client.accounts.list();
for (const account of page.result) {
  console.log(account);
}

while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

The library now uses the built-in Web fetch API across all platforms. If your code relies on node-fetch-specific properties, you must update it to use standardized Web alternatives:

1. Response Bodies: The body property is now a Web ReadableStream instead of a Node.js Readable. To use Node.js stream methods like .pipe(), wrap the body using Readable.fromWeb() from the node:stream module.
2. Error Headers: The headers property on APIError objects is now an instance of the Web Headers class. It is no longer a plain Record<string, string | null | undefined>.

// Before:
const res = await client.example.retrieve('string/with/slash').asResponse();
res.body.pipe(process.stdout);

// After:
import { Readable } from 'node:stream';
const res = await client.example.retrieve('string/with/slash').asResponse();
Readable.fromWeb(res.body).pipe(process.stdout);

The fileFromPath helper has been removed. For file uploads, use native Node.js streams or runtime-specific file APIs (like Bun.file for Bun).

// Before
Cloudflare.fileFromPath('path/to/file');

// After
import fs from 'fs';
fs.createReadStream('path/to/file');

Install the library directly from the GitLab repository using npm. Note that once published to npm, you will be able to use npm install cloudflare.

npm install git+ssh://git@gitlab.cfdata.org:cloudflare/sdks/cloudflare-typescript.git

Ensure your development environment meets the following minimum version requirements to use the latest SDK:

• Node.js: 20 LTS
• TypeScript: 4.9
• Jest: 28

When calling methods that do not require a body, query, or header parameters, you can no longer pass the options object as the first argument. You must now explicitly provide null, undefined, or an empty object {} as the first argument to reach the options argument.

Example transition:

- client.example.list({ headers: { ... } });
+ client.example.list({}, { headers: { ... } });
+ client.example.list(null, { headers: { ... } });
+ client.example.list(undefined, { headers: { ... } });

client.example.list();
client.example.list({}, { headers: { ... } });
client.example.list(null, { headers: { ... } });
client.example.list(undefined, { headers: { ... } });
- client.example.list({ headers: { ... } });
+ client.example.list({}, { headers: { ... } });

The library has been refactored to separate internal and public code. Many modules previously available at the top level have been moved to a core directory. Update your import paths as follows:

// Before
import 'cloudflare/error';
import 'cloudflare/pagination';
import 'cloudflare/resource';
import 'cloudflare/uploads';

// After
import 'cloudflare/core/error';
import 'cloudflare/core/pagination';
import 'cloudflare/core/resource';
import 'cloudflare/core/uploads';

The httpAgent option has been removed because it relied on node:http agents, which are incompatible with the built-in fetch implementation used by modern runtimes. To configure proxies or custom fetch behavior, use the fetchOptions property. If you are in a Node.js environment, use undici.ProxyAgent to provide a dispatcher within fetchOptions.

import Cloudflare from 'cloudflare';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent(process.env.PROXY_URL);
const client = new Cloudflare({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});