@tribe-nest/forge 3.53.0 → 3.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.53.0",
+  "version": "3.57.0",
   "publishConfig": {
     "access": "public"
   },

package/src/contexts/AppAuthContext.tsx

@@ -1,5 +1,6 @@
 "use client";
-import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { createSharedContext } from "../runtime/registry";
 import { useForge } from "../provider/ForgeProvider";
 import { createForgeClient } from "../client/createForgeClient";
 import {
@@ -105,7 +106,7 @@ interface AppAuthContextType {
   hasPermission: (permission: string) => boolean;
 }
 
-const AppAuthContext = createContext<AppAuthContextType | null>(null);
+const AppAuthContext = createSharedContext<AppAuthContextType | null>("appAuth", null);
 
 export function AppAuthProvider({ children }: { children: ReactNode }) {
   const { apiUrl, appId, publishableKey } = useForge();

package/src/contexts/AudioPlayerContext.tsx

@@ -1,5 +1,6 @@
 "use client";
-import { createContext, useContext, useState, useRef, useEffect, useCallback } from "react";
+import { useContext, useState, useRef, useEffect, useCallback } from "react";
+import { createSharedContext } from "../runtime/registry";
 import type { ReactNode } from "react";
 
 export interface AudioTrack {
@@ -34,7 +35,7 @@ interface AudioPlayerContextType {
   queue: AudioTrack[];
 }
 
-const AudioPlayerContext = createContext<AudioPlayerContextType | undefined>(undefined);
+const AudioPlayerContext = createSharedContext<AudioPlayerContextType | undefined>("audioPlayer", undefined);
 
 export function AudioPlayerProvider({ children }: { children: ReactNode }) {
   const [currentTrack, setCurrentTrack] = useState<AudioTrack | null>(null);

package/src/contexts/CartContext.tsx

@@ -1,6 +1,7 @@
 "use client";
 import type { IBookingFee, ProductDeliveryType } from "../types/models";
-import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import { useCallback, useContext, useMemo, useState } from "react";
+import { createSharedContext } from "../runtime/registry";
 import type { ReactNode } from "react";
 import { useEffect } from "react";
 
@@ -153,7 +154,7 @@ interface CartContextType {
   isReady: boolean;
 }
 
-const CartContext = createContext<CartContextType | undefined>(undefined);
+const CartContext = createSharedContext<CartContextType | undefined>("cart", undefined);
 
 const CART_STORAGE_KEY = "tribenest-cart";
 

package/src/contexts/PublicAuthContext.tsx

@@ -1,5 +1,6 @@
 "use client";
-import { createContext, type ReactNode, useCallback, useContext, useEffect, useReducer, useState } from "react";
+import { type ReactNode, useCallback, useContext, useEffect, useReducer, useState } from "react";
+import { createSharedContext } from "../runtime/registry";
 import {
   type ApiError,
   type PublicAuthUser,
@@ -107,7 +108,7 @@ const AuthReducer = (state: PublicAuthState, action: AuthActions): PublicAuthSta
   }
 };
 
-const PublicAuthContext = createContext<PublicAuthContextType | null>(null);
+const PublicAuthContext = createSharedContext<PublicAuthContextType | null>("publicAuth", null);
 
 // ----------------------------------------------------------------------
 

package/src/data/queries/useCoachingProducts.ts

@@ -7,7 +7,20 @@ export interface GetCoachingProductsParams {
   query?: string;
 }
 
-export function useGetCoachingProducts(params?: GetCoachingProductsParams, enabled = true) {
+export function useGetCoachingProducts(
+  params?: GetCoachingProductsParams,
+  enabled = true,
+  options?: {
+  /**
+   * The page a server render already fetched.
+   *
+   * Seeds the cache so the first client render matches the markup and nothing
+   * is refetched. Must be built with the SAME params as the key below, or the
+   * seed belongs to a different query and is ignored.
+   */
+    initialData?: PaginatedData<CoachingProduct>;
+  },
+) {
   const { client, profileId } = useForge();
 
   return useQuery<PaginatedData<CoachingProduct>>({
@@ -23,6 +36,7 @@ export function useGetCoachingProducts(params?: GetCoachingProductsParams, enabl
       return res.data;
     },
     enabled: !!profileId && !!client && enabled,
+    initialData: options?.initialData,
   });
 }
 

package/src/data/queries/useCourses.ts

@@ -90,7 +90,20 @@ export interface GetCoursesParams {
   query?: string;
 }
 
-export function useGetCourses(params?: GetCoursesParams, enabled = true) {
+export function useGetCourses(
+  params?: GetCoursesParams,
+  enabled = true,
+  options?: {
+  /**
+   * The page a server render already fetched.
+   *
+   * Seeds the cache so the first client render matches the markup and nothing
+   * is refetched. Must be built with the SAME params as the key below, or the
+   * seed belongs to a different query and is ignored.
+   */
+    initialData?: PaginatedData<PublicCourse>;
+  },
+) {
   const { client, profileId } = useForge();
 
   return useQuery<PaginatedData<PublicCourse>>({
@@ -106,6 +119,7 @@ export function useGetCourses(params?: GetCoursesParams, enabled = true) {
       return res.data;
     },
     enabled: !!profileId && !!client && enabled,
+    initialData: options?.initialData,
   });
 }
 

package/src/data/queries/useEvents.ts

@@ -3,7 +3,17 @@ import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
 /** All published events for the profile. */
-export function useEvents() {
+export function useEvents(options?: {
+  /**
+   * The list a server render already fetched (`fetchEventsServer`).
+   *
+   * Seeds the cache so the first client render shows the same events as the
+   * markup and nothing is refetched. Without it the list page renders a
+   * spinner on the server, which is what a crawler sees and what a fan sees
+   * for as long as the request takes.
+   */
+  initialData?: IEvent[];
+}) {
   const { client, profileId } = useForge();
 
   return useQuery<IEvent[]>({
@@ -15,6 +25,7 @@ export function useEvents() {
       return res.data;
     },
     enabled: !!profileId && !!client,
+    initialData: options?.initialData,
   });
 }
 
@@ -161,6 +172,20 @@ export type CreateEventOrderResult = {
    * exists — and for a profile with inventory holds switched off.
    */
   holdExpiresAt?: string | null;
+  /**
+   * This order is a ticket REQUEST (curated access, feature 3): the tiers in it
+   * need the organiser's approval, so nothing is sold until they decide.
+   *
+   * With a price on it the payment step runs as today and the charge is
+   * deferred (`settlement: "deferred"` on start-payment). With nothing to pay
+   * the order is already `pending_approval` when this returns, `isFreeCheckout`
+   * is FALSE (no passes were minted), and there is no payment step: the
+   * checkout goes straight to the request-received outcome. See
+   * `nextStepAfterTicketOrder`.
+   */
+  awaitingApproval?: boolean;
+  /** When an undecided request lapses, ISO-8601. `null` on an ordinary sale. */
+  requestExpiresAt?: string | null;
 };
 
 /** Create an event ticket order (the step before start-payment). */

package/src/data/queries/useMembership.ts

@@ -1,22 +1,60 @@
-import type { MembershipTier } from "../../types/models";
+import type {
+  ApplyForMembershipResult,
+  MembershipApplication,
+  MembershipInviteInfo,
+  MembershipTier,
+  QuestionnaireAnswer,
+} from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
-import { useQuery } from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+/**
+ * The membership invite token this visitor arrived holding, read from the
+ * `invite` search param of the CURRENT url (the invite email links to
+ * `/i/membership/checkout?membershipTierId=X&invite=TOKEN`).
+ *
+ * Deliberately not stored anywhere: it is a bearer credential, and the durable
+ * copy is the email. Returns undefined on the server and when absent.
+ */
+export const readMembershipInviteFromUrl = (search?: string): string | undefined => {
+  const raw = search ?? (typeof window === "undefined" ? "" : window.location.search);
+  if (!raw) return undefined;
+  const token = new URLSearchParams(raw).get("invite")?.trim();
+  return token ? token : undefined;
+};
+
+export interface UseGetMembershipTiersOptions {
+  enabled?: boolean;
+  /**
+   * An invite token to forward, so an invite-only tier it unlocks is listed.
+   * Omitted (undefined), the `invite` search param of the current url is used;
+   * `null` forwards nothing even when the url carries one.
+   */
+  inviteToken?: string | null;
+}
 
 /**
  * `opts.enabled` gates the request on top of the usual profile/client checks —
  * for a caller that only needs tier NAMES when something is actually gated, and
  * must not add a request to every ungated storefront. Defaults to on, so every
  * existing caller is unchanged.
+ *
+ * Invite-only tiers are omitted by the server unless the request carries a
+ * live invite token for them, so the token is part of the query key.
  */
-export function useGetMembershipTiers(opts: { enabled?: boolean } = {}) {
+export function useGetMembershipTiers(opts: UseGetMembershipTiersOptions = {}) {
   const { client, profileId } = useForge();
+  const inviteToken = opts.inviteToken === undefined ? readMembershipInviteFromUrl() : (opts.inviteToken ?? undefined);
 
   return useQuery<MembershipTier[]>({
-    queryKey: ["membership-tiers", profileId],
+    // The token is appended only when present, so the no-invite key stays the
+    // one every existing cache seed (SSR, specs) already writes.
+    queryKey: inviteToken ? ["membership-tiers", profileId, inviteToken] : ["membership-tiers", profileId],
     queryFn: async () => {
       const res = await client.get("/public/membership-tiers", {
         params: {
           profileId: profileId,
+          ...(inviteToken ? { inviteToken } : {}),
         },
       });
       return res.data;
@@ -24,3 +62,137 @@ export function useGetMembershipTiers(opts: { enabled?: boolean } = {}) {
     enabled: !!profileId && !!client && opts.enabled !== false,
   });
 }
+
+// ---- Invites -------------------------------------------------------------------
+
+/**
+ * What a membership invite link is for: the tier and the invited email, so the
+ * landing page can name both before asking for anything.
+ *
+ * A dead token (unknown, expired, revoked or already accepted) is a 404, which
+ * is an ANSWER rather than a transient failure, so it is not retried. Tell the
+ * two apart with `isMembershipInviteDead(error)`.
+ */
+export function useMembershipInviteInfo(token?: string | null) {
+  const { client } = useForge();
+
+  return useQuery<MembershipInviteInfo>({
+    queryKey: ["membership-invite-info", token ?? null],
+    queryFn: async () => {
+      const res = await client.get("/public/membership-invites/info", { params: { token } });
+      return res.data;
+    },
+    enabled: !!token && !!client,
+    retry: (count, error) => !isMembershipInviteDead(error) && count < 2,
+  });
+}
+
+/** True when an invite-info error means the invite is gone (404), not that the request failed. */
+export function isMembershipInviteDead(error: unknown): boolean {
+  return (error as { response?: { status?: number } } | null)?.response?.status === 404;
+}
+
+// ---- Applications ----------------------------------------------------------------
+
+export type ApplyForMembershipInput = {
+  membershipTierId: string;
+  /** Required on a paid tier. */
+  billingCycle?: "month" | "year";
+  /** Required on a paid tier; same floor/ceiling rules as a subscription. */
+  amount?: number;
+  /**
+   * A free-text note, up to 1000 characters. Still accepted by the server, but
+   * no current checkout sends it: the tier's questions replaced it.
+   */
+  message?: string;
+  /** Answers to the tier's questions. Required by the server when the tier has any. */
+  questionnaire?: QuestionnaireAnswer[];
+  /** Where Stripe returns after a redirect-based card confirmation. */
+  returnUrl?: string;
+};
+
+/** Invalidate everything an application changes: the tier cards and the fan's list. */
+function useInvalidateApplications() {
+  const queryClient = useQueryClient();
+  return () =>
+    Promise.all([
+      queryClient.invalidateQueries({ queryKey: ["membership-tiers"] }),
+      queryClient.invalidateQueries({ queryKey: ["my-membership-applications"] }),
+    ]);
+}
+
+/**
+ * Apply to join an `application` tier.
+ *
+ * A free tier comes back `pending` with nothing more to do. A paid tier comes
+ * back `card_pending` with `requiresCard` and a SetupIntent `clientSecret`: the
+ * card is saved, not charged, and after the renderer confirms it the caller
+ * calls `useConfirmMembershipApplication`. Applying again while one is open
+ * returns that one.
+ */
+export function useApplyForMembership() {
+  const { client, profileId } = useForge();
+  const invalidate = useInvalidateApplications();
+
+  return useMutation<ApplyForMembershipResult, unknown, ApplyForMembershipInput>({
+    mutationFn: async (body) => {
+      const res = await client.post("/public/membership-applications", { ...body, profileId });
+      return res.data;
+    },
+    onSuccess: () => void invalidate(),
+  });
+}
+
+/**
+ * Tell the server the card step finished. Idempotent. The application comes
+ * back `pending` once the provider shows the card saved, still `card_pending`
+ * if it does not yet, or `withdrawn` with `closedReason: "tier_full"` when the
+ * last seat went in the meantime.
+ */
+export function useConfirmMembershipApplication() {
+  const { client, profileId } = useForge();
+  const invalidate = useInvalidateApplications();
+
+  return useMutation<{ application: MembershipApplication }, unknown, { applicationId: string }>({
+    mutationFn: async ({ applicationId }) => {
+      const res = await client.post(`/public/membership-applications/${encodeURIComponent(applicationId)}/confirm`, {
+        profileId,
+      });
+      return res.data;
+    },
+    onSuccess: () => void invalidate(),
+  });
+}
+
+/** Withdraw an application that is still `card_pending` or `pending`. */
+export function useWithdrawMembershipApplication() {
+  const { client, profileId } = useForge();
+  const invalidate = useInvalidateApplications();
+
+  return useMutation<{ application: MembershipApplication }, unknown, { applicationId: string }>({
+    mutationFn: async ({ applicationId }) => {
+      const res = await client.post(`/public/membership-applications/${encodeURIComponent(applicationId)}/withdraw`, {
+        profileId,
+      });
+      return res.data;
+    },
+    onSuccess: () => void invalidate(),
+  });
+}
+
+/**
+ * The signed-in fan's applications on this profile, newest first. Pass the
+ * account id so the query waits for sign-in and is keyed per account.
+ */
+export function useMyMembershipApplications(accountId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<MembershipApplication[]>({
+    queryKey: ["my-membership-applications", accountId, profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/membership-applications/mine", { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!accountId && !!profileId && !!client,
+  });
+}

package/src/data/queries/useMyTickets.ts

@@ -108,6 +108,33 @@ export type MyTicketPendingTransfer = {
 /** How the caller comes to be looking at an order. */
 export type MyTicketRole = "purchaser" | "holder";
 
+/**
+ * Where a ticket REQUEST stands (curated access, feature 3), per order.
+ *
+ *   pending         lodged; the organiser has until `expiresAt` to decide
+ *   approved        approved; on a priced request the charge is settled or
+ *                   settling, and the passes are on the order
+ *   declined        the organiser said no; `decisionNote` carries their words
+ *   expired         the window lapsed undecided; the hold was released
+ *   payment_failed  approved, but the deferred charge could not be settled
+ *                   (`failureReason`); the seat was released
+ *
+ * `state: null` means the order was never a request. The whole object is
+ * optional because it is newer than the endpoint: an older API build sends no
+ * `request` at all, and `myTicketRequestState` reads that as "not a request".
+ */
+export type MyTicketRequestState = "pending" | "approved" | "declined" | "expired" | "payment_failed";
+
+export type MyTicketRequest = {
+  state: MyTicketRequestState | null;
+  requestedAt: string | null;
+  /** The "decide by" instant while `pending`. */
+  expiresAt: string | null;
+  decidedAt: string | null;
+  decisionNote: string | null;
+  failureReason: string | null;
+};
+
 export type MyTicketItem = {
   id: string;
   quantity: number;
@@ -150,6 +177,8 @@ export type MyTicket = {
    * `purchaser` reproduces exactly the previous behaviour.
    */
   role?: MyTicketRole;
+  /** The ticket request behind this order, if it was one. See `MyTicketRequest`. */
+  request?: MyTicketRequest | null;
   /**
    * The event's `.ics`, both forms — what lets the portal offer Apple Calendar
    * rather than only the three template providers. Null for a cancelled show.
@@ -163,6 +192,26 @@ export type MyTicket = {
   passes?: MyTicketPass[];
 };
 
+/**
+ * The request state of an order, or `null` when it was never a request (or
+ * the API build predates requests). One place to read it so no surface has to
+ * know the object is optional.
+ */
+export function myTicketRequestState(ticket: Pick<MyTicket, "request">): MyTicketRequestState | null {
+  return ticket.request?.state ?? null;
+}
+
+/**
+ * Does this request still have a live decision ahead of it, or did it end
+ * without a sale? Both mean "no passes, nothing to cancel, nothing to hand
+ * on", which is what the tickets tab reads to draw the row as a request rather
+ * than as a purchase. An `approved` request is a purchase by now.
+ */
+export function isMyTicketRequestOpenOrEnded(ticket: Pick<MyTicket, "request">): boolean {
+  const state = myTicketRequestState(ticket);
+  return state === "pending" || state === "declined" || state === "expired" || state === "payment_failed";
+}
+
 /**
  * Every pass id on an order.
  *

package/src/data/queries/usePaymentFlow.ts

@@ -152,6 +152,14 @@ export function usePaymentFlow(opts: UsePaymentFlowOptions) {
     /** PAYSTACK: the hosted page used only when the modal cannot open. */
     checkoutUrl: result?.checkoutUrl,
     isPaystack,
+    /**
+     * `"deferred"` when the charge is committed now and settled only if the
+     * organiser approves (an event ticket request). Undefined on every
+     * ordinary sale and on an older API build, which renders as before.
+     */
+    settlement: result?.settlement,
+    /** How the provider defers a `settlement: "deferred"` charge. See `PaymentStartResponse`. */
+    deferredStrategy: result?.deferredStrategy ?? null,
     /** True once there is a Paystack session a pay button can open. */
     canOpenPaystack: hasPaystackSession(session),
     openPaystackCheckout: openPaystack,

package/src/data/queries/useProducts.ts

@@ -41,7 +41,20 @@ export function useFeaturedProducts(productType?: ProductType) {
   });
 }
 
-export function useGetProducts(params?: GetProductsParams, enabled = true) {
+export function useGetProducts(
+  params?: GetProductsParams,
+  enabled = true,
+  options?: {
+  /**
+   * The page a server render already fetched.
+   *
+   * Seeds the cache so the first client render matches the markup and nothing
+   * is refetched. Must be built with the SAME params as the key below, or the
+   * seed belongs to a different query and is ignored.
+   */
+    initialData?: PaginatedData<IPublicProduct>;
+  },
+) {
   const { client, profileId } = useForge();
 
   return useQuery<PaginatedData<IPublicProduct>>({
@@ -64,6 +77,7 @@ export function useGetProducts(params?: GetProductsParams, enabled = true) {
       return res.data;
     },
     enabled: !!profileId && !!client && enabled,
+    initialData: options?.initialData,
   });
 }
 

package/src/data/queries/useSubscriptions.ts

@@ -1,6 +1,7 @@
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation } from "@tanstack/react-query";
 import { usePublicAuth } from "../../contexts/PublicAuthContext";
+import type { QuestionnaireAnswer } from "../../types/models";
 import {
   getMembershipAccess,
   getMembershipStatusMessage,
@@ -14,6 +15,13 @@ export type CreateSubscriptionInput = {
   membershipTierId: string;
   returnUrl: string;
   attributionRefId?: string;
+  /**
+   * A membership invite token. Required by the server on an `invite` tier (the
+   * invite must be for the signed-in email); ignored on an open tier.
+   */
+  inviteToken?: string;
+  /** Answers to the tier's questions. Required by the server when the tier has any. */
+  questionnaire?: QuestionnaireAnswer[];
 };
 
 /**
@@ -41,6 +49,12 @@ export type CreateSubscriptionResult = {
   currentPeriodEnd?: string;
   requiresPayment?: boolean;
   changed?: boolean;
+  /**
+   * Set when this subscription starts with a free trial. `clientSecret` is then
+   * a Stripe SetupIntent secret (`seti_...`): the card is saved, nothing is
+   * charged today, and the first charge is on `endsAt`.
+   */
+  trial?: { days: number; endsAt: string } | null;
 };
 
 /** Subscribe to a paid tier, or move an existing subscription onto another one. */
@@ -59,7 +73,13 @@ export function useCreateSubscription() {
 export function useCreateFreeSubscription() {
   const { client, profileId } = useForge();
 
-  return useMutation<unknown, unknown, { membershipTierId: string; attributionRefId?: string }>({
+  return useMutation<unknown, unknown, {
+      membershipTierId: string;
+      attributionRefId?: string;
+      inviteToken?: string;
+      /** Answers to the tier's questions. Required by the server when the tier has any. */
+      questionnaire?: QuestionnaireAnswer[];
+    }>({
     mutationFn: async (body) => {
       const res = await client.post("/public/payments/subscriptions/free", { ...body, profileId });
       return res.data;