Cloudflare/images

@webframp/cloudflare/imagesv2026.10.21.1· Apache-2.0· 5d agoBEHAVIORS

01README

Cloudflare Images — upload, transform, deliver, and manage image pipelines

02Release Notes

2026.10.21.1

Changed: The README and the apiToken description now lead with a vault. Store the token with swamp vault put cloudflare API_TOKEN and set apiToken to ${{ vault.get("cloudflare", "API_TOKEN") }}. The CLOUDFLARE_API_TOKEN environment variable still works as a fallback, but swamp does not redact it, so it is no longer recommended. The missing-token error now says the same.

Changed: Method arguments that carry a secret are now marked sensitive, so swamp redacts them from logs and run records. Pass them as vault.get expressions. Affected: create_source and create_cloudflare_images_sourcingkit_precheck_source_connectivity. The README's new "Secrets" section lists them per method.

Fixed: Create methods whose response carries no id wrote every result to one instance named created, so each call overwrote the previous one. They now name the instance by the response's id when present, else by the path parameter that scopes the call, else by a hash of the request arguments (secret arguments left out). Affected: create_a_variant and create_cloudflare_images_sourcingkit_precheck_source_connectivity.

Upgrade note: Results earlier versions wrote to the created instance stay there; new runs write under the new names.

03Behaviors1

@webframp/cloudflare/imagesv2026.10.21.1cloudflare/images.ts

Global Arguments

Argument	Type	Required	Description
apiToken?	string	no	Cloudflare API token. Wire it with ${{ vault.get("cloudflare", "API_TOKEN") }}; never pass the literal token. The CLOUDFLARE_API_TOKEN environment variable is read as a fallback, but it is not redacted and is not recommended.
accountId	string	yes	Cloudflare account ID

fn list_signing_keys()

List Signing Keys

fn update_cloudflare_images_keys_add_signing_key(signing_key_name: string)

Create a new Signing Key

Argument	Type	Required	Description
signing_key_name	string	yes

fn delete_signing_key(signing_key_name: string)

Delete Signing Key

Argument	Type	Required	Description
signing_key_name	string	yes

fn get_cloudflare_images_images_usage_statistics()

Images usage statistics

fn list_variants()

List variants

fn create_a_variant(neverRequireSignedURLs?: unknown, options: unknown)

Create a variant

Argument	Type	Required	Description
neverRequireSignedURLs?	unknown	no
options	unknown	yes

fn get_cloudflare_images_variants_variant_details(variant_id: string)

Variant details

Argument	Type	Required	Description
variant_id	string	yes

fn update_a_variant(variant_id: string, neverRequireSignedURLs?: unknown, options: unknown)

Update a variant

Argument	Type	Required
variant_id	string	yes
neverRequireSignedURLs?	unknown	no
options	unknown	yes

fn delete_a_variant(variant_id: string)

Delete a variant

Argument	Type	Required	Description
variant_id	string	yes

fn get_cloudflare_images_variants_variant_details_flat(variant_id: string)

Variant details (flat)

Argument	Type	Required	Description
variant_id	string	yes

fn get_cloudflare_images_image_details(image_id: string)

Image details

Argument	Type	Required	Description
image_id	string	yes

fn update_image(image_id: string, creator?: string, metadata?: object, requireSignedURLs?: boolean)

Update image

Argument	Type	Required	Description
image_id	string	yes
creator?	string	no	Can set the creator field with an internal user ID.
metadata?	object	no	User modifiable key-value store. Can be used for keeping references to anothe...
requireSignedURLs?	boolean	no	Indicates whether the image can be accessed using only its UID. If set to `tr...

fn delete_image(image_id: string)

Delete image

Argument	Type	Required	Description
image_id	string	yes

fn list_images_v2(continuation_token?: string, per_page?: number, sort_order?: enum, creator?: string, meta_field_operator?: string)

List images V2

Argument	Type	Required	Description
continuation_token?	string	no
per_page?	number	no
sort_order?	enum	no
creator?	string	no
meta_field_operator?	string	no	Optional metadata filter(s). Multiple filters can be combined with AND logic. Operators: - `eq`, `eq:string`, `eq:number`, `eq:boolean` - Exact match - `gt`, `gt:number` - Greater than (number only) - `gte`, `gte:number` - Greater than or equal (number only) - `lt`, `lt:number` - Less than (number only) - `lte`, `lte:number` - Less than or equal (number only) - `in`, `in:string`, `in:number` - Match any value in pipe-separated list Examples: - `meta.status[eq]=active` - `meta.priority[

fn list_migrations(offset?: number, limit?: number)

List sourcing kit migrations

Argument	Type	Required	Description
offset?	number	no
limit?	number	no

fn create_migration(conflictBehaviour?: unknown, excludedContentTypes?: array, pathPrefix?: string, rootDirectory?: string, sourceId: string)

Create a sourcing kit migration

Argument	Type	Required	Description
conflictBehaviour?	unknown	no
excludedContentTypes?	array	no	Content types to skip during migration.
pathPrefix?	string	no	Prefix to prepend to image custom IDs.
rootDirectory?	string	no	Only import objects under this prefix in the source bucket.
sourceId	string	yes	The identifier of the source to migrate from.

fn get_migration(migration_id: string)

Get sourcing kit migration

Argument	Type	Required	Description
migration_id	string	yes

fn delete_migration(migration_id: string)

Delete a sourcing kit migration

Argument	Type	Required	Description
migration_id	string	yes

fn get_migration_progress(migration_id: string)

Get migration progress

Argument	Type	Required	Description
migration_id	string	yes

fn update_cloudflare_images_sourcingkit_abort_migration(migration_id: string)

Abort a migration

Argument	Type	Required	Description
migration_id	string	yes

fn update_cloudflare_images_sourcingkit_start_migration(migration_id: string)

Start a migration

Argument	Type	Required	Description
migration_id	string	yes

fn list_migration_logs(migration_id: string, offset?: number, limit?: number)

List migration logs

Argument	Type	Required
migration_id	string	yes
offset?	number	no
limit?	number	no

fn list_sources(offset?: number, limit?: number, name?: string)

List sourcing kit sources

Argument	Type	Required
offset?	number	no
limit?	number	no
name?	string	no

fn create_source(account?: string, bucket: string, name: string, secret: object, vendor: unknown)

Create a sourcing kit source

Argument	Type	Required	Description
account?	string	no	Account identifier for the bucket (required for R2 vendor).
bucket	string	yes	The name of the storage bucket.
name	string	yes	A human-readable name for the source.
secret	object	yes	Storage credentials for accessing the bucket. Shape depends on vendor. Secret: pass a vault.get expression, never a literal value.
vendor	unknown	yes

fn create_cloudflare_images_sourcingkit_precheck_source_connectivity(account?: string, bucket: string, region?: string, secret: object, vendor: unknown)

Precheck source connectivity

Argument	Type	Required	Description
account?	string	no	Account identifier for the bucket (required for R2 vendor).
bucket	string	yes	The name of the storage bucket.
region?	string	no	The region hint for the bucket (S3 only).
secret	object	yes	Storage credentials for accessing the bucket. Secret: pass a vault.get expression, never a literal value.
vendor	unknown	yes

fn get_source(source_id: string)

Get sourcing kit source

Argument	Type	Required	Description
source_id	string	yes

fn update_source(source_id: string, name: string)

Update a sourcing kit source

Argument	Type	Required	Description
source_id	string	yes
name	string	yes	Updated name for the source.

fn delete_source(source_id: string)

Delete a sourcing kit source

Argument	Type	Required	Description
source_id	string	yes

fn get_source_connectivity(source_id: string)

Get source connectivity status

Argument	Type	Required	Description
source_id	string	yes

Resources

list_signing_keys(infinite)— List Signing Keys

cloudflare_images_keys_add_signing_key(infinite)— Create a new Signing Key

cloudflare_images_images_usage_statistics(infinite)— Images usage statistics

list_variants(infinite)— List variants

a_variant(infinite)— Create a variant

cloudflare_images_variants_variant_details(infinite)— Variant details

cloudflare_images_variants_variant_details_flat(infinite)— Variant details (flat)

cloudflare_images_image_details(infinite)— Image details

image(infinite)— Update image

list_images_v2(infinite)— List images V2

list_migrations(infinite)— List sourcing kit migrations

migration(infinite)— Create a sourcing kit migration

migration_progress(infinite)— Get migration progress

cloudflare_images_sourcingkit_abort_migration(infinite)— Abort a migration

cloudflare_images_sourcingkit_start_migration(infinite)— Start a migration

list_migration_logs(infinite)— List migration logs

list_sources(infinite)— List sourcing kit sources

source(infinite)— Create a sourcing kit source

cloudflare_images_sourcingkit_precheck_source_connectivity(infinite)— Precheck source connectivity

source_connectivity(infinite)— Get source connectivity status

04Previous Versions12

2026.10.14.1Apache-2.0(was none)Oct 14, 2026

2026.10.14.1

Fixed: Methods that write a singleton resource failed on current swamp with Data name 'latest' is reserved for internal use.

Changed: Singleton get and action methods now write their data under cloudflare_images_images_usage_statistics-current, list_images_v2-current, list_migrations-current, list_signing_keys-current, list_sources-current, list_variants-current instead of latest. Anything that read data.latest("<model>", "latest") or queried name == "latest" must use the new name.

Upgrade note: Data previously stored under latest is not migrated; re-run the method to populate the new name. No attribute schemas changed.

Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.

2026.09.18.1Sep 20, 2026

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.09.17.2Sep 17, 2026

2026.09.17.2

No changes to this extension's methods. Regenerated to refresh the shared _lib/api.ts helper library after PR #427 review fixes to cfApiPaginatedCursor (used by r2, kv, durable-objects, and workers-ai, but emitted into every extension's api.ts since it's part of the shared template).

2026.09.15.1Sep 15, 2026

2026.09.15.1

Changed: Bump zod 4.4.3 → 4.6.5

2026.08.28.2

Hardened codegen: instance names sanitized against path traversal; 429 rate-limit retry with Retry-After; string schema patterns emit regex validation; output schemas passthrough unknown fields; apiToken now optional and vault-wireable with CLOUDFLARE_API_TOKEN env fallback.

2026.08.28.2Aug 28, 2026

2026.08.28.2

2026.08.28.1Aug 28, 2026

2026.08.28.1

Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.

Upgrade note: License text only. No API, schema, or runtime behavior changed.

2026.08.26.2

Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry quality scorer can resolve dependencies and score the extension. An earlier release used a bare "zod" import-map specifier, which published but scored as unscored.

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.26.2Aug 27, 2026

2026.08.26.2

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.24.1Aug 24, 2026

2026.08.24.1

Added: Output metadata attributes for observability.

durationMs: Method execution duration in milliseconds.
collectedBy: Extension name that produced the data.
fetchedAt: ISO 8601 timestamp when data was fetched (added to resources that previously lacked it).

2026.08.21.2Aug 22, 2026

2026.08.21.2

Changed: Error messages for API failures and invalid input are now specific instead of generic.

Every method that calls the Cloudflare API now wraps failures with the operation attempted and the account/identifier involved (e.g. variant_id, image_id, migration_id, source_id), instead of surfacing the raw SDK error with no context.
Methods that take a signing_key_name, variant_id, image_id, migration_id, source_id, or sourceId now reject an empty value up front with a clear validation error, instead of sending a malformed request to the Cloudflare API.

Upgrade note: No behavioral change for valid requests. Callers passing an empty identifier will now get an immediate, descriptive validation error instead of a Cloudflare API failure.

2026.08.21.1Aug 21, 2026

2026.08.21.1

Fixed: Regenerated with three cloudflare-codegen fixes: (1) discriminated-union request bodies with a sibling top-level discriminator property (e.g. gateway proxy_endpoints kind) now correctly build the body from the full oneOf variant instead of silently dropping it to undefined; (2) DELETE methods with a request body (e.g. r2 delete_objects bulk-delete-by-list) now send that body instead of ignoring it; (3) oneOf/anyOf request body variants that are $ref (e.g. r2 sippy config) are now resolved to their real schema instead of collapsing to z.unknown(). Same generator fix as workers-scripts in #352, now caught up for these 7 services.

Changed: cloudflare_images_upload_an_image_via_url and create_authenticated_direct_upload_url_v_2 were removed — they are no longer present in the upstream Cloudflare API spec this extension is generated from.

Modified 1 behaviors

2026.07.27.1Jul 27, 2026

2026.07.27.1

Fixed: Regenerated from scripts/cloudflare-codegen after two generator bugs were repaired (webframp/swamp-extensions#284).

Methods referencing an undeclared path parameter did not compile. The generator derived a method's arguments schema and execute signature from the OpenAPI parameters list, but built the request URL from the path template. Where the Cloudflare spec omits a declaration for a {placeholder} — which it does in several places — the result was a method with arguments: z.object({}) and an unused _args parameter whose body still interpolated args.<name>. Those methods failed type checking and were uncallable even if they had compiled, because the argument was never declared. Path-template placeholders are now unioned into the declared parameters, so the schema, the signature, and the body agree.
Generated tests could request a URL the mock server did not serve. Test arguments merged the request-body fixture over the path-parameter values, so a body property sharing a name with a path parameter (commonly id) substituted its own example value into the URL. The request then missed the mock and failed with Cloudflare API error: Not found. Path parameters now take precedence, matching what the generated model already does by excluding path-parameter names from the request body.

Upgrade note: No API surface change and no method was added or removed. If this extension type-checked and tested cleanly before, its behavior is unchanged and only the version moved. Extensions that previously failed deno check or deno task test now pass.

2026.07.19.1Jul 19, 2026