cloudflare-client

Cloudflare API Client

Lightweight universal HTTP client for Cloudflare API based on Fetch API that works in Node.js, browser, and CF Workers environment. Optimized for a good developer experience and minimal code with zero dependencies supporting tree-shaking.

Getting Started

# Install using NPM
$ npm install cloudflare-client --save

# Install using Yarn
$ yarn add cloudflare-client

Once the library is installed, you can cherry pick and configure individual Cloudflare API endpoints that you need. If you bundle your code (e.g. with Rollup), only the selected modules will be included into the application bundle.

import * as Cloudflare from "cloudflare-client";

// EXAMPLE 1:
//   Initialize an HTTP client for managing Cloudflare DNS
//   records using API token for authentication
const dnsRecords = Cloudflare.dnsRecords({
  zoneId: "<CLOUDFLARE_ZONE_ID>",
  accessToken: "<CLOUDFLARE_API_TOKEN>",
});

// EXAMPLE 2:
//   Initialize an HTTP client for managing Cloudflare Workers
//   KV store using API key and email for authentication
const kv = Cloudflare.kv({
  accountId: "<CLOUDFLARE_ZONE_ID>",
  authKey: "<CLOUDFLARE_AUTH_KEY>",
  authEmail: "<CLOUDFLARE_AUTH_EMAIL>",
});

User

// Initialize an HTTP client for the `user` API endpoint
// using an API token for authentication
const user = Cloudflare.user({ accessToken: "xxx" });

// Fetch the currently logged in / authenticated user details
// https://api.cloudflare.com/#user-user-details
const userDetails = await user.get();
// => {
//   id: "7c5dae5552338874e5053f2534d2767a",
//   email: "[e-mail]",
//   ...
// }

User Tokens

// Initialize an HTTP client for the `userTokens` API endpoint
// using an API token for authentication
const userTokens = Cloudflare.userTokens({ accessToken: "xxx" });

// Verify the user's token
// https://api.cloudflare.com/#user-api-tokens-verify-token
const token = await userTokens.verify();
// => {
//   id: "ed17574386854bf78a67040be0a770b0",
//   status: "active"
// }

// Initialize an HTTP client for the `userTokens` API endpoint
// using an auth key and email
const userTokens = Cloudflare.userTokens({ authKey: "xxx", authEmail: "xxx" });

// Get token details
// https://api.cloudflare.com/#user-api-tokens-token-details
const token = await userTokens.get("ed17574386854bf78a67040be0a770b0");
// => {
//   id: "ed17574386854bf78a67040be0a770b0",
//   name: "My Token",
//   status: "active",
//   policies: [...],
//   ...
// }

DNS Records

// Initialize an HTTP client for managing DNS records
// within the target zone using API token for authentication
const dnsRecords = Cloudflare.dnsRecords({ zoneId: "xxx", accessToken: "xxx" });

// Find all DNS records of type "A"
const records = await dnsRecords.find({ type: "A" }).all();

// Find the first DNS record with the specified name
const record = await dnsRecords.find({ type: "A", name: "test" }).first();
// => {
//  id: "372e67954025e0ba6aaa6d586b9e0b59",
//  type: "A",
//  name: "test.example.com",
//  content: "192.0.2.1",
//  ...
// }

// Fetch the list of DNS records and iterate through the result set using `for await`
const records = await dnsRecords.find({ type: "A" });

for await (const record of records) {
  console.log(record);
}

// Get a specific DNS record by its ID
// https://api.cloudflare.com/#dns-records-for-a-zone-dns-record-details
const record = await dnsRecords.get("372e67954025e0ba6aaa6d586b9e0b59");

// Create a new DNS record
// https://api.cloudflare.com/#dns-records-for-a-zone-create-dns-record
const record = await dnsRecords.create({
  type: "A",
  name: "test.example.com",
  content: "192.0.2.1",
  proxied: true,
});

// Replace DNS record
// https://api.cloudflare.com/#dns-records-for-a-zone-update-dns-record
const record = await dnsRecords.replace("372e67954025e0ba6aaa6d586b9e0b59", {
  type: "A",
  name: "test.example.com",
  content: "192.0.2.1",
  proxied: true,
});

// Update DNS record
// https://api.cloudflare.com/#dns-records-for-a-zone-patch-dns-record
const record = await dnsRecords.update("372e67954025e0ba6aaa6d586b9e0b59", {
  proxied: false,
});

// Delete DNS record
// https://api.cloudflare.com/#dns-records-for-a-zone-delete-dns-record
await dnsRecords.delete("372e67954025e0ba6aaa6d586b9e0b59");

Workers KV

// Initialize an HTTP client for managing CF Workers KV store
const kv = Cloudflare.kv({
  accountId: "xxx",
  authKey: "xxx",
  authEmail: "xxx",
});

KV Namespaces

// Fetch the list of all KV namespaces
// https://api.cloudflare.com/#workers-kv-namespace-list-namespaces
const namespaces = await kv.find().all();

// Create a new namespace named "Example"
// https://api.cloudflare.com/#workers-kv-namespace-create-a-namespace
const ns = await kv.create("Example");
// => {
//   id: "0f2ac74b498b48028cb68387c421e279",
//   title: "Example",
//   supports_url_encoding: true
// }

// Update/rename a namespace
// https://api.cloudflare.com/#workers-kv-namespace-rename-a-namespace
await kv.update("0f2ac74b498b48028cb68387c421e279", "New Name");

// Delete a namespace
// https://api.cloudflare.com/#workers-kv-namespace-remove-a-namespace
await kv.delete("0f2ac74b498b48028cb68387c421e279");

Key-Value Pairs

// Initialize the API endpoint client for managing key-value pairs
const ns = kv.namespace("0f2ac74b498b48028cb68387c421e279");

// Fetch the list of all the keys
const keys = await ns.keys().all();

// Fetch the list of all the keys prefixed "example"
const keys = await ns.keys({ prefix: "example" }).all();

// Create or update a key-value pair in Cloudflare KV store
// using JSON encoding by default (`JSON.stringify(value)`).
await ns.set("key", { some: "value" });

// Read key-pair value from Cloudflare KV store
const value = await ns.get("key");
// => {
//  some: "name"
// }

// Delete a key-pair
await ns.delete("key");

// Save a key-value pair as plain text (as opposed to JSON-serialized)
await ns.set("όνομα", "José", { encode: false });

// Read a key-value pair as plain text
const value = await ns.get("όνομα", { decode: false });
// => "José"

Source Code

For more information and usage examples check out the source code / tests:

• user.ts (tests)
• userTokens.ts (tests)
• dnsRecords.ts (tests)
• customHostnames.ts (tests)
• kv.ts (tests)

Backers 💰

              

Related Projects

• Cloudflare Workers Starter Kit — TypeScript project template for Cloudflare Workers
• React Starter Kit — front-end template for React and Relay using Jamstack architecture
• GraphQL API and Relay Starter Kit — monorepo template, pre-configured with GraphQL API, React, and Relay

How to Contribute

You're very welcome to create a PR or send me a message on Discord.

$ git clone https://github.com/kriasoft/cloudflare-client.git
$ cd ./cloudflare-client
$ yarn install
$ yarn test

NOTE: In order to run unit tests locally you will need Node.js v16.15 or newer and Cloudflare API token.

License

Copyright © 2022-present Kriasoft. This source code is licensed under the MIT license found in the LICENSE file.

---

^{Made with ♥ by Konstantin Tarkus (@koistya, blog) and contributors.}