@tribe-nest/forge 3.52.0 → 3.54.0

package/src/runtime/registry.ts

@@ -0,0 +1,102 @@
+import { createContext, type Context } from "react";
+
+/**
+ * The runtime a built creator site shares with the central pages bundle.
+ *
+ * A site and the hosted `/i/*` pages are two separately built bundles that have
+ * to behave as ONE app. If each carried its own React, its own router and its
+ * own copies of Forge's contexts, a fan would hold two carts, be logged in on
+ * one half of the page and anonymous on the other, and hooks would throw the
+ * moment a bundled block tried to read a provider the host had mounted.
+ *
+ * So the host publishes its runtime on a global object and the bundle reads it
+ * rather than carrying its own. First writer wins, always: the site boots
+ * first, registers, and the bundle then finds what is already there.
+ *
+ * That rule is what makes a CONTEXT shareable, which is the part worth
+ * understanding. `createContext` called twice produces two unrelated objects,
+ * and a provider mounted from one is invisible to a consumer reading the other.
+ * `createSharedContext` gives both bundles the same object instead, so the
+ * host's `<CartProvider>` is the cart the bundle's `useCart()` reads.
+ *
+ * ## The contract
+ *
+ * What lives here is a contract between a site built at one moment and a bundle
+ * published later, so it is ADDITIVE FOR EVER. A key, once published under a
+ * contract, never changes meaning and is never removed. Adding one is safe:
+ * an older bundle simply does not ask for it. Removing or repurposing one is a
+ * contract bump (`rc1` to `rc2`), which leaves old sites on the old bundle
+ * until their next build.
+ *
+ * Nothing INSIDE the bundle is covered by this. Forge's UI blocks ship in the
+ * bundle precisely so a block fix needs no contract change and no rebuild.
+ */
+
+/**
+ * Names the set of things the registry exposes. It rides in the bundle URL
+ * (`forge-pages/<contract>/latest`), so a site always asks for the bundle that
+ * matches the runtime it was built with.
+ */
+export const PAGES_RUNTIME_CONTRACT = "rc1";
+
+/**
+ * A single global, not a module-level variable. A module-level one would give
+ * each bundle its own copy, which is the exact failure this exists to prevent.
+ * The name is deliberately awkward to discourage anyone reading it directly.
+ */
+const GLOBAL_KEY = "__tribenestPagesRuntime__";
+
+type Registry = Record<string, unknown>;
+
+function registry(): Registry {
+  const scope = globalThis as unknown as Record<string, Registry | undefined>;
+  const existing = scope[GLOBAL_KEY];
+  if (existing) return existing;
+  const created: Registry = {};
+  scope[GLOBAL_KEY] = created;
+  return created;
+}
+
+/**
+ * Publish a value under `key`, or return the one already published.
+ *
+ * `create` runs only when nobody has claimed the key yet, so the host's React
+ * and the host's QueryClient are the ones everybody ends up with, whichever
+ * bundle happens to call first. Registration is therefore safe to run more than
+ * once and in any order.
+ */
+export function shareRuntimeValue<T>(key: string, create: () => T): T {
+  const reg = registry();
+  if (!(key in reg)) reg[key] = create();
+  return reg[key] as T;
+}
+
+/** Read a published value, or `undefined` when the host never published it. */
+export function readRuntimeValue<T>(key: string): T | undefined {
+  return registry()[key] as T | undefined;
+}
+
+/**
+ * A React context that is the SAME object in every bundle that asks for it.
+ *
+ * Use this instead of `createContext` for anything a hosted page consumes.
+ * `defaultValue` is only used by the bundle that gets there first; the others
+ * receive that same context and its default, which is correct, since a context
+ * with two different defaults across bundles would be two contexts again.
+ */
+export function createSharedContext<T>(key: string, defaultValue: T): Context<T> {
+  return shareRuntimeValue(`context:${key}`, () => createContext<T>(defaultValue));
+}
+
+/**
+ * Which of `required` the host never published.
+ *
+ * The bundle calls this BEFORE it renders anything. A missing key means the
+ * site was built against a runtime older than this bundle expects, and the
+ * honest response is the reload notice: rendering anyway produces a blank page
+ * or a thrown hook, and neither tells anyone what went wrong.
+ */
+export function missingRuntimeKeys(required: readonly string[]): string[] {
+  const reg = registry();
+  return required.filter((key) => !(key in reg));
+}

package/src/server/jobs.ts

@@ -246,7 +246,10 @@ export async function handleAppJobRun(
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ token }),
     });
-    valid = (await res.json())?.valid === true;
+    // Typed rather than left to inference: under Cloudflare's types `json()`
+    // resolves to `{}`, so the property read does not compile in a Worker.
+    const verified = (await res.json()) as { valid?: boolean } | null;
+    valid = verified?.valid === true;
   } catch {
     valid = false;
   }

package/src/server/platformEvents.generated.ts

@@ -220,6 +220,94 @@ export type PlatformEventMap = {
       unitPrice: number | null;
     }>;
   };
+  /**
+   * Event ticket request approved: The organiser approved a ticket request; the sale settled and the tickets were issued.
+   *
+   * Requires the `events.read` grant.
+   */
+  "event_ticket_request.approved": {
+    orderId: string;
+    eventId: string | null;
+    status: string | null;
+    total: number | null;
+    currency: string | null;
+    buyer: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+    tickets: Array<{
+      ticketId: string | null;
+      quantity: number;
+      unitPrice: number | null;
+    }>;
+  };
+  /**
+   * Event ticket request declined: The organiser declined a ticket request; the hold was released.
+   *
+   * Requires the `events.read` grant.
+   */
+  "event_ticket_request.declined": {
+    orderId: string;
+    eventId: string | null;
+    status: string | null;
+    total: number | null;
+    currency: string | null;
+    buyer: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+    tickets: Array<{
+      ticketId: string | null;
+      quantity: number;
+      unitPrice: number | null;
+    }>;
+  };
+  /**
+   * Event ticket request expired: A ticket request lapsed undecided; the hold and the seats were released.
+   *
+   * Requires the `events.read` grant.
+   */
+  "event_ticket_request.expired": {
+    orderId: string;
+    eventId: string | null;
+    status: string | null;
+    total: number | null;
+    currency: string | null;
+    buyer: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+    tickets: Array<{
+      ticketId: string | null;
+      quantity: number;
+      unitPrice: number | null;
+    }>;
+  };
+  /**
+   * Event ticket requested: Someone requested tickets to an event that needs the organiser's approval. Their card is held, not charged.
+   *
+   * Requires the `events.read` grant.
+   */
+  "event_ticket_request.submitted": {
+    orderId: string;
+    eventId: string | null;
+    status: string | null;
+    total: number | null;
+    currency: string | null;
+    buyer: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+    tickets: Array<{
+      ticketId: string | null;
+      quantity: number;
+      unitPrice: number | null;
+    }>;
+  };
   /**
    * Membership tier archived: A membership tier was archived and can no longer be joined.
    *
@@ -403,6 +491,10 @@ export const PLATFORM_EVENT_PERMISSIONS: Record<PlatformEventName, string> = {
   "email.clicked": "emails.read",
   "email.opened": "emails.read",
   "event_ticket_order.paid": "events.read",
+  "event_ticket_request.approved": "events.read",
+  "event_ticket_request.declined": "events.read",
+  "event_ticket_request.expired": "events.read",
+  "event_ticket_request.submitted": "events.read",
   "membership_tier.archived": "membership.tier_archived",
   "membership_tier.created": "membership.tier_created",
   "message.received": "contacts.read",

package/src/types/models.ts

@@ -66,6 +66,12 @@ export type PublicTaxQuote = {
  * Stripe always populates `paymentSecret` and never the Paystack pair; Paystack
  * always populates `accessCode` + `checkoutUrl` and never `paymentSecret`.
  */
+/** Whether a started charge is taken now or only once the organiser approves. */
+export type PaymentSettlement = "immediate" | "deferred";
+
+/** How a provider holds a deferred charge until the decision. */
+export type DeferredChargeStrategy = "authorization" | "saved_instrument";
+
 export type PaymentStartResponse = {
   /**
    * STRIPE ONLY: the PaymentIntent client secret fed to Stripe Elements.
@@ -101,6 +107,19 @@ export type PaymentStartResponse = {
   shippingCosts?: { deliveryGroupId: string; amount: number; currency: string }[];
   /** Authoritative sales-tax quote for this charge (all wired pillars). */
   taxQuote?: PublicTaxQuote;
+  /**
+   * EVENT TICKET REQUESTS: `"deferred"` when this charge is committed now and
+   * settled only if the organiser approves. Absent (or `"immediate"`) on every
+   * ordinary sale. Drives the "Authorize" wording on the pay button.
+   */
+  settlement?: PaymentSettlement;
+  /**
+   * How the provider defers the charge. `"authorization"` places a temporary
+   * hold the fan can see on their statement; `"saved_instrument"` stores the
+   * card and takes nothing until approval. Only meaningful with
+   * `settlement: "deferred"`.
+   */
+  deferredStrategy?: DeferredChargeStrategy | null;
   /**
    * COHORT ENROLMENT ONLY: what THIS charge takes, when the plan is paid in
    * instalments. `totalAmount` above stays the whole plan, so a checkout that
@@ -1145,6 +1164,12 @@ export interface IEvent {
   createdAt: string;
   updatedAt: string;
   tickets: ITicket[];
+  /**
+   * At least one tier on this event needs the organiser's approval. Optional
+   * on the wire; derive it from `tickets` with `eventHasApprovalTiers` rather
+   * than trusting its absence.
+   */
+  hasApprovalTiers?: boolean;
   media: IMedia[];
   slug: string;
   /**
@@ -1339,6 +1364,17 @@ export type ITicket = {
    * {@link PublicMembershipGate}.
    */
   membershipGate?: PublicMembershipGate | null;
+  /**
+   * The organiser decides who gets this tier (curated access, feature 3).
+   *
+   * A request is lodged instead of a sale: the card is authorised, not charged,
+   * the seat is held, and the organiser has a window to approve or decline.
+   * Sent to every client. A site on an older Forge shows such a tier with its
+   * ordinary buy button; that is accepted until the site takes the update.
+   */
+  requiresApproval?: boolean;
+  /** How long the organiser has to decide, in hours. `null` means the platform default. */
+  approvalWindowHours?: number | null;
 };
 
 // ---- Invoices ----------------------------------------------------------------
@@ -1506,6 +1542,12 @@ export enum OrderStatus {
   Delivered = "delivered",
   Cancelled = "cancelled",
   Processed = "processed",
+  /** Ticket request lodged: charge committed (authorised), seat held, nothing captured, no passes. */
+  PendingApproval = "pending_approval",
+  /** Transient: the organiser approved and settlement is in flight. */
+  Approved = "approved",
+  /** The organiser declined the request; the authorisation was released. */
+  Declined = "declined",
 }
 
 export type IPublicOrderItem = {
@@ -1620,6 +1662,22 @@ export type ITicketOrder = {
   refundedAmountCents?: number | string | null;
   refundState?: "none" | "partial" | "full" | string | null;
   lastRefundedAt?: string | null;
+  /**
+   * Ticket-request columns (curated access, feature 3). All absent on an
+   * ordinary sale and on an older API build.
+   *
+   * `approvalRequestExpiresAt` is the "decide by" instant a fan is shown while
+   * the request is `pending_approval`. `approvalFailureReason` is set when a
+   * request ended without a sale: `"expired"` on a `cancelled` row whose window
+   * lapsed undecided, and the provider's reason on a `payment_failed` row the
+   * organiser approved but could not settle. See `getTicketOrderOutcome` and
+   * `ticketRequestFailureKind`.
+   */
+  approvalRequestedAt?: string | null;
+  approvalRequestExpiresAt?: string | null;
+  approvalDecidedAt?: string | null;
+  approvalDecisionNote?: string | null;
+  approvalFailureReason?: string | null;
   customerName: string;
   customerEmail: string;
   createdAt: string;

package/src/ui/headless/agent/_tests/pathExclusion.spec.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { isPathExcluded } from "../pathExclusion";
+
+/**
+ * The client half of the exclusion rule. It has to agree with the server half
+ * (`apps/backend/src/services/public/agent/pathExclusion.ts`) case for case:
+ * the server decides what gets stored, the browser decides what gets hidden,
+ * and a disagreement shows the widget on a page the artist excluded.
+ */
+describe("isPathExcluded", () => {
+  const patterns = ["/pricing", "/blog/*"];
+
+  it("shows the widget when nothing is excluded", () => {
+    expect(isPathExcluded("/pricing", [])).toBe(false);
+    expect(isPathExcluded("/pricing", undefined)).toBe(false);
+  });
+
+  it("hides it on an exactly named page", () => {
+    expect(isPathExcluded("/pricing", patterns)).toBe(true);
+  });
+
+  it("leaves a sibling that merely shares a prefix alone", () => {
+    expect(isPathExcluded("/pricing-guide", patterns)).toBe(false);
+    expect(isPathExcluded("/blogroll", patterns)).toBe(false);
+  });
+
+  it("hides it under a wildcard, index page included", () => {
+    expect(isPathExcluded("/blog", patterns)).toBe(true);
+    expect(isPathExcluded("/blog/hello", patterns)).toBe(true);
+    expect(isPathExcluded("/blog/2026/hello", patterns)).toBe(true);
+  });
+
+  it("ignores case, a trailing slash and a query string", () => {
+    expect(isPathExcluded("/Blog/Hello/", patterns)).toBe(true);
+    expect(isPathExcluded("/PRICING?ref=email", patterns)).toBe(true);
+  });
+
+  it("treats a bare /* as the whole site", () => {
+    expect(isPathExcluded("/", ["/*"])).toBe(true);
+    expect(isPathExcluded("/anything/deep", ["/*"])).toBe(true);
+  });
+
+  it("hides it on the home page only when '/' is listed", () => {
+    expect(isPathExcluded("/", ["/"])).toBe(true);
+    expect(isPathExcluded("/shop", ["/"])).toBe(false);
+  });
+
+  it("accepts a stored pattern the artist typed loosely", () => {
+    expect(isPathExcluded("/pricing", ["pricing"])).toBe(true);
+    expect(isPathExcluded("/blog/hello", ["/blog/"])).toBe(false);
+  });
+});

package/src/ui/headless/agent/_tests/useCurrentPath.spec.tsx

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useCurrentPath } from "../useCurrentPath";
+
+/**
+ * The widget hides itself per page, so it has to notice a page change. Forge
+ * has no router, and a site's in-app link is a `pushState` that fires no event
+ * of its own - which is exactly the case a `popstate`-only listener misses, and
+ * would leave the widget showing on an excluded page for the rest of the visit.
+ */
+describe("useCurrentPath", () => {
+  afterEach(() => {
+    window.history.pushState({}, "", "/");
+  });
+
+  it("reports the path the browser is on", () => {
+    window.history.pushState({}, "", "/pricing");
+    const { result } = renderHook(() => useCurrentPath());
+    expect(result.current).toBe("/pricing");
+  });
+
+  it("follows a pushState navigation, which is every in-app link", () => {
+    const { result } = renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.pushState({}, "", "/blog/hello");
+    });
+    expect(result.current).toBe("/blog/hello");
+  });
+
+  it("follows a replaceState navigation too", () => {
+    const { result } = renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.replaceState({}, "", "/shop");
+    });
+    expect(result.current).toBe("/shop");
+  });
+
+  it("ignores the query string, which is not part of the path", () => {
+    const { result } = renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.pushState({}, "", "/shop?sort=new");
+    });
+    expect(result.current).toBe("/shop");
+  });
+
+  it("leaves history working for everyone else - the wrap is additive", () => {
+    renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.pushState({}, "", "/one");
+    });
+    expect(window.location.pathname).toBe("/one");
+  });
+});

package/src/ui/headless/agent/pathExclusion.ts

@@ -0,0 +1,53 @@
+/**
+ * Client half of the concierge's "don't appear on these pages" rule.
+ *
+ * The artist stores paths in the admin; the widget hides itself when the page
+ * it is on matches one. Two forms:
+ *   "/pricing"   - that page only
+ *   "/blog/*"    - that page AND everything under it
+ *
+ * Matching is case-insensitive and ignores a trailing slash, so "/blog",
+ * "/Blog" and "/blog/" are one page here as they are to a visitor.
+ *
+ * This must stay in step with the server half,
+ * `apps/backend/src/services/public/agent/pathExclusion.ts`, which normalises
+ * what gets stored. Kept as a copy rather than an import because Forge ships to
+ * creator sites and cannot reach into the backend.
+ */
+
+/** Reduce one stored pattern or page path to the form both sides compare. */
+function normalize(raw: string): string {
+  let path = (raw || "").trim();
+  if (!path) return "";
+  const url = /^https?:\/\/[^/]+(\/.*)?$/i.exec(path);
+  if (url) path = url[1] || "/";
+  path = path.split("#")[0].split("?")[0];
+  if (!path.startsWith("/")) path = `/${path}`;
+  path = path.replace(/\/{2,}/g, "/");
+  const wildcard = path.endsWith("/*");
+  const base = wildcard ? path.slice(0, -2) : path;
+  const cleaned = base.length > 1 ? base.replace(/\/+$/, "") : base;
+  return wildcard ? `${cleaned}/*` : cleaned || "/";
+}
+
+/** Does `path` fall under any of `patterns`? */
+export function isPathExcluded(path: string, patterns: readonly string[] | null | undefined): boolean {
+  if (!patterns || patterns.length === 0) return false;
+  const normalizedTarget = normalize(path);
+  const target = (
+    normalizedTarget.endsWith("/*") ? normalizedTarget.slice(0, -2) || "/" : normalizedTarget
+  ).toLowerCase();
+  for (const raw of patterns) {
+    const pattern = normalize(raw).toLowerCase();
+    if (!pattern) continue;
+    if (pattern.endsWith("/*")) {
+      const prefix = pattern.slice(0, -2);
+      // "/*" alone means the whole site.
+      if (prefix === "") return true;
+      if (target === prefix || target.startsWith(`${prefix}/`)) return true;
+      continue;
+    }
+    if (target === pattern) return true;
+  }
+  return false;
+}

package/src/ui/headless/agent/useAiAgent.ts

@@ -5,6 +5,8 @@ import {
   streamAgentMessage,
   useWebsiteAgentConfig,
 } from "../../../data/queries/useWebsiteAgent";
+import { isPathExcluded } from "./pathExclusion";
+import { useCurrentPath } from "./useCurrentPath";
 
 export interface AiAgentMessage {
   role: "user" | "assistant";
@@ -35,6 +37,7 @@ function getVisitorId(): string {
 export function useAiAgent() {
   const { apiUrl, profileId, token } = useForge();
   const config = useWebsiteAgentConfig();
+  const path = useCurrentPath();
 
   const [messages, setMessages] = useState<AiAgentMessage[]>([]);
   const [sending, setSending] = useState(false);
@@ -94,9 +97,15 @@ export function useAiAgent() {
     [apiUrl, profileId, token, visitorId, sending, ensureConversation],
   );
 
+  // The artist can keep the assistant off named pages. Checked here rather than
+  // in the widget so every UI built on this hook obeys it, including custom
+  // ones. SSR reports no path, so the widget stays hidden until the browser can
+  // say where it is - appearing and then vanishing would be worse.
+  const excluded = !path || isPathExcluded(path, config.data?.excludedPaths);
+
   return {
     config: config.data,
-    isEnabled: !!config.data?.enabled,
+    isEnabled: !!config.data?.enabled && !excluded,
     loading: config.isLoading,
     messages,
     sending,

package/src/ui/headless/agent/useCurrentPath.ts

@@ -0,0 +1,49 @@
+import { useEffect, useState } from "react";
+
+/**
+ * The browser's current path, kept up to date across client-side navigation.
+ *
+ * Forge has no router of its own and ships into sites that do, so it cannot
+ * subscribe to one. `popstate` alone misses a pushState navigation, which is
+ * every in-app link, so the two history methods are wrapped once per document
+ * to emit an event the hook listens for. The wrapping is additive: the original
+ * methods still run, and anything else that wrapped them keeps working.
+ *
+ * Returns "" during SSR, where there is no location to read.
+ */
+
+const EVENT = "forge:locationchange";
+let patched = false;
+
+function patchHistoryOnce() {
+  if (patched || typeof window === "undefined") return;
+  patched = true;
+  for (const method of ["pushState", "replaceState"] as const) {
+    const original = window.history[method];
+    window.history[method] = function patchedMethod(this: History, ...args: Parameters<History[typeof method]>) {
+      const result = original.apply(this, args);
+      window.dispatchEvent(new Event(EVENT));
+      return result;
+    };
+  }
+}
+
+export function useCurrentPath(): string {
+  const [path, setPath] = useState(() => (typeof window === "undefined" ? "" : window.location.pathname));
+
+  useEffect(() => {
+    patchHistoryOnce();
+    const update = () => setPath(window.location.pathname);
+    // A navigation that happened between first render and this effect would
+    // otherwise be missed.
+    update();
+    window.addEventListener("popstate", update);
+    window.addEventListener(EVENT, update);
+    return () => {
+      window.removeEventListener("popstate", update);
+      window.removeEventListener(EVENT, update);
+    };
+  }, []);
+
+  return path;
+}