@tribe-nest/forge 1.14.0 → 1.15.0

package/package.json

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

package/src/server/jobs.ts

@@ -21,8 +21,17 @@ 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;
 }
 
 /** Context passed to a job handler — carries the platform token so the handler
@@ -48,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]),
+  );
 }
 
 /**
@@ -73,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(
@@ -115,8 +128,18 @@ 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`). `replace: true` = full refresh (archive
- * the existing app-owned rows first), so a re-sync doesn't accumulate duplicates.
+ * 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) => {