@tribe-nest/forge 3.21.0 → 3.23.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,
@@ -18,6 +19,8 @@ import {
   type ApplyCheckoutCouponResult,
 } from "../../../data/queries/useCheckouts";
 import { bundleCouponSummary, bundleReturnUrl } from "./bundleCoupon";
+import { holdExpiredMessage, isHoldExpiredError } from "./inventoryHold";
+import { useInventoryHold } from "./useInventoryHold";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 import { ProductDeliveryType, PaymentProviderName, type ApiError, type PublicTaxQuote } from "../../../types/models";
@@ -66,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;
@@ -285,10 +297,67 @@ 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;
 
+  // ── Inventory hold ──────────────────────────────────────────────────────────
+  /**
+   * The reservation clock the buyer is counting down.
+   *
+   * `start-payment` RESTARTS the hold and reports the new instant, so its figure
+   * supersedes the one `createOrder` returned — that one was measured before the
+   * buyer had even seen a payment field. The create-time value bridges the
+   * moment in between, which for a slow `start-payment` is the whole of the
+   * buyer's first impression of the page.
+   *
+   * A bundle has no create-time figure at all (`POST /public/checkouts` takes
+   * the holds but does not report a window), so it is start-payment or nothing —
+   * which is fine, because a bundle always starts payment immediately.
+   *
+   * `undefined` on an older API and `null` whenever no hold was taken; both mean
+   * "render nothing", which is exactly today's behaviour.
+   */
+  const holdExpiresAt = flow.result?.holdExpiresAt ?? created?.holdExpiresAt ?? null;
+  const hold = useInventoryHold(holdExpiresAt);
+
+  /**
+   * The reservation ran out before the payment landed (409
+   * `INVENTORY_HOLD_EXPIRED`), which is NOT sold-out — the items may well still
+   * be there, and re-running `start-payment` re-acquires the very same units
+   * when they are. Told apart from every other start failure so the buyer is
+   * offered the retry that actually works instead of a dead end.
+   */
+  const isHoldExpired = isHoldExpiredError(flow.error);
+  const holdExpiredError = isHoldExpired
+    ? holdExpiredMessage(flow.error, "Your basket reservation expired before payment finished. Please try again.")
+    : "";
+
+  /**
+   * Take the reservation again on the SAME order or bundle.
+   *
+   * The cheapest recovery there is: nothing about the cart has changed, so if
+   * the units are still free the buyer gets a fresh window and the card form
+   * they were already looking at. If they are genuinely gone, another 409 says
+   * so — and that is the point at which "change your selection" is the honest
+   * next step, not before.
+   */
+  const retryHold = useCallback(async () => {
+    if (!created?.orderId && !checkoutId) return;
+    try {
+      await flow.start();
+    } catch {
+      // The refusal is already on `flow.error`; a rethrow here would only turn a
+      // handled state into an unhandled rejection.
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [created?.orderId, checkoutId]);
+
   // A coupon re-issues the payment intent, so its update supersedes the initial
   // start-payment result. Otherwise use the started payment once both the order
   // and start-payment have resolved.
@@ -297,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;
@@ -442,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,
@@ -499,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,
@@ -544,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,
@@ -589,8 +699,34 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     ticketItems,
     isCreatingOrder: createOrder.isPending || flow.isStarting,
     startError,
+    // ── Inventory hold ─────────────────────────────────────────────────────────
+    /**
+     * The live reservation: `isHeld` + `label` while it runs, `hasLapsed` once
+     * the clock hits zero. Every field is null/false when no hold was taken, so
+     * a surface guarding on `isHeld || hasLapsed` is unchanged for the profiles
+     * that have holds switched off.
+     */
+    hold,
+    /**
+     * The server said the reservation expired (409 `INVENTORY_HOLD_EXPIRED`) —
+     * its own words, already localised. Empty for every other failure, so this
+     * can never be mistaken for sold-out.
+     */
+    holdExpiredError,
+    isHoldExpired,
+    /** Re-take the reservation on the same order/bundle. See `retryHold`. */
+    retryHold,
+    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/checkout/useInventoryHold.ts

@@ -0,0 +1,104 @@
+import { useEffect, useRef, useState } from "react";
+import { formatHoldRemaining, holdMsRemaining } from "./inventoryHold";
+
+export interface InventoryHoldState {
+  /**
+   * True only while a real reservation is running. False both when there is no
+   * hold at all and once one has run out — the two are told apart by
+   * `hasLapsed`, and no surface should draw a timer off this alone.
+   */
+  isHeld: boolean;
+  /** True when a hold existed and its clock reached zero on this device. */
+  hasLapsed: boolean;
+  /** The instant the API reported, unchanged; `null` when no hold was taken. */
+  expiresAt: string | null;
+  /** Milliseconds left, or `null` when there is no hold. */
+  msRemaining: number | null;
+  /** Whole seconds left, or `null` when there is no hold. */
+  secondsRemaining: number | null;
+  /** `m:ss` (or `h:mm:ss`) for display; `null` when there is nothing to count. */
+  label: string | null;
+  /** Under two minutes — the point at which a surface should stop being subtle. */
+  isUrgent: boolean;
+}
+
+export interface UseInventoryHoldOptions {
+  /**
+   * Fired once, when a running clock reaches zero. For telling a flow to stop
+   * describing the reservation as live; NOT for tearing the payment form down.
+   */
+  onLapse?: () => void;
+  /** Tick interval, ms. Only for tests — a second is what a countdown means. */
+  intervalMs?: number;
+}
+
+/**
+ * Count down an inventory hold.
+ *
+ * ## What it does at zero, and why
+ *
+ * It stops, and it flips `hasLapsed`. A timer that reaches 0:00 and then keeps
+ * sitting there is worse than no timer: it has told the buyer something has
+ * happened and then refuses to say what. So the honest end state is a *changed
+ * statement* — "your reservation has ended" — which the calling surface renders
+ * in place of the clock, with the same recovery action a 409 gets.
+ *
+ * It deliberately does **not** hide or disable the payment form. This clock is
+ * the buyer's device clock against an instant the server chose; it can be
+ * skewed, and the server may still accept the payment (`start-payment`
+ * re-acquires the same units when they are still free). Refusing a charge the
+ * server would have taken loses a real sale to defend a display detail. The
+ * authority stays where it belongs — the 409, when it comes.
+ *
+ * ## Degrading to today's behaviour
+ *
+ * Holds are behind a per-profile switch that most profiles have off, and a free
+ * or already-settled order never carries one either. In all of those cases
+ * `holdExpiresAt` is `null`/absent, every field here is null/false, and a
+ * surface that guards on `isHeld || hasLapsed` renders exactly what it renders
+ * today.
+ */
+export function useInventoryHold(
+  holdExpiresAt: string | null | undefined,
+  opts: UseInventoryHoldOptions = {},
+): InventoryHoldState {
+  const { onLapse, intervalMs = 1000 } = opts;
+  const [msRemaining, setMsRemaining] = useState<number | null>(() => holdMsRemaining(holdExpiresAt, Date.now()));
+  // Keeps the callback out of the effect's dependencies, so an inline arrow
+  // from the caller does not restart the interval on every render.
+  const onLapseRef = useRef(onLapse);
+  onLapseRef.current = onLapse;
+
+  useEffect(() => {
+    const initial = holdMsRemaining(holdExpiresAt, Date.now());
+    setMsRemaining(initial);
+    // No hold, or one that was already over when we first saw it (a resumed tab,
+    // a skewed clock): nothing to tick. The already-over case still reports
+    // `hasLapsed` below — it just never animated down to it.
+    if (initial === null || initial <= 0) return;
+
+    const id = setInterval(() => {
+      const next = holdMsRemaining(holdExpiresAt, Date.now());
+      setMsRemaining(next);
+      if (next !== null && next <= 0) {
+        clearInterval(id);
+        onLapseRef.current?.();
+      }
+    }, intervalMs);
+    return () => clearInterval(id);
+  }, [holdExpiresAt, intervalMs]);
+
+  const hasHold = msRemaining !== null;
+  const hasLapsed = hasHold && msRemaining <= 0;
+  const isHeld = hasHold && msRemaining > 0;
+
+  return {
+    isHeld,
+    hasLapsed,
+    expiresAt: holdExpiresAt ?? null,
+    msRemaining,
+    secondsRemaining: hasHold ? Math.ceil(msRemaining / 1000) : null,
+    label: isHeld ? formatHoldRemaining(msRemaining) : null,
+    isUrgent: isHeld && msRemaining <= 120_000,
+  };
+}

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,