@rtorcato/cf-common
Interfaces
ImageDetails
Defined in: index.ts:41
The fields Cloudflare returns for an uploaded image.
Properties
id
id:
string
Defined in: index.ts:42
filename?
optionalfilename?:string
Defined in: index.ts:43
uploaded
uploaded:
string
Defined in: index.ts:44
requireSignedURLs
requireSignedURLs:
boolean
Defined in: index.ts:45
variants
variants:
string[]
Defined in: index.ts:47
One delivery URL per named variant.
meta?
optionalmeta?:Record<string,unknown>
Defined in: index.ts:48
UploadOptions
Defined in: index.ts:52
Options shared by ImagesApi.upload and ImagesApi.directUpload.
Properties
id?
optionalid?:string
Defined in: index.ts:54
A custom image id (it may contain /). Omit it and Cloudflare generates one.
metadata?
optionalmetadata?:Record<string,unknown>
Defined in: index.ts:56
Arbitrary JSON stored with the image.
requireSignedURLs?
optionalrequireSignedURLs?:boolean
Defined in: index.ts:58
Only deliver this image through signed URLs (see signImageUrl).
ImagesApi
Defined in: index.ts:61
Methods
upload()
upload(
file,options?):Promise<ImageDetails>
Defined in: index.ts:66
Upload an image from a Blob/File, or have Cloudflare fetch it from a
URL string. filename names a Blob upload.
Parameters
file
string | Blob
options?
UploadOptions & object
Returns
Promise<ImageDetails>
directUpload()
directUpload(
options?):Promise<{id:string;uploadURL:string; }>
Defined in: index.ts:76
Reserve a one-time upload URL, so a browser can POST the file (as the
file form field) straight to Cloudflare without seeing your token.
expiry must be 2 minutes to 6 hours ahead (Cloudflare's default is 30
minutes).
Parameters
options?
UploadOptions & object
Returns
Promise<{ id: string; uploadURL: string; }>
Type Aliases
ImageOptions
ImageOptions =
Pick<RequestInitCfPropertiesImage,"width"|"height"|"fit"|"quality"|"dpr"|"zoom"|"sharpen"|"blur"|"rotate"|"flip"|"background"|"brightness"|"contrast"|"gamma"|"saturation"|"anim"|"metadata"|"segment"|"upscale"> &object
Defined in: index.ts:14
Resize and format options, written into a flexible variant or a
/cdn-cgi/image/ URL as key=value pairs. The names and values are the ones
fetch(url, { cf: { image } }) takes, limited to those a URL can carry, plus
format: 'auto' and gravity: { x, y } (sent as 0.5x0.5).
Type Declaration
format?
optionalformat?:RequestInitCfPropertiesImage["format"] |"auto"
gravity?
optionalgravity?:Exclude<BasicImageTransformations["gravity"],object> | {x:number;y:number; }
Functions
imageOptions()
imageOptions(
options):string
Defined in: index.ts:115
Serialize ImageOptions to key=value,…, skipping unset keys.
Parameters
options
Returns
string
imageUrl()
imageUrl(
options):string
Defined in: index.ts:139
Build an image's delivery URL from a named variant ('public') or flexible
variant options ({ width: 400, format: 'auto' }, which must be enabled for
the account). Pass origin to deliver from your own zone through
/cdn-cgi/imagedelivery/. A ./.. or empty id segment throws an exposed
400 IMAGES_INVALID_ID.
Example
imageUrl({ accountHash, imageId: 'avatars/ada', variant: { width: 128, fit: 'cover' } })
// https://imagedelivery.net/<accountHash>/avatars/ada/width=128,fit=cover
Parameters
options
accountHash
string
imageId
string
variant
string | ImageOptions
origin?
string
Returns
string
transformUrl()
transformUrl(
source,options,origin?):string
Defined in: index.ts:161
Build a /cdn-cgi/image/<options>/<source> URL, which resizes any image
(not only ones stored in Images) on a zone with Image Transformations on.
source is a path on the same zone or an absolute URL; origin defaults to
none, giving a root-relative URL.
Example
transformUrl('/uploads/cat.jpg', { width: 800, quality: 80, format: 'auto' })
// /cdn-cgi/image/width=800,quality=80,format=auto/uploads/cat.jpg
Parameters
source
string
options
origin?
string = ''
Returns
string
signImageUrl()
signImageUrl(
url,key,options?):Promise<string>
Defined in: index.ts:175
Sign a delivery URL for an image that requires signed URLs: adds exp (now +
expiresIn seconds, default 1 hour) and sig, an HMAC-SHA256 of the path and
query keyed with the account's Images signing key. Signed delivery works
with named variants only; flexible variants are refused for such images.
Keep the key in wrangler secret put.
Example
const url = await signImageUrl(imageUrl({ accountHash, imageId, variant: 'public' }), key)
Parameters
url
string
key
string
options?
expiresIn?
number
Returns
Promise<string>
createImagesApi()
createImagesApi(
options):ImagesApi
Defined in: index.ts:212
A client for the Cloudflare Images upload API, authenticated with an API
token that has Images Write. Every failure (non-2xx, success: false, a
non-JSON body, a network error) throws a non-exposed 502 CloudflareError
with code IMAGES_API_ERROR; the upstream status and errors are on cause.
The token never appears in the error.
Example
const images = createImagesApi({ accountId, token: requireEnv(env, 'IMAGES_TOKEN') })
const { uploadURL } = await images.directUpload({ metadata: { user: 'u_1' } })
Parameters
options
accountId
string
token
string