Comprehensive coverage of the Cloudflare API including zones, DNS records, and Workers
Class-based design with intuitive methods for all Cloudflare operations
Strong TypeScript typing for excellent IDE autocompletion and type safety
Fully integrated with the official Cloudflare client using modern async iterators
Convenience methods for common operations to reduce boilerplate code
Promise-based API for easy async/await usage
ESM compatible for modern JavaScript projects
Comprehensive error handling for robust applications

Installation

# Using npm
npm install @apiclient.xyz/cloudflare

# Using yarn
yarn add @apiclient.xyz/cloudflare

# Using pnpm
pnpm add @apiclient.xyz/cloudflare

Quick Start

import * as cflare from '@apiclient.xyz/cloudflare';

// Initialize with your API token
const cfAccount = new cflare.CloudflareAccount('your-cloudflare-api-token');

// Use convenience methods for quick operations
await cfAccount.convenience.createRecord('subdomain.example.com', 'A', '192.0.2.1', 3600);

// Or work with the powerful class-based API
const zone = await cfAccount.zoneManager.getZoneByName('example.com');
await zone.purgeCache();

Usage Guide

Account Management

Initialize your Cloudflare account with your API token:

import * as cflare from '@apiclient.xyz/cloudflare';

const cfAccount = new cflare.CloudflareAccount('your-cloudflare-api-token');

// If you have multiple accounts, you can preselect one
await cfAccount.preselectAccountByName('My Company Account');

// List all accounts you have access to
const myAccounts = await cfAccount.listAccounts();

Zone Management

Zones represent your domains in Cloudflare.

// Get all zones in your account
const allZones = await cfAccount.convenience.listZones();

// Get a specific zone by domain name
const myZone = await cfAccount.zoneManager.getZoneByName('example.com');

// Get zone ID directly
const zoneId = await cfAccount.convenience.getZoneId('example.com');

// Create a new zone
const newZone = await cfAccount.zoneManager.createZone('newdomain.com');

// Purge cache for an entire zone
await cfAccount.convenience.purgeZone('example.com');
// Or using the zone object
await myZone.purgeCache();

// Purge specific URLs
await myZone.purgeUrls(['https://example.com/css/styles.css', 'https://example.com/js/app.js']);

// Enable/disable development mode
await myZone.enableDevelopmentMode(); // Enables dev mode for 3 hours
await myZone.disableDevelopmentMode();

// Check zone status
const isActive = await myZone.isActive();
const usingCfNameservers = await myZone.isUsingCloudflareNameservers();

DNS Record Management

Manage DNS records for your domains with ease.

// List all DNS records for a domain
const allRecords = await cfAccount.convenience.listRecords('example.com');

// Create a new DNS record
await cfAccount.convenience.createRecord('api.example.com', 'A', '192.0.2.1', 3600);

// Create a CNAME record
await cfAccount.convenience.createRecord('www.example.com', 'CNAME', 'example.com', 3600);

// Get a specific DNS record
const record = await cfAccount.convenience.getRecord('api.example.com', 'A');

// Update a DNS record (automatically creates it if it doesn't exist)
await cfAccount.convenience.updateRecord('api.example.com', 'A', '192.0.2.2', 3600);

// Remove a specific DNS record
await cfAccount.convenience.removeRecord('api.example.com', 'A');

// Clean (remove) all records of a specific type
await cfAccount.convenience.cleanRecord('example.com', 'TXT');

// Support for ACME DNS challenges (for certificate issuance)
await cfAccount.convenience.acmeSetDnsChallenge({
  hostName: '_acme-challenge.example.com',
  challenge: 'token-validation-string',
});
await cfAccount.convenience.acmeRemoveDnsChallenge({
  hostName: '_acme-challenge.example.com',
  challenge: 'token-validation-string',
});

Workers Management

Create and manage Cloudflare Workers with full TypeScript support.

// Create or update a worker
const workerScript = `
addEventListener('fetch', event => {
  event.respondWith(new Response('Hello from Cloudflare Workers!'))
})`;

const worker = await cfAccount.workerManager.createWorker('my-worker', workerScript);

// List all workers
const allWorkers = await cfAccount.workerManager.listWorkerScripts();

// Get an existing worker
const existingWorker = await cfAccount.workerManager.getWorker('my-worker');

// Set routes for a worker
await worker.setRoutes([
  {
    zoneName: 'example.com',
    pattern: 'https://api.example.com/*',
  },
  {
    zoneName: 'example.com',
    pattern: 'https://app.example.com/api/*',
  },
]);

// Get all routes for a worker
const routes = await worker.getRoutes();

// Update a worker's script
await worker.updateScript(`
addEventListener('fetch', event => {
  event.respondWith(new Response('Updated worker content!'))
})`);

// Delete a worker
await worker.delete();
// Or using the worker manager
await cfAccount.workerManager.deleteWorker('my-worker');

Complete Example

Here's a complete example showing how to manage multiple aspects of your Cloudflare account:

import * as cflare from '@apiclient.xyz/cloudflare';

async function manageCloudflare() {
  try {
    // Initialize with API token from environment variable
    const cfAccount = new cflare.CloudflareAccount(process.env.CLOUDFLARE_API_TOKEN);

    // Preselect account if needed
    await cfAccount.preselectAccountByName('My Company');

    // Get zone and check status
    const myZone = await cfAccount.zoneManager.getZoneByName('example.com');
    console.log(`Zone active: ${await myZone.isActive()}`);
    console.log(`Using CF nameservers: ${await myZone.isUsingCloudflareNameservers()}`);

    // Configure DNS
    await cfAccount.convenience.createRecord('api.example.com', 'A', '192.0.2.1');
    await cfAccount.convenience.createRecord('www.example.com', 'CNAME', 'example.com');

    // Create a worker and set up routes
    const workerCode = `
    addEventListener('fetch', event => {
      const url = new URL(event.request.url);
      
      if (url.pathname.startsWith('/api/')) {
        event.respondWith(new Response(JSON.stringify({ status: 'ok' }), {
          headers: { 'Content-Type': 'application/json' }
        }));
      } else {
        event.respondWith(fetch(event.request));
      }
    })`;

    const worker = await cfAccount.workerManager.createWorker('api-handler', workerCode);
    await worker.setRoutes([{ zoneName: 'example.com', pattern: 'https://api.example.com/*' }]);

    // Purge cache for specific URLs
    await myZone.purgeUrls(['https://example.com/css/styles.css']);

    console.log('Configuration completed successfully');
  } catch (error) {
    console.error('Error managing Cloudflare:', error);
  }
}

manageCloudflare();

API Documentation

CloudflareAccount

The main entry point for all Cloudflare operations.

class CloudflareAccount {
  constructor(apiToken: string);

  // Account management
  async listAccounts(): Promise<Array<ICloudflareTypes['Account']>>;
  async preselectAccountByName(accountName: string): Promise<void>;

  // Managers
  readonly zoneManager: ZoneManager;
  readonly workerManager: WorkerManager;

  // Official Cloudflare client
  readonly apiAccount: cloudflare.Cloudflare;

  // Convenience namespace with helper methods
  readonly convenience: {
    // Zone operations
    listZones(domainName?: string): Promise<CloudflareZone[]>;
    getZoneId(domainName: string): Promise<string>;
    purgeZone(domainName: string): Promise<void>;

    // DNS operations
    listRecords(domainName: string): Promise<CloudflareRecord[]>;
    getRecord(domainName: string, recordType: string): Promise<CloudflareRecord | undefined>;
    createRecord(
      domainName: string,
      recordType: string,
      content: string,
      ttl?: number,
    ): Promise<any>;
    updateRecord(
      domainName: string,
      recordType: string,
      content: string,
      ttl?: number,
    ): Promise<any>;
    removeRecord(domainName: string, recordType: string): Promise<any>;
    cleanRecord(domainName: string, recordType: string): Promise<void>;

    // ACME operations
    acmeSetDnsChallenge(dnsChallenge: IDnsChallenge): Promise<any>;
    acmeRemoveDnsChallenge(dnsChallenge: IDnsChallenge): Promise<any>;
  };
}

CloudflareZone

Represents a Cloudflare zone (domain).

class CloudflareZone {
  // Properties
  readonly id: string;
  readonly name: string;
  readonly status: string;
  readonly paused: boolean;
  readonly type: string;
  readonly nameServers: string[];

  // Methods
  async purgeCache(): Promise<any>;
  async purgeUrls(urls: string[]): Promise<any>;
  async isActive(): Promise<boolean>;
  async isUsingCloudflareNameservers(): Promise<boolean>;
  async isDevelopmentModeActive(): Promise<boolean>;
  async enableDevelopmentMode(): Promise<any>;
  async disableDevelopmentMode(): Promise<any>;
}

CloudflareRecord

Represents a DNS record.

class CloudflareRecord {
  // Properties
  readonly id: string;
  readonly type: string;
  readonly name: string;
  readonly content: string;
  readonly ttl: number;
  readonly proxied: boolean;

  // Methods
  async update(content: string, ttl?: number): Promise<any>;
  async delete(): Promise<any>;
}

CloudflareWorker

Represents a Cloudflare Worker.

class CloudflareWorker {
  // Properties
  readonly id: string;
  readonly script: string;
  readonly routes: IWorkerRoute[];

  // Methods
  async getRoutes(): Promise<IWorkerRoute[]>;
  async setRoutes(routes: Array<IWorkerRouteDefinition>): Promise<void>;
  async updateScript(scriptContent: string): Promise<CloudflareWorker>;
  async delete(): Promise<boolean>;
}

interface IWorkerRouteDefinition {
  zoneName: string;
  pattern: string;
}

Utility Functions

The library includes helpful utility functions:

// Validate a domain name
CloudflareUtils.isValidDomain('example.com'); // true

// Extract zone name from a domain
CloudflareUtils.getZoneName('subdomain.example.com'); // 'example.com'

// Validate a record type
CloudflareUtils.isValidRecordType('A'); // true

// Format URL for cache purging
CloudflareUtils.formatUrlForPurge('example.com/page'); // 'https://example.com/page'

// Format TTL value
CloudflareUtils.formatTtl(3600); // '1 hour'

What's New in 6.2.0

Improved async iterator support: Fully leverages the official Cloudflare client's async iterator pattern
Enhanced error handling: Better error detection and recovery
Simplified API: More consistent method signatures and return types
Better type safety: Improved TypeScript typing throughout the library
Detailed logging: More informative logging for easier debugging

Development & Testing

To build the project:

npm run build
# or
pnpm run build

To run tests:

npm test
# or
pnpm run test

readme.md

@apiclient.xyz/cloudflare

Features