@tribe-nest/forge 1.19.0 → 1.20.0

package/package.json

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

package/src/server/jobs.ts

@@ -14,21 +14,8 @@ export interface AppJobsEnv {
 }
 
 interface AppJobsStub {
-  reconcile: (
-    script: string,
-    appId: string,
-    desired: JobSchedule[],
-    hash: string,
-    host: string,
-  ) => Promise<{ changed: boolean }>;
-  enqueue: (
-    script: string,
-    appId: string,
-    name: string,
-    payload: unknown,
-    delayMs: number,
-    host: string,
-  ) => Promise<void>;
+  reconcile: (script: string, appId: string, desired: JobSchedule[], hash: string) => Promise<{ changed: boolean }>;
+  enqueue: (script: string, appId: string, name: string, payload: unknown, delayMs: number) => Promise<void>;
   status: () => Promise<AppJobsStatus>;
 }
 
@@ -37,23 +24,34 @@ interface AppJobsStub {
  * and what happened on the LAST delivery attempt. Because jobs fail silently (no
  * logs / dead-letter), this is how you SEE why one didn't run:
  *  - `lastDispatchAt` null while `alarmAt` is in the past → the alarm isn't firing;
- *  - `appHost` null → this app predates host registration; redeploy it;
- *  - `lastError` starting "dispatch threw:" → the callback never reached your app
- *    (host unroutable / your Worker is down);
+ *  - `lastError` starting "runner unreachable:" → a platform-side fault, not yours;
+ *  - `lastDispatchStatus` "404" + "no dispatch target" → the platform has no
+ *    record of where to send your runs; republish the app;
+ *  - `lastDispatchStatus` "502" → your Worker isn't deployed;
  *  - `lastDispatchStatus` "401" → your app was reached but rejected the token
  *    (the dispatch-worker's APP_SYNC_SECRET ≠ the backend JWT_SECRET);
- *  - `lastDispatchStatus` "402" → the site is suspended for billing;
- *  - `lastDispatchStatus` "404" → no /api/tn-jobs/run route (or an unknown job name).
+ *  - `lastDispatchStatus` "404" + "unknown job" → the run landed but no handler
+ *    in your job map has that name.
+ *
+ * For "my one-time job never ran", read `deadLetters` first. `queueDepth` on its
+ * own tells you almost nothing: `enqueueAppJob(..., delayMs: 0)` causes the run
+ * to be dispatched and the row deleted within seconds, so depth reads 0 whether
+ * the job succeeded or was never enqueued at all. A job that keeps failing
+ * retries for ~15 minutes and then appears in `deadLetters` with its error.
  */
 export interface AppJobsStatus {
   appId: string | null;
-  /** The public host job runs are posted to. Null on apps deployed before this existed. */
-  appHost: string | null;
   now: number;
   alarmAt: number | null;
   schedules: Array<{ name: string; intervalMs: number | null; cron: string | null; nextRun: number }>;
   queueDepth: number;
+  /** Names currently queued with their next attempt time. */
+  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 }>;
   lastDispatchAt: number | null;
+  /** Which job the last delivery attempt was for — all jobs share one error slot. */
+  lastDispatchJob: string | null;
   lastDispatchScript: string | null;
   lastDispatchStatus: string | null;
   lastError: string | null;
@@ -87,18 +85,18 @@ export type JobHandler = (payload: unknown, env: unknown, ctx: JobContext) => Pr
 export interface AppJobsConfig {
   /** The app id (VITE_APP_ID). */
   appId: string;
-  /** This Worker's script name in the dispatch namespace (VITE_APP_SCRIPT). */
-  script: string;
   /** The TribeNest public API base (VITE_API_URL) — used to verify the callback token. */
   apiUrl: string;
   /**
-   * This app's public host, no scheme (VITE_APP_HOST) — e.g. "acme.tribenest.co".
-   * The job runtime posts each run to `https://<host>/api/tn-jobs/run`; it cannot
-   * reach the app any other way, so an app that never registers a host will not
-   * run jobs (its status reports "no app host recorded"). Injected at deploy —
-   * do not hand-set it.
+   * @deprecated No longer needed — leave it unset in new apps.
+   *
+   * This Worker's script name in the dispatch namespace (VITE_APP_SCRIPT). Your
+   * app's address is a PLATFORM fact: it is recorded at publish and resolved by
+   * the job runtime from your `appId`, so an app no longer reports where it
+   * lives. Still accepted (and forwarded as a fallback hint) so apps published
+   * before that change keep dispatching without a rebuild.
    */
-  host: string;
+  script?: string;
 }
 
 const stub = (env: AppJobsEnv, appId: string): AppJobsStub => env.JOBS.get(env.JOBS.idFromName(appId));
@@ -120,7 +118,7 @@ function scheduleHash(schedules: JobSchedule[]): string {
  * one, a removed one is pruned.
  */
 export async function reconcileAppJobs(env: AppJobsEnv, cfg: AppJobsConfig, schedules: JobSchedule[]): Promise<void> {
-  await stub(env, cfg.appId).reconcile(cfg.script, cfg.appId, schedules, scheduleHash(schedules), cfg.host);
+  await stub(env, cfg.appId).reconcile(cfg.script ?? "", cfg.appId, schedules, scheduleHash(schedules));
 }
 
 /** Enqueue a durable one-time job (survives redeploys, retried on failure). */
@@ -131,7 +129,7 @@ export async function enqueueAppJob(
   payload?: unknown,
   delayMs = 0,
 ): Promise<void> {
-  await stub(env, cfg.appId).enqueue(cfg.script, cfg.appId, name, payload ?? null, delayMs, cfg.host);
+  await stub(env, cfg.appId).enqueue(cfg.script ?? "", cfg.appId, name, payload ?? null, delayMs);
 }
 
 /**