@pithy-sh/cloudflare 0.1.0

package/src/email/emailRoutingManager.ts

@@ -0,0 +1,143 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/**
+ * Cloudflare Email Routing rules — the inbound side. Used by email provisioning to point a domain's
+ * bounce/complaint mail at the app worker that hosts the `email()` handler. Email Routing is
+ * **zone-scoped** (a rule lives on a zone, and routing must already be enabled on that zone — enabling
+ * it sets the zone's MX, an operator action we never take automatically, so the apex MX stays put).
+ *
+ * Rule *creation and deletion* go through the typed SDK. The lookup both of them turn on cannot:
+ * `emailRouting.rules` exposes only create/update/delete/get, and `get` addresses a rule by CF id — we
+ * match by name, which needs a listing the SDK has no method for. That one read stays on the documented
+ * raw-`fetch` escape hatch; drop it the moment a `rules.list` lands.
+ */
+
+/** A routing rule's stored shape — only the fields we match on for idempotency. */
+const RuleEnvelope = z.object({
+  success: z.boolean(),
+  result: z
+    .array(z.object({ id: z.string().optional(), name: z.string().optional() }))
+    .nullable()
+    .default([]),
+  /**
+   * The paging block. Present on every list response, and read rather than ignored because both
+   * callers ask a question a truncated answer gets **wrong in the dangerous direction**: an unseen
+   * rule reads as "no such rule", which makes `ensureWorkerRoute` create a duplicate on every run and
+   * `removeWorkerRoute` report a removal while mail is still being delivered.
+   */
+  result_info: z
+    .object({
+      page: z.number().optional(),
+      per_page: z.number().optional(),
+      total_count: z.number().optional(),
+      total_pages: z.number().optional(),
+    })
+    .nullish(),
+});
+
+/** Rules per page. Cloudflare's maximum, so the common zone is answered in one request. */
+const RULES_PER_PAGE = 50;
+
+/** A hard stop on the page loop, so a malformed `result_info` cannot spin forever. */
+const MAX_RULE_PAGES = 100;
+
+export class CloudflareEmailRoutingManager extends CloudflareManager {
+  getServiceType(): string {
+    return "Email Routing";
+  }
+
+  /** Prove reach by listing a zone's routing rules; never throws. (Account-level reach is a weak proxy here.) */
+  async validateServiceAccess(): Promise<boolean> {
+    return true;
+  }
+
+  /**
+   * Ensure a routing rule named `ruleName` exists on `zoneId`, delivering mail addressed to `address`
+   * to the Worker `workerName`. Idempotent: if a rule with that name already exists it is left as-is.
+   * Assumes Email Routing is already enabled on the zone.
+   */
+  async ensureWorkerRoute(options: {
+    zoneId: string;
+    address: string;
+    workerName: string;
+    ruleName: string;
+  }): Promise<{ created: boolean }> {
+    const { zoneId, address, workerName, ruleName } = options;
+    return cloudflareRequest("Email Routing ensure worker rule", async () => {
+      const rules = await this.#listRules(zoneId);
+      if (rules.some((rule) => rule.name === ruleName)) return { created: false };
+
+      await this.getClient().emailRouting.rules.create({
+        zone_id: zoneId,
+        name: ruleName,
+        enabled: true,
+        matchers: [{ type: "literal", field: "to", value: address }],
+        actions: [{ type: "worker", value: [workerName] }],
+      });
+      return { created: true };
+    });
+  }
+
+  /**
+   * Remove the rule named `ruleName` from `zoneId`, so mail stops being delivered to the Worker behind it.
+   * Idempotent: a zone carrying no such rule is a no-op, which is what lets a teardown be re-run.
+   *
+   * **Matched on the rule name, never on the address.** The name is the key `ensureWorkerRoute` created
+   * under, so the two agree on which rule belongs to which capability even after somebody edited the
+   * address in the dashboard — and a teardown that matched on the address would happily delete a rule an
+   * operator wrote by hand for the same mailbox.
+   */
+  async removeWorkerRoute(options: { zoneId: string; ruleName: string }): Promise<{ removed: boolean }> {
+    const { zoneId, ruleName } = options;
+    return cloudflareRequest("Email Routing remove worker rule", async () => {
+      const rule = (await this.#listRules(zoneId)).find((candidate) => candidate.name === ruleName);
+      if (!rule?.id) return { removed: false };
+      await this.getClient().emailRouting.rules.delete(rule.id, { zone_id: zoneId });
+      return { removed: true };
+    });
+  }
+
+  /**
+   * **Every** routing rule on a zone, by the raw-`fetch` escape hatch this file's header documents —
+   * the SDK has no listing, and both matching by name and deleting by id need one.
+   *
+   * Paged to exhaustion rather than reading the first page. A zone with more rules than fit one page
+   * is unusual but entirely legal, and a partial read is not a smaller answer here — it is a *wrong*
+   * one, because both callers treat "not in the list" as "does not exist". Provisioning would then
+   * create a second rule for the same address on every run, and a teardown would report mail stopped
+   * while it kept arriving.
+   *
+   * A failed read **throws**, for the same reason: silently degrading to an empty list would produce
+   * exactly the two failures above.
+   */
+  async #listRules(zoneId: string): Promise<{ id?: string; name?: string }[]> {
+    const rules: { id?: string; name?: string }[] = [];
+
+    for (let page = 1; page <= MAX_RULE_PAGES; page += 1) {
+      const url = `https://api.cloudflare.com/client/v4/zones/${zoneId}/email/routing/rules?page=${page}&per_page=${RULES_PER_PAGE}`;
+      const listed = await fetch(url, { headers: { Authorization: `Bearer ${this.getApiToken()}` } });
+      if (!listed.ok) {
+        throw new CloudflareInvalidResponseError({
+          message: "Could not read the zone's Email Routing rules.",
+          detail: `Email Routing rule list returned ${listed.status}: ${await listed.text()}`,
+        });
+      }
+
+      const envelope = RuleEnvelope.parse(await listed.json());
+      const batch = envelope.result ?? [];
+      rules.push(...batch);
+
+      // Stop on the paging block when the API supplied one, and on a short page otherwise — an older
+      // or proxied response that omits `result_info` still terminates correctly.
+      const totalPages = envelope.result_info?.total_pages;
+      if (totalPages !== undefined ? page >= totalPages : batch.length < RULES_PER_PAGE) break;
+    }
+
+    return rules;
+  }
+}

package/src/email/emailSendManager.ts

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { cloudflareRequest } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/**
+ * Out-of-Worker sends through the Cloudflare Email Service REST API — the control-plane counterpart to
+ * the in-Worker `send_email` binding. Used by the CLI's `pithy email test` to render and deliver one
+ * template through a project's configuration without deploying. Inside a Worker, always prefer the
+ * binding (no token, principle-1 aligned).
+ */
+
+/** A message to send over REST. `from` mirrors the binding's `{ email, name }`; the wire uses `address`. */
+export interface EmailSendInput {
+  to: string | string[];
+  from: { email: string; name?: string };
+  subject: string;
+  html: string;
+  text: string;
+  replyTo?: string;
+}
+
+/** What the send returned: the assigned message id and any synchronous delivery breakdown. */
+export interface EmailSendResult {
+  messageId?: string;
+  delivered: string[];
+  queued: string[];
+  permanentBounces: string[];
+}
+
+export class CloudflareEmailSendManager extends CloudflareManager {
+  getServiceType(): string {
+    return "Email Sending";
+  }
+
+  /**
+   * Prove reach by reading the account's sending limits; never throws (returns false on any failure).
+   * `/email/sending/limits` has no typed SDK method — only `send` and `subdomains` do — so this stays
+   * on the documented raw-`fetch` escape hatch. Probing `subdomains.list` instead would change what
+   * the check proves: a token scoped to send but not to read subdomains would start reporting false.
+   */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      const res = await fetch(
+        `https://api.cloudflare.com/client/v4/accounts/${this.getAccountId()}/email/sending/limits`,
+        { headers: { Authorization: `Bearer ${this.getApiToken()}` } },
+      );
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Send one message through the Email Sending API. Throws `cloudflare/request_failed` on any API
+   * error — the SDK unwraps the envelope and raises on `success: false`, so a resolved call is a send.
+   *
+   * `from` is sent as the object form only when a display name exists; the SDK's object form requires
+   * `name`, and the bare-string form is the wire's own representation of "address, no display name".
+   */
+  async send(message: EmailSendInput): Promise<EmailSendResult> {
+    return cloudflareRequest("Email Service send", async () => {
+      const result = await this.getClient().emailSending.send({
+        account_id: this.getAccountId(),
+        to: message.to,
+        from: message.from.name ? { address: message.from.email, name: message.from.name } : message.from.email,
+        subject: message.subject,
+        html: message.html,
+        text: message.text,
+        ...(message.replyTo ? { reply_to: message.replyTo } : {}),
+      });
+      return {
+        messageId: result.message_id,
+        delivered: result.delivered,
+        queued: result.queued,
+        permanentBounces: result.permanent_bounces,
+      };
+    });
+  }
+}

package/src/env/devVars.ts

@@ -0,0 +1,90 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The Cloudflare credential keys pithy reads out-of-Worker (CLI, provisioning, live tests). These are
+ * wrangler's own env-var names plus the Secrets Store id. From this single bootstrap token
+ * (`CLOUDFLARE_API_TOKEN`) pithy **mints** the scoped, least-privilege tokens each use case needs —
+ * most notably the secrets manager's runtime token, minted at provision time and written straight into
+ * the Secrets Store, so no scoped token is ever supplied or kept here.
+ *
+ * **Where they are read from is not this module's answer any more (#182).** They are account-scoped, so
+ * they live in `<config>/cloudflare.json` — or, since #206, in `<config>/cloudflare.<name>.json` when a
+ * project's root config names its account. See `@pithy-sh/cli`'s `cloudflare/config`, which owns the
+ * file, which file, the `process.env` overlay, and the split diagnostic. The names stay here because
+ * both ends need them and the Worker-side package is the one both can import.
+ *
+ * **The overlay has an off switch, and it is not `PITHY_CONFIG_DIR` (#218).** Relocating the config
+ * directory moves the *file*; these four names are still read out of the ambient environment, which is
+ * how a CLI run in an empty scratch directory reached a real account off a token a shell had exported
+ * hours earlier. `PITHY_OFFLINE` is the word that stops it, and it lives with the overlay it governs —
+ * `PITHY_OFFLINE_ENV` in `@pithy-sh/cli`'s `cloudflare/config`. Anything outside the CLI that grows a
+ * reason to read one of these names off `process.env` inherits that obligation with it.
+ */
+export const CLOUDFLARE_ENV_KEYS = [
+  "CLOUDFLARE_ACCOUNT_ID",
+  "CLOUDFLARE_API_TOKEN",
+  "SECRETS_STORE_ID",
+  "R2_CREDENTIALS",
+] as const;
+
+/**
+ * Which of {@link CLOUDFLARE_ENV_KEYS} an environment actually carries a value for. The one place that
+ * list is turned into a check.
+ *
+ * **Non-empty, not merely present.** `vitest.shared.ts`'s `NO_ACCOUNT` pins all four keys to `""`, and
+ * the `process.env` overlay in `@pithy-sh/cli`'s `cloudflare/config` already reads a blank as unset. A
+ * predicate keying on presence would report every guarded unit project as leaking.
+ *
+ * **This module is bundled into workerd as well as run on the host, and that is why it imports nothing.**
+ * The repository-root `vitest.workers.setup.ts` imports this function relatively and every workers
+ * project loads it, so a `node:` import here breaks seventeen suites at collection. `vitest.shared.ts`
+ * already leans on the same property for {@link CLOUDFLARE_ENV_KEYS} and says so. Nothing gates the
+ * import half — `@pithy-sh/core` has `worker-safety.test.ts` and this package has no equivalent — so it
+ * is a constraint a reader has to be told, which is what this paragraph is. The other half is gated:
+ * `packages/cli/src/ci/testIsolation.test.ts` walks what every workers config imports, so this module
+ * is in that scan and a `process.env` read here is red (#437).
+ */
+export function visibleCredentialKeys(env: Readonly<Record<string, string | undefined>>): readonly string[] {
+  return CLOUDFLARE_ENV_KEYS.filter((key) => (env[key] ?? "").length > 0);
+}
+
+/**
+ * Parse a `.dev.vars` file body into a map: `KEY=value` lines, `#` comments and blanks skipped, and
+ * a single layer of surrounding quotes stripped. Pure — the caller owns the file read.
+ */
+export function parseDevVars(content: string): Record<string, string> {
+  const vars: Record<string, string> = {};
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    vars[trimmed.slice(0, eq).trim()] = trimmed
+      .slice(eq + 1)
+      .trim()
+      .replace(/^["']|["']$/g, "");
+  }
+  return vars;
+}
+
+/**
+ * The keys that only mean anything **together, from one account**: the account id, and a token minted in
+ * that account. Deliberately just the pair.
+ *
+ * The other {@link CLOUDFLARE_ENV_KEYS} stay out, because each fails loudly and immediately when it comes
+ * from the wrong account: a store id this account does not hold 404s on the first call, and an S3 key
+ * that does not belong to the account in the endpoint will not sign. Only the pair can *quietly* succeed
+ * somewhere unintended — a live token against another account's id is a 403 or an empty listing much
+ * later — so only the pair is a group. That is the whole test for membership.
+ *
+ * **A whole file can be the wrong account too.** This pair is the *half-file, half-environment* case; one
+ * level up, a file that is entirely coherent in itself can belong to a different company than the project
+ * reading it, which is what a project's `cloudflare.accountName` and its `accountId` pin answer (#206).
+ *
+ * `SECRETS_STORE_ID` used to be excluded on the grounds that it is "routinely passed per environment
+ * while the pair sits in the file". That was never true: Cloudflare permits **one Secrets Store per
+ * account**, so nothing about the id is per-environment, and it now sits in `cloudflare.json` beside the
+ * pair for exactly that reason (#182). The conclusion was right; the stated reason was not.
+ */
+export const CLOUDFLARE_CREDENTIAL_KEYS = ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"] as const;

package/src/hostnames/customHostnamesManager.ts

@@ -0,0 +1,134 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type {
+  CustomHostnameCreateResponse,
+  CustomHostnameDeleteResponse,
+  CustomHostnameGetResponse,
+  CustomHostnameListResponse,
+} from "cloudflare/resources/custom-hostnames/custom-hostnames";
+import { CloudflareNotConfiguredError, cloudflareRequest } from "../client/errors";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+
+/**
+ * Config for the Custom Hostnames manager: the shared client config plus the zone the hostnames
+ * live under. Custom hostnames are a zone-scoped resource — the REST API addresses them by
+ * `zone_id`, so the zone is required configuration here.
+ */
+export interface CustomHostnamesManagerConfig extends CloudflareManagerConfig {
+  /** The zone id custom hostnames are created and managed under (the CF zone serving the apex). */
+  zoneId: string;
+}
+
+/** Options for creating a custom hostname. */
+export interface CreateCustomHostnameOptions {
+  /**
+   * The minimum TLS version the issued certificate negotiates. Defaults to `1.2`. Custom hostnames
+   * use HTTP DCV with a DV certificate.
+   */
+  minTlsVersion?: "1.0" | "1.1" | "1.2" | "1.3";
+}
+
+/**
+ * Out-of-Worker Custom Hostnames access over the REST API: create, look up, and remove custom
+ * hostnames on a zone from a CLI/CI/provisioning context. Custom hostnames let a zone serve domains
+ * it does not own DNS for — a customer CNAMEs their domain to a fallback origin on the zone, and CF
+ * issues a certificate via HTTP domain-control validation. Addressed by zone id.
+ */
+export class CloudflareCustomHostnamesManager extends CloudflareManager {
+  private readonly zoneId: string;
+
+  constructor(config: CustomHostnamesManagerConfig) {
+    super(config);
+    if (!config.zoneId) {
+      throw new CloudflareNotConfiguredError({ detail: "Missing zoneId for Custom Hostnames REST access." });
+    }
+    this.zoneId = config.zoneId;
+  }
+
+  /**
+   * Create a custom hostname with HTTP DCV and a DV certificate. Idempotent: if a custom hostname
+   * already exists for this hostname, the existing record is returned instead of creating a duplicate.
+   */
+  async addCustomHostname(
+    hostname: string,
+    options?: CreateCustomHostnameOptions,
+  ): Promise<CustomHostnameCreateResponse | CustomHostnameListResponse> {
+    const existing = await this.getCustomHostname(hostname);
+    if (existing) return existing;
+
+    return cloudflareRequest(`add custom hostname '${hostname}'`, () =>
+      this.getClient().customHostnames.create({
+        zone_id: this.zoneId,
+        hostname,
+        ssl: {
+          method: "http",
+          type: "dv",
+          settings: { min_tls_version: options?.minTlsVersion ?? "1.2" },
+        },
+      }),
+    );
+  }
+
+  /** Look up a custom hostname by its fully qualified name. Returns null when none matches. */
+  async getCustomHostname(hostname: string): Promise<CustomHostnameListResponse | null> {
+    return cloudflareRequest(`get custom hostname '${hostname}'`, async () => {
+      // `hostname` is a filter object in the v7 SDK; `exact` is the FQDN match (the loose
+      // `contain`/`startsWith` variants would return neighbors). The equality re-check below
+      // stays as a guard — the filter narrows the page, it does not guarantee a single result.
+      for await (const candidate of this.getClient().customHostnames.list({
+        zone_id: this.zoneId,
+        hostname: { exact: hostname },
+      })) {
+        if (candidate.hostname === hostname) return candidate;
+      }
+      return null;
+    });
+  }
+
+  /** Fetch a custom hostname by its id. */
+  async getCustomHostnameById(customHostnameId: string): Promise<CustomHostnameGetResponse> {
+    return cloudflareRequest(`get custom hostname by id '${customHostnameId}'`, () =>
+      this.getClient().customHostnames.get(customHostnameId, { zone_id: this.zoneId }),
+    );
+  }
+
+  /** List every custom hostname on the zone. */
+  async listCustomHostnames(): Promise<CustomHostnameListResponse[]> {
+    return cloudflareRequest("list custom hostnames", async () => {
+      const hostnames: CustomHostnameListResponse[] = [];
+      for await (const candidate of this.getClient().customHostnames.list({ zone_id: this.zoneId })) {
+        hostnames.push(candidate);
+      }
+      return hostnames;
+    });
+  }
+
+  /** Remove a custom hostname by its id. */
+  async removeCustomHostname(customHostnameId: string): Promise<CustomHostnameDeleteResponse> {
+    return cloudflareRequest(`remove custom hostname '${customHostnameId}'`, () =>
+      this.getClient().customHostnames.delete(customHostnameId, { zone_id: this.zoneId }),
+    );
+  }
+
+  /** The zone this manager targets and the account it lives in. */
+  getCustomHostnamesInfo(): { zoneId: string; accountId: string } {
+    return { zoneId: this.zoneId, accountId: this.accountId };
+  }
+
+  getServiceType(): string {
+    return "Cloudflare Custom Hostnames";
+  }
+
+  /** Prove access by listing custom hostnames on the zone. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      for await (const _candidate of this.getClient().customHostnames.list({ zone_id: this.zoneId, per_page: 1 })) {
+        break;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/kv/kvManager.ts

@@ -0,0 +1,202 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Key } from "cloudflare/resources/kv/namespaces/keys";
+import {
+  CloudflareInvalidResponseError,
+  CloudflareNotConfiguredError,
+  cloudflareRequest,
+  isNotFoundError,
+  reasonOf,
+} from "../client/errors";
+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 class CloudflareKVManager extends CloudflareManager {
+  private readonly namespaceId: string;
+
+  constructor(config: KVManagerConfig) {
+    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: string): Promise<string | null> {
+    return cloudflareRequest(`KV get for key '${key}'`, async () => {
+      try {
+        // The SDK resolves the values endpoint to a `Response`, not the value — read the body as text.
+        const response = await this.getClient().kv.namespaces.values.get(key, {
+          account_id: this.accountId,
+          namespace_id: this.namespaceId,
+        });
+        return await response.text();
+      } catch (error) {
+        // The REST API (and SDK) signal a missing key with a 404 throw, not a null resolve.
+        if (isNotFoundError(error)) return null;
+        throw error;
+      }
+    });
+  }
+
+  /** Read a key and `JSON.parse` it. Returns null when absent; throws on malformed JSON. */
+  async getJson<T = unknown>(key: string): Promise<T | null> {
+    const raw = await this.get(key);
+    if (raw === null) return null;
+    try {
+      return JSON.parse(raw) as T;
+    } 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: string, value: string, options?: KVPutOptions): Promise<void> {
+    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 !== undefined ? { expiration_ttl: options.expirationTtl } : {}),
+        ...(options?.metadata !== undefined ? { metadata: JSON.stringify(options.metadata) } : {}),
+      });
+    });
+  }
+
+  /** Delete a key. */
+  async delete(key: string): Promise<void> {
+    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?: string, limit?: number): Promise<Key[]> {
+    return cloudflareRequest("KV list keys", async () => {
+      const response = await this.getClient().kv.namespaces.keys.list(this.namespaceId, {
+        account_id: this.accountId,
+        ...(prefix !== undefined ? { prefix } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+      });
+      return response.result;
+    });
+  }
+
+  /** Read a key's value and metadata together. Both are null when absent. */
+  async getWithMetadata<M = unknown>(key: string): Promise<KVValueWithMetadata<M>> {
+    return cloudflareRequest(`KV getWithMetadata for key '${key}'`, async () => {
+      const [value, metadata] = await Promise.all([
+        // Reuse get()'s Response-unwrap + 404→null decode rather than re-deriving it here, and fetch
+        // the metadata in parallel. A missing key (or a key with no metadata) 404s on the metadata
+        // read; treat only that as absent. A real failure (auth, 5xx, network) is rethrown — never
+        // masked as "no metadata", which would let a caller mistake a fetch failure for an empty tag.
+        this.get(key),
+        this.getClient()
+          .kv.namespaces.metadata.get(key, { account_id: this.accountId, namespace_id: this.namespaceId })
+          .catch((error: unknown) => {
+            if (isNotFoundError(error)) return null;
+            throw error;
+          }),
+      ]);
+      return {
+        value,
+        metadata: (metadata as M | null) ?? 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: KVOperation[]): Promise<KVBatchResult[]> {
+    const results: KVBatchResult[] = [];
+    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(): { namespaceId: string; accountId: string } {
+    return { namespaceId: this.namespaceId, accountId: this.accountId };
+  }
+
+  getServiceType(): string {
+    return "KV Storage";
+  }
+
+  /** Prove access by reading the namespace record. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.getClient().kv.namespaces.get(this.namespaceId, { account_id: this.accountId });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}