@tribe-nest/forge 1.16.0 → 1.19.0

package/package.json

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

package/src/data/queries/useCollections.ts

@@ -10,6 +10,7 @@ import type {
 import { useForge } from "../../provider/ForgeProvider";
 import { useQuery, useMutation } from "@tanstack/react-query";
 import { collectionParamsToQuery, collectionParamsKey, splitCollectionQuery, collectionQueryKey } from "../collectionParams";
+import { APP_ACCESS_TOKEN_KEY } from "../../contexts/AppAuthContext";
 
 // Generic data hooks for CMS collections. Collection-agnostic — a lawyers
 // directory and a recipe index use the same three hooks. The bespoke rendering
@@ -119,6 +120,63 @@ export function useCollectionAggregate(
   });
 }
 
+// Prefer the app-user token (useAppAuth) when the viewer is an app user;
+// otherwise fall back to the Forge client's own token (an app-admin's TribeNest
+// session). Both are accepted by the app read endpoint. Returns a per-request
+// Axios config that overrides Authorization, or undefined to use the default.
+function appAuthConfig(): { headers: Record<string, string> } | undefined {
+  const t = typeof localStorage !== "undefined" ? localStorage.getItem(APP_ACCESS_TOKEN_KEY) : null;
+  return t ? { headers: { Authorization: `Bearer ${t}` } } : undefined;
+}
+
+/**
+ * Read an APP's OWN collection at `app` scope from the browser (a dashboard) —
+ * ALL rows, including `private`/unpublished ones. Authenticated as the logged-in
+ * app user (useAppAuth) or app admin. Use THIS (not useCollectionQuery) for
+ * app-owned/business data so the collection can stay `visibility: 'private'` and
+ * never be world-readable via the profile's public API.
+ */
+export function useAppCollectionQuery(
+  slug?: string,
+  query?: CollectionQuery,
+  options?: { enabled?: boolean; initialData?: CollectionSearchResult },
+) {
+  const { client, appId } = useForge();
+  const { query: body } = splitCollectionQuery(query);
+
+  return useQuery<CollectionSearchResult>({
+    queryKey: ["app-collection-query", appId, slug, collectionQueryKey(query)],
+    queryFn: async () => {
+      const res = await client.post(`/public/apps/${appId}/collections/${slug}/query`, { query: body }, appAuthConfig());
+      return res.data;
+    },
+    enabled: (options?.enabled ?? true) && !!appId && !!client && !!slug,
+    initialData: options?.initialData,
+  });
+}
+
+/** Aggregate an APP's OWN collection from the browser (see useAppCollectionQuery). */
+export function useAppCollectionAggregate(
+  slug?: string,
+  aggregate?: CollectionAggregate,
+  opts?: { where?: CollectionQuery["where"]; search?: string; enabled?: boolean },
+) {
+  const { client, appId } = useForge();
+
+  return useQuery<CollectionAggregateBucket[]>({
+    queryKey: ["app-collection-aggregate", appId, slug, JSON.stringify({ aggregate, ...opts })],
+    queryFn: async () => {
+      const res = await client.post(
+        `/public/apps/${appId}/collections/${slug}/aggregate`,
+        { where: opts?.where, search: opts?.search, aggregate },
+        appAuthConfig(),
+      );
+      return res.data.data;
+    },
+    enabled: (opts?.enabled ?? true) && !!appId && !!client && !!slug && !!aggregate,
+  });
+}
+
 export type SubmitCollectionEntryInput = {
   data: Record<string, unknown>;
   /** For anonymous submissions, when the collection requires them. */

package/src/server/jobs.ts

@@ -14,8 +14,49 @@ export interface AppJobsEnv {
 }
 
 interface AppJobsStub {
-  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>;
+  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>;
+  status: () => Promise<AppJobsStatus>;
+}
+
+/**
+ * A snapshot of the app's job runtime — what's scheduled, how deep the queue is,
+ * 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);
+ *  - `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).
+ */
+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;
+  lastDispatchAt: number | null;
+  lastDispatchScript: string | null;
+  lastDispatchStatus: string | null;
+  lastError: string | null;
 }
 
 export interface JobSchedule {
@@ -50,6 +91,14 @@ export interface AppJobsConfig {
   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.
+   */
+  host: string;
 }
 
 const stub = (env: AppJobsEnv, appId: string): AppJobsStub => env.JOBS.get(env.JOBS.idFromName(appId));
@@ -71,7 +120,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), cfg.host);
 }
 
 /** Enqueue a durable one-time job (survives redeploys, retried on failure). */
@@ -82,7 +131,26 @@ 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, cfg.host);
+}
+
+/**
+ * Inspect the app's job runtime — the ONLY window into why a job did or didn't
+ * run (jobs are fire-and-forget with no logs). Call it from a server route
+ * (server-only, needs the JOBS binding) and gate it behind `verifyAppAdmin`:
+ *
+ *   export const Route = createFileRoute("/api/tn-jobs/status")({
+ *     server: { handlers: { GET: async ({ request }) => {
+ *       if (!(await verifyAppAdmin(request, jobsConfig))) return new Response("forbidden", { status: 403 });
+ *       const { env } = await import("cloudflare:workers");
+ *       return Response.json(await appJobsStatus(env, jobsConfig));
+ *     } } },
+ *   });
+ *
+ * See {@link AppJobsStatus} for how to read the result.
+ */
+export async function appJobsStatus(env: AppJobsEnv, cfg: AppJobsConfig): Promise<AppJobsStatus> {
+  return stub(env, cfg.appId).status();
 }
 
 /**
@@ -165,3 +233,43 @@ export async function writeAppCollection(
   if (!res.ok) throw new Error(`writeAppCollection ${slug} failed: ${res.status} ${await res.text().catch(() => "")}`);
   return res.json();
 }
+
+/**
+ * Read an app's OWN collection back from a JOB handler (the read counterpart to
+ * writeAppCollection), authenticated by the run's app-sync token. Reads at `app`
+ * scope — ALL rows, including `private`/unpublished ones — so the collection can
+ * stay `visibility: 'private'` (never world-readable) yet the app still reads it.
+ * `query` is the query-engine DSL ({ where?, sort?, select?, page?, limit?, … }).
+ * For reading app-owned data in the browser (a dashboard) use the client hook
+ * `useAppCollectionQuery` instead — this one needs the job token.
+ */
+export async function queryAppCollection(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  slug: string,
+  query?: Record<string, unknown>,
+): Promise<{ data: unknown[]; total: number; [k: string]: unknown }> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/collections/${encodeURIComponent(slug)}/query`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: JSON.stringify({ query: query ?? {} }),
+  });
+  if (!res.ok) throw new Error(`queryAppCollection ${slug} failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+
+/** Aggregate over an app's OWN collection from a job handler (see queryAppCollection). */
+export async function aggregateAppCollection(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  slug: string,
+  input: { aggregate: unknown; where?: unknown; search?: string },
+): Promise<unknown> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/collections/${encodeURIComponent(slug)}/aggregate`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: JSON.stringify(input),
+  });
+  if (!res.ok) throw new Error(`aggregateAppCollection ${slug} failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}