@tribe-nest/forge 1.20.1 → 1.20.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "1.20.1",
+  "version": "1.20.2",
   "publishConfig": {
     "access": "public"
   },

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;
@@ -133,8 +146,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")({
@@ -192,46 +206,83 @@ 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. */
+    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`