@tribe-nest/forge 3.26.0 → 3.31.0

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

@@ -1,4 +1,4 @@
-import { useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
 import { useGetMembershipTiers } from "../../../data/queries/useMembership";
 import {
@@ -14,9 +14,30 @@ import {
   type PaystackCheckoutOutcome,
   type PaystackCheckoutSession,
 } from "../../../utils/paystackCheckout";
+import type { MembershipTier } from "../../../types/models";
+import {
+  cycleCeiling,
+  cycleFloor,
+  cycleIsFree,
+  defaultChosenAmount,
+  defaultCycle,
+  offeredCycles,
+  refuseMembershipAmount,
+  resolveSubscriptionAmount,
+  type BillingCycle,
+  type MembershipAmountRefusal,
+} from "../../format/membershipPwyw";
 
-export type MembershipCheckoutStep = "select" | "payment";
-export type BillingCycle = "month" | "year";
+/**
+ * Three steps, matching the client app's three stages.
+ *
+ * `"tier"` is the tier grid, reached when the page was opened with no
+ * `?membershipTierId`. `"select"` keeps its old name deliberately: it is the
+ * tier detail + billing options step, and every site already calls
+ * `setStep("select")` to go back from payment.
+ */
+export type MembershipCheckoutStep = "tier" | "select" | "payment";
+export type { BillingCycle };
 
 export interface UseMembershipCheckoutOptions {
   /** Pre-select a tier (e.g. from a `?membershipTierId=` param). */
@@ -25,27 +46,37 @@ export interface UseMembershipCheckoutOptions {
   returnPath?: string;
   /** Where free activations land. Default `/i/account?tab=membership`. */
   freeReturnPath?: string;
-  /** Called when a FREE activation completes in-app — the host navigates however
-   * it wants, instead of Forge doing a `window.location` redirect. */
-  onComplete?: () => void;
+  /**
+   * Called when the subscription completes IN-APP with nothing left to pay: a
+   * free activation, or a tier change the server settled by proration. The host
+   * navigates however it wants instead of Forge doing a `window.location`
+   * redirect. `requiresConfirmation` is false for both of those, because there
+   * is no provider payment for the account page to reconcile.
+   */
+  onComplete?: (result: { requiresConfirmation: boolean }) => void;
 }
 
 const errMessage = (e: unknown) =>
   (e as { response?: { data?: { message?: string } } })?.response?.data?.message || "Something went wrong.";
 
-const tierIsFree = (tier: { payWhatYouWant: boolean; priceMonthly?: number; priceYearly?: number }, cycle: BillingCycle) =>
-  !tier.payWhatYouWant && !(cycle === "month" ? tier.priceMonthly : tier.priceYearly);
-
 /**
- * Headless membership subscribe: tier selection → free activation OR paid Stripe
- * subscription. Composes `useGetMembershipTiers`, `useCreateFreeSubscription`,
+ * Headless membership subscribe: tier selection, billing cycle, pay-what-you-want
+ * amount, then free activation OR a paid subscription on the tenant's provider.
+ * Composes `useGetMembershipTiers`, `useCreateFreeSubscription`,
  * `useCreateSubscription`, and (for the return page) `useConfirmLatestSubscription`.
- * Paid flow exposes `clientSecret` for `ForgePaymentProvider`.
+ * Paid Stripe flow exposes `clientSecret` for `ForgePaymentProvider`; paid
+ * Paystack flow exposes `openPaystackCheckout`.
  *
  * 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
+ * subscription. That completes server-side with no payment step, it is
  * finished the moment `subscribe()` resolves, exactly like a free activation.
+ *
+ * ## Pricing lives in `ui/format/membershipPwyw`
+ *
+ * The floor, the default cycle, which cycles are on offer and the single number
+ * that gets sent are pure functions there, so they are testable without a
+ * provider tree. Read that file before changing anything about money here.
  */
 export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const { user } = usePublicAuth();
@@ -54,28 +85,105 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const createFree = useCreateFreeSubscription();
   const confirmLatest = useConfirmLatestSubscription();
 
-  const [step, setStep] = useState<MembershipCheckoutStep>("select");
+  const [step, setStep] = useState<MembershipCheckoutStep>(opts.initialTierId ? "select" : "tier");
   const [selectedTierId, setSelectedTierId] = useState<string | undefined>(opts.initialTierId);
-  const [billingCycle, setBillingCycle] = useState<BillingCycle>("month");
+  const [billingCycle, setBillingCycleState] = useState<BillingCycle>("month");
   const [customAmount, setCustomAmount] = useState<number>(0);
+  const [amountRefusal, setAmountRefusal] = useState<MembershipAmountRefusal | null>(null);
   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(
-    () => tiers?.find((t) => t.id === selectedTierId),
-    [tiers, selectedTierId],
+  const selectedTier = useMemo(() => tiers?.find((t) => t.id === selectedTierId), [tiers, selectedTierId]);
+
+  /**
+   * Seed the cycle and the amount box from the tier itself.
+   *
+   * This runs on the tier ARRIVING as much as on it being clicked: a page opened
+   * with `?membershipTierId=` has a selected id before the tier list has
+   * loaded, and without this the box would sit at 0 on a tier whose floor is 20.
+   *
+   * Keyed on the tier ID, not the tier OBJECT: the tier list is a React Query
+   * result, so a background refetch hands back an equal-but-new object, and
+   * keying on that would wipe the amount a fan had just typed.
+   */
+  useEffect(() => {
+    if (!selectedTier) return;
+    const cycle = defaultCycle(selectedTier);
+    setBillingCycleState(cycle);
+    setCustomAmount(defaultChosenAmount(selectedTier, cycle));
+    setAmountRefusal(null);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedTier?.id]);
+
+  /** Switching cycle re-seeds the amount box: the floor belongs to the cycle. */
+  const setBillingCycle = useCallback(
+    (cycle: BillingCycle) => {
+      setBillingCycleState(cycle);
+      setAmountRefusal(null);
+      if (selectedTier) setCustomAmount(defaultChosenAmount(selectedTier, cycle));
+    },
+    [selectedTier],
   );
 
-  const amount = useMemo(() => {
-    if (!selectedTier) return 0;
-    if (selectedTier.payWhatYouWant) return customAmount;
-    return (billingCycle === "month" ? selectedTier.priceMonthly : selectedTier.priceYearly) ?? 0;
-  }, [selectedTier, billingCycle, customAmount]);
+  const selectTier = useCallback((tier: MembershipTier) => {
+    setSelectedTierId(tier.id);
+    setError(null);
+    setAmountRefusal(null);
+    setStep("select");
+  }, []);
+
+  const backToTierList = useCallback(() => {
+    setSelectedTierId(undefined);
+    setError(null);
+    setAmountRefusal(null);
+    setStep("tier");
+  }, []);
+
+  const minimumAmount = selectedTier ? cycleFloor(selectedTier, billingCycle) : 0;
+  const maximumAmount = selectedTier ? cycleCeiling(selectedTier, billingCycle) : null;
+  const cycles = selectedTier ? offeredCycles(selectedTier) : { month: false, year: false };
+  const isFreeCycle = selectedTier ? cycleIsFree(selectedTier, billingCycle) : false;
+
+  /**
+   * What will be charged, and what will be SENT. A fixed tier ignores the
+   * amount box, so a figure left over from a pay-what-you-want tier cannot leak
+   * into a fixed-price subscription.
+   */
+  const amount = useMemo(
+    () => (selectedTier ? resolveSubscriptionAmount(selectedTier, billingCycle, customAmount) : 0),
+    [selectedTier, billingCycle, customAmount],
+  );
+
+  const membership = user?.membership;
+  /** The tier they are on now, so its card can say so instead of offering itself. */
+  const currentTierId = membership?.membershipTierId;
+  /**
+   * A member with a live provider subscription picking a PAID tier is changing,
+   * not joining. The server settles it by proration on the subscription they
+   * already have, so the button says so.
+   */
+  const isChange =
+    !!membership?.paymentProviderSubscriptionId && membership.status === "active" && !isFreeCycle && !!selectedTier;
+
+  const finish = (requiresConfirmation: boolean) => {
+    if (opts.onComplete) {
+      opts.onComplete({ requiresConfirmation });
+      return;
+    }
+    if (typeof window !== "undefined") {
+      const origin = window.location.origin;
+      const path = requiresConfirmation
+        ? (opts.returnPath ?? "/i/account?tab=membership&confirmSubscription=true")
+        : (opts.freeReturnPath ?? "/i/account?tab=membership");
+      window.location.href = `${origin}${path}`;
+    }
+  };
 
   const subscribe = async () => {
     setError(null);
+    setAmountRefusal(null);
     if (!selectedTier) {
       setError("Select a membership tier.");
       return;
@@ -84,17 +192,22 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
       setError("Please sign in to subscribe.");
       return;
     }
+    // Checked BEFORE the request, so a pay-what-you-want box below the floor
+    // (or still on its initial zero) is a message beside the field rather than
+    // an `amount_must_be_positive` 400 with nowhere to land.
+    const refusal = refuseMembershipAmount(selectedTier, billingCycle, customAmount);
+    if (refusal) {
+      setAmountRefusal(refusal);
+      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 {
-      if (tierIsFree(selectedTier, billingCycle)) {
+      if (isFreeCycle) {
         await createFree.mutateAsync({ membershipTierId: selectedTier.id, attributionRefId, ...landing });
-        if (opts.onComplete) opts.onComplete();
-        else if (typeof window !== "undefined") {
-          window.location.href = `${origin}${opts.freeReturnPath ?? "/i/account?tab=membership"}`;
-        }
+        finish(false);
         return;
       }
       const data = await createPaid.mutateAsync({
@@ -115,10 +228,7 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
       // 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"}`;
-        }
+        finish(false);
         return;
       }
 
@@ -156,10 +266,26 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     selectedTierId,
     setSelectedTierId,
     selectedTier,
+    selectTier,
+    backToTierList,
+    /** The tier the member is already on, so its card can be shown as taken. */
+    currentTierId,
+    /** True when pressing subscribe MOVES an existing subscription rather than starting one. */
+    isChange,
     billingCycle,
     setBillingCycle,
+    /** Which billing cycles this tier actually sells. */
+    cycles,
+    /** True when this cycle costs nothing, so `/subscriptions/free` is the call. */
+    isFreeCycle,
     customAmount,
     setCustomAmount,
+    /** The lowest amount this cycle may be bought at, in settlement-currency major units. */
+    minimumAmount,
+    /** The operator's ceiling for display, or null. Never applied to what is sent. */
+    maximumAmount,
+    /** Why the entered amount was refused, or null. Cleared on every edit path. */
+    amountRefusal,
     amount,
     subscribe,
     clientSecret,
@@ -178,5 +304,7 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     error,
     /** Call on the return page to reconcile the latest subscription. */
     confirmLatest,
+    /** Signals a completed paid payment (the Stripe `onSucceeded` leg). */
+    finish,
   };
 }

package/src/ui/index.ts

@@ -55,6 +55,8 @@ export { PresaleCodeField, type PresaleCodeFieldProps } from "./styled/PresaleCo
 export { MembershipCheckout, type MembershipCheckoutProps } from "./styled/MembershipCheckout";
 export { ForgeStripePayment } from "./payment/ForgeStripePayment";
 export { Cart, type CartProps } from "./styled/Cart";
+/** The page a cart-recovery email lands on. Drop in at `/i/checkout/resume`. */
+export { ResumeCart, type ResumeCartProps } from "./styled/ResumeCart";
 // The resolver is exported alongside the component because the Craft themes
 // are a separate rendering stack (Tailwind, not inline styles) and cannot use
 // the component — but the legacy `color`/`size` fallback must not diverge.
@@ -151,6 +153,24 @@ export { PodcastList, type PodcastListProps } from "./styled/PodcastList";
 export { PodcastShow, type PodcastShowProps } from "./styled/PodcastShow";
 export { PodcastEpisode, type PodcastEpisodeProps } from "./styled/PodcastEpisode";
 export { ReplayList, type ReplayListProps } from "./styled/ReplayList";
+// Live broadcasts. A replay is the recording of one of these; this is the half
+// that is on now. `BroadcastWatch` carries the paywall.
+export { LiveBroadcastList, type LiveBroadcastListProps } from "./styled/LiveBroadcastList";
+export { BroadcastWatch, type BroadcastWatchProps } from "./styled/BroadcastWatch";
+export { EndedBroadcast, type EndedBroadcastProps } from "./styled/broadcast/EndedBroadcast";
+export {
+  BroadcastPassValidation,
+  type BroadcastPassValidationProps,
+} from "./styled/broadcast/BroadcastPassValidation";
+export {
+  BroadcastTicketPurchase,
+  type BroadcastTicketPurchaseProps,
+} from "./styled/broadcast/BroadcastTicketPurchase";
+export {
+  BroadcastPlayer,
+  type BroadcastPlayerProps,
+  type BroadcastPlayerRenderProps,
+} from "./styled/broadcast/BroadcastPlayer";
 export { ConfirmSubscription, type ConfirmSubscriptionProps } from "./styled/ConfirmSubscription";
 export { LeadMagnet, type LeadMagnetProps } from "./styled/LeadMagnet";
 export { CohortPage, type CohortPageProps } from "./styled/CohortPage";
@@ -175,6 +195,24 @@ export {
   resolveUnitPrice,
   ticketSubtotals,
 } from "./format/pwyw";
+// Membership pricing: which billing cycles a tier sells, a pay-what-you-want
+// cycle's floor, and the ONE number that may be sent to the subscriptions API.
+// Settlement-currency MAJOR units throughout: convert for the screen, never for
+// the request.
+export {
+  cycleFloor,
+  cycleCeiling,
+  cycleIsOffered,
+  cycleIsFree,
+  offeredCycles,
+  defaultCycle,
+  defaultChosenAmount,
+  clampMembershipAmount,
+  resolveSubscriptionAmount,
+  refuseMembershipAmount,
+  type PricedTier,
+  type MembershipAmountRefusal,
+} from "./format/membershipPwyw";
 // 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

package/src/ui/media/CallHelpHint.tsx

@@ -0,0 +1,87 @@
+import { useId, useState, type ReactNode } from "react";
+import { HelpCircle } from "lucide-react";
+
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+
+/**
+ * The `?` that carries an explanation, instead of a paragraph that always shows.
+ *
+ * House design law: if a piece of text exists to EXPLAIN something, it goes
+ * behind a `?`. A call screen is the worst possible place to break that rule,
+ * because it is looked at while something is happening and every sentence that
+ * is not about right now is a sentence in the way.
+ *
+ * ## What is NOT help, and stays visible on this surface
+ *
+ * - the connection state, and what went wrong when it went wrong
+ * - a denied camera or microphone permission
+ * - the recording indicator, which is a consent signal
+ *
+ * ## Why Forge grows its own rather than importing `HelpHint`
+ *
+ * `@tribe-nest/frontend-shared` is not a dependency of this package and cannot
+ * become one: Forge publishes raw source and a creator site installs only
+ * Forge's declared dependencies, so an import of it would resolve here (npm
+ * workspaces symlink everything) and fail on every real site. See
+ * `_tests/publishedResolvability.spec.ts`. This is a disclosure built from a
+ * button and a span, which needs nothing.
+ */
+export type CallHelpHintProps = {
+  /** Accessible name. Say what it explains ("What does sharing send?"), never "help". */
+  label: string;
+  children: ReactNode;
+};
+
+export function CallHelpHint({ label, children }: CallHelpHintProps) {
+  const tokens = useThemeTokens();
+  const [open, setOpen] = useState(false);
+  const panelId = useId();
+
+  return (
+    <span style={{ position: "relative", display: "inline-flex", verticalAlign: "middle" }}>
+      <button
+        type="button"
+        aria-label={label}
+        aria-expanded={open}
+        aria-controls={panelId}
+        onClick={() => setOpen((was) => !was)}
+        style={{
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          background: "transparent",
+          border: "none",
+          padding: 0,
+          cursor: "pointer",
+          color: tokens.muted,
+        }}
+      >
+        <HelpCircle width={14} height={14} aria-hidden="true" />
+      </button>
+      {open && (
+        <span
+          id={panelId}
+          role="note"
+          style={{
+            position: "absolute",
+            bottom: "calc(100% + 6px)",
+            left: 0,
+            zIndex: 20,
+            width: "16rem",
+            padding: "0.5rem 0.625rem",
+            borderRadius: tokens.cornerRadius,
+            border: `1px solid ${tokens.border}`,
+            backgroundColor: tokens.surface,
+            color: tokens.text,
+            fontSize: "0.75rem",
+            lineHeight: 1.5,
+            textAlign: "left",
+            fontWeight: 400,
+          }}
+        >
+          {children}
+        </span>
+      )}
+    </span>
+  );
+}