@pithy-sh/cloudflare 0.1.2 → 0.1.4

package/dist/r2/r2Provisioner.d.ts

@@ -0,0 +1,41 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+/** An R2 bucket's identity, decoded from the create/list response. Buckets are addressed by name, not id. */
+export declare const R2BucketInfo: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+export type R2BucketInfo = z.output<typeof R2BucketInfo>;
+/**
+ * Account-level R2 control plane: **create and delete buckets**. Customers use this to stand up and
+ * tear down per-environment buckets (e.g. ephemeral staging), and worktree teardown uses it to
+ * reconcile/prune feature-scoped buckets. Unlike {@link CloudflareR2Manager}, which operates within
+ * one already-provisioned bucket (presigned object URLs), this manager is account-scoped and
+ * addresses buckets **by name** — R2 buckets carry no separate uuid id the way D1 databases do.
+ */
+export declare class CloudflareR2Provisioner extends CloudflareManager {
+    getServiceType(): string;
+    /** Prove access by listing buckets — a read, never a destructive create/delete. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /** Find a bucket by exact name in the account, or `null` — for idempotent provisioning. */
+    findBucketByName(name: string): Promise<R2BucketInfo | null>;
+    /**
+     * List every bucket in the account. R2's bucket list is cursor-paginated (a single call returns only
+     * one page, unlike D1/KV whose SDK list auto-paginates), so this drains every page via `start_after` —
+     * the name of the last bucket seen — until a page comes back empty, then returns them all. Skips entries
+     * with no name.
+     */
+    listBuckets(): Promise<R2BucketInfo[]>;
+    /** Create an R2 bucket by name; returns its name. */
+    createBucket(name: string): Promise<R2BucketInfo>;
+    /**
+     * Delete an R2 bucket by name. Idempotent — a missing bucket is not an error, so teardown can re-run safely.
+     *
+     * **The bucket must already be empty.** R2 rejects the delete otherwise, and "empty" includes multipart
+     * uploads that were never completed — parts nothing in this control plane can even see. Emptying is an
+     * S3-protocol operation: call `CloudflareR2Manager.emptyBucket` first, which needs the S3 key pair.
+     */
+    deleteBucket(name: string): Promise<void>;
+}
+//# sourceMappingURL=r2Provisioner.d.ts.map

package/dist/r2/r2Provisioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2Provisioner.d.ts","sourceRoot":"","sources":["../../src/r2/r2Provisioner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,6GAA6G;AAC7G,eAAO,MAAM,YAAY;;iBAIkE,CAAC;AAC5F,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,iBAAiB;IAC5D,cAAc,IAAI,MAAM,CAEvB;IAED,iGAAiG;IAC3F,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED,2FAA2F;IACrF,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAGjE;IAED;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAsB3C;IAED,qDAAqD;IAC/C,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAKtD;IAED;;;;;;OAMG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS9C;CACF"}

package/dist/r2/r2Provisioner.js

@@ -0,0 +1,88 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { cloudflareRequest, decodeResponse, isNotFoundError } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
+//#region src/r2/r2Provisioner.ts
+/** An R2 bucket's identity, decoded from the create/list response. Buckets are addressed by name, not id. */
+const R2BucketInfo = z.object({ name: z.string().describe("The bucket name — R2's sole address for a bucket (no separate uuid id).") }).describe("A Cloudflare R2 bucket's identity, as returned by the create/list endpoints.");
+/**
+* Account-level R2 control plane: **create and delete buckets**. Customers use this to stand up and
+* tear down per-environment buckets (e.g. ephemeral staging), and worktree teardown uses it to
+* reconcile/prune feature-scoped buckets. Unlike {@link CloudflareR2Manager}, which operates within
+* one already-provisioned bucket (presigned object URLs), this manager is account-scoped and
+* addresses buckets **by name** — R2 buckets carry no separate uuid id the way D1 databases do.
+*/
+var CloudflareR2Provisioner = class extends CloudflareManager {
+	getServiceType() {
+		return "Cloudflare R2 (control plane)";
+	}
+	/** Prove access by listing buckets — a read, never a destructive create/delete. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.getClient().r2.buckets.list({ account_id: this.accountId });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** Find a bucket by exact name in the account, or `null` — for idempotent provisioning. */
+	async findBucketByName(name) {
+		return (await this.listBuckets()).find((bucket) => bucket.name === name) ?? null;
+	}
+	/**
+	* List every bucket in the account. R2's bucket list is cursor-paginated (a single call returns only
+	* one page, unlike D1/KV whose SDK list auto-paginates), so this drains every page via `start_after` —
+	* the name of the last bucket seen — until a page comes back empty, then returns them all. Skips entries
+	* with no name.
+	*/
+	async listBuckets() {
+		return cloudflareRequest("list R2 buckets", async () => {
+			const buckets = [];
+			let startAfter;
+			for (;;) {
+				const page = (await this.getClient().r2.buckets.list({
+					account_id: this.accountId,
+					per_page: 1e3,
+					...startAfter ? { start_after: startAfter } : {}
+				})).buckets ?? [];
+				if (page.length === 0) break;
+				for (const bucket of page) {
+					const parsed = R2BucketInfo.safeParse(bucket);
+					if (parsed.success) buckets.push(parsed.data);
+				}
+				const last = page[page.length - 1]?.name;
+				if (!last || last === startAfter) break;
+				startAfter = last;
+			}
+			return buckets;
+		});
+	}
+	/** Create an R2 bucket by name; returns its name. */
+	async createBucket(name) {
+		const response = await cloudflareRequest(`create R2 bucket ${name}`, () => this.getClient().r2.buckets.create({
+			account_id: this.accountId,
+			name
+		}));
+		return decodeResponse(R2BucketInfo, response, "R2 bucket create");
+	}
+	/**
+	* Delete an R2 bucket by name. Idempotent — a missing bucket is not an error, so teardown can re-run safely.
+	*
+	* **The bucket must already be empty.** R2 rejects the delete otherwise, and "empty" includes multipart
+	* uploads that were never completed — parts nothing in this control plane can even see. Emptying is an
+	* S3-protocol operation: call `CloudflareR2Manager.emptyBucket` first, which needs the S3 key pair.
+	*/
+	async deleteBucket(name) {
+		await cloudflareRequest(`delete R2 bucket ${name}`, async () => {
+			try {
+				await this.getClient().r2.buckets.delete(name, { account_id: this.accountId });
+			} catch (error) {
+				if (isNotFoundError(error)) return;
+				throw error;
+			}
+		});
+	}
+};
+//#endregion
+export { CloudflareR2Provisioner, R2BucketInfo };

package/dist/secrets/secretsStoreManager.d.ts

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+/**
+ * One secret in the store, decoded from the CF list response. CF Secrets Store never returns
+ * plaintext over REST — values are bind-only by design — so this carries only metadata. The
+ * `created`/`modified` ISO strings decode through `JsonDate` to real `Date`s at the wire boundary.
+ */
+export declare const CfSecretEntry: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        deleted: "deleted";
+        pending: "pending";
+    }>;
+    created: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    modified: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type CfSecretEntry = z.output<typeof CfSecretEntry>;
+/** Config for the Secrets Store manager: the shared client config plus the store it targets. */
+export interface SecretsStoreManagerConfig extends CloudflareManagerConfig {
+    /** The CF Secrets Store id (the REST API addresses stores by id). */
+    storeId: string;
+}
+/**
+ * Out-of-Worker access to the account-level Cloudflare Secrets Store over the REST API: provisioning
+ * and audit from a CLI/CI context. Inside a Worker, secret values resolve via bindings — this manager
+ * is the REST counterpart for managing the store, addressed by store id.
+ *
+ * CF Secrets Store does not expose secret plaintext via REST (values are bind-only by design), so
+ * there is no `getSecret`. The provisioning and audit flows only need put, delete, and list.
+ */
+export declare class CloudflareSecretsStoreManager extends CloudflareManager {
+    private readonly storeId;
+    constructor(config: SecretsStoreManagerConfig);
+    getServiceType(): string;
+    /** Prove access by listing the store's secrets. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /**
+     * Insert or update a secret. An existing entry is updated in place via `edit`; otherwise a fresh
+     * secret is created.
+     *
+     * `edit` is what makes this safe. The old value is overwritten, never deleted first, so a failed
+     * update leaves the prior value intact and bound — there is no window where the secret is absent
+     * from the store (which, for a secret like the master encryption key, is a platform-level outage).
+     * Scopes are re-sent so an entry converges on the same shape whichever branch wrote it.
+     */
+    putSecret(name: string, value: string): Promise<void>;
+    /** Delete a secret by name. Resolves the id via `listSecrets`, then issues DELETE by id. */
+    deleteSecret(name: string): Promise<void>;
+    /**
+     * Delete a secret, treating an absent one as already done.
+     *
+     * The typed not-found on {@link deleteSecret} is right for a caller that named a specific secret and
+     * needs to hear it was not there. It is wrong for anything reconciling toward absence — teardown, a
+     * reaper, a re-run of a provisioning step — where "gone" is the goal and a second delete is a no-op,
+     * not a failure. Two callers race on the store all the time: another runner's sweep, or a listing that
+     * has not caught up.
+     *
+     * Given as its own method rather than a flag, so which semantics a call site wants is legible at the
+     * call site. The alternative every caller reaches for otherwise is `.catch(() => {})`, which also
+     * swallows the auth failure and the outage — and a teardown that swallows is how debris becomes
+     * permanent with no signal at all.
+     */
+    deleteSecretIfPresent(name: string): Promise<boolean>;
+    /**
+     * List every secret in the store. The SDK auto-paginates via `for await`, so callers receive the
+     * full set in one array. Each entry is Zod-validated (`CfSecretEntry`) at the wire boundary.
+     */
+    listSecrets(): Promise<CfSecretEntry[]>;
+    /** Whether a secret with the given name currently exists in the store. */
+    exists(name: string): Promise<boolean>;
+    /** The store this manager targets and the account it lives in. */
+    getSecretsStoreInfo(): {
+        storeId: string;
+        accountId: string;
+    };
+    /** Create a single secret with the default scopes. */
+    private createSecret;
+    private findByName;
+}
+//# sourceMappingURL=secretsStoreManager.d.ts.map

package/dist/secrets/secretsStoreManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secretsStoreManager.d.ts","sourceRoot":"","sources":["../../src/secrets/secretsStoreManager.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAKpF;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;iBAQqE,CAAC;AAChG,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,gGAAgG;AAChG,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACxE,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,iBAAiB;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,YAAY,MAAM,EAAE,yBAAyB,EAM5C;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,iEAAiE;IAC3D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;;OAQG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1D;IAED,4FAA4F;IACtF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc9C;IAED;;;;;;;;;;;;;OAaG;IACG,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1D;IAED;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAU5C;IAED,0EAA0E;IACpE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAED,kEAAkE;IAClE,mBAAmB,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAE5D;IAED,sDAAsD;YACxC,YAAY;YASZ,UAAU;CAIzB"}

package/dist/secrets/secretsStoreManager.js

@@ -0,0 +1,149 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareNotConfiguredError, cloudflareRequest, decodeResponse } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
+import { NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+//#region src/secrets/secretsStoreManager.ts
+/** Scopes attached to every secret we create. CF requires at least one; "workers" is the bind target. */
+const DEFAULT_SCOPES = ["workers"];
+/**
+* One secret in the store, decoded from the CF list response. CF Secrets Store never returns
+* plaintext over REST — values are bind-only by design — so this carries only metadata. The
+* `created`/`modified` ISO strings decode through `JsonDate` to real `Date`s at the wire boundary.
+*/
+const CfSecretEntry = z.object({
+	id: z.string().describe("The CF-assigned secret identifier, used to address delete by id."),
+	name: z.string().describe("The secret's name within the store (the key the CLI references)."),
+	status: z.enum([
+		"pending",
+		"active",
+		"deleted"
+	]).describe("The secret's lifecycle status in the store."),
+	created: JsonDate.describe("When the secret was created (ISO string on the wire, Date in app)."),
+	modified: JsonDate.describe("When the secret was last modified (ISO string on the wire, Date in app).")
+}).describe("A single Cloudflare Secrets Store secret's metadata (never its plaintext value).");
+/**
+* Out-of-Worker access to the account-level Cloudflare Secrets Store over the REST API: provisioning
+* and audit from a CLI/CI context. Inside a Worker, secret values resolve via bindings — this manager
+* is the REST counterpart for managing the store, addressed by store id.
+*
+* CF Secrets Store does not expose secret plaintext via REST (values are bind-only by design), so
+* there is no `getSecret`. The provisioning and audit flows only need put, delete, and list.
+*/
+var CloudflareSecretsStoreManager = class extends CloudflareManager {
+	storeId;
+	constructor(config) {
+		super(config);
+		if (!config.storeId) throw new CloudflareNotConfiguredError({ detail: "Missing storeId for Secrets Store REST access." });
+		this.storeId = config.storeId;
+	}
+	getServiceType() {
+		return "Cloudflare Secrets Store";
+	}
+	/** Prove access by listing the store's secrets. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.listSecrets();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Insert or update a secret. An existing entry is updated in place via `edit`; otherwise a fresh
+	* secret is created.
+	*
+	* `edit` is what makes this safe. The old value is overwritten, never deleted first, so a failed
+	* update leaves the prior value intact and bound — there is no window where the secret is absent
+	* from the store (which, for a secret like the master encryption key, is a platform-level outage).
+	* Scopes are re-sent so an entry converges on the same shape whichever branch wrote it.
+	*/
+	async putSecret(name, value) {
+		const existing = await this.findByName(name);
+		if (!existing) {
+			await this.createSecret(name, value);
+			return;
+		}
+		await cloudflareRequest(`put secret ${name}`, () => this.getClient().secretsStore.stores.secrets.edit(existing.id, {
+			account_id: this.accountId,
+			store_id: this.storeId,
+			value,
+			scopes: [...DEFAULT_SCOPES]
+		}));
+	}
+	/** Delete a secret by name. Resolves the id via `listSecrets`, then issues DELETE by id. */
+	async deleteSecret(name) {
+		const existing = await this.findByName(name);
+		if (!existing) throw new NotFoundError({
+			message: `Secret '${name}' was not found in the store.`,
+			detail: `delete secret ${name}: no entry with that name`
+		});
+		await cloudflareRequest(`delete secret ${name}`, () => this.getClient().secretsStore.stores.secrets.delete(existing.id, {
+			account_id: this.accountId,
+			store_id: this.storeId
+		}));
+	}
+	/**
+	* Delete a secret, treating an absent one as already done.
+	*
+	* The typed not-found on {@link deleteSecret} is right for a caller that named a specific secret and
+	* needs to hear it was not there. It is wrong for anything reconciling toward absence — teardown, a
+	* reaper, a re-run of a provisioning step — where "gone" is the goal and a second delete is a no-op,
+	* not a failure. Two callers race on the store all the time: another runner's sweep, or a listing that
+	* has not caught up.
+	*
+	* Given as its own method rather than a flag, so which semantics a call site wants is legible at the
+	* call site. The alternative every caller reaches for otherwise is `.catch(() => {})`, which also
+	* swallows the auth failure and the outage — and a teardown that swallows is how debris becomes
+	* permanent with no signal at all.
+	*/
+	async deleteSecretIfPresent(name) {
+		const existing = await this.findByName(name);
+		if (!existing) return false;
+		await cloudflareRequest(`delete secret ${name}`, () => this.getClient().secretsStore.stores.secrets.delete(existing.id, {
+			account_id: this.accountId,
+			store_id: this.storeId
+		}));
+		return true;
+	}
+	/**
+	* List every secret in the store. The SDK auto-paginates via `for await`, so callers receive the
+	* full set in one array. Each entry is Zod-validated (`CfSecretEntry`) at the wire boundary.
+	*/
+	async listSecrets() {
+		return cloudflareRequest("list secrets", async () => {
+			const out = [];
+			for await (const entry of this.getClient().secretsStore.stores.secrets.list(this.storeId, { account_id: this.accountId })) out.push(decodeResponse(CfSecretEntry, entry, "Secrets Store list entry"));
+			return out;
+		});
+	}
+	/** Whether a secret with the given name currently exists in the store. */
+	async exists(name) {
+		return await this.findByName(name) !== void 0;
+	}
+	/** The store this manager targets and the account it lives in. */
+	getSecretsStoreInfo() {
+		return {
+			storeId: this.storeId,
+			accountId: this.accountId
+		};
+	}
+	/** Create a single secret with the default scopes. */
+	async createSecret(name, value) {
+		await cloudflareRequest(`create secret ${name}`, () => this.getClient().secretsStore.stores.secrets.create(this.storeId, {
+			account_id: this.accountId,
+			body: [{
+				name,
+				value,
+				scopes: [...DEFAULT_SCOPES]
+			}]
+		}));
+	}
+	async findByName(name) {
+		return (await this.listSecrets()).find((entry) => entry.name === name);
+	}
+};
+//#endregion
+export { CfSecretEntry, CloudflareSecretsStoreManager };

package/dist/secrets/secretsStores.d.ts

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+/**
+ * The **account-level** view of Cloudflare Secrets Store: which stores exist, and nothing else.
+ *
+ * Its sibling {@link CloudflareSecretsStoreManager} is addressed *by store id* — it demands one in its
+ * constructor, because every operation it has is inside a store. That is the right shape for putting and
+ * deleting secrets and the wrong shape for the one question asked before any store id is known: which
+ * store does this account have?
+ *
+ * **One store per account**, which is what makes the answer usable at all. `pithy add secrets` resolves
+ * the id here, once, at provisioning time, and writes it into `<config>/cloudflare.json` — so every later
+ * run is a plain file read. Discovery on every invocation was considered and rejected (#182): a CLI that
+ * cannot run offline because it has to ask Cloudflare where its own store is has lost more than the key
+ * was costing.
+ */
+/**
+ * One store in the account, decoded from the CF list response.
+ *
+ * Metadata only — a store holds secrets whose plaintext the REST API never returns. The `created` and
+ * `modified` ISO strings decode through `JsonDate` at the wire boundary, as every other response here
+ * does, so nothing downstream parses a date string a second time.
+ */
+export declare const CfSecretsStore: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    created: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    modified: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type CfSecretsStore = z.output<typeof CfSecretsStore>;
+/** Account-level Secrets Store operations: listing the account's stores. Addressed by account, not store. */
+export declare class CloudflareSecretsStoresManager extends CloudflareManager {
+    getServiceType(): string;
+    /** Prove access by listing the account's stores. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /**
+     * Every Secrets Store in the account. The SDK auto-paginates via `for await`, so a caller receives
+     * the full set in one array, and each entry is Zod-validated at the wire boundary.
+     *
+     * **Returns the list, never a choice.** Cloudflare permits one store per account, so the ordinary
+     * answer has exactly one element — but "ordinarily one" is not "always one", and picking the first of
+     * two would be guessing which store holds an adopter's production secrets. The caller decides, and the
+     * only correct decision for two is to refuse and name them.
+     */
+    listStores(): Promise<CfSecretsStore[]>;
+}
+//# sourceMappingURL=secretsStores.d.ts.map

package/dist/secrets/secretsStores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secretsStores.d.ts","sourceRoot":"","sources":["../../src/secrets/secretsStores.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;;;iBAO6E,CAAC;AACzG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,6GAA6G;AAC7G,qBAAa,8BAA+B,SAAQ,iBAAiB;IACnE,cAAc,IAAI,MAAM,CAEvB;IAED,kEAAkE;IAC5D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;;OAQG;IACG,UAAU,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAQ5C;CACF"}

package/dist/secrets/secretsStores.js

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { cloudflareRequest, decodeResponse } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+//#region src/secrets/secretsStores.ts
+/**
+* The **account-level** view of Cloudflare Secrets Store: which stores exist, and nothing else.
+*
+* Its sibling {@link CloudflareSecretsStoreManager} is addressed *by store id* — it demands one in its
+* constructor, because every operation it has is inside a store. That is the right shape for putting and
+* deleting secrets and the wrong shape for the one question asked before any store id is known: which
+* store does this account have?
+*
+* **One store per account**, which is what makes the answer usable at all. `pithy add secrets` resolves
+* the id here, once, at provisioning time, and writes it into `<config>/cloudflare.json` — so every later
+* run is a plain file read. Discovery on every invocation was considered and rejected (#182): a CLI that
+* cannot run offline because it has to ask Cloudflare where its own store is has lost more than the key
+* was costing.
+*/
+/**
+* One store in the account, decoded from the CF list response.
+*
+* Metadata only — a store holds secrets whose plaintext the REST API never returns. The `created` and
+* `modified` ISO strings decode through `JsonDate` at the wire boundary, as every other response here
+* does, so nothing downstream parses a date string a second time.
+*/
+const CfSecretsStore = z.object({
+	id: z.string().describe("The CF-assigned store identifier — the value that becomes SECRETS_STORE_ID."),
+	name: z.string().describe("The store's display name, for naming it back to an operator who has two."),
+	created: JsonDate.describe("When the store was created (ISO string on the wire, Date in app)."),
+	modified: JsonDate.describe("When the store was last modified (ISO string on the wire, Date in app).")
+}).describe("A single Cloudflare Secrets Store's metadata. Never a secret, and never a secret's value.");
+/** Account-level Secrets Store operations: listing the account's stores. Addressed by account, not store. */
+var CloudflareSecretsStoresManager = class extends CloudflareManager {
+	getServiceType() {
+		return "Cloudflare Secrets Store (account)";
+	}
+	/** Prove access by listing the account's stores. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.listStores();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Every Secrets Store in the account. The SDK auto-paginates via `for await`, so a caller receives
+	* the full set in one array, and each entry is Zod-validated at the wire boundary.
+	*
+	* **Returns the list, never a choice.** Cloudflare permits one store per account, so the ordinary
+	* answer has exactly one element — but "ordinarily one" is not "always one", and picking the first of
+	* two would be guessing which store holds an adopter's production secrets. The caller decides, and the
+	* only correct decision for two is to refuse and name them.
+	*/
+	async listStores() {
+		return cloudflareRequest("list secrets stores", async () => {
+			const out = [];
+			for await (const store of this.getClient().secretsStore.stores.list({ account_id: this.accountId })) out.push(decodeResponse(CfSecretsStore, store, "Secrets Store list entry"));
+			return out;
+		});
+	}
+};
+//#endregion
+export { CfSecretsStore, CloudflareSecretsStoresManager };

package/dist/test-utils/emailRoutingRules.d.ts

@@ -0,0 +1,41 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import type { IntegrationCreds } from "./harness";
+/** One matcher on a routing rule: which mail the rule claims. */
+export declare const EmailRoutingMatcher: z.ZodObject<{
+    type: z.ZodString;
+    field: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** One action on a routing rule: what happens to the mail it claimed. */
+export declare const EmailRoutingAction: z.ZodObject<{
+    type: z.ZodString;
+    value: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** One Email Routing rule, as the zone stores it. */
+export declare const EmailRoutingRule: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodDefault<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    priority: z.ZodDefault<z.ZodNumber>;
+    matchers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        field: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    actions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        value: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** One Email Routing rule, as the zone stores it. */
+export type EmailRoutingRule = z.output<typeof EmailRoutingRule>;
+/** Every Email Routing rule on a zone, paged to exhaustion. */
+export declare function listEmailRoutingRules(creds: IntegrationCreds, zoneId: string): Promise<EmailRoutingRule[]>;
+/**
+ * The rules somebody named — the zone's own rules, without the unnamed catch-all Cloudflare puts on
+ * every zone configured or not.
+ */
+export declare function namedRules(rules: readonly EmailRoutingRule[]): EmailRoutingRule[];
+//# sourceMappingURL=emailRoutingRules.d.ts.map

package/dist/test-utils/emailRoutingRules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emailRoutingRules.d.ts","sourceRoot":"","sources":["../../src/test-utils/emailRoutingRules.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAkClD,iEAAiE;AACjE,eAAO,MAAM,mBAAmB;;;;iBAMoB,CAAC;AAErD,yEAAyE;AACzE,eAAO,MAAM,kBAAkB;;;iBAKoB,CAAC;AAEpD,qDAAqD;AACrD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;iBAYsC,CAAC;AAEpE,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAiBjE,+DAA+D;AAC/D,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAuBhH;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,CAEjF"}

package/dist/test-utils/emailRoutingRules.js

@@ -0,0 +1,91 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareRequestError } from "../client/errors.js";
+import { z } from "zod";
+//#region src/test-utils/emailRoutingRules.ts
+/**
+* A zone's Email Routing rules, read whole.
+*
+* `CloudflareEmailRoutingManager` reads the same endpoint and keeps only `id` and `name`, because
+* matching by name and deleting by id is all provisioning needs. Two callers here need more.
+*
+* **A live test has to see what Cloudflare stored, not what we sent.** #47's open question is whether
+* the `matchers`/`actions` shape `ensureWorkerRoute` posts still matches the current API — and a test
+* that asserts on its own request argument answers nothing. So the rule comes back in full and the
+* assertions are on the stored copy.
+*
+* **The reaper needs names it can hand back to `removeWorkerRoute`.** A run that dies between creating
+* a rule and tearing it down leaves live mail routing to a Worker that is about to be deleted, which is
+* the one piece of debris in this repo that changes what happens to somebody's mail rather than costing
+* a few cents.
+*
+* ## Two documented traps, both live here so nobody has to rediscover them
+*
+* **Every zone has a catch-all rule whether or not anything is configured** — no name, priority
+* `2147483647`, `matchers: [{ type: "all" }]`. A rule count of 1 means nothing. {@link namedRules}
+* drops it, so a caller counting *our* rules counts ours.
+*
+* **`result_info` on this endpoint carries no `total_pages`** on a single-page zone. The paging loop
+* therefore stops on a short page, exactly as the manager's does.
+*/
+/** 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;
+/** One matcher on a routing rule: which mail the rule claims. */
+const EmailRoutingMatcher = z.object({
+	type: z.string().describe("`literal` for one address, `all` for the zone's catch-all."),
+	field: z.string().optional().describe("The header the literal matches on — `to` for every rule Pithy writes."),
+	value: z.string().optional().describe("The address a `literal` matcher claims. Absent on a catch-all.")
+}).describe("One matcher on an Email Routing rule.");
+/** One action on a routing rule: what happens to the mail it claimed. */
+const EmailRoutingAction = z.object({
+	type: z.string().describe("`worker` for a Worker delivery, `drop` for the default catch-all, `forward` otherwise."),
+	value: z.array(z.string()).default([]).describe("The action's targets — a single Worker script name for `worker`.")
+}).describe("One action on an Email Routing rule.");
+/** One Email Routing rule, as the zone stores it. */
+const EmailRoutingRule = z.object({
+	id: z.string().describe("Cloudflare's id for the rule — what a delete addresses."),
+	name: z.string().default("").describe("The rule's name. Empty on the default catch-all every zone carries."),
+	enabled: z.boolean().default(false).describe("Whether the rule is live. The catch-all's flag doubles as the zone's."),
+	priority: z.number().default(0).describe("Match order, lowest first. The catch-all sits at 2147483647."),
+	matchers: z.array(EmailRoutingMatcher).default([]).describe("Which mail this rule claims."),
+	actions: z.array(EmailRoutingAction).default([]).describe("What happens to the mail this rule claimed.")
+}).describe("One Email Routing rule on a zone, read back in full.");
+/** The list envelope, validated because a response read is a boundary. */
+const RuleListEnvelope = z.object({
+	success: z.boolean().describe("Cloudflare's own verdict on the request."),
+	result: z.array(EmailRoutingRule).nullable().default([]).describe("This page of rules. Null on a failed call."),
+	result_info: z.object({
+		page: z.number().optional().describe("The page just returned."),
+		total_pages: z.number().optional().describe("Total pages, when Cloudflare states one. Often absent.")
+	}).nullish().describe("The paging block, when the response carries one.")
+}).describe("A page of a zone's Email Routing rules.");
+/** Every Email Routing rule on a zone, paged to exhaustion. */
+async function listEmailRoutingRules(creds, zoneId) {
+	const rules = [];
+	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 response = await fetch(url, { headers: { Authorization: `Bearer ${creds.apiToken}` } });
+		if (!response.ok) throw new CloudflareRequestError({
+			message: "Could not read the zone's Email Routing rules.",
+			action: "Check the token carries Email Routing Rules: Read on this zone.",
+			detail: `Email Routing rule list returned ${response.status}.`
+		});
+		const envelope = RuleListEnvelope.parse(await response.json());
+		const batch = envelope.result ?? [];
+		rules.push(...batch);
+		const totalPages = envelope.result_info?.total_pages;
+		if (totalPages !== void 0 ? page >= totalPages : batch.length < RULES_PER_PAGE) break;
+	}
+	return rules;
+}
+/**
+* The rules somebody named — the zone's own rules, without the unnamed catch-all Cloudflare puts on
+* every zone configured or not.
+*/
+function namedRules(rules) {
+	return rules.filter((rule) => rule.name !== "");
+}
+//#endregion
+export { EmailRoutingAction, EmailRoutingMatcher, EmailRoutingRule, listEmailRoutingRules, namedRules };