@codefusion-cc/r2

Cloudflare R2 through its S3 API, for scripts, CI jobs and Workers that reach a bucket without a binding: an account's photos uploaded from a Mac, a nightly backup between buckets, files read from another account. Built on WebCrypto and fetch only, so the same code runs in Node and in Workers. A Worker with an R2 binding uses the binding instead; this package is for everything else.

npm install @codefusion-cc/r2

import { orThrow, r2AccessFromToken, r2Client } from '@codefusion-cc/r2'

const access = await r2AccessFromToken(process.env.CLOUDFLARE_API_TOKEN!)
if (!access.ok) throw new Error(access.message) // rejected, accounts (which one?), network
const r2 = r2Client(access.access)

orThrow(await r2.createBucket('photos')) // 'created' or 'exists'
orThrow(await r2.put('photos', '42-800.webp', bytes, { contentType: 'image/webp', cacheControl: 'public, max-age=31536000, immutable' }))
const stored = orThrow(await r2.head('photos', '42-800.webp')) // null when there is none
const all = orThrow(await r2.list('photos', { prefix: '42-' })) // every page
orThrow(await r2.copy('photos', '42-800.webp', 'backups', 'photos/42-800.webp')) // on R2's side
orThrow(await r2.putMultipart('backups', 'db.sql.gz', file, { partSize: 16 * 1024 * 1024 }))

• One token, no extra secret. r2AccessFromToken turns a Cloudflare API token with an R2 permission into R2's S3 keys as Cloudflare defines them: the token's id, and its value's SHA-256. It takes user tokens (My Profile) and account tokens, and finds the account when the token sees only one. R2 takes a token's keys some seconds after Cloudflare makes it (it answers 401 until then, though the token verifies as active at once), so the keys come back once R2 lists the buckets with them, waiting up to a minute (usableWithinMs; 0 doesn't ask R2): a script's first call with a token minted moments before doesn't fail. The S3 API has its own limits, not the 1,200 requests per 5 minutes of Cloudflare's API, so a bulk upload doesn't hold up other tools that use that API.
• Results, not exceptions. Every call resolves with { ok: true, value } or an R2Failure naming why: denied, missing-bucket, rejected, network, timeout, with R2's status and S3 error code. A missing object is null, not a failure. orThrow turns a result into its value or an Error, for scripts where a failure ends the run. Only a caller's mistake throws: an account id that isn't one, a part under 5 MiB, metadata that can't be sent.
• Retries where they help. No answer, 429 and 5xx are tried again (4 tries by default), with growing pauses and Retry-After when R2 gives it; a refusal (4xx) is not. Every body is one fetch can send again.
• Multipart that cleans up. putMultipart sends equal parts (R2 requires it) several at once, each retried on its own, grows the part size past 10,000 parts, and aborts the upload when it fails, so no parts stay behind. A body of one part or less goes in a single put.
• Keys as given. Any key works: spaces, +&=?#, '!()*, unicode, many slashes. Paths are signed exactly as they're sent.
• signV4 signs any AWS request (SES, S3, others) with SigV4. AWS's published examples are part of its tests.

Testing

@codefusion-cc/r2/testing has R2 and Cloudflare's token API in memory, behind a fetch:

import { fakeR2, keysOf } from '@codefusion-cc/r2/testing'

const r2 = fakeR2({ tokens: [{ value: 'token', id: 'token-id' }], buckets: ['photos'] })
const client = r2Client({ accountId: r2.accountId, ...(await keysOf({ value: 'token', id: 'token-id' })), fetcher: r2.fetch })
r2.fault({ when: request => request.query.partNumber === '2', status: 503 }) // once; `times`, `drop`, `retryAfter`
r2.text('photos', 'a.txt') // what is stored

It checks every S3 request's signature with code of its own, written from AWS's specification and tested on AWS's examples, not with this package's signer. Clock skew, unknown keys, read-only tokens (write: false), a token R2 takes only later (s3From, answered 401 until then), missing buckets, list pages (pageSize), ListBuckets, CopyObject and multipart uploads with R2's part rules all behave as R2 does. verifySigV4 is exported for a server of your own.