api
@rtorcato/cf-common/api calls Cloudflare's v4 REST API over fetch. It covers
zones, DNS records and cache purge, and request reaches any other endpoint. It
adds no dependencies, so it stays small enough for a Worker.
import { createCloudflareApi } from '@rtorcato/cf-common/api'
The token
The client authenticates with an
API token.
Give the token only the permissions you use: Zone Read to list zones,
DNS Edit to change records and Cache Purge to purge. Keep it out of
source with wrangler secret put CLOUDFLARE_API_TOKEN.
import { requireEnv } from '@rtorcato/cf-common/env'
const cf = createCloudflareApi({ token: requireEnv(env, 'CLOUDFLARE_API_TOKEN') })
Zones
const { result: zones } = await cf.zones.list({ name: 'example.com' })
const zone = await cf.zones.get(zones[0].id)
DNS
const { result: records } = await cf.dns.list(zone.id, { type: 'A' })
const record = await cf.dns.create(zone.id, {
type: 'A',
name: 'app.example.com',
content: '192.0.2.1',
proxied: true,
})
// PATCH: only the fields you pass change.
await cf.dns.update(zone.id, record.id, { content: '192.0.2.2' })
await cf.dns.delete(zone.id, record.id)
Purge cache
Pass one purge mode per call: files, tags, hosts, prefixes or
purge_everything.
await cf.cache.purge(zone.id, { files: ['https://example.com/app.css'] })
await cf.cache.purge(zone.id, { purge_everything: true })
Cloudflare limits how many URLs, tags or prefixes one request may carry. See Purge cache for the current limits.
Other endpoints
request calls any v4 endpoint and returns the envelope's result.
requestPage does the same for a list endpoint and also returns its
result_info. The path is used as given, so encode any ids you put into it.
const token = await cf.request<{ status: string }>('GET', '/user/tokens/verify')
const accountId = encodeURIComponent(requireEnv(env, 'CLOUDFLARE_ACCOUNT_ID'))
const workers = await cf.requestPage<{ id: string }>(`/accounts/${accountId}/workers/scripts`)
List calls return one page. To read them all, loop on page:
const all = []
for (let page = 1; ; page++) {
const { result, resultInfo } = await cf.zones.list({ page, per_page: 50 })
all.push(...result)
if (page >= (resultInfo.total_pages ?? 1)) break
}
When the call fails
Every failure throws a CloudflareError with status 502, code CF_API_ERROR
and expose: false. That covers a non-2xx response, success: false in the
body, a body that isn't JSON, and a network error. The message names the method,
path and Cloudflare's first error message, but never the token.
The named helpers reject a zone or record id of . or .. before sending
anything, with an exposed 400 and code CF_API_INVALID_ID, since fetch
would resolve it to a different endpoint. Raw request sends its path as given.
For an API error, cause holds the upstream status and Cloudflare's errors,
so you can branch on a 404 or a 429:
import { isCloudflareError } from '@rtorcato/cf-common/errors'
try {
await cf.zones.get(zoneId)
} catch (err) {
const upstream = isCloudflareError(err) ? (err.cause as { status?: number }) : undefined
if (upstream?.status === 404) return error(404, 'No such zone')
throw err
}
For a network error, cause is the error fetch threw.
Good to know
ZoneandDnsRecordtype only the common fields. For the full payload, callrequest<YourType>with your own type.- There are no retries, timeouts or auto-pagination. Handle a 429 from
cause. - Only API tokens are supported, not the global API key.
- For the whole API, use Cloudflare's official
cloudflareSDK. This module stays small for the common Worker tasks.
For a runnable walkthrough, see the /api route in apps/example. See the
api API reference for every option.