@tribe-nest/forge 3.54.0 → 3.57.0

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

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

@@ -0,0 +1,165 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useMembershipCheckout } from "../useMembershipCheckout";
+import type { MembershipTier } from "../../../../types/models";
+
+/**
+ * Free trials in the headless checkout: the selected tier's trial is exposed
+ * only when the fan is eligible, and a paid subscribe that answers with `trial`
+ * and a SetupIntent secret routes the payment step to a card SAVE that finishes
+ * like a paid subscription (to the return page's confirm-latest), never to the
+ * application confirm.
+ */
+
+const auth = vi.hoisted(() => ({
+  user: { id: "account-1", email: "fan@example.com", membership: undefined as unknown },
+  refetchUser: vi.fn(async () => {}),
+}));
+
+const api = vi.hoisted(() => ({
+  confirm: vi.fn(async (_body: Record<string, unknown>) => ({}) as 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: vi.fn(), 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: vi.fn(), isPending: false }),
+  useConfirmLatestSubscription: () => ({ mutateAsync: vi.fn(), isPending: false }),
+}));
+
+const tier = (overrides: Partial<MembershipTier>): MembershipTier => ({
+  id: "tier-1",
+  name: "Inner Circle",
+  description: "",
+  payWhatYouWant: false,
+  benefits: [],
+  priceMonthly: 12,
+  ...overrides,
+});
+
+const onComplete = vi.fn();
+const DAY = 24 * 60 * 60 * 1000;
+
+beforeEach(() => {
+  api.confirm.mockReset();
+  api.createPaid.mockReset();
+  onComplete.mockReset();
+  auth.user.membership = undefined;
+  window.history.replaceState(null, "", "/i/membership/checkout");
+});
+
+describe("useMembershipCheckout: trial exposure", () => {
+  it("exposes trialDays and a first-charge date of today + trialDays for an eligible fan", () => {
+    tiers = [tier({ trialDays: 14, trialEligible: true })];
+    const before = Date.now();
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1", onComplete }));
+
+    expect(result.current.trialDays).toBe(14);
+    expect(result.current.trial).toBeNull();
+    const ends = new Date(result.current.trialEndsAt as string).getTime();
+    expect(ends).toBeGreaterThanOrEqual(before + 14 * DAY);
+    expect(ends).toBeLessThanOrEqual(Date.now() + 14 * DAY);
+    // The consent line's other inputs.
+    expect(result.current.amount).toBe(12);
+    expect(result.current.billingCycle).toBe("month");
+  });
+
+  it("exposes no trial to an ineligible fan, on a tier without one, or on a free tier", () => {
+    tiers = [
+      tier({ id: "used", trialDays: 14, trialEligible: false }),
+      tier({ id: "none", trialDays: null }),
+      tier({ id: "free", priceMonthly: 0, trialDays: 14 }),
+    ];
+    for (const id of ["used", "none", "free"]) {
+      const { result } = renderHook(() => useMembershipCheckout({ initialTierId: id, onComplete }));
+      expect(result.current.trialDays, id).toBe(0);
+      expect(result.current.trialEndsAt, id).toBeNull();
+    }
+  });
+
+  it("exposes no trial to a member changing tier", () => {
+    auth.user.membership = { paymentProviderSubscriptionId: "sub_1", status: "active", membershipTierId: "other" };
+    tiers = [tier({ trialDays: 14 })];
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1", onComplete }));
+    expect(result.current.isChange).toBe(true);
+    expect(result.current.trialDays).toBe(0);
+  });
+});
+
+describe("useMembershipCheckout: a trial's SetupIntent secret", () => {
+  it("routes a seti_ secret from the PAID subscribe to a setup, and finishes like a paid subscription", async () => {
+    tiers = [tier({ trialDays: 14 })];
+    api.createPaid.mockResolvedValue({
+      membershipId: "m-1",
+      subscriptionId: "s-1",
+      requiresPayment: true,
+      clientSecret: "seti_trial_secret_abc",
+      trial: { days: 14, endsAt: "2026-10-01T00:00:00.000Z" },
+    });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1", onComplete }));
+
+    await act(async () => {
+      await result.current.subscribe();
+    });
+
+    expect(api.createPaid).toHaveBeenCalledTimes(1);
+    expect(result.current.step).toBe("payment");
+    expect(result.current.clientSecret).toBe("seti_trial_secret_abc");
+    expect(result.current.paymentKind).toBe("setup");
+    expect(result.current.setupPurpose).toBe("trial");
+    expect(result.current.trial).toEqual({ days: 14, endsAt: "2026-10-01T00:00:00.000Z" });
+    // The server's date wins over the local estimate.
+    expect(result.current.trialEndsAt).toBe("2026-10-01T00:00:00.000Z");
+
+    await act(async () => {
+      await result.current.onPaymentSucceeded();
+    });
+
+    expect(onComplete).toHaveBeenCalledWith({ requiresConfirmation: true });
+    expect(api.confirm).not.toHaveBeenCalled();
+  });
+
+  it("keys setup off the SECRET: a seti_ secret with no trial field still confirms as a setup", async () => {
+    tiers = [tier({})];
+    api.createPaid.mockResolvedValue({ requiresPayment: true, clientSecret: "seti_x_secret_y" });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1", onComplete }));
+    await act(async () => {
+      await result.current.subscribe();
+    });
+    expect(result.current.paymentKind).toBe("setup");
+    expect(result.current.setupPurpose).toBe("trial");
+    expect(result.current.trial).toBeNull();
+  });
+
+  it("keeps an ordinary paid subscription on the payment confirm", async () => {
+    tiers = [tier({})];
+    api.createPaid.mockResolvedValue({ requiresPayment: true, clientSecret: "pi_1_secret_2", trial: null });
+    const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1", onComplete }));
+    await act(async () => {
+      await result.current.subscribe();
+    });
+    expect(result.current.paymentKind).toBe("payment");
+    expect(result.current.setupPurpose).toBeNull();
+    expect(result.current.trial).toBeNull();
+    await act(async () => {
+      await result.current.onPaymentSucceeded();
+    });
+    expect(onComplete).toHaveBeenCalledWith({ requiresConfirmation: true });
+  });
+});