@tribe-nest/forge 3.2.0 → 3.9.0

package/src/ui/shell/diagnosticsGating.spec.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import {
+  previewDiagnosticsEnabled,
+  resolvePreviewDiagnostics,
+  previewDiagnosticsMessage,
+} from "./diagnosticsGating";
+import type { ForgeSsrDiagnostics } from "../../types/diagnostics";
+
+describe("previewDiagnosticsEnabled", () => {
+  it("shows in the in-editor sandbox", () => {
+    expect(previewDiagnosticsEnabled({ editable: true, state: "draft" })).toBe(true);
+    // editable wins even if a shell mislabels the state.
+    expect(previewDiagnosticsEnabled({ editable: true, state: "published" })).toBe(true);
+  });
+
+  it("shows on a draft review Worker, which is not editable", () => {
+    expect(previewDiagnosticsEnabled({ editable: false, state: "draft" })).toBe(true);
+  });
+
+  it("NEVER shows on the live published site", () => {
+    expect(previewDiagnosticsEnabled({ editable: false, state: "published" })).toBe(false);
+    expect(previewDiagnosticsEnabled({ state: "published" })).toBe(false);
+    // A shell that passes neither must not leak the banner to visitors.
+    expect(previewDiagnosticsEnabled({})).toBe(false);
+  });
+});
+
+describe("resolvePreviewDiagnostics", () => {
+  const failed: ForgeSsrDiagnostics = {
+    apiUrl: "https://api.tribenest.co",
+    failures: [{ what: "content", error: "fetch failed" }],
+  };
+
+  it("passes through real diagnostics from fetchSiteBootstrap", () => {
+    expect(resolvePreviewDiagnostics({ diagnostics: failed, profileId: "p1", siteConfig: {} })).toBe(failed);
+  });
+
+  it("returns null on a healthy render", () => {
+    expect(resolvePreviewDiagnostics({ diagnostics: null, profileId: "p1", siteConfig: { currency: "USD" } })).toBeNull();
+  });
+
+  it("ignores an empty failure list", () => {
+    const clean: ForgeSsrDiagnostics = { apiUrl: "https://api.tribenest.co", failures: [] };
+    expect(resolvePreviewDiagnostics({ diagnostics: clean, profileId: "p1", siteConfig: {} })).toBeNull();
+  });
+
+  // The fallback that covers every already-deployed shell still calling
+  // fetchContentDocument/fetchSiteConfig separately — no file edit needed.
+  it("infers a failure from a null siteConfig when a profileId IS baked in", () => {
+    const d = resolvePreviewDiagnostics({ profileId: "p1", siteConfig: null, apiUrl: "https://api.tribenest.co" });
+    expect(d).toEqual({
+      apiUrl: "https://api.tribenest.co",
+      failures: [{ what: "siteConfig", error: "no response" }],
+    });
+  });
+
+  it("does NOT infer a failure when there was no profile to fetch for", () => {
+    // No profileId baked in → nothing was requested → a null config is correct,
+    // not a failure. Crying wolf here would train people to ignore the banner.
+    expect(resolvePreviewDiagnostics({ profileId: undefined, siteConfig: null })).toBeNull();
+    expect(resolvePreviewDiagnostics({ profileId: "", siteConfig: null })).toBeNull();
+  });
+});
+
+describe("previewDiagnosticsMessage", () => {
+  it("names the network as the cause when the probe also failed", () => {
+    const msg = previewDiagnosticsMessage({
+      apiUrl: "https://api.tribenest.co",
+      failures: [
+        { what: "content", error: "fetch failed" },
+        { what: "siteConfig", error: "fetch failed" },
+      ],
+      probe: { ok: false, url: "https://api.tribenest.co/healthcheck", error: "no response within 5000ms", ms: 5001 },
+    });
+    expect(msg.title).toBe("This preview can't reach the TribeNest API");
+    expect(msg.details.some((l) => l.includes("no route to the API"))).toBe(true);
+    expect(msg.details).toContain("API: https://api.tribenest.co");
+  });
+
+  it("distinguishes a reachable API from a per-route failure", () => {
+    const msg = previewDiagnosticsMessage({
+      apiUrl: "https://api.tribenest.co",
+      failures: [{ what: "content", error: "HTTP 500", status: 500 }],
+      probe: { ok: true, url: "https://api.tribenest.co/healthcheck", status: 200, ms: 42 },
+    });
+    expect(msg.title).toBe("This preview couldn't load your site data");
+    expect(msg.details.some((l) => l.includes("per-route failure"))).toBe(true);
+  });
+
+  it("always states that the defaults on screen are the symptom, not the setting", () => {
+    // This sentence is the entire point of the banner — the failure mode it was
+    // built for is a preview that looks configured-but-wrong rather than broken.
+    const msg = previewDiagnosticsMessage({ apiUrl: "", failures: [{ what: "siteConfig", error: "no response" }] });
+    expect(msg.consequence).toContain("default theme");
+    expect(msg.consequence).toContain("published site is unaffected");
+  });
+
+  it("omits the API line when the shell baked in no url", () => {
+    const msg = previewDiagnosticsMessage({ apiUrl: "", failures: [{ what: "content", error: "boom" }] });
+    expect(msg.details.some((l) => l.startsWith("API:"))).toBe(false);
+  });
+});

package/src/ui/shell/diagnosticsGating.ts

@@ -0,0 +1,90 @@
+// Pure logic for the preview's SSR-failure banner, kept React-free so it's
+// unit-testable in the node test env (no jsdom) — same split as `shellGating.ts`,
+// which is also why this is not named after the component it feeds: a
+// `previewDiagnostics.ts` next to `PreviewDiagnostics.tsx` differs only in
+// casing, which tsc rejects outright on a case-insensitive filesystem.
+import type { ForgeSsrDiagnostics } from "../../types/diagnostics";
+
+/**
+ * WHERE the banner is allowed to appear: any build that is NOT the released live
+ * site — the in-editor sandbox (`editable`) or a preview-<versionId> review
+ * Worker (`state === "draft"`).
+ *
+ * The inverse of `shellPwaEnabled` / `shellPoweredByEnabled`, and deliberately so:
+ * a visitor to a live site must never be shown our plumbing. On the live site the
+ * degraded render is still the right behaviour — the point of this banner is that
+ * the person who can FIX it (the creator, or us) is the one looking at it.
+ */
+export function previewDiagnosticsEnabled(opts: { editable?: boolean; state?: "draft" | "published" }): boolean {
+  return !!opts.editable || opts.state === "draft";
+}
+
+/**
+ * WHETHER there is anything to report, and what.
+ *
+ * Two sources, because the shells are versioned independently of Forge:
+ *
+ *  1. `diagnostics` — the precise answer, from `fetchSiteBootstrap`. Only shells
+ *     that have been updated to call it supply this.
+ *  2. The fallback — a deploy that HAS a `profileId` baked in but rendered with a
+ *     null `siteConfig` cannot be healthy: the fetch went out and came back with
+ *     nothing. Every already-deployed site whose `__root.tsx` still calls the old
+ *     `fetchSiteConfig` gets a (less detailed) banner from this on a Forge bump
+ *     alone, with no file edit.
+ *
+ * Returns null when there is nothing wrong.
+ */
+export function resolvePreviewDiagnostics(opts: {
+  diagnostics?: ForgeSsrDiagnostics | null;
+  profileId?: string;
+  siteConfig?: unknown;
+  apiUrl?: string;
+}): ForgeSsrDiagnostics | null {
+  if (opts.diagnostics && opts.diagnostics.failures.length > 0) return opts.diagnostics;
+  if (opts.profileId && opts.siteConfig == null) {
+    return {
+      apiUrl: opts.apiUrl ?? "",
+      failures: [{ what: "siteConfig", error: "no response" }],
+    };
+  }
+  return null;
+}
+
+export type PreviewDiagnosticsMessage = {
+  title: string;
+  /** The one sentence that resolves the confusion this banner exists for. */
+  consequence: string;
+  /** Specifics — one line per failure, plus the probe verdict. */
+  details: string[];
+};
+
+const WHAT_LABEL: Record<string, string> = {
+  content: "content document (your text, images and theme)",
+  siteConfig: "site config (currency, payment provider, tracking)",
+};
+
+/** Human copy for the banner. Pure — no React, no formatting concerns. */
+export function previewDiagnosticsMessage(d: ForgeSsrDiagnostics): PreviewDiagnosticsMessage {
+  const details = d.failures.map((f) => `Couldn't load the ${WHAT_LABEL[f.what] ?? f.what} — ${f.error}.`);
+
+  if (d.probe) {
+    details.push(
+      d.probe.ok
+        ? `The API answered ${d.probe.url} in ${d.probe.ms}ms, so this looks like a per-route failure rather than a network one.`
+        : `Couldn't reach ${d.probe.url} either — ${d.probe.error ?? `HTTP ${d.probe.status}`} after ${d.probe.ms}ms. This preview has no route to the API.`,
+    );
+  }
+  if (d.apiUrl) details.push(`API: ${d.apiUrl}`);
+
+  return {
+    title:
+      d.probe && !d.probe.ok
+        ? "This preview can't reach the TribeNest API"
+        : "This preview couldn't load your site data",
+    // The sentence that would have saved the debugging session this was built
+    // after: the defaults on screen are a symptom, not the setting.
+    consequence:
+      "You're seeing Forge's default theme (white background, purple accent) and empty content because the data never arrived — not because of how your site is configured. Your published site is unaffected.",
+    details,
+  };
+}

package/src/ui/shell/shellGating.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { shellPwaEnabled } from "./shellGating";
+import { poweredByHref, shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
 
 // The PWA (SW register + install prompt) must be ON only for the live published
 // site, and OFF everywhere else (editor, preview/draft), so review Workers never
@@ -26,3 +26,62 @@ describe("shellPwaEnabled", () => {
     expect(shellPwaEnabled({ editable: false, state: "published" })).toBe(true);
   });
 });
+
+// "Powered by TribeNest" ships on released builds only, and the ONLY way to
+// remove it is the server-supplied flag — there is no client-side opt-out,
+// because the tenant owns __root.tsx.
+describe("shellPoweredByEnabled", () => {
+  it("is true on a live published site", () => {
+    expect(shellPoweredByEnabled({ editable: false, state: "published" })).toBe(true);
+  });
+
+  it("is false in the editor and on draft/preview deploys", () => {
+    expect(shellPoweredByEnabled({ editable: true, state: "published" })).toBe(false);
+    expect(shellPoweredByEnabled({ editable: false, state: "draft" })).toBe(false);
+    expect(shellPoweredByEnabled({ editable: false })).toBe(false); // state undefined
+  });
+
+  it("is false only when the SERVER says to hide it", () => {
+    expect(shellPoweredByEnabled({ editable: false, state: "published", hideBadge: true })).toBe(false);
+    expect(shellPoweredByEnabled({ editable: false, state: "published", hideBadge: false })).toBe(true);
+  });
+});
+
+// The badge is only worth carrying if we can tell WHICH site sent the visitor,
+// so the identifying params are the point of the link, not decoration.
+describe("poweredByHref", () => {
+  const parse = (href: string) => new URL(href).searchParams;
+
+  it("identifies the referring site by subdomain", () => {
+    const p = parse(poweredByHref({ subdomain: "ladygaga", profileId: "prof-1" }));
+    expect(p.get("utm_source")).toBe("powered_by");
+    expect(p.get("utm_medium")).toBe("badge");
+    expect(p.get("utm_campaign")).toBe("creator_site");
+    expect(p.get("utm_content")).toBe("ladygaga");
+  });
+
+  it("falls back to the profileId when no subdomain is baked in", () => {
+    expect(parse(poweredByHref({ profileId: "prof-1" })).get("utm_content")).toBe("prof-1");
+  });
+
+  it("distinguishes a mini-app from a website, and one app from another", () => {
+    const p = parse(poweredByHref({ subdomain: "ladygaga", appId: "app-7" }));
+    expect(p.get("utm_campaign")).toBe("creator_app");
+    expect(p.get("utm_content")).toBe("ladygaga"); // the tenant
+    expect(p.get("utm_term")).toBe("app-7"); // the deploy
+  });
+
+  it("omits utm_content rather than emitting an empty one when identity is missing", () => {
+    expect(parse(poweredByHref({})).has("utm_content")).toBe(false);
+  });
+
+  it("url-encodes an identity that needs it", () => {
+    // A subdomain can't contain these, but utm_content also carries profile ids
+    // and one day whatever replaces them — encode rather than trust the shape.
+    expect(parse(poweredByHref({ subdomain: "a b&c" })).get("utm_content")).toBe("a b&c");
+  });
+
+  it("always points at the marketing site", () => {
+    expect(poweredByHref({ subdomain: "x" }).startsWith("https://tribenest.co/?")).toBe(true);
+  });
+});

package/src/ui/shell/shellGating.ts

@@ -9,3 +9,50 @@ export function shellPwaEnabled(opts: {
 }): boolean {
   return (opts.pwa ?? true) && !opts.editable && opts.state === "published";
 }
+
+// "Powered by TribeNest" shows on RELEASED builds only — the live published
+// site, never the HMR editor or a preview-<versionId>.* review Worker. Same
+// released-build test as the PWA, with one extra lever: `hideBadge` comes from
+// the server (`siteConfig.hideTribeNestBadge`), which is where a white-label
+// plan entitlement turns it off. It is deliberately not a `TribeNestApp` prop —
+// the tenant owns __root.tsx, so a prop would make the badge opt-out.
+export function shellPoweredByEnabled(opts: {
+  editable?: boolean;
+  state?: "draft" | "published";
+  hideBadge?: boolean;
+}): boolean {
+  return !opts.hideBadge && !opts.editable && opts.state === "published";
+}
+
+/** Marketing site the badge points at. */
+const TRIBENEST_URL = "https://tribenest.co/";
+
+/**
+ * The badge href, tagged so a signup can be traced back to the exact site that
+ * referred it.
+ *
+ *   utm_source=powered_by   the badge, as against any other tribenest.co inbound
+ *   utm_medium=badge
+ *   utm_campaign            creator_site | creator_app — which surface it was
+ *   utm_content             WHICH site: the tenant subdomain, falling back to the
+ *                           profileId when a deploy has no subdomain baked in
+ *   utm_term                the appId on a mini-app, so two apps on one profile
+ *                           stay distinguishable (utm_content is the tenant, not
+ *                           the deploy)
+ *
+ * Built from the identity `ForgeProvider` was constructed with — baked at build
+ * time — never from `window.location`. That keeps it identical on the server and
+ * the client (no hydration mismatch), and correct on custom domains, where the
+ * hostname says nothing about which tenant it is.
+ */
+export function poweredByHref(opts: { subdomain?: string; profileId?: string; appId?: string }): string {
+  const params = new URLSearchParams({
+    utm_source: "powered_by",
+    utm_medium: "badge",
+    utm_campaign: opts.appId ? "creator_app" : "creator_site",
+  });
+  const site = opts.subdomain || opts.profileId;
+  if (site) params.set("utm_content", site);
+  if (opts.appId) params.set("utm_term", opts.appId);
+  return `${TRIBENEST_URL}?${params.toString()}`;
+}