Cloudflare/r2

@webframp/cloudflare/r2v2026.09.18.1· 17d agoMODELS

01README

Cloudflare R2 object storage — buckets, objects, multipart uploads, notifications

02Release Notes

2026.09.18.1

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

03Models1

@webframp/cloudflare/r2v2026.09.18.1cloudflare/r2.ts

Global Arguments

Argument	Type	Required	Description
apiToken?	string	no	Cloudflare API token; overrides the CLOUDFLARE_API_TOKEN environment variable. Wire with a vault.get(...) expression to source it from a vault.
accountId	string	yes	Cloudflare account ID

fn list_catalogs()

List R2 catalogs

fn get_catalog_details(bucket_name: string)

Get R2 catalog details

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn create_store_credentials(bucket_name: string, token: string)

Store catalog credentials

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
token	string	yes	Provides the Cloudflare API token for accessing R2.

fn disable_catalog(bucket_name: string)

Disable R2 catalog

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name to disable as catalog.

fn enable_catalog(bucket_name: string)

Enable R2 bucket as a catalog

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name to enable as catalog.

fn get_maintenance_config(bucket_name: string)

Get catalog maintenance configuration

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn update_maintenance_config(bucket_name: string, compaction?: unknown, snapshot_expiration?: unknown)

Update catalog maintenance configuration

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
compaction?	unknown	no
snapshot_expiration?	unknown	no

fn list_namespaces(bucket_name: string, page_token?: string, page_size?: number, parent?: string, return_uuids?: boolean, return_details?: boolean)

List namespaces in catalog

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
page_token?	string	no	Opaque pagination token from a previous response. Use this to fetch the next page of results.
page_size?	number	no	Maximum number of namespaces to return per page. Defaults to 100, maximum 1000.
parent?	string	no	Parent namespace to filter by. Only returns direct children of this namespace. For nested namespaces, use %1F as separator (e.g., "bronze%1Fanalytics"). Omit this parameter to list top-level namespaces.
return_uuids?	boolean	no	Whether to include namespace UUIDs in the response. Set to true to receive the namespace_uuids array.
return_details?	boolean	no	Whether to include additional metadata (timestamps). When true, response includes created_at and updated_at arrays.

fn list_tables(bucket_name: string, namespace: string, page_token?: string, page_size?: number, return_uuids?: boolean, return_details?: boolean)

List tables in namespace

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
namespace	string	yes	The namespace identifier. For nested namespaces, use %1F as separator (e.g., "bronze%1Fanalytics").
page_token?	string	no	Opaque pagination token from a previous response. Use this to fetch the next page of results.
page_size?	number	no	Maximum number of tables to return per page. Defaults to 100, maximum 1000.
return_uuids?	boolean	no	Whether to include table UUIDs in the response. Set to true to receive the table_uuids array.
return_details?	boolean	no	Whether to include additional metadata (timestamps, locations). When true, response includes created_at, updated_at, metadata_locations, and locations arrays.

fn get_table(bucket_name: string, namespace: string, table_name: string)

Get table details

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
namespace	string	yes	The namespace identifier. For nested namespaces, use %1F as separator (e.g., "bronze%1Fanalytics").
table_name	string	yes	The table name within the given namespace.

fn get_table_maintenance_config(bucket_name: string, namespace: string, table_name: string)

Get table maintenance configuration

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
namespace	string	yes	The namespace identifier (use %1F as separator for nested namespaces).
table_name	string	yes	The table name.

fn update_table_maintenance_config(bucket_name: string, namespace: string, table_name: string, compaction?: unknown, snapshot_expiration?: unknown)

Update table maintenance configuration

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
namespace	string	yes	The namespace identifier (use %1F as separator for nested namespaces).
table_name	string	yes	The table name.
compaction?	unknown	no
snapshot_expiration?	unknown	no

fn list_buckets(name_contains?: string, start_after?: string, per_page?: number, order?: enum, direction?: enum, cursor?: string)

List Buckets

Argument	Type	Required
name_contains?	string	no
start_after?	string	no
per_page?	number	no
order?	enum	no
direction?	enum	no
cursor?	string	no

fn create_bucket(locationHint?: unknown, name: unknown, storageClass?: unknown)

Create Bucket

Argument	Type	Required
locationHint?	unknown	no
name	unknown	yes
storageClass?	unknown	no

fn get_bucket(bucket_name: string)

Get Bucket

Argument	Type	Required	Description
bucket_name	string	yes

fn patch_bucket(bucket_name: string)

Patch Bucket

Argument	Type	Required	Description
bucket_name	string	yes

fn delete_bucket(bucket_name: string)

Delete Bucket

Argument	Type	Required	Description
bucket_name	string	yes

fn get_bucket_cors_policy(bucket_name: string)

Get Bucket CORS Policy

Argument	Type	Required	Description
bucket_name	string	yes

fn put_bucket_cors_policy(bucket_name: string, rules?: array)

Put Bucket CORS Policy

Argument	Type	Required	Description
bucket_name	string	yes
rules?	array	no

fn delete_bucket_cors_policy(bucket_name: string)

Delete Bucket CORS Policy

Argument	Type	Required	Description
bucket_name	string	yes

fn list_custom_domains(bucket_name: string)

List Custom Domains of Bucket

Argument	Type	Required	Description
bucket_name	string	yes

fn create_r2_add_custom_domain(bucket_name: string, ciphers?: array, domain: string, enabled: boolean, minTLS?: enum, zoneId: string)

Attach Custom Domain To Bucket

Argument	Type	Required	Description
bucket_name	string	yes
ciphers?	array	no	An allowlist of ciphers for TLS termination. These ciphers must be in the Bor...
domain	string	yes	Name of the custom domain to be added.
enabled	boolean	yes	Whether to enable public bucket access at the custom domain. If undefined, th...
minTLS?	enum	no	Minimum TLS Version the custom domain will accept for incoming connections. I...
zoneId	string	yes	Zone ID of the custom domain.

fn get_custom_domain_settings(bucket_name: string, domain: string)

Get Custom Domain Settings

Argument	Type	Required	Description
bucket_name	string	yes
domain	string	yes

fn update_r2_edit_custom_domain_settings(bucket_name: string, domain: string, ciphers?: array, enabled?: boolean, minTLS?: enum)

Configure Custom Domain Settings

Argument	Type	Required	Description
bucket_name	string	yes
domain	string	yes
ciphers?	array	no	An allowlist of ciphers for TLS termination. These ciphers must be in the Bor...
enabled?	boolean	no	Whether to enable public bucket access at the specified custom domain.
minTLS?	enum	no	Minimum TLS Version the custom domain will accept for incoming connections. I...

fn delete_custom_domain(bucket_name: string, domain: string)

Remove Custom Domain From Bucket

Argument	Type	Required	Description
bucket_name	string	yes
domain	string	yes

fn get_bucket_public_policy(bucket_name: string)

Get r2.dev Domain of Bucket

Argument	Type	Required	Description
bucket_name	string	yes

fn put_bucket_public_policy(bucket_name: string, enabled: boolean)

Update r2.dev Domain of Bucket

Argument	Type	Required	Description
bucket_name	string	yes
enabled	boolean	yes	Whether to enable public bucket access at the r2.dev domain.

fn get_bucket_lifecycle_configuration(bucket_name: string)

Get Object Lifecycle Rules

Argument	Type	Required	Description
bucket_name	string	yes

fn put_bucket_lifecycle_configuration(bucket_name: string, rules?: array)

Put Object Lifecycle Rules

Argument	Type	Required	Description
bucket_name	string	yes
rules?	array	no

fn get_bucket_local_uploads_configuration(bucket_name: string)

Get Local Uploads Configuration

Argument	Type	Required	Description
bucket_name	string	yes

fn put_bucket_local_uploads_configuration(bucket_name: string, enabled: boolean)

Put Local Uploads Configuration

Argument	Type	Required	Description
bucket_name	string	yes
enabled	boolean	yes	Whether to enable local uploads for this bucket.

fn get_bucket_lock_configuration(bucket_name: string)

Get Bucket Lock Rules

Argument	Type	Required	Description
bucket_name	string	yes

fn put_bucket_lock_configuration(bucket_name: string, rules?: array)

Put Bucket Lock Rules

Argument	Type	Required	Description
bucket_name	string	yes
rules?	array	no

fn list_objects(bucket_name: string, per_page?: number, prefix?: string, delimiter?: string, cursor?: string, start_after?: string)

List Objects

Argument	Type	Required
bucket_name	string	yes
per_page?	number	no
prefix?	string	no
delimiter?	string	no
cursor?	string	no
start_after?	string	no

fn delete_objects(bucket_name: string, prefix?: string, items: array)

Delete Objects

Argument	Type	Required
bucket_name	string	yes
prefix?	string	no
items	array	yes

fn delete_object(bucket_name: string, object_key: string)

Delete Object

Argument	Type	Required	Description
bucket_name	string	yes
object_key	string	yes

fn get_bucket_sippy_config(bucket_name: string)

Get Sippy Configuration

Argument	Type	Required	Description
bucket_name	string	yes

fn put_bucket_sippy_config(bucket_name: string, body: union)

Enable Sippy

Argument	Type	Required	Description
bucket_name	string	yes
body	union	yes

fn delete_bucket_sippy_config(bucket_name: string)

Disable Sippy

Argument	Type	Required	Description
bucket_name	string	yes

fn get_account_level_metrics()

Get Account-Level Metrics

fn create_temp_access_credentials(bucket: string, objects?: array, parentAccessKeyId: string, permission: enum, prefixes?: array, ttlSeconds: number)

Create Temporary Access Credentials

Argument	Type	Required	Description
bucket	string	yes	Name of the R2 bucket.
objects?	array	no	Optional object paths to scope the credentials to.
parentAccessKeyId	string	yes	The parent access key id to use for signing.
permission	enum	yes	Permissions allowed on the credentials.
prefixes?	array	no	Optional prefix paths to scope the credentials to.
ttlSeconds	number	yes	How long the credentials will live for in seconds.

Resources

list_catalogs(infinite)— List R2 catalogs

catalog_details(infinite)— Get R2 catalog details

store_credentials(infinite)— Store catalog credentials

disable_catalog(infinite)— Disable R2 catalog

enable_catalog(infinite)— Enable R2 bucket as a catalog

maintenance_config(infinite)— Get catalog maintenance configuration

list_namespaces(infinite)— List namespaces in catalog

list_tables(infinite)— List tables in namespace

table(infinite)— Get table details

table_maintenance_config(infinite)— Get table maintenance configuration

list_buckets(infinite)— List Buckets

bucket(infinite)— Create Bucket

patch_bucket(infinite)— Patch Bucket

bucket_cors_policy(infinite)— Get Bucket CORS Policy

put_bucket_cors_policy(infinite)— Put Bucket CORS Policy

list_custom_domains(infinite)— List Custom Domains of Bucket

r2_add_custom_domain(infinite)— Attach Custom Domain To Bucket

custom_domain_settings(infinite)— Get Custom Domain Settings

r2_edit_custom_domain_settings(infinite)— Configure Custom Domain Settings

bucket_public_policy(infinite)— Get r2.dev Domain of Bucket

put_bucket_public_policy(infinite)— Update r2.dev Domain of Bucket

bucket_lifecycle_configuration(infinite)— Get Object Lifecycle Rules

put_bucket_lifecycle_configuration(infinite)— Put Object Lifecycle Rules

bucket_local_uploads_configuration(infinite)— Get Local Uploads Configuration

put_bucket_local_uploads_configuration(infinite)— Put Local Uploads Configuration

bucket_lock_configuration(infinite)— Get Bucket Lock Rules

put_bucket_lock_configuration(infinite)— Put Bucket Lock Rules

objects(infinite)— List Objects

bucket_sippy_config(infinite)— Get Sippy Configuration

put_bucket_sippy_config(infinite)— Enable Sippy

account_level_metrics(infinite)— Get Account-Level Metrics

temp_access_credentials(infinite)— Create Temporary Access Credentials

04Previous Versions11

2026.09.17.2Sep 17, 2026

2026.09.17.2

Adversarial review on PR #427 found: (1) a user-supplied cursor argument was silently discarded (excluded from the params passed to cfApiPaginatedCursor, so resuming from a prior truncated result always re-fetched from page one instead); (2) cfApiPaginatedCursor claimed truncated: false when a response had no result_info at all, which could silently under-report results on endpoints that omit that field. Both are fixed: a caller-supplied cursor now flows through as the starting point, and a missing result_info now marks truncated: true instead of claiming completeness. Also fixed a trailing '?' on URLs with no query params.

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.

Added 1, removed 1 models

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.3Aug 22, 2026

2026.08.21.3

Changed:

Errors raised when a Cloudflare API call fails now name the HTTP method and path that was attempted (e.g. Cloudflare API GET /accounts/.../r2-catalog/xxx/namespaces/yyy/tables failed with HTTP 400 ...) instead of a bare Cloudflare API error: .... Network-level failures (DNS, connection reset, timeout) are now also caught and wrapped with the same operation context instead of surfacing a raw fetch error.
disable_catalog, enable_catalog, list_tables, get_table, get_table_maintenance_config, and update_table_maintenance_config now reject an empty bucket_name, namespace, or table_name before making a request. Previously these identifiers were validated on some R2 catalog methods but not others, so an empty value on the unvalidated ones would fail deep inside the Cloudflare API call with a less specific error.
list_namespaces and list_tables now enforce the documented page_size bounds (1 to 1000) at the schema level, instead of letting an out-of-range value fail inside the Cloudflare API call.

No breaking changes. Existing calls that already supplied non-empty identifiers and in-range page sizes are unaffected.

2026.08.21.2Aug 21, 2026

2026.08.21.2

Changed: Added .describe() and .min(1) to previously undocumented bucket_name, domain, and object_key method arguments. No behavioral changes.

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: put_object was removed — it is no longer present in the upstream Cloudflare API spec this extension is generated from.

2026.08.21.1Aug 21, 2026

2026.08.21.1

Changed: put_object was removed — it is no longer present in the upstream Cloudflare API spec this extension is generated from.

Modified 1 models

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