@tribe-nest/forge 3.21.0 → 3.23.0

package/src/utils/paystackCheckout.ts

@@ -0,0 +1,277 @@
+/// <reference path="../types/paystack-inline.d.ts" />
+
+/**
+ * Paystack inline checkout: the ONE place in Forge that knows the popup exists.
+ *
+ * The fan pays in a modal on the creator's own site instead of being sent to a
+ * Paystack-branded page and back. Every pillar (cart, tickets, courses,
+ * coaching, invoices, payment links, donations, offers, memberships) reaches
+ * Paystack through this function, so there is exactly one implementation of the
+ * lazy load, the fallback and the success navigation to reason about.
+ *
+ * Four properties are load-bearing:
+ *
+ * 1. **SSR safety.** Forge sites are TanStack Start, so this module is evaluated
+ *    on the server. Nothing here touches `window`, `document` or the Paystack
+ *    bundle at module scope; the browser check happens before any of it.
+ * 2. **Lazy load.** `@paystack/inline-js` is reached through a dynamic
+ *    `import()`, so it never enters the initial bundle and a blocked script
+ *    cannot break page render: it becomes a rejected promise we can handle.
+ * 3. **One runtime fallback, not a version shim.** When the modal cannot open
+ *    (import rejected, `resumeTransaction` threw, or nothing appeared within
+ *    `MODAL_OPEN_TIMEOUT_MS`), the fan goes to the hosted page carried on
+ *    `checkoutUrl`. The sale survives a blocked CDN, a CSP, or an extension.
+ *    This is about browser conditions, never about which Forge version a site
+ *    compiled against.
+ * 4. **Dismissal is not failure.** Closing the modal without paying resolves
+ *    `"dismissed"`. Nothing is marked failed and the caller can open it again.
+ *
+ * Stripe is untouched by any of this: it keeps reading `paymentSecret` as the
+ * PaymentIntent client secret, exactly as live sites already do.
+ */
+
+/** How a checkout attempt ended. */
+export type PaystackCheckoutOutcome =
+  /** Paid in the modal. */
+  | "succeeded"
+  /** The fan closed the modal without paying. Retryable, not a failure. */
+  | "dismissed"
+  /** Paystack reported a genuine failure after the modal opened. */
+  | "failed"
+  /** The modal could not be used, so the fan was sent to the hosted page. */
+  | "redirected"
+  /** Nothing could be done here at all (server render, or no session to open). */
+  | "unavailable";
+
+/** The bits of a completed Paystack transaction the return leg needs. */
+export type PaystackTransactionResult = {
+  reference?: string;
+  trxref?: string;
+  transaction?: string;
+  status?: string;
+};
+
+/**
+ * A started Paystack charge, exactly as `start-payment` reports it.
+ *
+ * `accessCode` and `checkoutUrl` arrive in the SAME `/transaction/initialize`
+ * response, which is why carrying the fallback costs one field rather than a
+ * second round trip.
+ */
+export type PaystackCheckoutSession = {
+  /** Checkout-session access code. Carries the session; no public key needed. */
+  accessCode?: string | null;
+  /** Hosted checkout URL. The runtime fallback. */
+  checkoutUrl?: string | null;
+  /** Where the redirect leg would have landed. Used on success by default. */
+  returnUrl?: string | null;
+};
+
+export type PaystackCheckoutHandlers = {
+  /**
+   * Paid. When omitted, the helper navigates to `returnUrl` with Paystack's own
+   * `reference`/`trxref` appended, byte for byte what the hosted redirect did,
+   * so every finalise page keeps working untouched. Supply this only when the
+   * surface finalises in place (a modal that shows its own receipt).
+   */
+  onSuccess?: (result: PaystackTransactionResult) => void;
+  /** The fan closed the modal. Re-enable the pay button; change nothing else. */
+  onDismiss?: () => void;
+  /** A real failure, or no usable session at all. */
+  onError?: (message?: string) => void;
+};
+
+/**
+ * How long to wait for the modal to show itself before deciding it will not.
+ *
+ * Long enough that a slow phone on a bad connection is not thrown out of a
+ * working modal, short enough that a fan staring at a dead button gives up
+ * before we do.
+ */
+const MODAL_OPEN_TIMEOUT_MS = 4000;
+const MODAL_POLL_MS = 200;
+
+const inBrowser = (): boolean => typeof window !== "undefined" && typeof document !== "undefined";
+
+/**
+ * Is Paystack's checkout iframe actually on screen right now?
+ *
+ * This decides whether the 4s watchdog falls back to the hosted page, so a
+ * false positive strands a fan on a dead button. The obvious selector,
+ * `iframe[src*="paystack"]`, produces one in two ways that both happen in
+ * practice:
+ *
+ *  1. A DISMISSED modal's iframe is hidden, not removed. On a second attempt it
+ *     still matches, so the watchdog concludes the modal opened when nothing
+ *     did. Hence the visibility check rather than mere presence.
+ *  2. Any iframe whose src merely CONTAINS the string, including third-party
+ *     frames that echo the current page URL back in their own src, which match
+ *     on any host with "paystack" in it. Hence matching the parsed HOST rather
+ *     than a substring of the whole URL.
+ */
+const modalIsPresent = (): boolean => {
+  const frames = Array.from(document.querySelectorAll<HTMLIFrameElement>("iframe[src]"));
+  return frames.some((frame) => {
+    let host: string;
+    try {
+      host = new URL(frame.src, window.location.href).hostname.toLowerCase();
+    } catch {
+      return false;
+    }
+    if (host !== "paystack.com" && !host.endsWith(".paystack.com")) return false;
+
+    // Visibility, not layout size. `getBoundingClientRect` would be the more
+    // thorough test, but the checks that matter are the ones Paystack actually
+    // uses to put a dismissed modal away, and this keeps the rule assertable.
+    if (frame.hidden) return false;
+    const style = window.getComputedStyle(frame);
+    return style.display !== "none" && style.visibility !== "hidden";
+  });
+};
+
+const errorMessageOf = (error: unknown): string | undefined => {
+  if (typeof error === "string") return error;
+  const message = (error as { message?: unknown } | null)?.message;
+  return typeof message === "string" ? message : undefined;
+};
+
+/**
+ * The URL the hosted redirect would have landed on.
+ *
+ * Paystack appends `reference` and `trxref` to the callback URL, and finalise
+ * pages have always been able to read them. Appending the same two params after
+ * a modal success is what makes "nothing downstream changes" literally true.
+ */
+export function paystackReturnUrl(returnUrl: string, result: PaystackTransactionResult): string {
+  const reference = result.reference || result.trxref;
+  if (!reference) return returnUrl;
+  try {
+    const base = inBrowser() ? window.location.href : undefined;
+    const url = new URL(returnUrl, base);
+    url.searchParams.set("reference", reference);
+    url.searchParams.set("trxref", reference);
+    return url.toString();
+  } catch {
+    // A relative URL with no base to resolve against. The caller's own return
+    // path is still the right destination; it just carries no reference.
+    return returnUrl;
+  }
+}
+
+/** True when a start-payment result is a Paystack session this helper can act on. */
+export function hasPaystackSession(session: PaystackCheckoutSession | null | undefined): boolean {
+  return !!(session && (session.accessCode || session.checkoutUrl));
+}
+
+/**
+ * Open the Paystack modal for a started charge.
+ *
+ * Resolves once the attempt has ended one way or another; it never rejects, so
+ * a caller can `await` it from a click handler without a try/catch.
+ */
+export async function openPaystackCheckout(
+  session: PaystackCheckoutSession,
+  handlers: PaystackCheckoutHandlers = {},
+): Promise<PaystackCheckoutOutcome> {
+  // Server render: do nothing at all, and say so rather than throwing.
+  if (!inBrowser()) return "unavailable";
+
+  const accessCode = session.accessCode || undefined;
+  const checkoutUrl = session.checkoutUrl || undefined;
+
+  if (!accessCode && !checkoutUrl) {
+    handlers.onError?.("This payment could not be started. Please try again.");
+    return "unavailable";
+  }
+
+  /** The one runtime fallback: the hosted page the same initialize call returned. */
+  const goToHostedPage = (): PaystackCheckoutOutcome => {
+    if (!checkoutUrl) {
+      handlers.onError?.("The payment window could not be opened. Please try again.");
+      return "unavailable";
+    }
+    window.location.href = checkoutUrl;
+    return "redirected";
+  };
+
+  if (!accessCode) return goToHostedPage();
+
+  let PaystackPop: typeof import("@paystack/inline-js").default;
+  try {
+    // Lazily imported so a blocked CDN, an offline chunk or a CSP is a rejected
+    // promise here instead of a page that will not render.
+    PaystackPop = (await import("@paystack/inline-js")).default;
+  } catch {
+    return goToHostedPage();
+  }
+
+  return new Promise<PaystackCheckoutOutcome>((resolve) => {
+    let settled = false;
+    let opened = false;
+    let poll: ReturnType<typeof setInterval> | undefined;
+    let watchdog: ReturnType<typeof setTimeout> | undefined;
+
+    const stopWatching = () => {
+      if (poll) clearInterval(poll);
+      if (watchdog) clearTimeout(watchdog);
+      poll = undefined;
+      watchdog = undefined;
+    };
+
+    const settle = (outcome: PaystackCheckoutOutcome) => {
+      if (settled) return false;
+      settled = true;
+      stopWatching();
+      resolve(outcome);
+      return true;
+    };
+
+    const succeed = (result: PaystackTransactionResult) => {
+      if (!settle("succeeded")) return;
+      if (handlers.onSuccess) {
+        handlers.onSuccess(result);
+        return;
+      }
+      // No handler: continue down the exact path the redirect used.
+      if (session.returnUrl) window.location.href = paystackReturnUrl(session.returnUrl, result);
+    };
+
+    try {
+      new PaystackPop().resumeTransaction(accessCode, {
+        onSuccess: (transaction) => succeed(transaction ?? {}),
+        // Closing the popup leaves the charge exactly where it was. Nothing is
+        // failed, nothing is cancelled server-side, and the same access code
+        // still opens the same session on the next click.
+        onCancel: () => {
+          if (settle("dismissed")) handlers.onDismiss?.();
+        },
+        // The iframe is up, so the watchdog has nothing left to rescue.
+        onLoad: () => {
+          opened = true;
+          stopWatching();
+        },
+        onError: (error) => {
+          if (settle("failed")) handlers.onError?.(errorMessageOf(error));
+        },
+      });
+    } catch {
+      // `resumeTransaction` threw synchronously, so the modal never got started.
+      settle(goToHostedPage());
+      return;
+    }
+
+    poll = setInterval(() => {
+      if (!modalIsPresent()) return;
+      opened = true;
+      stopWatching();
+    }, MODAL_POLL_MS);
+
+    watchdog = setTimeout(() => {
+      stopWatching();
+      if (settled || opened) return;
+      // The modal never appeared. Send the fan to the hosted page rather than
+      // leaving them looking at a button that did nothing.
+      settle(goToHostedPage());
+    }, MODAL_OPEN_TIMEOUT_MS);
+  });
+}

package/src/utils/presaleCode.ts

@@ -0,0 +1,96 @@
+/**
+ * Where a buyer's presale code lives between typing it and paying with it.
+ *
+ * ## Why this is a module-level store and not component state
+ *
+ * The code has to be in three places at once, in components that do not share a
+ * parent: the event page's own `useEvent` (to reveal the hidden tiers), the
+ * ticket modal's `useEventCheckout` (its own separate `useEvent`), and the
+ * order body (the sell guard re-checks the code on every purchase, so a buyer
+ * who unlocks a tier and then checks out without the code is refused AFTER
+ * entering their card). Threading it through props would work for one host app
+ * and break for every code-site that composes the Forge pieces differently.
+ *
+ * ## Why sessionStorage and not localStorage
+ *
+ * A presale code is a right to buy now, not a saved preference. Session scope
+ * survives the reload, the Stripe redirect and the back button — everything
+ * inside one purchase — and does not silently re-apply a spent code to a
+ * different show weeks later.
+ *
+ * Keyed per event, because two presales are two different codes.
+ */
+
+const KEY_PREFIX = "tn:presale:";
+
+/** eventKey → code, mirroring sessionStorage so reads are synchronous. */
+const memory = new Map<string, string>();
+const listeners = new Set<() => void>();
+
+/** Loaded lazily so a server render never touches storage. */
+const hydrated = new Set<string>();
+
+const storageKey = (eventKey: string) => `${KEY_PREFIX}${eventKey}`;
+
+function hydrate(eventKey: string): void {
+  if (hydrated.has(eventKey) || typeof window === "undefined") return;
+  hydrated.add(eventKey);
+  try {
+    const stored = window.sessionStorage.getItem(storageKey(eventKey));
+    if (stored) memory.set(eventKey, stored);
+  } catch {
+    // Private mode / disabled storage. The code still works for this render;
+    // it just will not survive a reload.
+  }
+}
+
+export function readPresaleCode(eventKey: string): string | null {
+  if (!eventKey) return null;
+  hydrate(eventKey);
+  return memory.get(eventKey) ?? null;
+}
+
+export function writePresaleCode(eventKey: string, code: string | null): void {
+  if (!eventKey) return;
+  hydrated.add(eventKey);
+  const trimmed = code?.trim();
+  if (trimmed) memory.set(eventKey, trimmed);
+  else memory.delete(eventKey);
+
+  if (typeof window !== "undefined") {
+    try {
+      if (trimmed) window.sessionStorage.setItem(storageKey(eventKey), trimmed);
+      else window.sessionStorage.removeItem(storageKey(eventKey));
+    } catch {
+      // As above — in-memory only.
+    }
+  }
+
+  for (const listener of listeners) listener();
+}
+
+export function subscribePresaleCode(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * `?accessCode=PRESALE24` on the URL, so the link an artist mails to their list
+ * unlocks the page on arrival instead of asking the recipient to retype what
+ * they just clicked.
+ *
+ * The parameter is left ON the URL deliberately, unlike the attribution ref: a
+ * presale link is meant to be forwardable, and stripping it would break the
+ * one thing the recipient is most likely to do with it.
+ */
+export function readPresaleCodeFromUrl(): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const value = new URL(window.location.href).searchParams.get("accessCode");
+    return value?.trim() || null;
+  } catch {
+    return null;
+  }
+}