@tribe-nest/forge 3.54.0 → 3.57.0

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

@@ -0,0 +1,109 @@
+import type { MembershipApplication, MembershipApplicationStatus, MembershipTier } from "../../../types/models";
+
+/**
+ * Curated access for memberships: the pure decisions behind the tier card, the
+ * checkout and the account page, so every surface reads a tier the same way.
+ */
+
+/** The longest applicant note the server accepts. */
+export const MEMBERSHIP_APPLICATION_MESSAGE_MAX = 1000;
+
+/**
+ * Does subscribing to this tier go through an APPLICATION?
+ *
+ * True for an `application` tier, except when the fan's own application is
+ * `payment_failed`: they were approved and the saved card was declined, so the
+ * ordinary paid checkout runs and the server accepts it. That is the "complete
+ * your membership" path.
+ */
+export function tierUsesApplication(tier: Pick<MembershipTier, "joinMode" | "myApplication"> | undefined): boolean {
+  if (!tier || tier.joinMode !== "application") return false;
+  return tier.myApplication?.status !== "payment_failed";
+}
+
+/**
+ * What the tier card offers instead of (or as) its join button.
+ *
+ *   join            an open tier
+ *   accept_invite   an invite tier (only listed when the visitor holds its invite)
+ *   apply           an application tier with nothing open
+ *   pending         an application waiting on a decision (withdrawable)
+ *   approved        approved, the membership is being set up
+ *   complete        approved but the card was declined: finish at checkout
+ *   declined        not approved; nothing to press
+ *
+ * A card-step-in-progress (`card_pending`) application reads as `apply`, so the
+ * fan can pick the card step up again; the server hands back the same one.
+ */
+export type MembershipTierCardAction =
+  | "join"
+  | "accept_invite"
+  | "apply"
+  | "pending"
+  | "approved"
+  | "complete"
+  | "declined";
+
+export function tierCardAction(tier: Pick<MembershipTier, "joinMode" | "myApplication">): MembershipTierCardAction {
+  const status = tier.myApplication?.status;
+  switch (status) {
+    case "pending":
+      return "pending";
+    case "approved":
+      return "approved";
+    case "payment_failed":
+      return "complete";
+    case "declined":
+      return "declined";
+    default:
+      break;
+  }
+  if (tier.joinMode === "invite") return "accept_invite";
+  if (tier.joinMode === "application") return "apply";
+  return "join";
+}
+
+/** Can the fan still withdraw an application in this state? */
+export function canWithdrawMembershipApplication(status: MembershipApplicationStatus | null | undefined): boolean {
+  return status === "card_pending" || status === "pending";
+}
+
+/**
+ * What the checkout shows after an application was submitted or confirmed.
+ *
+ *   received    lodged (or its card is confirmed and the server is catching up)
+ *   approved    already approved or joined (a repeat submit returned it)
+ *   tier_full   the last seat went while the card was being confirmed
+ *   declined    a repeat submit returned a declined application
+ *   closed      withdrawn or expired for any other reason
+ *
+ * `null` while the card step is still ahead (`card_pending` before confirm).
+ * `cardConfirmed` says the renderer reported success, in which case a
+ * `card_pending` answer only means the server has not heard from the provider
+ * yet (the webhook finishes it), so it reads as received.
+ */
+export type MembershipApplicationOutcome = "received" | "approved" | "tier_full" | "declined" | "closed";
+
+export function membershipApplicationOutcome(
+  application: Pick<MembershipApplication, "status" | "closedReason"> | null | undefined,
+  cardConfirmed = false,
+): MembershipApplicationOutcome | null {
+  if (!application) return null;
+  switch (application.status) {
+    case "card_pending":
+      return cardConfirmed ? "received" : null;
+    case "pending":
+      return "received";
+    case "approved":
+    case "payment_failed":
+    case "joined":
+      return "approved";
+    case "declined":
+      return "declined";
+    case "withdrawn":
+      return application.closedReason === "tier_full" ? "tier_full" : "closed";
+    case "expired":
+    default:
+      return "closed";
+  }
+}

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

@@ -0,0 +1,44 @@
+import type { MembershipTier, QuestionnaireAnswer, QuestionnaireQuestion } from "../../../types/models";
+
+/**
+ * Tier questionnaires: the pure decisions behind asking a tier's questions at
+ * checkout, so the hook and any custom renderer read them the same way.
+ */
+
+/**
+ * The questions the checkout asks for this tier, or `[]`.
+ *
+ * Every join mode asks (open, invite and application). The one exception is a
+ * fan completing an approved application whose card was declined
+ * (`myApplication.status === "payment_failed"`): they answered when they
+ * applied, and the server uses those answers.
+ */
+export function tierQuestionnaire(
+  tier: Pick<MembershipTier, "questionnaire" | "myApplication"> | undefined,
+): QuestionnaireQuestion[] {
+  if (!tier?.questionnaire?.length) return [];
+  if (tier.myApplication?.status === "payment_failed") return [];
+  return tier.questionnaire;
+}
+
+/** The first required question with a blank answer, or null when every required one is answered. */
+export function firstMissingAnswer(
+  questions: QuestionnaireQuestion[],
+  answers: Record<string, string>,
+): QuestionnaireQuestion | null {
+  return questions.find((q) => !q.optional && !(answers[q.id] ?? "").trim()) ?? null;
+}
+
+/** The request body's `questionnaire`: every question, in order, with its trimmed answer (`""` when blank). */
+export function buildQuestionnaireAnswers(
+  questions: QuestionnaireQuestion[],
+  answers: Record<string, string>,
+): QuestionnaireAnswer[] {
+  return questions.map((q) => ({
+    id: q.id,
+    question: q.question,
+    type: q.type,
+    ...(q.options ? { options: q.options } : {}),
+    answer: (answers[q.id] ?? "").trim(),
+  }));
+}

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

@@ -0,0 +1,53 @@
+import type { Membership, MembershipTier } from "../../../types/models";
+
+/**
+ * Free trials on paid membership tiers: the pure decisions behind the tier card,
+ * the checkout, the payment step and the account page, so every surface reads a
+ * trial the same way.
+ */
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * The trial this fan would get on this tier, in days, or 0 for none.
+ *
+ * A tier offers a trial when `trialDays` is positive. The fan gets it unless the
+ * server said `trialEligible: false` (they already had a trial with this
+ * business). Anonymous visitors carry no `trialEligible`, which reads as
+ * eligible: the server decides again at subscribe time.
+ *
+ * Pass the fan's current membership where it is known: a member with a live
+ * paid subscription picking another tier is CHANGING tier, which moves the
+ * subscription they have and starts no trial.
+ */
+export function tierTrialDays(
+  tier: Pick<MembershipTier, "trialDays" | "trialEligible"> | null | undefined,
+  membership?: Pick<Membership, "paymentProviderSubscriptionId" | "status"> | null,
+): number {
+  if (!tier) return 0;
+  if (membership?.paymentProviderSubscriptionId && membership.status === "active") return 0;
+  const days = typeof tier.trialDays === "number" ? Math.floor(tier.trialDays) : 0;
+  if (days <= 0) return 0;
+  return tier.trialEligible === false ? 0 : days;
+}
+
+/** When a trial of `days` started now ends: the date of the first charge. */
+export function trialEndDate(days: number, now: Date = new Date()): Date {
+  return new Date(now.getTime() + days * DAY_MS);
+}
+
+/** Is this membership still inside its free trial? */
+export function isMembershipInTrial(
+  membership: Pick<Membership, "trialEndsAt"> | null | undefined,
+  now: Date = new Date(),
+): boolean {
+  if (!membership?.trialEndsAt) return false;
+  const ends = new Date(membership.trialEndsAt).getTime();
+  return Number.isFinite(ends) && ends > now.getTime();
+}
+
+/** A short, locale-aware date for trial copy ("Oct 1, 2026" / "1. Okt. 2026"). */
+export function formatTrialDate(value: string | number | Date, locale: string = "en"): string {
+  const tag = locale === "de" ? "de-DE" : "en-US";
+  return new Date(value).toLocaleDateString(tag, { year: "numeric", month: "short", day: "numeric" });
+}

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

@@ -1,6 +1,11 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
-import { useGetMembershipTiers } from "../../../data/queries/useMembership";
+import {
+  readMembershipInviteFromUrl,
+  useApplyForMembership,
+  useConfirmMembershipApplication,
+  useGetMembershipTiers,
+} from "../../../data/queries/useMembership";
 import {
   useCreateSubscription,
   useCreateFreeSubscription,
@@ -14,7 +19,15 @@ import {
   type PaystackCheckoutOutcome,
   type PaystackCheckoutSession,
 } from "../../../utils/paystackCheckout";
-import type { MembershipTier } from "../../../types/models";
+import type { MembershipApplication, MembershipTier, QuestionnaireQuestion } from "../../../types/models";
+import { stripeIntentKind } from "../../payment/stripeIntentKind";
+import { tierTrialDays, trialEndDate } from "./membershipTrial";
+import { buildQuestionnaireAnswers, firstMissingAnswer, tierQuestionnaire } from "./membershipQuestionnaire";
+import {
+  membershipApplicationOutcome,
+  tierUsesApplication,
+  type MembershipApplicationOutcome,
+} from "./membershipApplication";
 import {
   cycleCeiling,
   cycleFloor,
@@ -54,6 +67,19 @@ export interface UseMembershipCheckoutOptions {
    * is no provider payment for the account page to reconcile.
    */
   onComplete?: (result: { requiresConfirmation: boolean }) => void;
+  /**
+   * A membership invite token, sent with the subscribe call and the tier list so
+   * an invite-only tier can be joined. Omitted, the `invite` search param of
+   * the current url is used; `null` sends none.
+   */
+  inviteToken?: string | null;
+  /**
+   * Where Stripe returns after a redirect-based card confirmation on an
+   * APPLICATION (a card that needed a bank redirect). Default
+   * `/i/account?tab=membership`, where the fan's applications are listed. The
+   * application id is appended as `confirmApplication`.
+   */
+  applicationReturnPath?: string;
 }
 
 const errMessage = (e: unknown) =>
@@ -80,10 +106,13 @@ const errMessage = (e: unknown) =>
  */
 export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const { user, refetchUser } = usePublicAuth();
-  const { data: tiers, isLoading } = useGetMembershipTiers();
+  const inviteToken = opts.inviteToken === undefined ? readMembershipInviteFromUrl() : (opts.inviteToken ?? undefined);
+  const { data: tiers, isLoading } = useGetMembershipTiers({ inviteToken: inviteToken ?? null });
   const createPaid = useCreateSubscription();
   const createFree = useCreateFreeSubscription();
   const confirmLatest = useConfirmLatestSubscription();
+  const applyMutation = useApplyForMembership();
+  const confirmApplicationMutation = useConfirmMembershipApplication();
 
   const [step, setStep] = useState<MembershipCheckoutStep>(opts.initialTierId ? "select" : "tier");
   const [selectedTierId, setSelectedTierId] = useState<string | undefined>(opts.initialTierId);
@@ -94,8 +123,20 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   /** 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);
+  /** Answers to the selected tier's questions, keyed by question id. */
+  const [questionnaireAnswers, setQuestionnaireAnswers] = useState<Record<string, string>>({});
+  /** Set once subscribe() was pressed on this tier, so blank required answers read as refused from then on. */
+  const [questionnaireAttempted, setQuestionnaireAttempted] = useState(false);
+  /** The application this checkout submitted, once it has. */
+  const [application, setApplication] = useState<MembershipApplication | null>(null);
+  /** Set once the card renderer reported the SetupIntent confirmed. */
+  const [cardConfirmed, setCardConfirmed] = useState(false);
+  /** The free trial the paid subscribe call started, if any. */
+  const [trial, setTrial] = useState<{ days: number; endsAt: string } | null>(null);
 
   const selectedTier = useMemo(() => tiers?.find((t) => t.id === selectedTierId), [tiers, selectedTierId]);
+  /** The questions this checkout asks: none when completing a `payment_failed` application. */
+  const questionnaire = useMemo(() => tierQuestionnaire(selectedTier), [selectedTier]);
 
   /**
    * Seed the cycle and the amount box from the tier itself.
@@ -109,6 +150,9 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
    * keying on that would wipe the amount a fan had just typed.
    */
   useEffect(() => {
+    // Answers belong to one tier's questions: a different tier starts blank.
+    setQuestionnaireAnswers({});
+    setQuestionnaireAttempted(false);
     if (!selectedTier) return;
     const cycle = defaultCycle(selectedTier);
     setBillingCycleState(cycle);
@@ -129,6 +173,9 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
 
   const selectTier = useCallback((tier: MembershipTier) => {
     setSelectedTierId(tier.id);
+    setApplication(null);
+    setTrial(null);
+    setCardConfirmed(false);
     setError(null);
     setAmountRefusal(null);
     setStep("select");
@@ -136,15 +183,36 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
 
   const backToTierList = useCallback(() => {
     setSelectedTierId(undefined);
+    setApplication(null);
+    setTrial(null);
+    setCardConfirmed(false);
     setError(null);
     setAmountRefusal(null);
     setStep("tier");
   }, []);
 
+  const setQuestionnaireAnswer = useCallback((questionId: string, value: string) => {
+    setQuestionnaireAnswers((prev) => ({ ...prev, [questionId]: value }));
+  }, []);
+  /**
+   * Derived, not stored: once a subscribe attempt was made it follows the
+   * answers, so the message beside the questions never names one the fan has
+   * just answered.
+   */
+  const questionnaireRefusal: QuestionnaireQuestion | null = questionnaireAttempted
+    ? firstMissingAnswer(questionnaire, questionnaireAnswers)
+    : null;
+
   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;
+  /**
+   * True when subscribe() APPLIES rather than joins: an `application` tier,
+   * except when the fan's own application is `payment_failed`, where the
+   * ordinary paid checkout completes the membership they were approved for.
+   */
+  const isApplication = tierUsesApplication(selectedTier);
 
   /**
    * What will be charged, and what will be SENT. A fixed tier ignores the
@@ -167,6 +235,14 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const isChange =
     !!membership?.paymentProviderSubscriptionId && membership.status === "active" && !isFreeCycle && !!selectedTier;
 
+  /**
+   * The free trial this fan would start on the selected tier, in days, or 0.
+   * Zero on a free cycle (nothing to trial) and on a tier change (the server
+   * moves an existing subscription, it does not start a new one). An
+   * application tier still reports it: approval starts the trial.
+   */
+  const trialDays = isFreeCycle || isChange ? 0 : tierTrialDays(selectedTier);
+
   /**
    * `await`ed by every caller, because of the refetch below.
    *
@@ -195,9 +271,14 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     }
   };
 
+  /** `{ questionnaire }` for the request body, or nothing when this checkout asks no questions. */
+  const questionnaireBody = () =>
+    questionnaire.length ? { questionnaire: buildQuestionnaireAnswers(questionnaire, questionnaireAnswers) } : {};
+
   const subscribe = async () => {
     setError(null);
     setAmountRefusal(null);
+    setTrial(null);
     if (!selectedTier) {
       setError("Select a membership tier.");
       return;
@@ -210,17 +291,31 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     // (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);
+    // Same for the tier's questions: a blank required answer is refused beside
+    // the questions, before any request, rather than as a 400 from the server.
+    const missing = firstMissingAnswer(questionnaire, questionnaireAnswers);
+    setQuestionnaireAttempted(true);
+    if (refusal) setAmountRefusal(refusal);
+    if (refusal || missing) return;
+    const origin = typeof window !== "undefined" ? window.location.origin : "";
+    if (isApplication) {
+      await submitApplication(origin);
       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() ?? {};
+    const invite = inviteToken ? { inviteToken } : {};
+    const answers = questionnaireBody();
     try {
       if (isFreeCycle) {
-        await createFree.mutateAsync({ membershipTierId: selectedTier.id, attributionRefId, ...landing });
+        await createFree.mutateAsync({
+          membershipTierId: selectedTier.id,
+          attributionRefId,
+          ...landing,
+          ...invite,
+          ...answers,
+        });
         await finish(false);
         return;
       }
@@ -231,6 +326,8 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
         returnUrl,
         attributionRefId,
         ...landing,
+        ...invite,
+        ...answers,
       });
 
       // A member who already subscribes is CHANGING TIER: the server moved their
@@ -265,6 +362,10 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
         return;
       }
 
+      // A trial saves the card instead of charging it: the secret is a
+      // SetupIntent, the renderer confirms it with `confirmSetup`, and the return
+      // page's `confirmLatest` activates the membership like any paid one.
+      setTrial(data.trial ?? null);
       setClientSecret(data.clientSecret);
       setStep("payment");
     } catch (e) {
@@ -272,6 +373,69 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     }
   };
 
+  /**
+   * Apply to an `application` tier. Free: the application is lodged and the
+   * outcome is set. Paid: the server hands back a SetupIntent secret, the step
+   * moves to "payment" and the renderer saves the card; `confirmApplication()`
+   * runs after it succeeds. Nothing is charged until the business approves.
+   */
+  const applicationReturnBase = opts.applicationReturnPath ?? "/i/account?tab=membership";
+  const submitApplication = async (origin: string) => {
+    if (!selectedTier) return;
+    try {
+      const data = await applyMutation.mutateAsync({
+        membershipTierId: selectedTier.id,
+        ...(isFreeCycle ? {} : { billingCycle, amount }),
+        ...questionnaireBody(),
+        returnUrl: `${origin}${applicationReturnBase}`,
+      });
+      setApplication(data.application);
+      setCardConfirmed(false);
+      if (data.requiresCard && data.clientSecret) {
+        setClientSecret(data.clientSecret);
+        setStep("payment");
+      }
+    } catch (e) {
+      setError(errMessage(e));
+    }
+  };
+
+  /** Call after the card renderer confirmed the SetupIntent. Idempotent on the server. */
+  const confirmApplication = async () => {
+    if (!application) return;
+    setError(null);
+    setCardConfirmed(true);
+    try {
+      const data = await confirmApplicationMutation.mutateAsync({ applicationId: application.id });
+      setApplication(data.application);
+    } catch (e) {
+      setError(errMessage(e));
+    }
+  };
+
+  const applicationOutcome: MembershipApplicationOutcome | null = membershipApplicationOutcome(
+    application,
+    cardConfirmed,
+  );
+  /**
+   * What the payment step is confirming, read off the SECRET, not off the tier:
+   * a `seti_` secret is a card save whatever started it (an application, or a
+   * paid subscription that opens with a free trial), and confirming it as a
+   * payment fails with an error the fan cannot act on.
+   */
+  const paymentKind: "setup" | "payment" = paystackSession ? "payment" : stripeIntentKind(clientSecret);
+  /** Why a card is being saved: `application`, `trial`, or null when it is a payment. */
+  const setupPurpose: "application" | "trial" | null =
+    paymentKind !== "setup" ? null : isApplication && application ? "application" : "trial";
+  /** When the first charge falls: the server's date once subscribed, else today + trialDays. */
+  const trialEndsAt: string | null = trial?.endsAt ?? (trialDays > 0 ? trialEndDate(trialDays).toISOString() : null);
+
+  const applicationReturnUrl = application
+    ? `${typeof window !== "undefined" ? window.location.origin : ""}${applicationReturnBase}${
+        applicationReturnBase.includes("?") ? "&" : "?"
+      }confirmApplication=${encodeURIComponent(application.id)}`
+    : undefined;
+
   return {
     tiers,
     isLoading,
@@ -314,11 +478,66 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
             onError: (message) => setError(message ?? "The payment could not be completed. Please try again."),
           })
         : Promise.resolve("unavailable" as PaystackCheckoutOutcome),
-    isProcessing: createPaid.isPending || createFree.isPending,
+    isProcessing:
+      createPaid.isPending || createFree.isPending || applyMutation.isPending || confirmApplicationMutation.isPending,
     error,
     /** Call on the return page to reconcile the latest subscription. */
     confirmLatest,
     /** Signals a completed paid payment (the Stripe `onSucceeded` leg). */
     finish,
+    /** The invite token this checkout forwards, if any. */
+    inviteToken,
+    /** True when subscribe() applies to the tier instead of joining it. */
+    isApplication,
+    /**
+     * The selected tier's questions, asked before paying, joining or applying.
+     * Empty when the tier asks none, and when completing an approved
+     * application whose card was declined (its answers were already given).
+     */
+    questionnaire,
+    /** The answers so far, keyed by question id. Reset when the tier changes. */
+    questionnaireAnswers,
+    /** Record the answer to one question. */
+    setQuestionnaireAnswer,
+    /**
+     * The first required question left blank, once subscribe() refused for it;
+     * null otherwise. Nothing was sent. Show it beside the questions.
+     */
+    questionnaireRefusal,
+    /** The application this checkout submitted, as the server last returned it. */
+    application,
+    /**
+     * Where the application stands once submitted: `received`, `approved`,
+     * `tier_full`, `declined` or `closed`; null before submitting and while the
+     * card step is still ahead.
+     */
+    applicationOutcome,
+    /**
+     * `"setup"` while the payment step is saving a card for an application
+     * (the secret is a SetupIntent), else `"payment"`.
+     */
+    paymentKind,
+    /** Why the payment step saves a card: `application`, `trial`, or null when it charges. */
+    setupPurpose,
+    /**
+     * The free trial the selected tier gives THIS fan, in days (0 for none: no
+     * trial on the tier, already had one with this business, a free cycle, or a
+     * tier change).
+     */
+    trialDays,
+    /** The trial the subscribe call started (`{ days, endsAt }`), or null. */
+    trial,
+    /** When the first charge falls for a trial (ISO), or null without one. */
+    trialEndsAt,
+    /**
+     * Call once the card renderer reports success. An application's saved card
+     * goes to `confirmApplication`; a paid subscription (charged, or a trial's
+     * saved card) finishes to the return page, which runs `confirmLatest`.
+     */
+    onPaymentSucceeded: () => (setupPurpose === "application" ? confirmApplication() : finish(true)),
+    /** The renderer's `returnUrl` for an application's card step. */
+    applicationReturnUrl,
+    /** Call after the card renderer confirmed an application's SetupIntent. */
+    confirmApplication,
   };
 }

package/src/ui/index.ts

@@ -41,6 +41,7 @@ export {
   usePaymentRenderer,
   type PaymentRenderer,
   type PaymentRenderProps,
+  type PaymentTrial,
 } from "./payment/ForgePaymentProvider";
 
 // Re-export the headless layer so consumers can reach both tiers from `forge/ui`.
@@ -82,6 +83,14 @@ export {
   isManualConfirmSuccess,
   MANUAL_CONFIRM_SUCCESS_STATUSES,
 } from "./payment/stripeConfirmOutcome";
+// For a custom payment renderer: a SetupIntent secret (an application to a
+// membership tier, or a paid membership starting with a free trial) saves the card through `confirmSetup` instead of charging it.
+export {
+  isSetupConfirmSuccess,
+  SETUP_CONFIRM_SUCCESS_STATUSES,
+  stripeIntentKind,
+  type StripeIntentKind,
+} from "./payment/stripeIntentKind";
 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";

package/src/ui/payment/ForgePaymentProvider.tsx

@@ -31,6 +31,20 @@ export interface PaymentRenderProps {
    * nothing until approval. Only sent with `settlement: "deferred"`.
    */
   deferredStrategy?: DeferredChargeStrategy | null;
+  /**
+   * Set when a SetupIntent secret starts a FREE TRIAL on a paid membership
+   * rather than an application. The built-in renderer then reads "Start free
+   * trial" and says under the button that nothing is charged today, what is
+   * charged per cycle, and from which date. Ignored on a payment secret.
+   */
+  trial?: PaymentTrial | null;
+}
+
+/** The free trial a card save starts: when the first charge falls, and its cycle. */
+export interface PaymentTrial {
+  /** ISO date of the first charge. */
+  endsAt: string;
+  billingCycle: "month" | "year";
 }
 
 export type PaymentRenderer = (props: PaymentRenderProps) => ReactNode;