@tribe-nest/forge 1.13.0 → 1.15.0

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "1.13.0",
-  "publishConfig": { "access": "public" },
+  "version": "1.15.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

@@ -21,11 +21,27 @@ interface AppJobsStub {
 export interface JobSchedule {
   /** Stable job name — also the key in your job map + the `scheduleId` in the token. */
   name: string;
-  /** How often to run, in milliseconds (e.g. 60_000 = every minute). */
-  intervalMs: number;
+  /**
+   * Fixed interval in milliseconds (e.g. 60_000 = every minute). Provide this OR
+   * `cron`, not both. Best for "every N minutes/hours"; the first run lands one
+   * interval after the deploy.
+   */
+  intervalMs?: number;
+   // A 5-field UTC cron expression: minute hour day-of-month month day-of-week.
+   // e.g. "0 3 * * *" = daily at 03:00 UTC; "0 0,6,12,18 * * *" = every 6 hours;
+   // "0 9 * * 1-5" = 09:00 UTC on weekdays. Provide this OR `intervalMs`. Use
+   // cron when a run must land at a specific wall-clock time; evaluation is UTC.
+  cron?: string;
 }
 
-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). */
@@ -41,7 +57,11 @@ const stub = (env: AppJobsEnv, appId: string): AppJobsStub => env.JOBS.get(env.J
 // A stable fingerprint of the desired schedule set, so the DO skips reconcile
 // when nothing changed (sorted by name → order-independent).
 function scheduleHash(schedules: JobSchedule[]): string {
-  return JSON.stringify([...schedules].sort((a, b) => a.name.localeCompare(b.name)).map((s) => [s.name, s.intervalMs]));
+  return JSON.stringify(
+    [...schedules]
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map((s) => [s.name, s.intervalMs ?? null, s.cron ?? null]),
+  );
 }
 
 /**
@@ -66,9 +86,9 @@ export async function enqueueAppJob(
 }
 
 /**
- * Handle the DO's alarm callback (`POST /_jobs/run`). Verifies the platform
+ * Handle the DO's alarm callback (`POST /api/tn-jobs/run`). Verifies the platform
  * token, looks up the named handler in your job map, and runs it with the app's
- * `env` (so `env.SHOPIFY_TOKEN` etc. are available). Wire your `/_jobs/run` route
+ * `env` (so `env.SHOPIFY_TOKEN` etc. are available). Wire your `/api/tn-jobs/run` route
  * to this.
  */
 export async function handleAppJobRun(
@@ -95,10 +115,53 @@ 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`).
+ *
+ * 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.)
+ *
+ * Handlers receive `(payload, env, ctx)` — pass `ctx` here; `cfg` is your own
+ * config built from `import.meta.env`.
+ *
+ *     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();
+}