@tribe-nest/forge 3.2.0 → 3.9.0

package/src/data/queries/useWalletPass.ts

@@ -0,0 +1,236 @@
+import { useMemo } from "react";
+import { useMutation, useQueries, useQuery } from "@tanstack/react-query";
+import { useForge } from "../../provider/ForgeProvider";
+
+/**
+ * Events 2.3 — "Add to Apple Wallet" / "Save to Google Wallet" for a ticket the
+ * signed-in buyer already owns.
+ *
+ * Lives in Forge rather than in either app because both rendering surfaces —
+ * the client PWA and code websites — need exactly this, and a second copy is
+ * how the two drift (the same reason `useMyTickets` and `useEventWaitlist` live
+ * here).
+ *
+ * ## The endpoints
+ *
+ * ```
+ * GET /public/events/passes/:passId/wallet?profileId=…        status → WalletPassStatus (200)
+ * GET /public/events/passes/:passId/wallet/apple?profileId=…  the .pkpass bytes (200)
+ * ```
+ *
+ * `:passId` is `event_passes.id` — the string `TN-` followed by digits, NOT a
+ * UUID and NOT an order id. The API validates that shape and answers 404 for
+ * anything else, so callers must pass a real pass id rather than the order id
+ * `useMyTickets` returns.
+ *
+ * Both endpoints resolve the buyer from the SESSION and match it against the
+ * order's email; nothing about identity is accepted as input. A pass that
+ * exists but belongs to someone else answers **404, not 403** — deliberately, so
+ * the endpoint cannot be used as an oracle over other people's purchases. Which
+ * means: for this UI, "404" and "no such pass" are the same answer and neither
+ * is worth surfacing.
+ *
+ * ## THE RULE THIS FILE EXISTS TO ENFORCE: invisible when unavailable
+ *
+ * **No wallet signing credentials exist in production today.** The Apple Pass
+ * Type ID certificate and the Google Issuer ID are still being obtained, so the
+ * status endpoint currently answers, for every ticket:
+ *
+ * ```json
+ * { "passId": "TN-123", "available": false, "reason": "not_configured",
+ *   "apple": { "available": false, "downloadUrl": null },
+ *   "google": { "available": false, "saveUrl": null } }
+ * ```
+ *
+ * That is a 200. It is a successful answer meaning "this feature is off", not an
+ * error — and a buyer who will never get a wallet pass must not be able to tell
+ * the feature exists. So `hasWalletPass()` is the single predicate every caller
+ * gates on, and it is false for:
+ *
+ *   - `available: false` for ANY reason (`not_configured`, `rotating_qr` — a
+ *     pass on signed rotating QR cannot carry a static wallet barcode — or
+ *     `order_not_active` for a cancelled/refunded order);
+ *   - a query that failed, 401'd, 404'd, or has not answered yet;
+ *   - both providers coming back unusable even on an `available: true` row.
+ *
+ * There is no loading state, no disabled button, no "coming soon" and no error
+ * toast anywhere in this feature. Absence is the entire design.
+ *
+ * ## Why the `.pkpass` is fetched, not linked
+ *
+ * The download endpoint is authenticated by the member bearer token, which lives
+ * in memory/localStorage and is attached by the Forge Axios client — an `<a
+ * href>` straight at the API would send no `Authorization` header and 401. So
+ * the bytes are fetched through the client and handed to the browser as an
+ * object URL carrying the `application/vnd.apple.pkpass` type, which is what
+ * makes iOS open Wallet instead of saving a nameless file.
+ */
+
+/** The MIME type iOS keys off. A wrong one downloads as a zip and never opens. */
+export const PKPASS_MIME_TYPE = "application/vnd.apple.pkpass";
+
+/**
+ * Why a pass cannot go into a wallet right now. Mirrors the API's
+ * `WalletPassUnavailableReason`. Present for diagnostics and logging — it is
+ * deliberately never rendered, since every value means "show nothing".
+ */
+export type WalletPassUnavailableReason = "not_configured" | "rotating_qr" | "order_not_active";
+
+export type WalletPassStatus = {
+  passId: string;
+  /** The only field the UI branches on. */
+  available: boolean;
+  /** Null when `available` is true. */
+  reason: WalletPassUnavailableReason | null;
+  apple: {
+    available: boolean;
+    /** API-relative path INCLUDING `?profileId=…`; pass it to the Forge client as-is. */
+    downloadUrl: string | null;
+  };
+  google: {
+    available: boolean;
+    /** An absolute `https://pay.google.com/gp/v/save/<jwt>` URL. */
+    saveUrl: string | null;
+  };
+};
+
+/** `event_passes.id`. Cheap client-side mirror of the API's own guard, so an order id never becomes a request. */
+export const isEventPassId = (value: unknown): value is string =>
+  typeof value === "string" && /^TN-\d+$/.test(value);
+
+/**
+ * Is there anything to draw?
+ *
+ * The ONE predicate the whole feature gates on. Written as a total function over
+ * `unknown`-ish input so an undefined/loading/errored query is false by
+ * construction rather than by the caller remembering to check.
+ */
+export const hasWalletPass = (status?: WalletPassStatus | null): boolean =>
+  !!status?.available && (status.apple.available || !!status.google.saveUrl);
+
+const walletPassKey = (passId?: string, accountId?: string, profileId?: string) =>
+  ["wallet-pass", passId, accountId, profileId] as const;
+
+/**
+ * What this buyer can add to a wallet for ONE pass.
+ *
+ * `accountId` gates the query on being signed in and keys the cache; it is never
+ * sent, and sending it would not help — the API takes the buyer's identity from
+ * the session and ignores any supplied by the caller.
+ *
+ * `retry: false` because every failure here is an ANSWER, not a fault: 401 means
+ * anonymous, 404 means "not yours / no such pass", and both mean draw nothing.
+ * Retrying would only delay that conclusion and multiply the requests a page of
+ * tickets makes.
+ */
+export function useWalletPass(passId?: string, accountId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<WalletPassStatus>({
+    queryKey: walletPassKey(passId, accountId, profileId),
+    queryFn: async () => {
+      const res = await client.get(`/public/events/passes/${passId}/wallet`, { params: { profileId } });
+      return res.data;
+    },
+    enabled: isEventPassId(passId) && !!accountId && !!profileId && !!client,
+    retry: false,
+    // A save JWT carries no expiry and a `.pkpass` is regenerated per request,
+    // so nothing here goes stale within a session. Re-asking on every focus
+    // would just re-sign a pass to learn the same answer.
+    staleTime: 5 * 60 * 1000,
+    refetchOnWindowFocus: false,
+  });
+}
+
+export type WalletPassEntry = {
+  passId: string;
+  status: WalletPassStatus;
+};
+
+/**
+ * The same question for SEVERAL passes — an order is usually more than one
+ * ticket, and each pass is its own wallet artefact with its own barcode.
+ *
+ * Returns only the passes that actually have something to offer, so a caller
+ * renders `entries` directly and gets the invisible-when-unavailable behaviour
+ * without writing a condition. `isLoading` is exposed for completeness but must
+ * NOT be used to draw a placeholder: a spinner where a button will never appear
+ * is exactly the tell this feature must not give.
+ */
+export function useWalletPasses(passIds: string[] | undefined, accountId?: string) {
+  const { client, profileId } = useForge();
+
+  const ids = useMemo(() => (passIds ?? []).filter(isEventPassId), [passIds]);
+
+  const queries = useQueries({
+    queries: ids.map((passId) => ({
+      queryKey: walletPassKey(passId, accountId, profileId),
+      queryFn: async () => {
+        const res = await client.get(`/public/events/passes/${passId}/wallet`, { params: { profileId } });
+        return res.data as WalletPassStatus;
+      },
+      enabled: !!accountId && !!profileId && !!client,
+      retry: false,
+      staleTime: 5 * 60 * 1000,
+      refetchOnWindowFocus: false,
+    })),
+  });
+
+  // `useQueries` hands back a fresh array identity every render, so the memo is
+  // keyed on when its members last changed rather than on the array itself —
+  // the same trick `useEventWaitlistPlaces` uses.
+  const stamp = queries.map((query) => query.dataUpdatedAt).join(",");
+
+  const entries = useMemo(() => {
+    const out: WalletPassEntry[] = [];
+    queries.forEach((query, index) => {
+      const status = query.data;
+      if (status && hasWalletPass(status)) out.push({ passId: ids[index]!, status });
+    });
+    return out;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ids, stamp]);
+
+  return {
+    /** ONLY the passes with a real wallet artefact. Empty is the production state today. */
+    entries,
+    /** True while any pass is still being asked about. Never render on this. */
+    isLoading: queries.some((query) => query.isLoading),
+  };
+}
+
+/**
+ * Fetch the signed `.pkpass` and hand it to the browser.
+ *
+ * `downloadUrl` comes from the status response rather than being rebuilt here —
+ * it already carries the `profileId` the endpoint requires, and reconstructing
+ * it would be a second place for the path to drift from the API.
+ */
+export function useDownloadApplePass() {
+  const { client } = useForge();
+
+  return useMutation<void, unknown, { passId: string; downloadUrl: string }>({
+    mutationFn: async ({ passId, downloadUrl }) => {
+      const res = await client.get(downloadUrl, { responseType: "blob" });
+
+      // Re-wrapped rather than used as-is: whether Axios preserves the server's
+      // content type on a Blob varies by adapter, and the type is the entire
+      // mechanism by which iOS opens Wallet instead of downloading a file.
+      const blob = new Blob([res.data as BlobPart], { type: PKPASS_MIME_TYPE });
+      const url = URL.createObjectURL(blob);
+
+      const anchor = document.createElement("a");
+      anchor.href = url;
+      anchor.download = `${passId}.pkpass`;
+      anchor.rel = "noopener";
+      document.body.appendChild(anchor);
+      anchor.click();
+      anchor.remove();
+
+      // Deferred, not immediate: Safari — the browser that matters most for a
+      // `.pkpass` — hands the URL to Wallet asynchronously, and revoking in the
+      // same tick can leave the holder with a pass that silently fails to open.
+      setTimeout(() => URL.revokeObjectURL(url), 60_000);
+    },
+  });
+}

package/src/data/queries/useWebsite.ts

@@ -29,6 +29,12 @@ export interface SiteConfig {
    * installable manifest + head tags. `null` when the creator has no pwaConfig
    * (minimal name-only manifest, not installable). Screenshots are optional. */
   pwa?: PwaConfig | null;
+  /** Suppresses the "Powered by TribeNest" badge on released builds. Server-side
+   * on purpose: the tenant owns `__root.tsx`, so anything expressed as a prop is
+   * an opt-out. Absent/false today — this is the lever a white-label plan
+   * entitlement flips, and it works without waiting for a Forge bump to reach
+   * every site. */
+  hideTribeNestBadge?: boolean;
 }
 
 /** The PWA identity block on `site-config` (mirrors `pwaConfig` on the profile). */

package/src/index.ts

@@ -37,6 +37,15 @@ export {
 export type { AuthActions } from "./contexts/PublicAuthContext";
 export { PUBLIC_REFRESH_TOKEN_KEY, APP_REFRESH_TOKEN_KEY } from "./client/tokenStorage";
 export { safeRedirectPath } from "./utils/safeRedirect";
+// Ticket-confirmation copy decision — shared so the Forge block and the client
+// app's finalise page can never tell a refunded buyer two different stories.
+export {
+  getTicketOrderOutcome,
+  isTicketOrderRefunded,
+  TICKET_ORDER_REFUNDED_COPY,
+  type TicketOrderOutcome,
+  type TicketOrderOutcomeInput,
+} from "./utils/ticketOrderOutcome";
 // App-user auth (mini-apps) + the /admin guard.
 export {
   useAppAuth,
@@ -72,6 +81,11 @@ export * from "./data/queries/useCohortPage";
 export * from "./data/queries/useCourseAccess";
 export * from "./data/queries/useBroadcasts";
 export * from "./data/queries/useAccount";
+export * from "./data/queries/useMyTickets";
+export * from "./data/queries/usePassTransfers";
+export * from "./data/queries/useMyBookings";
+export * from "./data/queries/useEventWaitlist";
+export * from "./data/queries/useWalletPass";
 export * from "./data/queries/useFinalize";
 export * from "./data/queries/useSubscriptions";
 export * from "./data/queries/useEngagement";

package/src/server/_tests/siteBootstrap.spec.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { probeApi, fetchSiteBootstrap } from "../index";
+
+// `fetch` is the seam — these are pure network-shape tests, no server needed.
+const stubFetch = (impl: (url: string, init?: RequestInit) => Promise<Response> | Response) =>
+  vi.stubGlobal("fetch", vi.fn((input: RequestInfo | URL, init?: RequestInit) => Promise.resolve(impl(String(input), init))));
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+const API = "https://api.example.test";
+
+describe("probeApi", () => {
+  it("reports ok against the public liveness route", async () => {
+    stubFetch((url) => {
+      expect(url).toBe(`${API}/healthcheck`);
+      return new Response("", { status: 200 });
+    });
+    const r = await probeApi(API);
+    expect(r).toMatchObject({ ok: true, url: `${API}/healthcheck`, status: 200 });
+    expect(r.ms).toBeGreaterThanOrEqual(0);
+  });
+
+  it("reports not-ok on a non-2xx without throwing", async () => {
+    stubFetch(() => new Response("nope", { status: 403 }));
+    expect(await probeApi(API)).toMatchObject({ ok: false, status: 403 });
+  });
+
+  it("reports the transport error on a network failure", async () => {
+    stubFetch(() => {
+      throw new TypeError("fetch failed");
+    });
+    expect(await probeApi(API)).toMatchObject({ ok: false, error: "fetch failed" });
+  });
+
+  it("gives up after the timeout instead of stalling the render", async () => {
+    // Never resolves on its own — only the abort ends it. A black-holed network
+    // must not hold SSR open.
+    stubFetch(
+      (_url, init) =>
+        new Promise<Response>((_resolve, reject) => {
+          init?.signal?.addEventListener("abort", () => reject(new DOMException("Aborted", "AbortError")));
+        }),
+    );
+    const r = await probeApi(API, { timeoutMs: 20 });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("no response within 20ms");
+  });
+});
+
+describe("fetchSiteBootstrap", () => {
+  it("returns data and NO diagnostics on a healthy render", async () => {
+    stubFetch((url) =>
+      url.includes("/content")
+        ? json({ version: 3, defaultLocale: "en", locales: ["en"], fields: { "theme.background": { type: "color", localized: false, value: "#0A0A0A" } } })
+        : json({ currency: "USD" }),
+    );
+
+    const r = await fetchSiteBootstrap({ apiUrl: API, profileId: "p1", websiteVersionId: "v1", state: "draft" });
+    expect(r.diagnostics).toBeNull();
+    expect(r.siteConfig).toEqual({ currency: "USD" });
+    expect(r.contentDoc.fields["theme.background"]).toMatchObject({ value: "#0A0A0A" });
+  });
+
+  it("requests the state it was given", async () => {
+    const seen: string[] = [];
+    stubFetch((url) => {
+      seen.push(url);
+      return url.includes("/content") ? json({ version: 0, defaultLocale: "en", locales: ["en"], fields: {} }) : json({});
+    });
+    await fetchSiteBootstrap({ apiUrl: API, profileId: "p1", websiteVersionId: "v1", state: "draft" });
+    expect(seen.some((u) => u.includes("state=draft") && u.includes("websiteVersionId=v1"))).toBe(true);
+  });
+
+  // THE REGRESSION THIS EXISTS FOR: an unreachable API used to be
+  // indistinguishable from an unconfigured site — both rendered Forge's white
+  // default theme with no signal anywhere.
+  it("reports every failed fetch, and probes to say WHY", async () => {
+    stubFetch(() => {
+      throw new TypeError("fetch failed");
+    });
+
+    const r = await fetchSiteBootstrap({ apiUrl: API, profileId: "p1", websiteVersionId: "v1", state: "draft" });
+
+    // Still degrades — a site never crashes on a bad API.
+    expect(r.contentDoc.fields).toEqual({});
+    expect(r.siteConfig).toBeNull();
+    // ...but no longer silently.
+    expect(r.diagnostics?.apiUrl).toBe(API);
+    expect(r.diagnostics?.failures).toEqual([
+      { what: "content", status: undefined, error: "fetch failed" },
+      { what: "siteConfig", status: undefined, error: "fetch failed" },
+    ]);
+    expect(r.diagnostics?.probe).toMatchObject({ ok: false, url: `${API}/healthcheck` });
+  });
+
+  it("carries the HTTP status when the request completed but was rejected", async () => {
+    stubFetch((url) => (url.includes("/content") ? new Response("denied", { status: 403 }) : json({ currency: "USD" })));
+
+    const r = await fetchSiteBootstrap({ apiUrl: API, profileId: "p1", websiteVersionId: "v1", state: "draft" });
+    expect(r.diagnostics?.failures).toEqual([{ what: "content", status: 403, error: "HTTP 403" }]);
+    // The healthy one still lands — a partial failure isn't a total one.
+    expect(r.siteConfig).toEqual({ currency: "USD" });
+  });
+
+  it("does not treat 'nothing to fetch' as a failure", async () => {
+    // No version + no profile baked in → no request went out → nothing failed.
+    const fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const r = await fetchSiteBootstrap({ apiUrl: API });
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(r.diagnostics).toBeNull();
+    expect(r.siteConfig).toBeNull();
+    expect(r.contentDoc.fields).toEqual({});
+  });
+
+  it("skips the probe when asked (it costs a request)", async () => {
+    stubFetch(() => {
+      throw new TypeError("fetch failed");
+    });
+    const r = await fetchSiteBootstrap({ apiUrl: API, profileId: "p1", websiteVersionId: "v1", probe: false });
+    expect(r.diagnostics?.failures).toHaveLength(2);
+    expect(r.diagnostics?.probe).toBeUndefined();
+  });
+});

package/src/server/index.ts

@@ -26,6 +26,11 @@ export * from "./appAuth";
 export * from "./appUsers";
 
 import { emptyContentDocument, type ContentDocument } from "../content/types";
+import type { ApiProbeResult, ForgeSsrDiagnostics, SsrFetchFailure } from "../types/diagnostics";
+
+// Re-exported so a site's `__root.tsx` can type its loader return without
+// reaching past the `@tribe-nest/forge/server` entry it already imports.
+export type { ApiProbeResult, ForgeSsrDiagnostics, SsrFetchFailure };
 import type {
   IEvent,
   IPublicProduct,
@@ -43,20 +48,37 @@ import type {
 import { collectionParamsToQuery, splitCollectionQuery } from "../data/collectionParams";
 import type { SiteConfig } from "../data/queries/useWebsite";
 
-/** GET a public endpoint and parse JSON, returning `null` on any failure. */
-async function getJson<T>(apiUrl: string, path: string, params?: Record<string, string | undefined>): Promise<T | null> {
+/**
+ * One public-API GET, KEEPING the failure reason. `getJson` (below) throws that
+ * reason away on purpose — a site must degrade, not crash — but the preview needs
+ * to tell "nothing is configured yet" apart from "I could not reach the API",
+ * which otherwise render identically. See `fetchSiteBootstrap`.
+ */
+type JsonResult<T> = { ok: true; data: T } | { ok: false; status?: number; error: string };
+
+async function getJsonResult<T>(
+  apiUrl: string,
+  path: string,
+  params?: Record<string, string | undefined>,
+): Promise<JsonResult<T>> {
   try {
     const qs = new URLSearchParams();
     for (const [k, v] of Object.entries(params ?? {})) if (v != null) qs.set(k, v);
     const query = qs.toString();
     const res = await fetch(`${apiUrl}${path}${query ? `?${query}` : ""}`);
-    if (!res.ok) return null;
-    return (await res.json()) as T;
-  } catch {
-    return null;
+    if (!res.ok) return { ok: false, status: res.status, error: `HTTP ${res.status}` };
+    return { ok: true, data: (await res.json()) as T };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
   }
 }
 
+/** GET a public endpoint and parse JSON, returning `null` on any failure. */
+async function getJson<T>(apiUrl: string, path: string, params?: Record<string, string | undefined>): Promise<T | null> {
+  const res = await getJsonResult<T>(apiUrl, path, params);
+  return res.ok ? res.data : null;
+}
+
 /** POST a JSON body to a public endpoint and parse JSON, `null` on any failure. */
 async function postJson<T>(apiUrl: string, path: string, body: unknown): Promise<T | null> {
   try {
@@ -98,6 +120,100 @@ export function fetchSiteConfig(opts: { apiUrl: string; profileId?: string }): P
   return getJson<SiteConfig>(opts.apiUrl, "/public/websites/site-config", { profileId: opts.profileId });
 }
 
+/** The API's unauthenticated liveness route — no tenant, no params, no body. */
+const PROBE_PATH = "/healthcheck";
+
+/**
+ * Can this runtime reach the TribeNest API at all? Calls a public route and
+ * reports what happened, rather than degrading to a fallback.
+ *
+ * This exists because the SSR runtime is NOT the visitor's browser: a site
+ * renders inside a Cloudflare Worker (published) or inside the preview sandbox
+ * (the builder), and those have their own egress. A sandbox that cannot reach the
+ * API still renders a complete-looking page — every server fetch just quietly
+ * returns nothing, so the site falls back to Forge's baseline theme while all the
+ * client-side data (fetched from the visitor's browser, which CAN reach the API)
+ * loads normally. The result reads as "the theme is broken", not as "the preview
+ * has no network", which is the wrong thing to go and debug.
+ *
+ * Never throws: a probe that fails IS the answer.
+ */
+export async function probeApi(apiUrl: string, opts?: { timeoutMs?: number }): Promise<ApiProbeResult> {
+  const url = `${apiUrl}${PROBE_PATH}`;
+  const timeoutMs = opts?.timeoutMs ?? 5000;
+  const started = Date.now();
+  // AbortSignal.timeout() isn't in every runtime this ships to; the controller
+  // pair is. Without a timeout a black-holed network stalls the whole render.
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    return { ok: res.ok, url, status: res.status, ms: Date.now() - started };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      url,
+      // An abort is the timeout firing — say so, rather than surfacing the
+      // runtime's own wording for a cancelled request.
+      error: controller.signal.aborted ? `no response within ${timeoutMs}ms` : error,
+      ms: Date.now() - started,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The whole SSR bootstrap in one call: the content document + the tenant's
+ * runtime config, fetched in parallel — PLUS what failed, if anything.
+ *
+ * Prefer this over calling `fetchContentDocument` / `fetchSiteConfig` separately.
+ * They return the same data, but they cannot report a failure (an unreachable API
+ * and a brand-new site both produce an empty document), so a shell built on them
+ * can only ever show Forge's defaults and stay silent about why.
+ *
+ * `diagnostics` is `null` on a healthy render and is only populated when a fetch
+ * actually failed — the reachability probe costs a request, so it runs only then.
+ * Pass it to `<TribeNestApp diagnostics={…}>`, which surfaces it in the builder
+ * preview and on review Workers, and never on the live published site.
+ */
+export async function fetchSiteBootstrap(opts: {
+  apiUrl: string;
+  profileId?: string;
+  websiteVersionId?: string;
+  state?: "draft" | "published";
+  /** Set false to skip the reachability probe even when a fetch failed. */
+  probe?: boolean;
+}): Promise<{ contentDoc: ContentDocument; siteConfig: SiteConfig | null; diagnostics: ForgeSsrDiagnostics | null }> {
+  const { apiUrl, profileId, websiteVersionId, state = "published" } = opts;
+
+  const [content, siteConfig] = await Promise.all([
+    websiteVersionId
+      ? getJsonResult<ContentDocument>(apiUrl, "/public/websites/content", { websiteVersionId, state })
+      : Promise.resolve<JsonResult<ContentDocument>>({ ok: true, data: emptyContentDocument() }),
+    profileId
+      ? getJsonResult<SiteConfig>(apiUrl, "/public/websites/site-config", { profileId })
+      : Promise.resolve<JsonResult<SiteConfig | null>>({ ok: true, data: null }),
+  ]);
+
+  // A deploy with no version / no profile baked in isn't a failure — there was
+  // nothing to fetch. Only a request that actually went out and lost counts.
+  const failures: SsrFetchFailure[] = [];
+  if (!content.ok) failures.push({ what: "content", status: content.status, error: content.error });
+  if (!siteConfig.ok) failures.push({ what: "siteConfig", status: siteConfig.status, error: siteConfig.error });
+
+  const diagnostics: ForgeSsrDiagnostics | null = failures.length
+    ? { apiUrl, failures, probe: opts.probe === false ? undefined : await probeApi(apiUrl) }
+    : null;
+
+  return {
+    contentDoc: content.ok ? (content.data ?? emptyContentDocument()) : emptyContentDocument(),
+    siteConfig: siteConfig.ok ? (siteConfig.data ?? null) : null,
+    diagnostics,
+  };
+}
+
 /** Fetch a single event by id or slug for SSR. */
 export function fetchEventServer(opts: { apiUrl: string; profileId?: string; idOrSlug: string }): Promise<IEvent | null> {
   return getJson<IEvent>(opts.apiUrl, `/public/events/${encodeURIComponent(opts.idOrSlug)}`, {

package/src/types/diagnostics.ts

@@ -0,0 +1,49 @@
+// SSR bootstrap diagnostics — shared by the server fetchers (which produce them)
+// and the preview banner in `forge/ui` (which renders them). They live here, in a
+// React-free and fetch-free module, so the UI can import the types without
+// dragging the server entry (jobs, appAuth, appUsers) into a client bundle.
+//
+// WHY THIS EXISTS: every public fetch in `forge/server` degrades to `null` / an
+// empty document on failure, so a site never crashes when the API hiccups. The
+// cost of that is that "this creator hasn't set a theme yet" and "I could not
+// reach the API at all" render as the SAME screen — Forge's baseline theme, a
+// white background and a purple accent. That ambiguity is invisible in the
+// builder preview and cost real debugging time: the published site was correctly
+// dark while the preview stayed white, and nothing anywhere said why.
+//
+// Keeping the failure reason instead of discarding it is what makes the preview
+// able to say "I could not reach the API", which is a different sentence from
+// "you have not set a theme".
+
+/** One public-API GET that failed during the SSR bootstrap. */
+export type SsrFetchFailure = {
+  /** Which bootstrap fetch this was. */
+  what: "content" | "siteConfig";
+  /** HTTP status, when the request completed but was not ok. Absent on a transport error. */
+  status?: number;
+  /** Transport error message, or `HTTP <status>`. */
+  error: string;
+};
+
+/** The result of calling a known-good public route to test API reachability. */
+export type ApiProbeResult = {
+  ok: boolean;
+  /** The exact URL probed, so the message can name it. */
+  url: string;
+  status?: number;
+  error?: string;
+  /** Round-trip milliseconds (a timeout shows up here as ~the timeout). */
+  ms: number;
+};
+
+/**
+ * What went wrong while bootstrapping this render. `null` on a healthy render —
+ * it is only ever populated when a bootstrap fetch actually failed.
+ */
+export type ForgeSsrDiagnostics = {
+  /** The API base URL this deploy is pointed at. */
+  apiUrl: string;
+  failures: SsrFetchFailure[];
+  /** Only run when a bootstrap fetch already failed — it costs a request. */
+  probe?: ApiProbeResult;
+};