@pithy-sh/cloudflare 0.1.2 → 0.1.4

package/dist/client/errors.d.ts

@@ -0,0 +1,75 @@
+// 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 declare class CloudflareNotConfiguredError extends PithyError {
+    constructor(args?: CloudflareErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/** A call to the Cloudflare REST API failed (network error, 4xx/5xx from the API). */
+export declare class CloudflareRequestError extends PithyError {
+    constructor(args?: CloudflareErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/** A Cloudflare REST API response did not match its expected shape (failed Zod validation). */
+export declare class CloudflareInvalidResponseError extends PithyError {
+    constructor(args?: CloudflareErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare function cloudflareRequest<T>(operation: string, fn: () => Promise<T>): Promise<T>;
+/** The raw message of an unknown throw, for use as a PithyError `detail`. One source of truth. */
+export declare function messageOf(error: unknown): string;
+/**
+ * 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 declare function reasonOf(error: unknown): string;
+/** Whether a thrown SDK error is an HTTP 404 — the SDK throws on a missing resource, not null. */
+export declare function isNotFoundError(error: unknown): boolean;
+/**
+ * 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 declare function isAuthorizationError(error: unknown): boolean;
+/**
+ * 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 declare function decodeResponse<T extends z.ZodType>(schema: T, raw: unknown, context: string): z.output<T>;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/client/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;GAMG;AAEH,uFAAuF;AACvF,UAAU,mBAAmB;IAC3B,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,qFAAqF;AACrF,qBAAa,4BAA6B,SAAQ,UAAU;IAC1D,YAAY,IAAI,GAAE,mBAAwB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYxE;CACF;AAED,sFAAsF;AACtF,qBAAa,sBAAuB,SAAQ,UAAU;IACpD,YAAY,IAAI,GAAE,mBAAwB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYxE;CACF;AAED,+FAA+F;AAC/F,qBAAa,8BAA+B,SAAQ,UAAU;IAC5D,YAAY,IAAI,GAAE,mBAAwB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYxE;CACF;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAU9F;AAED,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAG/C;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CASzG"}

package/dist/client/errors.js

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/client/errors.ts
+/** A required piece of configuration (token, account id, resource id) is missing. */
+var CloudflareNotConfiguredError = class extends PithyError {
+	constructor(args = {}, options) {
+		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). */
+var CloudflareRequestError = class extends PithyError {
+	constructor(args = {}, options) {
+		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). */
+var CloudflareInvalidResponseError = class extends PithyError {
+	constructor(args = {}, options) {
+		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.
+*/
+async function cloudflareRequest(operation, fn) {
+	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. */
+function messageOf(error) {
+	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.
+*/
+function reasonOf(error) {
+	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. */
+function isNotFoundError(error) {
+	return typeof error === "object" && error !== null && error.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.
+*/
+function isAuthorizationError(error) {
+	return typeof error === "object" && error !== null && error.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.
+*/
+function decodeResponse(schema, raw, context) {
+	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;
+}
+//#endregion
+export { CloudflareInvalidResponseError, CloudflareNotConfiguredError, CloudflareRequestError, cloudflareRequest, decodeResponse, isAuthorizationError, isNotFoundError, messageOf, reasonOf };

package/dist/client/manager.d.ts

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { Cloudflare } from "cloudflare";
+import type { Account } from "cloudflare/resources/accounts/accounts";
+/**
+ * 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 declare abstract class CloudflareManager {
+    private readonly client;
+    private readonly apiToken;
+    protected readonly accountId: string;
+    constructor(config: CloudflareManagerConfig);
+    /** The configured SDK client. Subclasses route typed calls through this. */
+    protected getClient(): Cloudflare;
+    /**
+     * 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;
+    /** The account id all operations target. */
+    protected getAccountId(): string;
+    /** Fetch the full account record. Wraps SDK failures as `cloudflare/request_failed`. */
+    getAccountInfo(): Promise<Account>;
+    /** Whether the credentials work, proved by a lightweight account read. Never throws. */
+    validateCredentials(): Promise<boolean>;
+    /** 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>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/client/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/client/manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wCAAwC,CAAC;AAGtE;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,oGAAoG;IACpG,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,8BAAsB,iBAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAErC,YAAY,MAAM,EAAE,uBAAuB,EAU1C;IAED,4EAA4E;IAC5E,SAAS,CAAC,SAAS,IAAI,UAAU,CAEhC;IAED;;;OAGG;IACH,SAAS,CAAC,WAAW,IAAI,MAAM,CAE9B;IAED,4CAA4C;IAC5C,SAAS,CAAC,YAAY,IAAI,MAAM,CAE/B;IAED,wFAAwF;IAClF,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAEvC;IAED,wFAAwF;IAClF,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO5C;IAED,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,IAAI,MAAM,CAAC;IAElC,kGAAkG;IAClG,QAAQ,CAAC,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD"}

package/dist/client/manager.js

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareNotConfiguredError, cloudflareRequest } from "./errors.js";
+import { Cloudflare } from "cloudflare";
+//#region src/client/manager.ts
+/**
+* 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`).
+*/
+var CloudflareManager = class {
+	client;
+	apiToken;
+	accountId;
+	constructor(config) {
+		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. */
+	getClient() {
+		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.
+	*/
+	getApiToken() {
+		return this.apiToken;
+	}
+	/** The account id all operations target. */
+	getAccountId() {
+		return this.accountId;
+	}
+	/** Fetch the full account record. Wraps SDK failures as `cloudflare/request_failed`. */
+	async getAccountInfo() {
+		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() {
+		try {
+			await this.getAccountInfo();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { CloudflareManager };

package/dist/d1/d1Manager.d.ts

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { D1Database, D1PreparedStatement, D1Result } from "@cloudflare/workers-types";
+import type { D1 } from "cloudflare/resources/d1/d1";
+import type { QueryResult } from "cloudflare/resources/d1/database";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+/** 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 declare class CloudflareD1Manager extends CloudflareManager implements D1Database {
+    private readonly databaseId;
+    constructor(config: D1ManagerConfig);
+    prepare(query: string): D1PreparedStatement;
+    /**
+     * 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.
+     */
+    batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
+    exec(query: string): Promise<D1ExecResult>;
+    /** `dump()` is deprecated and has no REST equivalent — calling it is a programming error. */
+    dump(): Promise<ArrayBuffer>;
+    /** Sessions are a binding-only feature; the REST client has no equivalent. */
+    withSession(): never;
+    /** Run one SQL statement and return its raw REST result sets. */
+    executeQuery(sql: string, params?: string[]): Promise<QueryResult[]>;
+    /**
+     * 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.
+     */
+    batchQueries(queries: Array<{
+        sql: string;
+        params?: string[];
+    }>): Promise<D1BatchResult[]>;
+    /** Fetch the D1 database record. */
+    getDatabaseInfo(): Promise<D1>;
+    /** List the user tables in the database. */
+    listTables(): Promise<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.
+     */
+    getTableSchema(tableName: string): Promise<unknown[]>;
+    /** The database this manager targets and the account it lives in. */
+    getD1Info(): {
+        databaseId: string;
+        accountId: string;
+    };
+    getServiceType(): string;
+    /** Prove access by reading the database record. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+}
+//# sourceMappingURL=d1Manager.d.ts.map

package/dist/d1/d1Manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1Manager.d.ts","sourceRoot":"","sources":["../../src/d1/d1Manager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE3F,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAGpF,wFAAwF;AACxF,MAAM,WAAW,eAAgB,SAAQ,uBAAuB;IAC9D,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,iBAAkB,YAAW,UAAU;IAC9E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YAAY,MAAM,EAAE,eAAe,EAMlC;IAID,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,CAE1C;IAED;;;;;;OAMG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAMlF;IAEK,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAM/C;IAED,6FAA6F;IACvF,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,CAEjC;IAED,8EAA8E;IAC9E,WAAW,IAAI,KAAK,CAEnB;IAID,iEAAiE;IAC3D,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAKzE;IAED;;;OAGG;IACG,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAW/F;IAED,oCAAoC;IAC9B,eAAe,IAAI,OAAO,CAAC,EAAE,CAAC,CAInC;IAED,4CAA4C;IACtC,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAMpC;IAED;;;;OAIG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAS1D;IAED,qEAAqE;IACrE,SAAS,IAAI;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAErD;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,iEAAiE;IAC3D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}

package/dist/d1/d1Manager.js

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareNotConfiguredError, cloudflareRequest, reasonOf } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { D1PreparedStatementREST } from "./d1PreparedStatement.js";
+import { InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/d1/d1Manager.ts
+/**
+* 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.
+*/
+var CloudflareD1Manager = class extends CloudflareManager {
+	databaseId;
+	constructor(config) {
+		super(config);
+		if (!config.databaseId) throw new CloudflareNotConfiguredError({ detail: "Missing databaseId for D1 REST access." });
+		this.databaseId = config.databaseId;
+	}
+	prepare(query) {
+		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(statements) {
+		const results = [];
+		for (const statement of statements) results.push(await statement.run());
+		return results;
+	}
+	async exec(query) {
+		const result = (await cloudflareRequest("D1 exec", () => this.getClient().d1.database.query(this.databaseId, {
+			account_id: this.accountId,
+			sql: query
+		}))).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() {
+		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() {
+		throw new InternalError({ detail: "D1 withSession() is not supported via the REST client." });
+	}
+	/** Run one SQL statement and return its raw REST result sets. */
+	async executeQuery(sql, params) {
+		return (await cloudflareRequest("D1 query", () => this.getClient().d1.database.query(this.databaseId, {
+			account_id: this.accountId,
+			sql,
+			params
+		}))).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) {
+		return Promise.all(queries.map(async (query) => {
+			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() {
+		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() {
+		return (await this.executeQuery("SELECT name FROM sqlite_master WHERE type='table'")).flatMap((queryResult) => queryResult.results ?? []).map((row) => isNamedRow(row) ? row.name : void 0).filter((name) => 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) {
+		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}`
+		});
+		return (await this.executeQuery(`PRAGMA table_info(${tableName})`)).flatMap((queryResult) => queryResult.results ?? []);
+	}
+	/** The database this manager targets and the account it lives in. */
+	getD1Info() {
+		return {
+			databaseId: this.databaseId,
+			accountId: this.accountId
+		};
+	}
+	getServiceType() {
+		return "D1 Database";
+	}
+	/** Prove access by reading the database record. Never throws. */
+	async validateServiceAccess() {
+		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) {
+	return typeof row === "object" && row !== null && "name" in row && typeof row.name === "string";
+}
+//#endregion
+export { CloudflareD1Manager };

package/dist/d1/d1PreparedStatement.d.ts

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { D1PreparedStatement, D1Result } from "@cloudflare/workers-types";
+import type { Cloudflare } from "cloudflare";
+export declare class D1PreparedStatementREST<T = Record<string, unknown>> implements D1PreparedStatement {
+    private readonly sql;
+    private readonly boundParams;
+    private readonly client;
+    private readonly accountId;
+    private readonly databaseId;
+    constructor(sql: string, client: Cloudflare, accountId: string, databaseId: string, boundParams?: unknown[]);
+    /** Bind positional parameters, returning a new statement (the binding's immutable contract). */
+    bind(...values: unknown[]): D1PreparedStatementREST<T>;
+    run<U = T>(): Promise<D1Result<U>>;
+    all<U = T>(): Promise<D1Result<U>>;
+    first<U = unknown>(colName: string): Promise<U | null>;
+    first<U = T>(): Promise<U | null>;
+    raw<U = unknown[]>(options: {
+        columnNames: true;
+    }): Promise<[string[], ...U[]]>;
+    raw<U = unknown[]>(options?: {
+        columnNames?: false;
+    }): Promise<U[]>;
+    private executeQuery;
+}
+//# sourceMappingURL=d1PreparedStatement.d.ts.map

package/dist/d1/d1PreparedStatement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1PreparedStatement.d.ts","sourceRoot":"","sources":["../../src/d1/d1PreparedStatement.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAU,mBAAmB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAuC7C,qBAAa,uBAAuB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,mBAAmB;IAC9F,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAY;IAExC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YAAY,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAE,OAAO,EAAO,EAM9G;IAED,gGAAgG;IAChG,IAAI,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAErD;IAED,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAEjC;IAED,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAEjC;IAEK,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvD,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IASlC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,OAAO,EAAE;QAAE,WAAW,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAChF,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;YAe5D,YAAY;CAY3B"}

package/dist/d1/d1PreparedStatement.js

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { cloudflareRequest } from "../client/errors.js";
+//#region src/d1/d1PreparedStatement.ts
+/**
+* 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) {
+	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) {
+	return params.map((value) => {
+		if (value === null || value === void 0) return "";
+		if (typeof value === "string") return value;
+		if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+		return JSON.stringify(value);
+	});
+}
+var D1PreparedStatementREST = class D1PreparedStatementREST {
+	sql;
+	boundParams;
+	client;
+	accountId;
+	databaseId;
+	constructor(sql, client, accountId, databaseId, boundParams = []) {
+		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) {
+		return new D1PreparedStatementREST(this.sql, this.client, this.accountId, this.databaseId, values);
+	}
+	run() {
+		return this.executeQuery();
+	}
+	all() {
+		return this.executeQuery();
+	}
+	async first(colName) {
+		const row = (await this.executeQuery()).results[0] ?? null;
+		if (row === null) return null;
+		if (colName) return row[colName] ?? null;
+		return row;
+	}
+	async raw(options) {
+		const params = this.boundParams.length > 0 ? toStringParams(this.boundParams) : void 0;
+		const rawResult = (await cloudflareRequest("D1 raw query", () => this.client.d1.database.raw(this.databaseId, {
+			account_id: this.accountId,
+			sql: this.sql,
+			params
+		}))).result[0];
+		const rows = rawResult?.results?.rows ?? [];
+		if (options?.columnNames) return [rawResult?.results?.columns ?? [], ...rows];
+		return rows;
+	}
+	async executeQuery() {
+		const params = this.boundParams.length > 0 ? toStringParams(this.boundParams) : void 0;
+		const queryResult = (await cloudflareRequest("D1 query", () => this.client.d1.database.query(this.databaseId, {
+			account_id: this.accountId,
+			sql: this.sql,
+			params
+		}))).result[0];
+		return {
+			success: true,
+			meta: mapMeta(queryResult?.meta),
+			results: queryResult?.results ?? []
+		};
+	}
+};
+//#endregion
+export { D1PreparedStatementREST };

package/dist/d1/d1Provisioner.d.ts

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+/** A D1 database's identity, decoded from the create response. */
+export declare const D1DatabaseInfo: z.ZodObject<{
+    uuid: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+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 declare class CloudflareD1Provisioner extends CloudflareManager {
+    getServiceType(): string;
+    /** Prove access by listing databases — a read, never a destructive create/delete. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /** Every D1 database in the account — for prefix-scan reconcile teardown (`pithy feature destroy`). */
+    listDatabases(): Promise<D1DatabaseInfo[]>;
+    /** Find a database by exact name in the account, or `null` — for idempotent provisioning. */
+    findDatabaseByName(name: string): Promise<D1DatabaseInfo | null>;
+    /** Create a D1 database by name; returns its id and name. */
+    createDatabase(name: string): Promise<D1DatabaseInfo>;
+    /** Delete a D1 database by id. */
+    deleteDatabase(databaseId: string): Promise<void>;
+}
+//# sourceMappingURL=d1Provisioner.d.ts.map

package/dist/d1/d1Provisioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1Provisioner.d.ts","sourceRoot":"","sources":["../../src/d1/d1Provisioner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,kEAAkE;AAClE,eAAO,MAAM,cAAc;;;iBAK4D,CAAC;AACxF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,iBAAiB;IAC5D,cAAc,IAAI,MAAM,CAEvB;IAED,mGAAmG;IAC7F,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED,uGAAuG;IACjG,aAAa,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAS/C;IAED,6FAA6F;IACvF,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAQrE;IAED,6DAA6D;IACvD,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAK1D;IAED,kCAAkC;IAC5B,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAItD;CACF"}