@tribe-nest/forge 3.22.0 → 3.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.22.0",
+  "version": "3.24.0",
   "publishConfig": {
     "access": "public"
   },
@@ -20,6 +20,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@paystack/inline-js": "^2.24.0",
     "@radix-ui/react-dialog": "^1.1.14",
     "@radix-ui/react-slot": "^1.2.3",
     "@stripe/react-stripe-js": "^3.8.0",

package/src/data/queries/_tests/eventWaitlist.spec.ts

@@ -6,6 +6,7 @@ import {
   isLiveWaitlistEntry,
   isTicketSoldOut,
   rememberWaitlistEntry,
+  readWaitlistClaimFromUrl,
   ticketSeatsRemaining,
 } from "../useEventWaitlist";
 import type { IEvent, ITicket } from "../../../types/models";
@@ -120,3 +121,40 @@ describe("the anonymous joiner's remembered capability ids", () => {
     expect(getRememberedWaitlistEntries("e1")).toEqual([]);
   });
 });
+
+/**
+ * Events 2.6b — the offer email's claim link.
+ *
+ * `?waitlistEntry=<uuid>&waitlistClaim=<64 hex>`. The parse is deliberately
+ * strict about the token's shape so a junk query string never becomes a request,
+ * and a link missing either half is simply not a claim — the visitor gets the
+ * ordinary page rather than a broken one.
+ */
+describe("readWaitlistClaimFromUrl", () => {
+  const token = "a".repeat(64);
+
+  it("reads a well-formed claim", () => {
+    expect(readWaitlistClaimFromUrl(`?waitlistEntry=entry-1&waitlistClaim=${token}`)).toEqual({
+      entryId: "entry-1",
+      token,
+    });
+  });
+
+  it("survives the other query parameters an email link picks up", () => {
+    expect(
+      readWaitlistClaimFromUrl(`?utm_source=email&waitlistClaim=${token}&waitlistEntry=entry-9&ref=x`),
+    ).toEqual({ entryId: "entry-9", token });
+  });
+
+  it("is null when either half is missing", () => {
+    expect(readWaitlistClaimFromUrl(`?waitlistClaim=${token}`)).toBeNull();
+    expect(readWaitlistClaimFromUrl("?waitlistEntry=entry-1")).toBeNull();
+    expect(readWaitlistClaimFromUrl("")).toBeNull();
+  });
+
+  it("rejects a token that is not exactly 64 lowercase hex characters", () => {
+    for (const bad of ["nope", "A".repeat(64), "a".repeat(63), "a".repeat(65), "../../etc"]) {
+      expect(readWaitlistClaimFromUrl(`?waitlistEntry=entry-1&waitlistClaim=${bad}`)).toBeNull();
+    }
+  });
+});

package/src/data/queries/useAnalytics.ts

@@ -62,25 +62,76 @@ export interface TrackEventOptions {
  * `const { track } = useTrackEvent(); track("cta_click", { id: "hero" })`.
  */
 export function useTrackEvent(opts?: TrackEventOptions) {
-  const { client, subdomain: ctxSubdomain } = useForge();
+  const { client, apiUrl, subdomain: ctxSubdomain } = useForge();
   const subdomain = opts?.subdomain ?? ctxSubdomain;
   const storeSession = opts?.storeSession ?? true;
 
-  const track = useCallback(
-    (eventType: string, eventData: Record<string, unknown> = {}) => {
-      if (typeof window === "undefined" || !client || !subdomain) return;
+  const buildPayload = useCallback(
+    (eventData: Record<string, unknown>) => {
       // Cookieless mode omits the sessionId entirely — the backend derives a
       // rotating per-day visitor hash so nothing touches the device.
-      const sessionId = storeSession ? getAnalyticsSessionId(subdomain) : undefined;
+      const sessionId = storeSession && subdomain ? getAnalyticsSessionId(subdomain) : undefined;
       const payload: Record<string, unknown> = { ...eventData };
       if (sessionId) payload.sessionId = sessionId;
+      return payload;
+    },
+    [subdomain, storeSession],
+  );
+
+  const track = useCallback(
+    (eventType: string, eventData: Record<string, unknown> = {}) => {
+      if (typeof window === "undefined" || !client || !subdomain) return;
       // Fire-and-forget: analytics must never block the UI or surface errors.
       client
-        .post("/public/websites/track-event", { subdomain, eventType, eventData: payload })
+        .post("/public/websites/track-event", { subdomain, eventType, eventData: buildPayload(eventData) })
         .catch(() => {});
     },
-    [client, subdomain, storeSession],
+    [client, subdomain, buildPayload],
+  );
+
+  /**
+   * Same event, but it survives the page going away.
+   *
+   * `track` above posts through the Axios instance, and Axios in the browser is
+   * XHR. XHR has no `keepalive` option at all, so when a click navigates the tab
+   * somewhere else the request is cancelled mid-flight and the event is simply
+   * lost. That is tolerable for a click that stays on the site and fatal for one
+   * that does not: on a music smart link EVERY conversion is an outbound
+   * navigation to Spotify, so the ordinary transport would drop a large share of
+   * the only events the page exists to record, and take the server-side Meta
+   * `Lead` down with them.
+   *
+   * `fetch` with `keepalive: true` is the fix. Deliberately not
+   * `navigator.sendBeacon`, which cannot set `Content-Type: application/json`
+   * without wrapping the body in a Blob, and this endpoint is JSON-only.
+   *
+   * Use it for any event immediately followed by a navigation. Ordinary
+   * in-page events should keep using `track`, which goes through the configured
+   * client and picks up its interceptors.
+   */
+  const trackBeacon = useCallback(
+    (eventType: string, eventData: Record<string, unknown> = {}) => {
+      if (typeof window === "undefined" || !apiUrl || !subdomain) return;
+      try {
+        void fetch(`${apiUrl.replace(/\/$/, "")}/public/websites/track-event`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          keepalive: true,
+          body: JSON.stringify({
+            subdomain,
+            eventType,
+            eventData: buildPayload(eventData),
+            // The referrer header only carries the origin cross-origin, so the
+            // server cannot work out which page this happened on by itself.
+            eventSourceUrl: window.location.href,
+          }),
+        }).catch(() => {});
+      } catch {
+        // Best-effort by definition; never disrupt the navigation.
+      }
+    },
+    [apiUrl, subdomain, buildPayload],
   );
 
-  return { track };
+  return { track, trackBeacon };
 }

package/src/data/queries/useAuthActions.ts

@@ -39,7 +39,7 @@ export function useForgotPassword() {
       if (!contextId) {
         // Better than posting without it: the endpoint would 400 on schema
         // validation and the form would show "something went wrong".
-        throw new Error("useForgotPassword: no profileId — pass one or render inside a ForgeProvider with profileId");
+        throw new Error("useForgotPassword: no profileId. Pass one or render inside a ForgeProvider with profileId");
       }
       const res = await client.post("/public/sessions/forgot-password", {
         profileId: contextId,

package/src/data/queries/useCheckouts.ts

@@ -143,7 +143,12 @@ export type ApplyCheckoutCouponResult = {
   /** NET = max(0, subtotalCents − discountCents), minor units. */
   totalCents: number;
   appliedCoupons: AppliedBundleCoupon[];
+  /** STRIPE: the re-issued PaymentIntent client secret. */
   paymentSecret: string;
+  /** PAYSTACK: the re-issued inline-checkout session. */
+  accessCode?: string;
+  /** PAYSTACK: the hosted page for the re-issued session (runtime fallback). */
+  checkoutUrl?: string;
   paymentId: string;
   chargedAmount: number;
   chargedCurrency: string;

package/src/data/queries/useEventWaitlist.ts

@@ -17,6 +17,10 @@ import type { IEvent, ITicket } from "../../types/models";
  * POST   /public/events/:eventId/waitlist              join      → WaitlistEntry (201)
  * GET    /public/events/:eventId/waitlist              mine      → WaitlistEntry[]  (401 if anonymous)
  * GET    /public/events/:eventId/waitlist/:entryId     one       → WaitlistEntry
+ *        …optionally `&claimToken=<64 hex>` — the offer email's credential (2.6b),
+ *        which is the ONLY way an offered fan can read their place on a device
+ *        that never joined and is not signed in. That is the device the email is
+ *        opened on.
  * DELETE /public/events/:eventId/waitlist/:entryId     leave     → { id, status, leftAt }
  * ```
  *
@@ -49,6 +53,22 @@ export type WaitlistOffer = {
   secondsRemaining: number | null;
   /** The instant the offer lapses — the single most important field here. */
   claimExpiresAt: string | null;
+  /**
+   * Are the offered seats actually HELD for this person until the deadline
+   * (events 2.6b)?
+   *
+   * Distinct from `offerOpen`, and the distinction is the whole change. An offer
+   * used to reserve nothing — the fan raced the open page, and the copy said so.
+   * A reserved offer takes a real inventory hold for the length of the window,
+   * so the tier reads sold out to everybody else. Render "these are yours until
+   * Friday" ONLY when this is true; an unreserved offer (one made before the
+   * reservation existed, or one whose hold a failed payment released) is still a
+   * real offer with a real deadline and must keep the older, weaker promise.
+   *
+   * Optional so a site pinned to an older API build degrades to "not reserved"
+   * rather than claiming a hold that is not there.
+   */
+  seatsReserved?: boolean;
 };
 
 export type WaitlistEntry = {
@@ -88,14 +108,26 @@ export const isLiveWaitlistEntry = (entry: Pick<WaitlistEntry, "status">): boole
 // ── Where a join control may be DRAWN ────────────────────────────────────────
 
 /**
- * Seats a buyer can still take, by the same arithmetic the purchase UI uses.
+ * Seats that are not SOLD — the waitlist's question, which is not the purchase
+ * UI's question.
  *
  * Deliberately ignores `held` (units inside somebody else's live checkout) even
  * though the server's waitlist rule subtracts it. The difference only ever makes
  * this stricter: `quantity - sold <= 0` implies `quantity - sold - held <= 0`,
  * so a tier this calls sold out is always one the server will accept a join for.
- * Including `held` would do the opposite — offer a waitlist beside a "+" button
- * the buyer can still press, on a tier that unfreezes minutes later.
+ *
+ * The purchase UI DOES subtract `held` — it has to, because that is what the
+ * server sells on (`ticketSeatsAvailable` in `ui/format/ticketAvailability`).
+ * The two are answering different things and the gap between them is deliberate:
+ *
+ *  - a tier with held-but-unsold seats is un-addable and says "ON HOLD", and
+ *    offers no waitlist, because the seats are coming back;
+ *  - a tier with nothing unsold says "SOLD OUT" and offers the queue.
+ *
+ * Collapsing them would put a "join the waitlist" beside a tier that unfreezes
+ * five minutes later, and send a fan an email about a seat they could have had
+ * by waiting. Identical to `waitlistAvailableSeats` on the server only in shape,
+ * not in intent — that one gates OFFERS, this one gates where a join is drawn.
  */
 export const ticketSeatsRemaining = (ticket: Pick<ITicket, "quantity" | "sold">): number =>
   Math.max(0, (ticket.quantity ?? 0) - (ticket.sold ?? 0));
@@ -334,6 +366,16 @@ export function useEventWaitlistPlaces(eventId?: string, accountId?: string) {
   const { client, profileId } = useForge();
   const mine = useMyEventWaitlist(eventId, accountId);
   const remembered = useRememberedWaitlistEntries(eventId);
+  /**
+   * 2.6b — a THIRD source: the offer the visitor arrived holding.
+   *
+   * The other two both assume continuity with the browser that joined — a
+   * session, or a remembered id in this localStorage. An offer email is read on
+   * a phone, and neither holds there, so the fan landed on an ordinary sold-out
+   * page with a "join the waitlist" form beside the seats already reserved for
+   * them. The token in the link is what makes that place readable.
+   */
+  const claim = useEventWaitlistClaim(eventId);
 
   const entryQueries = useQueries({
     queries: remembered.map((item) => ({
@@ -359,15 +401,21 @@ export function useEventWaitlistPlaces(eventId?: string, accountId?: string) {
       const entry = query.data;
       if (entry && !byId.has(entry.id)) byId.set(entry.id, entry);
     }
+    // Last, and unconditionally: an entry the link addresses is the one the
+    // visitor is here about. `set` rather than a has-check so the token-scoped
+    // read wins if the same row arrived by another route.
+    if (claim.entry) byId.set(claim.entry.id, claim.entry);
     return [...byId.values()];
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [mine.data, entryStamp]);
+  }, [mine.data, entryStamp, claim.entry]);
 
   return {
     entries,
     /** Only the LIVE ones — what "am I on the waitlist?" means to a buyer. */
     liveEntries: useMemo(() => entries.filter(isLiveWaitlistEntry), [entries]),
-    isLoading: mine.isLoading || entryQueries.some((query) => query.isLoading),
+    /** The claim this visitor arrived with, for the surface that spends it. */
+    claim,
+    isLoading: mine.isLoading || claim.isLoading || entryQueries.some((query) => query.isLoading),
   };
 }
 
@@ -427,3 +475,73 @@ export function useMyWaitlistPlaces(accountId?: string) {
     isLoading: eventsLoading || listQueries.some((query) => query.isLoading),
   };
 }
+
+// ── The offer email's claim link (2.6b) ──────────────────────────────────────
+
+/**
+ * The claim credential an offer email hands out.
+ *
+ * The link used to be the ordinary public event page, which proved nothing about
+ * who was holding it — and once the offer started RESERVING seats it could not
+ * even be used, because the reservation makes the tier read sold out to
+ * everybody, the offeree included. The email now carries
+ * `?waitlistEntry=<id>&waitlistClaim=<64 hex>`: the id addresses the place, the
+ * token proves the holder and is what lets the reserved hold be spent.
+ */
+export type WaitlistClaimLink = { entryId: string; token: string };
+
+/** 64 lowercase hex, matching the server's own shape gate. */
+const isWellFormedClaimToken = (value: string | null): value is string =>
+  !!value && /^[0-9a-f]{64}$/.test(value);
+
+/**
+ * Read the claim out of the CURRENT url.
+ *
+ * Deliberately not stored anywhere. It is a bearer credential with a deadline,
+ * and the durable copy is the email; putting it in localStorage would leave a
+ * spendable token on a shared device long after the offer died, for no benefit
+ * — the fan re-opens the email.
+ */
+export const readWaitlistClaimFromUrl = (search?: string): WaitlistClaimLink | null => {
+  const raw = search ?? (typeof window === "undefined" ? "" : window.location.search);
+  if (!raw) return null;
+  const params = new URLSearchParams(raw);
+  const entryId = params.get("waitlistEntry");
+  const token = params.get("waitlistClaim");
+  if (!entryId || !isWellFormedClaimToken(token)) return null;
+  return { entryId, token };
+};
+
+/**
+ * The offer this visitor arrived holding, if they arrived holding one.
+ *
+ * `enabled` on the token means an ordinary visitor makes no request at all. A
+ * dead or foreign token 404s, which is an ANSWER — the offer is over, or the
+ * link belongs to another artist — so it is not retried and the caller simply
+ * renders the ordinary page.
+ */
+export function useEventWaitlistClaim(eventId?: string, search?: string) {
+  const { client, profileId } = useForge();
+  const link = useMemo(() => readWaitlistClaimFromUrl(search), [search]);
+
+  const query = useQuery<WaitlistEntry>({
+    queryKey: [...waitlistKey(eventId), "claim", link?.entryId, profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/events/${eventId}/waitlist/${link!.entryId}`, {
+        params: { profileId, claimToken: link!.token },
+      });
+      return res.data;
+    },
+    enabled: !!eventId && !!profileId && !!client && !!link,
+    retry: false,
+  });
+
+  return {
+    /** The raw token, to be posted with the order that spends the reservation. */
+    token: link?.token ?? null,
+    entry: query.data ?? null,
+    /** True only while the seats are genuinely held and the window is open. */
+    isClaimable: !!query.data?.offer?.offerOpen && !!query.data?.offer?.seatsReserved,
+    isLoading: query.isLoading,
+  };
+}

package/src/data/queries/useEvents.ts

@@ -114,6 +114,22 @@ export type CreateEventOrderInput = {
    * their order refused after entering their card details.
    */
   accessCode?: string;
+  /**
+   * The waitlist offer's claim token (events 2.6b) — 64 hex from the offer
+   * email's link, NOT a discount and NOT a presale code.
+   *
+   * It is a capability over inventory that is ALREADY reserved: the offer took
+   * a real hold when it was made, so presenting this makes the order spend that
+   * hold rather than acquire a new one. Without it an offeree cannot buy at
+   * all, because their own reservation is what makes the tier read sold out to
+   * them.
+   *
+   * The server refuses a claim it cannot honour (closed window, released
+   * reservation, a cart reaching past the offered tier) rather than quietly
+   * falling back to an ordinary purchase — so a refusal here is the truth about
+   * the offer, not a generic sold-out.
+   */
+  waitlistClaimToken?: string;
 };
 
 export type CreateEventOrderResult = {

package/src/data/queries/useMusicLink.ts

@@ -0,0 +1,28 @@
+import type { IMusicLink } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+/**
+ * One music smart link by slug.
+ *
+ * Pass `initialData` from the route loader (`fetchMusicLinkServer`) so the page
+ * renders complete on the server with no client spinner. That is not just a
+ * polish detail here: these links are opened almost entirely from social apps'
+ * in-app browsers on a phone, on the worst connection the fan will use all day,
+ * and a page that shows a spinner before its buttons loses the tap.
+ *
+ * `undefined` while loading, `null` when the link does not exist or is archived.
+ */
+export function useMusicLink(slug?: string, options?: { initialData?: IMusicLink | null }) {
+  const { client, profileId } = useForge();
+
+  return useQuery<IMusicLink | null>({
+    queryKey: ["music-link", profileId, slug],
+    queryFn: async () => {
+      const res = await client.get(`/public/music-links`, { params: { profileId, slug } });
+      return res.data ?? null;
+    },
+    enabled: !!profileId && !!client && !!slug,
+    ...(options?.initialData !== undefined ? { initialData: options.initialData } : {}),
+  });
+}

package/src/data/queries/useMyBookings.ts

@@ -108,6 +108,8 @@ export type MyBooking = {
   coachingProductTimezone: string | null;
   coachingProductDurationMinutes: number | null;
   cancellation: BookingCancellation;
+  /** Already resolved server-side — see {@link BookingLocation}. */
+  location?: BookingLocation | null;
   /** The server's answer. Never recomputed here. */
   canReschedule: boolean;
   rescheduleReason: RescheduleRefusal | null;
@@ -125,6 +127,29 @@ export type MyBooking = {
   calendarWebcalUrl?: string | null;
 };
 
+/**
+ * WHERE the session happens.
+ *
+ * The server has already resolved this — the booking's own override if the
+ * coach set one for this session, otherwise the coaching product's default —
+ * so there is exactly one value and no rule to re-derive in the browser. Two
+ * fields would eventually be rendered in the wrong order by one of the two
+ * rendering stacks, and the consequence of that is not cosmetic: it is a client
+ * dialling into an empty room.
+ *
+ * `null` means the coach has not said where the session is. Draw nothing; the
+ * confirmation email carries the same gap and inventing a placeholder ("Online")
+ * would promise a link that does not exist.
+ *
+ * Withheld for anything not `confirmed`: a cancelled session has no venue to go
+ * to and no call to join.
+ *
+ * Optional on the type because an older API build does not emit it.
+ */
+export type BookingLocation =
+  | { type: "in_person"; address: string }
+  | { type: "online"; url: string };
+
 export type CancelBookingResult = {
   bookingId: string;
   /** True when money actually went back; false for a free or already-refunded session. */

package/src/data/queries/usePaymentFlow.ts

@@ -1,6 +1,12 @@
-import { useEffect, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 import type { PaymentFlowResult, PaymentStartResponse } from "../../types/models";
 import { PaymentProviderName } from "../../types/models";
+import {
+  hasPaystackSession,
+  openPaystackCheckout,
+  type PaystackCheckoutHandlers,
+  type PaystackCheckoutOutcome,
+} from "../../utils/paystackCheckout";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation } from "@tanstack/react-query";
 
@@ -15,42 +21,80 @@ export interface UsePaymentFlowOptions {
   autoStart?: boolean;
   /** Gate auto-start on extra readiness (default true). */
   enabled?: boolean;
-  /** Redirect to the Paystack checkout URL on success (default true). */
+  /**
+   * Handle the Paystack checkout automatically once the charge starts: open the
+   * inline modal, falling back to the hosted page when it cannot open
+   * (default true). `false` means "I will drive it myself": call
+   * `openPaystackCheckout()` from a button.
+   *
+   * The name is historical (it used to mean "redirect to the hosted page") and
+   * is deliberately kept: renaming it would break compiling sites for no gain.
+   */
   paystackRedirect?: boolean;
+  /**
+   * Paystack modal callbacks. Omit `onPaystackSuccess` to keep the redirect
+   * leg's behaviour, which is to navigate to `returnUrl`, and that is what leaves
+   * every finalise page unchanged.
+   */
+  onPaystackSuccess?: PaystackCheckoutHandlers["onSuccess"];
+  /** The fan closed the modal. NOT a failure, so leave them able to retry. */
+  onPaystackDismiss?: PaystackCheckoutHandlers["onDismiss"];
+  onPaystackError?: PaystackCheckoutHandlers["onError"];
 }
 
 /**
  * Starts a payment against any `/public/<domain>/.../start-payment` endpoint and
  * normalizes the result: resolves the provider (the field is named differently
- * per domain) and, for Paystack, redirects to the hosted checkout. The Stripe
- * UI (Elements + confirm) stays in the app — this hook only owns the data.
+ * per domain) and, for Paystack, opens the inline checkout modal so the fan
+ * pays without leaving the creator's site. The Stripe UI (Elements + confirm)
+ * stays in the app; this hook only owns the data.
  */
 export function usePaymentFlow(opts: UsePaymentFlowOptions) {
   const { client, profileId } = useForge();
   const { path, body, returnUrl, autoStart = true, enabled = true, paystackRedirect = true } = opts;
   const startedRef = useRef(false);
 
+  // Callbacks are read through a ref so a caller passing inline arrows does not
+  // re-trigger the auto-open effect on every render.
+  const handlersRef = useRef<PaystackCheckoutHandlers>({});
+  handlersRef.current = {
+    onSuccess: opts.onPaystackSuccess,
+    onDismiss: opts.onPaystackDismiss,
+    onError: opts.onPaystackError,
+  };
+
   const mutation = useMutation<PaymentFlowResult, unknown, Record<string, unknown> | undefined>({
     mutationFn: async (override) => {
       // override wins — click-driven flows pass a just-created orderId/returnUrl.
       const res = await client.post(path as string, { ...body, profileId, returnUrl, ...(override ?? {}) });
       const data = res.data as PaymentStartResponse;
       const provider = (data.paymentProvider ?? data.paymentProviderName) as PaymentProviderName | undefined;
-
-      if (
-        paystackRedirect &&
-        provider === PaymentProviderName.Paystack &&
-        data.paymentSecret &&
-        typeof window !== "undefined"
-      ) {
-        window.location.href = data.paymentSecret;
-      }
-
       return { ...data, provider };
     },
   });
 
   const { mutate, mutateAsync } = mutation;
+  const result = mutation.data ?? null;
+  const isPaystack = result?.provider === PaymentProviderName.Paystack;
+
+  const session = useMemo(
+    () => ({ accessCode: result?.accessCode, checkoutUrl: result?.checkoutUrl, returnUrl }),
+    [result?.accessCode, result?.checkoutUrl, returnUrl],
+  );
+
+  /**
+   * Open the Paystack modal for the charge that has already been started.
+   * Safe to call again after a dismissal: the access code still opens the same
+   * session, which is what makes "closed it by accident" recoverable.
+   */
+  const openPaystack = useCallback(async (): Promise<PaystackCheckoutOutcome> => {
+    if (!hasPaystackSession(session)) return "unavailable";
+    return openPaystackCheckout(session, {
+      onSuccess: handlersRef.current.onSuccess,
+      onDismiss: handlersRef.current.onDismiss,
+      onError: handlersRef.current.onError,
+    });
+  }, [session]);
 
   useEffect(() => {
     if (autoStart && enabled && path && returnUrl && profileId && !startedRef.current) {
@@ -60,11 +104,32 @@ export function usePaymentFlow(opts: UsePaymentFlowOptions) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [autoStart, enabled, path, returnUrl, profileId]);
 
+  // Auto-open, once per started charge. Keyed on the charge rather than a bare
+  // boolean so a coupon that re-mints the session opens the NEW one, and a fan
+  // who dismissed the modal is not immediately re-interrupted by it.
+  const autoOpenedRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!paystackRedirect || !isPaystack) return;
+    const key = result?.paymentId || result?.accessCode;
+    if (!key || autoOpenedRef.current === key) return;
+    autoOpenedRef.current = key;
+    void openPaystack();
+  }, [paystackRedirect, isPaystack, result?.paymentId, result?.accessCode, openPaystack]);
+
   return {
-    result: mutation.data ?? null,
-    clientSecret: mutation.data?.paymentSecret,
-    paymentId: mutation.data?.paymentId,
-    provider: mutation.data?.provider,
+    result,
+    /** STRIPE: the PaymentIntent client secret. Undefined on Paystack. */
+    clientSecret: result?.paymentSecret,
+    paymentId: result?.paymentId,
+    provider: result?.provider,
+    /** PAYSTACK: the inline checkout session. Undefined on Stripe. */
+    accessCode: result?.accessCode,
+    /** PAYSTACK: the hosted page used only when the modal cannot open. */
+    checkoutUrl: result?.checkoutUrl,
+    isPaystack,
+    /** True once there is a Paystack session a pay button can open. */
+    canOpenPaystack: hasPaystackSession(session),
+    openPaystackCheckout: openPaystack,
     isStarting: mutation.isPending,
     error: mutation.error,
     /**
@@ -86,6 +151,7 @@ export function usePaymentFlow(opts: UsePaymentFlowOptions) {
      */
     reset: () => {
       startedRef.current = false;
+      autoOpenedRef.current = null;
       mutation.reset();
     },
   };

package/src/data/queries/useShipping.ts

@@ -82,7 +82,12 @@ export type ApplyCouponResult = {
   discountAmount: number;
   chargedAmount: number;
   chargedCurrency: string;
+  /** STRIPE: the re-issued PaymentIntent client secret. */
   paymentSecret?: string;
+  /** PAYSTACK: the re-issued inline-checkout session. */
+  accessCode?: string;
+  /** PAYSTACK: the hosted page for the re-issued session (runtime fallback). */
+  checkoutUrl?: string;
   paymentId?: string;
   /** Re-quoted sales tax for the re-issued payment intent (display only). */
   taxQuote?: import("../../types/models").PublicTaxQuote;