@tribe-nest/forge 3.53.0 → 3.57.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/index.ts

@@ -46,6 +46,7 @@ import type {
   CollectionQueryParams,
   CollectionQuery,
   CollectionSearchResult,
+  PaginatedData,
 } from "../types/models";
 import { collectionParamsToQuery, splitCollectionQuery } from "../data/collectionParams";
 // SEO context for structured data. Pure functions over plain data, so this is
@@ -274,6 +275,18 @@ export async function fetchSiteBootstrap(opts: {
 }
 
 /** Fetch a single event by id or slug for SSR. */
+/**
+ * Every published event, for SSR of the events list.
+ *
+ * The list page had no server fetch at all: it rendered a spinner into the
+ * document and filled itself in from the browser, so a crawler saw an empty
+ * page and a fan saw a flash of nothing. It is the same endpoint the client
+ * hook reads, so the markup and the first client render agree.
+ */
+export async function fetchEventsServer(opts: { apiUrl: string; profileId?: string }): Promise<IEvent[]> {
+  return (await getJson<IEvent[]>(opts.apiUrl, `/public/events`, { profileId: opts.profileId })) ?? [];
+}
+
 export function fetchEventServer(opts: {
   apiUrl: string;
   profileId?: string;
@@ -351,6 +364,67 @@ export function buildMusicLinkHead(
 }
 
 /** Fetch a single product by id or slug for SSR. */
+/**
+ * The catalogue pages, server-rendered.
+ *
+ * Each of these list pages used to render a spinner into the document and
+ * fill itself in from the browser, so a crawler indexed an empty page and a
+ * fan saw nothing until the fetch landed. They are the pages search engines
+ * actually index, which makes an empty server render the expensive kind.
+ *
+ * Each mirrors its client hook exactly, same endpoint and same page size, so
+ * the markup and the first client render agree and nothing is fetched twice.
+ * An empty page is a real answer here (a creator who sells no courses), so a
+ * failed fetch resolves to an empty page rather than throwing.
+ */
+const emptyPage = <T,>(): PaginatedData<T> => ({
+  data: [],
+  total: 0,
+  hasNextPage: false,
+  page: 1,
+  nextPage: null,
+  pageSize: 10,
+});
+
+export async function fetchProductsServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+}): Promise<PaginatedData<IPublicProduct>> {
+  return (
+    (await getJson<PaginatedData<IPublicProduct>>(opts.apiUrl, `/public/products`, {
+      profileId: opts.profileId,
+      page: "1",
+      limit: "10",
+    })) ?? emptyPage<IPublicProduct>()
+  );
+}
+
+export async function fetchCoursesServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+}): Promise<PaginatedData<PublicCourse>> {
+  return (
+    (await getJson<PaginatedData<PublicCourse>>(opts.apiUrl, `/public/courses`, {
+      profileId: opts.profileId,
+      page: "1",
+      limit: "10",
+    })) ?? emptyPage<PublicCourse>()
+  );
+}
+
+export async function fetchCoachingProductsServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+}): Promise<PaginatedData<CoachingProduct>> {
+  return (
+    (await getJson<PaginatedData<CoachingProduct>>(opts.apiUrl, `/public/coaching/products`, {
+      profileId: opts.profileId,
+      page: "1",
+      limit: "10",
+    })) ?? emptyPage<CoachingProduct>()
+  );
+}
+
 export function fetchProductServer(opts: {
   apiUrl: string;
   profileId?: string;

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,151 @@ 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 application approved: An application was approved. `status` is `joined`, or `payment_failed` when the saved card was declined.
+   *
+   * Requires the `membership.application_approved` grant.
+   */
+  "membership_application.approved": {
+    applicationId: string;
+    membershipTierId: string | null;
+    status: string | null;
+    billingCycle: string | null;
+    amount: number | null;
+    currency: string | null;
+    membershipId: string | null;
+    applicant: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+  };
+  /**
+   * Membership application declined: An application to join a membership tier was declined.
+   *
+   * Requires the `membership.application_declined` grant.
+   */
+  "membership_application.declined": {
+    applicationId: string;
+    membershipTierId: string | null;
+    status: string | null;
+    billingCycle: string | null;
+    amount: number | null;
+    currency: string | null;
+    membershipId: string | null;
+    applicant: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+  };
+  /**
+   * Membership application submitted: Someone applied to join a membership tier that needs approval. Nothing is charged until approved.
+   *
+   * Requires the `membership.application_submitted` grant.
+   */
+  "membership_application.submitted": {
+    applicationId: string;
+    membershipTierId: string | null;
+    status: string | null;
+    billingCycle: string | null;
+    amount: number | null;
+    currency: string | null;
+    membershipId: string | null;
+    applicant: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+  };
   /**
    * Membership tier archived: A membership tier was archived and can no longer be joined.
    *
@@ -403,6 +548,13 @@ 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_application.approved": "membership.application_approved",
+  "membership_application.declined": "membership.application_declined",
+  "membership_application.submitted": "membership.application_submitted",
   "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
@@ -288,6 +307,116 @@ export type MembershipTier = {
   welcomeMessageContent?: string | null;
   cancellationMessageSubject?: string | null;
   cancellationMessageContent?: string | null;
+  /**
+   * How a fan gets onto this tier (curated access). `open` is the ordinary
+   * checkout; `invite` needs a live invite for the signed-in email (and the
+   * tier is only listed when the request carried that invite's token);
+   * `application` means the fan applies and the business approves. Optional,
+   * because an older API build sends nothing, which reads as `open`.
+   */
+  joinMode?: MembershipJoinMode;
+  /**
+   * The signed-in fan's most recent open application on this tier (or their
+   * latest declined one), so the tier card can show where it stands instead of
+   * a join button. Absent when signed out or on an older API build.
+   */
+  myApplication?: MembershipTierMyApplication | null;
+  /**
+   * Free trial length in days on a paid tier (1 to 90), or null for no trial.
+   * A card is still collected; the first charge is on today + trialDays.
+   */
+  trialDays?: number | null;
+  /**
+   * False once the signed-in fan has had a trial with this business (one per
+   * fan per business, any tier). Absent when signed out: treat as eligible.
+   */
+  trialEligible?: boolean;
+  /**
+   * Questions the fan answers before paying or joining, on every join mode.
+   * Null or absent when the tier asks nothing.
+   */
+  questionnaire?: QuestionnaireQuestion[] | null;
+};
+
+/** How a fan gets onto a membership tier. */
+export type MembershipJoinMode = "open" | "invite" | "application";
+
+/**
+ * Where an application to a membership tier stands.
+ *
+ *   card_pending    paid tier: card step started, not confirmed. Not yet visible to the business.
+ *   pending         lodged and waiting for a decision; holds a seat
+ *   approved        approved; the subscription is being created
+ *   payment_failed  approved, but the saved card was declined; the fan can finish at checkout
+ *   joined          the membership exists
+ *   declined        not approved
+ *   withdrawn       withdrawn by the fan, or closed because the tier filled (`closedReason: "tier_full"`)
+ *   expired         the window to finish a failed payment lapsed
+ */
+export type MembershipApplicationStatus =
+  | "card_pending"
+  | "pending"
+  | "approved"
+  | "payment_failed"
+  | "joined"
+  | "declined"
+  | "withdrawn"
+  | "expired";
+
+/** The slice of an application the public tier list carries per tier. */
+export type MembershipTierMyApplication = {
+  id: string;
+  status: MembershipApplicationStatus;
+  paymentWindowExpiresAt: string | null;
+};
+
+export type MembershipApplication = {
+  id: string;
+  profileId: string;
+  membershipTierId: string;
+  /** Present on list payloads. */
+  membershipTierName?: string;
+  accountId: string;
+  status: MembershipApplicationStatus;
+  /** Null on a free tier. */
+  billingCycle: "month" | "year" | null;
+  /** What will be charged per cycle, in major units. Null on a free tier. */
+  amount: number | null;
+  currency: string | null;
+  /** A note from an older checkout. Current checkouts ask the tier's questions instead. */
+  message: string | null;
+  /** The fan's answers to the tier's questions, as given when applying. */
+  questionnaire?: QuestionnaireAnswer[] | null;
+  /** e.g. "Visa •••• 4242", set once the card is confirmed. */
+  instrumentLabel: string | null;
+  decidedAt: string | null;
+  decisionNote: string | null;
+  /** `"tier_full"`, `"expired"`, or the provider's decline reason on `payment_failed`. */
+  closedReason: string | null;
+  /** The deadline to finish a `payment_failed` application. */
+  paymentWindowExpiresAt: string | null;
+  membershipId: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+/** What `POST /public/membership-applications` answers. */
+export type ApplyForMembershipResult = {
+  application: MembershipApplication;
+  /** True on a paid tier until the card is confirmed. */
+  requiresCard: boolean;
+  /** A Stripe SetupIntent secret (`seti_..._secret_...`) when `requiresCard`. */
+  clientSecret: string | null;
+};
+
+/** What `GET /public/membership-invites/info` answers for a live invite. */
+export type MembershipInviteInfo = {
+  membershipTierId: string;
+  membershipTierName: string;
+  profileId: string;
+  /** The address the invite was sent to; the fan must be signed in with it. */
+  email: string;
+  expiresAt: string;
 };
 
 /**
@@ -327,6 +456,10 @@ export interface Membership {
   subscriptionAmount: number;
   subscriptionCurrency: string;
   billingCycle: string;
+  /** Set when the membership started with a free trial: when the first charge is due. */
+  trialEndsAt?: string | null;
+  /** The fan's answers to the tier's questions, as given when joining. */
+  questionnaire?: QuestionnaireAnswer[] | null;
 }
 
 // ---- Public auth -------------------------------------------------------------
@@ -892,6 +1025,19 @@ export type QuestionnaireQuestion = {
   optional?: boolean;
 };
 
+/**
+ * A fan's answer to one {@link QuestionnaireQuestion}, as sent at checkout and
+ * as stored on what the checkout created. `answer` is `""` for an optional
+ * question left blank.
+ */
+export type QuestionnaireAnswer = {
+  id: string;
+  question: string;
+  type: string;
+  options?: string[];
+  answer: string;
+};
+
 /**
  * S.6 — the cancellation terms a buyer is entitled to read BEFORE they pay.
  *
@@ -1145,6 +1291,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 +1491,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 +1669,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 +1789,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;