@pithy-sh/cloudflare 0.1.2 → 0.1.3

package/dist/workers/workersManager.d.ts

@@ -0,0 +1,136 @@
+import type { RouteCreateResponse, RouteListResponse } from "cloudflare/resources/workers/routes";
+import type { Deployment } from "cloudflare/resources/workers/scripts/deployments";
+import type { Script } from "cloudflare/resources/workers/scripts/scripts";
+import type { SecretListResponse } from "cloudflare/resources/workers/scripts/secrets";
+import type { SettingEditParams } from "cloudflare/resources/workers/scripts/settings";
+import type { VersionGetResponse, VersionListResponse } from "cloudflare/resources/workers/scripts/versions";
+import { CloudflareManager } from "../client/manager";
+/** Worker settings a caller may edit (observability, logpush, tags, …); the account id is supplied. */
+export type WorkerSettings = Omit<SettingEditParams, "account_id">;
+/**
+ * One ES-module file of a Worker upload.
+ *
+ * **ES modules only.** `name` becomes both the multipart part name and the upload's `main_module`,
+ * and the part is sent as `application/javascript+module`. Classic service-worker scripts — the
+ * `body_part` shape, with a global `addEventListener("fetch", …)` — are not supported by this
+ * manager and never were: every upload it has ever sent set `main_module`. {@link
+ * CloudflareWorkersManager.createWorker} refuses a `body_part` in metadata rather than sending a
+ * request with both shapes half-declared.
+ */
+export interface WorkerModule {
+    /** The module's filename, e.g. `index.js`. Becomes the part name and the upload's `main_module`. */
+    name: string;
+    /** The module's ES-module source, uploaded verbatim as `application/javascript+module`. */
+    body: string;
+}
+/**
+ * Out-of-Worker Workers access over the REST API: script create/list/delete, subdomain + settings,
+ * versions, deployments, secrets, and routes from a CLI/CI/provisioning context. Inside a Worker you
+ * manage scripts through wrangler/bindings; this manager is the REST counterpart, addressed by
+ * account (and zone, for routes).
+ */
+export declare class CloudflareWorkersManager extends CloudflareManager {
+    /** List every Worker script on the account. */
+    listWorkers(): Promise<Script[]>;
+    /** Find a Worker script by name. Returns null when none matches. */
+    getWorker(scriptName: string): Promise<Script | null>;
+    /**
+     * Resolve a Worker's immutable `id` (the hex UUID) from the beta `/workers/workers` endpoint. CF
+     * Builds' `external_script_id` uses this immutable id, not the worker name. This is an explicit
+     * get: it throws `core/not_found` when no worker on the account carries the given name.
+     */
+    getWorkerInternalId(workerName: string): Promise<string>;
+    /**
+     * Create (upload) a Worker script. With no `module` the placeholder above is uploaded and the real
+     * build output replaces it via a later version upload; pass one to upload real source. `metadata`
+     * is merged into the upload's metadata — bindings, compatibility flags, tags — and this method
+     * fixes `main_module`.
+     *
+     * **`compatibilityDate` is required, and there is no default (#396).** This method used to supply
+     * `2026-04-07` when the caller named none, which is one date below the floor `compatibility.ts`
+     * holds every other Worker in this repository to, and the one date #388's gate could not reach —
+     * because it is TypeScript rather than a `wrangler.jsonc`, and the gate reads manifests.
+     *
+     * Moving it to the floor was the obvious answer and it is the wrong one. **A compatibility date is a
+     * behavior contract, not a version number** — it is the date workerd pretends it is — and this one
+     * lands on Workers in accounts that are not ours. Re-picking the number changes what an existing
+     * caller's Workers run, silently, for somebody who never asked; and the new number is stale on
+     * exactly the schedule the old one was, with the same gate unable to see it. `compatibility.ts` makes
+     * that argument about `2026-03-03` in as many words: *the minimum that fixes the last bug is exactly
+     * the number `2025-01-01` once was.*
+     *
+     * Requiring the date removes the class instead of re-picking the number, which is the move #377, #366
+     * and #394 each took. It is also the cheaper break: a caller who wanted `2026-04-07` writes
+     * `2026-04-07` and gets precisely what they had, and everyone else finds out at compile time rather
+     * than from a behavior change in production. `WorkersProvisioner` already promised this — *"it
+     * carries no environment- or product-specific defaults — every name, command, and env var is supplied
+     * by the caller"* — and the manager under it was the one place that was untrue.
+     *
+     * `metadata` may **not** also carry `compatibility_date`. Two ways to state one contract is a
+     * precedence rule to remember, and this method exists to have one statement rather than two.
+     *
+     * **The multipart request is built here rather than through `workers.scripts.update`, and that is
+     * a fix rather than a preference (#373).** The typed SDK's `update` pins
+     * `Content-Type: application/javascript` on the request and *then* lets its uploader turn the body
+     * into `FormData`. Cloudflare believes the header, parses the multipart envelope as a classic
+     * service-worker script, and rejects every upload with `10021 Uncaught SyntaxError: Invalid
+     * left-hand side expression in prefix operation at worker.js:1:4` — the leading `------WebKit…`
+     * boundary read as prefix `--` operators. Its form is wrong twice over besides: metadata is
+     * flattened to `metadata[main_module]` fields instead of one JSON part, and the module is appended
+     * as `files[]` rather than under the filename `main_module` names. So the form is assembled here
+     * and handed to the SDK's own `put`, which keeps auth, retries, timeout and error mapping intact.
+     */
+    createWorker(scriptName: string, compatibilityDate: string, metadata?: Record<string, unknown>, module?: WorkerModule): Promise<Script>;
+    /**
+     * Configure the workers.dev subdomain and preview URLs for a script. Both are controlled by the
+     * same endpoint — `previews_enabled` is always sent explicitly so CF does not default it to true.
+     */
+    setSubdomainSettings(scriptName: string, enabled: boolean, previewsEnabled?: boolean): Promise<void>;
+    /** Edit a Worker's settings (observability, logpush, tags, …). */
+    updateSettings(scriptName: string, settings: WorkerSettings): Promise<void>;
+    /** Delete a Worker script. */
+    deleteWorker(scriptName: string): Promise<void>;
+    /** List every version of a Worker script. */
+    listVersions(scriptName: string): Promise<VersionListResponse[]>;
+    /** Get one version of a Worker script. */
+    getVersion(scriptName: string, versionId: string): Promise<VersionGetResponse>;
+    /** List a Worker script's deployments. Empty when none exist. */
+    listDeployments(scriptName: string): Promise<Deployment[]>;
+    /** Get one deployment of a Worker script. */
+    getDeployment(scriptName: string, deploymentId: string): Promise<Deployment>;
+    /** Deploy a version to 100% of traffic for a Worker script. */
+    createDeployment(scriptName: string, versionId: string): Promise<Deployment>;
+    /** Set a secret on a Worker script. */
+    addSecret(scriptName: string, name: string, value: string): Promise<void>;
+    /** Delete a secret from a Worker script. */
+    deleteSecret(scriptName: string, secretName: string): Promise<void>;
+    /** List a Worker script's secrets. */
+    listSecrets(scriptName: string): Promise<SecretListResponse[]>;
+    /**
+     * Create a Workers Route on a zone, mapping a hostname pattern to a script. Idempotent: returns the
+     * existing route when one with the same pattern is already present on the zone.
+     */
+    addRoute(zoneId: string, pattern: string, scriptName: string): Promise<RouteCreateResponse | RouteListResponse>;
+    /** Find a Workers Route on a zone by its pattern. Returns null when none matches. */
+    getRoute(zoneId: string, pattern: string): Promise<RouteListResponse | null>;
+    /** Delete a Workers Route from a zone. */
+    removeRoute(zoneId: string, routeId: string): Promise<void>;
+    /** Resolve a queue's id (UUID) from its name. Returns null when no queue on the account matches. */
+    findQueueIdByName(queueName: string): Promise<string | null>;
+    /**
+     * Subscribe a queue to a Worker's Builds lifecycle events (started/succeeded/failed/canceled).
+     * Idempotent: a CF "already exists" conflict (405 "multiple subscriptions", or 409 "already
+     * exists") is treated as success rather than re-thrown.
+     */
+    subscribeBuildEvents(subscriptionName: string, queueId: string, workerName: string): Promise<void>;
+    /**
+     * The account's `workers.dev` subdomain, or `null` if none is registered. Deploying a Worker that
+     * hosts Workflows requires the account to have one (a one-time account bootstrap), so provisioning
+     * checks this up front. The CF API returns a 404-style error when absent; that maps to `null`.
+     */
+    accountSubdomain(): Promise<string | null>;
+    getServiceType(): string;
+    /** Prove access by listing the account's Workers. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+}
+//# sourceMappingURL=workersManager.d.ts.map

package/dist/workers/workersManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workersManager.d.ts","sourceRoot":"","sources":["../../src/workers/workersManager.ts"],"names":[],"mappings":"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"}

package/dist/workers/workersManager.js

@@ -0,0 +1,312 @@
+import { CloudflareInvalidResponseError, cloudflareRequest, messageOf } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { NotFoundError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/workers/workersManager.ts
+/** Per-call SDK timeout + retry budget for Worker management operations. */
+const requestOptions = {
+	timeout: 1e4,
+	maxRetries: 3
+};
+/**
+* The placeholder module uploaded when a Worker script is first created. A Worker upload requires
+* at least one module file plus `main_module` pointing at it; the real build output replaces this
+* via a later version upload. This stub returns 503 while the worker is being provisioned.
+*/
+const PLACEHOLDER_MODULE = "index.js";
+const PLACEHOLDER_BODY = "export default { async fetch() { return new Response('Provisioning...', { status: 503 }); } };";
+/**
+* An ISO date, the only spelling a compatibility date has. Refused here so a typo is a `ValidationError`
+* naming the argument rather than a 400 from Cloudflare naming the request.
+*/
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** The content type every module part carries. ES modules only — see {@link WorkerModule}. */
+const MODULE_CONTENT_TYPE = "application/javascript+module";
+/** The placeholder module `createWorker` uploads when the caller supplies none. */
+const PLACEHOLDER = {
+	name: PLACEHOLDER_MODULE,
+	body: PLACEHOLDER_BODY
+};
+/**
+* Out-of-Worker Workers access over the REST API: script create/list/delete, subdomain + settings,
+* versions, deployments, secrets, and routes from a CLI/CI/provisioning context. Inside a Worker you
+* manage scripts through wrangler/bindings; this manager is the REST counterpart, addressed by
+* account (and zone, for routes).
+*/
+var CloudflareWorkersManager = class extends CloudflareManager {
+	/** List every Worker script on the account. */
+	async listWorkers() {
+		return cloudflareRequest("list workers", async () => {
+			const scripts = [];
+			for await (const script of this.getClient().workers.scripts.list({ account_id: this.accountId })) scripts.push(script);
+			return scripts;
+		});
+	}
+	/** Find a Worker script by name. Returns null when none matches. */
+	async getWorker(scriptName) {
+		return (await this.listWorkers()).find((script) => script.id === scriptName) ?? null;
+	}
+	/**
+	* Resolve a Worker's immutable `id` (the hex UUID) from the beta `/workers/workers` endpoint. CF
+	* Builds' `external_script_id` uses this immutable id, not the worker name. This is an explicit
+	* get: it throws `core/not_found` when no worker on the account carries the given name.
+	*/
+	async getWorkerInternalId(workerName) {
+		return cloudflareRequest(`get worker internal id for '${workerName}'`, async () => {
+			for await (const worker of this.getClient().workers.beta.workers.list({ account_id: this.accountId })) if (worker.name === workerName) return worker.id;
+			throw new NotFoundError({
+				message: `No Worker named '${workerName}' exists on the account.`,
+				detail: `Beta workers list returned no entry with name '${workerName}'.`
+			});
+		});
+	}
+	/**
+	* Create (upload) a Worker script. With no `module` the placeholder above is uploaded and the real
+	* build output replaces it via a later version upload; pass one to upload real source. `metadata`
+	* is merged into the upload's metadata — bindings, compatibility flags, tags — and this method
+	* fixes `main_module`.
+	*
+	* **`compatibilityDate` is required, and there is no default (#396).** This method used to supply
+	* `2026-04-07` when the caller named none, which is one date below the floor `compatibility.ts`
+	* holds every other Worker in this repository to, and the one date #388's gate could not reach —
+	* because it is TypeScript rather than a `wrangler.jsonc`, and the gate reads manifests.
+	*
+	* Moving it to the floor was the obvious answer and it is the wrong one. **A compatibility date is a
+	* behavior contract, not a version number** — it is the date workerd pretends it is — and this one
+	* lands on Workers in accounts that are not ours. Re-picking the number changes what an existing
+	* caller's Workers run, silently, for somebody who never asked; and the new number is stale on
+	* exactly the schedule the old one was, with the same gate unable to see it. `compatibility.ts` makes
+	* that argument about `2026-03-03` in as many words: *the minimum that fixes the last bug is exactly
+	* the number `2025-01-01` once was.*
+	*
+	* Requiring the date removes the class instead of re-picking the number, which is the move #377, #366
+	* and #394 each took. It is also the cheaper break: a caller who wanted `2026-04-07` writes
+	* `2026-04-07` and gets precisely what they had, and everyone else finds out at compile time rather
+	* than from a behavior change in production. `WorkersProvisioner` already promised this — *"it
+	* carries no environment- or product-specific defaults — every name, command, and env var is supplied
+	* by the caller"* — and the manager under it was the one place that was untrue.
+	*
+	* `metadata` may **not** also carry `compatibility_date`. Two ways to state one contract is a
+	* precedence rule to remember, and this method exists to have one statement rather than two.
+	*
+	* **The multipart request is built here rather than through `workers.scripts.update`, and that is
+	* a fix rather than a preference (#373).** The typed SDK's `update` pins
+	* `Content-Type: application/javascript` on the request and *then* lets its uploader turn the body
+	* into `FormData`. Cloudflare believes the header, parses the multipart envelope as a classic
+	* service-worker script, and rejects every upload with `10021 Uncaught SyntaxError: Invalid
+	* left-hand side expression in prefix operation at worker.js:1:4` — the leading `------WebKit…`
+	* boundary read as prefix `--` operators. Its form is wrong twice over besides: metadata is
+	* flattened to `metadata[main_module]` fields instead of one JSON part, and the module is appended
+	* as `files[]` rather than under the filename `main_module` names. So the form is assembled here
+	* and handed to the SDK's own `put`, which keeps auth, retries, timeout and error mapping intact.
+	*/
+	async createWorker(scriptName, compatibilityDate, metadata = {}, module = PLACEHOLDER) {
+		if ("body_part" in metadata) throw new ValidationError({
+			message: "This client uploads ES-module Workers only.",
+			action: "Remove `body_part` from the metadata and pass the script as a module.",
+			detail: `createWorker('${scriptName}') was given a 'body_part', the classic service-worker shape. Every upload sets 'main_module'.`
+		});
+		if ("compatibility_date" in metadata) throw new ValidationError({
+			message: "A Worker's compatibility date is named once, as an argument.",
+			action: "Remove `compatibility_date` from the metadata and pass it as the second argument.",
+			detail: `createWorker('${scriptName}') was given a 'compatibility_date' in metadata as well as an argument. Two statements of one behavior contract is a precedence rule nobody should have to know.`
+		});
+		if (!ISO_DATE.test(compatibilityDate)) throw new ValidationError({
+			message: "A compatibility date is an ISO date, like 2026-06-01.",
+			action: "Pass the date as YYYY-MM-DD.",
+			detail: `createWorker('${scriptName}') was given the compatibility date '${compatibilityDate}'.`
+		});
+		const form = new FormData();
+		form.append("metadata", new Blob([JSON.stringify({
+			...metadata,
+			compatibility_date: compatibilityDate,
+			main_module: module.name
+		})], { type: "application/json" }));
+		form.append(module.name, new Blob([module.body], { type: MODULE_CONTENT_TYPE }), module.name);
+		return cloudflareRequest(`create worker '${scriptName}'`, async () => {
+			const envelope = await this.getClient().put(`/accounts/${this.accountId}/workers/scripts/${scriptName}`, {
+				body: form,
+				...requestOptions
+			});
+			if (!envelope.result) throw new CloudflareInvalidResponseError({
+				message: "Cloudflare accepted the Worker upload but returned no script.",
+				detail: `Upload of '${scriptName}' returned a success envelope with a null result.`
+			});
+			return envelope.result;
+		});
+	}
+	/**
+	* Configure the workers.dev subdomain and preview URLs for a script. Both are controlled by the
+	* same endpoint — `previews_enabled` is always sent explicitly so CF does not default it to true.
+	*/
+	async setSubdomainSettings(scriptName, enabled, previewsEnabled = false) {
+		await cloudflareRequest(`set subdomain settings for '${scriptName}'`, () => this.getClient().workers.scripts.subdomain.create(scriptName, {
+			account_id: this.accountId,
+			enabled,
+			previews_enabled: previewsEnabled
+		}));
+	}
+	/** Edit a Worker's settings (observability, logpush, tags, …). */
+	async updateSettings(scriptName, settings) {
+		await cloudflareRequest(`update settings for '${scriptName}'`, () => this.getClient().workers.scripts.settings.edit(scriptName, {
+			account_id: this.accountId,
+			...settings
+		}));
+	}
+	/** Delete a Worker script. */
+	async deleteWorker(scriptName) {
+		await cloudflareRequest(`delete worker '${scriptName}'`, () => this.getClient().workers.scripts.delete(scriptName, { account_id: this.accountId }, requestOptions));
+	}
+	/** List every version of a Worker script. */
+	async listVersions(scriptName) {
+		return cloudflareRequest(`list versions for '${scriptName}'`, async () => {
+			const versions = [];
+			for await (const version of this.getClient().workers.scripts.versions.list(scriptName, { account_id: this.accountId })) versions.push(version);
+			return versions;
+		});
+	}
+	/** Get one version of a Worker script. */
+	async getVersion(scriptName, versionId) {
+		return cloudflareRequest(`get version '${versionId}' for '${scriptName}'`, () => this.getClient().workers.scripts.versions.get(versionId, {
+			account_id: this.accountId,
+			script_name: scriptName
+		}, requestOptions));
+	}
+	/** List a Worker script's deployments. Empty when none exist. */
+	async listDeployments(scriptName) {
+		return cloudflareRequest(`list deployments for '${scriptName}'`, async () => {
+			return (await this.getClient().workers.scripts.deployments.list(scriptName, { account_id: this.accountId }, requestOptions)).deployments ?? [];
+		});
+	}
+	/** Get one deployment of a Worker script. */
+	async getDeployment(scriptName, deploymentId) {
+		return cloudflareRequest(`get deployment '${deploymentId}' for '${scriptName}'`, () => this.getClient().workers.scripts.deployments.get(deploymentId, {
+			account_id: this.accountId,
+			script_name: scriptName
+		}, requestOptions));
+	}
+	/** Deploy a version to 100% of traffic for a Worker script. */
+	async createDeployment(scriptName, versionId) {
+		return cloudflareRequest(`create deployment for '${scriptName}'`, () => this.getClient().workers.scripts.deployments.create(scriptName, {
+			account_id: this.accountId,
+			strategy: "percentage",
+			versions: [{
+				percentage: 100,
+				version_id: versionId
+			}]
+		}, requestOptions));
+	}
+	/** Set a secret on a Worker script. */
+	async addSecret(scriptName, name, value) {
+		await cloudflareRequest(`add secret '${name}' to '${scriptName}'`, () => this.getClient().workers.scripts.secrets.update(scriptName, {
+			account_id: this.accountId,
+			name,
+			text: value,
+			type: "secret_text"
+		}, requestOptions));
+	}
+	/** Delete a secret from a Worker script. */
+	async deleteSecret(scriptName, secretName) {
+		await cloudflareRequest(`delete secret '${secretName}' from '${scriptName}'`, () => this.getClient().workers.scripts.secrets.delete(secretName, {
+			account_id: this.accountId,
+			script_name: scriptName
+		}, requestOptions));
+	}
+	/** List a Worker script's secrets. */
+	async listSecrets(scriptName) {
+		return cloudflareRequest(`list secrets for '${scriptName}'`, async () => {
+			const secrets = [];
+			for await (const secret of this.getClient().workers.scripts.secrets.list(scriptName, { account_id: this.accountId })) secrets.push(secret);
+			return secrets;
+		});
+	}
+	/**
+	* Create a Workers Route on a zone, mapping a hostname pattern to a script. Idempotent: returns the
+	* existing route when one with the same pattern is already present on the zone.
+	*/
+	async addRoute(zoneId, pattern, scriptName) {
+		const existing = await this.getRoute(zoneId, pattern);
+		if (existing) return existing;
+		return cloudflareRequest(`add worker route '${pattern}'`, () => this.getClient().workers.routes.create({
+			zone_id: zoneId,
+			pattern,
+			script: scriptName
+		}, requestOptions));
+	}
+	/** Find a Workers Route on a zone by its pattern. Returns null when none matches. */
+	async getRoute(zoneId, pattern) {
+		return cloudflareRequest(`get worker route '${pattern}'`, async () => {
+			for await (const route of this.getClient().workers.routes.list({ zone_id: zoneId })) if (route.pattern === pattern) return route;
+			return null;
+		});
+	}
+	/** Delete a Workers Route from a zone. */
+	async removeRoute(zoneId, routeId) {
+		await cloudflareRequest(`remove worker route '${routeId}'`, () => this.getClient().workers.routes.delete(routeId, { zone_id: zoneId }, requestOptions));
+	}
+	/** Resolve a queue's id (UUID) from its name. Returns null when no queue on the account matches. */
+	async findQueueIdByName(queueName) {
+		return cloudflareRequest(`find queue '${queueName}'`, async () => {
+			for await (const queue of this.getClient().queues.list({ account_id: this.accountId })) if (queue.queue_name === queueName) return queue.queue_id ?? null;
+			return null;
+		});
+	}
+	/**
+	* Subscribe a queue to a Worker's Builds lifecycle events (started/succeeded/failed/canceled).
+	* Idempotent: a CF "already exists" conflict (405 "multiple subscriptions", or 409 "already
+	* exists") is treated as success rather than re-thrown.
+	*/
+	async subscribeBuildEvents(subscriptionName, queueId, workerName) {
+		await cloudflareRequest(`subscribe build events for '${workerName}'`, async () => {
+			try {
+				await this.getClient().queues.subscriptions.create({
+					account_id: this.accountId,
+					name: subscriptionName,
+					destination: {
+						type: "queues.queue",
+						queue_id: queueId
+					},
+					source: {
+						type: "workersBuilds.worker",
+						worker_name: workerName
+					},
+					events: [
+						"build.started",
+						"build.succeeded",
+						"build.failed",
+						"build.canceled"
+					]
+				});
+			} catch (error) {
+				const message = messageOf(error);
+				if (/\b409\b/.test(message) || /already exists/i.test(message) || /multiple subscriptions/i.test(message)) return;
+				throw error;
+			}
+		});
+	}
+	/**
+	* The account's `workers.dev` subdomain, or `null` if none is registered. Deploying a Worker that
+	* hosts Workflows requires the account to have one (a one-time account bootstrap), so provisioning
+	* checks this up front. The CF API returns a 404-style error when absent; that maps to `null`.
+	*/
+	async accountSubdomain() {
+		try {
+			return (await this.getClient().workers.subdomains.get({ account_id: this.accountId })).subdomain ?? null;
+		} catch {
+			return null;
+		}
+	}
+	getServiceType() {
+		return "Cloudflare Workers";
+	}
+	/** Prove access by listing the account's Workers. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.getClient().workers.scripts.list({ account_id: this.accountId });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { CloudflareWorkersManager };

package/dist/workers/workersProvisioner.d.ts

@@ -0,0 +1,80 @@
+import type { CloudflareManagerConfig } from "../client/manager";
+import type { CfRepoConnection, CfTriggerEnvVar } from "./buildsTypes";
+/** Describes the git repo a build trigger should clone, in provider-neutral terms. */
+export interface BuildRepo {
+    /** The git provider hosting the repo. */
+    providerType: "gitlab" | "github";
+    /** The repository's id in the git provider. */
+    repoId: string;
+    /** The repo path relative to the provider account. */
+    repoName: string;
+    /** The provider account identifier (e.g. 'group:15366484'). */
+    providerAccountId: string;
+    /** The provider account display name. */
+    providerAccountName: string;
+}
+/** Everything `setupBuildTrigger` needs, all caller-supplied — no environment-specific defaults. */
+export interface BuildTriggerSetup {
+    /** The Worker the trigger builds, by name (resolved to its immutable id internally). */
+    workerName: string;
+    /** The repo to clone. */
+    repo: BuildRepo;
+    /** The build token UUID the trigger authenticates with. */
+    buildTokenUuid: string;
+    /** The trigger's human-readable name. */
+    triggerName: string;
+    /** Branch patterns that auto-fire the trigger (must be non-empty). */
+    branchIncludes: string[];
+    /** The shell command that builds the Worker. */
+    buildCommand: string;
+    /** The shell command CF Builds runs to deploy after a build. */
+    deployCommand: string;
+    /** Environment variables to set on the trigger. */
+    envVars?: CfTriggerEnvVar[];
+}
+/**
+ * Provisions Cloudflare Workers infrastructure over the REST API: create a Worker, set its secrets,
+ * wire a CF Builds trigger to a repo, register a Workers Route, and subscribe a queue to build
+ * events. A thin orchestrator over `CloudflareWorkersManager` + `CloudflareBuildsManager`.
+ *
+ * Each method is a discrete, idempotent step so a caller (e.g. a Workflow) can resume from the point
+ * of failure rather than from scratch. It carries no environment- or product-specific defaults —
+ * every name, command, and env var is supplied by the caller.
+ */
+export declare class WorkersProvisioner {
+    private readonly workers;
+    private readonly builds;
+    constructor(config: CloudflareManagerConfig);
+    /**
+     * Create the Worker script, enable its workers.dev subdomain, and turn on observability. Returns
+     * the created script's id. workers.dev must be enabled via a separate call after script creation.
+     *
+     * `compatibilityDate` is passed through and not defaulted, which is this class's standing promise
+     * one level down: a compatibility date is a behavior contract in the caller's own account, and the
+     * manager stopped inventing one in #396.
+     */
+    createWorker(workerName: string, compatibilityDate: string, metadata?: Record<string, unknown>): Promise<string>;
+    /** Resolve the immutable hex id ("external_script_id") for a worker, stable across renames. */
+    getWorkerInternalId(workerName: string): Promise<string>;
+    /** Set a secret on a worker. */
+    addWorkerSecret(workerName: string, key: string, value: string): Promise<void>;
+    /**
+     * Create the CF Builds repo connection + trigger and set its env vars, returning the trigger UUID.
+     * Idempotent — `createRepoConnection` is CF's upsert and `upsertTrigger` reconciles an existing
+     * trigger. The trigger is keyed on the worker's immutable internal id (resolved here), not its name.
+     */
+    setupBuildTrigger(setup: BuildTriggerSetup): Promise<string>;
+    /** Create (or upsert) only the repo connection. Useful when a caller manages the trigger itself. */
+    setupRepoConnection(repo: BuildRepo): Promise<CfRepoConnection>;
+    /**
+     * Register a Workers Route on a zone mapping `${hostname}/*` to the worker. Idempotent. Returns the
+     * route id (empty string when CF returns a route without one).
+     */
+    setupWorkerRoute(zoneId: string, workerName: string, hostname: string): Promise<string>;
+    /**
+     * Subscribe a named queue to the worker's Builds lifecycle events. Resolves the queue's id from its
+     * name first; throws `cloudflare/not_configured` when the queue does not exist. Idempotent.
+     */
+    setupBuildEventSubscription(workerName: string, queueName: string): Promise<void>;
+}
+//# sourceMappingURL=workersProvisioner.d.ts.map

package/dist/workers/workersProvisioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workersProvisioner.d.ts","sourceRoot":"","sources":["../../src/workers/workersProvisioner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGvE,sFAAsF;AACtF,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,YAAY,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAClC,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,oGAAoG;AACpG,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IAEnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IAEjD,YAAY,MAAM,EAAE,uBAAuB,EAG1C;IAED;;;;;;;OAOG;IACG,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,EACzB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,OAAO,CAAC,MAAM,CAAC,CAWjB;IAED,+FAA+F;IACzF,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7D;IAED,gCAAgC;IAC1B,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;IAED;;;;OAIG;IACG,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BjE;IAED,oGAAoG;IAC9F,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQpE;IAED;;;OAGG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5F;IAED;;;OAGG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUtF;CACF"}

package/dist/workers/workersProvisioner.js

@@ -0,0 +1,106 @@
+import { CloudflareNotConfiguredError } from "../client/errors.js";
+import { CloudflareBuildsManager } from "./buildsManager.js";
+import { CloudflareWorkersManager } from "./workersManager.js";
+//#region src/workers/workersProvisioner.ts
+/**
+* Provisions Cloudflare Workers infrastructure over the REST API: create a Worker, set its secrets,
+* wire a CF Builds trigger to a repo, register a Workers Route, and subscribe a queue to build
+* events. A thin orchestrator over `CloudflareWorkersManager` + `CloudflareBuildsManager`.
+*
+* Each method is a discrete, idempotent step so a caller (e.g. a Workflow) can resume from the point
+* of failure rather than from scratch. It carries no environment- or product-specific defaults —
+* every name, command, and env var is supplied by the caller.
+*/
+var WorkersProvisioner = class {
+	workers;
+	builds;
+	constructor(config) {
+		this.workers = new CloudflareWorkersManager(config);
+		this.builds = new CloudflareBuildsManager(config);
+	}
+	/**
+	* Create the Worker script, enable its workers.dev subdomain, and turn on observability. Returns
+	* the created script's id. workers.dev must be enabled via a separate call after script creation.
+	*
+	* `compatibilityDate` is passed through and not defaulted, which is this class's standing promise
+	* one level down: a compatibility date is a behavior contract in the caller's own account, and the
+	* manager stopped inventing one in #396.
+	*/
+	async createWorker(workerName, compatibilityDate, metadata = {}) {
+		const script = await this.workers.createWorker(workerName, compatibilityDate, metadata);
+		if (!script.id) throw new CloudflareNotConfiguredError({
+			message: `Worker '${workerName}' was created but returned no script id.`,
+			detail: "The Worker upload returned a script with no id."
+		});
+		await this.workers.setSubdomainSettings(workerName, true, false);
+		await this.workers.updateSettings(workerName, { observability: { enabled: true } });
+		return script.id;
+	}
+	/** Resolve the immutable hex id ("external_script_id") for a worker, stable across renames. */
+	async getWorkerInternalId(workerName) {
+		return this.workers.getWorkerInternalId(workerName);
+	}
+	/** Set a secret on a worker. */
+	async addWorkerSecret(workerName, key, value) {
+		await this.workers.addSecret(workerName, key, value);
+	}
+	/**
+	* Create the CF Builds repo connection + trigger and set its env vars, returning the trigger UUID.
+	* Idempotent — `createRepoConnection` is CF's upsert and `upsertTrigger` reconciles an existing
+	* trigger. The trigger is keyed on the worker's immutable internal id (resolved here), not its name.
+	*/
+	async setupBuildTrigger(setup) {
+		const repoConnection = await this.builds.createRepoConnection({
+			providerType: setup.repo.providerType,
+			repoId: setup.repo.repoId,
+			repoName: setup.repo.repoName,
+			providerAccountId: setup.repo.providerAccountId,
+			providerAccountName: setup.repo.providerAccountName
+		});
+		const externalScriptId = await this.workers.getWorkerInternalId(setup.workerName);
+		const trigger = await this.builds.upsertTrigger({
+			scriptName: externalScriptId,
+			repoConnectionId: repoConnection.repo_connection_uuid,
+			buildTokenUuid: setup.buildTokenUuid,
+			triggerName: setup.triggerName,
+			branchIncludes: setup.branchIncludes,
+			pathIncludes: ["*"],
+			buildCommand: setup.buildCommand,
+			deployCommand: setup.deployCommand
+		});
+		if (setup.envVars && setup.envVars.length > 0) await this.builds.upsertTriggerEnvVars(trigger.trigger_uuid, setup.envVars);
+		return trigger.trigger_uuid;
+	}
+	/** Create (or upsert) only the repo connection. Useful when a caller manages the trigger itself. */
+	async setupRepoConnection(repo) {
+		return this.builds.createRepoConnection({
+			providerType: repo.providerType,
+			repoId: repo.repoId,
+			repoName: repo.repoName,
+			providerAccountId: repo.providerAccountId,
+			providerAccountName: repo.providerAccountName
+		});
+	}
+	/**
+	* Register a Workers Route on a zone mapping `${hostname}/*` to the worker. Idempotent. Returns the
+	* route id (empty string when CF returns a route without one).
+	*/
+	async setupWorkerRoute(zoneId, workerName, hostname) {
+		return (await this.workers.addRoute(zoneId, `${hostname}/*`, workerName)).id ?? "";
+	}
+	/**
+	* Subscribe a named queue to the worker's Builds lifecycle events. Resolves the queue's id from its
+	* name first; throws `cloudflare/not_configured` when the queue does not exist. Idempotent.
+	*/
+	async setupBuildEventSubscription(workerName, queueName) {
+		const queueId = await this.workers.findQueueIdByName(queueName);
+		if (!queueId) throw new CloudflareNotConfiguredError({
+			message: `Queue '${queueName}' was not found on the account.`,
+			action: "Create the queue before provisioning build event subscriptions.",
+			detail: `No queue named '${queueName}' on the account.`
+		});
+		await this.workers.subscribeBuildEvents(`build-events-${workerName}`, queueId, workerName);
+	}
+};
+//#endregion
+export { WorkersProvisioner };