{"id":26291930,"url":"https://github.com/kriasoft/cloudflare-client","last_synced_at":"2025-05-08T03:27:45.012Z","repository":{"id":37770057,"uuid":"506010352","full_name":"kriasoft/cloudflare-client","owner":"kriasoft","description":"Lightweight universal Cloudflare API client library for Node.js, Browser, and CF Workers","archived":false,"fork":false,"pushed_at":"2022-07-02T11:31:47.000Z","size":2234,"stargazers_count":22,"open_issues_count":1,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-30T00:55:21.060Z","etag":null,"topics":["api","cloudflare","cloudflare-api","cloudflare-workers","dns","edge","http-client","rest-api","rest-client"],"latest_commit_sha":null,"homepage":"https://api.cloudflare.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kriasoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"kriasoft","patreon":"koistya","open_collective":"react-starter-kit"}},"created_at":"2022-06-21T21:33:54.000Z","updated_at":"2024-04-20T08:40:38.000Z","dependencies_parsed_at":"2022-08-18T22:31:27.132Z","dependency_job_id":null,"html_url":"https://github.com/kriasoft/cloudflare-client","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fcloudflare-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fcloudflare-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fcloudflare-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fcloudflare-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kriasoft","download_url":"https://codeload.github.com/kriasoft/cloudflare-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243668231,"owners_count":20328042,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cloudflare","cloudflare-api","cloudflare-workers","dns","edge","http-client","rest-api","rest-client"],"created_at":"2025-03-15T01:17:55.271Z","updated_at":"2025-03-15T01:17:55.766Z","avatar_url":"https://github.com/kriasoft.png","language":"TypeScript","readme":"# Cloudflare API Client\n\n[![NPM Version](https://img.shields.io/npm/v/cloudflare-client?style=flat-square)](https://www.npmjs.com/package/cloudflare-client)\n[![NPM Downloads](https://img.shields.io/npm/dm/cloudflare-client?style=flat-square)](https://www.npmjs.com/package/cloudflare-client)\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg?style=flat-square)](http://www.typescriptlang.org/)\n[![Donate](https://img.shields.io/badge/dynamic/json?color=%23ff424d\u0026label=Patreon\u0026style=flat-square\u0026query=data.attributes.patron_count\u0026suffix=%20patrons\u0026url=https%3A%2F%2Fwww.patreon.com%2Fapi%2Fcampaigns%2F233228)](http://patreon.com/koistya)\n[![Discord](https://img.shields.io/discord/643523529131950086?label=Chat\u0026style=flat-square)](https://discord.gg/bSsv7XM)\n\nLightweight universal HTTP client for [Cloudflare API](https://api.cloudflare.com/)\nbased on [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)\nthat works in Node.js, browser, and CF Workers environment. Optimized for a good\ndeveloper experience and minimal code with zero dependencies supporting tree-shaking.\n\n## Getting Started\n\n```bash\n# Install using NPM\n$ npm install cloudflare-client --save\n\n# Install using Yarn\n$ yarn add cloudflare-client\n```\n\nOnce the library is installed, you can cherry pick and configure individual\nCloudflare API endpoints that you need. If you bundle your code (e.g. with\nRollup), only the selected modules will be included into the application bundle.\n\n```ts\nimport * as Cloudflare from \"cloudflare-client\";\n\n// EXAMPLE 1:\n//   Initialize an HTTP client for managing Cloudflare DNS\n//   records using API token for authentication\nconst dnsRecords = Cloudflare.dnsRecords({\n  zoneId: \"\u003cCLOUDFLARE_ZONE_ID\u003e\",\n  accessToken: \"\u003cCLOUDFLARE_API_TOKEN\u003e\",\n});\n\n// EXAMPLE 2:\n//   Initialize an HTTP client for managing Cloudflare Workers\n//   KV store using API key and email for authentication\nconst kv = Cloudflare.kv({\n  accountId: \"\u003cCLOUDFLARE_ZONE_ID\u003e\",\n  authKey: \"\u003cCLOUDFLARE_AUTH_KEY\u003e\",\n  authEmail: \"\u003cCLOUDFLARE_AUTH_EMAIL\u003e\",\n});\n```\n\n## User\n\n```ts\n// Initialize an HTTP client for the `user` API endpoint\n// using an API token for authentication\nconst user = Cloudflare.user({ accessToken: \"xxx\" });\n\n// Fetch the currently logged in / authenticated user details\n// https://api.cloudflare.com/#user-user-details\nconst userDetails = await user.get();\n// =\u003e {\n//   id: \"7c5dae5552338874e5053f2534d2767a\",\n//   email: \"user@example.com\",\n//   ...\n// }\n```\n\n## User Tokens\n\n```ts\n// Initialize an HTTP client for the `userTokens` API endpoint\n// using an API token for authentication\nconst userTokens = Cloudflare.userTokens({ accessToken: \"xxx\" });\n\n// Verify the user's token\n// https://api.cloudflare.com/#user-api-tokens-verify-token\nconst token = await userTokens.verify();\n// =\u003e {\n//   id: \"ed17574386854bf78a67040be0a770b0\",\n//   status: \"active\"\n// }\n```\n\n```ts\n// Initialize an HTTP client for the `userTokens` API endpoint\n// using an auth key and email\nconst userTokens = Cloudflare.userTokens({ authKey: \"xxx\", authEmail: \"xxx\" });\n\n// Get token details\n// https://api.cloudflare.com/#user-api-tokens-token-details\nconst token = await userTokens.get(\"ed17574386854bf78a67040be0a770b0\");\n// =\u003e {\n//   id: \"ed17574386854bf78a67040be0a770b0\",\n//   name: \"My Token\",\n//   status: \"active\",\n//   policies: [...],\n//   ...\n// }\n```\n\n## DNS Records\n\n```ts\n// Initialize an HTTP client for managing DNS records\n// within the target zone using API token for authentication\nconst dnsRecords = Cloudflare.dnsRecords({ zoneId: \"xxx\", accessToken: \"xxx\" });\n```\n\n```ts\n// Find all DNS records of type \"A\"\nconst records = await dnsRecords.find({ type: \"A\" }).all();\n\n// Find the first DNS record with the specified name\nconst record = await dnsRecords.find({ type: \"A\", name: \"test\" }).first();\n// =\u003e {\n//  id: \"372e67954025e0ba6aaa6d586b9e0b59\",\n//  type: \"A\",\n//  name: \"test.example.com\",\n//  content: \"192.0.2.1\",\n//  ...\n// }\n```\n\n```ts\n// Fetch the list of DNS records and iterate through the result set using `for await`\nconst records = await dnsRecords.find({ type: \"A\" });\n\nfor await (const record of records) {\n  console.log(record);\n}\n```\n\n```ts\n// Get a specific DNS record by its ID\n// https://api.cloudflare.com/#dns-records-for-a-zone-dns-record-details\nconst record = await dnsRecords.get(\"372e67954025e0ba6aaa6d586b9e0b59\");\n\n// Create a new DNS record\n// https://api.cloudflare.com/#dns-records-for-a-zone-create-dns-record\nconst record = await dnsRecords.create({\n  type: \"A\",\n  name: \"test.example.com\",\n  content: \"192.0.2.1\",\n  proxied: true,\n});\n\n// Replace DNS record\n// https://api.cloudflare.com/#dns-records-for-a-zone-update-dns-record\nconst record = await dnsRecords.replace(\"372e67954025e0ba6aaa6d586b9e0b59\", {\n  type: \"A\",\n  name: \"test.example.com\",\n  content: \"192.0.2.1\",\n  proxied: true,\n});\n\n// Update DNS record\n// https://api.cloudflare.com/#dns-records-for-a-zone-patch-dns-record\nconst record = await dnsRecords.update(\"372e67954025e0ba6aaa6d586b9e0b59\", {\n  proxied: false,\n});\n\n// Delete DNS record\n// https://api.cloudflare.com/#dns-records-for-a-zone-delete-dns-record\nawait dnsRecords.delete(\"372e67954025e0ba6aaa6d586b9e0b59\");\n```\n\n## Workers KV\n\n```ts\n// Initialize an HTTP client for managing CF Workers KV store\nconst kv = Cloudflare.kv({\n  accountId: \"xxx\",\n  authKey: \"xxx\",\n  authEmail: \"xxx\",\n});\n```\n\n#### KV Namespaces\n\n```ts\n// Fetch the list of all KV namespaces\n// https://api.cloudflare.com/#workers-kv-namespace-list-namespaces\nconst namespaces = await kv.find().all();\n\n// Create a new namespace named \"Example\"\n// https://api.cloudflare.com/#workers-kv-namespace-create-a-namespace\nconst ns = await kv.create(\"Example\");\n// =\u003e {\n//   id: \"0f2ac74b498b48028cb68387c421e279\",\n//   title: \"Example\",\n//   supports_url_encoding: true\n// }\n\n// Update/rename a namespace\n// https://api.cloudflare.com/#workers-kv-namespace-rename-a-namespace\nawait kv.update(\"0f2ac74b498b48028cb68387c421e279\", \"New Name\");\n\n// Delete a namespace\n// https://api.cloudflare.com/#workers-kv-namespace-remove-a-namespace\nawait kv.delete(\"0f2ac74b498b48028cb68387c421e279\");\n```\n\n#### Key-Value Pairs\n\n```ts\n// Initialize the API endpoint client for managing key-value pairs\nconst ns = kv.namespace(\"0f2ac74b498b48028cb68387c421e279\");\n\n// Fetch the list of all the keys\nconst keys = await ns.keys().all();\n\n// Fetch the list of all the keys prefixed \"example\"\nconst keys = await ns.keys({ prefix: \"example\" }).all();\n\n// Create or update a key-value pair in Cloudflare KV store\n// using JSON encoding by default (`JSON.stringify(value)`).\nawait ns.set(\"key\", { some: \"value\" });\n\n// Read key-pair value from Cloudflare KV store\nconst value = await ns.get(\"key\");\n// =\u003e {\n//  some: \"name\"\n// }\n\n// Delete a key-pair\nawait ns.delete(\"key\");\n```\n\n```ts\n// Save a key-value pair as plain text (as opposed to JSON-serialized)\nawait ns.set(\"όνομα\", \"José\", { encode: false });\n\n// Read a key-value pair as plain text\nconst value = await ns.get(\"όνομα\", { decode: false });\n// =\u003e \"José\"\n```\n\n## Source Code\n\nFor more information and usage examples check out the source code / tests:\n\n- **[`user.ts`](./src/user.ts)** ([tests](./src/user.test.ts))\n- **[`userTokens.ts`](./src/userTokens.ts)** ([tests](./src/userTokens.test.ts))\n- **[`dnsRecords.ts`](./src/dnsRecords.ts)** ([tests](./src/dnsRecords.test.ts))\n- **[`customHostnames.ts`](./src/customHostnames.ts)** ([tests](./src/customHostnames.test.ts))\n- **[`kv.ts`](./src/kv.ts)** ([tests](./src/kv.test.ts))\n\n## Backers 💰\n\n\u003ca href=\"https://reactstarter.com/b/1\"\u003e\u003cimg src=\"https://reactstarter.com/b/1.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/2\"\u003e\u003cimg src=\"https://reactstarter.com/b/2.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/3\"\u003e\u003cimg src=\"https://reactstarter.com/b/3.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/4\"\u003e\u003cimg src=\"https://reactstarter.com/b/4.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/5\"\u003e\u003cimg src=\"https://reactstarter.com/b/5.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/6\"\u003e\u003cimg src=\"https://reactstarter.com/b/6.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/7\"\u003e\u003cimg src=\"https://reactstarter.com/b/7.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/8\"\u003e\u003cimg src=\"https://reactstarter.com/b/8.png\" height=\"60\" /\u003e\u003c/a\u003e\n\n## Related Projects\n\n- [Cloudflare Workers Starter Kit](https://github.com/kriasoft/cloudflare-starter-kit) — TypeScript project template for Cloudflare Workers\n- [React Starter Kit](https://github.com/kriasoft/react-starter-kit) — front-end template for React and Relay using Jamstack architecture\n- [GraphQL API and Relay Starter Kit](https://github.com/kriasoft/graphql-starter) — monorepo template, pre-configured with GraphQL API, React, and Relay\n\n## How to Contribute\n\nYou're very welcome to [create a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)\nor send me a message on [Discord](https://discord.gg/bSsv7XM).\n\n```bash\n$ git clone https://github.com/kriasoft/cloudflare-client.git\n$ cd ./cloudflare-client\n$ yarn install\n$ yarn test\n```\n\n**NOTE**: In order to run unit tests locally you will need Node.js `v16.15` or newer and Cloudflare API token.\n\n## License\n\nCopyright © 2022-present Kriasoft. This source code is licensed under the MIT license found in the\n[LICENSE](https://github.com/kriasoft/cloudflare-client/blob/main/LICENSE) file.\n\n---\n\n\u003csup\u003eMade with ♥ by Konstantin Tarkus ([@koistya](https://twitter.com/koistya), [blog](https://medium.com/@koistya))\nand [contributors](https://github.com/kriasoft/cloudflare-client/graphs/contributors).\u003c/sup\u003e\n","funding_links":["https://github.com/sponsors/kriasoft","https://patreon.com/koistya","https://opencollective.com/react-starter-kit","https://img.shields.io/badge/dynamic/json?color=%23ff424d\u0026label=Patreon\u0026style=flat-square\u0026query=data.attributes.patron_count\u0026suffix=%20patrons\u0026url=https%3A%2F%2Fwww.patreon.com%2Fapi%2Fcampaigns%2F233228","http://patreon.com/koistya"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkriasoft%2Fcloudflare-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkriasoft%2Fcloudflare-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkriasoft%2Fcloudflare-client/lists"}