cloudflare/cloudflare-typescript
Publicmirrored from https://github.com/cloudflare/cloudflare-typescriptAvailable
README.md
295lines · modecode
| 1 | # Cloudflare Node API Library |
| 2 | |
| 3 | [](https://npmjs.org/package/cloudflare) |
| 4 | |
| 5 | This library provides convenient access to the Cloudflare REST API from server-side TypeScript or JavaScript. |
| 6 | |
| 7 | The REST API documentation can be found [on developers.cloudflare.com](https://developers.cloudflare.com/api). The full API of this library can be found in [api.md](api.md). |
| 8 | |
| 9 | ## Installation |
| 10 | |
| 11 | ```sh |
| 12 | npm install cloudflare |
| 13 | ``` |
| 14 | |
| 15 | ## Usage |
| 16 | |
| 17 | The full API of this library can be found in [api.md](api.md). |
| 18 | |
| 19 | <!-- prettier-ignore --> |
| 20 | ```js |
| 21 | import Cloudflare from 'cloudflare'; |
| 22 | |
| 23 | const cloudflare = new Cloudflare({ |
| 24 | apiEmail: process.env['CLOUDFLARE_EMAIL'], // This is the default and can be omitted |
| 25 | apiKey: process.env['CLOUDFLARE_API_KEY'], // This is the default and can be omitted |
| 26 | }); |
| 27 | |
| 28 | async function main() { |
| 29 | const zoneCreateResponse = await cloudflare.zones.create({ |
| 30 | account: { id: '023e105f4ecef8ad9ca31a8372d0c353' }, |
| 31 | name: 'example.com', |
| 32 | type: 'full', |
| 33 | }); |
| 34 | |
| 35 | console.log(zoneCreateResponse.id); |
| 36 | } |
| 37 | |
| 38 | main(); |
| 39 | ``` |
| 40 | |
| 41 | ### Request & Response types |
| 42 | |
| 43 | This library includes TypeScript definitions for all request params and response fields. You may import and use them like so: |
| 44 | |
| 45 | <!-- prettier-ignore --> |
| 46 | ```ts |
| 47 | import Cloudflare from 'cloudflare'; |
| 48 | |
| 49 | const cloudflare = new Cloudflare({ |
| 50 | apiEmail: process.env['CLOUDFLARE_EMAIL'], // This is the default and can be omitted |
| 51 | apiKey: process.env['CLOUDFLARE_API_KEY'], // This is the default and can be omitted |
| 52 | }); |
| 53 | |
| 54 | async function main() { |
| 55 | const params: Cloudflare.ZoneCreateParams = { |
| 56 | account: { id: '023e105f4ecef8ad9ca31a8372d0c353' }, |
| 57 | name: 'example.com', |
| 58 | type: 'full', |
| 59 | }; |
| 60 | const zoneCreateResponse: Cloudflare.ZoneCreateResponse = await cloudflare.zones.create(params); |
| 61 | } |
| 62 | |
| 63 | main(); |
| 64 | ``` |
| 65 | |
| 66 | Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors. |
| 67 | |
| 68 | ## Handling errors |
| 69 | |
| 70 | When the library is unable to connect to the API, |
| 71 | or if the API returns a non-success status code (i.e., 4xx or 5xx response), |
| 72 | a subclass of `APIError` will be thrown: |
| 73 | |
| 74 | <!-- prettier-ignore --> |
| 75 | ```ts |
| 76 | async function main() { |
| 77 | const zone = await cloudflare.zones |
| 78 | .get({ zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }) |
| 79 | .catch(async (err) => { |
| 80 | if (err instanceof Cloudflare.APIError) { |
| 81 | console.log(err.status); // 400 |
| 82 | console.log(err.name); // BadRequestError |
| 83 | console.log(err.headers); // {server: 'nginx', ...} |
| 84 | } else { |
| 85 | throw err; |
| 86 | } |
| 87 | }); |
| 88 | } |
| 89 | |
| 90 | main(); |
| 91 | ``` |
| 92 | |
| 93 | Error codes are as followed: |
| 94 | |
| 95 | | Status Code | Error Type | |
| 96 | | ----------- | -------------------------- | |
| 97 | | 400 | `BadRequestError` | |
| 98 | | 401 | `AuthenticationError` | |
| 99 | | 403 | `PermissionDeniedError` | |
| 100 | | 404 | `NotFoundError` | |
| 101 | | 422 | `UnprocessableEntityError` | |
| 102 | | 429 | `RateLimitError` | |
| 103 | | >=500 | `InternalServerError` | |
| 104 | | N/A | `APIConnectionError` | |
| 105 | |
| 106 | ### Retries |
| 107 | |
| 108 | Certain errors will be automatically retried 2 times by default, with a short exponential backoff. |
| 109 | Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, |
| 110 | 429 Rate Limit, and >=500 Internal errors will all be retried by default. |
| 111 | |
| 112 | You can use the `maxRetries` option to configure or disable this: |
| 113 | |
| 114 | <!-- prettier-ignore --> |
| 115 | ```js |
| 116 | // Configure the default for all requests: |
| 117 | const cloudflare = new Cloudflare({ |
| 118 | maxRetries: 0, // default is 2 |
| 119 | }); |
| 120 | |
| 121 | // Or, configure per-request: |
| 122 | await cloudflare.zones.get({ zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }, { |
| 123 | maxRetries: 5, |
| 124 | }); |
| 125 | ``` |
| 126 | |
| 127 | ### Timeouts |
| 128 | |
| 129 | Requests time out after 1 minute by default. You can configure this with a `timeout` option: |
| 130 | |
| 131 | <!-- prettier-ignore --> |
| 132 | ```ts |
| 133 | // Configure the default for all requests: |
| 134 | const cloudflare = new Cloudflare({ |
| 135 | timeout: 20 * 1000, // 20 seconds (default is 1 minute) |
| 136 | }); |
| 137 | |
| 138 | // Override per-request: |
| 139 | await cloudflare.zones.edit({ zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }, { |
| 140 | timeout: 5 * 1000, |
| 141 | }); |
| 142 | ``` |
| 143 | |
| 144 | On timeout, an `APIConnectionTimeoutError` is thrown. |
| 145 | |
| 146 | Note that requests which time out will be [retried twice by default](#retries). |
| 147 | |
| 148 | ## Auto-pagination |
| 149 | |
| 150 | List methods in the Cloudflare API are paginated. |
| 151 | You can use `for await … of` syntax to iterate through items across all pages: |
| 152 | |
| 153 | ```ts |
| 154 | async function fetchAllAccounts(params) { |
| 155 | const allAccounts = []; |
| 156 | // Automatically fetches more pages as needed. |
| 157 | for await (const accountListResponse of cloudflare.accounts.list()) { |
| 158 | allAccounts.push(accountListResponse); |
| 159 | } |
| 160 | return allAccounts; |
| 161 | } |
| 162 | ``` |
| 163 | |
| 164 | Alternatively, you can make request a single page at a time: |
| 165 | |
| 166 | ```ts |
| 167 | let page = await cloudflare.accounts.list(); |
| 168 | for (const accountListResponse of page.result) { |
| 169 | console.log(accountListResponse); |
| 170 | } |
| 171 | |
| 172 | // Convenience methods are provided for manually paginating: |
| 173 | while (page.hasNextPage()) { |
| 174 | page = page.getNextPage(); |
| 175 | // ... |
| 176 | } |
| 177 | ``` |
| 178 | |
| 179 | ## Advanced Usage |
| 180 | |
| 181 | ### Accessing raw Response data (e.g., headers) |
| 182 | |
| 183 | The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return. |
| 184 | |
| 185 | You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data. |
| 186 | |
| 187 | <!-- prettier-ignore --> |
| 188 | ```ts |
| 189 | const cloudflare = new Cloudflare(); |
| 190 | |
| 191 | const response = await cloudflare.zones |
| 192 | .create({ account: { id: '023e105f4ecef8ad9ca31a8372d0c353' }, name: 'example.com', type: 'full' }) |
| 193 | .asResponse(); |
| 194 | console.log(response.headers.get('X-My-Header')); |
| 195 | console.log(response.statusText); // access the underlying Response object |
| 196 | |
| 197 | const { data: zoneCreateResponse, response: raw } = await cloudflare.zones |
| 198 | .create({ account: { id: '023e105f4ecef8ad9ca31a8372d0c353' }, name: 'example.com', type: 'full' }) |
| 199 | .withResponse(); |
| 200 | console.log(raw.headers.get('X-My-Header')); |
| 201 | console.log(zoneCreateResponse.id); |
| 202 | ``` |
| 203 | |
| 204 | ## Customizing the fetch client |
| 205 | |
| 206 | By default, this library uses `node-fetch` in Node, and expects a global `fetch` function in other environments. |
| 207 | |
| 208 | If you would prefer to use a global, web-standards-compliant `fetch` function even in a Node environment, |
| 209 | (for example, if you are running Node with `--experimental-fetch` or using NextJS which polyfills with `undici`), |
| 210 | add the following import before your first import `from "Cloudflare"`: |
| 211 | |
| 212 | ```ts |
| 213 | // Tell TypeScript and the package to use the global web fetch instead of node-fetch. |
| 214 | // Note, despite the name, this does not add any polyfills, but expects them to be provided if needed. |
| 215 | import 'cloudflare/shims/web'; |
| 216 | import Cloudflare from 'cloudflare'; |
| 217 | ``` |
| 218 | |
| 219 | To do the inverse, add `import "cloudflare/shims/node"` (which does import polyfills). |
| 220 | This can also be useful if you are getting the wrong TypeScript types for `Response` ([more details](https://github.com/cloudflare/cloudflare-typescript/tree/main/src/_shims#readme)). |
| 221 | |
| 222 | You may also provide a custom `fetch` function when instantiating the client, |
| 223 | which can be used to inspect or alter the `Request` or `Response` before/after each request: |
| 224 | |
| 225 | ```ts |
| 226 | import { fetch } from 'undici'; // as one example |
| 227 | import Cloudflare from 'cloudflare'; |
| 228 | |
| 229 | const client = new Cloudflare({ |
| 230 | fetch: async (url: RequestInfo, init?: RequestInit): Promise<Response> => { |
| 231 | console.log('About to make a request', url, init); |
| 232 | const response = await fetch(url, init); |
| 233 | console.log('Got response', response); |
| 234 | return response; |
| 235 | }, |
| 236 | }); |
| 237 | ``` |
| 238 | |
| 239 | Note that if given a `DEBUG=true` environment variable, this library will log all requests and responses automatically. |
| 240 | This is intended for debugging purposes only and may change in the future without notice. |
| 241 | |
| 242 | ## Configuring an HTTP(S) Agent (e.g., for proxies) |
| 243 | |
| 244 | By default, this library uses a stable agent for all http/https requests to reuse TCP connections, eliminating many TCP & TLS handshakes and shaving around 100ms off most requests. |
| 245 | |
| 246 | If you would like to disable or customize this behavior, for example to use the API behind a proxy, you can pass an `httpAgent` which is used for all requests (be they http or https), for example: |
| 247 | |
| 248 | <!-- prettier-ignore --> |
| 249 | ```ts |
| 250 | import http from 'http'; |
| 251 | import { HttpsProxyAgent } from 'https-proxy-agent'; |
| 252 | |
| 253 | // Configure the default for all requests: |
| 254 | const cloudflare = new Cloudflare({ |
| 255 | httpAgent: new HttpsProxyAgent(process.env.PROXY_URL), |
| 256 | }); |
| 257 | |
| 258 | // Override per-request: |
| 259 | await cloudflare.zones.delete( |
| 260 | { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }, |
| 261 | { |
| 262 | httpAgent: new http.Agent({ keepAlive: false }), |
| 263 | }, |
| 264 | ); |
| 265 | ``` |
| 266 | |
| 267 | ## Semantic Versioning |
| 268 | |
| 269 | This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions: |
| 270 | |
| 271 | 1. Changes that only affect static types, without breaking runtime behavior. |
| 272 | 2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals)_. |
| 273 | 3. Changes that we do not expect to impact the vast majority of users in practice. |
| 274 | |
| 275 | We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience. |
| 276 | |
| 277 | We are keen for your feedback; please open an [issue](https://www.github.com/cloudflare/cloudflare-typescript/issues) with questions, bugs, or suggestions. |
| 278 | |
| 279 | ## Requirements |
| 280 | |
| 281 | TypeScript >= 4.5 is supported. |
| 282 | |
| 283 | The following runtimes are supported: |
| 284 | |
| 285 | - Node.js 18 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions. |
| 286 | - Deno v1.28.0 or higher, using `import Cloudflare from "npm:cloudflare"`. |
| 287 | - Bun 1.0 or later. |
| 288 | - Cloudflare Workers. |
| 289 | - Vercel Edge Runtime. |
| 290 | - Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time). |
| 291 | - Nitro v2.6 or greater. |
| 292 | |
| 293 | Note that React Native is not supported at this time. |
| 294 | |
| 295 | If you are interested in other runtime environments, please open or upvote an issue on GitHub. |
| 296 | |