@tribe-nest/forge 3.21.0 → 3.23.0

package/src/ui/headless/event/useEventCheckout.ts

@@ -1,11 +1,25 @@
 import { useMemo, useState } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
 import { useCart } from "../../../contexts/CartContext";
-import { useEvent, useCreateEventOrder } from "../../../data/queries/useEvents";
+import { useCreateEventOrder } from "../../../data/queries/useEvents";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
 import { useCouponField } from "../coupon/useCouponField";
+import { usePresaleCode } from "./usePresaleCode";
+import { useEventWaitlistClaim } from "../../../data/queries/useEventWaitlist";
+import {
+  buildAttendeeSlots,
+  setAttendeeName,
+  validateAttendeeNames,
+  attendeesPayload,
+  collectsAttendees,
+  buyerFullName,
+  type AttendeeNames,
+} from "../../format/attendees";
+import { holdExpiredMessage, isHoldExpiredError } from "../checkout/inventoryHold";
+import { useInventoryHold } from "../checkout/useInventoryHold";
 import { computeBookingFeeAmount } from "../../format/bookingFee";
 import { isPayWhatYouWant, pwywDefaultAmount, resolveUnitPrice, ticketSubtotals } from "../../format/pwyw";
+import { parseMembershipGateError, type MembershipGateRefusal } from "../../format/membershipGate";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 
@@ -36,9 +50,40 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
   const { setTickets, hasTicketsFor } = useCart();
   // The detail is resolved by slug; the order is created against the real event
   // id (the orders endpoint looks the event up by id, not slug).
-  const { data: event, isLoading } = useEvent(slug);
+  // Read THROUGH the presale field rather than calling `useEvent` directly: it
+  // is the same React Query entry, but it is the one fetched with whatever
+  // presale code this buyer has applied, so `event.tickets` already contains the
+  // tiers that code unlocked. Calling `useEvent(slug)` here instead would give a
+  // tier list that silently omits what the buyer just unlocked access to.
+  const presale = usePresaleCode(slug);
+  const { event, isLoading } = presale;
   const eventId = event?.id;
   const createOrder = useCreateEventOrder(eventId);
+  /**
+   * Events 2.6b — the waitlist offer this visitor arrived holding, if any.
+   *
+   * Read here rather than passed in because the whole flow needs it: the tier
+   * the offer covers must be ADDABLE (the offeree's own reservation is what
+   * makes it read sold out), and the order must carry the token that spends the
+   * reservation instead of trying to take a new one. Null for every ordinary
+   * visitor, and no request is made for them.
+   */
+  const waitlistClaim = useEventWaitlistClaim(eventId);
+  /**
+   * Seats of `held` that belong to THIS visitor, by tier.
+   *
+   * Handed to `maxAddableTickets` / `ticketSeatState` so the picker lets the
+   * offeree add exactly what was reserved for them and not one seat more. The
+   * server re-derives the same number from the hold it issued, so a tampered
+   * value buys nothing.
+   */
+  const reservedForYou = useMemo<Record<string, number>>(
+    () =>
+      waitlistClaim.isClaimable && waitlistClaim.entry
+        ? { [waitlistClaim.entry.eventTicketId]: waitlistClaim.entry.quantity }
+        : {},
+    [waitlistClaim.isClaimable, waitlistClaim.entry],
+  );
   const flow = usePaymentFlow({ path: `/public/events/${eventId}/start-payment`, autoStart: false });
 
   const [step, setStep] = useState<EventCheckoutStep>("tickets");
@@ -53,8 +98,31 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
   const [lastName, setLastName] = useState(user?.lastName ?? "");
   const [email, setEmail] = useState(user?.email ?? "");
   const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
+  /**
+   * ticketId → per-seat names, positional.
+   *
+   * `collectAttendeeDetails` is an event setting an artist turns on for a
+   * guest-list show. It shipped with an admin toggle, a backend that accepts a
+   * per-ticket attendees map, and NO storefront asking for anything — so every
+   * pass printed the buyer's name and the door list was wrong, with nothing
+   * explaining why the setting did nothing. Both stacks render this component,
+   * so collecting it here is what makes the toggle real.
+   */
+  const [attendeeNames, setAttendeeNames] = useState<AttendeeNames>({});
   const [returnUrl, setReturnUrl] = useState("");
   const [error, setError] = useState<string | null>(null);
+  /**
+   * A `MEMBERSHIP_GATE` refusal, STRUCTURED — which tier, and whether the buyer
+   * needs to sign in or to join.
+   *
+   * The gate should have been visible on the tier long before this (the read
+   * announces it), so reaching here means either the buyer's membership lapsed
+   * mid-checkout or the page rendered from a stale cache. Either way the useful
+   * response is the badge's: name the tier and offer the way in. Kept as state
+   * rather than a message because a sentence alone turns a silent failure into a
+   * visible dead end.
+   */
+  const [gateRefusal, setGateRefusal] = useState<MembershipGateRefusal | null>(null);
   /**
    * The booking fee the SERVER charged, once an order exists.
    *
@@ -232,11 +300,32 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
 
   const continueToPayment = async () => {
     setError(null);
+    setGateRefusal(null);
     if (!slug || !eventId) return;
     if (!firstName.trim() || !lastName.trim() || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
       setError("Please enter your name and a valid email.");
       return;
     }
+    /**
+     * Spend the reservation only when this order IS the claim.
+     *
+     * The offered tier, alone in the cart, at no more than the offered
+     * quantity — the same shape `resolveWaitlistClaim` accepts. Checking it
+     * here rather than sending the token blindly means a fan who adds a second
+     * tier gets an ordinary (and possibly successful) purchase instead of a
+     * claim rejection, which is the friendlier of the two truths.
+     */
+    const claimedTierId = waitlistClaim.entry?.eventTicketId;
+    const cartTiers = Object.keys(selectedTickets).filter((id) => (selectedTickets[id] ?? 0) > 0);
+    const waitlistClaimToken =
+      waitlistClaim.isClaimable &&
+      claimedTierId &&
+      cartTiers.length === 1 &&
+      cartTiers[0] === claimedTierId &&
+      (selectedTickets[claimedTierId] ?? 0) <= (waitlistClaim.entry?.quantity ?? 0)
+        ? waitlistClaim.token
+        : null;
+
     try {
       const data = await createOrder.mutateAsync({
         items: selectedTickets,
@@ -247,7 +336,27 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
         firstName,
         lastName,
         questionnaire,
+        // Omitted entirely when the event does not collect them, so an ordinary
+        // purchase posts the body it always did.
+        ...(attendeesPayload(attendeeSlots) ? { attendees: attendeesPayload(attendeeSlots) } : {}),
         couponCode: coupon.submittedCode,
+        // The presale code, not a discount. The sell guard re-checks it on the
+        // ORDER, so it has to travel with the purchase and not just with the
+        // read that revealed the tier — otherwise a buyer unlocks a presale,
+        // fills in their details, and is refused at the card step for want of
+        // the code they already typed. Omitted when there is none, so an
+        // ordinary purchase posts the body it always did.
+        ...(presale.code ? { accessCode: presale.code } : {}),
+        /**
+         * The waitlist claim (2.6b). Sent ONLY when the cart is exactly the
+         * offered tier: the server refuses a claim whose cart reaches past it,
+         * and sending one anyway would turn "you also added a T-shirt tier"
+         * into a claim failure rather than an ordinary purchase.
+         *
+         * Omitted entirely otherwise, so an ordinary purchase posts the body it
+         * always did.
+         */
+        ...(waitlistClaimToken ? { waitlistClaimToken } : {}),
         attributionRefId: readAttributionRef() ?? undefined,
         ...(readLanding() ?? {}),
       });
@@ -279,10 +388,36 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       if (result.provider && result.provider !== "stripe") return; // Paystack redirected
       setStep("payment");
     } catch (e) {
+      /**
+       * A members-only tier the buyer cannot have. Checked BEFORE the coupon
+       * branch: a buyer who happened to type a discount code would otherwise be
+       * told the CODE was refused and sent to fix a code that was never the
+       * problem.
+       */
+      const gate = parseMembershipGateError(e);
+      if (gate) {
+        setGateRefusal(gate);
+        return;
+      }
       // A refused code fails the whole request, so with one entered the message
       // belongs next to the field the buyer just used. The message is the API's
       // own — "This coupon has expired", "…does not reach this coupon's minimum
       // spend" — never a house "invalid code" that hides which it was.
+      /**
+       * The reservation lapsed mid-payment (409 `INVENTORY_HOLD_EXPIRED`) —
+       * NOT sold out, and emphatically not a bad coupon. Checked before the
+       * coupon branch for the same reason the gate is: a buyer who happened to
+       * type a discount code would otherwise be sent to fix a code that was
+       * never the problem, while the one action that works — retry — is not
+       * offered at all.
+       *
+       * Event ticket holds are taken UNCONDITIONALLY (no feature switch), so
+       * unlike the product cart this path is live for every profile.
+       */
+      if (isHoldExpiredError(e)) {
+        setError(holdExpiredMessage(e, "Your ticket reservation expired before payment finished. Please try again."));
+        return;
+      }
       if (coupon.submittedCode) coupon.fail(e);
       else setError(errMessage(e));
     }
@@ -306,9 +441,47 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     setStep("details");
   };
 
+  /**
+   * One slot per seat, in cart order, with the buyer pre-filled into the first.
+   * Empty when the event does not ask — so a normal event renders and posts
+   * exactly what it always did.
+   */
+  /**
+   * The reservation clock. `undefined` on an older API and `null` when no hold
+   * was taken or the order is already paid — both render nothing, i.e. exactly
+   * the behaviour before holds existed.
+   */
+  const holdExpiresAt = (flow.result as { holdExpiresAt?: string | null } | undefined)?.holdExpiresAt ?? null;
+  const hold = useInventoryHold(holdExpiresAt);
+
+  const attendeeSlots = useMemo(
+    () =>
+      collectsAttendees(event)
+        ? buildAttendeeSlots({
+            tickets: (event?.tickets ?? []).filter((t) => (selectedTickets[t.id] ?? 0) > 0),
+            quantities: selectedTickets,
+            names: attendeeNames,
+            buyerName: buyerFullName({ firstName, lastName }),
+          })
+        : [],
+    [event, selectedTickets, attendeeNames, firstName, lastName],
+  );
+
+  const attendeeCheck = useMemo(() => validateAttendeeNames(attendeeSlots), [attendeeSlots]);
+
+  const setAttendee = (ticketId: string, index: number, value: string) =>
+    setAttendeeNames((prev) => setAttendeeName(prev, ticketId, index, value));
+
   return {
     event,
     isLoading,
+    /** Countdown on the ticket reservation. `active:false` when there is none. */
+    hold,
+    /** Per-seat name inputs. Empty array when the event does not collect them. */
+    attendeeSlots,
+    setAttendee,
+    /** `{ok:false}` while a required seat name is missing or too long. */
+    attendeeCheck,
     step,
     setStep,
     selectedTickets,
@@ -354,6 +527,22 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     /** Discount code state + the server's quote. See `useCouponField`. */
     coupon,
     clearCoupon,
+    /**
+     * Presale-code state (1.2) — a DIFFERENT code from `coupon`: it buys access
+     * to a tier, it does not change a price. `presale.visible` is false on every
+     * event without a coded tier, so a surface can render it unconditionally.
+     */
+    presale,
+    /**
+     * Events 2.6b — the waitlist offer this visitor arrived holding.
+     *
+     * `reservedForYou` is the per-tier seat count a surface must pass to
+     * `maxAddableTickets` / `ticketSeatState`, or the offeree cannot add the
+     * seat that is being held for them. `waitlistClaim.isClaimable` is what a
+     * surface renders "your tickets are reserved until…" off.
+     */
+    waitlistClaim,
+    reservedForYou,
     /** Authoritative sales-tax quote from start-payment (display only). */
     taxQuote: flow.result?.taxQuote ?? null,
     firstName,
@@ -370,8 +559,20 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     ticketsInCart: event ? hasTicketsFor(event.id) : false,
     continueToPayment,
     clientSecret: flow.clientSecret,
+    /** Paystack: the started inline-checkout session and the way back into it. */
+    isPaystack: flow.isPaystack,
+    canOpenPaystack: flow.canOpenPaystack,
+    openPaystackCheckout: flow.openPaystackCheckout,
     returnUrl,
     isProcessing: createOrder.isPending || flow.isStarting,
     error,
+    /**
+     * A `MEMBERSHIP_GATE` refusal, structured — pass it to
+     * `<MembershipGateNotice refusal={…}>` (or `useMembershipGateNotice`) rather
+     * than printing `error`, which is deliberately NOT set for this case: the
+     * buyer needs the tier's name and a way in, and a generic red line gives
+     * them neither.
+     */
+    gateRefusal,
   };
 }

package/src/ui/headless/event/usePresaleCode.ts

@@ -0,0 +1,181 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import type { IEvent } from "../../../types/models";
+import { useEvent } from "../../../data/queries/useEvents";
+import {
+  readPresaleCode,
+  readPresaleCodeFromUrl,
+  subscribePresaleCode,
+  writePresaleCode,
+} from "../../../utils/presaleCode";
+
+export type PresaleCodeStatus = "idle" | "checking" | "accepted" | "rejected";
+
+export interface UsePresaleCodeOptions {
+  /**
+   * The event as a route loader already fetched it (uncoded). Seeds the read so
+   * a server-rendered page paints without a spinner, exactly as
+   * `useEvent`'s own `initialData` does.
+   */
+  initialEvent?: IEvent;
+}
+
+export interface PresaleCodeField {
+  /**
+   * The event AS THIS BUYER MAY SEE IT — refetched with the applied code, so
+   * `tickets` already contains whatever that code unlocked.
+   *
+   * Read this rather than calling `useEvent` separately; both resolve to the
+   * same React Query entry, but only this one is guaranteed to be the coded
+   * read.
+   */
+  event?: IEvent;
+  isLoading: boolean;
+  /**
+   * Render a code box at all?
+   *
+   * FALSE for every event with no presale — which is nearly all of them, and
+   * the reason this is a server fact rather than "always show it". A box on an
+   * event with no coded tier sends the buyer hunting for a code that does not
+   * exist.
+   */
+  visible: boolean;
+  /** The text in the input — the applied code until the buyer edits it. */
+  input: string;
+  setInput: (value: string) => void;
+  /**
+   * The code currently APPLIED: what the event above was fetched with, and what
+   * the order must carry. `null` until one is submitted.
+   */
+  code: string | null;
+  status: PresaleCodeStatus;
+  /**
+   * The message to put under the field, or `null` for none.
+   *
+   * A refusal names no tier and confirms no guess: the buyer learns their code
+   * is not one for this event and nothing else, or the box becomes a way to
+   * enumerate codes.
+   */
+  message: string | null;
+  /** Apply what is in the input. No-op on an empty field. */
+  submit: () => void;
+  /** Drop the applied code — re-hides whatever it revealed. */
+  clear: () => void;
+  /** Whether the applied code opened something. */
+  isUnlocked: boolean;
+}
+
+/**
+ * The presale-code entry on an event page (Events 1.2).
+ *
+ * ## The gap this closes
+ *
+ * 1.2 shipped hidden tiers, an access-code column, SQL that reveals a tier to
+ * the right code, and a sell guard that enforces it at checkout — and no
+ * storefront on either rendering stack had an input. An artist could author a
+ * presale and mail the code to their list, and the recipient had nowhere to put
+ * it. The feature was unreachable by the only person it is for.
+ *
+ * ## Two facts, both of which have to come from the server
+ *
+ * `presale.hasCodedTiers` decides whether the box exists. A client cannot work
+ * it out: a hidden tier is filtered out of the response, so a presale-only
+ * event is indistinguishable from an event with no tickets yet.
+ *
+ * `presale.codeAccepted` decides what the box SAYS. Diffing the tier list
+ * before and after would look like it works and then fail on the case that
+ * matters — a tier that is VISIBLE but code-gated is already listed, so the
+ * correct code changes nothing on screen and the diff would call it wrong.
+ *
+ * ## Persistence
+ *
+ * The applied code is stored per event in `sessionStorage` (see
+ * `utils/presaleCode`), so it survives the reload, the payment redirect and the
+ * back button, and so the page and the ticket modal — separate components each
+ * with their own `useEvent` — always agree on it. Without that, a buyer unlocks
+ * a tier, walks to checkout, and the order is refused for want of the code they
+ * already typed. `?accessCode=` on the URL seeds it once, which is what makes a
+ * mailed presale link work on arrival.
+ *
+ * ```tsx
+ * const presale = usePresaleCode(slug);
+ * // presale.event already has the unlocked tiers in it
+ * ```
+ */
+export function usePresaleCode(eventKey?: string, options: UsePresaleCodeOptions = {}): PresaleCodeField {
+  const key = eventKey ?? "";
+
+  const code = useSyncExternalStore(
+    subscribePresaleCode,
+    () => readPresaleCode(key),
+    // Server render: no storage, so nothing is applied. The first client render
+    // picks up a stored code and refetches with it.
+    () => null,
+  );
+
+  /** `null` = untouched, so the field shows the applied code until it is edited. */
+  const [draft, setDraft] = useState<string | null>(null);
+
+  // A mailed presale link lands with the code already on it. Seeded once, and
+  // never over an applied code — a buyer who cleared one did so on purpose.
+  useEffect(() => {
+    if (!key || readPresaleCode(key)) return;
+    const fromUrl = readPresaleCodeFromUrl();
+    if (fromUrl) writePresaleCode(key, fromUrl);
+  }, [key]);
+
+  const { data: event, isLoading, isFetching } = useEvent(eventKey, {
+    accessCode: code,
+    initialData: options.initialEvent,
+  });
+
+  const presale = event?.presale;
+
+  // While a newly applied code is in flight the event on hand is still the
+  // PREVIOUS response (kept deliberately, so the page does not blank), and its
+  // verdict describes the old code. Reporting it would flash "not valid" at a
+  // buyer whose code is about to be accepted.
+  //
+  // `!presale` is an API that does not report presale state at all (an older
+  // deployment, or the list endpoint's shape). Silence, not a spinner that
+  // never resolves.
+  const status: PresaleCodeStatus = !code || !presale
+    ? "idle"
+    : isFetching || presale.codeAccepted === null
+      ? "checking"
+      : presale.codeAccepted
+        ? "accepted"
+        : "rejected";
+
+  const submit = useCallback(() => {
+    const trimmed = (draft ?? "").trim();
+    if (!trimmed || !key) return;
+    writePresaleCode(key, trimmed);
+  }, [draft, key]);
+
+  const clear = useCallback(() => {
+    if (!key) return;
+    setDraft("");
+    writePresaleCode(key, null);
+  }, [key]);
+
+  return {
+    event,
+    isLoading,
+    visible: !!presale?.hasCodedTiers,
+    input: draft ?? code ?? "",
+    setInput: setDraft,
+    code,
+    status,
+    message:
+      status === "accepted"
+        ? "Code applied."
+        : // Says only that the code is not one for this event. Naming a tier, or
+          // hinting that one exists, would turn the box into a way to guess codes.
+          status === "rejected"
+          ? "That code isn't valid for this event."
+          : null,
+    submit,
+    clear,
+    isUnlocked: status === "accepted",
+  };
+}

package/src/ui/headless/index.ts

@@ -4,6 +4,11 @@ export * from "./dialog";
 export * from "./donation";
 export * from "./offer";
 export { MembershipGate, type MembershipGateProps, type MembershipGateState } from "./membership/MembershipGate";
+// S.4 members-only gates: the notice a storefront draws BEFORE the buyer pays.
+export {
+  useMembershipGateNotice,
+  type UseMembershipGateNoticeInput,
+} from "./membership/useMembershipGateNotice";
 export { useEmailListForm, type UseEmailListFormOptions, type FormStatus } from "./forms/useEmailListForm";
 export { useContactForm } from "./forms/useContactForm";
 export { useSectionedForm } from "./forms/useSectionedForm";
@@ -17,12 +22,32 @@ export {
   type CheckoutShippingData,
   type SelectedShippingRate,
 } from "./checkout/useCheckout";
+// Inventory holds — the reservation a buyer is given while they pay, and the
+// 409 they get when it lapses. Shared by both rendering stacks.
+export {
+  useInventoryHold,
+  type InventoryHoldState,
+  type UseInventoryHoldOptions,
+} from "./checkout/useInventoryHold";
+export {
+  isHoldExpiredError,
+  holdExpiredMessage,
+  holdMsRemaining,
+  formatHoldRemaining,
+  HOLD_EXPIRED_CODE,
+} from "./checkout/inventoryHold";
 export { useLoginFlow, type LoginStep } from "./auth/useLoginFlow";
 export { useSignupForm, type UseSignupFormOptions } from "./auth/useSignupForm";
 
 // Flow primitives (Part A2) — multi-step purchase/booking/subscribe/chat flows,
 // each composed from the data hooks so a creator can rebuild any page.
 export { useEventCheckout, type UseEventCheckoutOptions, type EventCheckoutStep } from "./event/useEventCheckout";
+export {
+  usePresaleCode,
+  type PresaleCodeField,
+  type PresaleCodeStatus,
+  type UsePresaleCodeOptions,
+} from "./event/usePresaleCode";
 export {
   useCouponField,
   apiErrorMessage,

package/src/ui/headless/invoice/useInvoicePayment.ts

@@ -11,8 +11,9 @@ export interface UseInvoicePaymentOptions {
 /**
  * Headless invoice payment: loads the invoice, starts its payment, and exposes
  * the PDF download. Composes `useInvoice`, `useDownloadInvoicePdf`,
- * `usePaymentFlow`. Stripe UI renders from `clientSecret`; finalize on the
- * return page with `useInvoiceFinalize`.
+ * `usePaymentFlow`. Stripe UI renders from `clientSecret`; Paystack opens its
+ * inline modal (and `openPaystackCheckout` re-opens it after a dismissal).
+ * Finalize on the return page with `useInvoiceFinalize`.
  */
 export function useInvoicePayment(invoiceId?: string, opts: UseInvoicePaymentOptions = {}) {
   const invoice = useInvoice(invoiceId);
@@ -35,6 +36,10 @@ export function useInvoicePayment(invoiceId?: string, opts: UseInvoicePaymentOpt
     clientSecret: flow.clientSecret,
     paymentId: flow.paymentId,
     provider: flow.provider,
+    /** Paystack: the started inline-checkout session and the way back into it. */
+    isPaystack: flow.isPaystack,
+    canOpenPaystack: flow.canOpenPaystack,
+    openPaystackCheckout: flow.openPaystackCheckout,
     /** Sales-tax quote (built from the invoice's own tax columns — no re-quote). */
     taxQuote: flow.result?.taxQuote ?? null,
     isStarting: flow.isStarting,

package/src/ui/headless/membership/useMembershipCheckout.ts

@@ -8,6 +8,12 @@ import {
 } from "../../../data/queries/useSubscriptions";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
+import {
+  hasPaystackSession,
+  openPaystackCheckout as openPaystackModal,
+  type PaystackCheckoutOutcome,
+  type PaystackCheckoutSession,
+} from "../../../utils/paystackCheckout";
 
 export type MembershipCheckoutStep = "select" | "payment";
 export type BillingCycle = "month" | "year";
@@ -15,7 +21,7 @@ export type BillingCycle = "month" | "year";
 export interface UseMembershipCheckoutOptions {
   /** Pre-select a tier (e.g. from a `?membershipTierId=` param). */
   initialTierId?: string;
-  /** Where Stripe returns the member after a paid subscription. Default `/i/account?tab=membership&confirmSubscription=true`. */
+  /** Where the provider returns the member after a paid subscription. Default `/i/account?tab=membership&confirmSubscription=true`. */
   returnPath?: string;
   /** Where free activations land. Default `/i/account?tab=membership`. */
   freeReturnPath?: string;
@@ -35,6 +41,11 @@ const tierIsFree = (tier: { payWhatYouWant: boolean; priceMonthly?: number; pric
  * subscription. Composes `useGetMembershipTiers`, `useCreateFreeSubscription`,
  * `useCreateSubscription`, and (for the return page) `useConfirmLatestSubscription`.
  * Paid flow exposes `clientSecret` for `ForgePaymentProvider`.
+ *
+ * Three outcomes, not two: a member who ALREADY subscribes to this artist is
+ * changing tier, which the server settles by proration on their existing
+ * subscription. That completes server-side with no payment step — it is
+ * finished the moment `subscribe()` resolves, exactly like a free activation.
  */
 export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const { user } = usePublicAuth();
@@ -48,6 +59,8 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const [billingCycle, setBillingCycle] = useState<BillingCycle>("month");
   const [customAmount, setCustomAmount] = useState<number>(0);
   const [clientSecret, setClientSecret] = useState<string | undefined>();
+  /** The started Paystack checkout, kept so the modal can be re-opened. */
+  const [paystackSession, setPaystackSession] = useState<PaystackCheckoutSession | null>(null);
   const [error, setError] = useState<string | null>(null);
 
   const selectedTier = useMemo(
@@ -72,6 +85,7 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
       return;
     }
     const origin = typeof window !== "undefined" ? window.location.origin : "";
+    const returnUrl = `${origin}${opts.returnPath ?? "/i/account?tab=membership&confirmSubscription=true"}`;
     const attributionRefId = readAttributionRef() ?? undefined;
     const landing = readLanding() ?? {};
     try {
@@ -87,10 +101,46 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
         amount,
         billingCycle,
         membershipTierId: selectedTier.id,
-        returnUrl: `${origin}${opts.returnPath ?? "/i/account?tab=membership&confirmSubscription=true"}`,
+        returnUrl,
         attributionRefId,
         ...landing,
       });
+
+      // A member who already subscribes is CHANGING TIER: the server moved their
+      // existing subscription onto the new price with proration, so there is
+      // nothing to pay and no card to collect. Sending them to a payment step
+      // with no client secret is a form that can never be completed.
+      // Every provider session counts, not just Stripe's secret. Reading a
+      // missing `clientSecret` as "nothing to pay" would activate a Paystack
+      // membership nobody has paid for.
+      const requiresPayment = data.requiresPayment ?? !!(data.clientSecret || data.accessCode || data.checkoutUrl);
+      if (!requiresPayment) {
+        if (opts.onComplete) opts.onComplete();
+        else if (typeof window !== "undefined") {
+          window.location.href = `${origin}${opts.freeReturnPath ?? "/i/account?tab=membership"}`;
+        }
+        return;
+      }
+
+      if (data.accessCode || data.checkoutUrl) {
+        // Paystack: the fan pays in a modal over this page. The helper navigates
+        // to `returnUrl` on success, the same return leg the hosted redirect
+        // used, so `confirmLatest` still reconciles on arrival.
+        const session: PaystackCheckoutSession = {
+          accessCode: data.accessCode,
+          checkoutUrl: data.checkoutUrl,
+          returnUrl,
+        };
+        setPaystackSession(session);
+        setStep("payment");
+        void openPaystackModal(session, {
+          // Closing the popup leaves the subscription unpaid and re-openable.
+          onDismiss: () => {},
+          onError: (message) => setError(message ?? "The payment could not be completed. Please try again."),
+        });
+        return;
+      }
+
       setClientSecret(data.clientSecret);
       setStep("payment");
     } catch (e) {
@@ -113,6 +163,17 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     amount,
     subscribe,
     clientSecret,
+    /** True once the subscription started on Paystack rather than Stripe. */
+    isPaystack: !!paystackSession,
+    canOpenPaystack: hasPaystackSession(paystackSession),
+    /** Re-open the Paystack modal on the same subscription charge. */
+    openPaystackCheckout: (): Promise<PaystackCheckoutOutcome> =>
+      paystackSession
+        ? openPaystackModal(paystackSession, {
+            onDismiss: () => {},
+            onError: (message) => setError(message ?? "The payment could not be completed. Please try again."),
+          })
+        : Promise.resolve("unavailable" as PaystackCheckoutOutcome),
     isProcessing: createPaid.isPending || createFree.isPending,
     error,
     /** Call on the return page to reconcile the latest subscription. */