@tribe-nest/forge 1.18.0 → 1.20.0

package/package.json

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

package/src/server/jobs.ts

@@ -24,9 +24,20 @@ 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;
- *  - `lastError` starting "dispatch threw:" → the callback never reached your app;
+ *  - `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).
+ *    (the dispatch-worker's APP_SYNC_SECRET ≠ the backend JWT_SECRET);
+ *  - `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;
@@ -34,7 +45,13 @@ export interface AppJobsStatus {
   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;
@@ -68,10 +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;
+  /**
+   * @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.
+   */
+  script?: string;
 }
 
 const stub = (env: AppJobsEnv, appId: string): AppJobsStub => env.JOBS.get(env.JOBS.idFromName(appId));
@@ -93,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));
+  await stub(env, cfg.appId).reconcile(cfg.script ?? "", cfg.appId, schedules, scheduleHash(schedules));
 }
 
 /** Enqueue a durable one-time job (survives redeploys, retried on failure). */
@@ -104,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);
+  await stub(env, cfg.appId).enqueue(cfg.script ?? "", cfg.appId, name, payload ?? null, delayMs);
 }
 
 /**