@tribe-nest/forge 3.54.0 → 3.57.0

package/src/i18n/en.json

@@ -1,4 +1,19 @@
 {
+  "forge.account_dashboard.application_complete": "Complete your membership",
+  "forge.account_dashboard.application_complete_by": "Complete by {date}",
+  "forge.account_dashboard.application_status_approved": "Approved, finishing up",
+  "forge.account_dashboard.application_status_card_pending": "Card not confirmed yet",
+  "forge.account_dashboard.application_status_declined": "Not approved",
+  "forge.account_dashboard.application_status_expired": "Expired",
+  "forge.account_dashboard.application_status_joined": "Joined",
+  "forge.account_dashboard.application_status_payment_failed": "Approved: complete your membership",
+  "forge.account_dashboard.application_status_pending": "Application pending",
+  "forge.account_dashboard.application_status_withdrawn": "Withdrawn",
+  "forge.account_dashboard.application_submitted_on": "Applied on {date}",
+  "forge.account_dashboard.application_withdraw": "Withdraw",
+  "forge.account_dashboard.application_withdraw_error": "We couldn't withdraw your application. Please try again.",
+  "forge.account_dashboard.application_withdrawing": "Withdrawing…",
+  "forge.account_dashboard.applications_title": "Your applications",
   "forge.account_dashboard.billing_portal_error": "We couldn't open the billing page. Please contact us.",
   "forge.account_dashboard.billing_portal_opening": "Opening…",
   "forge.account_dashboard.booking_cancel_error": "We could not cancel this session. Please try again.",
@@ -16,6 +31,7 @@
   "forge.account_dashboard.cancel_confirm_paid": "It will not renew, and you keep your benefits until the end of the period you have paid for.",
   "forge.account_dashboard.cancel_confirm_paid_until": "It will not renew, and you keep your benefits until {date}.",
   "forge.account_dashboard.cancel_confirm_title": "Cancel your membership?",
+  "forge.account_dashboard.cancel_confirm_trial": "Your free trial will not turn into a paid membership. You keep your benefits until {date}, and nothing is charged.",
   "forge.account_dashboard.cancel_deletion": "Cancel Deletion",
   "forge.account_dashboard.cancel_session": "Cancel session",
   "forge.account_dashboard.cancel_ticket": "Cancel ticket",
@@ -29,6 +45,8 @@
   "forge.account_dashboard.courses_start": "Start",
   "forge.account_dashboard.courses_title": "Your courses",
   "forge.account_dashboard.current_password": "Current password",
+  "forge.account_dashboard.cycle_month": "month",
+  "forge.account_dashboard.cycle_year": "year",
   "forge.account_dashboard.data_export_description": "Export a copy of your personal data.",
   "forge.account_dashboard.data_section_title": "Your Data",
   "forge.account_dashboard.delete_section_title": "Delete Account",
@@ -50,6 +68,9 @@
   "forge.account_dashboard.membership_price": "{amount} / {cycle}",
   "forge.account_dashboard.membership_renews_on": "Renews on {date}",
   "forge.account_dashboard.membership_title": "Current Membership",
+  "forge.account_dashboard.membership_trial_cancelled": "Cancelled. Nothing will be charged.",
+  "forge.account_dashboard.membership_trial_then": "Then {amount} per {cycle} from {date}.",
+  "forge.account_dashboard.membership_trial_until": "Free trial until {date}",
   "forge.account_dashboard.new_password": "New password",
   "forge.account_dashboard.notifications_title": "Notification Types",
   "forge.account_dashboard.notify_chat_description": "Get notified when new chat messages arrive",
@@ -1003,8 +1024,16 @@
   "forge.film_watch.up_next": "Up next: {title}",
   "forge.film_watch.window_not_started": "Your window starts now.",
   "forge.forge_stripe_payment.authorize": "Authorize {amount}",
+  "forge.forge_stripe_payment.cycle_month": "month",
+  "forge.forge_stripe_payment.cycle_year": "year",
   "forge.forge_stripe_payment.deferred_charged_on_approval": "Your card is only charged if we approve your request.",
   "forge.forge_stripe_payment.deferred_hold_on_statement": "Until then a temporary hold will show on your statement.",
+  "forge.forge_stripe_payment.setup_charged_on_approval": "Nothing is charged now. We will only charge this card if we approve your application, and then at the amount shown ({amount}).",
+  "forge.forge_stripe_payment.setup_failed": "We couldn't save your card. Please try again.",
+  "forge.forge_stripe_payment.setup_incomplete": "Your card was not saved. Please try again.",
+  "forge.forge_stripe_payment.start_free_trial": "Start free trial",
+  "forge.forge_stripe_payment.submit_application": "Submit application",
+  "forge.forge_stripe_payment.trial_consent": "Nothing is charged today. {amount} per {cycle} from {date}. Cancel before then and you will not be charged.",
   "forge.forgot_password_form.back_to_login": "Back to login",
   "forge.forgot_password_form.email_label": "Email",
   "forge.forgot_password_form.email_placeholder": "Email",
@@ -1082,8 +1111,27 @@
   "forge.login_form.verify_submit": "Verify & Sign In",
   "forge.login_form.verify_title": "Verify your email",
   "forge.login_form.verifying": "Verifying…",
+  "forge.membership_checkout.accept_invite": "Accept invite",
   "forge.membership_checkout.amount_below_minimum": "Enter {minimum} or more.",
   "forge.membership_checkout.amount_not_positive": "Enter an amount greater than zero.",
+  "forge.membership_checkout.answer_required": "Please answer: {question}",
+  "forge.membership_checkout.application_approved_body": "Your application to {tier_name} was approved. Your membership is being set up.",
+  "forge.membership_checkout.application_approved_title": "You're approved",
+  "forge.membership_checkout.application_card_title": "Your card",
+  "forge.membership_checkout.application_closed_body": "Your application to {tier_name} is closed. Nothing was charged.",
+  "forge.membership_checkout.application_closed_title": "Application closed",
+  "forge.membership_checkout.application_declined_body": "Your application to {tier_name} was not approved. Nothing was charged.",
+  "forge.membership_checkout.application_declined_title": "Application not approved",
+  "forge.membership_checkout.application_received_body": "Thanks for applying to {tier_name}. We'll email you once we've reviewed your application.",
+  "forge.membership_checkout.application_received_paid_body": "Thanks for applying to {tier_name}. Nothing has been charged. If we approve your application, {amount} {cycle} will be charged to your card and your membership starts then.",
+  "forge.membership_checkout.application_received_title": "Application received",
+  "forge.membership_checkout.application_state_approved": "You're approved. We're finishing setting up your membership.",
+  "forge.membership_checkout.application_state_complete": "You're approved, but we couldn't charge your card. Complete your membership below.",
+  "forge.membership_checkout.application_state_declined": "Your application was not approved.",
+  "forge.membership_checkout.application_state_pending": "Your application is pending.",
+  "forge.membership_checkout.application_tier_full_body": "The last place was taken while your card was being saved, so your application was closed. Nothing was charged.",
+  "forge.membership_checkout.application_tier_full_title": "{tier_name} is full",
+  "forge.membership_checkout.apply": "Apply to join",
   "forge.membership_checkout.back": "Back",
   "forge.membership_checkout.billing_cycle_label": "Billing cycle",
   "forge.membership_checkout.billing_monthly": "Monthly",
@@ -1093,10 +1141,18 @@
   "forge.membership_checkout.billing_yearly_price": "Yearly ({amount})",
   "forge.membership_checkout.billing_yearly_pwyw": "Pay what you want from {amount}/yr",
   "forge.membership_checkout.choose_title": "Choose your membership",
+  "forge.membership_checkout.complete_membership": "Complete your membership",
   "forge.membership_checkout.confirm_change": "Confirm change",
   "forge.membership_checkout.current_plan": "Current plan",
   "forge.membership_checkout.empty_title": "No memberships available",
+  "forge.membership_checkout.field_required": "This field is required",
   "forge.membership_checkout.free": "Free",
+  "forge.membership_checkout.go_to_account": "Go to your account",
+  "forge.membership_checkout.invite_dead_body": "It may have expired, been used already, or been replaced by a newer invite. Ask us for a new one.",
+  "forge.membership_checkout.invite_dead_title": "This invite is no longer valid",
+  "forge.membership_checkout.invite_email_mismatch": "You're signed in as {signed_in_email}. Sign in with {email} to accept this invite.",
+  "forge.membership_checkout.invite_for_email": "This invite is for {email}.",
+  "forge.membership_checkout.invite_title": "You're invited to join {tier_name}",
   "forge.membership_checkout.more_benefits": "+{count} more",
   "forge.membership_checkout.no_tier_body": "Select a membership tier to continue.",
   "forge.membership_checkout.on_this_plan": "You are on this plan",
@@ -1108,15 +1164,28 @@
   "forge.membership_checkout.pwyw_charged_as": "You will be charged {amount}.",
   "forge.membership_checkout.pwyw_label": "How much would you like to pay?",
   "forge.membership_checkout.pwyw_min": "(minimum {amount})",
+  "forge.membership_checkout.questions_title": "A few questions",
+  "forge.membership_checkout.select_placeholder": "Select…",
   "forge.membership_checkout.select_tier": "Select this tier",
+  "forge.membership_checkout.start_free_trial": "Start free trial",
   "forge.membership_checkout.submit": "Subscribe",
   "forge.membership_checkout.submitting": "Processing…",
   "forge.membership_checkout.title": "Join {tier_name}",
   "forge.membership_checkout.total": "Total",
+  "forge.membership_checkout.trial_card_title": "Start your free trial",
+  "forge.membership_checkout.trial_line": "{days}-day free trial. Your first charge is on {date}.",
   "forge.membership_checkout.view_memberships": "View memberships",
   "forge.membership_tier_callout.benefits_label": "Benefits:",
+  "forge.membership_tier_callout.invite_for_email": "This invite is for {email}. Sign in or create an account with that address.",
   "forge.membership_tier_callout.join_title": "Join {tier_name}",
   "forge.membership_tier_callout.more_benefits": "+{count} more benefits",
+  "forge.membership_tiers.accept_invite": "Accept invite",
+  "forge.membership_tiers.application_approved": "Approved, finishing up",
+  "forge.membership_tiers.application_declined": "Not approved",
+  "forge.membership_tiers.application_payment_failed": "Approved: complete your membership",
+  "forge.membership_tiers.application_pending": "Application pending",
+  "forge.membership_tiers.apply": "Apply to join",
+  "forge.membership_tiers.complete_membership": "Complete your membership",
   "forge.membership_tiers.empty_title": "No membership tiers available.",
   "forge.membership_tiers.heading": "Membership",
   "forge.membership_tiers.price_free": "Free",
@@ -1125,6 +1194,11 @@
   "forge.membership_tiers.price_pwyw_yearly": "Pay what you want from {amount}/yr",
   "forge.membership_tiers.price_yearly": "{amount}/yr",
   "forge.membership_tiers.select": "Select",
+  "forge.membership_tiers.start_free_trial": "Start free trial",
+  "forge.membership_tiers.trial_badge": "{days}-day free trial",
+  "forge.membership_tiers.withdraw": "Withdraw application",
+  "forge.membership_tiers.withdraw_error": "We couldn't withdraw your application. Please try again.",
+  "forge.membership_tiers.withdrawing": "Withdrawing…",
   "forge.offer_button.buy_now": "Buy now",
   "forge.offer_button.confirm_email": "Confirm email",
   "forge.offer_button.continue_to_payment": "Continue to payment",

package/src/server/index.ts

@@ -46,6 +46,7 @@ import type {
   CollectionQueryParams,
   CollectionQuery,
   CollectionSearchResult,
+  PaginatedData,
 } from "../types/models";
 import { collectionParamsToQuery, splitCollectionQuery } from "../data/collectionParams";
 // SEO context for structured data. Pure functions over plain data, so this is
@@ -274,6 +275,18 @@ export async function fetchSiteBootstrap(opts: {
 }
 
 /** Fetch a single event by id or slug for SSR. */
+/**
+ * Every published event, for SSR of the events list.
+ *
+ * The list page had no server fetch at all: it rendered a spinner into the
+ * document and filled itself in from the browser, so a crawler saw an empty
+ * page and a fan saw a flash of nothing. It is the same endpoint the client
+ * hook reads, so the markup and the first client render agree.
+ */
+export async function fetchEventsServer(opts: { apiUrl: string; profileId?: string }): Promise<IEvent[]> {
+  return (await getJson<IEvent[]>(opts.apiUrl, `/public/events`, { profileId: opts.profileId })) ?? [];
+}
+
 export function fetchEventServer(opts: {
   apiUrl: string;
   profileId?: string;
@@ -351,6 +364,67 @@ export function buildMusicLinkHead(
 }
 
 /** Fetch a single product by id or slug for SSR. */
+/**
+ * The catalogue pages, server-rendered.
+ *
+ * Each of these list pages used to render a spinner into the document and
+ * fill itself in from the browser, so a crawler indexed an empty page and a
+ * fan saw nothing until the fetch landed. They are the pages search engines
+ * actually index, which makes an empty server render the expensive kind.
+ *
+ * Each mirrors its client hook exactly, same endpoint and same page size, so
+ * the markup and the first client render agree and nothing is fetched twice.
+ * An empty page is a real answer here (a creator who sells no courses), so a
+ * failed fetch resolves to an empty page rather than throwing.
+ */
+const emptyPage = <T,>(): PaginatedData<T> => ({
+  data: [],
+  total: 0,
+  hasNextPage: false,
+  page: 1,
+  nextPage: null,
+  pageSize: 10,
+});
+
+export async function fetchProductsServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+}): Promise<PaginatedData<IPublicProduct>> {
+  return (
+    (await getJson<PaginatedData<IPublicProduct>>(opts.apiUrl, `/public/products`, {
+      profileId: opts.profileId,
+      page: "1",
+      limit: "10",
+    })) ?? emptyPage<IPublicProduct>()
+  );
+}
+
+export async function fetchCoursesServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+}): Promise<PaginatedData<PublicCourse>> {
+  return (
+    (await getJson<PaginatedData<PublicCourse>>(opts.apiUrl, `/public/courses`, {
+      profileId: opts.profileId,
+      page: "1",
+      limit: "10",
+    })) ?? emptyPage<PublicCourse>()
+  );
+}
+
+export async function fetchCoachingProductsServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+}): Promise<PaginatedData<CoachingProduct>> {
+  return (
+    (await getJson<PaginatedData<CoachingProduct>>(opts.apiUrl, `/public/coaching/products`, {
+      profileId: opts.profileId,
+      page: "1",
+      limit: "10",
+    })) ?? emptyPage<CoachingProduct>()
+  );
+}
+
 export function fetchProductServer(opts: {
   apiUrl: string;
   profileId?: string;

package/src/server/platformEvents.generated.ts

@@ -308,6 +308,63 @@ export type PlatformEventMap = {
       unitPrice: number | null;
     }>;
   };
+  /**
+   * Membership application approved: An application was approved. `status` is `joined`, or `payment_failed` when the saved card was declined.
+   *
+   * Requires the `membership.application_approved` grant.
+   */
+  "membership_application.approved": {
+    applicationId: string;
+    membershipTierId: string | null;
+    status: string | null;
+    billingCycle: string | null;
+    amount: number | null;
+    currency: string | null;
+    membershipId: string | null;
+    applicant: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+  };
+  /**
+   * Membership application declined: An application to join a membership tier was declined.
+   *
+   * Requires the `membership.application_declined` grant.
+   */
+  "membership_application.declined": {
+    applicationId: string;
+    membershipTierId: string | null;
+    status: string | null;
+    billingCycle: string | null;
+    amount: number | null;
+    currency: string | null;
+    membershipId: string | null;
+    applicant: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+  };
+  /**
+   * Membership application submitted: Someone applied to join a membership tier that needs approval. Nothing is charged until approved.
+   *
+   * Requires the `membership.application_submitted` grant.
+   */
+  "membership_application.submitted": {
+    applicationId: string;
+    membershipTierId: string | null;
+    status: string | null;
+    billingCycle: string | null;
+    amount: number | null;
+    currency: string | null;
+    membershipId: string | null;
+    applicant: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+  };
   /**
    * Membership tier archived: A membership tier was archived and can no longer be joined.
    *
@@ -495,6 +552,9 @@ export const PLATFORM_EVENT_PERMISSIONS: Record<PlatformEventName, string> = {
   "event_ticket_request.declined": "events.read",
   "event_ticket_request.expired": "events.read",
   "event_ticket_request.submitted": "events.read",
+  "membership_application.approved": "membership.application_approved",
+  "membership_application.declined": "membership.application_declined",
+  "membership_application.submitted": "membership.application_submitted",
   "membership_tier.archived": "membership.tier_archived",
   "membership_tier.created": "membership.tier_created",
   "message.received": "contacts.read",

package/src/types/models.ts

@@ -307,6 +307,116 @@ export type MembershipTier = {
   welcomeMessageContent?: string | null;
   cancellationMessageSubject?: string | null;
   cancellationMessageContent?: string | null;
+  /**
+   * How a fan gets onto this tier (curated access). `open` is the ordinary
+   * checkout; `invite` needs a live invite for the signed-in email (and the
+   * tier is only listed when the request carried that invite's token);
+   * `application` means the fan applies and the business approves. Optional,
+   * because an older API build sends nothing, which reads as `open`.
+   */
+  joinMode?: MembershipJoinMode;
+  /**
+   * The signed-in fan's most recent open application on this tier (or their
+   * latest declined one), so the tier card can show where it stands instead of
+   * a join button. Absent when signed out or on an older API build.
+   */
+  myApplication?: MembershipTierMyApplication | null;
+  /**
+   * Free trial length in days on a paid tier (1 to 90), or null for no trial.
+   * A card is still collected; the first charge is on today + trialDays.
+   */
+  trialDays?: number | null;
+  /**
+   * False once the signed-in fan has had a trial with this business (one per
+   * fan per business, any tier). Absent when signed out: treat as eligible.
+   */
+  trialEligible?: boolean;
+  /**
+   * Questions the fan answers before paying or joining, on every join mode.
+   * Null or absent when the tier asks nothing.
+   */
+  questionnaire?: QuestionnaireQuestion[] | null;
+};
+
+/** How a fan gets onto a membership tier. */
+export type MembershipJoinMode = "open" | "invite" | "application";
+
+/**
+ * Where an application to a membership tier stands.
+ *
+ *   card_pending    paid tier: card step started, not confirmed. Not yet visible to the business.
+ *   pending         lodged and waiting for a decision; holds a seat
+ *   approved        approved; the subscription is being created
+ *   payment_failed  approved, but the saved card was declined; the fan can finish at checkout
+ *   joined          the membership exists
+ *   declined        not approved
+ *   withdrawn       withdrawn by the fan, or closed because the tier filled (`closedReason: "tier_full"`)
+ *   expired         the window to finish a failed payment lapsed
+ */
+export type MembershipApplicationStatus =
+  | "card_pending"
+  | "pending"
+  | "approved"
+  | "payment_failed"
+  | "joined"
+  | "declined"
+  | "withdrawn"
+  | "expired";
+
+/** The slice of an application the public tier list carries per tier. */
+export type MembershipTierMyApplication = {
+  id: string;
+  status: MembershipApplicationStatus;
+  paymentWindowExpiresAt: string | null;
+};
+
+export type MembershipApplication = {
+  id: string;
+  profileId: string;
+  membershipTierId: string;
+  /** Present on list payloads. */
+  membershipTierName?: string;
+  accountId: string;
+  status: MembershipApplicationStatus;
+  /** Null on a free tier. */
+  billingCycle: "month" | "year" | null;
+  /** What will be charged per cycle, in major units. Null on a free tier. */
+  amount: number | null;
+  currency: string | null;
+  /** A note from an older checkout. Current checkouts ask the tier's questions instead. */
+  message: string | null;
+  /** The fan's answers to the tier's questions, as given when applying. */
+  questionnaire?: QuestionnaireAnswer[] | null;
+  /** e.g. "Visa •••• 4242", set once the card is confirmed. */
+  instrumentLabel: string | null;
+  decidedAt: string | null;
+  decisionNote: string | null;
+  /** `"tier_full"`, `"expired"`, or the provider's decline reason on `payment_failed`. */
+  closedReason: string | null;
+  /** The deadline to finish a `payment_failed` application. */
+  paymentWindowExpiresAt: string | null;
+  membershipId: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+/** What `POST /public/membership-applications` answers. */
+export type ApplyForMembershipResult = {
+  application: MembershipApplication;
+  /** True on a paid tier until the card is confirmed. */
+  requiresCard: boolean;
+  /** A Stripe SetupIntent secret (`seti_..._secret_...`) when `requiresCard`. */
+  clientSecret: string | null;
+};
+
+/** What `GET /public/membership-invites/info` answers for a live invite. */
+export type MembershipInviteInfo = {
+  membershipTierId: string;
+  membershipTierName: string;
+  profileId: string;
+  /** The address the invite was sent to; the fan must be signed in with it. */
+  email: string;
+  expiresAt: string;
 };
 
 /**
@@ -346,6 +456,10 @@ export interface Membership {
   subscriptionAmount: number;
   subscriptionCurrency: string;
   billingCycle: string;
+  /** Set when the membership started with a free trial: when the first charge is due. */
+  trialEndsAt?: string | null;
+  /** The fan's answers to the tier's questions, as given when joining. */
+  questionnaire?: QuestionnaireAnswer[] | null;
 }
 
 // ---- Public auth -------------------------------------------------------------
@@ -911,6 +1025,19 @@ export type QuestionnaireQuestion = {
   optional?: boolean;
 };
 
+/**
+ * A fan's answer to one {@link QuestionnaireQuestion}, as sent at checkout and
+ * as stored on what the checkout created. `answer` is `""` for an optional
+ * question left blank.
+ */
+export type QuestionnaireAnswer = {
+  id: string;
+  question: string;
+  type: string;
+  options?: string[];
+  answer: string;
+};
+
 /**
  * S.6 — the cancellation terms a buyer is entitled to read BEFORE they pay.
  *

package/src/ui/headless/index.ts

@@ -100,6 +100,29 @@ export {
   type MembershipCheckoutStep,
   type BillingCycle,
 } from "./membership/useMembershipCheckout";
+// Curated access (invite-only and apply-to-join tiers): the pure decisions the
+// tier card, the checkout and the account page share.
+export {
+  canWithdrawMembershipApplication,
+  MEMBERSHIP_APPLICATION_MESSAGE_MAX,
+  membershipApplicationOutcome,
+  tierCardAction,
+  tierUsesApplication,
+  type MembershipApplicationOutcome,
+  type MembershipTierCardAction,
+} from "./membership/membershipApplication";
+export {
+  formatTrialDate,
+  isMembershipInTrial,
+  tierTrialDays,
+  trialEndDate,
+} from "./membership/membershipTrial";
+// Tier questionnaires: which questions a checkout asks and what it sends.
+export {
+  buildQuestionnaireAnswers,
+  firstMissingAnswer,
+  tierQuestionnaire,
+} from "./membership/membershipQuestionnaire";
 export { useInvoicePayment, type UseInvoicePaymentOptions } from "./invoice/useInvoicePayment";
 export { usePaymentLinkPayment, type UsePaymentLinkPaymentOptions } from "./paymentLink/usePaymentLinkPayment";
 export { useBroadcastWatch } from "./broadcast/useBroadcastWatch";

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

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest";
+import {
+  canWithdrawMembershipApplication,
+  membershipApplicationOutcome,
+  tierCardAction,
+  tierUsesApplication,
+} from "../membershipApplication";
+import type { MembershipApplicationStatus, MembershipTier } from "../../../../types/models";
+
+const app = (status: MembershipApplicationStatus) => ({ id: "app-1", status, paymentWindowExpiresAt: null });
+
+describe("tierCardAction", () => {
+  it("offers the tier in its own words when the fan has no application", () => {
+    expect(tierCardAction({})).toBe("join");
+    expect(tierCardAction({ joinMode: "open" })).toBe("join");
+    expect(tierCardAction({ joinMode: "invite" })).toBe("accept_invite");
+    expect(tierCardAction({ joinMode: "application" })).toBe("apply");
+    expect(tierCardAction({ joinMode: "application", myApplication: null })).toBe("apply");
+  });
+
+  it("shows where the fan's application stands instead of the button", () => {
+    expect(tierCardAction({ joinMode: "application", myApplication: app("pending") })).toBe("pending");
+    expect(tierCardAction({ joinMode: "application", myApplication: app("approved") })).toBe("approved");
+    expect(tierCardAction({ joinMode: "application", myApplication: app("payment_failed") })).toBe("complete");
+    expect(tierCardAction({ joinMode: "application", myApplication: app("declined") })).toBe("declined");
+  });
+
+  it("lets a fan pick an unfinished card step back up", () => {
+    expect(tierCardAction({ joinMode: "application", myApplication: app("card_pending") })).toBe("apply");
+  });
+});
+
+describe("tierUsesApplication", () => {
+  it("is true on an application tier", () => {
+    expect(tierUsesApplication({ joinMode: "application" })).toBe(true);
+    expect(tierUsesApplication({ joinMode: "application", myApplication: app("pending") })).toBe(true);
+  });
+
+  it("EXCEPTION: a payment_failed application completes through the ordinary paid checkout", () => {
+    expect(tierUsesApplication({ joinMode: "application", myApplication: app("payment_failed") })).toBe(false);
+  });
+
+  it("is false on open and invite tiers, and with no tier", () => {
+    expect(tierUsesApplication({ joinMode: "open" } as Pick<MembershipTier, "joinMode">)).toBe(false);
+    expect(tierUsesApplication({ joinMode: "invite" })).toBe(false);
+    expect(tierUsesApplication({})).toBe(false);
+    expect(tierUsesApplication(undefined)).toBe(false);
+  });
+});
+
+describe("canWithdrawMembershipApplication", () => {
+  it("allows withdrawing only before a decision", () => {
+    expect(canWithdrawMembershipApplication("card_pending")).toBe(true);
+    expect(canWithdrawMembershipApplication("pending")).toBe(true);
+    for (const status of ["approved", "payment_failed", "joined", "declined", "withdrawn", "expired"] as const) {
+      expect(canWithdrawMembershipApplication(status)).toBe(false);
+    }
+    expect(canWithdrawMembershipApplication(undefined)).toBe(false);
+  });
+});
+
+describe("membershipApplicationOutcome", () => {
+  const outcome = (status: MembershipApplicationStatus, closedReason: string | null = null, confirmed = false) =>
+    membershipApplicationOutcome({ status, closedReason }, confirmed);
+
+  it("is null before anything was submitted, and while the card step is still ahead", () => {
+    expect(membershipApplicationOutcome(null)).toBeNull();
+    expect(outcome("card_pending")).toBeNull();
+  });
+
+  it("reads a confirmed card the server has not caught up with as received", () => {
+    expect(outcome("card_pending", null, true)).toBe("received");
+  });
+
+  it("maps every other status", () => {
+    expect(outcome("pending")).toBe("received");
+    expect(outcome("approved")).toBe("approved");
+    expect(outcome("joined")).toBe("approved");
+    expect(outcome("payment_failed")).toBe("approved");
+    expect(outcome("declined")).toBe("declined");
+    expect(outcome("withdrawn", "tier_full")).toBe("tier_full");
+    expect(outcome("withdrawn")).toBe("closed");
+    expect(outcome("expired", "expired")).toBe("closed");
+  });
+});

package/src/ui/headless/membership/_tests/membershipCheckoutRefetch.spec.tsx

@@ -39,6 +39,8 @@ vi.mock("../../../../contexts/PublicAuthContext", async (importOriginal) => ({
 vi.mock("../../../../data/queries/useMembership", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../../../../data/queries/useMembership")>()),
   useGetMembershipTiers: () => ({ data: tiers, isLoading: false }),
+  useApplyForMembership: () => ({ mutateAsync: vi.fn(), isPending: false }),
+  useConfirmMembershipApplication: () => ({ mutateAsync: vi.fn(), isPending: false }),
 }));
 
 vi.mock("../../../../data/queries/useSubscriptions", async (importOriginal) => ({

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

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { formatTrialDate, isMembershipInTrial, tierTrialDays, trialEndDate } from "../membershipTrial";
+
+/**
+ * Free trials on paid membership tiers: who gets one, when it ends, and whether
+ * a membership is still inside it. Every surface reads these, so they are pinned
+ * as pure functions.
+ */
+describe("tierTrialDays", () => {
+  it("gives the tier's trial to an eligible fan, and to a signed-out visitor (no trialEligible)", () => {
+    expect(tierTrialDays({ trialDays: 14, trialEligible: true })).toBe(14);
+    expect(tierTrialDays({ trialDays: 7 })).toBe(7);
+  });
+
+  it("gives none to a fan who already had a trial with this business", () => {
+    expect(tierTrialDays({ trialDays: 14, trialEligible: false })).toBe(0);
+  });
+
+  it("gives none when the tier has no trial", () => {
+    expect(tierTrialDays({ trialDays: null })).toBe(0);
+    expect(tierTrialDays({ trialDays: 0 })).toBe(0);
+    expect(tierTrialDays({ trialDays: -3 })).toBe(0);
+    expect(tierTrialDays({})).toBe(0);
+    expect(tierTrialDays(undefined)).toBe(0);
+  });
+
+  it("gives none to a member with a live paid subscription (that is a tier change)", () => {
+    expect(
+      tierTrialDays({ trialDays: 14 }, { paymentProviderSubscriptionId: "sub_1", status: "active" }),
+    ).toBe(0);
+    // A lapsed or free membership does not block the trial.
+    expect(tierTrialDays({ trialDays: 14 }, { paymentProviderSubscriptionId: "sub_1", status: "cancelled" })).toBe(14);
+    expect(tierTrialDays({ trialDays: 14 }, { status: "active" })).toBe(14);
+  });
+});
+
+describe("trialEndDate", () => {
+  it("is today plus the trial days", () => {
+    const now = new Date("2026-09-17T10:00:00.000Z");
+    expect(trialEndDate(14, now).toISOString()).toBe("2026-10-01T10:00:00.000Z");
+  });
+});
+
+describe("isMembershipInTrial", () => {
+  const now = new Date("2026-09-17T10:00:00.000Z");
+  it("is true only while trialEndsAt is in the future", () => {
+    expect(isMembershipInTrial({ trialEndsAt: "2026-09-30T00:00:00.000Z" }, now)).toBe(true);
+    expect(isMembershipInTrial({ trialEndsAt: "2026-09-01T00:00:00.000Z" }, now)).toBe(false);
+    expect(isMembershipInTrial({ trialEndsAt: null }, now)).toBe(false);
+    expect(isMembershipInTrial({}, now)).toBe(false);
+    expect(isMembershipInTrial(undefined, now)).toBe(false);
+    expect(isMembershipInTrial({ trialEndsAt: "not a date" }, now)).toBe(false);
+  });
+});
+
+describe("formatTrialDate", () => {
+  it("formats per locale", () => {
+    expect(formatTrialDate("2026-10-01T12:00:00.000Z", "en")).toBe("Oct 1, 2026");
+    expect(formatTrialDate("2026-10-01T12:00:00.000Z", "de")).toContain("2026");
+  });
+});