@tribe-nest/forge 3.29.0 → 3.34.0

package/src/ui/format/_tests/membershipPwyw.spec.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from "vitest";
+import type { MembershipTier } from "../../../types/models";
+import {
+  clampMembershipAmount,
+  cycleCeiling,
+  cycleFloor,
+  cycleIsFree,
+  cycleIsOffered,
+  defaultChosenAmount,
+  defaultCycle,
+  offeredCycles,
+  refuseMembershipAmount,
+  resolveSubscriptionAmount,
+} from "../membershipPwyw";
+
+/**
+ * The membership money rules, away from React.
+ *
+ * Everything here decides either what a fan is CHARGED or which endpoint is
+ * called, and both have shipped wrong: a pay-what-you-want box that sent its
+ * initial zero to an endpoint that refuses anything not positive, and a
+ * yearly-only tier read as free because the default cycle was the literal
+ * "month".
+ */
+
+const tier = (overrides: Partial<MembershipTier> = {}): MembershipTier => ({
+  id: "tier-1",
+  name: "Inner Circle",
+  description: "The good stuff",
+  payWhatYouWant: false,
+  benefits: [],
+  ...overrides,
+});
+
+describe("cycleFloor", () => {
+  it("reads a pay-what-you-want tier's YEARLY minimum on the yearly cycle", () => {
+    // Monthly 5, yearly 50. Reading the monthly floor on a yearly subscription
+    // would let someone buy a whole year for the price of a month.
+    const t = tier({ payWhatYouWant: true, payWhatYouWantMinimum: 5, payWhatYouWantYearlyMinimum: 50 });
+
+    expect(cycleFloor(t, "month")).toBe(5);
+    expect(cycleFloor(t, "year")).toBe(50);
+  });
+
+  it("reads a fixed tier's own cycle price, which is the only amount the server takes", () => {
+    const t = tier({ priceMonthly: 10, priceYearly: 100 });
+
+    expect(cycleFloor(t, "month")).toBe(10);
+    expect(cycleFloor(t, "year")).toBe(100);
+  });
+
+  it("treats a missing, null or negative price as no price at all", () => {
+    expect(cycleFloor(tier({ priceMonthly: undefined }), "month")).toBe(0);
+    expect(cycleFloor(tier({ priceYearly: -4 }), "year")).toBe(0);
+  });
+});
+
+describe("offeredCycles / defaultCycle", () => {
+  it("REGRESSION: opens a YEARLY-ONLY tier on the yearly cycle", () => {
+    // The defect: the cycle defaulted to the literal "month", the monthly price
+    // was absent, and the tier was therefore read as FREE and activated through
+    // the free endpoint. The fan got the tier and the artist was never charged.
+    const t = tier({ priceYearly: 100 });
+
+    expect(offeredCycles(t)).toEqual({ month: false, year: true });
+    expect(defaultCycle(t)).toBe("year");
+    expect(cycleIsFree(t, defaultCycle(t))).toBe(false);
+  });
+
+  it("opens a pay-what-you-want tier with only a yearly minimum on the yearly cycle", () => {
+    const t = tier({ payWhatYouWant: true, payWhatYouWantYearlyMinimum: 60 });
+
+    expect(offeredCycles(t)).toEqual({ month: false, year: true });
+    expect(defaultCycle(t)).toBe("year");
+  });
+
+  it("prefers monthly when both are sold", () => {
+    expect(defaultCycle(tier({ priceMonthly: 10, priceYearly: 100 }))).toBe("month");
+  });
+
+  it("calls a tier with no price on either cycle free, and opens it on monthly", () => {
+    const t = tier();
+
+    expect(cycleIsOffered(t, "month")).toBe(false);
+    expect(cycleIsOffered(t, "year")).toBe(false);
+    expect(defaultCycle(t)).toBe("month");
+    expect(cycleIsFree(t, "month")).toBe(true);
+  });
+
+  it("never calls a pay-what-you-want tier free, whatever its minimums", () => {
+    // A PWYW tier is bought through the PAID endpoint even at its floor, so
+    // reading it as free would activate a membership with no charge behind it.
+    expect(cycleIsFree(tier({ payWhatYouWant: true, payWhatYouWantMinimum: 5 }), "month")).toBe(false);
+  });
+});
+
+describe("defaultChosenAmount", () => {
+  it("REGRESSION: opens the amount box at the floor, not at zero", () => {
+    // The defect: the box started at 0 and nothing ever seeded it, so the very
+    // first press of Subscribe sent `amount: 0` and the server answered
+    // `amount_must_be_positive`. Pay-what-you-want could not be bought at all.
+    const t = tier({ payWhatYouWant: true, payWhatYouWantMinimum: 25, payWhatYouWantYearlyMinimum: 250 });
+
+    expect(defaultChosenAmount(t, "month")).toBe(25);
+    expect(defaultChosenAmount(t, "year")).toBe(250);
+  });
+
+  it("leaves a fixed tier's box at zero, because it is never read", () => {
+    expect(defaultChosenAmount(tier({ priceMonthly: 10 }), "month")).toBe(0);
+  });
+});
+
+describe("clampMembershipAmount", () => {
+  const t = tier({ payWhatYouWant: true, payWhatYouWantMinimum: 20, payWhatYouWantMaximum: 100 });
+
+  it("lifts anything under the floor up to it", () => {
+    expect(clampMembershipAmount(t, "month", 5)).toBe(20);
+    expect(clampMembershipAmount(t, "month", 0)).toBe(20);
+    expect(clampMembershipAmount(t, "month", -3)).toBe(20);
+  });
+
+  it("treats an unparseable box (a cleared input) as the floor rather than NaN", () => {
+    expect(clampMembershipAmount(t, "month", Number(""))).toBe(20);
+    expect(clampMembershipAmount(t, "month", undefined)).toBe(20);
+  });
+
+  it("keeps a generous amount exactly as typed, ceiling and all", () => {
+    // The ceiling is display-only: neither the client app nor the server
+    // enforces one on a membership, and lowering the figure here would charge
+    // less than the total the fan just read.
+    expect(clampMembershipAmount(t, "month", 45)).toBe(45);
+    expect(clampMembershipAmount(t, "month", 500)).toBe(500);
+    expect(cycleCeiling(t, "month")).toBe(100);
+  });
+});
+
+describe("resolveSubscriptionAmount", () => {
+  it("ignores the amount box on a fixed tier", () => {
+    // A figure left over from a pay-what-you-want tier must not follow the fan
+    // onto a fixed one: the server rejects anything that is not exactly the
+    // cycle price, so this would be a checkout that always 400s.
+    const t = tier({ priceMonthly: 10, priceYearly: 100 });
+
+    expect(resolveSubscriptionAmount(t, "month", 999)).toBe(10);
+    expect(resolveSubscriptionAmount(t, "year", 999)).toBe(100);
+  });
+
+  it("sends the fan's own figure on a pay-what-you-want tier", () => {
+    const t = tier({ payWhatYouWant: true, payWhatYouWantMinimum: 5 });
+
+    expect(resolveSubscriptionAmount(t, "month", 12.5)).toBe(12.5);
+  });
+});
+
+describe("refuseMembershipAmount", () => {
+  it("refuses a pay-what-you-want figure under the floor, and names the floor", () => {
+    const t = tier({ payWhatYouWant: true, payWhatYouWantMinimum: 20 });
+
+    expect(refuseMembershipAmount(t, "month", 5)).toEqual({ reason: "below_minimum", minimum: 20 });
+  });
+
+  it("refuses a zero before the request rather than after the 400", () => {
+    // A pay-what-you-want tier whose floor is 0 passes the minimum check on 0
+    // and then fails `amount_must_be_positive` server-side, with the failure
+    // landing nowhere the fan can see.
+    const t = tier({ payWhatYouWant: true, payWhatYouWantMinimum: 0, payWhatYouWantYearlyMinimum: 60 });
+
+    expect(refuseMembershipAmount(t, "month", 0)).toEqual({ reason: "not_positive" });
+  });
+
+  it("passes a figure at the floor, and anything above it", () => {
+    const t = tier({ payWhatYouWant: true, payWhatYouWantMinimum: 20 });
+
+    expect(refuseMembershipAmount(t, "month", 20)).toBeNull();
+    expect(refuseMembershipAmount(t, "month", 21)).toBeNull();
+  });
+
+  it("passes a free cycle, which never sends an amount at all", () => {
+    expect(refuseMembershipAmount(tier(), "month", 0)).toBeNull();
+  });
+
+  it("passes a fixed paid cycle regardless of the box", () => {
+    expect(refuseMembershipAmount(tier({ priceMonthly: 10 }), "month", 0)).toBeNull();
+  });
+});

package/src/ui/format/_tests/pwyw.spec.ts

@@ -1,13 +1,6 @@
 import { describe, it, expect } from "vitest";
 import type { ITicket } from "../../../types/models";
-import {
-  clampChosenAmount,
-  isPayWhatYouWant,
-  pwywDefaultAmount,
-  pwywMaximum,
-  resolveUnitPrice,
-  ticketSubtotals,
-} from "../pwyw";
+import { checkoutAmounts, clampChosenAmount, isPayWhatYouWant, pwywDefaultAmount, pwywMaximum, resolveUnitPrice, ticketSubtotals } from "../pwyw";
 
 /**
  * The pay-what-you-want arithmetic shared by BOTH storefront stacks (Forge and
@@ -155,3 +148,67 @@ describe("pwyw helpers", () => {
     });
   });
 });
+
+describe("what actually gets sent as `amounts`", () => {
+  /**
+   * The server takes `amounts` as `z.number().positive()`. A zero answers
+   * `amounts.<id>: Amount must be a positive number` and the checkout fails
+   * outright, so a free pay-what-you-like ticket could not be bought at all.
+   * These assert the PAYLOAD rather than the displayed price, which is why the
+   * existing subtotal tests could not see it.
+   */
+  const pwyw = (over: Partial<ITicket> = {}): ITicket =>
+    ({ id: "t1", price: 0, payWhatYouWant: true, ...over }) as ITicket;
+
+  it("sends NOTHING for a free pay-what-you-like tier the buyer left alone", () => {
+    // The reported failure. Floor 0, no suggestion, so both the default and the
+    // clamp hand back 0.
+    const sent = checkoutAmounts({ tickets: [pwyw()], quantities: { t1: 1 }, chosen: {} });
+
+    expect(sent).toEqual({});
+    expect(Object.values(sent).every((v) => v > 0)).toBe(true);
+  });
+
+  it("sends nothing when the buyer TYPES a zero on a free tier", () => {
+    const sent = checkoutAmounts({ tickets: [pwyw()], quantities: { t1: 1 }, chosen: { t1: 0 } });
+    expect(sent).toEqual({});
+  });
+
+  it("still sends a real amount on a free tier when the buyer chooses to pay", () => {
+    // Omitting must not mean "never send"; a free tier is exactly where a
+    // voluntary payment matters most.
+    const sent = checkoutAmounts({ tickets: [pwyw()], quantities: { t1: 1 }, chosen: { t1: 15 } });
+    expect(sent).toEqual({ t1: 15 });
+  });
+
+  it("sends the floor on a PAID tier, which is positive and therefore legal", () => {
+    const sent = checkoutAmounts({
+      tickets: [pwyw({ price: 10 })],
+      quantities: { t1: 1 },
+      chosen: { t1: 4 },
+    });
+    // Clamped up to the floor rather than dropped: 10 is a positive number and
+    // says something true.
+    expect(sent).toEqual({ t1: 10 });
+  });
+
+  it("ignores a tier with no quantity, and a tier that is not PWYW", () => {
+    const sent = checkoutAmounts({
+      tickets: [pwyw({ id: "none" }), { id: "fixed", price: 20, payWhatYouWant: false } as ITicket],
+      quantities: { none: 0, fixed: 2 },
+      chosen: { none: 50, fixed: 99 },
+    });
+    expect(sent).toEqual({});
+  });
+
+  it("never emits a non-positive value for any mix of tiers", () => {
+    const sent = checkoutAmounts({
+      tickets: [pwyw({ id: "free" }), pwyw({ id: "paid", price: 12 })],
+      quantities: { free: 1, paid: 1 },
+      chosen: {},
+    });
+
+    expect(sent).toEqual({ paid: 12 });
+    expect(Object.values(sent).some((v) => v <= 0)).toBe(false);
+  });
+});

package/src/ui/format/membershipPwyw.ts

@@ -0,0 +1,164 @@
+import type { MembershipTier } from "../../types/models";
+
+/**
+ * Membership pricing arithmetic: which billing cycles a tier actually offers,
+ * what a pay-what-you-want cycle's floor is, and the ONE number that may be
+ * sent to `POST /public/payments/subscriptions`.
+ *
+ * ## Why this is a module and not four lines inside the hook
+ *
+ * Every rule here has a wrong-charge or a dead-end on the other side of it, and
+ * none of them is reachable from a React test without a provider tree:
+ *
+ *  - **A cycle a tier does not sell must not be selectable.** The default cycle
+ *    used to be the literal `"month"`, so a tier priced YEARLY only was read as
+ *    "no monthly price, therefore free" and activated as a free membership. The
+ *    fan got the tier and the artist got nothing.
+ *  - **The floor belongs to the CYCLE, not the tier.** `payWhatYouWantMinimum`
+ *    is the monthly floor and `payWhatYouWantYearlyMinimum` the yearly one.
+ *    Reading the monthly one on a yearly subscription understates the minimum
+ *    by a factor of twelve.
+ *  - **A zero must never be sent.** The server takes the amount as
+ *    `z.number()` and then refuses anything `<= 0` with
+ *    `amount_must_be_positive`, so a pay-what-you-want box left at its initial
+ *    0 is not "pay nothing", it is a subscribe button that always fails.
+ *
+ * ## Units
+ *
+ * Every number in and out of here is MAJOR units (19.99, not 1999) in the
+ * TENANT'S SETTLEMENT currency (`useSiteConfig().currency`), because that is
+ * what the tier rows hold and what the server converts with `toMinorUnits`.
+ * A visitor's chosen display currency converts on the way to the SCREEN and
+ * never on the way to the API: convert what is sent and the fan is charged a
+ * number nobody agreed to.
+ */
+
+export type BillingCycle = "month" | "year";
+
+/** A tier's own numbers, narrowed to what pricing needs. */
+export type PricedTier = Pick<
+  MembershipTier,
+  | "payWhatYouWant"
+  | "payWhatYouWantMinimum"
+  | "payWhatYouWantYearlyMinimum"
+  | "payWhatYouWantMaximum"
+  | "payWhatYouWantYearlyMaximum"
+  | "priceMonthly"
+  | "priceYearly"
+>;
+
+const positive = (value: number | null | undefined): number => {
+  const parsed = typeof value === "number" ? value : Number(value ?? 0);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+};
+
+/**
+ * The lowest amount this cycle may be bought at.
+ *
+ * Pay-what-you-want: the cycle's own minimum. Fixed price: the cycle's price,
+ * which is also the only amount the server accepts (`amount !== cyclePrice`
+ * is rejected outright). 0 means "this cycle is free or not offered", which
+ * `cycleIsOffered` separates.
+ */
+export const cycleFloor = (tier: PricedTier, cycle: BillingCycle): number => {
+  if (tier.payWhatYouWant) {
+    return positive(cycle === "month" ? tier.payWhatYouWantMinimum : tier.payWhatYouWantYearlyMinimum);
+  }
+  return positive(cycle === "month" ? tier.priceMonthly : tier.priceYearly);
+};
+
+/**
+ * The operator's ceiling for a pay-what-you-want cycle, or `null` for none.
+ *
+ * Exposed for display only. It is deliberately NOT applied to the amount that
+ * is sent: neither the client app nor the server enforces a membership PWYW
+ * maximum today, and clamping here would charge less than the total the fan
+ * just read on screen.
+ */
+export const cycleCeiling = (tier: PricedTier, cycle: BillingCycle): number | null => {
+  if (!tier.payWhatYouWant) return null;
+  const raw = cycle === "month" ? tier.payWhatYouWantMaximum : tier.payWhatYouWantYearlyMaximum;
+  const value = positive(raw);
+  return value > 0 ? value : null;
+};
+
+/** Does the tier sell this cycle at all? A cycle with no price is not on offer. */
+export const cycleIsOffered = (tier: PricedTier, cycle: BillingCycle): boolean => cycleFloor(tier, cycle) > 0;
+
+/** Both answers at once, for rendering the billing-cycle radios. */
+export const offeredCycles = (tier: PricedTier): { month: boolean; year: boolean } => ({
+  month: cycleIsOffered(tier, "month"),
+  year: cycleIsOffered(tier, "year"),
+});
+
+/**
+ * The cycle a tier opens on: monthly when it is sold, otherwise yearly.
+ *
+ * A tier that sells NEITHER is a free tier, where the cycle is never sent and
+ * only decides whether the summary reads "per month" or "per year".
+ */
+export const defaultCycle = (tier: PricedTier): BillingCycle =>
+  cycleIsOffered(tier, "month") ? "month" : cycleIsOffered(tier, "year") ? "year" : "month";
+
+/**
+ * Free means free on THIS cycle: no pay-what-you-want floor and no price.
+ * A free tier is activated through `/subscriptions/free`, which takes no
+ * amount, so this is the branch that decides which endpoint is called.
+ */
+export const cycleIsFree = (tier: PricedTier, cycle: BillingCycle): boolean =>
+  !tier.payWhatYouWant && cycleFloor(tier, cycle) === 0;
+
+/** What the amount box starts at: the floor for the cycle. */
+export const defaultChosenAmount = (tier: PricedTier, cycle: BillingCycle): number =>
+  tier.payWhatYouWant ? cycleFloor(tier, cycle) : 0;
+
+/** Lift a fan-entered figure up to the floor. Never lowers it to a ceiling. */
+export const clampMembershipAmount = (tier: PricedTier, cycle: BillingCycle, chosen: number | null | undefined): number => {
+  const floor = cycleFloor(tier, cycle);
+  const parsed = typeof chosen === "number" ? chosen : Number(chosen ?? 0);
+  if (!Number.isFinite(parsed) || parsed < floor) return floor;
+  return parsed;
+};
+
+/**
+ * The number to SEND for a paid subscription, in settlement-currency major
+ * units.
+ *
+ * A fixed tier ignores `chosen` exactly as the server does, so a stale amount
+ * left in state after switching from a pay-what-you-want tier cannot change
+ * what is charged.
+ */
+export const resolveSubscriptionAmount = (
+  tier: PricedTier,
+  cycle: BillingCycle,
+  chosen: number | null | undefined,
+): number => (tier.payWhatYouWant ? clampMembershipAmount(tier, cycle, chosen) : cycleFloor(tier, cycle));
+
+/** Why an amount cannot be sent. `null` when it can. */
+export type MembershipAmountRefusal =
+  | { reason: "below_minimum"; minimum: number }
+  | { reason: "not_positive" };
+
+/**
+ * The check that runs before the request, not after the 400.
+ *
+ * Two refusals, and the second is the one that bites hardest: a
+ * pay-what-you-want box that is still on its initial 0, or one the fan cleared,
+ * resolves to 0 on a tier whose floor is 0, and the server answers
+ * `amount_must_be_positive`. Saying so here turns an unexplained failure into a
+ * field error next to the field.
+ */
+export const refuseMembershipAmount = (
+  tier: PricedTier,
+  cycle: BillingCycle,
+  chosen: number | null | undefined,
+): MembershipAmountRefusal | null => {
+  if (cycleIsFree(tier, cycle)) return null;
+  const floor = cycleFloor(tier, cycle);
+  if (tier.payWhatYouWant) {
+    const parsed = typeof chosen === "number" ? chosen : Number(chosen ?? 0);
+    if (!Number.isFinite(parsed) || parsed < floor) return { reason: "below_minimum", minimum: floor };
+  }
+  if (resolveSubscriptionAmount(tier, cycle, chosen) <= 0) return { reason: "not_positive" };
+  return null;
+};

package/src/ui/format/pwyw.ts

@@ -93,3 +93,40 @@ export function ticketSubtotals(input: {
   }
   return { paid, floor };
 }
+
+/**
+ * The `amounts` map to SEND for a selection, keyed by ticket id.
+ *
+ * Only PWYW tiers with a quantity appear, and only with a POSITIVE amount. That
+ * last rule is not a tidy-up: the server takes `amounts` as
+ * `z.number().positive()`, so a zero answers
+ *
+ *   amounts.<id>: Amount must be a positive number
+ *
+ * and the checkout fails outright. It is reachable on any PWYW tier whose floor
+ * is zero, a free "pay what you like" ticket: with no suggestion
+ * `pwywDefaultAmount` returns the floor, and `clampChosenAmount` returns the
+ * floor for anything below it, so both paths hand back 0 and the buyer cannot
+ * check out at all.
+ *
+ * Omitting the key says what the 0 was trying to say. The server reads a missing
+ * entry as `NaN`, fails `Number.isFinite`, and falls through to the tier's list
+ * price, which for such a tier IS zero.
+ */
+export function checkoutAmounts(input: {
+  tickets: ITicket[];
+  quantities: Record<string, number>;
+  /** What the buyer typed, where they typed anything. */
+  chosen: Record<string, number | null | undefined>;
+}): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const ticket of input.tickets) {
+    if (!isPayWhatYouWant(ticket) || (input.quantities[ticket.id] ?? 0) <= 0) continue;
+    const amount =
+      input.chosen[ticket.id] != null
+        ? resolveUnitPrice(ticket, input.chosen[ticket.id])
+        : pwywDefaultAmount(ticket);
+    if (amount > 0) out[ticket.id] = amount;
+  }
+  return out;
+}