@tribe-nest/forge 3.58.0 → 3.60.0

package/src/ui/headless/_tests/useCommunityJoin.spec.tsx

@@ -0,0 +1,382 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { communityJoinStep, tierHasChoice, useCommunityJoin, type CommunityJoinStepInput } from "../communities/useCommunityJoin";
+import type { CommunityInviteState } from "../../../data/queries/useCommunities";
+import {
+  account,
+  calls,
+  detailRoute,
+  get,
+  installAdapter,
+  meRoute,
+  post,
+  restoreAdapter,
+  tier,
+  viewer,
+  wrapper,
+  type Route,
+} from "./communityHarness";
+
+const paystack = vi.hoisted(() => ({ open: vi.fn(async () => "opened" as const) }));
+vi.mock("../../../utils/paystackCheckout", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../utils/paystackCheckout")>()),
+  openPaystackCheckout: paystack.open,
+}));
+
+/**
+ * The join sheet's step machine, driven with no markup.
+ *
+ *     email -> code -> tier -> questions -> payment -> inside
+ *
+ * Every step that does not apply is skipped, every success lands INSIDE the
+ * community (never `/i/account`), invites preset their tier and lock their
+ * email, and a dead invite falls back to the normal join without its token.
+ */
+
+const HOME = "/i/communities/fan-club/home";
+let onJoined: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  onJoined = vi.fn();
+  paystack.open.mockClear();
+  window.history.replaceState(null, "", "/i/communities/fan-club");
+});
+afterEach(restoreAdapter);
+
+const free = tier({ id: "tier-free", name: "Free" });
+const paid = tier({ id: "tier-paid", name: "Paid", priceMonthly: 10 });
+const both = tier({ id: "tier-both", name: "Both", priceMonthly: 10, priceYearly: 100 });
+const apply = tier({ id: "tier-apply", name: "Apply", joinMode: "application" });
+const invited = tier({ id: "tier-vip", name: "VIP", joinMode: "invite" });
+
+function routes({
+  tiers,
+  me = () => viewer(),
+  invite,
+  extra = [],
+}: {
+  tiers: ReturnType<typeof tier>[];
+  me?: () => ReturnType<typeof viewer>;
+  invite?: CommunityInviteState;
+  extra?: Route[];
+}): Route[] {
+  return [
+    ...extra,
+    get(/^\/public\/communities\/fan-club\/invite$/, () => invite),
+    meRoute(me),
+    detailRoute((req) => ({
+      // The invite-only tier is listed only with a valid token, as on the server.
+      tiers: req.params?.invite || req.params?.join ? [...tiers, invited] : tiers,
+    })),
+    post("/public/payments/subscriptions/free", () => ({ membershipId: "m-1", communitySlug: "fan-club" })),
+    post("/public/payments/subscriptions", () => ({
+      membershipId: "m-1",
+      subscriptionId: "s-1",
+      clientSecret: "pi_1_secret_2",
+      requiresPayment: true,
+    })),
+    get("/public/websites/site-config", () => ({ currency: "USD" })),
+  ];
+}
+
+async function signUp(result: { current: ReturnType<typeof useCommunityJoin> }, email = "fan@example.com") {
+  act(() => {
+    result.current.signup.setFirstName("Fan");
+    result.current.signup.setLastName("Person");
+    if (!result.current.emailLocked) result.current.signup.setEmail(email);
+    result.current.signup.setPassword("password123");
+    result.current.signup.setAcceptedTerms(true);
+  });
+  await act(async () => {
+    await result.current.next();
+  });
+  expect(result.current.step).toBe("code");
+  act(() => result.current.setCode("123456"));
+  await act(async () => {
+    await result.current.next();
+  });
+}
+
+describe("the step order", () => {
+  const base: CommunityJoinStepInput = {
+    isAuthenticated: true,
+    awaitingCode: false,
+    emailMismatch: false,
+    joined: false,
+    pending: false,
+    alreadyMember: false,
+    isProcessing: false,
+    hasPaymentStep: false,
+    hasSelectedTier: true,
+    tierStepOpen: false,
+    questionsOpen: false,
+  };
+  it.each<[string, Partial<CommunityJoinStepInput>, string]>([
+    ["anonymous asks who the fan is", { isAuthenticated: false }, "email"],
+    ["then the emailed code", { isAuthenticated: false, awaitingCode: true }, "code"],
+    ["a mismatched invite stays on identity even when signed in", { emailMismatch: true }, "email"],
+    ["no tier chosen yet", { hasSelectedTier: false }, "tier"],
+    ["a tier with a choice to make", { tierStepOpen: true }, "tier"],
+    ["questions after the tier", { questionsOpen: true }, "questions"],
+    ["the card once a paid join started", { hasPaymentStep: true, questionsOpen: true }, "payment"],
+    ["in flight", { isProcessing: true }, "submitting"],
+    ["nothing left to ask submits", {}, "submitting"],
+    ["an application lodged", { pending: true }, "pending"],
+    ["joined", { joined: true }, "joined"],
+    ["already a member goes inside", { alreadyMember: true }, "joined"],
+  ])("%s", (_label, patch, step) => {
+    expect(communityJoinStep({ ...base, ...patch })).toBe(step);
+  });
+
+  it("a tier asks for a choice only with two cycles or a pay-what-you-want amount", () => {
+    expect(tierHasChoice(free)).toBe(false);
+    expect(tierHasChoice(paid)).toBe(false);
+    expect(tierHasChoice(both)).toBe(true);
+    expect(tierHasChoice(tier({ payWhatYouWant: true, payWhatYouWantMinimum: 5 }))).toBe(true);
+  });
+});
+
+describe("signed out, one free tier: the code is the last step", () => {
+  it("email -> code -> joined free, landing inside with welcome", async () => {
+    installAdapter(routes({ tiers: [free] }));
+    const { result } = renderHook(() => useCommunityJoin({ onJoined }), { wrapper: wrapper() });
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.step).toBe("email");
+
+    await signUp(result);
+
+    await waitFor(() => expect(calls("post", "/public/payments/subscriptions/free")).toHaveLength(1));
+    expect(calls("post", "/public/payments/subscriptions/free")[0].body).toMatchObject({
+      membershipTierId: "tier-free",
+      profileId: "profile-1",
+    });
+    await waitFor(() => expect(result.current.step).toBe("joined"));
+    expect(onJoined).toHaveBeenCalledWith({ pending: false, requiresConfirmation: false, path: `${HOME}?welcome=1` });
+    expect(JSON.stringify(onJoined.mock.calls)).not.toContain("/i/account");
+  });
+});
+
+describe("signed in", () => {
+  it("several tiers: asks which, then joins the chosen one", async () => {
+    installAdapter(routes({ tiers: [free, paid] }));
+    const { result } = renderHook(() => useCommunityJoin({ onJoined }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.step).toBe("tier"));
+    expect(result.current.hasTierChoice).toBe(true);
+    act(() => result.current.selectTier(free));
+    await act(async () => {
+      await result.current.next();
+    });
+    await waitFor(() => expect(result.current.step).toBe("joined"));
+    expect(calls("post", "/public/payments/subscriptions/free")[0].body).toMatchObject({ membershipTierId: "tier-free" });
+  });
+
+  it("?tier= preselects a tier; a tier with a cycle choice still asks", async () => {
+    installAdapter(routes({ tiers: [free, both] }));
+    const { result } = renderHook(() => useCommunityJoin({ tierId: "tier-both", onJoined }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.selectedTier?.id).toBe("tier-both"));
+    expect(result.current.step).toBe("tier");
+    act(() => result.current.setBillingCycle("year"));
+    await act(async () => {
+      await result.current.next();
+    });
+    await waitFor(() => expect(result.current.step).toBe("payment"));
+    expect(calls("post", "/public/payments/subscriptions")[0].body).toMatchObject({
+      membershipTierId: "tier-both",
+      billingCycle: "year",
+      amount: 100,
+    });
+  });
+
+  it("questions: a blank required answer is refused before anything is sent, then the answers go with the join", async () => {
+    const withQuestions = tier({
+      id: "tier-q",
+      questionnaire: [{ id: "q-why", question: "Why?", type: "text", optional: false }] as never,
+    });
+    installAdapter(routes({ tiers: [withQuestions] }));
+    const { result } = renderHook(() => useCommunityJoin({ onJoined }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.step).toBe("questions"));
+
+    await act(async () => {
+      await result.current.next();
+    });
+    expect(result.current.questionnaireRefusal?.id).toBe("q-why");
+    expect(result.current.step).toBe("questions");
+    expect(calls("post", "/public/payments/subscriptions/free")).toHaveLength(0);
+
+    act(() => result.current.setQuestionnaireAnswer("q-why", "Big fan"));
+    await act(async () => {
+      await result.current.next();
+    });
+    await waitFor(() => expect(result.current.step).toBe("joined"));
+    expect(calls("post", "/public/payments/subscriptions/free")[0].body?.questionnaire).toEqual([
+      expect.objectContaining({ id: "q-why", answer: "Big fan" }),
+    ]);
+  });
+
+  it("paid on Stripe: the card step, returning to the community home to reconcile", async () => {
+    installAdapter(routes({ tiers: [paid] }));
+    const { result } = renderHook(() => useCommunityJoin({ onJoined }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.step).toBe("payment"));
+    expect(result.current.clientSecret).toBe("pi_1_secret_2");
+    expect(result.current.paymentKind).toBe("payment");
+    expect(result.current.returnUrl).toBe(`${window.location.origin}${HOME}?confirmSubscription=1`);
+    expect(calls("post", "/public/payments/subscriptions")[0].body?.returnUrl).toBe(
+      `${window.location.origin}${HOME}?confirmSubscription=1`,
+    );
+
+    await act(async () => {
+      await result.current.onPaymentSucceeded();
+    });
+    expect(onJoined).toHaveBeenCalledWith({ pending: false, requiresConfirmation: true, path: `${HOME}?confirmSubscription=1` });
+    expect(result.current.step).toBe("joined");
+  });
+
+  it("paid on Paystack: the card step opens the provider's checkout", async () => {
+    installAdapter(
+      routes({
+        tiers: [paid],
+        extra: [
+          post("/public/payments/subscriptions", () => ({
+            membershipId: "m-1",
+            subscriptionId: "s-1",
+            accessCode: "ac_1",
+            checkoutUrl: "https://paystack.test/ac_1",
+            requiresPayment: true,
+          })),
+        ],
+      }),
+    );
+    const { result } = renderHook(() => useCommunityJoin({ onJoined }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.step).toBe("payment"));
+    expect(result.current.isPaystack).toBe(true);
+    expect(result.current.clientSecret).toBeUndefined();
+    expect(paystack.open).toHaveBeenCalledWith(
+      expect.objectContaining({ accessCode: "ac_1", returnUrl: `${window.location.origin}${HOME}?confirmSubscription=1` }),
+      expect.anything(),
+    );
+    expect(onJoined).not.toHaveBeenCalled();
+  });
+
+  it("apply-to-join lands inside, pending", async () => {
+    installAdapter(
+      routes({
+        tiers: [apply],
+        extra: [
+          post("/public/membership-applications", () => ({
+            application: { id: "app-1", membershipTierId: "tier-apply", status: "pending", createdAt: "2026-09-27T00:00:00.000Z" },
+            requiresCard: false,
+            clientSecret: null,
+          })),
+        ],
+      }),
+    );
+    const { result } = renderHook(() => useCommunityJoin({ onJoined }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.step).toBe("pending"));
+    expect(calls("post", "/public/membership-applications")[0].body).toMatchObject({ membershipTierId: "tier-apply" });
+    expect(onJoined).toHaveBeenCalledWith({ pending: true, requiresConfirmation: false, path: HOME });
+  });
+
+  it("a member of THIS community is taken straight inside, and nothing is sent", async () => {
+    installAdapter(
+      routes({
+        tiers: [free],
+        me: () =>
+          viewer({
+            state: "member",
+            membership: {
+              id: "m-1",
+              tierId: "tier-free",
+              tierName: "Free",
+              status: "active",
+              cancelAtPeriodEnd: false,
+              currentPeriodEnd: null,
+              pendingDowngradeTierId: null,
+            },
+          }),
+      }),
+    );
+    const { result } = renderHook(() => useCommunityJoin({ onJoined }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.step).toBe("joined"));
+    expect(result.current.alreadyMember).toBe(true);
+    await waitFor(() => expect(onJoined).toHaveBeenCalledWith({ pending: false, requiresConfirmation: false, path: HOME }));
+    expect(calls("post", /\/public\/payments\/subscriptions/)).toHaveLength(0);
+  });
+});
+
+describe("invites", () => {
+  const emailInvite = (state: CommunityInviteState["state"], invitedEmail = "invited@example.com"): CommunityInviteState => ({
+    kind: "email",
+    state,
+    invitedEmail,
+    tier: state === "valid" || state === "email_mismatch" ? invited : null,
+  });
+
+  it("a per-email invite presets its (invite-only) tier, prefills and locks the email, and forwards the token", async () => {
+    installAdapter(routes({ tiers: [free], invite: emailInvite("valid") }));
+    const { result } = renderHook(() => useCommunityJoin({ invite: "tok-1", onJoined }), { wrapper: wrapper() });
+    await waitFor(() => expect(result.current.emailLocked).toBe(true));
+    expect(result.current.signup.email).toBe("invited@example.com");
+    expect(result.current.lockedEmail).toBe("invited@example.com");
+
+    await signUp(result);
+
+    await waitFor(() => expect(result.current.step).toBe("joined"));
+    const [join] = calls("post", "/public/payments/subscriptions/free");
+    expect(join.body).toMatchObject({ membershipTierId: "tier-vip", inviteToken: "tok-1" });
+    expect(join.body).not.toHaveProperty("joinToken");
+  });
+
+  it("signed in as someone else: the mismatch is shown with Sign in as, which signs out into a locked sign-in", async () => {
+    const logout = vi.fn();
+    installAdapter(routes({ tiers: [free], invite: emailInvite("valid") }));
+    const { result } = renderHook(() => useCommunityJoin({ invite: "tok-1", onJoined }), {
+      wrapper: wrapper({ user: account("other@example.com"), controls: { logout } }),
+    });
+    await waitFor(() => expect(result.current.emailMismatch).not.toBeNull());
+    expect(result.current.step).toBe("email");
+    expect(result.current.emailMismatch).toEqual({ invitedEmail: "invited@example.com", signedInEmail: "other@example.com" });
+    expect(calls("post", /\/public\/payments\/subscriptions/)).toHaveLength(0);
+
+    await act(async () => {
+      await result.current.signInAsInvited();
+    });
+    expect(logout).toHaveBeenCalledTimes(1);
+    expect(result.current.mode).toBe("signin");
+    expect(result.current.emailMismatch).toBeNull();
+    await waitFor(() => expect(result.current.login.email).toBe("invited@example.com"));
+    expect(result.current.emailLocked).toBe(true);
+  });
+
+  it.each(["expired", "revoked", "used", "not_found"] as const)(
+    "a %s invite says why and falls back to the normal join, without the token",
+    async (state) => {
+      installAdapter(routes({ tiers: [free], invite: emailInvite(state) }));
+      const { result } = renderHook(() => useCommunityJoin({ invite: "tok-dead", onJoined }), { wrapper: wrapper({ user: account() }) });
+      await waitFor(() => expect(result.current.inviteProblem).toBe(state));
+      expect(result.current.emailLocked).toBe(false);
+      await waitFor(() => expect(result.current.step).toBe("joined"));
+      const [join] = calls("post", "/public/payments/subscriptions/free");
+      expect(join.body).toMatchObject({ membershipTierId: "tier-free" });
+      expect(join.body).not.toHaveProperty("inviteToken");
+    },
+  );
+
+  it("a shareable link presets its tier with no email lock and forwards the join token", async () => {
+    installAdapter(routes({ tiers: [free], invite: { kind: "link", state: "valid", invitedEmail: null, tier: invited } }));
+    const { result } = renderHook(() => useCommunityJoin({ join: "link-1", onJoined }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.step).toBe("joined"));
+    expect(result.current.emailLocked).toBe(false);
+    const [join] = calls("post", "/public/payments/subscriptions/free");
+    expect(join.body).toMatchObject({ membershipTierId: "tier-vip", joinToken: "link-1" });
+    expect(join.body).not.toHaveProperty("inviteToken");
+  });
+
+  it("a used-up shareable link falls back without its token", async () => {
+    installAdapter(routes({ tiers: [free], invite: { kind: "link", state: "used_up", invitedEmail: null, tier: null } }));
+    const { result } = renderHook(() => useCommunityJoin({ join: "link-1", onJoined }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.inviteProblem).toBe("used_up"));
+    await waitFor(() => expect(result.current.step).toBe("joined"));
+    expect(calls("post", "/public/payments/subscriptions/free")[0].body).not.toHaveProperty("joinToken");
+  });
+});

package/src/ui/headless/_tests/useCommunityMembership.spec.tsx

@@ -0,0 +1,151 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { communityDowngradeTiers, useCommunityMembership } from "../communities/useCommunityMembership";
+import { account, calls, detailRoute, installAdapter, meRoute, post, restoreAdapter, tier, viewer, wrapper } from "./communityHarness";
+
+/**
+ * The Membership menu: cancel keeps the paid period and is two-step, a
+ * downgrade waits for period end and can be withdrawn, and every action is
+ * addressed to THIS community.
+ */
+
+afterEach(restoreAdapter);
+
+const free = tier({ id: "tier-free", name: "Free" });
+const basic = tier({ id: "tier-basic", name: "Basic", priceMonthly: 5 });
+const gold = tier({ id: "tier-gold", name: "Gold", priceMonthly: 20 });
+const yearlyCheap = tier({ id: "tier-yearly", name: "Yearly", priceYearly: 60 });
+const apply = tier({ id: "tier-apply", name: "Apply", priceMonthly: 1, joinMode: "application" });
+
+let state = viewer();
+const onGold = (patch: Record<string, unknown> = {}) =>
+  viewer({
+    state: "member",
+    membership: {
+      id: "m-1",
+      tierId: "tier-gold",
+      tierName: "Gold",
+      status: "active",
+      cancelAtPeriodEnd: false,
+      currentPeriodEnd: "2026-10-27T00:00:00.000Z",
+      pendingDowngradeTierId: null,
+      ...patch,
+    },
+  });
+
+function install() {
+  installAdapter([
+    post("/public/communities/fan-club/membership/cancel", () => {
+      state = onGold({ cancelAtPeriodEnd: true });
+      return {};
+    }),
+    post("/public/communities/fan-club/membership/downgrade", (req) => {
+      state = onGold({ pendingDowngradeTierId: req.body?.membershipTierId });
+      return {};
+    }),
+    post("/public/communities/fan-club/membership/undo-downgrade", () => {
+      state = onGold();
+      return {};
+    }),
+    meRoute(() => state),
+    detailRoute(() => ({ tiers: [free, basic, gold, yearlyCheap, apply] })),
+  ]);
+}
+
+describe("communityDowngradeTiers", () => {
+  it("lists cheaper tiers of this community, on a monthly footing, never an application tier or an upgrade", () => {
+    const tiers = [free, basic, gold, yearlyCheap, apply];
+    expect(communityDowngradeTiers(tiers, "tier-gold", []).map((t) => t.id)).toEqual(["tier-free", "tier-basic", "tier-yearly"]);
+    expect(communityDowngradeTiers(tiers, "tier-gold", ["tier-basic"]).map((t) => t.id)).toEqual(["tier-free", "tier-yearly"]);
+    expect(communityDowngradeTiers(tiers, "tier-free", [])).toEqual([]);
+    expect(communityDowngradeTiers(tiers, null, [])).toEqual([]);
+  });
+});
+
+describe("useCommunityMembership", () => {
+  it("shows the tier, the renewal date and what it can move down to", async () => {
+    state = onGold();
+    install();
+    const { result } = renderHook(() => useCommunityMembership(), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.hasMembership).toBe(true));
+    expect(result.current.membership?.tierName).toBe("Gold");
+    expect(result.current.periodEnd).toBe("2026-10-27T00:00:00.000Z");
+    await waitFor(() => expect(result.current.downgradeTiers.map((t) => t.id)).toEqual(["tier-free", "tier-basic", "tier-yearly"]));
+  });
+
+  it("cancel asks first, then cancels in this community and keeps the period", async () => {
+    state = onGold();
+    install();
+    const { result } = renderHook(() => useCommunityMembership(), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.hasMembership).toBe(true));
+    act(() => result.current.requestCancel());
+    expect(result.current.cancelRequested).toBe(true);
+    expect(calls("post", /cancel$/)).toHaveLength(0);
+
+    await act(async () => {
+      await result.current.confirmCancel();
+    });
+    expect(calls("post", "/public/communities/fan-club/membership/cancel")[0].body).toEqual({ profileId: "profile-1" });
+    await waitFor(() => expect(result.current.isCancelling).toBe(true));
+    expect(result.current.cancelRequested).toBe(false);
+  });
+
+  it("abort leaves the membership alone", async () => {
+    state = onGold();
+    install();
+    const { result } = renderHook(() => useCommunityMembership(), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.hasMembership).toBe(true));
+    act(() => result.current.requestCancel());
+    act(() => result.current.abortCancel());
+    expect(result.current.cancelRequested).toBe(false);
+    expect(calls("post", /cancel$/)).toHaveLength(0);
+  });
+
+  it("downgrade waits for period end and shows as pending; undo withdraws it", async () => {
+    state = onGold();
+    install();
+    const { result } = renderHook(() => useCommunityMembership(), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.hasMembership).toBe(true));
+
+    await act(async () => {
+      await result.current.downgrade("tier-basic");
+    });
+    expect(calls("post", "/public/communities/fan-club/membership/downgrade")[0].body).toEqual({
+      profileId: "profile-1",
+      membershipTierId: "tier-basic",
+    });
+    await waitFor(() => expect(result.current.pendingDowngradeTier?.name).toBe("Basic"));
+
+    await act(async () => {
+      await result.current.undoDowngrade();
+    });
+    expect(calls("post", "/public/communities/fan-club/membership/undo-downgrade")).toHaveLength(1);
+    await waitFor(() => expect(result.current.pendingDowngradeTier).toBeNull());
+  });
+
+  it("a refused action is reported, not swallowed", async () => {
+    state = onGold();
+    installAdapter([
+      post("/public/communities/fan-club/membership/cancel", () => {
+        throw { status: 400, message: "Already cancelled." };
+      }),
+      meRoute(() => state),
+      detailRoute(() => ({ tiers: [gold] })),
+    ]);
+    const { result } = renderHook(() => useCommunityMembership(), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.hasMembership).toBe(true));
+    await act(async () => {
+      await result.current.cancel();
+    });
+    expect(result.current.error).toBe("Already cancelled.");
+  });
+
+  it("has nothing to manage for a non-member", async () => {
+    state = viewer();
+    install();
+    const { result } = renderHook(() => useCommunityMembership(), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.hasMembership).toBe(false);
+  });
+});