@pithy-sh/cloudflare 0.1.2 → 0.1.4

package/dist/media/ownership.js

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareNotConfiguredError } from "../client/errors.js";
+//#region src/media/ownership.ts
+/**
+* The ownership stamp on every Cloudflare Images and Stream asset Pithy creates.
+*
+* Every other resource this toolset provisions is isolated by its **name** —
+* `<project>-<env>-<thing>`, because those namespaces are flat and account-wide (CLAUDE.md
+* §Resource naming). Images and Stream cannot use that lever: their stores are just as flat and
+* account-wide, but an asset is keyed by a **Cloudflare-minted id**, not by a name we choose. So
+* metadata is the only place ownership can live, and without it two projects' assets in one account
+* are indistinguishable — you cannot tell which app owns an asset, cannot sweep one app's assets at
+* teardown, and `pithy doctor` is blind to them.
+*
+* The **same two keys** are used for both stores (Images `metadata`, Stream `meta`), so one query
+* answers "what does this project own" across them rather than two dialects answering half each.
+* Nothing else is imposed: a caller's own metadata rides along untouched — but it can never displace
+* the reserved keys, which are merged last on purpose.
+*/
+/** The metadata key naming the owning project — the root `pithy.config.ts` `name`. */
+const ASSET_PROJECT_KEY = "pithyProject";
+/** The metadata key naming the owning environment (`dev` | `staging` | `production`). */
+const ASSET_ENV_KEY = "pithyEnv";
+/**
+* Merge the ownership stamp over a caller's metadata bag.
+*
+* Ownership is applied **last**, so a caller-supplied `pithyProject`/`pithyEnv` cannot displace the
+* real one — a fixture or a client-supplied bag claiming another project's assets would defeat the
+* whole point of the stamp. A blank project or environment is refused rather than written: an asset
+* stamped with an empty string reads as owned and still sweeps to nothing.
+*/
+function withAssetOwnership(owner, metadata) {
+	const project = owner.project.trim();
+	const env = owner.env.trim();
+	if (!project || !env) throw new CloudflareNotConfiguredError({
+		message: "A Cloudflare Images or Stream asset cannot be created without an owner.",
+		action: "Pass the project (requireProjectName) and the environment to the uploader.",
+		detail: `asset owner is incomplete: project="${owner.project}", env="${owner.env}"`
+	});
+	return {
+		...metadata,
+		[ASSET_PROJECT_KEY]: project,
+		[ASSET_ENV_KEY]: env
+	};
+}
+//#endregion
+export { ASSET_ENV_KEY, ASSET_PROJECT_KEY, withAssetOwnership };

package/dist/media/streamManager.d.ts

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { DirectUploadCreateParams, DirectUploadCreateResponse } from "cloudflare/resources/stream/direct-upload";
+import type { StreamEditParams, Video } from "cloudflare/resources/stream/stream";
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+/**
+ * One download artifact's state, as returned by the Stream downloads API. The SDK types these
+ * responses as `unknown`, so this Zod object is the validated shape — it is the JS↔wire boundary
+ * for the raw downloads payloads.
+ */
+export declare const DownloadEntry: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        inprogress: "inprogress";
+        ready: "ready";
+    }>>;
+    url: z.ZodOptional<z.ZodString>;
+    percentComplete: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type DownloadEntry = z.infer<typeof DownloadEntry>;
+/**
+ * The Stream downloads payload: the default (MP4) artifact, plus an optional audio-only (M4A) one.
+ * `GET /downloads` returns every type; `POST /downloads/{type}` returns just that type.
+ */
+export declare const StreamDownloadStatus: z.ZodObject<{
+    default: z.ZodObject<{
+        status: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            inprogress: "inprogress";
+            ready: "ready";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        percentComplete: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    audio: z.ZodOptional<z.ZodObject<{
+        status: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            inprogress: "inprogress";
+            ready: "ready";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        percentComplete: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type StreamDownloadStatus = z.infer<typeof StreamDownloadStatus>;
+/**
+ * Out-of-Worker Cloudflare Stream access over the REST API: delete, fetch, edit, direct uploads,
+ * and download (MP4 + audio-only) management from a CLI/CI/provisioning context. Video metadata is
+ * the SDK's own `Video` shape — this class imposes none of its own.
+ *
+ * The ownership stamp is imposed one layer up, by `withAssetOwnership` in `ownership.ts`, which every
+ * Pithy path that *creates* a video goes through (the seeder here, and media's `videoMinter`). Stream
+ * is account-flat and keys a video by a Cloudflare-minted uid, so `meta.pithyProject` is the only
+ * thing that says which project owns it.
+ */
+export declare class CloudflareStreamManager extends CloudflareManager {
+    /** Delete a video by its Stream UID. */
+    deleteVideo(videoId: string): Promise<void>;
+    /** Fetch a video's details by UID. */
+    getVideoDetails(videoId: string): Promise<Video>;
+    /** Update a video's metadata and settings. */
+    updateVideo(videoId: string, params: Omit<StreamEditParams, "account_id">): Promise<Video>;
+    /** Read the download status for a video (all artifact types). */
+    videoDownloadStatus(videoId: string): Promise<StreamDownloadStatus>;
+    /** Trigger Cloudflare to generate a downloadable MP4 for a video. */
+    createVideoDownload(videoId: string): Promise<StreamDownloadStatus>;
+    /**
+     * Request an audio-only (M4A) download for a video. The CF Node SDK does not expose the
+     * type-specific `POST /downloads/audio` endpoint, so this falls back to a direct `fetch` — the
+     * documented escape hatch — authenticated with the manager's API token.
+     */
+    createAudioDownload(videoId: string): Promise<DownloadEntry>;
+    /**
+     * Read the audio-download status for a video. The SDK has no standalone `GET /downloads/audio`,
+     * so this reads the generic downloads endpoint and extracts the `audio` entry.
+     */
+    audioDownloadStatus(videoId: string): Promise<DownloadEntry>;
+    /** Create a direct-upload URL for a client-side video upload. */
+    createDirectUpload(params: Omit<DirectUploadCreateParams, "account_id">): Promise<DirectUploadCreateResponse>;
+    getServiceType(): string;
+    /** Prove access by listing videos. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+}
+//# sourceMappingURL=streamManager.d.ts.map

package/dist/media/streamManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamManager.d.ts","sourceRoot":"","sources":["../../src/media/streamManager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AACtH,OAAO,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,oCAAoC,CAAC;AAClF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAWtD;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;iBAM8C,CAAC;AACzE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;iBAKwD,CAAC;AAC1F,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AA2BxE;;;;;;;;;GASG;AACH,qBAAa,uBAAwB,SAAQ,iBAAiB;IAC5D,wCAAwC;IAClC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhD;IAED,sCAAsC;IAChC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAIrD;IAED,8CAA8C;IACxC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAI/F;IAED,iEAAiE;IAC3D,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CASxE;IAED,qEAAqE;IAC/D,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CASxE;IAED;;;;OAIG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA4BjE;IAED;;;OAGG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAUjE;IAED,iEAAiE;IAC3D,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAIlH;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,oDAAoD;IAC9C,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}

package/dist/media/streamManager.js

@@ -0,0 +1,147 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
+//#region src/media/streamManager.ts
+/**
+* Per-request CF SDK options for every Stream call: a 10s timeout and up to 3 retries — the same
+* generous envelope the Images manager uses, since video operations can be slow.
+*/
+const requestOptions = {
+	timeout: 1e4,
+	maxRetries: 3
+};
+/**
+* One download artifact's state, as returned by the Stream downloads API. The SDK types these
+* responses as `unknown`, so this Zod object is the validated shape — it is the JS↔wire boundary
+* for the raw downloads payloads.
+*/
+const DownloadEntry = z.object({
+	status: z.enum([
+		"error",
+		"inprogress",
+		"ready"
+	]).optional().describe("Where this download is in its lifecycle."),
+	url: z.string().optional().describe("The download URL, present once the artifact is ready."),
+	percentComplete: z.number().optional().describe("Generation progress, 0–100, while in progress.")
+}).describe("The state of one Stream download artifact (MP4 or audio).");
+/**
+* The Stream downloads payload: the default (MP4) artifact, plus an optional audio-only (M4A) one.
+* `GET /downloads` returns every type; `POST /downloads/{type}` returns just that type.
+*/
+const StreamDownloadStatus = z.object({
+	default: DownloadEntry.describe("The default MP4 download artifact."),
+	audio: DownloadEntry.optional().describe("The audio-only (M4A) download artifact, when requested.")
+}).describe("The set of download artifacts Cloudflare Stream has generated for a video.");
+/** The envelope the raw audio-download endpoint returns: `{ result: { audio } }`. */
+const AudioDownloadEnvelope = z.object({ result: z.object({ audio: DownloadEntry.describe("The audio-only download artifact.") }).describe("The CF API result wrapper for the audio download.") }).describe("The raw `POST /downloads/audio` response envelope.");
+/**
+* Validate a raw downloads payload against `StreamDownloadStatus`, mapping a Zod failure to a
+* `CloudflareInvalidResponseError` (the response did not match its expected shape) rather than
+* letting it surface as a generic request failure.
+*/
+function parseDownloadStatus(response) {
+	const result = StreamDownloadStatus.safeParse(response);
+	if (!result.success) throw new CloudflareInvalidResponseError({
+		message: "A Stream downloads response had an unexpected shape.",
+		detail: result.error.message
+	});
+	return result.data;
+}
+/**
+* Out-of-Worker Cloudflare Stream access over the REST API: delete, fetch, edit, direct uploads,
+* and download (MP4 + audio-only) management from a CLI/CI/provisioning context. Video metadata is
+* the SDK's own `Video` shape — this class imposes none of its own.
+*
+* The ownership stamp is imposed one layer up, by `withAssetOwnership` in `ownership.ts`, which every
+* Pithy path that *creates* a video goes through (the seeder here, and media's `videoMinter`). Stream
+* is account-flat and keys a video by a Cloudflare-minted uid, so `meta.pithyProject` is the only
+* thing that says which project owns it.
+*/
+var CloudflareStreamManager = class extends CloudflareManager {
+	/** Delete a video by its Stream UID. */
+	async deleteVideo(videoId) {
+		await cloudflareRequest(`Stream delete '${videoId}'`, () => this.getClient().stream.delete(videoId, { account_id: this.accountId }, requestOptions));
+	}
+	/** Fetch a video's details by UID. */
+	async getVideoDetails(videoId) {
+		return cloudflareRequest(`Stream get details for '${videoId}'`, () => this.getClient().stream.get(videoId, { account_id: this.accountId }, requestOptions));
+	}
+	/** Update a video's metadata and settings. */
+	async updateVideo(videoId, params) {
+		return cloudflareRequest(`Stream update '${videoId}'`, () => this.getClient().stream.edit(videoId, {
+			account_id: this.accountId,
+			...params
+		}, requestOptions));
+	}
+	/** Read the download status for a video (all artifact types). */
+	async videoDownloadStatus(videoId) {
+		return cloudflareRequest(`Stream download status for '${videoId}'`, async () => {
+			return parseDownloadStatus(await this.getClient().stream.downloads.get(videoId, { account_id: this.accountId }, requestOptions));
+		});
+	}
+	/** Trigger Cloudflare to generate a downloadable MP4 for a video. */
+	async createVideoDownload(videoId) {
+		return cloudflareRequest(`Stream create download for '${videoId}'`, async () => {
+			return parseDownloadStatus(await this.getClient().stream.downloads.create(videoId, { account_id: this.accountId }, requestOptions));
+		});
+	}
+	/**
+	* Request an audio-only (M4A) download for a video. The CF Node SDK does not expose the
+	* type-specific `POST /downloads/audio` endpoint, so this falls back to a direct `fetch` — the
+	* documented escape hatch — authenticated with the manager's API token.
+	*/
+	async createAudioDownload(videoId) {
+		return cloudflareRequest(`Stream create audio download for '${videoId}'`, async () => {
+			const response = await fetch(`https://api.cloudflare.com/client/v4/accounts/${this.accountId}/stream/${videoId}/downloads/audio`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${this.getApiToken()}`,
+					"Content-Type": "application/json"
+				}
+			});
+			if (!response.ok) throw new CloudflareInvalidResponseError({
+				message: "The Stream audio-download request failed.",
+				detail: `Stream audio download returned ${response.status}: ${await response.text()}`
+			});
+			const json = await response.json();
+			const envelope = AudioDownloadEnvelope.safeParse(json);
+			if (!envelope.success) throw new CloudflareInvalidResponseError({
+				message: "The Stream audio-download response had an unexpected shape.",
+				detail: envelope.error.message
+			});
+			return envelope.data.result.audio;
+		});
+	}
+	/**
+	* Read the audio-download status for a video. The SDK has no standalone `GET /downloads/audio`,
+	* so this reads the generic downloads endpoint and extracts the `audio` entry.
+	*/
+	async audioDownloadStatus(videoId) {
+		return cloudflareRequest(`Stream audio download status for '${videoId}'`, async () => {
+			return parseDownloadStatus(await this.getClient().stream.downloads.get(videoId, { account_id: this.accountId }, requestOptions)).audio ?? {};
+		});
+	}
+	/** Create a direct-upload URL for a client-side video upload. */
+	async createDirectUpload(params) {
+		return cloudflareRequest("Stream create direct upload", () => this.getClient().stream.directUpload.create({
+			account_id: this.accountId,
+			...params
+		}, requestOptions));
+	}
+	getServiceType() {
+		return "Cloudflare Stream";
+	}
+	/** Prove access by listing videos. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.getClient().stream.list({ account_id: this.accountId });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { CloudflareStreamManager, DownloadEntry, StreamDownloadStatus };

package/dist/queue/queueManager.d.ts

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { MessageBulkPushResponse } from "cloudflare/resources/queues/messages";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+/** Config for the Queue manager: the shared client config plus the queue it targets by name. */
+export interface QueueManagerConfig extends CloudflareManagerConfig {
+    /**
+     * The queue name. The REST API addresses queues by id, so the manager resolves this name to an
+     * id once (and caches it). Required for every operation.
+     */
+    queueName: string;
+}
+/** The per-batch outcome of a `sendBatches` run: a partial-failure report, never a thrown batch. */
+export interface QueueBatchResult {
+    /** The caller-supplied number identifying this batch. */
+    batchNumber: number;
+    /** Whether the batch was sent. */
+    success: boolean;
+    /** The failure reason, present only when `success` is false. */
+    error?: string;
+    /** How many messages the batch carried. */
+    messageCount: number;
+}
+/** The aggregate result of a `sendBatches` run. */
+export interface SendBatchesResult {
+    /** How many batches sent successfully. */
+    successCount: number;
+    /** How many batches failed. */
+    failureCount: number;
+    /** The per-batch outcomes, in input order (truncated if a non-continuing run stopped early). */
+    results: QueueBatchResult[];
+}
+/** One batch of messages to send, with bookkeeping for progress reporting. */
+export interface QueueBatch<T> {
+    /** A number identifying this batch in callbacks and results. */
+    batchNumber: number;
+    /** How many messages the batch carries (for progress reporting; need not equal `messages.length`). */
+    messageCount: number;
+    /** The message bodies to enqueue. */
+    messages: T[];
+}
+/** Options governing a `sendBatches` run. Callbacks are pure reporting hooks — no I/O is built in. */
+export interface SendBatchesOptions {
+    /** Called before each batch is sent. */
+    onProgress?: (batchNumber: number, totalBatches: number, messageCount: number) => void;
+    /** Called after a batch sends successfully. */
+    onSuccess?: (batchNumber: number, messageCount: number) => void;
+    /** Called when a batch fails. */
+    onError?: (batchNumber: number, error: string) => void;
+    /** Milliseconds to wait between batches. Defaults to 0 (no delay). */
+    delayBetweenBatches?: number;
+    /** Keep going after a batch fails (collecting results). When false, the first failure throws. */
+    continueOnError?: boolean;
+}
+/**
+ * Out-of-Worker Cloudflare Queues access over the REST API: resolve a queue by name and bulk-push
+ * messages from a CLI/CI/provisioning context. Inside a Worker you use the `Queue` binding directly
+ * — this manager is the REST counterpart, addressed by queue id (resolved from the name).
+ */
+export declare class CloudflareQueueManager extends CloudflareManager {
+    private readonly queueName;
+    private queueId?;
+    constructor(config: QueueManagerConfig);
+    /** Resolve (and cache) the queue id for the configured name by listing the account's queues. */
+    getQueueId(): Promise<string>;
+    /** Bulk-push a batch of message bodies to the queue. Each item becomes one queue message. */
+    sendBatch<T>(messages: T[]): Promise<MessageBulkPushResponse>;
+    /** Send a single message. Convenience wrapper over `sendBatch`. */
+    send<T>(message: T): Promise<void>;
+    /**
+     * Send many batches in sequence, collecting a per-batch result. By default it continues past a
+     * failed batch (reporting it) rather than aborting; set `continueOnError: false` to throw on the
+     * first failure. Optional callbacks are pure reporting hooks; nothing is logged or prompted.
+     */
+    sendBatches<T>(batches: QueueBatch<T>[], options?: SendBatchesOptions): Promise<SendBatchesResult>;
+    /** The queue this manager targets, the account it lives in, and the resolved id (once known). */
+    getQueueInfo(): {
+        queueName: string;
+        accountId: string;
+        queueId?: string;
+    };
+    getServiceType(): string;
+    /** Prove access by listing the account's queues. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+}
+//# sourceMappingURL=queueManager.d.ts.map

package/dist/queue/queueManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queueManager.d.ts","sourceRoot":"","sources":["../../src/queue/queueManager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAEpF,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEpF,gGAAgG;AAChG,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IACjE;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,oGAAoG;AACpG,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,gGAAgG;IAChG,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,8EAA8E;AAC9E,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,sGAAsG;IACtG,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,EAAE,CAAC,EAAE,CAAC;CACf;AAED,sGAAsG;AACtG,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IACvF,+CAA+C;IAC/C,SAAS,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IAChE,iCAAiC;IACjC,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD,sEAAsE;IACtE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iGAAiG;IACjG,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,iBAAiB;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,OAAO,CAAC,OAAO,CAAC,CAAS;IAEzB,YAAY,MAAM,EAAE,kBAAkB,EAMrC;IAED,gGAAgG;IAC1F,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAoBlC;IAED,6FAA6F;IACvF,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAUlE;IAED,mEAAmE;IAC7D,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvC;IAED;;;;OAIG;IACG,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqC3G;IAED,iGAAiG;IACjG,YAAY,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAEzE;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,kEAAkE;IAC5D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}

package/dist/queue/queueManager.js

@@ -0,0 +1,116 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareNotConfiguredError, cloudflareRequest, reasonOf } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/queue/queueManager.ts
+/**
+* Out-of-Worker Cloudflare Queues access over the REST API: resolve a queue by name and bulk-push
+* messages from a CLI/CI/provisioning context. Inside a Worker you use the `Queue` binding directly
+* — this manager is the REST counterpart, addressed by queue id (resolved from the name).
+*/
+var CloudflareQueueManager = class extends CloudflareManager {
+	queueName;
+	queueId;
+	constructor(config) {
+		super(config);
+		if (!config.queueName) throw new CloudflareNotConfiguredError({ detail: "Missing queueName for Queue REST access." });
+		this.queueName = config.queueName;
+	}
+	/** Resolve (and cache) the queue id for the configured name by listing the account's queues. */
+	async getQueueId() {
+		if (this.queueId) return this.queueId;
+		const queues = await cloudflareRequest("list queues", async () => {
+			return (await this.getClient().queues.list({ account_id: this.accountId })).result;
+		});
+		const match = queues.find((queue) => queue.queue_name === this.queueName);
+		if (!match?.queue_id) {
+			const available = queues.map((queue) => queue.queue_name).join(", ");
+			throw new NotFoundError({
+				message: `Queue '${this.queueName}' not found.`,
+				detail: `Available queues: ${available || "(none)"}.`,
+				action: "Verify the queue name and that the API token has Queues access."
+			});
+		}
+		this.queueId = match.queue_id;
+		return this.queueId;
+	}
+	/** Bulk-push a batch of message bodies to the queue. Each item becomes one queue message. */
+	async sendBatch(messages) {
+		const queueId = await this.getQueueId();
+		return cloudflareRequest(`send batch of ${messages.length} message(s)`, async () => {
+			return await this.getClient().queues.messages.bulkPush(queueId, {
+				account_id: this.accountId,
+				messages: messages.map((body) => ({ body }))
+			});
+		});
+	}
+	/** Send a single message. Convenience wrapper over `sendBatch`. */
+	async send(message) {
+		await this.sendBatch([message]);
+	}
+	/**
+	* Send many batches in sequence, collecting a per-batch result. By default it continues past a
+	* failed batch (reporting it) rather than aborting; set `continueOnError: false` to throw on the
+	* first failure. Optional callbacks are pure reporting hooks; nothing is logged or prompted.
+	*/
+	async sendBatches(batches, options = {}) {
+		const { onProgress, onSuccess, onError, delayBetweenBatches = 0, continueOnError = true } = options;
+		await this.getQueueId();
+		let successCount = 0;
+		let failureCount = 0;
+		const results = [];
+		for (const batch of batches) {
+			onProgress?.(batch.batchNumber, batches.length, batch.messageCount);
+			try {
+				await this.sendBatch(batch.messages);
+				onSuccess?.(batch.batchNumber, batch.messageCount);
+				successCount++;
+				results.push({
+					batchNumber: batch.batchNumber,
+					success: true,
+					messageCount: batch.messageCount
+				});
+			} catch (error) {
+				const reason = reasonOf(error);
+				onError?.(batch.batchNumber, reason);
+				failureCount++;
+				results.push({
+					batchNumber: batch.batchNumber,
+					success: false,
+					error: reason,
+					messageCount: batch.messageCount
+				});
+				if (!continueOnError) throw error;
+			}
+			if (!(batch === batches[batches.length - 1]) && delayBetweenBatches > 0) await new Promise((resolve) => setTimeout(resolve, delayBetweenBatches));
+		}
+		return {
+			successCount,
+			failureCount,
+			results
+		};
+	}
+	/** The queue this manager targets, the account it lives in, and the resolved id (once known). */
+	getQueueInfo() {
+		return {
+			queueName: this.queueName,
+			accountId: this.accountId,
+			queueId: this.queueId
+		};
+	}
+	getServiceType() {
+		return "Queues";
+	}
+	/** Prove access by listing the account's queues. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.getClient().queues.list({ account_id: this.accountId });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { CloudflareQueueManager };

package/dist/r2/r2Credentials.d.ts

@@ -0,0 +1,14 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * The R2 S3-compatible credential pair. R2 speaks the S3 protocol, so presigned-URL signing needs
+ * an access-key/secret-key pair (distinct from the CF API token). This is the canonical shape —
+ * `@pithy-sh/secrets` validates the persisted credential envelope against it.
+ */
+export declare const R2Credentials: z.ZodObject<{
+    accessKeyId: z.ZodString;
+    secretAccessKey: z.ZodString;
+}, z.core.$strip>;
+export type R2Credentials = z.infer<typeof R2Credentials>;
+//# sourceMappingURL=r2Credentials.d.ts.map

package/dist/r2/r2Credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2Credentials.d.ts","sourceRoot":"","sources":["../../src/r2/r2Credentials.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;iBAKiE,CAAC;AAC5F,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/r2/r2Credentials.js

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+//#region src/r2/r2Credentials.ts
+/**
+* The R2 S3-compatible credential pair. R2 speaks the S3 protocol, so presigned-URL signing needs
+* an access-key/secret-key pair (distinct from the CF API token). This is the canonical shape —
+* `@pithy-sh/secrets` validates the persisted credential envelope against it.
+*/
+const R2Credentials = z.object({
+	accessKeyId: z.string().min(1).describe("The R2 S3 access key id."),
+	secretAccessKey: z.string().min(1).describe("The R2 S3 secret access key. Never logged or serialized to clients.")
+}).describe("The S3-compatible access-key/secret-key pair R2 uses to sign presigned URLs.");
+//#endregion
+export { R2Credentials };