@tribe-nest/forge 1.20.1 → 2.1.0

package/src/server/_tests/appUserPermissions.spec.ts

@@ -0,0 +1,197 @@
+// Unit tests for the app-user permission helpers — the CLIENT side of the
+// permission store (packages/forge/src/server/appUsers.ts + verifyAppUser's
+// `require` in appAuth.ts). The platform's own rules are tested against a real
+// database in apps/backend/src/routes/public/apps/_tests/appUserPermissions.spec.ts;
+// what CANNOT be tested there is this half, which decides which header a
+// credential becomes and whether a guard says yes.
+//
+// Both are security-relevant in a quiet way: a typo in the header name turns
+// every grant into a 401 (visible), and a wrong `require` turns every guard into
+// a yes (invisible). Hence the emphasis on the negative cases.
+//
+// Coverage:
+//  - credential → header mapping for all three principals
+//  - `Bearer ` normalization (bare token and full header value both work)
+//  - set vs add/remove body shapes
+//  - error surfacing: the platform's message reaches the caller, not "failed"
+//  - verifyAppUser: no token, bad response, permission held / not held / absent
+//  - verifyAppUser: `require` accepts one permission or any-of several
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { setAppUserPermissions, getAppUserPermissions } from "../appUsers";
+import { verifyAppUser } from "../appAuth";
+
+const cfg = { appId: "app-1", apiUrl: "https://api.test" };
+
+type Call = { url: string; init: RequestInit };
+let calls: Call[];
+
+/** Stub `fetch`, recording every call and answering with `body`. */
+function stubFetch(body: unknown, ok = true, status = 200) {
+  calls = [];
+  const fake = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+    calls.push({ url: String(url), init: init ?? {} });
+    return { ok, status, json: async () => body } as unknown as Response;
+  });
+  vi.stubGlobal("fetch", fake);
+  return fake;
+}
+
+const headers = (i = 0) => (calls[i].init.headers ?? {}) as Record<string, string>;
+const body = (i = 0) => JSON.parse(String(calls[i].init.body));
+
+const request = (auth?: string) =>
+  new Request("https://app.test/api/thing", { headers: auth ? { authorization: auth } : {} });
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("setAppUserPermissions — credentials", () => {
+  beforeEach(() => stubFetch({ permissions: ["a"] }));
+
+  it("sends a job token as the app-sync header, NOT as a bearer", async () => {
+    await setAppUserPermissions(cfg, { jobToken: "sync-token" }, "assoc-1", { add: ["a"] });
+    expect(headers()["x-app-sync-token"]).toBe("sync-token");
+    // A job token is not a bearer credential; sending it as one would be
+    // rejected by the platform with an auth error that reads like a bug.
+    expect(headers().authorization).toBeUndefined();
+  });
+
+  it("sends a platform token as a bearer", async () => {
+    await setAppUserPermissions(cfg, { platformToken: "tnp_abc" }, "assoc-1", { add: ["a"] });
+    expect(headers().authorization).toBe("Bearer tnp_abc");
+    expect(headers()["x-app-sync-token"]).toBeUndefined();
+  });
+
+  it("accepts an admin token either bare or as a whole Authorization header", async () => {
+    // The admin lane usually has the full header straight off the request, and
+    // double-prefixing it would produce "Bearer Bearer …".
+    await setAppUserPermissions(cfg, { adminToken: "Bearer jwt-value" }, "assoc-1", { add: ["a"] });
+    expect(headers().authorization).toBe("Bearer jwt-value");
+
+    await setAppUserPermissions(cfg, { adminToken: "jwt-value" }, "assoc-1", { add: ["a"] });
+    expect(headers(1).authorization).toBe("Bearer jwt-value");
+  });
+});
+
+describe("setAppUserPermissions — request shape", () => {
+  beforeEach(() => stubFetch({ permissions: ["kept"] }));
+
+  it("PUTs to the app's own user, url-encoding the association id", async () => {
+    await setAppUserPermissions(cfg, { jobToken: "t" }, "assoc/1", { add: ["a"] });
+    expect(calls[0].url).toBe("https://api.test/public/apps/app-1/users/assoc%2F1/permissions");
+    expect(calls[0].init.method).toBe("PUT");
+    expect(headers()["content-type"]).toBe("application/json");
+  });
+
+  it("sends `permissions` for a full set and `add`/`remove` for a patch", async () => {
+    await setAppUserPermissions(cfg, { jobToken: "t" }, "a1", { set: ["only", "these"] });
+    expect(body()).toEqual({ permissions: ["only", "these"] });
+
+    await setAppUserPermissions(cfg, { jobToken: "t" }, "a1", { add: ["x"], remove: ["y"] });
+    expect(body(1)).toEqual({ add: ["x"], remove: ["y"] });
+  });
+
+  it("returns the resulting list", async () => {
+    expect(await setAppUserPermissions(cfg, { jobToken: "t" }, "a1", { add: ["x"] })).toEqual(["kept"]);
+  });
+
+  it("GETs without a body", async () => {
+    expect(await getAppUserPermissions(cfg, { jobToken: "t" }, "a1")).toEqual(["kept"]);
+    expect(calls[0].init.method).toBe("GET");
+    expect(calls[0].init.body).toBeUndefined();
+  });
+});
+
+describe("setAppUserPermissions — failures", () => {
+  it("surfaces the platform's own message", async () => {
+    // The refusals say WHY and what to do instead ("an app user cannot change
+    // permissions…"). Flattening that to "request failed" would strand the
+    // developer who hit it.
+    stubFetch({ message: "An app user cannot change permissions — not even their own." }, false, 403);
+    await expect(setAppUserPermissions(cfg, { jobToken: "t" }, "a1", { add: ["x"] })).rejects.toThrow(
+      /app user cannot change permissions/,
+    );
+  });
+
+  it("still throws when the error body is not JSON", async () => {
+    calls = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: false, status: 500, json: async () => Promise.reject(new Error("nope")) })),
+    );
+    await expect(setAppUserPermissions(cfg, { jobToken: "t" }, "a1", { add: ["x"] })).rejects.toThrow(/500/);
+  });
+
+  it("treats a response with no permissions as an empty list, not undefined", async () => {
+    stubFetch({});
+    expect(await getAppUserPermissions(cfg, { jobToken: "t" }, "a1")).toEqual([]);
+  });
+});
+
+describe("verifyAppUser — require", () => {
+  const user = (permissions?: unknown) => ({
+    id: "acc-1",
+    associationId: "assoc-1",
+    email: "u@test",
+    firstName: null,
+    lastName: null,
+    status: "active",
+    appId: "app-1",
+    ...(permissions === undefined ? {} : { permissions }),
+  });
+
+  it("returns the user with permissions when no requirement is given", async () => {
+    stubFetch(user(["bookings.manage"]));
+    const result = await verifyAppUser(request("Bearer tok"), cfg);
+    expect(result).toMatchObject({ associationId: "assoc-1", permissions: ["bookings.manage"] });
+  });
+
+  it("passes when the user holds the required permission", async () => {
+    stubFetch(user(["bookings.manage", "reports.view"]));
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: "bookings.manage" })).not.toBeNull();
+  });
+
+  it("REFUSES when the user is signed in but lacks it", async () => {
+    stubFetch(user(["reports.view"]));
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: "bookings.manage" })).toBeNull();
+  });
+
+  it("treats an array requirement as ANY-of", async () => {
+    stubFetch(user(["reports.view"]));
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: ["bookings.manage", "reports.view"] })).not.toBeNull();
+
+    stubFetch(user(["something.else"]));
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: ["bookings.manage", "reports.view"] })).toBeNull();
+  });
+
+  it("holds nothing when the API sends no permissions (older backend)", async () => {
+    // A site on a newer Forge against an older API must degrade to "holds none"
+    // rather than throwing inside a guard — a crash there is a 500 on a route
+    // that should simply have said no.
+    stubFetch(user(undefined));
+    expect(await verifyAppUser(request("Bearer tok"), cfg)).toMatchObject({ permissions: [] });
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: "anything" })).toBeNull();
+  });
+
+  it("returns null without a token, and never calls the platform", async () => {
+    const fetchMock = stubFetch(user([]));
+    expect(await verifyAppUser(request(), cfg, { require: "x" })).toBeNull();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("returns null when the platform rejects the token", async () => {
+    stubFetch({ message: "nope" }, false, 401);
+    expect(await verifyAppUser(request("Bearer bad"), cfg, { require: "x" })).toBeNull();
+  });
+
+  it("returns null when the platform is unreachable", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new Error("network down");
+      }),
+    );
+    // Fail CLOSED: an outage must not open a guarded route.
+    expect(await verifyAppUser(request("Bearer tok"), cfg, { require: "x" })).toBeNull();
+  });
+});

package/src/server/appAuth.ts

@@ -40,6 +40,15 @@ export interface AppUserIdentity {
   lastName: string | null;
   status: string;
   appId: string | null;
+  /**
+   * The permissions YOUR app has given this user. Your own vocabulary — the
+   * platform stores these strings and never interprets them.
+   *
+   * Read here, on the server, from the platform's answer about the caller's
+   * token. That is what makes them trustworthy: nothing the browser sends can
+   * change them, and a revoked permission is gone on the very next request.
+   */
+  permissions: string[];
 }
 
 // The bearer credential the client forwarded, or null. We pass it through as-is
@@ -91,8 +100,26 @@ export async function verifyAppAdmin(request: Request, cfg: AppAuthConfig): Prom
  * user, or `null` when unauthenticated. Use to scope an end-user server action
  * to that user (e.g. read/write only their own rows) — the returned
  * `associationId` is the owner id the platform enforces on `mine`-scoped data.
+ *
+ * Pass `require` to also demand one of YOUR app's permissions, so the check and
+ * the refusal are one line and can't drift apart:
+ *
+ *     const user = await verifyAppUser(request, cfg, { require: "bookings.manage" })
+ *     if (!user) return new Response("forbidden", { status: 403 })
+ *
+ * `require` returns null when the user is signed in but lacks the permission —
+ * same shape as "not signed in", because the route's answer is the same either
+ * way and distinguishing them tells a prober which permission to go hunting for.
+ * Read `user.permissions` yourself when you need the difference.
  */
-export async function verifyAppUser(request: Request, cfg: AppAuthConfig): Promise<AppUserIdentity | null> {
+export async function verifyAppUser(
+  request: Request,
+  cfg: AppAuthConfig,
+  opts?: {
+    /** A permission (or any one of several) the user must hold. */
+    require?: string | string[];
+  },
+): Promise<AppUserIdentity | null> {
   const auth = bearer(request);
   if (!auth) return null;
   try {
@@ -100,7 +127,15 @@ export async function verifyAppUser(request: Request, cfg: AppAuthConfig): Promi
       headers: { authorization: auth },
     });
     if (!res.ok) return null;
-    return (await res.json()) as AppUserIdentity;
+    const user = (await res.json()) as AppUserIdentity;
+    // Older API responses have no `permissions`; treat that as "holds none"
+    // rather than letting `undefined.includes` throw inside a guard.
+    user.permissions = Array.isArray(user.permissions) ? user.permissions : [];
+    if (opts?.require) {
+      const required = Array.isArray(opts.require) ? opts.require : [opts.require];
+      if (!required.some((p) => user.permissions.includes(p))) return null;
+    }
+    return user;
   } catch {
     return null;
   }

package/src/server/appUsers.ts

@@ -0,0 +1,133 @@
+// Permissions for YOUR app's own users. SERVER-ONLY.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// THE ONE RULE: NEVER SET PERMISSIONS FROM WHAT THE BROWSER ASKED FOR.
+//
+// A user's own token can't reach this API — the platform refuses it — so the
+// only way to get self-escalation is to replay a user's request on the app's own
+// credential. That is exactly what a route looks like when it's written without
+// thinking about it:
+//
+//   ❌ WRONG — any signed-in user can now make themselves an admin
+//   const { associationId, permissions } = await request.json()
+//   await setAppUserPermissions(cfg, { jobToken: ctx.token }, associationId, { set: permissions })
+//
+//   ✅ RIGHT — a person with admin rights on the app decided this
+//   const admin = await verifyAppAdmin(request, cfg)
+//   if (!admin) return new Response("forbidden", { status: 403 })
+//   const { associationId, permissions } = await request.json()
+//   await setAppUserPermissions(cfg, { adminToken: request.headers.get("authorization")! },
+//     associationId, { set: permissions })
+//
+//   ✅ ALSO RIGHT — your own code decided, with no user request involved
+//   await setAppUserPermissions(cfg, { jobToken: ctx.token }, buyer.associationId,
+//     { add: ["premium"] })
+//
+// The difference is not the credential. It is whether the DECISION came from
+// your app or from the caller.
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// The permission strings are your own — "bookings.manage", "premium", whatever
+// your code checks. TribeNest stores them against the user and hands them back
+// with their identity (`verifyAppUser`, `useAppAuth`). It never reads them, so
+// there is no catalog to register and nothing to keep in sync with your code.
+
+import type { AppAuthConfig } from "./appAuth";
+
+/**
+ * How this call proves it is allowed to change permissions. Three principals,
+ * and a user's own session token is not one of them.
+ */
+export type AppUserPermissionCredential =
+  /** Inside a job handler: `{ jobToken: ctx.token }`. The app acting as itself. */
+  | { jobToken: string }
+  /** From your own server, outside a job: `{ platformToken: env.TN_APP_TOKEN }`. */
+  | { platformToken: string }
+  /** A person's token, AFTER `verifyAppAdmin` said they're an admin of this app. */
+  | { adminToken: string };
+
+export type AppUserPermissionChange =
+  /** The complete list. What an admin screen sends. */
+  | { set: string[] }
+  /**
+   * A patch. What automation should send: granting `premium` must not silently
+   * drop something another path added between your read and your write.
+   */
+  | { add?: string[]; remove?: string[] };
+
+function authHeaders(credential: AppUserPermissionCredential): Record<string, string> {
+  if ("jobToken" in credential) return { "x-app-sync-token": credential.jobToken };
+  const raw = "platformToken" in credential ? credential.platformToken : credential.adminToken;
+  // Accept a bare token or a whole `Authorization` header value, since the admin
+  // lane usually has the latter straight off the incoming request.
+  return { authorization: /^Bearer\s/i.test(raw) ? raw : `Bearer ${raw}` };
+}
+
+async function permissionsRequest(
+  cfg: AppAuthConfig,
+  credential: AppUserPermissionCredential,
+  associationId: string,
+  init: RequestInit,
+): Promise<string[]> {
+  const res = await fetch(
+    `${cfg.apiUrl}/public/apps/${cfg.appId}/users/${encodeURIComponent(associationId)}/permissions`,
+    { ...init, headers: { "content-type": "application/json", ...authHeaders(credential), ...(init.headers ?? {}) } },
+  );
+  const body = (await res.json().catch(() => ({}))) as { permissions?: string[]; message?: string };
+  if (!res.ok) {
+    throw new Error(body.message ?? `Could not update app-user permissions (${res.status})`);
+  }
+  return body.permissions ?? [];
+}
+
+/**
+ * Set or patch what one of your app's users may do. Returns the resulting list.
+ *
+ * NEVER TAKE THE PERMISSIONS FROM THE REQUEST BODY UNLESS YOU VERIFIED AN ADMIN
+ * FIRST. A user's own token cannot reach this API, so the only way to build
+ * self-escalation is to replay their request on your app's credential — which is
+ * what the obvious version of the route does:
+ *
+ * WRONG (any signed-in user just promoted themselves):
+ *   const { associationId, permissions } = await request.json()
+ *   await setAppUserPermissions(cfg, { jobToken: ctx.token }, associationId, { set: permissions })
+ *
+ * RIGHT (a person with admin rights on the app decided):
+ *   const admin = await verifyAppAdmin(request, cfg)
+ *   if (!admin) return new Response("forbidden", { status: 403 })
+ *   await setAppUserPermissions(cfg, { adminToken: request.headers.get("authorization")! },
+ *     associationId, { set: permissions })
+ *
+ * RIGHT (your own logic decided, no user request involved):
+ *   await setAppUserPermissions(cfg, { jobToken: ctx.token }, buyer.associationId, { add: ["premium"] })
+ *
+ * Prefer `add`/`remove` over `set` in automation — the owner can grant from the
+ * dashboard too, and replacing the whole list would undo them. Idempotent, which
+ * matters because jobs and event deliveries retry.
+ */
+export async function setAppUserPermissions(
+  cfg: AppAuthConfig,
+  credential: AppUserPermissionCredential,
+  associationId: string,
+  change: AppUserPermissionChange,
+): Promise<string[]> {
+  return permissionsRequest(cfg, credential, associationId, {
+    method: "PUT",
+    body: JSON.stringify("set" in change ? { permissions: change.set } : { add: change.add, remove: change.remove }),
+  });
+}
+
+/**
+ * What one of your app's users currently holds.
+ *
+ * For your ADMIN surface — "who has what". To authorize the CURRENT caller, use
+ * `verifyAppUser(request, cfg, { require })` instead: it reads the permissions of
+ * whoever is actually making the request, rather than an id the request supplied.
+ */
+export async function getAppUserPermissions(
+  cfg: AppAuthConfig,
+  credential: AppUserPermissionCredential,
+  associationId: string,
+): Promise<string[]> {
+  return permissionsRequest(cfg, credential, associationId, { method: "GET" });
+}

package/src/server/index.ts

@@ -20,6 +20,11 @@ export * from "./jobs";
 // shared secret. See appAuth.ts.
 export * from "./appAuth";
 
+// Permissions your app gives its OWN users — your vocabulary, stored by the
+// platform and never interpreted by it. Server-only, and read the rule at the
+// top of appUsers.ts before wiring a route to it.
+export * from "./appUsers";
+
 import { emptyContentDocument, type ContentDocument } from "../content/types";
 import type {
   IEvent,
@@ -263,3 +268,15 @@ export function toPlainText(html?: string, max = 200): string | undefined {
   if (!text) return undefined;
   return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
 }
+
+// Platform access + events (docs/app-platform-access-initiative.md). SERVER ONLY —
+// the client carries the app's platform credential.
+export {
+  createPlatformClient,
+  verifyPlatformEvent,
+  PlatformError,
+  type PlatformClient,
+  type PlatformConfig,
+  type PlatformAction,
+  type PlatformEvent,
+} from "./platform";

package/src/server/jobs.ts

@@ -49,6 +49,19 @@ export interface AppJobsStatus {
   queued: Array<{ name: string; runAt: number; attempts: number }>;
   /** One-time jobs that exhausted their retries and were given up on, newest first. */
   deadLetters: Array<{ name: string; attempts: number; failedAt: number; error: string | null }>;
+  /**
+   * Recent runs, newest first — every job, not only the last one. A run showing
+   * `status: "running"` with an old `startedAt` means your app never answered and
+   * may STILL be working; `durationMs` stays null until a run completes.
+   */
+  recentRuns: Array<{
+    name: string;
+    script: string | null;
+    startedAt: number;
+    durationMs: number | null;
+    status: string;
+    error: string | null;
+  }>;
   lastDispatchAt: number | null;
   /** Which job the last delivery attempt was for — all jobs share one error slot. */
   lastDispatchJob: string | null;
@@ -78,9 +91,30 @@ export interface JobSchedule {
 export interface JobContext {
   /** The app-sync token this run was invoked with (forward it to writes). */
   token: string;
+  /**
+   * Milliseconds left before the platform stops waiting for this run.
+   *
+   * CHECK THIS IN ANY LOOP THAT DOES REAL WORK. A run that overruns is cut off
+   * mid-flight: the platform never learns the outcome, so it will NOT be retried
+   * automatically (retrying might redo work you already committed) and it lands in
+   * `deadLetters` for the owner to decide about. Commit what you have and stop
+   * while there is still time — see `partial` below.
+   */
+  remainingMs: () => number;
 }
 
-export type JobHandler = (payload: unknown, env: unknown, ctx: JobContext) => Promise<void> | void;
+/**
+ * What a handler can report back.
+ *
+ * Return nothing for "done". Return `{ partial: true }` when you committed some
+ * work and stopped deliberately — because you were running out of time, or the
+ * upstream paged. That is NOT a failure: it will not be retried, and it shows as
+ * `partial` rather than as an error on the owner's dashboard. Enqueue the next
+ * slice yourself; the cursor lives with you, not with us.
+ */
+export type JobResult = void | { partial: true; message?: string };
+
+export type JobHandler = (payload: unknown, env: unknown, ctx: JobContext) => Promise<JobResult> | JobResult;
 
 export interface AppJobsConfig {
   /** The app id (VITE_APP_ID). */
@@ -121,7 +155,16 @@ export async function reconcileAppJobs(env: AppJobsEnv, cfg: AppJobsConfig, sche
   await stub(env, cfg.appId).reconcile(cfg.script ?? "", cfg.appId, schedules, scheduleHash(schedules));
 }
 
-/** Enqueue a durable one-time job (survives redeploys, retried on failure). */
+/**
+ * Enqueue a durable one-time job (survives redeploys, retried on failure).
+ *
+ * `delayMs` means NOT BEFORE — it is a floor, not a schedule. Queued jobs run one
+ * after another, so once several are due they are dispatched back to back and any
+ * stagger you gave them is gone: fan out ten with `delayMs: i * 4000` and, if each
+ * takes a minute, they run a minute apart, not four seconds. Do NOT use it to pace
+ * against a third party's rate limit — handle that inside the handler, or chain the
+ * work by enqueueing the next slice when one finishes.
+ */
 export async function enqueueAppJob(
   env: AppJobsEnv,
   cfg: AppJobsConfig,
@@ -133,8 +176,9 @@ export async function enqueueAppJob(
 }
 
 /**
- * Inspect the app's job runtime — the ONLY window into why a job did or didn't
- * run (jobs are fire-and-forget with no logs). Call it from a server route
+ * Why a job did or didn't run — read `recentRuns` (every run, with duration + outcome) and `deadLetters` (jobs that gave up), NOT `queueDepth`, which reads 0 whether a job succeeded or was never enqueued.
+ *
+ * The only window into a fire-and-forget runtime with no logs. Call it from a server route
  * (server-only, needs the JOBS binding) and gate it behind `verifyAppAdmin`:
  *
  *   export const Route = createFileRoute("/api/tn-jobs/status")({
@@ -177,13 +221,27 @@ export async function handleAppJobRun(
   }
   if (!valid) return new Response("unauthorized", { status: 401 });
 
-  const body = (await request.json().catch(() => ({}))) as { job?: string; payload?: unknown };
+  const body = (await request.json().catch(() => ({}))) as {
+    job?: string;
+    payload?: unknown;
+    deadlineAt?: number;
+  };
   const handler = body.job ? jobs[body.job] : undefined;
   if (!handler) return new Response("unknown job", { status: 404 });
   try {
     // Pass the verified token so the handler can write app-owned data back
-    // (writeAppCollection) without re-minting anything.
-    await handler(body.payload ?? null, env, { token });
+    // (writeAppCollection) without re-minting anything, plus how long it has —
+    // so a long job can commit and stop instead of being cut off mid-write.
+    const deadlineAt = typeof body.deadlineAt === "number" ? body.deadlineAt : undefined;
+    const result = await handler(body.payload ?? null, env, {
+      token,
+      remainingMs: () => (deadlineAt ? Math.max(0, deadlineAt - Date.now()) : Number.POSITIVE_INFINITY),
+    });
+    if (result && typeof result === "object" && result.partial) {
+      // Reported to the platform as its own outcome so a correctly-behaving
+      // resumable job doesn't read as an error.
+      return new Response(result.message ?? "partial", { headers: { "x-tn-job-status": "partial" } });
+    }
     return new Response("ok");
   } catch (err) {
     // Non-2xx → the DO retries (one-time) / re-fires next interval (recurring).
@@ -192,46 +250,87 @@ export async function handleAppJobRun(
 }
 
 /**
- * Persist APP-OWNED rows into one of the app's collections from a job handler —
- * the sanctioned server-side write path (do NOT invent an endpoint). Authenticated
- * by the run's token (from `JobContext`).
+ * Write app-owned rows to a collection — pass `{ upsertKey: 'yourIdField' }` so re-runs UPDATE instead of duplicating (without it every call inserts; `replace: true` archives everything first and is only for a complete dataset).
+ *
+ * The sanctioned server-side write path — do NOT invent an endpoint.
+ *
+ * PICK ONE OF THREE MODES:
+ *
+ * 1. `upsertKey` — INCREMENTAL, and what you almost always want. Rows are matched
+ *    on the field(s) you name and updated in place; anything new is inserted.
+ *    Nothing else is touched, so you can sync just what changed:
  *
- * IMPORTANT — this ALWAYS INSERTS (there is no upsert-by-key). A stable title does
- * NOT make re-runs idempotent (slugs auto-dedupe to -2/-3…), so re-running WILL
- * duplicate rows. For idempotency use `replace: true` (archives every existing
- * app-owned row in the collection, then inserts) AND re-pull the FULL dataset each
- * run. NEVER combine `replace: true` with an incremental window (e.g.
- * updated_at_min / last-7-days) — it archives the rows outside the window too and
- * you lose history. (True incremental upsert-by-key is not supported yet.)
+ *      await writeAppCollection(ctx, cfg, "orders", changed, { upsertKey: "orderId" })
  *
- * Handlers receive `(payload, env, ctx)` — pass `ctx` here; `cfg` is your own
- * config built from `import.meta.env`.
+ *    Use several fields when one isn't unique: `{ upsertKey: ["shop", "orderId"] }`.
+ *    A row missing any key field is inserted rather than matched, so an incomplete
+ *    record can never collide with another.
  *
- *     jobs = {
- *       "sync-shopify": async (_p, env, ctx) => {
- *         const orders = await fetchShopify(env);
- *         await writeAppCollection(ctx, cfg, "shopify-orders",
- *           orders.map(o => ({ data: { orderId: o.id, total: o.total, utmSource: o.utm } })),
- *           { replace: true });
- *       },
- *     };
+ * 2. `replace: true` — archives EVERY existing row, then inserts what you sent.
+ *    Only correct when the payload is the COMPLETE dataset. Combining it with a
+ *    time window ("last 7 days") archives everything outside that window and
+ *    destroys your history. It also grows with your data: a full replace of a
+ *    large collection is a big write and will eventually time out. Prefer
+ *    `upsertKey`.
+ *
+ * 3. Neither — plain insert. Every call adds rows, so re-running duplicates them.
+ *    Fine for append-only logs, wrong for a sync.
+ *
+ * A stable title does NOT make re-runs idempotent (slugs auto-dedupe to -2/-3…);
+ * only `upsertKey` does.
+ *
+ * Write at most 1000 rows per call — page larger syncs.
  */
 export async function writeAppCollection(
   ctx: JobContext,
   cfg: AppJobsConfig,
   slug: string,
   entries: Array<{ data: Record<string, unknown>; status?: "draft" | "published" }>,
-  opts?: { replace?: boolean },
-): Promise<{ created: number }> {
+  opts?: {
+    /** Archive every existing row first. Only for a COMPLETE dataset — see above. */
+    replace?: boolean;
+    /**
+     * Field(s) identifying a row, so existing rows are updated instead of
+     * duplicated. Mark the key field FILTERABLE on the collection — matching is
+     * then an indexed lookup; otherwise it still works but scans.
+     */
+    upsertKey?: string | string[];
+  },
+): Promise<{ created: number; updated: number; archived: number }> {
   const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/collections/${encodeURIComponent(slug)}/entries`, {
     method: "POST",
     headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
-    body: JSON.stringify({ entries, replace: opts?.replace === true }),
+    body: JSON.stringify({ entries, replace: opts?.replace === true, upsertKey: opts?.upsertKey }),
   });
   if (!res.ok) throw new Error(`writeAppCollection ${slug} failed: ${res.status} ${await res.text().catch(() => "")}`);
   return res.json();
 }
 
+/**
+ * Delete app-owned rows by key — use this instead of `replace: true` when you only need to drop some records (rows are archived, not destroyed).
+ *
+ *   await deleteAppCollection(ctx, cfg, "orders", "orderId", ["1001", "1002"])
+ *
+ * Rows are archived, not destroyed, so a mistaken sync can be recovered. Use this
+ * instead of `replace: true` when you only need to drop a few records.
+ */
+export async function deleteAppCollection(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  slug: string,
+  upsertKey: string | string[],
+  keys: string[],
+): Promise<{ deleted: number }> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/collections/${encodeURIComponent(slug)}/entries`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: JSON.stringify({ upsertKey, deleteKeys: keys }),
+  });
+  if (!res.ok) throw new Error(`deleteAppCollection ${slug} failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+
+
 /**
  * Read an app's OWN collection back from a JOB handler (the read counterpart to
  * writeAppCollection), authenticated by the run's app-sync token. Reads at `app`