Git Product home page Git Product logo

cloudflare-client's Introduction

Cloudflare API Client

NPM Version NPM Downloads TypeScript Donate Discord

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: "[email protected]",
//   ...
// }

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:

Backers 💰

              

Related Projects

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.

cloudflare-client's People

Contributors

koistya avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.