@suluk/cloudflare 0.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@suluk/cloudflare",
+  "version": "0.1.0",
+  "description": "Butter-smooth, API-driven provisioning + deployment for a Suluk app on Cloudflare — no wrangler CLI. A typed REST client + idempotent provisioners (D1, KV, R2, secrets) + the Workers module-script + static-assets upload flow, orchestrated into one deploy(). The platform that ships itself, shipping itself. CANDIDATE tooling.",
+  "publishConfig": {
+  "access": "public"
+},
+"license": "Apache-2.0",
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+  "directory": "tooling/ts/packages/cloudflare"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"module": "src/index.ts",
+"types": "src/index.ts",
+"exports": {
+".": "./src/index.ts"
+},
+"dependencies": {},
+"devDependencies": {
+"@types/bun": "latest"
+},
+"scripts": {
+"test": "bun test",
+"typecheck": "tsc --noEmit -p ."
+}
+}

package/src/assets.ts

@@ -0,0 +1,66 @@
+/**
+ * The Workers Static-Assets upload flow: build a manifest (path → {hash,size}), open an upload session, push the
+ * file buckets the API asks for, and return the COMPLETION JWT to embed in the worker's `assets.jwt`. The manifest
+ * hash is the SHA-256 of the contents (hex). Idempotent: unchanged files aren't re-requested by the session, so a
+ * redeploy only uploads what changed.
+ */
+import type { CloudflareClient } from "./client";
+
+/** One asset: its server path (e.g. "/index.html"), bytes, and content type. */
+export interface AssetFile {
+  path: string;
+  bytes: Uint8Array;
+  contentType: string;
+}
+
+async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", bytes as unknown as ArrayBuffer);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** The Workers-Assets manifest hash: the first 32 hex chars (16 bytes) of the contents' SHA-256. The API rejects
+ *  the full 64-char digest ("file hash size of 64 is too large"). */
+export async function assetHash(bytes: Uint8Array): Promise<string> {
+  return (await sha256Hex(bytes)).slice(0, 32);
+}
+
+const toBase64 = (bytes: Uint8Array): string =>
+  typeof Buffer !== "undefined" ? Buffer.from(bytes).toString("base64") : btoa(String.fromCharCode(...bytes));
+
+export interface UploadSession {
+  jwt: string;
+  /** the file hashes (grouped into buckets) the API still needs uploaded; empty when everything is cached. */
+  buckets?: string[][];
+}
+
+/**
+ * Upload a set of static assets; returns the completion JWT for the worker metadata, or `null` when there are none.
+ * When every file is already cached server-side the session returns no buckets and its own jwt IS the completion token.
+ */
+export async function uploadAssets(cf: CloudflareClient, scriptName: string, files: AssetFile[]): Promise<string | null> {
+  if (!files.length) return null;
+  const acct = await cf.resolveAccountId();
+
+  const byHash = new Map<string, AssetFile>();
+  const manifest: Record<string, { hash: string; size: number }> = {};
+  for (const f of files) {
+    const hash = await assetHash(f.bytes);
+    manifest[f.path] = { hash, size: f.bytes.byteLength };
+    byHash.set(hash, f);
+  }
+
+  const session = await cf.request<UploadSession>("POST", `/accounts/${acct}/workers/scripts/${scriptName}/assets-upload-session`, { json: { manifest } });
+  let completion = session.jwt;
+
+  for (const bucket of session.buckets ?? []) {
+    const form = new FormData();
+    for (const hash of bucket) {
+      const f = byHash.get(hash);
+      if (!f) continue;
+      form.append(hash, new Blob([toBase64(f.bytes)], { type: f.contentType }), hash);
+    }
+    const r = await cf.request<{ jwt?: string } | null>("POST", `/accounts/${acct}/workers/assets/upload`, { query: { base64: true }, body: form, token: session.jwt });
+    if (r?.jwt) completion = r.jwt; // the last successful bucket returns the completion token
+  }
+  return completion;
+}

package/src/client.ts

@@ -0,0 +1,86 @@
+/**
+ * The Cloudflare REST client — a thin, typed wrapper over `https://api.cloudflare.com/client/v4` with Bearer-token
+ * auth, the standard `{ success, errors, result }` envelope, and a CloudflareError that surfaces the API's own error
+ * codes (so a failed deploy says WHY). `fetch` is injectable so the whole library is unit-testable without a network.
+ */
+export interface CloudflareError_t {
+  code: number;
+  message: string;
+}
+
+export class CloudflareError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly errors: CloudflareError_t[],
+    public readonly path: string,
+  ) {
+    super(`Cloudflare API ${status} on ${path}: ${errors.map((e) => `[${e.code}] ${e.message}`).join("; ") || "request failed"}`);
+    this.name = "CloudflareError";
+  }
+}
+
+export interface CloudflareClientOptions {
+  /** an API token (Bearer). Account-scoped: Workers Scripts + D1 (+ KV/R2) Edit, Account Settings Read. */
+  apiToken: string;
+  /** the account id; resolved from the token's first account when omitted. */
+  accountId?: string;
+  /** injected fetch (tests pass a recorder); defaults to the global. */
+  fetch?: typeof fetch;
+  /** API base (default the public Cloudflare API). */
+  baseUrl?: string;
+}
+
+export interface RequestOptions {
+  /** a JSON body (sets content-type + serializes). */
+  json?: unknown;
+  /** a raw body (e.g. FormData / multipart) — takes precedence over `json`. */
+  body?: BodyInit;
+  /** extra headers. */
+  headers?: Record<string, string>;
+  /** query params. */
+  query?: Record<string, string | number | boolean | undefined>;
+  /** override the Bearer token (e.g. an assets-upload JWT). */
+  token?: string;
+}
+
+const API = "https://api.cloudflare.com/client/v4";
+
+export class CloudflareClient {
+  private readonly token: string;
+  private readonly doFetch: typeof fetch;
+  private readonly base: string;
+  accountId: string | undefined;
+
+  constructor(opts: CloudflareClientOptions) {
+    if (!opts.apiToken) throw new Error("@suluk/cloudflare: apiToken is required");
+    this.token = opts.apiToken;
+    this.accountId = opts.accountId;
+    this.doFetch = opts.fetch ?? globalThis.fetch;
+    this.base = opts.baseUrl ?? API;
+  }
+
+  /** Make a request and return the unwrapped `result`, throwing a CloudflareError when `success` is false. */
+  async request<T = unknown>(method: string, path: string, opts: RequestOptions = {}): Promise<T> {
+    const qs = opts.query
+      ? "?" + Object.entries(opts.query).filter(([, v]) => v !== undefined).map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`).join("&")
+      : "";
+    const headers: Record<string, string> = { authorization: `Bearer ${opts.token ?? this.token}`, ...opts.headers };
+    let body = opts.body;
+    if (body === undefined && opts.json !== undefined) { headers["content-type"] = "application/json"; body = JSON.stringify(opts.json); }
+    const res = await this.doFetch(`${this.base}${path}${qs}`, { method, headers, body });
+    const text = await res.text();
+    let env: { success?: boolean; errors?: CloudflareError_t[]; result?: T } = {};
+    try { env = text ? JSON.parse(text) : {}; } catch { /* non-JSON (e.g. an asset upload 200) */ }
+    if (!res.ok || env.success === false) throw new CloudflareError(res.status, env.errors?.length ? env.errors : [{ code: res.status, message: text.slice(0, 200) || res.statusText }], path);
+    return env.result as T;
+  }
+
+  /** Resolve (and cache) the account id — the first account the token can see, unless one was supplied. */
+  async resolveAccountId(): Promise<string> {
+    if (this.accountId) return this.accountId;
+    const accounts = await this.request<{ id: string; name: string }[]>("GET", "/accounts");
+    if (!accounts?.length) throw new Error("@suluk/cloudflare: the token can see no accounts (grant Account Settings: Read)");
+    this.accountId = accounts[0].id;
+    return this.accountId;
+  }
+}

package/src/deploy.ts

@@ -0,0 +1,98 @@
+/**
+ * The one-call deploy — provision → migrate → upload assets → deploy worker → push secrets → set cron, in the order
+ * that makes each step's output feed the next (D1 id + assets JWT become worker bindings; secrets are set AFTER the
+ * script exists and preserved on redeploy via keep_bindings). Pure over an injected CloudflareClient + a resolved
+ * PLAN (bytes, not paths), so it's fully unit-testable; a thin disk-reading wrapper lives in the app's deploy script.
+ */
+import { CloudflareClient, type CloudflareClientOptions } from "./client";
+import { provisionD1, provisionKvNamespace, provisionR2Bucket, applyMigrations, putSecrets, type Migration } from "./resources";
+import { uploadAssets, type AssetFile } from "./assets";
+import { deployWorker, putCronTriggers, type WorkerBinding } from "./worker";
+
+export interface DeployPlan {
+  scriptName: string;
+  /** the bundled worker ES module. */
+  module: string;
+  mainModule?: string;
+  compatibilityDate: string;
+  compatibilityFlags?: string[];
+  /** provision + bind a D1 database, applying each migration once (ledger-tracked, baseline-safe). */
+  d1?: { binding: string; databaseName: string; migrations?: Migration[] };
+  /** provision + bind KV namespaces (binding → title). */
+  kv?: { binding: string; title: string }[];
+  /** provision + bind R2 buckets (binding → bucketName). */
+  r2?: { binding: string; bucketName: string }[];
+  /** static assets to serve (uploaded; bound as ASSETS by default). */
+  assets?: AssetFile[];
+  assetsBinding?: string;
+  assetsConfig?: Record<string, unknown>;
+  /** plain-text vars. */
+  vars?: Record<string, string>;
+  /** encrypted secrets (empty values skipped). */
+  secrets?: Record<string, string | undefined>;
+  /** cron triggers. */
+  crons?: string[];
+  observability?: boolean;
+}
+
+export interface DeployResult {
+  accountId: string;
+  scriptName: string;
+  d1?: { binding: string; id: string };
+  kv: { binding: string; id: string }[];
+  r2: { binding: string; name: string }[];
+  assetsUploaded: number;
+  secretsSet: string[];
+  crons: string[];
+}
+
+export type DeployLog = (msg: string) => void;
+
+/** Orchestrate a full deploy over a client + plan. `log` narrates each step. */
+export async function deploy(cf: CloudflareClient, plan: DeployPlan, log: DeployLog = () => {}): Promise<DeployResult> {
+  const accountId = await cf.resolveAccountId();
+  log(`account ${accountId} · script "${plan.scriptName}"`);
+  const bindings: WorkerBinding[] = [];
+
+  let d1: DeployResult["d1"];
+  if (plan.d1) {
+    const db = await provisionD1(cf, plan.d1.databaseName);
+    log(`D1 "${plan.d1.databaseName}" → ${db.uuid}`);
+    bindings.push({ type: "d1", name: plan.d1.binding, id: db.uuid });
+    d1 = { binding: plan.d1.binding, id: db.uuid };
+    if (plan.d1.migrations?.length) {
+      const newly = await applyMigrations(cf, db.uuid, plan.d1.migrations);
+      log(newly.length ? `  migrations applied/baselined: ${newly.join(", ")}` : `  migrations: all up to date`);
+    }
+  }
+
+  const kv: DeployResult["kv"] = [];
+  for (const k of plan.kv ?? []) { const ns = await provisionKvNamespace(cf, k.title); bindings.push({ type: "kv_namespace", name: k.binding, namespace_id: ns.id }); kv.push({ binding: k.binding, id: ns.id }); log(`KV "${k.title}" → ${ns.id}`); }
+
+  const r2: DeployResult["r2"] = [];
+  for (const b of plan.r2 ?? []) { const bk = await provisionR2Bucket(cf, b.bucketName); bindings.push({ type: "r2_bucket", name: b.binding, bucket_name: bk.name }); r2.push({ binding: b.binding, name: bk.name }); log(`R2 "${bk.name}" bound`); }
+
+  let assetsJwt: string | null = null;
+  if (plan.assets?.length) { assetsJwt = await uploadAssets(cf, plan.scriptName, plan.assets); log(`assets: ${plan.assets.length} files uploaded`); }
+
+  await deployWorker(cf, {
+    name: plan.scriptName, module: plan.module, mainModule: plan.mainModule,
+    compatibilityDate: plan.compatibilityDate, compatibilityFlags: plan.compatibilityFlags,
+    bindings, vars: plan.vars,
+    assets: { jwt: assetsJwt, binding: plan.assetsBinding, config: plan.assetsConfig },
+    observability: plan.observability,
+  });
+  log(`worker "${plan.scriptName}" deployed`);
+
+  const secretsSet = plan.secrets ? await putSecrets(cf, plan.scriptName, plan.secrets) : [];
+  if (secretsSet.length) log(`secrets set: ${secretsSet.join(", ")}`);
+
+  if (plan.crons?.length) { await putCronTriggers(cf, plan.scriptName, plan.crons); log(`crons: ${plan.crons.join(" · ")}`); }
+
+  return { accountId, scriptName: plan.scriptName, d1, kv, r2, assetsUploaded: plan.assets?.length ?? 0, secretsSet, crons: plan.crons ?? [] };
+}
+
+/** Convenience: build a client from token/account options and run a deploy. */
+export async function deployWith(opts: CloudflareClientOptions, plan: DeployPlan, log?: DeployLog): Promise<DeployResult> {
+  return deploy(new CloudflareClient(opts), plan, log);
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @suluk/cloudflare — API-driven provisioning + deployment for a Suluk app on Cloudflare, no wrangler CLI. A typed
+ * REST client, idempotent provisioners (D1 / KV / R2 / secrets), the Workers module-script + static-assets upload
+ * flow, and a one-call `deploy()` that wires them in dependency order. The platform that ships itself, shipping
+ * itself — readable, testable, and the same contract-first discipline as the rest of the suite. CANDIDATE tooling.
+ */
+export { CloudflareClient, CloudflareError, type CloudflareClientOptions, type RequestOptions } from "./client";
+export { provisionD1, queryD1, applyMigrations, provisionKvNamespace, provisionR2Bucket, putSecret, putSecrets, type D1Database, type KvNamespace, type Migration } from "./resources";
+export { uploadAssets, assetHash, type AssetFile, type UploadSession } from "./assets";
+export { deployWorker, putCronTriggers, type DeployWorkerOptions, type WorkerBinding } from "./worker";
+export { deploy, deployWith, type DeployPlan, type DeployResult, type DeployLog } from "./deploy";

package/src/resources.ts

@@ -0,0 +1,104 @@
+/**
+ * Idempotent resource provisioners — create-OR-get, so `deploy` can run repeatedly without "already exists" errors.
+ * Each resolves the account id off the client and uses the Cloudflare API's list-then-create pattern.
+ */
+import type { CloudflareClient } from "./client";
+
+export interface D1Database {
+  uuid: string;
+  name: string;
+}
+
+/** Create-or-get a D1 database by name. */
+export async function provisionD1(cf: CloudflareClient, name: string): Promise<D1Database> {
+  const acct = await cf.resolveAccountId();
+  const existing = await cf.request<D1Database[]>("GET", `/accounts/${acct}/d1/database`, { query: { name } });
+  const hit = (existing ?? []).find((d) => d.name === name);
+  if (hit) return hit;
+  return cf.request<D1Database>("POST", `/accounts/${acct}/d1/database`, { json: { name } });
+}
+
+/** Run SQL against a D1 database (D1 accepts multiple `;`-separated statements per call). */
+export async function queryD1(cf: CloudflareClient, databaseId: string, sql: string): Promise<unknown> {
+  const acct = await cf.resolveAccountId();
+  return cf.request("POST", `/accounts/${acct}/d1/database/${databaseId}/query`, { json: { sql } });
+}
+
+/** Rows from a D1 query response — the API returns `[{ results, success, meta }]` (one per statement). */
+function d1Rows(result: unknown): Record<string, unknown>[] {
+  const arr = Array.isArray(result) ? (result as { results?: Record<string, unknown>[] }[]) : [];
+  return arr[arr.length - 1]?.results ?? [];
+}
+
+export interface Migration {
+  /** a stable identifier (e.g. the file name) — recorded in the ledger so it runs at most once. */
+  name: string;
+  sql: string;
+}
+
+/** SQLite "the schema is already there" errors — benign when baselining a DB migrated before the ledger existed. */
+const IDEMPOTENT_ERR = /duplicate column|already exists|duplicate table/i;
+
+/**
+ * Apply D1 migrations with a LEDGER (`_suluk_migrations`) so each runs exactly once — the missing piece that makes a
+ * redeploy safe. A migration not yet in the ledger is run and recorded; if it fails because the schema is ALREADY
+ * present (a DB migrated by raw execute before tracking existed), that idempotency error is swallowed and the
+ * migration is baselined (recorded), not fatal. Any other SQL error aborts. Returns the names newly recorded.
+ */
+export async function applyMigrations(cf: CloudflareClient, databaseId: string, migrations: Migration[], now: () => number = () => Date.now()): Promise<string[]> {
+  const acct = await cf.resolveAccountId();
+  const run = (sql: string) => cf.request<unknown>("POST", `/accounts/${acct}/d1/database/${databaseId}/query`, { json: { sql } });
+  await run("CREATE TABLE IF NOT EXISTS _suluk_migrations (name TEXT PRIMARY KEY, applied_at INTEGER)");
+  const applied = new Set(d1Rows(await run("SELECT name FROM _suluk_migrations")).map((r) => String(r.name)));
+  const newly: string[] = [];
+  for (const m of migrations) {
+    if (applied.has(m.name)) continue;
+    try {
+      await run(m.sql);
+    } catch (e) {
+      if (!IDEMPOTENT_ERR.test((e as Error).message)) throw e; // a real error — surface it
+      // else: schema already present (pre-ledger) → baseline below, don't abort
+    }
+    await run(`INSERT OR IGNORE INTO _suluk_migrations (name, applied_at) VALUES ('${m.name.replace(/'/g, "''")}', ${now()})`);
+    newly.push(m.name);
+  }
+  return newly;
+}
+
+export interface KvNamespace {
+  id: string;
+  title: string;
+}
+
+/** Create-or-get a Workers KV namespace by title (e.g. a sessions or rate-limit store). */
+export async function provisionKvNamespace(cf: CloudflareClient, title: string): Promise<KvNamespace> {
+  const acct = await cf.resolveAccountId();
+  const list = await cf.request<KvNamespace[]>("GET", `/accounts/${acct}/storage/kv/namespaces`, { query: { per_page: 100 } });
+  const hit = (list ?? []).find((n) => n.title === title);
+  if (hit) return hit;
+  return cf.request<KvNamespace>("POST", `/accounts/${acct}/storage/kv/namespaces`, { json: { title } });
+}
+
+/** Create-or-get an R2 bucket by name (e.g. media/upload storage). */
+export async function provisionR2Bucket(cf: CloudflareClient, name: string): Promise<{ name: string }> {
+  const acct = await cf.resolveAccountId();
+  const res = await cf.request<{ buckets?: { name: string }[] }>("GET", `/accounts/${acct}/r2/buckets`);
+  const hit = (res?.buckets ?? []).find((b) => b.name === name);
+  if (hit) return hit;
+  return cf.request<{ name: string }>("POST", `/accounts/${acct}/r2/buckets`, { json: { name } });
+}
+
+/** Set ONE Worker secret (an encrypted `secret_text` binding). The script must already exist. */
+export async function putSecret(cf: CloudflareClient, scriptName: string, name: string, value: string): Promise<void> {
+  const acct = await cf.resolveAccountId();
+  await cf.request("PUT", `/accounts/${acct}/workers/scripts/${scriptName}/secrets`, { json: { name, text: value, type: "secret_text" } });
+}
+
+/** Set many secrets, skipping empty/undefined values; returns the names actually set. */
+export async function putSecrets(cf: CloudflareClient, scriptName: string, secrets: Record<string, string | undefined>): Promise<string[]> {
+  const set: string[] = [];
+  for (const [name, value] of Object.entries(secrets)) {
+    if (value) { await putSecret(cf, scriptName, name, value); set.push(name); }
+  }
+  return set;
+}

package/src/worker.ts

@@ -0,0 +1,64 @@
+/**
+ * Upload a Workers MODULE script via the multipart `PUT /workers/scripts/{name}` endpoint: a `metadata` JSON part
+ * (main_module + compatibility + bindings + assets + observability) plus the bundled ES-module part. Vars become
+ * `plain_text` bindings; a static-assets JWT becomes the `assets` binding + metadata. `keep_bindings` preserves
+ * existing secret bindings across redeploys, so you set secrets once and they survive.
+ */
+import type { CloudflareClient } from "./client";
+
+export interface WorkerBinding {
+  type: string;
+  name: string;
+  [k: string]: unknown;
+}
+
+export interface DeployWorkerOptions {
+  name: string;
+  /** the bundled ES-module source. */
+  module: string;
+  /** the module filename referenced as `main_module` (default "worker.js"). */
+  mainModule?: string;
+  compatibilityDate: string;
+  compatibilityFlags?: string[];
+  /** typed bindings (d1, kv_namespace, r2_bucket, durable_object_namespace, …). */
+  bindings?: WorkerBinding[];
+  /** plain-text vars → `plain_text` bindings. */
+  vars?: Record<string, string>;
+  /** the static-assets completion JWT (from uploadAssets) + the binding name + assets config. */
+  assets?: { jwt: string | null; binding?: string; config?: Record<string, unknown> };
+  /** cron triggers (e.g. ["0 * * * *"]). */
+  observability?: boolean;
+  /** preserve bindings of these types from the prior version (default keeps secrets across deploys). */
+  keepBindings?: string[];
+}
+
+export async function deployWorker(cf: CloudflareClient, opts: DeployWorkerOptions): Promise<{ id?: string }> {
+  const acct = await cf.resolveAccountId();
+  const main = opts.mainModule ?? "worker.js";
+
+  const bindings: WorkerBinding[] = [...(opts.bindings ?? [])];
+  for (const [name, text] of Object.entries(opts.vars ?? {})) bindings.push({ type: "plain_text", name, text });
+  if (opts.assets?.jwt) bindings.push({ type: "assets", name: opts.assets.binding ?? "ASSETS" });
+
+  const metadata: Record<string, unknown> = {
+    main_module: main,
+    compatibility_date: opts.compatibilityDate,
+    ...(opts.compatibilityFlags?.length ? { compatibility_flags: opts.compatibilityFlags } : {}),
+    bindings,
+    keep_bindings: opts.keepBindings ?? ["secret_text", "secret_key"],
+    ...(opts.assets?.jwt ? { assets: { jwt: opts.assets.jwt, ...(opts.assets.config ? { config: opts.assets.config } : {}) } } : {}),
+    ...(opts.observability !== undefined ? { observability: { enabled: opts.observability } } : {}),
+  };
+
+  const form = new FormData();
+  form.append("metadata", new Blob([JSON.stringify(metadata)], { type: "application/json" }));
+  form.append(main, new Blob([opts.module], { type: "application/javascript+module" }), main);
+
+  return cf.request<{ id?: string }>("PUT", `/accounts/${acct}/workers/scripts/${opts.name}`, { body: form });
+}
+
+/** Set the cron triggers for a script (separate endpoint — metadata doesn't carry them). */
+export async function putCronTriggers(cf: CloudflareClient, scriptName: string, crons: string[]): Promise<void> {
+  const acct = await cf.resolveAccountId();
+  await cf.request("PUT", `/accounts/${acct}/workers/scripts/${scriptName}/schedules`, { json: crons.map((cron) => ({ cron })) });
+}

package/test/cloudflare.test.ts

@@ -0,0 +1,135 @@
+import { test, expect, describe } from "bun:test";
+import { CloudflareClient, CloudflareError, deploy, provisionD1, putSecrets, applyMigrations, assetHash, type AssetFile } from "../src/index";
+
+/** A routing mock fetch: returns the CF `{success,result}` envelope; records every call. */
+function mockCf(routes: [RegExp, unknown | ((ctx: { body: BodyInit | null | undefined }) => unknown)][]) {
+  const calls: { method: string; path: string; query: Record<string, string>; body: BodyInit | null | undefined; token?: string }[] = [];
+  const fetch = (async (url: string, init?: RequestInit) => {
+    const u = new URL(url);
+    const path = u.pathname.replace("/client/v4", ""); // match the logical path, not the API base prefix
+    const method = init?.method ?? "GET";
+    const auth = (init?.headers as Record<string, string>)?.authorization;
+    calls.push({ method, path, query: Object.fromEntries(u.searchParams), body: init?.body, token: auth?.replace("Bearer ", "") });
+    for (const [pat, handler] of routes) {
+      if (pat.test(`${method} ${path}`)) {
+        const result = typeof handler === "function" ? (handler as (c: { body: BodyInit | null | undefined }) => unknown)({ body: init?.body }) : handler;
+        return new Response(JSON.stringify({ success: true, errors: [], result }), { status: 200 });
+      }
+    }
+    return new Response(JSON.stringify({ success: false, errors: [{ code: 404, message: `no route: ${method} ${path}` }] }), { status: 404 });
+  }) as unknown as typeof globalThis.fetch;
+  return { fetch, calls };
+}
+
+describe("CloudflareClient", () => {
+  test("unwraps the result envelope + resolves the account id", async () => {
+    const { fetch } = mockCf([[/GET \/accounts$/, [{ id: "acct_1", name: "Acme" }]]]);
+    const cf = new CloudflareClient({ apiToken: "t", fetch });
+    expect(await cf.resolveAccountId()).toBe("acct_1");
+    expect(await cf.resolveAccountId()).toBe("acct_1"); // cached (no second call needed)
+  });
+  test("throws CloudflareError carrying the API's error codes on success:false", async () => {
+    const fetch = (async () => new Response(JSON.stringify({ success: false, errors: [{ code: 10000, message: "Authentication error" }] }), { status: 403 })) as unknown as typeof globalThis.fetch;
+    const cf = new CloudflareClient({ apiToken: "t", accountId: "a", fetch });
+    await expect(cf.request("GET", "/x")).rejects.toThrow(CloudflareError);
+    await expect(cf.request("GET", "/x")).rejects.toThrow("10000");
+  });
+});
+
+describe("provisioners — idempotent create-or-get", () => {
+  test("provisionD1 returns the existing DB (no create) when one matches", async () => {
+    const { fetch, calls } = mockCf([[/GET .*\/d1\/database$/, [{ uuid: "db_existing", name: "saasuluk-db" }]]]);
+    const cf = new CloudflareClient({ apiToken: "t", accountId: "a", fetch });
+    const db = await provisionD1(cf, "saasuluk-db");
+    expect(db.uuid).toBe("db_existing");
+    expect(calls.some((c) => c.method === "POST" && /d1\/database$/.test(c.path))).toBe(false); // never created
+  });
+  test("provisionD1 creates when none matches", async () => {
+    const { fetch } = mockCf([[/GET .*\/d1\/database$/, []], [/POST .*\/d1\/database$/, { uuid: "db_new", name: "saasuluk-db" }]]);
+    const cf = new CloudflareClient({ apiToken: "t", accountId: "a", fetch });
+    expect((await provisionD1(cf, "saasuluk-db")).uuid).toBe("db_new");
+  });
+  test("assetHash is a 32-char (16-byte) truncated SHA-256 — the API rejects the full 64", async () => {
+    const h = await assetHash(new TextEncoder().encode("hello"));
+    expect(h).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  test("applyMigrations runs only un-recorded migrations + baselines an 'already exists' error", async () => {
+    const ran: string[] = [];
+    const ok = (result: unknown) => new Response(JSON.stringify({ success: true, errors: [], result }), { status: 200 });
+    const fetch = (async (_url: string, init?: RequestInit) => {
+      const sql = JSON.parse(init!.body as string).sql as string;
+      ran.push(sql);
+      if (/SELECT name FROM _suluk_migrations/.test(sql)) return ok([{ results: [{ name: "0001_done.sql" }] }]);
+      if (/__dup__/.test(sql)) return new Response(JSON.stringify({ success: false, errors: [{ code: 7500, message: "duplicate column name: x: SQLITE_ERROR" }] }), { status: 400 });
+      return ok([{ results: [] }]);
+    }) as unknown as typeof globalThis.fetch;
+    const cf = new CloudflareClient({ apiToken: "t", accountId: "a", fetch });
+    const newly = await applyMigrations(cf, "db", [
+      { name: "0001_done.sql", sql: "SHOULD_NOT_RUN" },     // already in the ledger → skipped
+      { name: "0002_new.sql", sql: "CREATE TABLE n(id)" },  // runs
+      { name: "0003_dup.sql", sql: "ALTER __dup__" },       // idempotency error → baselined, not fatal
+    ], () => 1700000000000);
+    expect(newly).toEqual(["0002_new.sql", "0003_dup.sql"]);
+    expect(ran).not.toContain("SHOULD_NOT_RUN");
+  });
+
+  test("putSecrets sets the non-empty secrets only", async () => {
+    const { fetch, calls } = mockCf([[/PUT .*\/secrets$/, {}]]);
+    const cf = new CloudflareClient({ apiToken: "t", accountId: "a", fetch });
+    const set = await putSecrets(cf, "saasuluk", { A: "1", B: "", C: undefined, D: "4" });
+    expect(set).toEqual(["A", "D"]);
+    expect(calls.filter((c) => /\/secrets$/.test(c.path)).length).toBe(2);
+  });
+});
+
+describe("deploy() — full orchestration in dependency order", () => {
+  test("provisions D1, migrates, uploads assets, deploys the worker (correct metadata), sets secrets + crons", async () => {
+    const { fetch, calls } = mockCf([
+      [/GET \/accounts$/, [{ id: "acct_1" }]],
+      [/GET .*\/d1\/database$/, []],
+      [/POST .*\/d1\/database$/, { uuid: "db_1", name: "saasuluk-db" }],
+      [/POST .*\/d1\/database\/db_1\/query$/, [{ results: [] }]], // ledger empty → migration runs
+      [/POST .*\/assets-upload-session$/, { jwt: "session_jwt", buckets: [] }], // all cached → completion = session jwt
+      [/PUT .*\/workers\/scripts\/saasuluk$/, { id: "saasuluk" }],
+      [/PUT .*\/workers\/scripts\/saasuluk\/secrets$/, {}],
+      [/PUT .*\/workers\/scripts\/saasuluk\/schedules$/, []],
+    ]);
+    const cf = new CloudflareClient({ apiToken: "t", fetch });
+    const assets: AssetFile[] = [{ path: "/index.html", bytes: new TextEncoder().encode("<!doctype html>"), contentType: "text/html" }];
+    const res = await deploy(cf, {
+      scriptName: "saasuluk",
+      module: "export default { fetch(){ return new Response('ok') } }",
+      compatibilityDate: "2026-06-01",
+      compatibilityFlags: ["nodejs_compat"],
+      d1: { binding: "DB", databaseName: "saasuluk-db", migrations: [{ name: "0000_domain.sql", sql: "CREATE TABLE t (id INTEGER);" }] },
+      assets,
+      vars: { STRIPE_METER_EVENT_NAME: "saasuluk_cost" },
+      secrets: { BETTER_AUTH_SECRET: "shh", MISSING: "" },
+      crons: ["0 * * * *"],
+      observability: true,
+    });
+
+    expect(res.d1).toEqual({ binding: "DB", id: "db_1" });
+    expect(res.assetsUploaded).toBe(1);
+    expect(res.secretsSet).toEqual(["BETTER_AUTH_SECRET"]);
+    expect(res.crons).toEqual(["0 * * * *"]);
+
+    // the worker PUT carried the right metadata (parse the multipart)
+    const put = calls.find((c) => c.method === "PUT" && /\/workers\/scripts\/saasuluk$/.test(c.path))!;
+    const meta = JSON.parse(await (put.body as FormData).get("metadata")!.text());
+    expect(meta.main_module).toBe("worker.js");
+    expect(meta.compatibility_flags).toEqual(["nodejs_compat"]);
+    expect(meta.bindings).toContainEqual({ type: "d1", name: "DB", id: "db_1" });
+    expect(meta.bindings).toContainEqual({ type: "plain_text", name: "STRIPE_METER_EVENT_NAME", text: "saasuluk_cost" });
+    expect(meta.bindings).toContainEqual({ type: "assets", name: "ASSETS" });
+    expect(meta.assets.jwt).toBe("session_jwt");
+    expect(meta.keep_bindings).toContain("secret_text"); // secrets survive redeploys
+    expect(meta.observability).toEqual({ enabled: true });
+
+    // ordering: D1 provisioned + migrated BEFORE the worker deploy; secrets AFTER
+    const idx = (re: RegExp) => calls.findIndex((c) => re.test(`${c.method} ${c.path}`));
+    expect(idx(/POST .*\/d1\/database\/db_1\/query/)).toBeLessThan(idx(/PUT .*\/workers\/scripts\/saasuluk$/));
+    expect(idx(/PUT .*\/workers\/scripts\/saasuluk$/)).toBeLessThan(idx(/\/secrets$/));
+  });
+});