Cloudflare/queues

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

01README

Cloudflare Queues — queue management, consumers, message operations

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.

Fixed: create_consumer wrote to a resource the model does not declare, so it always failed. It now writes the resource the model declares.

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, create_queues_push_message, create_queues_ack_messages, create_queues_push_messages, create_queues_preview_messages, create_queues_ack_preview_messages and 2 more.

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

03Behaviors1

@webframp/cloudflare/queuesv2026.10.21.1cloudflare/queues.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()

List Queues

fn create(queue_name: unknown)

Create Queue

Argument	Type	Required	Description
queue_name	unknown	yes

fn get(queue_id: string)

Get Queue

Argument	Type	Required	Description
queue_id	string	yes

fn update(queue_id: string, consumers?: array, consumers_total_count?: number, created_on?: string, modified_on?: string, producers?: array, producers_total_count?: number, queue_name?: unknown, settings?: unknown)

Update Queue

Argument	Type	Required
queue_id	string	yes
consumers?	array	no
consumers_total_count?	number	no
created_on?	string	no
modified_on?	string	no
producers?	array	no
producers_total_count?	number	no
queue_name?	unknown	no
settings?	unknown	no

fn update_partial(queue_id: string, consumers?: array, consumers_total_count?: number, created_on?: string, modified_on?: string, producers?: array, producers_total_count?: number, queue_name?: unknown, settings?: unknown)

Update Queue

Argument	Type	Required
queue_id	string	yes
consumers?	array	no
consumers_total_count?	number	no
created_on?	string	no
modified_on?	string	no
producers?	array	no
producers_total_count?	number	no
queue_name?	unknown	no
settings?	unknown	no

fn delete(queue_id: string)

Delete Queue

Argument	Type	Required	Description
queue_id	string	yes

fn list_consumers(queue_id: string)

List Queue Consumers

Argument	Type	Required	Description
queue_id	string	yes

fn create_consumer(queue_id: string, body: union)

Create a Queue Consumer

Argument	Type	Required	Description
queue_id	string	yes
body	union	yes	Request body for creating or updating a consumer

fn get_consumer(consumer_id: string, queue_id: string)

Get Queue Consumer

Argument	Type	Required	Description
consumer_id	string	yes
queue_id	string	yes

fn update_consumer(consumer_id: string, queue_id: string, body: union)

Update Queue Consumer

Argument	Type	Required	Description
consumer_id	string	yes
queue_id	string	yes
body	union	yes	Request body for creating or updating a consumer

fn delete_consumer(consumer_id: string, queue_id: string)

Delete Queue Consumer

Argument	Type	Required	Description
consumer_id	string	yes
queue_id	string	yes

fn create_queues_push_message(queue_id: string, delay_seconds?: number)

Push Message

Argument	Type	Required	Description
queue_id	string	yes
delay_seconds?	number	no	The number of seconds to wait for attempting to deliver this message to consu...

fn create_queues_ack_messages(queue_id: string, acks?: array, retries?: array)

Acknowledge + Retry Queue Messages

Argument	Type	Required
queue_id	string	yes
acks?	array	no
retries?	array	no

fn create_queues_push_messages(queue_id: string, delay_seconds?: number, messages?: array)

Push Message Batch

Argument	Type	Required	Description
queue_id	string	yes
delay_seconds?	number	no	The number of seconds to wait for attempting to deliver this batch to consumers
messages?	array	no

fn create_queues_preview_messages(queue_id: string, batch_size?: unknown)

Preview Queue Messages

Argument	Type	Required	Description
queue_id	string	yes
batch_size?	unknown	no

fn create_queues_ack_preview_messages(queue_id: string, acks?: array, retries?: array)

Delete Previewed Queue Messages

Argument	Type	Required
queue_id	string	yes
acks?	array	no
retries?	array	no

fn create_queues_pull_messages(queue_id: string, batch_size?: unknown, visibility_timeout_ms?: unknown)

Pull Queue Messages

Argument	Type	Required
queue_id	string	yes
batch_size?	unknown	no
visibility_timeout_ms?	unknown	no

fn get_metrics(queue_id: string)

Get Queue Metrics

Argument	Type	Required	Description
queue_id	string	yes

fn create_queues_purge(queue_id: string, delete_messages_permanently?: boolean)

Purge Queue

Argument	Type	Required	Description
queue_id	string	yes
delete_messages_permanently?	boolean	no	Confimation that all messages will be deleted permanently.

Resources

list(infinite)— List Queues

create(infinite)— Create Queue

get(infinite)— Get Queue

update(infinite)— Update Queue

partial(infinite)— Update Queue

consumers(infinite)— List Queue Consumers

consumer(infinite)— Create a Queue Consumer

queues_push_message(infinite)— Push Message

queues_ack_messages(infinite)— Acknowledge + Retry Queue Messages

queues_push_messages(infinite)— Push Message Batch

queues_preview_messages(infinite)— Preview Queue Messages

queues_ack_preview_messages(infinite)— Delete Previewed Queue Messages

queues_pull_messages(infinite)— Pull Queue Messages

metrics(infinite)— Get Queue Metrics

queues_purge(infinite)— Purge Queue

04Previous Versions13

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 create_consumer-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

updated labels

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.25.1Aug 26, 2026

2026.08.25.1

Changed: Updated labels for improved extension discoverability. Added cross-cutting category labels (security, observability, finops, infrastructure, networking, compliance, devops, ai, incident-response) where applicable.

updated labels

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:

Errors raised when a Cloudflare API call fails now name the HTTP method and path that was attempted (e.g. Cloudflare API POST /accounts/.../queues/xxx/messages/ack 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.
create_queues_ack_messages and create_queues_ack_preview_messages now reject requests where both acks and retries are empty, since such a request has no effect on the queue.
create_queues_push_messages now rejects an empty messages array before making a request, instead of sending a no-op batch to Cloudflare.

No breaking changes. Existing calls that already supplied at least one ack, retry, or message are unaffected.

2026.08.21.1Aug 21, 2026

2026.08.21.1

Changed: Added .describe() and .min(1) to the queue_id and consumer_id identifier arguments used across most methods. No behavioral changes.

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.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.