@startsimpli/billing 0.4.22 → 0.4.24

package/src/utils/format.ts

@@ -0,0 +1,54 @@
+/**
+ * Display formatting shared by every plan card, so a price or a feature line
+ * reads the same on /pricing, the billing settings page and the upgrade modal
+ * (crochet_patterns-34n7).
+ */
+import type { OfferFeature } from "../types";
+
+/**
+ * "$2.99", "$9", "€10". Cents are kept when there are any and dropped when
+ * the amount is whole — truncating with Math.floor turned $2.99 into $2.
+ */
+export function formatPrice(amount: string | number, currency = "USD"): string {
+  const n = typeof amount === "number" ? amount : parseFloat(amount);
+  const value = Number.isFinite(n) ? n : 0;
+  const whole = Math.abs(value - Math.round(value)) < 0.005;
+  try {
+    return new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: currency || "USD",
+      minimumFractionDigits: whole ? 0 : 2,
+      maximumFractionDigits: whole ? 0 : 2,
+    }).format(value);
+  } catch {
+    return `$${whole ? Math.round(value) : value.toFixed(2)}`;
+  }
+}
+
+/** Lower-case the first letter for mid-sentence use, unless the first word is
+ * an acronym ("AI designs" stays "AI designs", "Team seats" → "team seats"). */
+function midSentence(name: string): string {
+  const firstWord = name.split(/\s+/)[0] ?? "";
+  if ((firstWord.match(/[A-Z]/g) ?? []).length >= 2) return name;
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+
+/** "Saved patterns per month" → "Saved patterns": an unlimited allowance has
+ * no period. */
+function withoutPeriod(name: string): string {
+  return name.replace(/\s+(per|a|each|\/)\s*(day|week|month|year)$/i, "");
+}
+
+/**
+ * The line a plan card shows for one feature. Numeric allowances read as
+ * "Up to 3 AI designs per month" / "Unlimited saved patterns"; capabilities
+ * and string values are shown by name. Callers decide what to do with a
+ * feature whose value is `false`.
+ */
+export function formatFeatureLabel(feature: OfferFeature): string {
+  const { name, value, limit } = feature;
+  const n = typeof limit === "number" ? limit : typeof value === "number" ? value : null;
+  if (n === -1) return `Unlimited ${midSentence(withoutPeriod(name))}`;
+  if (n !== null && n > 0) return `Up to ${n} ${midSentence(name)}`;
+  return name;
+}

package/src/utils/ga-ids.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from "vitest";
+import { readGaIds } from "./ga-ids";
+
+describe("readGaIds", () => {
+  it("reads the client id from _ga and the session id from a GS2 _ga_<stream> cookie", () => {
+    expect(
+      readGaIds("foo=1; _ga=GA1.1.1234567890.1760000000; _ga_K1M560RH1W=GS2.1.s1760600000$o3$g1$t1760600500$j0$l0$h0"),
+    ).toEqual({ ga_client_id: "1234567890.1760000000", ga_session_id: "1760600000" });
+  });
+
+  it("reads the session id from the older GS1 format", () => {
+    expect(readGaIds("_ga=GA1.2.111.222; _ga_ABC=GS1.1.1760600001.4.1.1760600500.0.0.0")).toEqual({
+      ga_client_id: "111.222",
+      ga_session_id: "1760600001",
+    });
+  });
+
+  it("returns a client id without a session, and nothing without _ga", () => {
+    expect(readGaIds("_ga=GA1.1.111.222")).toEqual({ ga_client_id: "111.222", ga_session_id: "" });
+    expect(readGaIds("other=1")).toBeNull();
+    expect(readGaIds("")).toBeNull();
+  });
+});

package/src/utils/ga-ids.ts

@@ -0,0 +1,43 @@
+/**
+ * The buyer's GA4 client and session ids, read from gtag's cookies, so the
+ * server can send the subscription's conversion to the same GA user and
+ * session (and Google Ads can credit the ad click). Sent with checkout.
+ *
+ *   _ga=GA1.1.<client id: two numbers>
+ *   _ga_<stream>=GS1.1.<session id>.<...>        (before 2025)
+ *   _ga_<stream>=GS2.1.s<session id>$o<n>$...     (since 2025)
+ */
+export interface GaIds {
+  ga_client_id: string;
+  ga_session_id: string;
+}
+
+export function readGaIds(cookie: string): GaIds | null {
+  const jar = new Map<string, string>();
+  for (const part of cookie.split(";")) {
+    const i = part.indexOf("=");
+    if (i > 0) jar.set(part.slice(0, i).trim(), decodeURIComponent(part.slice(i + 1).trim()));
+  }
+  const ga = jar.get("_ga")?.split(".");
+  if (!ga || ga.length < 4) return null;
+  const clientId = ga.slice(-2).join(".");
+
+  let sessionId = "";
+  for (const [name, value] of jar) {
+    if (!name.startsWith("_ga_")) continue;
+    const gs2 = value.match(/^GS2\.\d+\.s(\d+)/);
+    const gs1 = value.match(/^GS1\.\d+\.(\d+)\./);
+    sessionId = gs2?.[1] ?? gs1?.[1] ?? "";
+    if (sessionId) break;
+  }
+  return { ga_client_id: clientId, ga_session_id: sessionId };
+}
+
+/** readGaIds over document.cookie; null outside a browser. */
+export function currentGaIds(): GaIds | null {
+  try {
+    return typeof document === "undefined" ? null : readGaIds(document.cookie);
+  } catch {
+    return null;
+  }
+}

package/src/utils/plan.ts

@@ -201,3 +201,41 @@ 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;
+}

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