@tribe-nest/forge 1.13.0 → 1.14.0

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "1.13.0",
-  "publishConfig": { "access": "public" },
+  "version": "1.14.0",
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "Forge — the headless React SDK for building custom TribeNest creator sites (the Hydrogen of TribeNest). Exposes the backend (memberships, commerce, gated content, ticketing, courses, booking, auth) as data + behavior primitives.",
   "exports": {
     ".": "./src/index.ts",

package/src/server/jobs.ts

@@ -25,7 +25,14 @@ export interface JobSchedule {
   intervalMs: number;
 }
 
-export type JobHandler = (payload: unknown, env: unknown) => Promise<void> | void;
+/** Context passed to a job handler — carries the platform token so the handler
+ *  can write app-owned data back (writeAppCollection). */
+export interface JobContext {
+  /** The app-sync token this run was invoked with (forward it to writes). */
+  token: string;
+}
+
+export type JobHandler = (payload: unknown, env: unknown, ctx: JobContext) => Promise<void> | void;
 
 export interface AppJobsConfig {
   /** The app id (VITE_APP_ID). */
@@ -95,10 +102,43 @@ export async function handleAppJobRun(
   const handler = body.job ? jobs[body.job] : undefined;
   if (!handler) return new Response("unknown job", { status: 404 });
   try {
-    await handler(body.payload ?? null, env);
+    // 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 });
     return new Response("ok");
   } catch (err) {
     // Non-2xx → the DO retries (one-time) / re-fires next interval (recurring).
     return new Response(`job failed: ${(err as Error).message}`, { status: 500 });
   }
 }
+
+/**
+ * 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`). `replace: true` = full refresh (archive
+ * the existing app-owned rows first), so a re-sync doesn't accumulate duplicates.
+ *
+ *     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 });
+ *       },
+ *     };
+ */
+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 }> {
+  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 }),
+  });
+  if (!res.ok) throw new Error(`writeAppCollection ${slug} failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}