@tribe-nest/forge 3.22.0 → 3.24.0

package/src/ui/headless/checkout/useCheckout.ts

@@ -11,6 +11,7 @@ import {
   type ShippingCountry,
 } from "../../../data/queries/useShipping";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { hasPaystackSession, openPaystackCheckout as openPaystackModal } from "../../../utils/paystackCheckout";
 import {
   useCreateCheckout,
   useApplyCheckoutCoupon,
@@ -68,8 +69,17 @@ interface AppliedCoupon {
   discountAmount?: number;
 }
 
+/**
+ * The charge the payment stage is currently pointed at.
+ *
+ * Exactly one provider session is populated: `paymentSecret` on Stripe,
+ * `accessCode` + `checkoutUrl` on Paystack. Nothing here may assume a secret is
+ * present. A Paystack charge has never had one.
+ */
 interface CouponPaymentUpdate {
-  paymentSecret: string;
+  paymentSecret?: string;
+  accessCode?: string;
+  checkoutUrl?: string;
   paymentId: string;
   chargedAmount: number;
   chargedCurrency: string;
@@ -287,6 +297,11 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     body: checkoutId ? { checkoutId } : { orderId: created?.orderId },
     returnUrl,
     enabled: !!checkoutId || !!created?.orderId,
+    // The cart is the one surface where the buyer is looking at a summary they
+    // may still want to change (a discount code, a shipping rate). Opening the
+    // Paystack modal over it the instant the intent lands would cover that up,
+    // so the pay button drives it here, via `openPaystackCheckout` below.
+    paystackRedirect: false,
   });
 
   const orderId = created?.orderId ?? null;
@@ -351,12 +366,19 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     // `checkoutId` as well as `created`: a BUNDLE has no `created` order, and
     // gating on that alone left a bundle buyer with no payment element at all
     // unless a coupon happened to re-mint one.
-    if ((created || checkoutId) && flow.result?.paymentSecret && flow.result?.paymentId) {
+    const started = flow.result;
+    // Stripe answers with a secret, Paystack with a session. Either one means
+    // there is a charge to pay. Gating on the secret alone left every Paystack
+    // buyer with no payment step at all.
+    const hasSession = !!(started?.paymentSecret || started?.accessCode || started?.checkoutUrl);
+    if ((created || checkoutId) && started && hasSession && started.paymentId) {
       return {
-        paymentSecret: flow.result.paymentSecret,
-        paymentId: flow.result.paymentId,
-        chargedAmount: flow.result.amount ?? 0,
-        chargedCurrency: flow.result.currency ?? "",
+        paymentSecret: started.paymentSecret,
+        accessCode: started.accessCode,
+        checkoutUrl: started.checkoutUrl,
+        paymentId: started.paymentId,
+        chargedAmount: started.amount ?? 0,
+        chargedCurrency: started.currency ?? "",
       };
     }
     return null;
@@ -496,9 +518,11 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
       setChargedTotal({ amount: data.chargedAmount, currency: data.chargedCurrency });
       setCouponTaxQuote(data.taxQuote ?? null);
       setCouponPaymentUpdate(
-        data.paymentSecret && data.paymentId
+        (data.paymentSecret || data.accessCode || data.checkoutUrl) && data.paymentId
           ? {
               paymentSecret: data.paymentSecret,
+              accessCode: data.accessCode,
+              checkoutUrl: data.checkoutUrl,
               paymentId: data.paymentId,
               chargedAmount: data.chargedAmount,
               chargedCurrency: data.chargedCurrency,
@@ -553,9 +577,11 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
       setDiscountAmount(0);
       setChargedTotal({ amount: data.chargedAmount, currency: data.chargedCurrency });
       setCouponTaxQuote(data.taxQuote ?? null);
-      if (data.paymentSecret && data.paymentId) {
+      if ((data.paymentSecret || data.accessCode || data.checkoutUrl) && data.paymentId) {
         setCouponPaymentUpdate({
           paymentSecret: data.paymentSecret,
+          accessCode: data.accessCode,
+          checkoutUrl: data.checkoutUrl,
           paymentId: data.paymentId,
           chargedAmount: data.chargedAmount,
           chargedCurrency: data.chargedCurrency,
@@ -598,6 +624,36 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
 
   const provider = flow.provider;
 
+  // ── Paystack inline checkout ────────────────────────────────────────────────
+  /**
+   * The Paystack session the pay button acts on.
+   *
+   * Read off `effectivePayment` rather than `flow.result` so a discount code
+   * that re-mints the charge is what gets opened. Opening the start-payment
+   * session after a coupon applied would charge the undiscounted amount.
+   */
+  const paystackSession = useMemo(
+    () => ({
+      accessCode: effectivePayment?.accessCode,
+      checkoutUrl: effectivePayment?.checkoutUrl,
+      returnUrl,
+    }),
+    [effectivePayment?.accessCode, effectivePayment?.checkoutUrl, returnUrl],
+  );
+  const canOpenPaystack = hasPaystackSession(paystackSession);
+
+  const openPaystackCheckout = useCallback(
+    () =>
+      openPaystackModal(paystackSession, {
+        // Closing the popup is not a failed order. The order is still there,
+        // the reservation is still running, and the button opens the very same
+        // session again, so nothing is said and nothing is marked.
+        onDismiss: () => {},
+        onError: (message) => setPageError(message || "The payment could not be completed. Please try again."),
+      }),
+    [paystackSession],
+  );
+
   return {
     // ── Cart + totals ────────────────────────────────────────────────────────
     cartItems,
@@ -663,6 +719,14 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     isRetryingHold: flow.isStarting,
     provider,
     isPaystack: provider === PaymentProviderName.Paystack,
+    /**
+     * Open the Paystack modal for whatever charge is CURRENTLY live. A coupon
+     * re-mints the session, and the pay button has to follow it rather than
+     * re-opening the pre-discount one.
+     */
+    openPaystackCheckout,
+    /** True once there is a Paystack session the pay button can open. */
+    canOpenPaystack,
     paymentSecret: effectivePayment?.paymentSecret,
     paymentId: effectivePayment?.paymentId,
     chargedAmount: effectivePayment?.chargedAmount ?? 0,

package/src/ui/headless/coaching/useCoachingBooking.ts

@@ -297,6 +297,10 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
     setQuestionnaire,
     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,
     // The booking quote WINS over start-payment: every `continueToPayment`
     // re-quotes before starting the payment, and applying or removing a code
     // re-quotes again — so the quote is never staler, and preferring the

package/src/ui/headless/course/useCourseCheckout.ts

@@ -193,6 +193,10 @@ export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions
     setQuestionnaire,
     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,
     // The booking quote WINS over start-payment: every `continueToPayment`
     // re-quotes before starting the payment, and applying or removing a code
     // re-quotes again — so the quote is never staler, and preferring the

package/src/ui/headless/donation/Donation.tsx

@@ -13,15 +13,22 @@ import {
   useDonationContext,
   type DonationProviderProps,
 } from "./DonationContext";
+import type { PaystackCheckoutOutcome } from "../../../utils/paystackCheckout";
 
 /** Render-prop payload for `<Donation.PaymentStep>`. The app supplies the
  * actual payment UI (e.g. Stripe Elements) — the SDK owns only the data. */
 export interface DonationPaymentRenderProps {
+  /** STRIPE: the PaymentIntent client secret. Undefined on Paystack. */
   clientSecret?: string;
   returnUrl: string;
   amount: number;
   onSucceeded: () => void;
   onFailed: (message?: string) => void;
+  /** PAYSTACK: render a pay button instead of a card form. */
+  isPaystack: boolean;
+  canOpenPaystack: boolean;
+  /** Opens (or re-opens, after a dismissal) the Paystack modal. */
+  openPaystackCheckout: () => Promise<PaystackCheckoutOutcome>;
 }
 
 type DonationComponent = ((props: DonationProviderProps) => React.ReactElement) & {
@@ -102,6 +109,9 @@ Donation.PaymentStep = function DonationPaymentStep({ children }) {
           amount: ctx.startResult?.totalAmount ?? ctx.estimatedTotal,
           onSucceeded: ctx.onPaymentSucceeded,
           onFailed: ctx.onPaymentFailed,
+          isPaystack: ctx.isPaystack,
+          canOpenPaystack: ctx.canOpenPaystack,
+          openPaystackCheckout: ctx.openPaystackCheckout,
         })}
       </>
     );

package/src/ui/headless/donation/DonationContext.tsx

@@ -3,6 +3,7 @@ import type { PaymentFlowResult, PublicDonation } from "../../../types/models";
 import { useGetDonation, useTrackDonationView } from "../../../data/queries/useDonations";
 import { useDonationFinalize } from "../../../data/queries/useFinalize";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import type { PaystackCheckoutOutcome } from "../../../utils/paystackCheckout";
 import { estimateProcessingFee } from "./fees";
 
 export type DonationStep = "amount" | "payment" | "result";
@@ -46,6 +47,15 @@ export interface DonationContextValue {
   /** The return URL passed to the payment provider. */
   returnUrl: string;
   continueToPayment: () => Promise<void>;
+  /** True once the charge started on Paystack rather than Stripe. */
+  isPaystack: boolean;
+  /** True once there is a Paystack session a pay button can (re-)open. */
+  canOpenPaystack: boolean;
+  /**
+   * Re-open the Paystack modal on the SAME charge. The donor who closed it by
+   * accident has not failed and needs a way back in.
+   */
+  openPaystackCheckout: () => Promise<PaystackCheckoutOutcome>;
 
   // Result
   outcome: DonationOutcome;
@@ -75,7 +85,20 @@ export interface DonationProviderProps {
 export function DonationProvider({ donationId, children, returnUrl, onSuccess }: DonationProviderProps) {
   const { data: donation, isLoading } = useGetDonation(donationId);
   const trackView = useTrackDonationView();
-  const flow = usePaymentFlow({ path: `/public/donations/${donationId}/start-payment`, autoStart: false });
+  const flow = usePaymentFlow({
+    path: `/public/donations/${donationId}/start-payment`,
+    autoStart: false,
+    // The donation modal finalizes IN PLACE, so a Paystack success stays here
+    // and runs the same finalize the Stripe path runs. Without this the helper
+    // would navigate to `returnUrl` and the donor would lose the thank-you step.
+    onPaystackSuccess: () => {
+      void onPaymentSucceeded();
+    },
+    // Closing the popup is not a failed donation: the payment step stays put,
+    // with the pay button live again on the very same charge.
+    onPaystackDismiss: () => {},
+    onPaystackError: (message) => onPaymentFailed(message),
+  });
   const donationFinalize = useDonationFinalize();
 
   const [open, setOpenState] = useState(false);
@@ -212,6 +235,9 @@ export function DonationProvider({ donationId, children, returnUrl, onSuccess }:
     startResult: flow.result,
     returnUrl: resolvedReturnUrl,
     continueToPayment,
+    isPaystack: flow.isPaystack,
+    canOpenPaystack: flow.canOpenPaystack,
+    openPaystackCheckout: flow.openPaystackCheckout,
     outcome,
     paymentErrorMessage,
     onPaymentSucceeded,

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

@@ -5,6 +5,7 @@ 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,
@@ -58,6 +59,31 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
   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");
@@ -280,6 +306,26 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       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,
@@ -301,6 +347,16 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
         // 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() ?? {}),
       });
@@ -477,6 +533,16 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
      * 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,
@@ -493,6 +559,10 @@ 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,

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. */

package/src/ui/headless/offer/Offer.tsx

@@ -9,12 +9,19 @@ import {
   DialogTitle,
 } from "../dialog";
 import { OfferProvider, useOfferContext, type OfferProviderProps } from "./OfferContext";
+import type { PaystackCheckoutOutcome } from "../../../utils/paystackCheckout";
 
 /** Render-prop payload for `<Offer.PaymentStep>` (redirect-mode payment). */
 export interface OfferPaymentRenderProps {
+  /** STRIPE: the PaymentIntent client secret. Undefined on Paystack. */
   clientSecret?: string;
   returnUrl: string;
   amount: number;
+  /** PAYSTACK: render a pay button instead of a card form. */
+  isPaystack: boolean;
+  canOpenPaystack: boolean;
+  /** Opens (or re-opens, after a dismissal) the Paystack modal. */
+  openPaystackCheckout: () => Promise<PaystackCheckoutOutcome>;
 }
 
 type OfferComponent = ((props: OfferProviderProps) => React.ReactElement) & {
@@ -82,7 +89,18 @@ Offer.PaymentStep = function OfferPaymentStep({ children }) {
   const ctx = useOfferContext();
   if (ctx.step !== "payment") return null;
   if (typeof children === "function") {
-    return <>{children({ clientSecret: ctx.clientSecret, returnUrl: ctx.returnUrl, amount: ctx.totalPrice })}</>;
+    return (
+      <>
+        {children({
+          clientSecret: ctx.clientSecret,
+          returnUrl: ctx.returnUrl,
+          amount: ctx.totalPrice,
+          isPaystack: ctx.isPaystack,
+          canOpenPaystack: ctx.canOpenPaystack,
+          openPaystackCheckout: ctx.openPaystackCheckout,
+        })}
+      </>
+    );
   }
   return <>{children}</>;
 };

package/src/ui/headless/offer/OfferContext.tsx

@@ -5,6 +5,7 @@ import { useCreateOrder } from "../../../data/queries/useOrders";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
 import { holdExpiredMessage, isHoldExpiredError } from "../checkout/inventoryHold";
 import { useInventoryHold, type InventoryHoldState } from "../checkout/useInventoryHold";
+import type { PaystackCheckoutOutcome } from "../../../utils/paystackCheckout";
 
 export type OfferStep = "details" | "payment";
 
@@ -36,8 +37,17 @@ export interface OfferContextValue {
 
   isProcessing: boolean;
   error: string | null;
-  /** Payment intent once the order is created (Stripe). */
+  /** Payment intent once the order is created (STRIPE only). */
   clientSecret?: string;
+  /** True once the charge started on Paystack rather than Stripe. */
+  isPaystack: boolean;
+  /** True once there is a Paystack session a pay button can (re-)open. */
+  canOpenPaystack: boolean;
+  /**
+   * Re-open the Paystack modal on the SAME charge. A buyer who closed it has
+   * not failed, and the order is still sitting there waiting to be paid.
+   */
+  openPaystackCheckout: () => Promise<PaystackCheckoutOutcome>;
   returnUrl: string;
   continueToPayment: () => Promise<void>;
   /** The stock reservation held while the buyer pays. All-null when none was taken. */
@@ -205,6 +215,9 @@ export function OfferProvider({ productId, children, finalisePath }: OfferProvid
     isProcessing: createOrder.isPending || flow.isStarting,
     error,
     clientSecret: flow.result?.paymentSecret,
+    isPaystack: flow.isPaystack,
+    canOpenPaystack: flow.canOpenPaystack,
+    openPaystackCheckout: flow.openPaystackCheckout,
     returnUrl,
     continueToPayment,
     hold,

package/src/ui/headless/paymentLink/usePaymentLinkPayment.ts

@@ -11,7 +11,9 @@ export interface UsePaymentLinkPaymentOptions {
 /**
  * Headless payment-link checkout: loads the link and starts its payment.
  * Composes `usePaymentLink` + `usePaymentFlow`. Stripe UI renders from
- * `clientSecret`; finalize on the return page with `usePaymentLinkFinalize`.
+ * `clientSecret`; Paystack opens its inline modal (and `openPaystackCheckout`
+ * re-opens it after a dismissal). Finalize on the return page with
+ * `usePaymentLinkFinalize`.
  */
 export function usePaymentLinkPayment(paymentLinkId?: string, opts: UsePaymentLinkPaymentOptions = {}) {
   const link = usePaymentLink(paymentLinkId);
@@ -34,6 +36,10 @@ export function usePaymentLinkPayment(paymentLinkId?: string, opts: UsePaymentLi
     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,
     /** Authoritative sales-tax quote from start-payment (display only). */
     taxQuote: flow.result?.taxQuote ?? null,
     isStarting: flow.isStarting,

package/src/ui/headless/work/useWorkPortal.ts

@@ -343,10 +343,10 @@ export function formatWorkMoney(amount: number, currency = "USD"): string {
   return `${symbol}${n.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
 }
 
-/** ISO date → short human date, or "—" when absent. */
+/** ISO date → short human date, or "Not set" when absent. */
 export function formatWorkDate(value: string | null | undefined): string {
-  if (!value) return "—";
+  if (!value) return "Not set";
   const d = new Date(value);
-  if (Number.isNaN(d.getTime())) return "—";
+  if (Number.isNaN(d.getTime())) return "Not set";
   return d.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
 }

package/src/ui/index.ts

@@ -64,6 +64,7 @@ export { UserMenu, type UserMenuProps } from "./styled/UserMenu";
 export { EmailListForm, type EmailListFormProps } from "./styled/EmailListForm";
 export { BlogComments, type BlogCommentsProps } from "./styled/BlogComments";
 export { PageActions, type PageActionsProps } from "./styled/PageActions";
+export { MusicLinkPage, type MusicLinkPageProps } from "./styled/MusicLinkPage";
 export { BlogPostFooter, type BlogPostFooterProps } from "./styled/BlogPostFooter";
 export { BotProtection, EMPTY_BOT_FIELDS, type BotFields } from "./styled/BotProtection";
 export { ContactForm, type ContactFormProps } from "./styled/ContactForm";
@@ -112,6 +113,7 @@ export { CookieConsent, type CookieConsentProps } from "./styled/CookieConsent";
 export { Loading, type LoadingProps } from "./styled/Loading";
 /** The inventory-hold countdown + its lapsed/409 state. See `useInventoryHold`. */
 export { HoldNotice, type HoldNoticeProps } from "./styled/HoldNotice";
+export { PaystackPayButton, type PaystackPayButtonProps } from "./styled/PaystackPayButton";
 export {
   ConfirmationStage,
   ConfirmationCard,
@@ -173,6 +175,27 @@ export {
   resolveUnitPrice,
   ticketSubtotals,
 } from "./format/pwyw";
+// When a tier may be BOUGHT, for a site rendering its own ticket UI. Both halves
+// close a "discoverable only by failing" journey: `ticketSeatsAvailable`
+// subtracts `held` the way the server does, so a fan is never shown seats that
+// are already in someone else's checkout; `ticketSaleWindow` surfaces a
+// scheduled on-sale, which shipped enforced and drawn nowhere. Presentation
+// only — `createOrder` re-checks both.
+export {
+  ticketSeatsAvailable,
+  ticketSeatsUnsold,
+  ticketSeatState,
+  ticketSeatLabel,
+  ticketSeatNotice,
+  ticketSaleWindow,
+  isTicketScheduled,
+  formatOnSaleAt,
+  onSaleBadge,
+  onSaleNotice,
+  maxAddableTickets,
+  type TicketSeatState,
+  type TicketSaleWindow,
+} from "./format/ticketAvailability";
 // Per-attendee names at checkout. Exported for a site rendering its own ticket
 // UI — and used by `apps/client`, which has its own event checkout: the request
 // shape is positional per tier and a length mismatch is refused server-side, so