@pithy-sh/cloudflare 0.1.0

package/src/workers/buildsManager.ts

@@ -0,0 +1,348 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import {
+  CloudflareInvalidResponseError,
+  CloudflareRequestError,
+  cloudflareRequest,
+  decodeResponse,
+  messageOf,
+} from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+import {
+  CfBuild,
+  CfBuildLog,
+  CfBuildToken,
+  CfBuildTrigger,
+  CfRepoConnection,
+  type CfTriggerEnvVar,
+} from "./buildsTypes";
+
+/** 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 = 12000;
+
+/** 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(),
+});
+
+/** Arguments for `createRepoConnection`. */
+export interface CreateRepoConnectionArgs {
+  /** 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;
+}
+
+/** Arguments for `upsertTrigger`. */
+export interface UpsertTriggerArgs {
+  /** The immutable Worker id (hex UUID) the trigger builds — not the worker name. */
+  scriptName: string;
+  /** The repo connection UUID to build from. */
+  repoConnectionId: string;
+  /** The build token UUID the trigger authenticates with. */
+  buildTokenUuid: string;
+  /** The trigger's human-readable name. */
+  triggerName: string;
+  /** Branch patterns whose pushes auto-fire the trigger (must be non-empty). */
+  branchIncludes: string[];
+  /** Branch patterns excluded from auto-firing. */
+  branchExcludes?: string[];
+  /** Path patterns whose changes auto-fire the trigger. */
+  pathIncludes?: string[];
+  /** The shell command that builds the Worker. */
+  buildCommand: string;
+  /** The shell command CF Builds runs to deploy after a build. */
+  deployCommand: string;
+  /** The repo subdirectory builds run from. Defaults to '/'. */
+  rootDirectory?: string;
+  /** Whether build caching is enabled. Defaults to true. */
+  buildCachingEnabled?: boolean;
+}
+
+/** A subset of trigger fields that can be patched after creation. */
+export interface UpdateTriggerArgs {
+  /** A branch filter to set on the trigger. */
+  branchFilter?: string;
+  /** The build command to set. */
+  buildCommand?: string;
+  /** The deploy command to set. */
+  deployCommand?: string;
+  /** The root directory to set. */
+  rootDirectory?: string;
+}
+
+/**
+ * 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).
+ */
+export class CloudflareBuildsManager 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`.
+   */
+  private async call(
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
+    path: string,
+    body?: unknown,
+  ): Promise<unknown> {
+    const response = await fetch(`${CF_API_BASE}${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${this.getApiToken()}`,
+        ...(body !== undefined ? { "content-type": "application/json" } : {}),
+      },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+
+    const text = await response.text();
+
+    let parsed: unknown = {};
+    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);
+    // CF signals failure two ways: a non-2xx status, or a 200 body with `success: false`.
+    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 is number => c !== undefined)
+        : [];
+      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, 2000),
+      });
+    }
+
+    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: CreateRepoConnectionArgs): Promise<CfRepoConnection> {
+    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: UpsertTriggerArgs): Promise<CfBuildTrigger> {
+    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(): Promise<CfBuildToken[]> {
+    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: string, args: UpdateTriggerArgs): Promise<CfBuildTrigger> {
+    return cloudflareRequest("update trigger", async () => {
+      const body: Record<string, string> = {};
+      if (args.branchFilter !== undefined) body.branch_filter = args.branchFilter;
+      if (args.buildCommand !== undefined) body.build_command = args.buildCommand;
+      if (args.deployCommand !== undefined) body.deploy_command = args.deployCommand;
+      if (args.rootDirectory !== undefined) 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: string): Promise<void> {
+    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: string, branch: string, commitHash: string): Promise<CfBuild> {
+    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: string): Promise<CfBuild> {
+    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: string): Promise<void> {
+    await cloudflareRequest("cancel build", () =>
+      this.call("POST", `/accounts/${this.getAccountId()}/builds/${buildId}/cancel`),
+    );
+  }
+
+  /** Get the log output for a build. */
+  async getBuildLogs(buildId: string): Promise<CfBuildLog[]> {
+    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: string): Promise<CfBuild[]> {
+    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: string): Promise<CfBuildTrigger[]> {
+    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: string, envVars: CfTriggerEnvVar[]): Promise<void> {
+    await cloudflareRequest("upsert trigger env vars", () => {
+      const body: Record<string, { is_secret: boolean; value: string }> = {};
+      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(): string {
+    return "Cloudflare Builds";
+  }
+
+  /** Prove access by listing build triggers. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    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. */
+  private validate<T extends z.ZodType>(schema: T, raw: unknown, label: string): z.output<T> {
+    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: unknown, code: number): boolean {
+  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}`);
+}

package/src/workers/buildsTypes.ts

@@ -0,0 +1,122 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+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 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.");
+export type CfRepoConnection = z.output<typeof CfRepoConnection>;
+
+/** A build trigger linking a Worker script to a repo connection and its build/deploy commands. */
+export 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.");
+export type CfBuildTrigger = z.output<typeof CfBuildTrigger>;
+
+/** Metadata about the commit a build ran against. */
+export 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.");
+export type CfBuildTriggerMetadata = z.output<typeof CfBuildTriggerMetadata>;
+
+/** A back-reference from a build to the trigger that produced it. */
+export 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.");
+export type CfBuildTriggerRef = z.output<typeof CfBuildTriggerRef>;
+
+/** A single execution of a build trigger and its lifecycle state. */
+export 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.");
+export type CfBuild = z.output<typeof CfBuild>;
+
+/** One line of a build's log output. */
+export 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.");
+export type CfBuildLog = z.output<typeof CfBuildLog>;
+
+/** An environment variable set on a build trigger. */
+export 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.");
+export type CfTriggerEnvVar = z.output<typeof CfTriggerEnvVar>;
+
+/** A build token usable by triggers on the account. */
+export 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.");
+export type CfBuildToken = z.output<typeof CfBuildToken>;

package/src/workers/workersBuildEvent.ts

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+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 const WorkersBuildStatus = z
+  .enum(["queued", "initializing", "running", "stopped"])
+  .describe("A Cloudflare Builds lifecycle state.");
+export type WorkersBuildStatus = z.infer<typeof WorkersBuildStatus>;
+
+/** The terminal result of a build, set once it reaches `stopped`. */
+export const WorkersBuildOutcome = z
+  .enum(["success", "fail", "skipped", "cancelled", "terminated"])
+  .describe("The terminal outcome of a Cloudflare build.");
+export type WorkersBuildOutcome = z.infer<typeof WorkersBuildOutcome>;
+
+/** What kicked off a build. */
+export const WorkersTriggerSource = z
+  .enum(["push", "pull_request", "manual", "api"])
+  .describe("What initiated a Cloudflare build.");
+export type WorkersTriggerSource = z.infer<typeof WorkersTriggerSource>;
+
+/** A build lifecycle event delivered to a subscribed queue. */
+export 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.");
+export type WorkersBuildEvent = z.output<typeof WorkersBuildEvent>;