@startsimpli/billing 0.4.23 → 0.4.25

package/src/utils/plan.ts

@@ -201,3 +201,125 @@ export function resolveUsageWindow(
   );
   return { start: monthStart, end: monthEnd };
 }
+
+/**
+ * What a plan picker knows about the viewer. Omit it (signed-out pages) and
+ * no card is marked current.
+ */
+export interface CurrentPlanState {
+  signedIn: boolean;
+  subscription: SubscriptionInfo | null | undefined;
+  /** The subscription is still being fetched. */
+  loading?: boolean;
+  /** The subscription fetch failed. */
+  error?: unknown;
+}
+
+/**
+ * The offer to mark "Current plan" on a picker (crochet_patterns-34n7).
+ *
+ * A signed-in user with no subscription row is on the free plan — that is
+ * what every gate already assumes — so the free card is theirs. A paid plan
+ * counts while it is active, trialing or past due; a lapsed one falls back to
+ * free so the user can buy it again. Nothing is marked while the plan is
+ * unknown (loading / failed): a paying user must never see Free flash as
+ * current with their real plan offered as an upgrade.
+ */
+export function resolveCurrentOfferId(
+  offers: ProductOffer[],
+  state: CurrentPlanState | null | undefined,
+): string | null {
+  if (!state || !state.signedIn || state.loading || state.error) return null;
+  const offer = state.subscription?.offer ?? null;
+  if (offer) {
+    if (offer.isFree) return offer.id;
+    if (isPaidSubscription(state.subscription) || state.subscription?.status === "past_due") {
+      return offer.id;
+    }
+  }
+  return offers.find((o) => o.isFree)?.id ?? null;
+}
+
+/**
+ * The plan to treat as the viewer's own on a picker: their subscription's
+ * offer while it counts (see resolveCurrentOfferId), else the free offer for a
+ * signed-in viewer. The offer may be one the picker does not list (a hidden
+ * complimentary plan); `isUnlistedOffer` says so. Null while unknown.
+ */
+export function resolveCurrentOffer(
+  offers: ProductOffer[],
+  state: CurrentPlanState | null | undefined,
+): ProductOffer | null {
+  const id = resolveCurrentOfferId(offers, state);
+  if (!id) return null;
+  const own = state?.subscription?.offer ?? null;
+  if (own && own.id === id) return own;
+  return offers.find((o) => o.id === id) ?? null;
+}
+
+/** True when `offer` is not one of the offers for sale (e.g. a complimentary plan). */
+export function isUnlistedOffer(offers: ProductOffer[], offer: ProductOffer | null | undefined): boolean {
+  return !!offer && !offers.some((o) => o.id === offer.id);
+}
+
+/**
+ * True while the viewer pays for a plan that is still running (active,
+ * trialing or past due). Choosing another paid plan then changes that
+ * subscription in place — an upgrade is charged now, prorated, and never
+ * starts a trial — so pickers must not sell it as one (crochet_patterns-anw61).
+ */
+export function isPayingSubscription(sub: SubscriptionInfo | null | undefined): boolean {
+  if (!sub?.offer || sub.offer.isFree) return false;
+  return PAID_STATUSES.includes(sub.status) || sub.status === "past_due";
+}
+
+/**
+ * A card's direction relative to the viewer's plan:
+ * - "current"   their exact offer
+ * - "switch"    the same plan on the other billing interval (Lite ↔ Lite Annual)
+ * - "upgrade"   paid over free, or a higher sortOrder
+ * - "downgrade" free under paid, or a lower sortOrder
+ * Unknown plan (null) → every card is an upgrade.
+ */
+export type PlanDirection = "current" | "upgrade" | "downgrade" | "switch";
+
+export function planDirection(
+  card: ProductOffer,
+  current: ProductOffer | null | undefined,
+  tierKeyOf: (offerId: string) => string | null = () => null,
+): PlanDirection {
+  if (!current) return "upgrade";
+  if (card.id === current.id) return "current";
+  const tierKey = tierKeyOf(card.id);
+  if (tierKey !== null && tierKey === tierKeyOf(current.id)) return "switch";
+  if (card.isFree && !current.isFree) return "downgrade";
+  if (!card.isFree && current.isFree) return "upgrade";
+  return card.sortOrder > current.sortOrder ? "upgrade" : "downgrade";
+}
+
+/**
+ * Whether the offer's free trial applies to this viewer: only an upgrade by
+ * someone not already paying goes through a checkout that starts one.
+ */
+export function trialApplies(card: ProductOffer, direction: PlanDirection, paying: boolean): boolean {
+  return direction === "upgrade" && !paying && (card.trialDays ?? 0) > 0;
+}
+
+/**
+ * The CTA for a card. `offer.ctaText` ("Start Free Trial") is the pitch to a
+ * new buyer; someone already paying is upgraded in place, so they get
+ * "Upgrade to X" (startsim-21f, crochet_patterns-anw61).
+ */
+export function planCtaLabel(card: ProductOffer, direction: PlanDirection, paying = false): string {
+  if (direction === "current") return "Current plan";
+  if (direction === "switch") return card.intervalUnit === "year" ? "Switch to annual" : "Switch to monthly";
+  if (direction === "downgrade") return `Downgrade to ${card.name}`;
+  if (paying) return `Upgrade to ${card.name}`;
+  return card.ctaText || `Upgrade to ${card.name}`;
+}
+
+/**
+ * A feature row that only describes the trial (key `trial_note`, e.g. "7-day
+ * free trial with AI designs included") is not true when the trial does not apply.
+ */
+export const TRIAL_NOTE_FEATURE_KEY = "trial_note";

package/src/utils/tiers.interval.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Pairing monthly and annual offers into one card per tier
+ * (crochet_patterns-34n7).
+ */
+import { describe, it, expect } from "vitest";
+import { groupOffersByTier, offersForInterval, annualSavings } from "./tiers";
+import {
+  crochetProduct,
+  crochetProductWithTiers,
+  crochetLite,
+  crochetLiteAnnual,
+  crochetPro,
+} from "../components/__fixtures__/crochetProduct";
+
+const slugs = (offers: { slug: string }[]) => offers.map((o) => o.slug);
+
+describe("groupOffersByTier", () => {
+  it("pairs Lite with Lite Annual without a tier field (same features)", () => {
+    const tiers = groupOffersByTier(crochetProduct.offers);
+    expect(tiers.map((t) => t.name)).toEqual(["Free", "Lite", "Pro"]);
+    const lite = tiers[1];
+    expect(lite.monthly?.slug).toBe("crochet-lite");
+    expect(lite.annual?.slug).toBe("crochet-lite-annual");
+    expect(tiers[2].annual).toBeNull();
+  });
+
+  it("pairs by tier when the API sends it", () => {
+    const tiers = groupOffersByTier(crochetProductWithTiers.offers);
+    expect(tiers.map((t) => [t.monthly?.slug ?? null, t.annual?.slug ?? null])).toEqual([
+      ["crochet-free", null],
+      ["crochet-lite", "crochet-lite-annual"],
+      ["crochet-pro", "crochet-pro-annual"],
+    ]);
+  });
+
+  it("falls back to the name prefix when features differ", () => {
+    const annual = { ...crochetLiteAnnual, features: [] };
+    const tiers = groupOffersByTier([crochetLite, annual, crochetPro]);
+    expect(tiers.map((t) => t.name)).toEqual(["Lite", "Pro"]);
+    expect(tiers[0].annual?.slug).toBe("crochet-lite-annual");
+  });
+
+  it("never pairs two monthly offers", () => {
+    const tiers = groupOffersByTier([crochetLite, crochetPro]);
+    expect(tiers).toHaveLength(2);
+  });
+});
+
+describe("offersForInterval", () => {
+  it("monthly shows Free, Lite, Pro", () => {
+    expect(slugs(offersForInterval(crochetProduct.offers, "monthly")))
+      .toEqual(["crochet-free", "crochet-lite", "crochet-pro"]);
+  });
+
+  it("annual shows Free in both modes and keeps a tier with no annual price", () => {
+    expect(slugs(offersForInterval(crochetProduct.offers, "annual")))
+      .toEqual(["crochet-free", "crochet-lite-annual", "crochet-pro"]);
+    expect(slugs(offersForInterval(crochetProductWithTiers.offers, "annual")))
+      .toEqual(["crochet-free", "crochet-lite-annual", "crochet-pro-annual"]);
+  });
+});
+
+describe("annualSavings", () => {
+  it("gives the per-month equivalent and the saving against 12x monthly", () => {
+    const lite = groupOffersByTier(crochetProduct.offers)[1];
+    const s = annualSavings(lite);
+    expect(s).not.toBeNull();
+    expect(s!.perMonth).toBeCloseTo(29 / 12, 5);
+    expect(s!.percent).toBe(19); // 29 vs 35.88
+  });
+
+  it("is null without a monthly sibling to compare against", () => {
+    const pro = groupOffersByTier(crochetProduct.offers)[2];
+    expect(annualSavings(pro)).toBeNull();
+  });
+});

package/src/utils/tiers.ts

@@ -53,3 +53,108 @@ export function tierBelow(offers: ProductOffer[], offer: ProductOffer): ProductO
   const below = index > 0 ? cheapestFirst[index - 1] : null;
   return below && below.features.length > 0 ? below : null;
 }
+
+/** Which price a plan picker is showing. */
+export type BillingInterval = "monthly" | "annual";
+
+/**
+ * One plan tier as the picker shows it: the same plan billed monthly and/or
+ * yearly. Free has only a monthly offer and shows in both modes.
+ */
+export interface OfferTier {
+  key: string;
+  /** The tier's name without the interval: "Lite", never "Lite Annual". */
+  name: string;
+  monthly: ProductOffer | null;
+  annual: ProductOffer | null;
+}
+
+const isAnnual = (o: ProductOffer) => o.intervalUnit === "year";
+
+const featureSignature = (o: ProductOffer) =>
+  JSON.stringify(o.features.map((f) => [f.key, f.value, f.limit ?? null]));
+
+const stripInterval = (name: string) =>
+  name.replace(/\s*[-·(]?\s*(annual|annually|yearly|year)\)?\s*$/i, "").trim() || name;
+
+/**
+ * Pair each annual offer with the monthly offer of the same plan
+ * (crochet_patterns-34n7). Evidence, strongest first: the API's `tier`, an
+ * identical feature list, then the annual name starting with the monthly
+ * name ("Lite Annual" → "Lite"). Two monthly offers are never paired, and an
+ * annual offer with no match becomes a tier of its own.
+ */
+export function groupOffersByTier(offers: ProductOffer[]): OfferTier[] {
+  const tiers: Array<OfferTier & { position: number }> = [];
+
+  offers.forEach((offer, position) => {
+    if (isAnnual(offer)) return;
+    tiers.push({
+      key: offer.tier ? `tier:${offer.tier}` : `offer:${offer.slug}`,
+      name: offer.name,
+      monthly: offer,
+      annual: null,
+      position,
+    });
+  });
+
+  offers.forEach((offer, position) => {
+    if (!isAnnual(offer)) return;
+    const open = tiers.filter((t) => t.annual === null && t.monthly && !t.monthly.isFree);
+    const signature = featureSignature(offer);
+    const lowerName = offer.name.toLowerCase();
+    const match =
+      (offer.tier ? open.find((t) => t.monthly?.tier === offer.tier) : undefined) ??
+      open.find((t) => offer.features.length > 0 && featureSignature(t.monthly!) === signature) ??
+      open
+        .filter((t) => lowerName.startsWith(`${t.monthly!.name.toLowerCase()} `))
+        .sort((a, b) => b.monthly!.name.length - a.monthly!.name.length)[0];
+
+    if (match) {
+      match.annual = offer;
+    } else {
+      tiers.push({
+        key: offer.tier ? `tier:${offer.tier}` : `offer:${offer.slug}`,
+        name: stripInterval(offer.name),
+        monthly: null,
+        annual: offer,
+        position,
+      });
+    }
+  });
+
+  return tiers
+    .sort((a, b) => a.position - b.position)
+    .map(({ position: _position, ...tier }) => tier);
+}
+
+/** The offer a tier shows for `interval`, falling back to the other one so a
+ * plan with no annual price stays on the page. */
+export function tierOffer(tier: OfferTier, interval: BillingInterval): ProductOffer {
+  return (interval === "annual" ? tier.annual ?? tier.monthly : tier.monthly ?? tier.annual)!;
+}
+
+/** One offer per tier for the chosen interval, in catalogue order. */
+export function offersForInterval(offers: ProductOffer[], interval: BillingInterval): ProductOffer[] {
+  return groupOffersByTier(offers).map((tier) => tierOffer(tier, interval));
+}
+
+/** True when at least one plan can be bought both monthly and yearly. */
+export function hasIntervalChoice(offers: ProductOffer[]): boolean {
+  return groupOffersByTier(offers).some((t) => t.monthly !== null && t.annual !== null);
+}
+
+/**
+ * What yearly billing works out to per month, and the whole-percent saving
+ * against paying monthly for twelve months. Null when the tier has no
+ * monthly price to compare against.
+ */
+export function annualSavings(tier: OfferTier): { perMonth: number; percent: number } | null {
+  if (!tier.monthly || !tier.annual) return null;
+  const yearly = parseFloat(tier.annual.unitPrice);
+  const monthly = parseFloat(tier.monthly.unitPrice);
+  if (!Number.isFinite(yearly) || !Number.isFinite(monthly) || monthly <= 0) return null;
+  const twelve = monthly * 12;
+  const percent = yearly < twelve ? Math.floor(((twelve - yearly) / twelve) * 100) : 0;
+  return { perMonth: yearly / 12, percent };
+}