@tribe-nest/forge 3.53.0 → 3.57.0

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

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