@tribe-nest/forge 3.53.0 → 3.57.0

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");
+  });
+});

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

@@ -0,0 +1,253 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useMembershipCheckout } from "../useMembershipCheckout";
+import type { MembershipApplication, MembershipTier } from "../../../../types/models";
+
+/**
+ * Curated access in the headless checkout: an application tier APPLIES instead
+ * of subscribing (free lodges it, paid saves a card through a SetupIntent and
+ * confirms), a `payment_failed` application completes through the ordinary
+ * paid subscribe, and an invite token rides on the tier list and on both
+ * subscribe calls. Every seam is mocked at the module boundary.
+ */
+
+const auth = vi.hoisted(() => ({
+  user: { id: "account-1", email: "fan@example.com", membership: undefined as unknown },
+  refetchUser: vi.fn(async () => {}),
+}));
+
+const api = vi.hoisted(() => ({
+  tiersOptions: [] as unknown[],
+  apply: vi.fn(async (_body: Record<string, unknown>) => ({}) as Record<string, unknown>),
+  confirm: vi.fn(async (_body: Record<string, unknown>) => ({}) as Record<string, unknown>),
+  createFree: vi.fn(async (_body: Record<string, unknown>) => ({})),
+  createPaid: vi.fn(async (_body: Record<string, unknown>) => ({}) as Record<string, unknown>),
+}));
+
+let tiers: MembershipTier[] = [];
+
+vi.mock("../../../../contexts/PublicAuthContext", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../../contexts/PublicAuthContext")>()),
+  usePublicAuth: () => ({ user: auth.user, refetchUser: auth.refetchUser }),
+}));
+
+vi.mock("../../../../data/queries/useMembership", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../../data/queries/useMembership")>()),
+  useGetMembershipTiers: (opts: unknown) => {
+    api.tiersOptions.push(opts);
+    return { data: tiers, isLoading: false };
+  },
+  useApplyForMembership: () => ({ mutateAsync: api.apply, isPending: false }),
+  useConfirmMembershipApplication: () => ({ mutateAsync: api.confirm, isPending: false }),
+}));
+
+vi.mock("../../../../data/queries/useSubscriptions", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../../data/queries/useSubscriptions")>()),
+  useCreateSubscription: () => ({ mutateAsync: api.createPaid, isPending: false }),
+  useCreateFreeSubscription: () => ({ mutateAsync: api.createFree, isPending: false }),
+  useConfirmLatestSubscription: () => ({ mutateAsync: vi.fn(), isPending: false }),
+}));
+
+const tier = (overrides: Partial<MembershipTier>): MembershipTier => ({
+  id: "tier-1",
+  name: "Inner Circle",
+  description: "",
+  payWhatYouWant: false,
+  benefits: [],
+  ...overrides,
+});
+
+const application = (overrides: Partial<MembershipApplication> = {}): MembershipApplication => ({
+  id: "app-1",
+  profileId: "profile-1",
+  membershipTierId: "tier-1",
+  accountId: "account-1",
+  status: "pending",
+  billingCycle: null,
+  amount: null,
+  currency: null,
+  message: null,
+  instrumentLabel: null,
+  decidedAt: null,
+  decisionNote: null,
+  closedReason: null,
+  paymentWindowExpiresAt: null,
+  membershipId: null,
+  createdAt: "2026-09-17T00:00:00.000Z",
+  updatedAt: "2026-09-17T00:00:00.000Z",
+  ...overrides,
+});
+
+beforeEach(() => {
+  api.tiersOptions.length = 0;
+  api.apply.mockReset();
+  api.confirm.mockReset();
+  api.createFree.mockReset();
+  api.createFree.mockResolvedValue({});
+  api.createPaid.mockReset();
+  auth.refetchUser.mockClear();
+  window.history.replaceState(null, "", "/i/membership/checkout");
+});
+
+const onComplete = vi.fn();
+
+describe("application tiers: subscribe() applies", () => {
+  it("free tier: lodges the application and shows it received, no subscription", async () => {
+    tiers = [tier({ id: "tier-free", priceMonthly: 0, joinMode: "application" })];
+    api.apply.mockResolvedValue({ application: application({ membershipTierId: "tier-free" }), requiresCard: false, clientSecret: null });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-free", onComplete }));
+
+    expect(result.current.isApplication).toBe(true);
+    // The free-text note is gone from the checkout: the tier's questions replaced it.
+    expect(result.current).not.toHaveProperty("setApplicationMessage");
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.apply).toHaveBeenCalledTimes(1);
+    const body = api.apply.mock.calls[0][0];
+    expect(body).toMatchObject({ membershipTierId: "tier-free" });
+    expect(body).not.toHaveProperty("message");
+    // A tier without questions sends none.
+    expect(body).not.toHaveProperty("questionnaire");
+    // A free tier sends no cycle and no amount.
+    expect(body).not.toHaveProperty("billingCycle");
+    expect(body).not.toHaveProperty("amount");
+    expect(api.createFree).not.toHaveBeenCalled();
+    expect(api.createPaid).not.toHaveBeenCalled();
+    expect(result.current.applicationOutcome).toBe("received");
+    expect(result.current.step).toBe("select");
+    expect(onComplete).not.toHaveBeenCalled();
+  });
+
+  it("paid tier: saves the card through a SetupIntent, then confirms, then shows it received", async () => {
+    tiers = [tier({ priceMonthly: 12, joinMode: "application" })];
+    api.apply.mockResolvedValue({
+      application: application({ status: "card_pending", billingCycle: "month", amount: 12, currency: "USD" }),
+      requiresCard: true,
+      clientSecret: "seti_123_secret_abc",
+    });
+    api.confirm.mockResolvedValue({
+      application: application({ status: "pending", billingCycle: "month", amount: 12, currency: "USD" }),
+    });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1", onComplete }));
+
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.apply.mock.calls[0][0]).toMatchObject({ membershipTierId: "tier-1", billingCycle: "month", amount: 12 });
+    expect(api.createPaid).not.toHaveBeenCalled();
+    expect(result.current.step).toBe("payment");
+    expect(result.current.clientSecret).toBe("seti_123_secret_abc");
+    expect(result.current.paymentKind).toBe("setup");
+    // The card step is still ahead: nothing to announce yet.
+    expect(result.current.applicationOutcome).toBeNull();
+    expect(result.current.applicationReturnUrl).toContain("confirmApplication=app-1");
+
+    await act(async () => {
+      await result.current.confirmApplication();
+    });
+
+    expect(api.confirm).toHaveBeenCalledWith({ applicationId: "app-1" });
+    expect(result.current.application?.status).toBe("pending");
+    expect(result.current.applicationOutcome).toBe("received");
+    expect(onComplete).not.toHaveBeenCalled();
+  });
+
+  it("surfaces a server refusal in the error slot", async () => {
+    tiers = [tier({ priceMonthly: 0, joinMode: "application" })];
+    api.apply.mockRejectedValue({ response: { data: { message: "This membership is full." } } });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1" }));
+
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(result.current.error).toBe("This membership is full.");
+    expect(result.current.applicationOutcome).toBeNull();
+  });
+
+  it("closes as tier_full when the last seat went while the card was saved", async () => {
+    tiers = [tier({ priceMonthly: 12, joinMode: "application" })];
+    api.apply.mockResolvedValue({
+      application: application({ status: "card_pending" }),
+      requiresCard: true,
+      clientSecret: "seti_1_secret_2",
+    });
+    api.confirm.mockResolvedValue({ application: application({ status: "withdrawn", closedReason: "tier_full" }) });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1" }));
+
+    await act(async () => {
+      await result.current.subscribe();
+    });
+    await act(async () => {
+      await result.current.confirmApplication();
+    });
+
+    expect(result.current.applicationOutcome).toBe("tier_full");
+  });
+
+  it("EXCEPTION: a payment_failed application runs the ordinary paid subscribe", async () => {
+    tiers = [
+      tier({
+        priceMonthly: 12,
+        joinMode: "application",
+        myApplication: { id: "app-1", status: "payment_failed", paymentWindowExpiresAt: "2026-09-24T00:00:00.000Z" },
+      }),
+    ];
+    api.createPaid.mockResolvedValue({ requiresPayment: true, clientSecret: "pi_1_secret_2" });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1" }));
+
+    expect(result.current.isApplication).toBe(false);
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.apply).not.toHaveBeenCalled();
+    expect(api.createPaid).toHaveBeenCalledTimes(1);
+    expect(result.current.paymentKind).toBe("payment");
+    expect(result.current.clientSecret).toBe("pi_1_secret_2");
+  });
+});
+
+describe("invite tokens", () => {
+  it("reads the invite off the url and forwards it to the tier list and the paid subscribe", async () => {
+    window.history.replaceState(null, "", "/i/membership/checkout?membershipTierId=tier-1&invite=tok-abc");
+    tiers = [tier({ priceMonthly: 12, joinMode: "invite" })];
+    api.createPaid.mockResolvedValue({ requiresPayment: true, clientSecret: "pi_1_secret_2" });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1" }));
+
+    expect(result.current.inviteToken).toBe("tok-abc");
+    expect(api.tiersOptions.at(-1)).toEqual({ inviteToken: "tok-abc" });
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.createPaid.mock.calls[0][0]).toMatchObject({ membershipTierId: "tier-1", inviteToken: "tok-abc" });
+  });
+
+  it("forwards an explicit token on a free join", async () => {
+    tiers = [tier({ priceMonthly: 0, joinMode: "invite" })];
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1", inviteToken: "tok-free", onComplete }));
+
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.createFree.mock.calls[0][0]).toMatchObject({ membershipTierId: "tier-1", inviteToken: "tok-free" });
+  });
+
+  it("sends no token when there is none", async () => {
+    tiers = [tier({ priceMonthly: 0 })];
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1", onComplete }));
+
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.tiersOptions.at(-1)).toEqual({ inviteToken: null });
+    expect(api.createFree.mock.calls[0][0]).not.toHaveProperty("inviteToken");
+  });
+});

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

@@ -0,0 +1,241 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useMembershipCheckout } from "../useMembershipCheckout";
+import { buildQuestionnaireAnswers, firstMissingAnswer, tierQuestionnaire } from "../membershipQuestionnaire";
+import type { MembershipTier, QuestionnaireQuestion } from "../../../../types/models";
+
+/**
+ * Tier questionnaires in the headless checkout: every join mode (open free,
+ * open paid, application) asks the tier's questions, refuses a blank required
+ * answer before any request, and sends the answers in the body. Completing a
+ * `payment_failed` application asks nothing and sends nothing.
+ */
+
+const auth = vi.hoisted(() => ({
+  user: { id: "account-1", email: "fan@example.com", membership: undefined as unknown },
+  refetchUser: vi.fn(async () => {}),
+}));
+
+const api = vi.hoisted(() => ({
+  apply: vi.fn(async (_body: Record<string, unknown>) => ({}) as Record<string, unknown>),
+  createFree: vi.fn(async (_body: Record<string, unknown>) => ({})),
+  createPaid: vi.fn(async (_body: Record<string, unknown>) => ({}) as Record<string, unknown>),
+}));
+
+let tiers: MembershipTier[] = [];
+
+vi.mock("../../../../contexts/PublicAuthContext", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../../contexts/PublicAuthContext")>()),
+  usePublicAuth: () => ({ user: auth.user, refetchUser: auth.refetchUser }),
+}));
+
+vi.mock("../../../../data/queries/useMembership", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../../data/queries/useMembership")>()),
+  useGetMembershipTiers: () => ({ data: tiers, isLoading: false }),
+  useApplyForMembership: () => ({ mutateAsync: api.apply, isPending: false }),
+  useConfirmMembershipApplication: () => ({ mutateAsync: vi.fn(), isPending: false }),
+}));
+
+vi.mock("../../../../data/queries/useSubscriptions", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../../data/queries/useSubscriptions")>()),
+  useCreateSubscription: () => ({ mutateAsync: api.createPaid, isPending: false }),
+  useCreateFreeSubscription: () => ({ mutateAsync: api.createFree, isPending: false }),
+  useConfirmLatestSubscription: () => ({ mutateAsync: vi.fn(), isPending: false }),
+}));
+
+const questions: QuestionnaireQuestion[] = [
+  { id: "q-why", question: "Why do you want to join?", type: "textarea" },
+  { id: "q-city", question: "Which city?", type: "select", options: ["Berlin", "Lagos"] },
+  { id: "q-handle", question: "Instagram handle", type: "text", optional: true },
+];
+
+/** Exactly what the server is sent when the fan answers the two required questions. */
+const expectedAnswers = [
+  { id: "q-why", question: "Why do you want to join?", type: "textarea", answer: "Long-time listener" },
+  { id: "q-city", question: "Which city?", type: "select", options: ["Berlin", "Lagos"], answer: "Lagos" },
+  { id: "q-handle", question: "Instagram handle", type: "text", answer: "" },
+];
+
+const tier = (overrides: Partial<MembershipTier>): MembershipTier => ({
+  id: "tier-1",
+  name: "Inner Circle",
+  description: "",
+  payWhatYouWant: false,
+  benefits: [],
+  questionnaire: questions,
+  ...overrides,
+});
+
+const onComplete = vi.fn();
+
+beforeEach(() => {
+  api.apply.mockReset();
+  api.createFree.mockReset();
+  api.createFree.mockResolvedValue({});
+  api.createPaid.mockReset();
+  onComplete.mockClear();
+  window.history.replaceState(null, "", "/i/membership/checkout");
+});
+
+function answerRequired(result: { current: ReturnType<typeof useMembershipCheckout> }) {
+  act(() => result.current.setQuestionnaireAnswer("q-why", "  Long-time listener  "));
+  act(() => result.current.setQuestionnaireAnswer("q-city", "Lagos"));
+}
+
+describe("answers are sent on every join call", () => {
+  it("open free tier: /subscriptions/free carries the answers", async () => {
+    tiers = [tier({ priceMonthly: 0 })];
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1", onComplete }));
+
+    expect(result.current.questionnaire).toEqual(questions);
+    answerRequired(result);
+    expect(result.current.questionnaireAnswers).toEqual({ "q-why": "  Long-time listener  ", "q-city": "Lagos" });
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.createFree).toHaveBeenCalledTimes(1);
+    expect(api.createFree.mock.calls[0][0]).toMatchObject({ membershipTierId: "tier-1" });
+    expect(api.createFree.mock.calls[0][0].questionnaire).toEqual(expectedAnswers);
+    expect(result.current.questionnaireRefusal).toBeNull();
+  });
+
+  it("open paid tier: /subscriptions carries the answers", async () => {
+    tiers = [tier({ priceMonthly: 12 })];
+    api.createPaid.mockResolvedValue({ requiresPayment: true, clientSecret: "pi_1_secret_2" });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1" }));
+
+    answerRequired(result);
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.createPaid).toHaveBeenCalledTimes(1);
+    expect(api.createPaid.mock.calls[0][0]).toMatchObject({ membershipTierId: "tier-1", amount: 12, billingCycle: "month" });
+    expect(api.createPaid.mock.calls[0][0].questionnaire).toEqual(expectedAnswers);
+    expect(result.current.step).toBe("payment");
+  });
+
+  it("invite tier: /subscriptions carries the answers and the token", async () => {
+    tiers = [tier({ priceMonthly: 12, joinMode: "invite" })];
+    api.createPaid.mockResolvedValue({ requiresPayment: true, clientSecret: "pi_1_secret_2" });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1", inviteToken: "tok-1" }));
+
+    answerRequired(result);
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.createPaid.mock.calls[0][0]).toMatchObject({ inviteToken: "tok-1", questionnaire: expectedAnswers });
+  });
+
+  it("application tier: /membership-applications carries the answers and no message", async () => {
+    tiers = [tier({ priceMonthly: 0, joinMode: "application" })];
+    api.apply.mockResolvedValue({
+      application: { id: "app-1", status: "pending", closedReason: null },
+      requiresCard: false,
+      clientSecret: null,
+    });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1" }));
+
+    answerRequired(result);
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.apply).toHaveBeenCalledTimes(1);
+    const body = api.apply.mock.calls[0][0];
+    expect(body.questionnaire).toEqual(expectedAnswers);
+    expect(body).not.toHaveProperty("message");
+    expect(result.current.applicationOutcome).toBe("received");
+  });
+});
+
+describe("a blank required answer is refused before any request", () => {
+  it.each([
+    ["open free", { priceMonthly: 0 }],
+    ["open paid", { priceMonthly: 12 }],
+    ["application", { priceMonthly: 12, joinMode: "application" as const }],
+  ])("%s: nothing is sent and the first blank question is named", async (_label, overrides) => {
+    tiers = [tier(overrides)];
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1", onComplete }));
+
+    // Whitespace is blank.
+    act(() => result.current.setQuestionnaireAnswer("q-why", "   "));
+    expect(result.current.questionnaireRefusal).toBeNull();
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.createFree).not.toHaveBeenCalled();
+    expect(api.createPaid).not.toHaveBeenCalled();
+    expect(api.apply).not.toHaveBeenCalled();
+    expect(onComplete).not.toHaveBeenCalled();
+    expect(result.current.questionnaireRefusal?.id).toBe("q-why");
+
+    // The refusal follows the answers: it moves on, then clears.
+    act(() => result.current.setQuestionnaireAnswer("q-why", "Because"));
+    expect(result.current.questionnaireRefusal?.id).toBe("q-city");
+    act(() => result.current.setQuestionnaireAnswer("q-city", "Berlin"));
+    expect(result.current.questionnaireRefusal).toBeNull();
+  });
+});
+
+describe("completing an approved application whose card was declined", () => {
+  it("asks nothing and sends no questionnaire", async () => {
+    tiers = [
+      tier({
+        priceMonthly: 12,
+        joinMode: "application",
+        myApplication: { id: "app-1", status: "payment_failed", paymentWindowExpiresAt: "2026-09-24T00:00:00.000Z" },
+      }),
+    ];
+    api.createPaid.mockResolvedValue({ requiresPayment: true, clientSecret: "pi_1_secret_2" });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1" }));
+
+    expect(result.current.questionnaire).toEqual([]);
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.createPaid).toHaveBeenCalledTimes(1);
+    expect(api.createPaid.mock.calls[0][0]).not.toHaveProperty("questionnaire");
+    expect(result.current.questionnaireRefusal).toBeNull();
+  });
+});
+
+describe("changing tier", () => {
+  it("starts the next tier's answers blank", () => {
+    tiers = [
+      tier({ id: "tier-1", priceMonthly: 12 }),
+      tier({ id: "tier-2", priceMonthly: 20, questionnaire: [{ id: "q-why", question: "Why?", type: "text" }] }),
+    ];
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1" }));
+
+    act(() => result.current.setQuestionnaireAnswer("q-why", "An answer for tier one"));
+    act(() => result.current.selectTier(tiers[1]));
+
+    expect(result.current.selectedTierId).toBe("tier-2");
+    expect(result.current.questionnaire).toEqual([{ id: "q-why", question: "Why?", type: "text" }]);
+    expect(result.current.questionnaireAnswers).toEqual({});
+  });
+});
+
+describe("pure helpers", () => {
+  it("a tier with no questions asks none", () => {
+    expect(tierQuestionnaire(undefined)).toEqual([]);
+    expect(tierQuestionnaire({ questionnaire: null })).toEqual([]);
+    expect(tierQuestionnaire({ questionnaire: [] })).toEqual([]);
+  });
+
+  it("optional questions are never missing", () => {
+    expect(firstMissingAnswer([questions[2]], {})).toBeNull();
+  });
+
+  it("builds every question in order with trimmed answers", () => {
+    expect(buildQuestionnaireAnswers(questions, { "q-why": " Long-time listener ", "q-city": "Lagos" })).toEqual(
+      expectedAnswers,
+    );
+  });
+});