Skip to main content

@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?​

optional filename?: 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?​

optional meta?: Record<string, unknown>

Defined in: index.ts:48


UploadOptions​

Defined in: index.ts:52

Options shared by ImagesApi.upload and ImagesApi.directUpload.

Properties​

id?​

optional id?: string

Defined in: index.ts:54

A custom image id (it may contain /). Omit it and Cloudflare generates one.

metadata?​

optional metadata?: Record<string, unknown>

Defined in: index.ts:56

Arbitrary JSON stored with the image.

requireSignedURLs?​

optional requireSignedURLs?: 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?​

optional format?: RequestInitCfPropertiesImage["format"] | "auto"

gravity?​

optional gravity?: 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​

ImageOptions

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​

ImageOptions

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

Returns​

ImagesApi