@tribe-nest/forge 1.16.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "1.16.0",
+  "version": "1.18.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

@@ -16,6 +16,28 @@ 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>;
+  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;
+ *  - `lastError` starting "dispatch threw:" → the callback never reached your app;
+ *  - `lastDispatchStatus` "401" → your app was reached but rejected the token
+ *    (the dispatch-worker's APP_SYNC_SECRET ≠ the backend JWT_SECRET).
+ */
+export interface AppJobsStatus {
+  appId: 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 {
@@ -85,6 +107,25 @@ export async function enqueueAppJob(
   await stub(env, cfg.appId).enqueue(cfg.script, cfg.appId, name, payload ?? null, delayMs);
 }
 
+/**
+ * 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();
+}
+
 /**
  * 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
@@ -165,3 +206,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();
+}