@pithy-sh/cloudflare 0.1.0

package/src/kv/kvProvisioner.ts

@@ -0,0 +1,80 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { cloudflareRequest, decodeResponse, isNotFoundError } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/** A KV namespace's identity, decoded from the create response. */
+export 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.");
+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 class CloudflareKVProvisioner extends CloudflareManager {
+  getServiceType(): string {
+    return "Cloudflare KV (control plane)";
+  }
+
+  /** Prove access by listing namespaces — a read, never a destructive create/delete. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    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: string): Promise<KVNamespaceInfo | null> {
+    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(): Promise<KVNamespaceInfo[]> {
+    return cloudflareRequest("list KV namespaces", async () => {
+      const namespaces: KVNamespaceInfo[] = [];
+      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: string): Promise<KVNamespaceInfo> {
+    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: string): Promise<void> {
+    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;
+      }
+    });
+  }
+}

package/src/media/assetSeeder.ts

@@ -0,0 +1,87 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { CloudflareRequestError, cloudflareRequest, decodeResponse } from "../client/errors";
+import type { CloudflareImageManager } from "./imageManager";
+import { type AssetOwner, withAssetOwnership } from "./ownership";
+import type { CloudflareStreamManager } from "./streamManager";
+
+/**
+ * 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.
+ */
+export async function uploadImageBytes(
+  manager: CloudflareImageManager,
+  bytes: Uint8Array | Blob,
+  opts: { owner: AssetOwner; metadata?: Record<string, string> },
+): Promise<{ id: string }> {
+  // The Images SDK's `Uploadable` type is a `File`, not a bare `Blob`, so wrap a Blob/bytes input.
+  const file = bytes instanceof File ? bytes : new File([bytes], "seed");
+  const response = await manager.uploadImage({ file, metadata: withAssetOwnership(opts.owner, opts.metadata) });
+  const result = decodeResponse(ImageUploadResult, response, "Images seed upload");
+  return { id: result.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.
+ */
+export async function uploadStreamBytes(
+  manager: CloudflareStreamManager,
+  bytes: Uint8Array | Blob,
+  opts: { owner: AssetOwner; metadata?: Record<string, string>; maxDurationSeconds?: number },
+): Promise<{ uid: string }> {
+  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 };
+}

package/src/media/imageManager.ts

@@ -0,0 +1,125 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Cloudflare } from "cloudflare";
+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 { cloudflareRequest } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/**
+ * 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: Cloudflare.RequestOptions = {
+  timeout: 10000,
+  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: unknown): unknown {
+  return metadata === undefined || 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`.
+ */
+export class CloudflareImageManager extends CloudflareManager {
+  /** Upload an image via the V1 API. `account_id` is set from the manager's config. */
+  async uploadImage(params: Omit<V1CreateParams, "account_id">): Promise<Image> {
+    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: string): Promise<Image> {
+    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: string, params: Omit<V1EditParams, "account_id">): Promise<Image> {
+    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: string): Promise<void> {
+    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: Omit<DirectUploadCreateParams, "account_id">,
+  ): Promise<DirectUploadCreateResponse> {
+    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?: Omit<V2ListParams, "account_id">): Promise<Image[]> {
+    return cloudflareRequest("Images list", async () => {
+      const response = await this.getClient().images.v2.list({ account_id: this.accountId, ...params }, requestOptions);
+      return response.images ?? [];
+    });
+  }
+
+  /** List all images across every page, following the V2 continuation token. */
+  async listAllImages(params?: Omit<V2ListParams, "account_id">): Promise<Image[]> {
+    return cloudflareRequest("Images list all", async () => {
+      const allImages: Image[] = [];
+      const client = this.getClient();
+      const fetchPage = async (token?: string | null): Promise<void> => {
+        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(): string {
+    return "Cloudflare Images";
+  }
+
+  /** Prove access by listing images. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.listImages();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/media/ownership.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { CloudflareNotConfiguredError } from "../client/errors";
+
+/**
+ * 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 const ASSET_PROJECT_KEY = "pithyProject";
+
+/** The metadata key naming the owning environment (`dev` | `staging` | `production`). */
+export 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 function withAssetOwnership(owner: AssetOwner, metadata?: Record<string, string>): Record<string, string> {
+  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 };
+}

package/src/media/streamManager.ts

@@ -0,0 +1,198 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Cloudflare } from "cloudflare";
+import type { DirectUploadCreateParams, DirectUploadCreateResponse } from "cloudflare/resources/stream/direct-upload";
+import type { StreamEditParams, Video } from "cloudflare/resources/stream/stream";
+import { z } from "zod";
+import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/**
+ * 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: Cloudflare.RequestOptions = {
+  timeout: 10000,
+  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.
+ */
+export 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).");
+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 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.");
+export type StreamDownloadStatus = z.infer<typeof StreamDownloadStatus>;
+
+/** 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: unknown): StreamDownloadStatus {
+  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.
+ */
+export class CloudflareStreamManager extends CloudflareManager {
+  /** Delete a video by its Stream UID. */
+  async deleteVideo(videoId: string): Promise<void> {
+    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: string): Promise<Video> {
+    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: string, params: Omit<StreamEditParams, "account_id">): Promise<Video> {
+    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: string): Promise<StreamDownloadStatus> {
+    return cloudflareRequest(`Stream download status for '${videoId}'`, async () => {
+      const response = await this.getClient().stream.downloads.get(
+        videoId,
+        { account_id: this.accountId },
+        requestOptions,
+      );
+      return parseDownloadStatus(response);
+    });
+  }
+
+  /** Trigger Cloudflare to generate a downloadable MP4 for a video. */
+  async createVideoDownload(videoId: string): Promise<StreamDownloadStatus> {
+    return cloudflareRequest(`Stream create download for '${videoId}'`, async () => {
+      const response = await this.getClient().stream.downloads.create(
+        videoId,
+        { account_id: this.accountId },
+        requestOptions,
+      );
+      return parseDownloadStatus(response);
+    });
+  }
+
+  /**
+   * 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: string): Promise<DownloadEntry> {
+    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: unknown = 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: string): Promise<DownloadEntry> {
+    return cloudflareRequest(`Stream audio download status for '${videoId}'`, async () => {
+      const response = await this.getClient().stream.downloads.get(
+        videoId,
+        { account_id: this.accountId },
+        requestOptions,
+      );
+      const status = parseDownloadStatus(response);
+      return status.audio ?? {};
+    });
+  }
+
+  /** Create a direct-upload URL for a client-side video upload. */
+  async createDirectUpload(params: Omit<DirectUploadCreateParams, "account_id">): Promise<DirectUploadCreateResponse> {
+    return cloudflareRequest("Stream create direct upload", () =>
+      this.getClient().stream.directUpload.create({ account_id: this.accountId, ...params }, requestOptions),
+    );
+  }
+
+  getServiceType(): string {
+    return "Cloudflare Stream";
+  }
+
+  /** Prove access by listing videos. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.getClient().stream.list({ account_id: this.accountId });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}