@startsimpli/billing 0.4.32 → 0.4.34

package/src/utils/credit-math.ts

@@ -0,0 +1,32 @@
+/** Price math for one-time credit packs. Pure. */
+
+export interface PackPrice {
+  price: string;
+  compareAt?: string | null;
+  credits: number;
+}
+
+/** "$19.99" from a decimal-string price and its currency; cents always shown. */
+export function formatPackPrice(amount: string, currency: string): string {
+  const n = Number(amount);
+  if (!Number.isFinite(n)) return amount;
+  try {
+    return new Intl.NumberFormat("en-US", { style: "currency", currency: (currency || "USD").toUpperCase() }).format(n);
+  } catch {
+    return `${n.toFixed(2)} ${currency}`;
+  }
+}
+
+/** Whole-percent saving of `price` against a struck-through `compareAt`, or null when there is none. */
+export function savingsPercent(offer: Pick<PackPrice, "price" | "compareAt">): number | null {
+  const price = Number(offer.price);
+  const was = Number(offer.compareAt);
+  if (!offer.compareAt || !Number.isFinite(price) || !Number.isFinite(was) || was <= price || was <= 0) return null;
+  return Math.round((1 - price / was) * 100);
+}
+
+/** Price of one credit in this pack (decimal string, 2 places). */
+export function pricePerCredit(offer: Pick<PackPrice, "price" | "credits">): string {
+  const total = Number(offer.price);
+  return offer.credits > 0 && Number.isFinite(total) ? (total / offer.credits).toFixed(2) : offer.price;
+}

package/src/utils/plan.test.ts

@@ -99,7 +99,7 @@ describe('isPaidSubscription', () => {
 //      current_period_start is frozen at signup and never rolls.
 // ---------------------------------------------------------------------------
 
-import { getFeatureLimit, resolvePlanEntitlement, resolveUsageWindow } from './plan'
+import { getFeatureLimit, resolvePlanEntitlement, resolveUsageWindow, trialLabel } from './plan'
 
 const freeOffer = makeOffer({
   slug: 'crochet-free',
@@ -312,3 +312,15 @@ describe('resolveUsageWindow', () => {
     expect(w.end.toISOString()).toBe('2027-01-01T00:00:00.000Z')
   })
 })
+
+describe("trialLabel", () => {
+  const base = { trialDays: 7, currency: "USD" } as const;
+  it("says free when nothing is charged", () => {
+    expect(trialLabel({ ...base })).toBe("7-day free trial");
+    expect(trialLabel({ ...base, trialFeeCents: 0 })).toBe("7-day free trial");
+  });
+  it("does not say free when a card-check fee is charged", () => {
+    expect(trialLabel({ ...base, trialFeeCents: 100 })).toBe("7-day trial · $1 today");
+    expect(trialLabel({ ...base, trialFeeCents: 150 })).toBe("7-day trial · $1.50 today");
+  });
+});

package/src/utils/plan.ts

@@ -307,6 +307,28 @@ export function trialApplies(card: ProductOffer, direction: PlanDirection, payin
   return direction === "upgrade" && !paying && (card.trialDays ?? 0) > 0;
 }
 
+/**
+ * "7-day free trial", or "7-day trial · $1 today" when starting it charges a
+ * card-check fee (then it is not free, so it must not say so).
+ */
+export function trialLabel(offer: Pick<ProductOffer, "trialDays" | "trialFeeCents" | "currency">): string {
+  const days = offer.trialDays ?? 0;
+  const cents = offer.trialFeeCents ?? 0;
+  if (cents <= 0) return `${days}-day free trial`;
+  const amount = cents / 100;
+  let fee: string;
+  try {
+    fee = new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: (offer.currency || "USD").toUpperCase(),
+      minimumFractionDigits: Number.isInteger(amount) ? 0 : 2,
+    }).format(amount);
+  } catch {
+    fee = `$${amount}`;
+  }
+  return `${days}-day trial · ${fee} today`;
+}
+
 /**
  * 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

package/src/utils/return-urls.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import {
+  autoCheckoutOffer, billingReturnUrl, creditReturnUrls, creditSessionFrom, signUpReturnUrl, statusMessageFrom,
+} from "./return-urls";
+import type { ProductOffer } from "../types";
+
+const offers = [{ slug: "pro" }, { slug: "lite" }] as unknown as ProductOffer[];
+
+describe("return urls", () => {
+  it("prefers the public origin, trims slashes and adds a leading slash", () => {
+    expect(billingReturnUrl("/x", "http://localhost:3000", "https://app.example/")).toBe("https://app.example/x");
+    expect(billingReturnUrl("x", "http://localhost:3000")).toBe("http://localhost:3000/x");
+  });
+  it("builds the sign-up return with plan, auto and optional next", () => {
+    expect(signUpReturnUrl("https://a.b", "pro", null)).toBe("https://a.b/pricing?plan=pro&checkout=auto");
+    expect(signUpReturnUrl("https://a.b", "pro", "/go", "/plans")).toBe("https://a.b/plans?plan=pro&checkout=auto&next=%2Fgo");
+  });
+  it("picks the auto-checkout offer only when asked and known", () => {
+    expect(autoCheckoutOffer(offers, new URLSearchParams("checkout=auto&plan=lite"))?.slug).toBe("lite");
+    expect(autoCheckoutOffer(offers, new URLSearchParams("plan=lite"))).toBeNull();
+    expect(autoCheckoutOffer(offers, new URLSearchParams("checkout=auto&plan=zzz"))).toBeNull();
+    expect(autoCheckoutOffer(offers, new URLSearchParams("checkout=auto"))).toBeNull();
+  });
+  it("credit return urls carry the session placeholder, unencoded", () => {
+    const abs = (p: string) => `https://a.b${p}`;
+    expect(creditReturnUrls(abs)).toEqual({
+      successUrl: "https://a.b/settings/billing/credits/success?session_id={CHECKOUT_SESSION_ID}",
+      cancelUrl: "https://a.b/settings/billing/credits/cancelled",
+    });
+    expect(creditReturnUrls(abs, { successPath: "/ok", cancelledPath: "/no" }).cancelUrl).toBe("https://a.b/no");
+  });
+  it("reads only real session ids and known statuses", () => {
+    expect(creditSessionFrom(new URLSearchParams("session_id=cs_test_1"))).toBe("cs_test_1");
+    expect(creditSessionFrom(new URLSearchParams("session_id={CHECKOUT_SESSION_ID}"))).toBeNull();
+    expect(statusMessageFrom(new URLSearchParams("status=scheduled"))).toBe("scheduled");
+    expect(statusMessageFrom(new URLSearchParams("status=hax"))).toBeNull();
+  });
+});

package/src/utils/return-urls.ts

@@ -0,0 +1,74 @@
+/**
+ * Return-URL and hand-off helpers around checkout: where Stripe (or central
+ * sign-up) sends the browser back to, and how a pricing page picks up an
+ * "auto checkout" request. Pure: no React, no window.
+ */
+
+import type { ProductOffer } from "../types";
+import { checkoutSessionIdFrom, withSessionPlaceholder } from "./checkout-flow";
+
+/**
+ * The absolute URL Stripe (or central auth) sends the browser back to. The
+ * configured public origin wins so a build served behind a tunnel or proxy
+ * still returns to the public site; else the origin the page is on.
+ */
+export function billingReturnUrl(path: string, currentOrigin?: string, publicOrigin?: string): string {
+  const origin = (publicOrigin || currentOrigin || "").replace(/\/+$/, "");
+  const normalized = path.startsWith("/") ? path : `/${path}`;
+  return `${origin}${normalized}`;
+}
+
+/**
+ * Where sign-up sends the person back to: the pricing page with the plan they
+ * picked, so checkout starts without a second click.
+ */
+export function signUpReturnUrl(
+  origin: string,
+  planSlug: string,
+  nextPath: string | null,
+  pricingPath = "/pricing",
+): string {
+  const q = new URLSearchParams({ plan: planSlug, checkout: "auto" });
+  if (nextPath) q.set("next", nextPath);
+  return `${origin}${pricingPath}?${q.toString()}`;
+}
+
+/** The offer to check out straight away: only when ?checkout=auto&plan=<slug>. */
+export function autoCheckoutOffer(offers: ProductOffer[], params: URLSearchParams): ProductOffer | null {
+  if (params.get("checkout") !== "auto") return null;
+  const plan = params.get("plan");
+  if (!plan) return null;
+  return offers.find((o) => o.slug === plan) ?? null;
+}
+
+export interface CreditReturnPaths {
+  successPath: string;
+  cancelledPath: string;
+}
+
+/** Where Stripe sends the browser after a credit pack: the return pages. */
+export function creditReturnUrls(
+  absolute: (path: string) => string,
+  paths: CreditReturnPaths = {
+    successPath: "/settings/billing/credits/success",
+    cancelledPath: "/settings/billing/credits/cancelled",
+  },
+): { successUrl: string; cancelUrl: string } {
+  return {
+    successUrl: withSessionPlaceholder(absolute(paths.successPath)),
+    cancelUrl: absolute(paths.cancelledPath),
+  };
+}
+
+/** The Stripe session to sync from the success page's query, or null. */
+export function creditSessionFrom(params: URLSearchParams): string | null {
+  return checkoutSessionIdFrom(params.get("session_id"));
+}
+
+export type PlanStatusMessage = "success" | "cancelled" | "scheduled";
+
+/** ?status= on billing settings after a plan checkout or change. */
+export function statusMessageFrom(params: URLSearchParams): PlanStatusMessage | null {
+  const s = params.get("status");
+  return s === "success" || s === "cancelled" || s === "scheduled" ? s : null;
+}

package/src/utils/usage-meters.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { meterRows } from "./usage-meters";
+
+describe("meterRows", () => {
+  it("skips unlimited and flags, states by fill, humanizes missing labels", () => {
+    const rows = meterRows({
+      ai_designs: { used: 2, limit: 10 },
+      near: { used: 8, limit: 10 },
+      full: { used: 12, limit: 10 },
+      unlimited: { used: 5, limit: null },
+      zero: { used: 0, limit: 0 },
+    }, { near: "Near" });
+    expect(rows.map((r) => [r.key, r.state, r.label, r.left])).toEqual([
+      ["ai_designs", "ok", "Ai designs", 8],
+      ["near", "approaching", "Near", 2],
+      ["full", "at-cap", "Full", 0],
+      ["zero", "at-cap", "Zero", 0],
+    ]);
+  });
+});

package/src/utils/usage-meters.ts

@@ -0,0 +1,35 @@
+import type { UsageMap } from "../types";
+
+export type MeterState = "ok" | "approaching" | "at-cap";
+
+export interface MeterRow {
+  key: string;
+  label: string;
+  used: number;
+  limit: number;
+  pct: number;
+  left: number;
+  state: MeterState;
+}
+
+const humanize = (key: string): string => {
+  const words = key.replace(/[_-]+/g, " ").trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+};
+
+/**
+ * One meter per feature with a real numeric cap. Unlimited (-1 / null) and
+ * flags render nothing: a paying person is not shown a bar for what they have
+ * no cap on. Labels come from the plan's own feature names.
+ */
+export function meterRows(usage: UsageMap, labels: Record<string, string> = {}): MeterRow[] {
+  return Object.entries(usage ?? {})
+    .filter(([, u]) => u && typeof u.limit === "number" && u.limit >= 0)
+    .map(([key, u]) => {
+      const limit = u.limit as number;
+      const used = Math.max(0, u.used);
+      const pct = limit === 0 ? 100 : Math.min(100, Math.round((used / limit) * 100));
+      const state: MeterState = used >= limit ? "at-cap" : pct >= 80 ? "approaching" : "ok";
+      return { key, label: labels[key] ?? humanize(key), used, limit, pct, left: Math.max(0, limit - used), state };
+    });
+}