@pithy-sh/cloudflare 0.1.0

package/src/client/errors.ts

@@ -0,0 +1,143 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+import type { z } from "zod";
+
+/**
+ * Cloudflare REST client throw sugar. The `cloudflare/*` codes live in core's closed
+ * `KitErrorPayload` union (CLAUDE.md §Errors: capabilities add their codes to the one union); these
+ * subclasses are the package-local vehicles that set one of those members — the same pattern as
+ * core's `NotFoundError`/`InternalError`, just owned here. Runtime code in this package throws
+ * one of these, never a plain `new Error`.
+ */
+
+/** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
+interface CloudflareErrorArgs {
+  /** Override the public, safe-to-expose message. */
+  message?: string;
+  /** A remediation hint (CLI action line). */
+  action?: string;
+  /** Internal context for logs + audit. Never serialized to clients. */
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`.
+   */
+  params?: MessageParams;
+}
+
+/** A required piece of configuration (token, account id, resource id) is missing. */
+export class CloudflareNotConfiguredError extends PithyError {
+  constructor(args: CloudflareErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "cloudflare/not_configured",
+        status: 500,
+        message: args.message ?? "The Cloudflare REST client is not fully configured.",
+        action: args.action ?? "Provide apiToken, accountId, and any required resource id.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** A call to the Cloudflare REST API failed (network error, 4xx/5xx from the API). */
+export class CloudflareRequestError extends PithyError {
+  constructor(args: CloudflareErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "cloudflare/request_failed",
+        status: 502,
+        message: args.message ?? "A Cloudflare REST API call failed.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** A Cloudflare REST API response did not match its expected shape (failed Zod validation). */
+export class CloudflareInvalidResponseError extends PithyError {
+  constructor(args: CloudflareErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "cloudflare/invalid_response",
+        status: 502,
+        message: args.message ?? "A Cloudflare REST API response had an unexpected shape.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * Run a Cloudflare SDK call and turn any failure into a `CloudflareRequestError`, preserving the
+ * original error as `cause` and its message as internal `detail`. `operation` names the call for
+ * the audit trail (`"KV get for key 'x'"`). A `PithyError` already in flight (e.g. a
+ * not-configured guard) passes through untouched — only foreign throws get wrapped.
+ */
+export async function cloudflareRequest<T>(operation: string, fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof PithyError) throw error;
+    throw new CloudflareRequestError(
+      { message: `Cloudflare request failed: ${operation}.`, detail: messageOf(error) },
+      { cause: error },
+    );
+  }
+}
+
+/** The raw message of an unknown throw, for use as a PithyError `detail`. One source of truth. */
+export function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * The most specific failure reason available, for a partial-failure report's `error` field: a
+ * `PithyError`'s internal `detail` (the real cause `cloudflareRequest` captured), else its public
+ * message, else the raw throw. Centralized so the detail-vs-message precedence lives in one place.
+ */
+export function reasonOf(error: unknown): string {
+  if (error instanceof PithyError) return error.payload.detail ?? error.payload.message;
+  return messageOf(error);
+}
+
+/** Whether a thrown SDK error is an HTTP 404 — the SDK throws on a missing resource, not null. */
+export function isNotFoundError(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as { status?: unknown }).status === 404;
+}
+
+/**
+ * Whether a thrown SDK error is an HTTP 403 — the token reached the API but lacks the permission for
+ * the operation. The signal a caller uses to turn a raw "Unauthorized" into an actionable
+ * "grant this permission group" message instead of a generic request failure.
+ */
+export function isAuthorizationError(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as { status?: unknown }).status === 403;
+}
+
+/**
+ * Decode a Cloudflare response against `schema`, throwing `cloudflare/invalid_response` on a shape
+ * mismatch. The decode counterpart to `cloudflareRequest`'s error wrapping — one seam so every
+ * manager validates the wire the same way instead of hand-rolling `safeParse` + throw.
+ */
+export function decodeResponse<T extends z.ZodType>(schema: T, raw: unknown, context: string): z.output<T> {
+  const parsed = schema.safeParse(raw);
+  if (!parsed.success) {
+    throw new CloudflareInvalidResponseError({
+      message: `A Cloudflare response had an unexpected shape: ${context}.`,
+      detail: parsed.error.message,
+    });
+  }
+  return parsed.data;
+}

package/src/client/manager.ts

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { Cloudflare } from "cloudflare";
+import type { Account } from "cloudflare/resources/accounts/accounts";
+import { CloudflareNotConfiguredError, cloudflareRequest } from "./errors";
+
+/**
+ * Configuration every manager shares. This is the whole surface: a scoped CF API token and the
+ * account it targets. The CMS managers also accepted Worker bindings (dual REST/binding mode);
+ * `@pithy-sh/cloudflare` is the *out-of-Worker* client (CLI, CI, provisioning), so it is REST-only
+ * — inside a Worker you use the binding directly (CLAUDE.md §Cloudflare access). One token, one
+ * account, no env coupling.
+ */
+export interface CloudflareManagerConfig {
+  /** A scoped, least-privilege CF API token (from `CLOUDFLARE_API_TOKEN`, minted per environment). */
+  apiToken: string;
+  /** The Cloudflare account id all operations target (`CLOUDFLARE_ACCOUNT_ID`). */
+  accountId: string;
+}
+
+/**
+ * Base for every Cloudflare resource manager. Holds the configured SDK client and account id, and
+ * carries the account-level operations shared across resources. Subclasses add one resource's REST
+ * operations and declare what they are (`getServiceType`) and how to prove access
+ * (`validateServiceAccess`).
+ */
+export abstract class CloudflareManager {
+  private readonly client: Cloudflare;
+
+  private readonly apiToken: string;
+
+  protected readonly accountId: string;
+
+  constructor(config: CloudflareManagerConfig) {
+    if (!config.apiToken) {
+      throw new CloudflareNotConfiguredError({ detail: "Missing apiToken in CloudflareManagerConfig." });
+    }
+    if (!config.accountId) {
+      throw new CloudflareNotConfiguredError({ detail: "Missing accountId in CloudflareManagerConfig." });
+    }
+    this.client = new Cloudflare({ apiToken: config.apiToken });
+    this.apiToken = config.apiToken;
+    this.accountId = config.accountId;
+  }
+
+  /** The configured SDK client. Subclasses route typed calls through this. */
+  protected getClient(): Cloudflare {
+    return this.client;
+  }
+
+  /**
+   * The raw API token, for subclasses that fall back to direct `fetch()` for endpoints the typed
+   * SDK does not cover (e.g. Workers Builds, event subscriptions). The documented escape hatch.
+   */
+  protected getApiToken(): string {
+    return this.apiToken;
+  }
+
+  /** The account id all operations target. */
+  protected getAccountId(): string {
+    return this.accountId;
+  }
+
+  /** Fetch the full account record. Wraps SDK failures as `cloudflare/request_failed`. */
+  async getAccountInfo(): Promise<Account> {
+    return cloudflareRequest("get account info", () => this.getClient().accounts.get({ account_id: this.accountId }));
+  }
+
+  /** Whether the credentials work, proved by a lightweight account read. Never throws. */
+  async validateCredentials(): Promise<boolean> {
+    try {
+      await this.getAccountInfo();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** A human label for the resource this manager owns (e.g. "KV Storage"). */
+  abstract getServiceType(): string;
+
+  /** Prove this manager can reach its specific resource. Never throws; returns false on failure. */
+  abstract validateServiceAccess(): Promise<boolean>;
+}

package/src/d1/d1Manager.ts

@@ -0,0 +1,171 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database, D1PreparedStatement, D1Result } from "@cloudflare/workers-types";
+import { InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { D1 } from "cloudflare/resources/d1/d1";
+import type { QueryResult } from "cloudflare/resources/d1/database";
+import { CloudflareNotConfiguredError, cloudflareRequest, reasonOf } from "../client/errors";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+import { D1PreparedStatementREST } from "./d1PreparedStatement";
+
+/** Config for the D1 manager: the shared client config plus the database it targets. */
+export interface D1ManagerConfig extends CloudflareManagerConfig {
+  /** The D1 database id (the REST API addresses databases by id). */
+  databaseId: string;
+}
+
+/** The per-query outcome of `batchQueries`: a partial-failure report, never a thrown batch. */
+export interface D1BatchResult {
+  /** The SQL this result is for. */
+  query: string;
+  /** Whether the query returned at least one result set. */
+  success: boolean;
+  /** The result sets, present only on success. */
+  result?: QueryResult[];
+  /** The failure reason, present only when `success` is false. */
+  error?: string;
+}
+
+/**
+ * Out-of-Worker D1 access over the REST API. It `implements D1Database`, so the same query builder
+ * a Worker runs against a binding runs from a CLI/CI context against D1 over REST — most
+ * importantly as the database behind a Kysely `D1Dialect` (kysely-d1), which is how `pithy migrate`
+ * promotes/rolls back schema remotely (issue #31). Inside a Worker you use the `D1Database` binding
+ * directly; this is the REST counterpart, addressed by database id.
+ */
+export class CloudflareD1Manager extends CloudflareManager implements D1Database {
+  private readonly databaseId: string;
+
+  constructor(config: D1ManagerConfig) {
+    super(config);
+    if (!config.databaseId) {
+      throw new CloudflareNotConfiguredError({ detail: "Missing databaseId for D1 REST access." });
+    }
+    this.databaseId = config.databaseId;
+  }
+
+  // --- D1Database surface (what Kysely's D1Dialect drives) ---
+
+  prepare(query: string): D1PreparedStatement {
+    return new D1PreparedStatementREST(query, this.getClient(), this.accountId, this.databaseId);
+  }
+
+  /**
+   * Run each statement and collect its result. **Not atomic:** unlike the Worker binding's `batch()`
+   * (which runs the statements in one transaction), the D1 REST API exposes no batch/transaction
+   * endpoint, so these execute as independent sequential queries — a mid-batch failure leaves earlier
+   * statements committed. D1 has no interactive transactions, and Kysely drives migrations through
+   * `prepare().all()` per statement rather than this method, so this affects only direct callers.
+   */
+  async batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]> {
+    const results: D1Result<T>[] = [];
+    for (const statement of statements) {
+      results.push(await (statement as D1PreparedStatementREST<T>).run<T>());
+    }
+    return results;
+  }
+
+  async exec(query: string): Promise<D1ExecResult> {
+    const response = await cloudflareRequest("D1 exec", () =>
+      this.getClient().d1.database.query(this.databaseId, { account_id: this.accountId, sql: query }),
+    );
+    const result = response.result[0];
+    return { count: result?.results?.length ?? 0, duration: result?.meta?.duration ?? 0 };
+  }
+
+  /** `dump()` is deprecated and has no REST equivalent — calling it is a programming error. */
+  async dump(): Promise<ArrayBuffer> {
+    throw new InternalError({ detail: "D1 dump() is not supported via the REST client." });
+  }
+
+  /** Sessions are a binding-only feature; the REST client has no equivalent. */
+  withSession(): never {
+    throw new InternalError({ detail: "D1 withSession() is not supported via the REST client." });
+  }
+
+  // --- REST convenience methods ---
+
+  /** Run one SQL statement and return its raw REST result sets. */
+  async executeQuery(sql: string, params?: string[]): Promise<QueryResult[]> {
+    const response = await cloudflareRequest("D1 query", () =>
+      this.getClient().d1.database.query(this.databaseId, { account_id: this.accountId, sql, params }),
+    );
+    return response.result;
+  }
+
+  /**
+   * Run many independent queries, collecting a per-query result instead of failing the whole batch
+   * on the first error — the caller decides what to do with partial failure.
+   */
+  async batchQueries(queries: Array<{ sql: string; params?: string[] }>): Promise<D1BatchResult[]> {
+    return Promise.all(
+      queries.map(async (query): Promise<D1BatchResult> => {
+        try {
+          const result = await this.executeQuery(query.sql, query.params);
+          return { query: query.sql, success: result.length > 0, result };
+        } catch (error) {
+          return { query: query.sql, success: false, error: reasonOf(error) };
+        }
+      }),
+    );
+  }
+
+  /** Fetch the D1 database record. */
+  async getDatabaseInfo(): Promise<D1> {
+    return cloudflareRequest("get D1 database info", () =>
+      this.getClient().d1.database.get(this.databaseId, { account_id: this.accountId }),
+    );
+  }
+
+  /** List the user tables in the database. */
+  async listTables(): Promise<string[]> {
+    const result = await this.executeQuery("SELECT name FROM sqlite_master WHERE type='table'");
+    return result
+      .flatMap((queryResult) => (queryResult.results ?? []) as unknown[])
+      .map((row) => (isNamedRow(row) ? row.name : undefined))
+      .filter((name): name is string => typeof name === "string");
+  }
+
+  /**
+   * Read a table's column schema via `PRAGMA table_info`. SQLite pragmas take no bind parameters, so
+   * the table name is interpolated — guard it against a strict identifier allowlist first, so the one
+   * un-parameterized SQL path in this client can never become an injection sink.
+   */
+  async getTableSchema(tableName: string): Promise<unknown[]> {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tableName)) {
+      throw new ValidationError({
+        message: "Invalid table name.",
+        detail: `Table name must be a plain SQL identifier, got: ${tableName}`,
+      });
+    }
+    const result = await this.executeQuery(`PRAGMA table_info(${tableName})`);
+    return result.flatMap((queryResult) => (queryResult.results ?? []) as unknown[]);
+  }
+
+  /** The database this manager targets and the account it lives in. */
+  getD1Info(): { databaseId: string; accountId: string } {
+    return { databaseId: this.databaseId, accountId: this.accountId };
+  }
+
+  getServiceType(): string {
+    return "D1 Database";
+  }
+
+  /** Prove access by reading the database record. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.getDatabaseInfo();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/** Narrow a result row to one carrying a string `name` column (the `sqlite_master` shape). */
+function isNamedRow(row: unknown): row is { name: string } {
+  return (
+    typeof row === "object" && row !== null && "name" in row && typeof (row as { name: unknown }).name === "string"
+  );
+}

package/src/d1/d1PreparedStatement.ts

@@ -0,0 +1,114 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Meta, D1PreparedStatement, D1Result } from "@cloudflare/workers-types";
+import type { Cloudflare } from "cloudflare";
+import type { QueryResult } from "cloudflare/resources/d1/database";
+import { cloudflareRequest } from "../client/errors";
+
+/**
+ * A `D1PreparedStatement` backed by the D1 REST API instead of a Worker binding. It mirrors the
+ * binding's prepared-statement surface (`bind`/`run`/`all`/`first`/`raw`) closely enough that a
+ * Kysely `D1Dialect` (kysely-d1) can drive it unchanged — which is how `pithy migrate` runs the
+ * same query builder from a CLI/CI context against D1 over REST (issue #31).
+ *
+ * `D1PreparedStatement` and `D1Meta` are imported by name from `@cloudflare/workers-types`, so this
+ * class is structurally a drop-in for the binding's statement. They used to be named off the global
+ * scope, which resolved only because this package's own `tsconfig.json` loads the types — and every
+ * package here ships raw TypeScript, so an adopter compiling this file got `Cannot find name` unless
+ * their program happened to pull the types in too. Importing them is what makes the dependency real
+ * (#431).
+ */
+function mapMeta(restMeta?: QueryResult.Meta): D1Meta & Record<string, unknown> {
+  return {
+    duration: restMeta?.duration ?? 0,
+    size_after: restMeta?.size_after ?? 0,
+    rows_read: restMeta?.rows_read ?? 0,
+    rows_written: restMeta?.rows_written ?? 0,
+    last_row_id: restMeta?.last_row_id ?? 0,
+    changed_db: restMeta?.changed_db ?? false,
+    changes: restMeta?.changes ?? 0,
+  };
+}
+
+/** The REST `params` array is strings; coerce each bound value the way the D1 REST API expects. */
+function toStringParams(params: unknown[]): string[] {
+  return params.map((value) => {
+    if (value === null || value === undefined) return "";
+    if (typeof value === "string") return value;
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+    return JSON.stringify(value);
+  });
+}
+
+export class D1PreparedStatementREST<T = Record<string, unknown>> implements D1PreparedStatement {
+  private readonly sql: string;
+
+  private readonly boundParams: unknown[];
+
+  private readonly client: Cloudflare;
+
+  private readonly accountId: string;
+
+  private readonly databaseId: string;
+
+  constructor(sql: string, client: Cloudflare, accountId: string, databaseId: string, boundParams: unknown[] = []) {
+    this.sql = sql;
+    this.boundParams = boundParams;
+    this.client = client;
+    this.accountId = accountId;
+    this.databaseId = databaseId;
+  }
+
+  /** Bind positional parameters, returning a new statement (the binding's immutable contract). */
+  bind(...values: unknown[]): D1PreparedStatementREST<T> {
+    return new D1PreparedStatementREST<T>(this.sql, this.client, this.accountId, this.databaseId, values);
+  }
+
+  run<U = T>(): Promise<D1Result<U>> {
+    return this.executeQuery<U>();
+  }
+
+  all<U = T>(): Promise<D1Result<U>> {
+    return this.executeQuery<U>();
+  }
+
+  async first<U = unknown>(colName: string): Promise<U | null>;
+  async first<U = T>(): Promise<U | null>;
+  async first<U = unknown>(colName?: string): Promise<U | null> {
+    const result = await this.executeQuery<Record<string, unknown>>();
+    const row = result.results[0] ?? null;
+    if (row === null) return null;
+    if (colName) return (row[colName] as U) ?? null;
+    return row as U;
+  }
+
+  async raw<U = unknown[]>(options: { columnNames: true }): Promise<[string[], ...U[]]>;
+  async raw<U = unknown[]>(options?: { columnNames?: false }): Promise<U[]>;
+  async raw<U = unknown[]>(options?: { columnNames?: boolean }): Promise<U[] | [string[], ...U[]]> {
+    const params = this.boundParams.length > 0 ? toStringParams(this.boundParams) : undefined;
+    const response = await cloudflareRequest("D1 raw query", () =>
+      this.client.d1.database.raw(this.databaseId, { account_id: this.accountId, sql: this.sql, params }),
+    );
+    const rawResult = response.result[0];
+    const rows = (rawResult?.results?.rows ?? []) as U[];
+    if (options?.columnNames) {
+      const columns = rawResult?.results?.columns ?? [];
+      return [columns, ...rows];
+    }
+    return rows;
+  }
+
+  private async executeQuery<U>(): Promise<D1Result<U>> {
+    const params = this.boundParams.length > 0 ? toStringParams(this.boundParams) : undefined;
+    const response = await cloudflareRequest("D1 query", () =>
+      this.client.d1.database.query(this.databaseId, { account_id: this.accountId, sql: this.sql, params }),
+    );
+    const queryResult = response.result[0];
+    return {
+      success: true,
+      meta: mapMeta(queryResult?.meta),
+      results: (queryResult?.results ?? []) as U[],
+    };
+  }
+}

package/src/d1/d1Provisioner.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { cloudflareRequest, decodeResponse } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/** A D1 database's identity, decoded from the create response. */
+export const D1DatabaseInfo = z
+  .object({
+    uuid: z.string().describe("The CF-assigned database id (a uuid) used to address the database."),
+    name: z.string().describe("The database name."),
+  })
+  .describe("A Cloudflare D1 database's identity, as returned by the create endpoint.");
+export type D1DatabaseInfo = z.output<typeof D1DatabaseInfo>;
+
+/**
+ * Account-level D1 control plane: **create and delete databases**. Customers use this to stand up
+ * and tear down per-environment databases (e.g. ephemeral staging), and `pithy add secrets` uses it
+ * to provision each environment's secrets D1. Addressed by account — unlike {@link CloudflareD1Manager},
+ * which targets one database id for queries.
+ */
+export class CloudflareD1Provisioner extends CloudflareManager {
+  getServiceType(): string {
+    return "Cloudflare D1 (control plane)";
+  }
+
+  /** Prove access by listing databases — a read, never a destructive create/delete. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.getClient().d1.database.list({ account_id: this.accountId });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Every D1 database in the account — for prefix-scan reconcile teardown (`pithy feature destroy`). */
+  async listDatabases(): Promise<D1DatabaseInfo[]> {
+    return cloudflareRequest("list D1 databases", async () => {
+      const databases: D1DatabaseInfo[] = [];
+      for await (const db of this.getClient().d1.database.list({ account_id: this.accountId })) {
+        const parsed = D1DatabaseInfo.safeParse(db);
+        if (parsed.success) databases.push(parsed.data);
+      }
+      return databases;
+    });
+  }
+
+  /** Find a database by exact name in the account, or `null` — for idempotent provisioning. */
+  async findDatabaseByName(name: string): Promise<D1DatabaseInfo | null> {
+    return cloudflareRequest(`find D1 database ${name}`, async () => {
+      for await (const db of this.getClient().d1.database.list({ account_id: this.accountId, name })) {
+        const parsed = D1DatabaseInfo.safeParse(db);
+        if (parsed.success && parsed.data.name === name) return parsed.data;
+      }
+      return null;
+    });
+  }
+
+  /** Create a D1 database by name; returns its id and name. */
+  async createDatabase(name: string): Promise<D1DatabaseInfo> {
+    const response = await cloudflareRequest(`create D1 database ${name}`, () =>
+      this.getClient().d1.database.create({ account_id: this.accountId, name }),
+    );
+    return decodeResponse(D1DatabaseInfo, response, "D1 database create");
+  }
+
+  /** Delete a D1 database by id. */
+  async deleteDatabase(databaseId: string): Promise<void> {
+    await cloudflareRequest(`delete D1 database ${databaseId}`, () =>
+      this.getClient().d1.database.delete(databaseId, { account_id: this.accountId }),
+    );
+  }
+}