@pithy-sh/cloudflare 0.1.2 → 0.1.4

package/dist/workflows/workflowsClient.js

@@ -0,0 +1,158 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareInvalidResponseError, cloudflareRequest, isNotFoundError } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { stepFailure, terminalWorkflowError } from "./stepFailure.js";
+import { z } from "zod";
+import { UpstreamTimeoutError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/workflows/workflowsClient.ts
+const WorkflowInstanceStatus = z.enum([
+	"queued",
+	"running",
+	"paused",
+	"errored",
+	"terminated",
+	"complete",
+	"waitingForPause",
+	"waiting",
+	"rollingBack",
+	"unknown"
+]).describe("Lifecycle state of a Cloudflare Workflow instance, from the status endpoint.");
+const WorkflowInstance = z.object({
+	status: WorkflowInstanceStatus.describe("The instance's current lifecycle state."),
+	output: z.unknown().optional().describe("The Workflow's return value, present once `status` is `complete`."),
+	error: z.union([
+		z.string(),
+		z.object({ message: z.string().optional().describe("Failure message.") }).describe("The structured form of the failure, when the API sends an object rather than a string."),
+		z.null()
+	]).optional().describe("The instance-level failure, present when `status` is `errored` or `terminated`."),
+	steps: z.array(z.unknown()).optional().describe("The instance's steps, each validated where it is read (`stepFailure`). Held as `unknown` here on purpose: the API has four step shapes, this client reads one field of one of them, and a shape nobody anticipated must not turn a failed Workflow into a parse error about the failure report.")
+}).describe("A Cloudflare Workflow instance's status, as returned by the instance-detail endpoint.");
+/** Terminal states a poll stops on. */
+const TERMINAL = /* @__PURE__ */ new Set([
+	"complete",
+	"errored",
+	"terminated"
+]);
+const defaultSleeper = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* A client over the Cloudflare Workflows API — the only sanctioned way to reach CF Workflows from
+* outside a Worker (CLAUDE.md: no hand-rolled CF `fetch` outside `@pithy-sh/cloudflare`). The
+* `pithy secrets` CLI uses it to trigger a per-env manager's Workflow and poll to completion: the
+* CLI never runs secret logic locally, since the master key is worker-only.
+*
+* The SDK owns transport and envelope handling. Instance status is still re-validated through
+* {@link WorkflowInstance} rather than taken from the SDK's types: the SDK narrows `output` to
+* `string | number`, but a Workflow's return value is arbitrary JSON, and the status enum is a wire
+* value we decode at the boundary like every other external input.
+*/
+var CloudflareWorkflowsClient = class extends CloudflareManager {
+	#sleeper;
+	constructor(config) {
+		super(config);
+		this.#sleeper = config.sleeper ?? defaultSleeper;
+	}
+	getServiceType() {
+		return "Workflows";
+	}
+	/** Prove reach by listing the account's Workflows; never throws. */
+	async validateServiceAccess() {
+		try {
+			for await (const _workflow of this.getClient().workflows.list({ account_id: this.accountId })) break;
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** Create (trigger) a Workflow instance and return its id. */
+	async createInstance(workflowName, params, instanceId) {
+		return cloudflareRequest(`create instance of ${workflowName}`, async () => {
+			const created = await this.getClient().workflows.instances.create(workflowName, {
+				account_id: this.accountId,
+				params,
+				...instanceId ? { instance_id: instanceId } : {}
+			});
+			if (!created.id) throw new CloudflareInvalidResponseError({ detail: `create instance of ${workflowName}: missing instance id` });
+			return created.id;
+		});
+	}
+	/** Fetch an instance's status. Returns `null` on a 404 (a just-created instance can briefly lag). */
+	async getInstanceStatus(workflowName, instanceId) {
+		const operation = `get status of ${workflowName}/${instanceId}`;
+		return cloudflareRequest(operation, async () => {
+			let response;
+			try {
+				response = await this.getClient().workflows.instances.get(instanceId, {
+					account_id: this.accountId,
+					workflow_name: workflowName
+				});
+			} catch (error) {
+				if (isNotFoundError(error)) return null;
+				throw error;
+			}
+			const parsed = WorkflowInstance.safeParse(response);
+			if (!parsed.success) throw new CloudflareInvalidResponseError({ detail: `${operation}: unexpected shape` });
+			return parsed.data;
+		});
+	}
+	/**
+	* Trigger a Workflow and poll until it reaches a terminal state. Resolves with the instance
+	* `output` on `complete`. The error never carries the dispatched params (which may be secret).
+	*
+	* **Three failures, three codes, and a caller can tell them apart without reading a word of prose**
+	* (pithy-sh/pithy#365):
+	*
+	* | What happened | Code | Status |
+	* |---|---|---|
+	* | A step raised, and the kit pins a status for its code | that code | that status |
+	* | The run ended terminally, nothing attributable | `core/workflow_failed` | 500 |
+	* | The dispatch or a poll could not be delivered | `cloudflare/request_failed` | 502 |
+	* | We stopped waiting; the instance may still finish | `core/upstream_timeout` | 504 |
+	*
+	* The first two are terminal — the run is over and re-driving it reaches the same end. The last two
+	* are not. Reporting all of them as 502 told an operator to wait for a recovery that would never
+	* come; see `terminalWorkflowError` for the argument in full.
+	*/
+	async dispatchAndPoll(workflowName, params, options = {}) {
+		const pollIntervalMs = options.pollIntervalMs ?? 1e3;
+		const maxPolls = options.maxPolls ?? 120;
+		const id = await this.createInstance(workflowName, params, options.instanceId);
+		for (let poll = 0; poll < maxPolls; poll++) {
+			await this.#sleeper(pollIntervalMs);
+			const instance = await this.getInstanceStatus(workflowName, id);
+			if (!instance) continue;
+			if (!TERMINAL.has(instance.status)) continue;
+			if (instance.status === "complete") return instance.output;
+			const failure = stepFailure(instance.steps);
+			throw terminalWorkflowError({
+				failure,
+				fallbackMessage: `Workflow ${workflowName} did not complete (${instance.status}).`,
+				detail: `instance ${id} ended ${instance.status}: ${describeFailure(failure, instance.error)}`
+			});
+		}
+		throw new UpstreamTimeoutError({
+			message: `Workflow ${workflowName} did not finish in time.`,
+			action: `Check the instance in the Cloudflare dashboard; it may still complete.`,
+			detail: `instance ${id} still running after ${maxPolls} polls`
+		});
+	}
+};
+/** The most specific instance-error text, for a failure `detail`. Never the dispatched params. */
+function describeError(error) {
+	if (!error) return "no error detail";
+	if (typeof error === "string") return error;
+	return error.message ?? "no error detail";
+}
+/**
+* Everything known about why, for the `detail` line: the failed step's name and its recorded text
+* verbatim, then the instance's own. Both, because they differ — that difference is the bug this
+* function exists because of — and `detail` is the operator's side of the boundary, where the raw
+* platform text belongs. Never the dispatched params.
+*/
+function describeFailure(failure, error) {
+	const instance = describeError(error);
+	if (failure === null) return instance;
+	return `${failure.step === void 0 ? "step" : `step '${failure.step}'`} raised${failure.code === void 0 ? "" : ` [${failure.code}]`} ${failure.raw} — instance error: ${instance}`;
+}
+//#endregion
+export { CloudflareWorkflowsClient, WorkflowInstance, WorkflowInstanceStatus };

package/dist/zones/zonesManager.d.ts

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+/**
+ * The account's zones — the registrable domains a custom domain can attach to.
+ *
+ * **Nothing here listed zones before.** Every zone-scoped operation in this package takes a `zoneId` the
+ * caller already knows: `CloudflareCustomHostnamesManager` takes it as constructor config,
+ * `CloudflareEmailRoutingManager` takes it per method, `CloudflareWorkersManager.addRoute` takes it
+ * positionally — and `pithy email provision` makes a human paste one, telling them to "find it on the
+ * zone's Overview page". So the CLI never *discovered* a zone; it demanded one.
+ *
+ * That is what this exists to change. When `pithy init` and `pithy worker add` ask where a Worker will
+ * answer, offering the account's real zones means a typo fails at `init` with a list of what exists,
+ * rather than at `deploy` with a Cloudflare error to decode.
+ *
+ * Read-only, deliberately. Pithy attaches routes to zones and never creates, transfers, or deletes one —
+ * a zone is the adopter's relationship with their registrar, not a resource this toolset provisions. The
+ * scoped token needs only `Zone:Read`.
+ */
+/** One zone on the account. */
+export declare const ZoneInfo: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodString;
+}, z.core.$strip>;
+export type ZoneInfo = z.output<typeof ZoneInfo>;
+/** Read the account's zones. Never creates or deletes — a zone is the adopter's, not ours to provision. */
+export declare class CloudflareZonesManager extends CloudflareManager {
+    getServiceType(): string;
+    /** Prove access by listing. A read, and never throws — the caller decides what an inaccessible account means. */
+    validateServiceAccess(): Promise<boolean>;
+    /**
+     * Every zone on this account, name-sorted so a picker is stable between runs.
+     *
+     * Filtered to the account, because a user-bound token can see zones on accounts this project has
+     * nothing to do with — offering those would invite someone to attach a Worker to a zone that another
+     * account owns, which fails at deploy with an error that names neither problem.
+     */
+    listZones(): Promise<ZoneInfo[]>;
+    /**
+     * The zone a hostname belongs to, or `null`.
+     *
+     * Matches the **longest** zone name that the hostname sits under, which is the only correct rule when
+     * an account holds both `example.com` and `eu.example.com`: `api.eu.example.com` belongs to the latter,
+     * and picking the first match would attach it to the wrong zone. A public-suffix guess is not used at
+     * all — a zone can itself be a subdomain, and the account's own list is the authority.
+     */
+    findZoneForHostname(hostname: string): Promise<ZoneInfo | null>;
+}
+//# sourceMappingURL=zonesManager.d.ts.map

package/dist/zones/zonesManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zonesManager.d.ts","sourceRoot":"","sources":["../../src/zones/zonesManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;;;;;;;;;;GAgBG;AAEH,+BAA+B;AAC/B,eAAO,MAAM,QAAQ;;;;iBAc4F,CAAC;AAClH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD,2GAA2G;AAC3G,qBAAa,sBAAuB,SAAQ,iBAAiB;IAC3D,cAAc,IAAI,MAAM,CAEvB;IAED,iHAAiH;IAC3G,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CASrC;IAED;;;;;;;OAOG;IACG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAKpE;CACF"}

package/dist/zones/zonesManager.js

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { cloudflareRequest } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
+//#region src/zones/zonesManager.ts
+/**
+* The account's zones — the registrable domains a custom domain can attach to.
+*
+* **Nothing here listed zones before.** Every zone-scoped operation in this package takes a `zoneId` the
+* caller already knows: `CloudflareCustomHostnamesManager` takes it as constructor config,
+* `CloudflareEmailRoutingManager` takes it per method, `CloudflareWorkersManager.addRoute` takes it
+* positionally — and `pithy email provision` makes a human paste one, telling them to "find it on the
+* zone's Overview page". So the CLI never *discovered* a zone; it demanded one.
+*
+* That is what this exists to change. When `pithy init` and `pithy worker add` ask where a Worker will
+* answer, offering the account's real zones means a typo fails at `init` with a list of what exists,
+* rather than at `deploy` with a Cloudflare error to decode.
+*
+* Read-only, deliberately. Pithy attaches routes to zones and never creates, transfers, or deletes one —
+* a zone is the adopter's relationship with their registrar, not a resource this toolset provisions. The
+* scoped token needs only `Zone:Read`.
+*/
+/** One zone on the account. */
+const ZoneInfo = z.object({
+	id: z.string().describe("The CF-assigned zone id, which every zone-scoped API call is addressed by."),
+	name: z.string().describe("The registrable domain, e.g. `example.com`. This is the value a Worker's `domains` declaration names as its `zone`, and what wrangler writes as `zone_name`."),
+	status: z.string().describe("The zone's lifecycle status — `active` once Cloudflare is serving it, otherwise `pending`, `initializing`, or `moved`. A non-active zone cannot carry a custom domain yet, so a picker shows it and says so rather than hiding it.")
+}).describe("One Cloudflare zone: the registrable domain a custom domain can attach to, and whether it is live.");
+/** Read the account's zones. Never creates or deletes — a zone is the adopter's, not ours to provision. */
+var CloudflareZonesManager = class extends CloudflareManager {
+	getServiceType() {
+		return "Cloudflare Zones";
+	}
+	/** Prove access by listing. A read, and never throws — the caller decides what an inaccessible account means. */
+	async validateServiceAccess() {
+		try {
+			await this.listZones();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Every zone on this account, name-sorted so a picker is stable between runs.
+	*
+	* Filtered to the account, because a user-bound token can see zones on accounts this project has
+	* nothing to do with — offering those would invite someone to attach a Worker to a zone that another
+	* account owns, which fails at deploy with an error that names neither problem.
+	*/
+	async listZones() {
+		return cloudflareRequest("list zones", async () => {
+			const zones = [];
+			for await (const zone of this.getClient().zones.list({ account: { id: this.accountId } })) {
+				const parsed = ZoneInfo.safeParse(zone);
+				if (parsed.success) zones.push(parsed.data);
+			}
+			return zones.sort((a, b) => a.name.localeCompare(b.name));
+		});
+	}
+	/**
+	* The zone a hostname belongs to, or `null`.
+	*
+	* Matches the **longest** zone name that the hostname sits under, which is the only correct rule when
+	* an account holds both `example.com` and `eu.example.com`: `api.eu.example.com` belongs to the latter,
+	* and picking the first match would attach it to the wrong zone. A public-suffix guess is not used at
+	* all — a zone can itself be a subdomain, and the account's own list is the authority.
+	*/
+	async findZoneForHostname(hostname) {
+		const candidates = (await this.listZones()).filter((zone) => hostname === zone.name || hostname.endsWith(`.${zone.name}`));
+		if (candidates.length === 0) return null;
+		return candidates.reduce((longest, zone) => zone.name.length > longest.name.length ? zone : longest);
+	}
+};
+//#endregion
+export { CloudflareZonesManager, ZoneInfo };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/cloudflare",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -8,18 +8,23 @@
     "directory": "packages/cloudflare"
   },
   "files": [
+    "dist",
     "src",
-    "!src/**/*.test.*"
+    "!src/**/*.test.*",
+    "!dist/**/*.test.*"
   ],
   "type": "module",
   "engines": {
     "node": ">=22"
   },
   "exports": {
-    "./src/*": "./src/*.ts"
+    "./src/*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "build": "tsdown && tsc -p tsconfig.build.json && bun ../../tooling/build/src/stampDeclarations.ts",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run",
     "test:node": "vitest run --project=node",
@@ -31,18 +36,22 @@
     "@aws-sdk/client-s3": "^3.1111.0",
     "@aws-sdk/s3-request-presigner": "^3.1111.0",
     "@cloudflare/workers-types": "^5.20260729.1",
-    "@pithy-sh/core": "^0.1.2",
+    "@pithy-sh/core": "^0.1.5",
     "cloudflare": "^7.0.0",
-    "js-base64": "^3.9.2",
-    "kysely": "^0.29.0",
-    "zod": "^4.0.0"
+    "js-base64": "^3.9.2"
   },
   "devDependencies": {
     "@pithy-sh/tsconfig": "workspace:*",
     "@types/node": "^22.15.0",
     "@vitest/coverage-v8": "^4.1.0",
+    "kysely": "^0.29.0",
     "kysely-d1": "^0.4.0",
+    "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.0",
+    "zod": "^4.4.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.4.0"
   }
 }