@pithy-sh/cloudflare 0.1.2 → 0.1.4

package/dist/workers/buildsManager.js

@@ -0,0 +1,239 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareInvalidResponseError, CloudflareRequestError, cloudflareRequest, decodeResponse, messageOf } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { CfBuild, CfBuildLog, CfBuildToken, CfBuildTrigger, CfRepoConnection } from "./buildsTypes.js";
+import { z } from "zod";
+//#region src/workers/buildsManager.ts
+/** The Cloudflare REST API v4 base URL. The Builds endpoints live under `/accounts/{id}/builds`. */
+const CF_API_BASE = "https://api.cloudflare.com/client/v4";
+/** CF 409 code 12042: "A trigger already exists for this configuration". */
+const CONFLICT_TRIGGER_EXISTS = 12042;
+/** CF 404 code 12000: "Not found" — returned when a script has no triggers. */
+const NOT_FOUND = 12e3;
+/** The standard `{ result, success, errors, messages }` envelope every CF REST response carries. */
+const CfEnvelope = z.object({
+	result: z.unknown(),
+	success: z.boolean().optional(),
+	errors: z.array(z.object({
+		code: z.number().optional(),
+		message: z.string().optional()
+	}).loose()).optional()
+});
+/**
+* Out-of-Worker access to the Cloudflare Builds API: repo connections, build triggers, builds, and
+* trigger env vars. CF Builds is the CI/CD layer for Workers — it clones a git repo, runs a build
+* command, and reports outcomes.
+*
+* As of the SDK version this package targets, the Builds endpoints are NOT exposed as typed SDK
+* resources, so this manager uses the documented escape hatch (`getApiToken()` + raw `fetch`) against
+* explicit `/accounts/{id}/builds/...` paths. Every request goes through `cloudflareRequest` so
+* failures wrap as `cloudflare/request_failed`, and every response is validated with Zod
+* (`cloudflare/invalid_response` on mismatch).
+*/
+var CloudflareBuildsManager = class extends CloudflareManager {
+	/**
+	* Issue a raw CF REST call and unwrap the `{ result, success, errors }` envelope. A failure —
+	* either a non-2xx status **or** a 200 carrying `success: false` — throws `cloudflare/request_failed`
+	* with the structured CF error codes pinned to the front of `detail` (so idempotency checks read a
+	* stable marker, never a substring a verbose body could push past truncation). An unparseable body
+	* throws `cloudflare/invalid_response`.
+	*/
+	async call(method, path, body) {
+		const response = await fetch(`${CF_API_BASE}${path}`, {
+			method,
+			headers: {
+				authorization: `Bearer ${this.getApiToken()}`,
+				...body !== void 0 ? { "content-type": "application/json" } : {}
+			},
+			...body !== void 0 ? { body: JSON.stringify(body) } : {}
+		});
+		const text = await response.text();
+		let parsed = {};
+		if (text.length > 0) try {
+			parsed = JSON.parse(text);
+		} catch (error) {
+			throw new CloudflareInvalidResponseError({
+				message: "A Cloudflare Builds response was not valid JSON.",
+				detail: `${method} ${path}: ${messageOf(error)}`
+			});
+		}
+		const envelope = CfEnvelope.safeParse(parsed);
+		const apiReportedFailure = envelope.success && envelope.data.success === false;
+		if (!response.ok || apiReportedFailure) {
+			const codes = envelope.success ? (envelope.data.errors ?? []).map((e) => e.code).filter((c) => c !== void 0) : [];
+			const marker = codes.length > 0 ? `[cf-codes:${codes.join(",")}] ` : "";
+			throw new CloudflareRequestError({
+				message: `Cloudflare Builds returned ${response.status}.`,
+				detail: `${marker}${method} ${path} → ${response.status}: ${text}`.slice(0, 2e3)
+			});
+		}
+		return envelope.success ? envelope.data.result : parsed;
+	}
+	/**
+	* Register a git repository with CF Builds. `PUT /builds/repos/connections` is CF's documented
+	* upsert — calling with the same repo id returns the existing connection.
+	*/
+	async createRepoConnection(args) {
+		return cloudflareRequest("create repo connection", async () => {
+			const result = await this.call("PUT", `/accounts/${this.getAccountId()}/builds/repos/connections`, {
+				provider_type: args.providerType,
+				repo_id: args.repoId,
+				repo_name: args.repoName,
+				provider_account_id: args.providerAccountId,
+				provider_account_name: args.providerAccountName
+			});
+			return this.validate(CfRepoConnection, result, "repo connection");
+		});
+	}
+	/**
+	* Upsert a build trigger linking a Worker script to a repo. Tries `POST /builds/triggers`; on the
+	* 409 "trigger already exists" conflict, falls back to listing the script's triggers and returning
+	* the matching one. Idempotent.
+	*/
+	async upsertTrigger(args) {
+		return cloudflareRequest("upsert trigger", async () => {
+			try {
+				const result = await this.call("POST", `/accounts/${this.getAccountId()}/builds/triggers`, {
+					external_script_id: args.scriptName,
+					repo_connection_uuid: args.repoConnectionId,
+					build_token_uuid: args.buildTokenUuid,
+					trigger_name: args.triggerName,
+					branch_includes: args.branchIncludes,
+					branch_excludes: args.branchExcludes ?? [],
+					path_includes: args.pathIncludes ?? ["*"],
+					build_command: args.buildCommand,
+					deploy_command: args.deployCommand,
+					root_directory: args.rootDirectory ?? "/",
+					build_caching_enabled: args.buildCachingEnabled ?? true
+				});
+				return this.validate(CfBuildTrigger, result, "build trigger");
+			} catch (error) {
+				if (hasErrorCode(error, CONFLICT_TRIGGER_EXISTS)) {
+					const existing = await this.listTriggersByScript(args.scriptName);
+					const match = existing.find((t) => t.trigger_name === args.triggerName) ?? existing.find((t) => JSON.stringify(t.branch_includes) === JSON.stringify(args.branchIncludes));
+					if (match) return match;
+				}
+				throw error;
+			}
+		});
+	}
+	/** List the build tokens available on the account. */
+	async listBuildTokens() {
+		return cloudflareRequest("list build tokens", async () => {
+			const result = await this.call("GET", `/accounts/${this.getAccountId()}/builds/tokens`);
+			return this.validate(z.array(CfBuildToken), Array.isArray(result) ? result : [], "build tokens");
+		});
+	}
+	/** Patch an existing build trigger's configuration. */
+	async updateTrigger(triggerId, args) {
+		return cloudflareRequest("update trigger", async () => {
+			const body = {};
+			if (args.branchFilter !== void 0) body.branch_filter = args.branchFilter;
+			if (args.buildCommand !== void 0) body.build_command = args.buildCommand;
+			if (args.deployCommand !== void 0) body.deploy_command = args.deployCommand;
+			if (args.rootDirectory !== void 0) body.root_directory = args.rootDirectory;
+			const result = await this.call("PUT", `/accounts/${this.getAccountId()}/builds/triggers/${triggerId}`, body);
+			return this.validate(CfBuildTrigger, result, "build trigger");
+		});
+	}
+	/** Delete a build trigger. */
+	async deleteTrigger(triggerId) {
+		await cloudflareRequest("delete trigger", () => this.call("DELETE", `/accounts/${this.getAccountId()}/builds/triggers/${triggerId}`));
+	}
+	/** Manually start a build for a trigger at a specific branch + commit. */
+	async triggerManualBuild(triggerId, branch, commitHash) {
+		return cloudflareRequest("trigger manual build", async () => {
+			const result = await this.call("POST", `/accounts/${this.getAccountId()}/builds/triggers/${triggerId}/builds`, {
+				branch,
+				commit_hash: commitHash
+			});
+			return this.validate(CfBuild, result, "build");
+		});
+	}
+	/** Get a build's current status and metadata by id. */
+	async getBuild(buildId) {
+		return cloudflareRequest("get build", async () => {
+			const result = await this.call("GET", `/accounts/${this.getAccountId()}/builds/${buildId}`);
+			return this.validate(CfBuild, result, "build");
+		});
+	}
+	/** Cancel a running build. */
+	async cancelBuild(buildId) {
+		await cloudflareRequest("cancel build", () => this.call("POST", `/accounts/${this.getAccountId()}/builds/${buildId}/cancel`));
+	}
+	/** Get the log output for a build. */
+	async getBuildLogs(buildId) {
+		return cloudflareRequest("get build logs", async () => {
+			const result = await this.call("GET", `/accounts/${this.getAccountId()}/builds/${buildId}/logs`);
+			return this.validate(z.array(CfBuildLog), result, "build logs");
+		});
+	}
+	/** List all builds for a Worker script. */
+	async listBuildsByScript(scriptName) {
+		return cloudflareRequest("list builds by script", async () => {
+			const result = await this.call("GET", `/accounts/${this.getAccountId()}/builds?script_name=${encodeURIComponent(scriptName)}`);
+			return this.validate(z.array(CfBuild), result, "builds");
+		});
+	}
+	/**
+	* List the build triggers for a Worker script. `externalScriptId` must be the immutable Worker id
+	* (hex UUID), resolved via `CloudflareWorkersManager.getWorkerInternalId`. Returns an empty array
+	* when the script has no triggers (CF 404 code 12000).
+	*/
+	async listTriggersByScript(externalScriptId) {
+		return cloudflareRequest("list triggers by script", async () => {
+			try {
+				const result = await this.call("GET", `/accounts/${this.getAccountId()}/builds/workers/${encodeURIComponent(externalScriptId)}/triggers`);
+				return this.validate(z.array(CfBuildTrigger), result, "build triggers");
+			} catch (error) {
+				if (hasErrorCode(error, NOT_FOUND)) return [];
+				throw error;
+			}
+		});
+	}
+	/**
+	* Bulk-upsert environment variables on a build trigger. The wire body is a map keyed by variable
+	* name (`{ NAME: { is_secret, value }, ... }`), not an array.
+	*/
+	async upsertTriggerEnvVars(triggerId, envVars) {
+		await cloudflareRequest("upsert trigger env vars", () => {
+			const body = {};
+			for (const variable of envVars) body[variable.name] = {
+				is_secret: variable.type === "secret_text",
+				value: variable.value
+			};
+			return this.call("PATCH", `/accounts/${this.getAccountId()}/builds/triggers/${triggerId}/environment_variables`, body);
+		});
+	}
+	getServiceType() {
+		return "Cloudflare Builds";
+	}
+	/** Prove access by listing build triggers. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.call("GET", `/accounts/${this.getAccountId()}/builds/triggers`);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** Validate a raw CF result against a Zod schema, throwing `cloudflare/invalid_response` on mismatch. */
+	validate(schema, raw, label) {
+		return decodeResponse(schema, raw, `Builds ${label}`);
+	}
+};
+/**
+* Whether a thrown `CloudflareRequestError` carries the given CF error code. Reads the `[cf-codes:…]`
+* marker `call()` pins to the front of `detail` (stable across the 2000-char truncation); falls back
+* to a substring scan for errors raised without the structured marker.
+*/
+function hasErrorCode(error, code) {
+	if (!(error instanceof CloudflareRequestError)) return false;
+	const detail = error.payload.detail ?? "";
+	const marker = detail.match(/^\[cf-codes:([\d,]+)\]/);
+	if (marker?.[1]) return marker[1].split(",").includes(String(code));
+	return detail.includes(`"code":${code}`) || detail.includes(`"code": ${code}`);
+}
+//#endregion
+export { CloudflareBuildsManager };

package/dist/workers/buildsTypes.d.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * Zod schemas for the Cloudflare Builds REST API.
+ *
+ * CF Builds provides CI/CD for Workers — it clones a git repo, runs a build command, and optionally
+ * runs a deploy command. As of the SDK version this package targets, the Builds endpoints are not
+ * exposed as typed SDK resources, so `buildsManager` reaches them over raw `fetch` (the documented
+ * escape hatch) and validates every response through the schemas here. ISO-string dates on the wire
+ * are decoded to `Date` via the `JsonDate` codec, so each dated schema round-trips through
+ * `.parse()`/`.encode()`.
+ */
+/** A git-provider repository linked to the Cloudflare account for builds. */
+export declare const CfRepoConnection: z.ZodObject<{
+    repo_connection_uuid: z.ZodString;
+    repo_id: z.ZodString;
+    repo_name: z.ZodString;
+    provider_type: z.ZodString;
+    provider_account_id: z.ZodString;
+    provider_account_name: z.ZodString;
+    created_on: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    modified_on: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    deleted_on: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>>;
+}, z.core.$strip>;
+export type CfRepoConnection = z.output<typeof CfRepoConnection>;
+/** A build trigger linking a Worker script to a repo connection and its build/deploy commands. */
+export declare const CfBuildTrigger: z.ZodObject<{
+    trigger_uuid: z.ZodString;
+    external_script_id: z.ZodString;
+    build_token_uuid: z.ZodString;
+    build_token_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    trigger_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    build_command: z.ZodString;
+    deploy_command: z.ZodString;
+    root_directory: z.ZodString;
+    branch_includes: z.ZodArray<z.ZodString>;
+    branch_excludes: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    path_includes: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    path_excludes: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    build_caching_enabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    created_on: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    modified_on: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    deleted_on: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>>;
+}, z.core.$strip>;
+export type CfBuildTrigger = z.output<typeof CfBuildTrigger>;
+/** Metadata about the commit a build ran against. */
+export declare const CfBuildTriggerMetadata: z.ZodObject<{
+    branch: z.ZodString;
+    commit_hash: z.ZodString;
+    build_trigger_source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type CfBuildTriggerMetadata = z.output<typeof CfBuildTriggerMetadata>;
+/** A back-reference from a build to the trigger that produced it. */
+export declare const CfBuildTriggerRef: z.ZodObject<{
+    trigger_uuid: z.ZodString;
+    external_script_id: z.ZodString;
+}, z.core.$loose>;
+export type CfBuildTriggerRef = z.output<typeof CfBuildTriggerRef>;
+/** A single execution of a build trigger and its lifecycle state. */
+export declare const CfBuild: z.ZodObject<{
+    build_uuid: z.ZodString;
+    status: z.ZodString;
+    build_outcome: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    initializing_on: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>>;
+    running_on: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>>;
+    stopped_on: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>>;
+    created_on: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    modified_on: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    build_trigger_metadata: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        branch: z.ZodString;
+        commit_hash: z.ZodString;
+        build_trigger_source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>>;
+    trigger: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        trigger_uuid: z.ZodString;
+        external_script_id: z.ZodString;
+    }, z.core.$loose>>>;
+}, z.core.$strip>;
+export type CfBuild = z.output<typeof CfBuild>;
+/** One line of a build's log output. */
+export declare const CfBuildLog: z.ZodObject<{
+    line: z.ZodNumber;
+    timestamp: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type CfBuildLog = z.output<typeof CfBuildLog>;
+/** An environment variable set on a build trigger. */
+export declare const CfTriggerEnvVar: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodString;
+    type: z.ZodEnum<{
+        plain_text: "plain_text";
+        secret_text: "secret_text";
+    }>;
+}, z.core.$strip>;
+export type CfTriggerEnvVar = z.output<typeof CfTriggerEnvVar>;
+/** A build token usable by triggers on the account. */
+export declare const CfBuildToken: z.ZodObject<{
+    build_token_uuid: z.ZodString;
+    build_token_name: z.ZodString;
+}, z.core.$strip>;
+export type CfBuildToken = z.output<typeof CfBuildToken>;
+//# sourceMappingURL=buildsTypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buildsTypes.d.ts","sourceRoot":"","sources":["../../src/workers/buildsTypes.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;GASG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB;;;;;;;;;;iBAY2C,CAAC;AACzE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,kGAAkG;AAClG,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;iBAmBqE,CAAC;AACjG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,qDAAqD;AACrD,eAAO,MAAM,sBAAsB;;;;iBAOuB,CAAC;AAC3D,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E,qEAAqE;AACrE,eAAO,MAAM,iBAAiB;;;iBAMkC,CAAC;AACjE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE,qEAAqE;AACrE,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;iBAawD,CAAC;AAC7E,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,OAAO,CAAC,CAAC;AAE/C,wCAAwC;AACxC,eAAO,MAAM,UAAU;;;;iBAMsC,CAAC;AAC9D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAErD,sDAAsD;AACtD,eAAO,MAAM,eAAe;;;;;;;iBAM8C,CAAC;AAC3E,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,uDAAuD;AACvD,eAAO,MAAM,YAAY;;;iBAKyC,CAAC;AACnE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/workers/buildsTypes.js

@@ -0,0 +1,89 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+//#region src/workers/buildsTypes.ts
+/**
+* Zod schemas for the Cloudflare Builds REST API.
+*
+* CF Builds provides CI/CD for Workers — it clones a git repo, runs a build command, and optionally
+* runs a deploy command. As of the SDK version this package targets, the Builds endpoints are not
+* exposed as typed SDK resources, so `buildsManager` reaches them over raw `fetch` (the documented
+* escape hatch) and validates every response through the schemas here. ISO-string dates on the wire
+* are decoded to `Date` via the `JsonDate` codec, so each dated schema round-trips through
+* `.parse()`/`.encode()`.
+*/
+/** A git-provider repository linked to the Cloudflare account for builds. */
+const CfRepoConnection = z.object({
+	repo_connection_uuid: z.string().describe("The connection's UUID, used to attach build triggers."),
+	repo_id: z.string().describe("The repository's id in the git provider."),
+	repo_name: z.string().describe("The repo path relative to the provider account."),
+	provider_type: z.string().describe("The git provider (e.g. 'gitlab', 'github')."),
+	provider_account_id: z.string().describe("The provider account identifier (e.g. 'group:15366484')."),
+	provider_account_name: z.string().describe("The provider account display name."),
+	created_on: JsonDate.describe("When the connection was created (ISO-8601 on the wire, Date in JS)."),
+	modified_on: JsonDate.describe("When the connection was last modified (ISO-8601 on the wire, Date in JS)."),
+	deleted_on: JsonDate.nullish().describe("When the connection was deleted, if it has been.")
+}).describe("A git-provider repository connected to Cloudflare Builds.");
+/** A build trigger linking a Worker script to a repo connection and its build/deploy commands. */
+const CfBuildTrigger = z.object({
+	trigger_uuid: z.string().describe("The trigger's UUID."),
+	external_script_id: z.string().describe("The immutable Worker id (hex UUID) this trigger builds."),
+	build_token_uuid: z.string().describe("The build token this trigger authenticates with."),
+	build_token_name: z.string().nullish().describe("The build token's display name, if returned."),
+	trigger_name: z.string().nullish().describe("The trigger's human-readable name."),
+	build_command: z.string().describe("The shell command that builds the Worker."),
+	deploy_command: z.string().describe("The shell command CF Builds runs to deploy after a build."),
+	root_directory: z.string().describe("The repo subdirectory builds run from."),
+	branch_includes: z.array(z.string()).describe("Branch patterns whose pushes auto-fire the trigger."),
+	branch_excludes: z.array(z.string()).nullish().describe("Branch patterns excluded from auto-firing."),
+	path_includes: z.array(z.string()).nullish().describe("Path patterns whose changes auto-fire the trigger."),
+	path_excludes: z.array(z.string()).nullish().describe("Path patterns excluded from auto-firing."),
+	build_caching_enabled: z.boolean().nullish().describe("Whether build caching is enabled for the trigger."),
+	created_on: JsonDate.describe("When the trigger was created (ISO-8601 on the wire, Date in JS)."),
+	modified_on: JsonDate.describe("When the trigger was last modified (ISO-8601 on the wire, Date in JS)."),
+	deleted_on: JsonDate.nullish().describe("When the trigger was deleted, if it has been.")
+}).describe("A Cloudflare Builds trigger binding a Worker script to a repo and build commands.");
+/** Metadata about the commit a build ran against. */
+const CfBuildTriggerMetadata = z.object({
+	branch: z.string().describe("The git branch the build ran against."),
+	commit_hash: z.string().describe("The git commit SHA the build ran against."),
+	build_trigger_source: z.string().nullish().describe("How the build was initiated (push, manual, api, …).")
+}).loose().describe("Commit/branch metadata attached to a build.");
+/** A back-reference from a build to the trigger that produced it. */
+const CfBuildTriggerRef = z.object({
+	trigger_uuid: z.string().describe("The producing trigger's UUID."),
+	external_script_id: z.string().describe("The immutable Worker id the trigger targets.")
+}).loose().describe("A reference to the trigger that produced a build.");
+/** A single execution of a build trigger and its lifecycle state. */
+const CfBuild = z.object({
+	build_uuid: z.string().describe("The build's identifier."),
+	status: z.string().describe("The build's lifecycle state (queued, initializing, running, stopped)."),
+	build_outcome: z.string().nullish().describe("The final result, present once the build completes."),
+	initializing_on: JsonDate.nullish().describe("When the build began initializing (ISO-8601 on the wire)."),
+	running_on: JsonDate.nullish().describe("When execution began (ISO-8601 on the wire, Date in JS)."),
+	stopped_on: JsonDate.nullish().describe("When the build finished (ISO-8601 on the wire, Date in JS)."),
+	created_on: JsonDate.describe("When the build was queued (ISO-8601 on the wire, Date in JS)."),
+	modified_on: JsonDate.describe("When the build's status last changed (ISO-8601 on the wire, Date in JS)."),
+	build_trigger_metadata: CfBuildTriggerMetadata.nullish().describe("Commit/branch metadata for the build."),
+	trigger: CfBuildTriggerRef.nullish().describe("The trigger that produced this build.")
+}).describe("A single Cloudflare Builds execution and its lifecycle state.");
+/** One line of a build's log output. */
+const CfBuildLog = z.object({
+	line: z.number().describe("The log line number."),
+	timestamp: JsonDate.describe("When the line was emitted (ISO-8601 on the wire, Date in JS)."),
+	message: z.string().describe("The log message content.")
+}).describe("A single line of Cloudflare Builds log output.");
+/** An environment variable set on a build trigger. */
+const CfTriggerEnvVar = z.object({
+	name: z.string().describe("The environment variable's name."),
+	value: z.string().describe("The environment variable's value."),
+	type: z.enum(["plain_text", "secret_text"]).describe("Whether the value is stored encrypted at rest.")
+}).describe("An environment variable set on a Cloudflare Builds trigger.");
+/** A build token usable by triggers on the account. */
+const CfBuildToken = z.object({
+	build_token_uuid: z.string().describe("The build token's UUID."),
+	build_token_name: z.string().describe("The build token's display name.")
+}).describe("A Cloudflare Builds token available on the account.");
+//#endregion
+export { CfBuild, CfBuildLog, CfBuildToken, CfBuildTrigger, CfBuildTriggerMetadata, CfBuildTriggerRef, CfRepoConnection, CfTriggerEnvVar };

package/dist/workers/workersBuildEvent.d.ts

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * The shape of a Cloudflare Workers Builds lifecycle event, as delivered to a subscribed queue.
+ * A subscription (created via `workersProvisioner.setupBuildEventSubscription`) pushes one of these
+ * each time a build changes state. Consumers validate the raw message through `WorkersBuildEvent`
+ * before trusting it; ISO-string dates decode to `Date` via `JsonDate`, so the schema round-trips.
+ */
+/** Where a build's lifecycle currently sits. */
+export declare const WorkersBuildStatus: z.ZodEnum<{
+    initializing: "initializing";
+    queued: "queued";
+    running: "running";
+    stopped: "stopped";
+}>;
+export type WorkersBuildStatus = z.infer<typeof WorkersBuildStatus>;
+/** The terminal result of a build, set once it reaches `stopped`. */
+export declare const WorkersBuildOutcome: z.ZodEnum<{
+    cancelled: "cancelled";
+    fail: "fail";
+    skipped: "skipped";
+    success: "success";
+    terminated: "terminated";
+}>;
+export type WorkersBuildOutcome = z.infer<typeof WorkersBuildOutcome>;
+/** What kicked off a build. */
+export declare const WorkersTriggerSource: z.ZodEnum<{
+    api: "api";
+    manual: "manual";
+    pull_request: "pull_request";
+    push: "push";
+}>;
+export type WorkersTriggerSource = z.infer<typeof WorkersTriggerSource>;
+/** A build lifecycle event delivered to a subscribed queue. */
+export declare const WorkersBuildEvent: z.ZodObject<{
+    build_id: z.ZodString;
+    script_name: z.ZodString;
+    trigger_id: z.ZodString;
+    trigger_source: z.ZodEnum<{
+        api: "api";
+        manual: "manual";
+        pull_request: "pull_request";
+        push: "push";
+    }>;
+    status: z.ZodEnum<{
+        initializing: "initializing";
+        queued: "queued";
+        running: "running";
+        stopped: "stopped";
+    }>;
+    outcome: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        cancelled: "cancelled";
+        fail: "fail";
+        skipped: "skipped";
+        success: "success";
+        terminated: "terminated";
+    }>>>;
+    branch: z.ZodString;
+    commit_hash: z.ZodString;
+    started_at: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>>;
+    completed_at: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>>;
+    created_at: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type WorkersBuildEvent = z.output<typeof WorkersBuildEvent>;
+//# sourceMappingURL=workersBuildEvent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workersBuildEvent.d.ts","sourceRoot":"","sources":["../../src/workers/workersBuildEvent.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AAEH,gDAAgD;AAChD,eAAO,MAAM,kBAAkB;;;;;EAEoB,CAAC;AACpD,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,qEAAqE;AACrE,eAAO,MAAM,mBAAmB;;;;;;EAE0B,CAAC;AAC3D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,+BAA+B;AAC/B,eAAO,MAAM,oBAAoB;;;;;EAEgB,CAAC;AAClD,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAc6D,CAAC;AAC5F,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/workers/workersBuildEvent.js

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+//#region src/workers/workersBuildEvent.ts
+/**
+* The shape of a Cloudflare Workers Builds lifecycle event, as delivered to a subscribed queue.
+* A subscription (created via `workersProvisioner.setupBuildEventSubscription`) pushes one of these
+* each time a build changes state. Consumers validate the raw message through `WorkersBuildEvent`
+* before trusting it; ISO-string dates decode to `Date` via `JsonDate`, so the schema round-trips.
+*/
+/** Where a build's lifecycle currently sits. */
+const WorkersBuildStatus = z.enum([
+	"queued",
+	"initializing",
+	"running",
+	"stopped"
+]).describe("A Cloudflare Builds lifecycle state.");
+/** The terminal result of a build, set once it reaches `stopped`. */
+const WorkersBuildOutcome = z.enum([
+	"success",
+	"fail",
+	"skipped",
+	"cancelled",
+	"terminated"
+]).describe("The terminal outcome of a Cloudflare build.");
+/** What kicked off a build. */
+const WorkersTriggerSource = z.enum([
+	"push",
+	"pull_request",
+	"manual",
+	"api"
+]).describe("What initiated a Cloudflare build.");
+/** A build lifecycle event delivered to a subscribed queue. */
+const WorkersBuildEvent = z.object({
+	build_id: z.string().describe("The build's unique identifier from CF Builds."),
+	script_name: z.string().describe("The Worker script this build targets."),
+	trigger_id: z.string().describe("The build trigger that initiated this build."),
+	trigger_source: WorkersTriggerSource.describe("How the build was initiated."),
+	status: WorkersBuildStatus.describe("The build's current lifecycle state."),
+	outcome: WorkersBuildOutcome.nullish().describe("The final result, set once status reaches 'stopped'."),
+	branch: z.string().describe("The git branch that was built."),
+	commit_hash: z.string().describe("The git commit SHA that was built."),
+	started_at: JsonDate.nullish().describe("When execution began (ISO-8601 on the wire, Date in JS)."),
+	completed_at: JsonDate.nullish().describe("When the build finished (ISO-8601 on the wire, Date in JS)."),
+	created_at: JsonDate.describe("When the build was queued (ISO-8601 on the wire, Date in JS).")
+}).describe("A Cloudflare Workers Builds lifecycle event delivered to a subscribed queue.");
+//#endregion
+export { WorkersBuildEvent, WorkersBuildOutcome, WorkersBuildStatus, WorkersTriggerSource };