@pithy-sh/cloudflare 0.1.1 → 0.1.3

package/dist/kv/kvManager.d.ts

@@ -0,0 +1,76 @@
+import type { Key } from "cloudflare/resources/kv/namespaces/keys";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+/** Config for the KV manager: the shared client config plus the namespace it targets. */
+export interface KVManagerConfig extends CloudflareManagerConfig {
+    /** The KV namespace id (the REST API addresses namespaces by id, not binding name). */
+    namespaceId: string;
+}
+/** Options for a single KV write. TTL is explicit (CLAUDE.md §KV). */
+export interface KVPutOptions {
+    /** Seconds until the key expires. Omit for no expiry. */
+    expirationTtl?: number;
+    /** Arbitrary metadata stored alongside the value. */
+    metadata?: Record<string, unknown>;
+}
+/** One entry in a `batchSet` call. */
+export interface KVOperation {
+    /** The key to write. */
+    key: string;
+    /** The value to store. */
+    value: string;
+    /** Seconds until the key expires. */
+    expirationTtl?: number;
+    /** Metadata to store with the value. */
+    metadata?: Record<string, unknown>;
+}
+/** The per-key outcome of a `batchSet`: a partial-failure report, never a thrown batch. */
+export interface KVBatchResult {
+    /** The key this result is for. */
+    key: string;
+    /** Whether the write succeeded. */
+    success: boolean;
+    /** The failure reason, present only when `success` is false. */
+    error?: string;
+}
+/** A KV value together with its metadata, as returned by `getWithMetadata`. */
+export interface KVValueWithMetadata<M = unknown> {
+    /** The stored value, or null if the key is absent. */
+    value: string | null;
+    /** The stored metadata, or null if absent. */
+    metadata: M | null;
+}
+/**
+ * Out-of-Worker KV access over the REST API: namespace management and key reads/writes from a
+ * CLI/CI/provisioning context. Inside a Worker you use the `KVNamespace` binding directly — this
+ * manager is the REST counterpart, addressed by namespace id.
+ */
+export declare class CloudflareKVManager extends CloudflareManager {
+    private readonly namespaceId;
+    constructor(config: KVManagerConfig);
+    /** Read a key's value as text. Returns null when the key is absent (the API 404s a missing key). */
+    get(key: string): Promise<string | null>;
+    /** Read a key and `JSON.parse` it. Returns null when absent; throws on malformed JSON. */
+    getJson<T = unknown>(key: string): Promise<T | null>;
+    /** Write a value, with optional TTL and metadata. */
+    set(key: string, value: string, options?: KVPutOptions): Promise<void>;
+    /** Delete a key. */
+    delete(key: string): Promise<void>;
+    /** List keys in the namespace, optionally filtered by prefix and bounded by limit. */
+    listKeys(prefix?: string, limit?: number): Promise<Key[]>;
+    /** Read a key's value and metadata together. Both are null when absent. */
+    getWithMetadata<M = unknown>(key: string): Promise<KVValueWithMetadata<M>>;
+    /**
+     * Write many keys, collecting a per-key result instead of failing the whole batch on the first
+     * error — the caller decides what to do with partial failure.
+     */
+    batchSet(operations: KVOperation[]): Promise<KVBatchResult[]>;
+    /** The namespace this manager targets and the account it lives in. */
+    getKVInfo(): {
+        namespaceId: string;
+        accountId: string;
+    };
+    getServiceType(): string;
+    /** Prove access by reading the namespace record. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+}
+//# sourceMappingURL=kvManager.d.ts.map

package/dist/kv/kvManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kvManager.d.ts","sourceRoot":"","sources":["../../src/kv/kvManager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yCAAyC,CAAC;AAQnE,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEpF,yFAAyF;AACzF,MAAM,WAAW,eAAgB,SAAQ,uBAAuB;IAC9D,uFAAuF;IACvF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C,sDAAsD;IACtD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,iBAAiB;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,YAAY,MAAM,EAAE,eAAe,EAMlC;IAED,oGAAoG;IAC9F,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAe7C;IAED,0FAA0F;IACpF,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAWzD;IAED,qDAAqD;IAC/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAU3E;IAED,oBAAoB;IACd,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvC;IAED,sFAAsF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAS9D;IAED,2EAA2E;IACrE,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAoB/E;IAED;;;OAGG;IACG,QAAQ,CAAC,UAAU,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAclE;IAED,sEAAsE;IACtE,SAAS,IAAI;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAEtD;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,kEAAkE;IAC5D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}

package/dist/kv/kvManager.js

@@ -0,0 +1,135 @@
+import { CloudflareInvalidResponseError, CloudflareNotConfiguredError, cloudflareRequest, isNotFoundError, reasonOf } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+//#region src/kv/kvManager.ts
+/**
+* Out-of-Worker KV access over the REST API: namespace management and key reads/writes from a
+* CLI/CI/provisioning context. Inside a Worker you use the `KVNamespace` binding directly — this
+* manager is the REST counterpart, addressed by namespace id.
+*/
+var CloudflareKVManager = class extends CloudflareManager {
+	namespaceId;
+	constructor(config) {
+		super(config);
+		if (!config.namespaceId) throw new CloudflareNotConfiguredError({ detail: "Missing namespaceId for KV REST access." });
+		this.namespaceId = config.namespaceId;
+	}
+	/** Read a key's value as text. Returns null when the key is absent (the API 404s a missing key). */
+	async get(key) {
+		return cloudflareRequest(`KV get for key '${key}'`, async () => {
+			try {
+				return await (await this.getClient().kv.namespaces.values.get(key, {
+					account_id: this.accountId,
+					namespace_id: this.namespaceId
+				})).text();
+			} catch (error) {
+				if (isNotFoundError(error)) return null;
+				throw error;
+			}
+		});
+	}
+	/** Read a key and `JSON.parse` it. Returns null when absent; throws on malformed JSON. */
+	async getJson(key) {
+		const raw = await this.get(key);
+		if (raw === null) return null;
+		try {
+			return JSON.parse(raw);
+		} catch (error) {
+			throw new CloudflareInvalidResponseError({
+				message: `KV value for key '${key}' is not valid JSON.`,
+				detail: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	/** Write a value, with optional TTL and metadata. */
+	async set(key, value, options) {
+		await cloudflareRequest(`KV set for key '${key}'`, async () => {
+			await this.getClient().kv.namespaces.values.update(key, {
+				account_id: this.accountId,
+				namespace_id: this.namespaceId,
+				value,
+				...options?.expirationTtl !== void 0 ? { expiration_ttl: options.expirationTtl } : {},
+				...options?.metadata !== void 0 ? { metadata: JSON.stringify(options.metadata) } : {}
+			});
+		});
+	}
+	/** Delete a key. */
+	async delete(key) {
+		await cloudflareRequest(`KV delete for key '${key}'`, async () => {
+			await this.getClient().kv.namespaces.values.delete(key, {
+				account_id: this.accountId,
+				namespace_id: this.namespaceId
+			});
+		});
+	}
+	/** List keys in the namespace, optionally filtered by prefix and bounded by limit. */
+	async listKeys(prefix, limit) {
+		return cloudflareRequest("KV list keys", async () => {
+			return (await this.getClient().kv.namespaces.keys.list(this.namespaceId, {
+				account_id: this.accountId,
+				...prefix !== void 0 ? { prefix } : {},
+				...limit !== void 0 ? { limit } : {}
+			})).result;
+		});
+	}
+	/** Read a key's value and metadata together. Both are null when absent. */
+	async getWithMetadata(key) {
+		return cloudflareRequest(`KV getWithMetadata for key '${key}'`, async () => {
+			const [value, metadata] = await Promise.all([this.get(key), this.getClient().kv.namespaces.metadata.get(key, {
+				account_id: this.accountId,
+				namespace_id: this.namespaceId
+			}).catch((error) => {
+				if (isNotFoundError(error)) return null;
+				throw error;
+			})]);
+			return {
+				value,
+				metadata: metadata ?? null
+			};
+		});
+	}
+	/**
+	* Write many keys, collecting a per-key result instead of failing the whole batch on the first
+	* error — the caller decides what to do with partial failure.
+	*/
+	async batchSet(operations) {
+		const results = [];
+		for (const operation of operations) try {
+			await this.set(operation.key, operation.value, {
+				expirationTtl: operation.expirationTtl,
+				metadata: operation.metadata
+			});
+			results.push({
+				key: operation.key,
+				success: true
+			});
+		} catch (error) {
+			results.push({
+				key: operation.key,
+				success: false,
+				error: reasonOf(error)
+			});
+		}
+		return results;
+	}
+	/** The namespace this manager targets and the account it lives in. */
+	getKVInfo() {
+		return {
+			namespaceId: this.namespaceId,
+			accountId: this.accountId
+		};
+	}
+	getServiceType() {
+		return "KV Storage";
+	}
+	/** Prove access by reading the namespace record. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.getClient().kv.namespaces.get(this.namespaceId, { account_id: this.accountId });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { CloudflareKVManager };

package/dist/kv/kvProvisioner.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+/** A KV namespace's identity, decoded from the create response. */
+export declare const KVNamespaceInfo: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>;
+export type KVNamespaceInfo = z.output<typeof KVNamespaceInfo>;
+/**
+ * Account-level KV control plane: **create and delete namespaces**. Customers use this to stand up
+ * and tear down per-environment KV namespaces (e.g. ephemeral staging), and `pithy add`-driven
+ * provisioning uses it to create each environment's namespaces. Addressed by account — unlike
+ * {@link CloudflareKVManager}, which targets one namespace id for key reads/writes.
+ */
+export declare class CloudflareKVProvisioner extends CloudflareManager {
+    getServiceType(): string;
+    /** Prove access by listing namespaces — a read, never a destructive create/delete. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /** Find a namespace by exact title in the account, or `null` — for idempotent provisioning. */
+    findNamespaceByTitle(title: string): Promise<KVNamespaceInfo | null>;
+    /** List every namespace in the account — for prefix-scan reconcile teardown. */
+    listNamespaces(): Promise<KVNamespaceInfo[]>;
+    /** Create a KV namespace by title; returns its id and title. */
+    createNamespace(title: string): Promise<KVNamespaceInfo>;
+    /** Delete a KV namespace by id. Idempotent — a missing namespace is not an error, so teardown can re-run safely. */
+    deleteNamespace(namespaceId: string): Promise<void>;
+}
+//# sourceMappingURL=kvProvisioner.d.ts.map

package/dist/kv/kvProvisioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kvProvisioner.d.ts","sourceRoot":"","sources":["../../src/kv/kvProvisioner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,mEAAmE;AACnE,eAAO,MAAM,eAAe;;;iBAK4D,CAAC;AACzF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,iBAAiB;IAC5D,cAAc,IAAI,MAAM,CAEvB;IAED,oGAAoG;IAC9F,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED,+FAA+F;IACzF,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAQzE;IAED,gFAAgF;IAC1E,cAAc,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CASjD;IAED,gEAAgE;IAC1D,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAK7D;IAED,oHAAoH;IAC9G,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASxD;CACF"}

package/dist/kv/kvProvisioner.js

@@ -0,0 +1,71 @@
+import { cloudflareRequest, decodeResponse, isNotFoundError } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
+//#region src/kv/kvProvisioner.ts
+/** A KV namespace's identity, decoded from the create response. */
+const KVNamespaceInfo = z.object({
+	id: z.string().describe("The CF-assigned namespace id used to address the namespace."),
+	title: z.string().describe("The namespace title.")
+}).describe("A Cloudflare KV namespace's identity, as returned by the create endpoint.");
+/**
+* Account-level KV control plane: **create and delete namespaces**. Customers use this to stand up
+* and tear down per-environment KV namespaces (e.g. ephemeral staging), and `pithy add`-driven
+* provisioning uses it to create each environment's namespaces. Addressed by account — unlike
+* {@link CloudflareKVManager}, which targets one namespace id for key reads/writes.
+*/
+var CloudflareKVProvisioner = class extends CloudflareManager {
+	getServiceType() {
+		return "Cloudflare KV (control plane)";
+	}
+	/** Prove access by listing namespaces — a read, never a destructive create/delete. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.getClient().kv.namespaces.list({ account_id: this.accountId });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** Find a namespace by exact title in the account, or `null` — for idempotent provisioning. */
+	async findNamespaceByTitle(title) {
+		return cloudflareRequest(`find KV namespace ${title}`, async () => {
+			for await (const ns of this.getClient().kv.namespaces.list({ account_id: this.accountId })) {
+				const parsed = KVNamespaceInfo.safeParse(ns);
+				if (parsed.success && parsed.data.title === title) return parsed.data;
+			}
+			return null;
+		});
+	}
+	/** List every namespace in the account — for prefix-scan reconcile teardown. */
+	async listNamespaces() {
+		return cloudflareRequest("list KV namespaces", async () => {
+			const namespaces = [];
+			for await (const ns of this.getClient().kv.namespaces.list({ account_id: this.accountId })) {
+				const parsed = KVNamespaceInfo.safeParse(ns);
+				if (parsed.success) namespaces.push(parsed.data);
+			}
+			return namespaces;
+		});
+	}
+	/** Create a KV namespace by title; returns its id and title. */
+	async createNamespace(title) {
+		const response = await cloudflareRequest(`create KV namespace ${title}`, () => this.getClient().kv.namespaces.create({
+			account_id: this.accountId,
+			title
+		}));
+		return decodeResponse(KVNamespaceInfo, response, "KV namespace create");
+	}
+	/** Delete a KV namespace by id. Idempotent — a missing namespace is not an error, so teardown can re-run safely. */
+	async deleteNamespace(namespaceId) {
+		await cloudflareRequest(`delete KV namespace ${namespaceId}`, async () => {
+			try {
+				await this.getClient().kv.namespaces.delete(namespaceId, { account_id: this.accountId });
+			} catch (error) {
+				if (isNotFoundError(error)) return;
+				throw error;
+			}
+		});
+	}
+};
+//#endregion
+export { CloudflareKVProvisioner, KVNamespaceInfo };

package/dist/media/assetSeeder.d.ts

@@ -0,0 +1,31 @@
+import type { CloudflareImageManager } from "./imageManager";
+import { type AssetOwner } from "./ownership";
+import type { CloudflareStreamManager } from "./streamManager";
+/**
+ * Upload image bytes to Cloudflare Images, stamped with the owner, returning the minted id. Images
+ * supports a direct byte upload, so this is a single `uploadImage({ file, metadata })` call — the
+ * manager JSON-encodes the metadata bag for the wire. The fixture's own metadata rides along; the
+ * ownership keys are merged last, so a fixture cannot claim another project's assets.
+ */
+export declare function uploadImageBytes(manager: CloudflareImageManager, bytes: Uint8Array | Blob, opts: {
+    owner: AssetOwner;
+    metadata?: Record<string, string>;
+}): Promise<{
+    id: string;
+}>;
+/**
+ * Upload video bytes to Cloudflare Stream, returning the minted uid. Stream has no single direct-bytes
+ * method, so this mints a one-time upload URL with `createDirectUpload` — carrying the stamped metadata
+ * as `meta` so ownership lands with the video — then POSTs the bytes to that URL as `multipart/form-data` (the
+ * basic direct-upload contract). Because the mint carries the metadata, no follow-up `updateVideo`
+ * stamp is needed; if a future Stream contract dropped mint-time `meta`, stamp with
+ * `updateVideo(uid, { meta })` after the upload.
+ */
+export declare function uploadStreamBytes(manager: CloudflareStreamManager, bytes: Uint8Array | Blob, opts: {
+    owner: AssetOwner;
+    metadata?: Record<string, string>;
+    maxDurationSeconds?: number;
+}): Promise<{
+    uid: string;
+}>;
+//# sourceMappingURL=assetSeeder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assetSeeder.d.ts","sourceRoot":"","sources":["../../src/media/assetSeeder.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,KAAK,UAAU,EAAsB,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAyB/D;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,UAAU,GAAG,IAAI,EACxB,IAAI,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC7D,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAMzB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,uBAAuB,EAChC,KAAK,EAAE,UAAU,GAAG,IAAI,EACxB,IAAI,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1F,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAwB1B"}

package/dist/media/assetSeeder.js

@@ -0,0 +1,70 @@
+import { CloudflareRequestError, cloudflareRequest, decodeResponse } from "../client/errors.js";
+import { withAssetOwnership } from "./ownership.js";
+import { z } from "zod";
+//#region src/media/assetSeeder.ts
+/**
+* Seed-time byte uploads to the account-flat Cloudflare Images and Stream stores. Seeding hands a
+* manager raw bytes and a metadata bag and gets back the minted asset id/uid to record — the one
+* place these two stores accept fixture bytes from a CLI/CI context. Every wire response is
+* validated with a local Zod object so a shape drift fails loudly (`cloudflare/invalid_response`)
+* instead of surfacing as `undefined`. These calls are always remote: neither store has a local
+* emulation, so even a `pithy seed` against dev writes into the same store production shares.
+*
+* Which is why {@link AssetOwner} is **required**, not optional. An asset here is keyed by a
+* Cloudflare-minted id, so its metadata is the only thing that says which project seeded it —
+* see `ownership.ts`. Seed fixtures are the likeliest source of debris, and an unattributable
+* fixture asset is one nobody can sweep.
+*/
+/** The default max video duration (seconds) CF Stream requires for a direct upload — 6 hours. */
+const STREAM_MAX_DURATION_SECONDS = 21600;
+/** The only field of an Images upload response the seeder needs: the minted image id. */
+const ImageUploadResult = z.object({ id: z.string() });
+/** The fields of a Stream direct-upload mint the seeder needs: the uid and the one-time upload URL. */
+const StreamDirectUploadResult = z.object({
+	uid: z.string(),
+	uploadURL: z.string()
+});
+/**
+* Upload image bytes to Cloudflare Images, stamped with the owner, returning the minted id. Images
+* supports a direct byte upload, so this is a single `uploadImage({ file, metadata })` call — the
+* manager JSON-encodes the metadata bag for the wire. The fixture's own metadata rides along; the
+* ownership keys are merged last, so a fixture cannot claim another project's assets.
+*/
+async function uploadImageBytes(manager, bytes, opts) {
+	const file = bytes instanceof File ? bytes : new File([bytes], "seed");
+	const response = await manager.uploadImage({
+		file,
+		metadata: withAssetOwnership(opts.owner, opts.metadata)
+	});
+	return { id: decodeResponse(ImageUploadResult, response, "Images seed upload").id };
+}
+/**
+* Upload video bytes to Cloudflare Stream, returning the minted uid. Stream has no single direct-bytes
+* method, so this mints a one-time upload URL with `createDirectUpload` — carrying the stamped metadata
+* as `meta` so ownership lands with the video — then POSTs the bytes to that URL as `multipart/form-data` (the
+* basic direct-upload contract). Because the mint carries the metadata, no follow-up `updateVideo`
+* stamp is needed; if a future Stream contract dropped mint-time `meta`, stamp with
+* `updateVideo(uid, { meta })` after the upload.
+*/
+async function uploadStreamBytes(manager, bytes, opts) {
+	const mint = decodeResponse(StreamDirectUploadResult, await manager.createDirectUpload({
+		maxDurationSeconds: opts.maxDurationSeconds ?? STREAM_MAX_DURATION_SECONDS,
+		meta: withAssetOwnership(opts.owner, opts.metadata)
+	}), "Stream seed direct upload");
+	await cloudflareRequest("Stream seed byte upload", async () => {
+		const file = bytes instanceof Blob ? bytes : new Blob([bytes]);
+		const form = new FormData();
+		form.append("file", file, "seed");
+		const response = await fetch(mint.uploadURL, {
+			method: "POST",
+			body: form
+		});
+		if (!response.ok) throw new CloudflareRequestError({
+			message: "The Stream direct upload failed.",
+			detail: `Stream direct upload returned ${response.status}: ${await response.text()}`
+		});
+	});
+	return { uid: mint.uid };
+}
+//#endregion
+export { uploadImageBytes, uploadStreamBytes };

package/dist/media/imageManager.d.ts

@@ -0,0 +1,34 @@
+import type { Image, V1CreateParams, V1EditParams } from "cloudflare/resources/images/v1/v1";
+import type { DirectUploadCreateParams, DirectUploadCreateResponse } from "cloudflare/resources/images/v2/direct-uploads";
+import type { V2ListParams } from "cloudflare/resources/images/v2/v2";
+import { CloudflareManager } from "../client/manager";
+/**
+ * Out-of-Worker Cloudflare Images access over the REST API: upload, fetch, edit, delete, list, and
+ * direct-upload URLs from a CLI/CI/provisioning context. Image metadata is an arbitrary
+ * `Record<string, string>` passthrough at this layer — the manager imposes no shape.
+ *
+ * The ownership stamp is imposed one layer up, by `withAssetOwnership` in `ownership.ts`, which every
+ * Pithy path that *creates* an image goes through (the seeder here, and media's `imageMinter`). The
+ * split is deliberate: this class stays a faithful REST client usable for reading and sweeping
+ * anyone's images, while nothing Pithy writes can escape carrying `pithyProject`/`pithyEnv`.
+ */
+export declare class CloudflareImageManager extends CloudflareManager {
+    /** Upload an image via the V1 API. `account_id` is set from the manager's config. */
+    uploadImage(params: Omit<V1CreateParams, "account_id">): Promise<Image>;
+    /** Fetch details for one image by id. */
+    imageDetails(imageId: string): Promise<Image>;
+    /** Update an image's metadata and settings. */
+    updateImage(imageId: string, params: Omit<V1EditParams, "account_id">): Promise<Image>;
+    /** Delete an image by id. */
+    deleteImage(imageId: string): Promise<void>;
+    /** Create a direct-upload URL for a client-side upload (V2 API). */
+    createDirectUploadUrl(params: Omit<DirectUploadCreateParams, "account_id">): Promise<DirectUploadCreateResponse>;
+    /** List images (V2 API), first page only. Returns the page's images, never null. */
+    listImages(params?: Omit<V2ListParams, "account_id">): Promise<Image[]>;
+    /** List all images across every page, following the V2 continuation token. */
+    listAllImages(params?: Omit<V2ListParams, "account_id">): Promise<Image[]>;
+    getServiceType(): string;
+    /** Prove access by listing images. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+}
+//# sourceMappingURL=imageManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"imageManager.d.ts","sourceRoot":"","sources":["../../src/media/imageManager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAC7F,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,+CAA+C,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAEtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAoBtD;;;;;;;;;GASG;AACH,qBAAa,sBAAuB,SAAQ,iBAAiB;IAC3D,qFAAqF;IAC/E,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAO5E;IAED,yCAAyC;IACnC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAIlD;IAED,+CAA+C;IACzC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAI3F;IAED,6BAA6B;IACvB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhD;IAED,oEAAoE;IAC9D,qBAAqB,CACzB,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,YAAY,CAAC,GACnD,OAAO,CAAC,0BAA0B,CAAC,CAOrC;IAED,oFAAoF;IAC9E,UAAU,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAK5E;IAED,8EAA8E;IACxE,aAAa,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAe/E;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,oDAAoD;IAC9C,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}

package/dist/media/imageManager.js

@@ -0,0 +1,103 @@
+import { cloudflareRequest } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+//#region src/media/imageManager.ts
+/**
+* Per-request CF SDK options for every Images call: a 10s timeout and up to 3 retries. Uploads and
+* list calls can be slow, so the timeout is generous and retries cover transient API blips.
+*/
+const requestOptions = {
+	timeout: 1e4,
+	maxRetries: 3
+};
+/**
+* Encode a user-metadata bag to the string the Images API expects. CF stores image metadata as a
+* JSON string; we serialize the generic `Record<string, string>` passthrough before sending, and
+* leave an absent bag untouched.
+*/
+function encodeMetadata(metadata) {
+	return metadata === void 0 || metadata === null ? metadata : JSON.stringify(metadata);
+}
+/**
+* Out-of-Worker Cloudflare Images access over the REST API: upload, fetch, edit, delete, list, and
+* direct-upload URLs from a CLI/CI/provisioning context. Image metadata is an arbitrary
+* `Record<string, string>` passthrough at this layer — the manager imposes no shape.
+*
+* The ownership stamp is imposed one layer up, by `withAssetOwnership` in `ownership.ts`, which every
+* Pithy path that *creates* an image goes through (the seeder here, and media's `imageMinter`). The
+* split is deliberate: this class stays a faithful REST client usable for reading and sweeping
+* anyone's images, while nothing Pithy writes can escape carrying `pithyProject`/`pithyEnv`.
+*/
+var CloudflareImageManager = class extends CloudflareManager {
+	/** Upload an image via the V1 API. `account_id` is set from the manager's config. */
+	async uploadImage(params) {
+		return cloudflareRequest("Images upload", () => this.getClient().images.v1.create({
+			account_id: this.accountId,
+			...params,
+			metadata: encodeMetadata(params.metadata)
+		}, requestOptions));
+	}
+	/** Fetch details for one image by id. */
+	async imageDetails(imageId) {
+		return cloudflareRequest(`Images get details for '${imageId}'`, () => this.getClient().images.v1.get(imageId, { account_id: this.accountId }, requestOptions));
+	}
+	/** Update an image's metadata and settings. */
+	async updateImage(imageId, params) {
+		return cloudflareRequest(`Images update '${imageId}'`, () => this.getClient().images.v1.edit(imageId, {
+			account_id: this.accountId,
+			...params
+		}, requestOptions));
+	}
+	/** Delete an image by id. */
+	async deleteImage(imageId) {
+		await cloudflareRequest(`Images delete '${imageId}'`, () => this.getClient().images.v1.delete(imageId, { account_id: this.accountId }, requestOptions));
+	}
+	/** Create a direct-upload URL for a client-side upload (V2 API). */
+	async createDirectUploadUrl(params) {
+		return cloudflareRequest("Images create direct upload URL", () => this.getClient().images.v2.directUploads.create({
+			account_id: this.accountId,
+			...params,
+			metadata: encodeMetadata(params.metadata)
+		}, requestOptions));
+	}
+	/** List images (V2 API), first page only. Returns the page's images, never null. */
+	async listImages(params) {
+		return cloudflareRequest("Images list", async () => {
+			return (await this.getClient().images.v2.list({
+				account_id: this.accountId,
+				...params
+			}, requestOptions)).images ?? [];
+		});
+	}
+	/** List all images across every page, following the V2 continuation token. */
+	async listAllImages(params) {
+		return cloudflareRequest("Images list all", async () => {
+			const allImages = [];
+			const client = this.getClient();
+			const fetchPage = async (token) => {
+				const response = await client.images.v2.list({
+					account_id: this.accountId,
+					...params,
+					continuation_token: token
+				}, requestOptions);
+				if (response.images) allImages.push(...response.images);
+				if (response.continuation_token) await fetchPage(response.continuation_token);
+			};
+			await fetchPage();
+			return allImages;
+		});
+	}
+	getServiceType() {
+		return "Cloudflare Images";
+	}
+	/** Prove access by listing images. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.listImages();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { CloudflareImageManager };

package/dist/media/ownership.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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`. */
+export declare const ASSET_PROJECT_KEY = "pithyProject";
+/** The metadata key naming the owning environment (`dev` | `staging` | `production`). */
+export declare const ASSET_ENV_KEY = "pithyEnv";
+/** Who owns an asset: the project that created it, in the environment that created it. */
+export interface AssetOwner {
+    /**
+     * The project name — the root `pithy.config.ts` `name`, resolved by `requireProjectName` and never
+     * guessed. It is the segment every sweep, listing, and teardown filters on.
+     */
+    project: string;
+    /** The environment the asset was created in (`dev` | `staging` | `production`). */
+    env: string;
+}
+/**
+ * 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.
+ */
+export declare function withAssetOwnership(owner: AssetOwner, metadata?: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=ownership.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ownership.d.ts","sourceRoot":"","sources":["../../src/media/ownership.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AAEH,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAEhD,yFAAyF;AACzF,eAAO,MAAM,aAAa,aAAa,CAAC;AAExC,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAW/G"}