@tribe-nest/forge 1.15.0 → 1.18.0

package/package.json

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

@@ -0,0 +1,107 @@
+// Authenticate the CALLER of one of your app's OWN server routes (TanStack
+// server handlers, e.g. a "run this job now" or "save settings" endpoint).
+// SERVER-ONLY.
+//
+// Why this exists: `useAppAuth` / `useAppAdminGuard` are React hooks — they run
+// in the browser and CANNOT gate a server route. Without a server-side check, a
+// privileged route is either wide open or bolted shut behind a shared secret.
+// Neither is right. Instead: the client already holds the caller's token (the
+// app-user token, or the admin's TribeNest account token); forward it to your
+// server route in the `Authorization` header, and verify it HERE. The app Worker
+// is only a CLIENT — TribeNest is the sole authority on identity + access, so
+// these helpers forward the token to the platform and trust its answer.
+//
+// NEVER gate a privileged app route with a hardcoded/shared secret. Verify the
+// actual person making the request:
+//   - APP ADMIN  → `verifyAppAdmin`: the owner or a team member with a Work grant
+//     on the app (operator actions: trigger a sync, edit config, rebuild data).
+//   - APP USER   → `verifyAppUser`: an app-scoped account (`useAppAuth`); scope
+//     end-user actions to that user's own data.
+
+export interface AppAuthConfig {
+  /** The app id (VITE_APP_ID). `jobsConfig` from src/lib/jobs.ts satisfies this. */
+  appId: string;
+  /** The TribeNest public API base (VITE_API_URL). */
+  apiUrl: string;
+}
+
+export interface AppAdminIdentity {
+  isAdmin: true;
+  /** Highest permission the account holds on the app (view/comment/edit/manage). */
+  permission: string | null;
+  appName: string | null;
+}
+
+export interface AppUserIdentity {
+  id: string;
+  associationId: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+  status: string;
+  appId: string | null;
+}
+
+// The bearer credential the client forwarded, or null. We pass it through as-is
+// (the platform verifies it) — never parse or trust its contents here.
+function bearer(request: Request): string | null {
+  const h = request.headers.get("authorization");
+  return h && /^Bearer\s+\S/i.test(h) ? h : null;
+}
+
+/**
+ * Verify the request comes from an APP ADMIN — the owner or a team member with a
+ * Work grant on the app. Forwards the caller's TribeNest account token to
+ * `GET /public/apps/:appId/admin-access`. Returns the admin identity, or `null`
+ * when there's no token / it's invalid / the account isn't an admin.
+ *
+ *     export const Route = createFileRoute("/api/tn-jobs/trigger")({
+ *       server: { handlers: { POST: async ({ request }) => {
+ *         const admin = await verifyAppAdmin(request, jobsConfig);
+ *         if (!admin) return new Response("forbidden", { status: 403 });
+ *         const { job, payload } = await request.json();
+ *         const { env } = await import("cloudflare:workers");
+ *         await enqueueAppJob(env, jobsConfig, job, payload);
+ *         return Response.json({ ok: true });
+ *       } } },
+ *     });
+ *
+ * The dashboard/admin UI calls this route with the admin's token in the
+ * `Authorization` header (the same token `usePublicAuth` holds) — so the button
+ * is authenticated as the person clicking it, no shared secret.
+ */
+export async function verifyAppAdmin(request: Request, cfg: AppAuthConfig): Promise<AppAdminIdentity | null> {
+  const auth = bearer(request);
+  if (!auth) return null;
+  try {
+    const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/admin-access`, {
+      headers: { authorization: auth },
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { isAdmin?: boolean; permission?: string | null; appName?: string | null };
+    return data.isAdmin ? { isAdmin: true, permission: data.permission ?? null, appName: data.appName ?? null } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verify the request comes from a logged-in APP USER (`useAppAuth` account).
+ * Forwards the app-user token to `GET /public/app-sessions/me`. Returns the
+ * user, or `null` when unauthenticated. Use to scope an end-user server action
+ * to that user (e.g. read/write only their own rows) — the returned
+ * `associationId` is the owner id the platform enforces on `mine`-scoped data.
+ */
+export async function verifyAppUser(request: Request, cfg: AppAuthConfig): Promise<AppUserIdentity | null> {
+  const auth = bearer(request);
+  if (!auth) return null;
+  try {
+    const res = await fetch(`${cfg.apiUrl}/public/app-sessions/me`, {
+      headers: { authorization: auth },
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as AppUserIdentity;
+  } catch {
+    return null;
+  }
+}

package/src/server/index.ts

@@ -15,6 +15,11 @@
 // App background-job runtime (no-config wrapper over the JobsDO). Server-only.
 export * from "./jobs";
 
+// Authenticate the caller of an app's own server routes (admin / app-user).
+// Server-only — the sanctioned alternative to gating a privileged route with a
+// shared secret. See appAuth.ts.
+export * from "./appAuth";
+
 import { emptyContentDocument, type ContentDocument } from "../content/types";
 import type {
   IEvent,

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();
+}