@omg-dev/billing 0.4.33 → 0.4.35

package/dist/catalog.mjs

@@ -93,6 +93,7 @@ function toCatalog(billing) {
 			price: p.price,
 			interval: p.interval,
 			default: p.default,
+			deprecated: p.deprecated ? true : void 0,
 			inclusions: p.inclusions.map((i) => ({
 				feature: i.feature,
 				kind: i.kind,

package/dist/index.mjs

@@ -73,6 +73,7 @@ function defineBilling(config) {
 	if (planKeys.length === 0) throw new Error("@omg-dev/billing: at least one plan must be declared");
 	const defaults = planKeys.filter((k) => config.plans[k].default);
 	if (defaults.length !== 1) throw new Error(`@omg-dev/billing: exactly one plan must be default:true (found ${defaults.length}: [${defaults.join(", ")}])`);
+	if (config.plans[defaults[0]].deprecated) throw new Error(`@omg-dev/billing: the default plan "${defaults[0]}" cannot be deprecated — new customers land on it`);
 	const rateCards = config.usage ?? {};
 	for (const fkey of Object.keys(rateCards)) {
 		const f = config.features[fkey];
@@ -120,7 +121,8 @@ function defineBilling(config) {
 			price: p.price,
 			interval: p.interval,
 			default: p.default ?? false,
-			inclusions
+			inclusions,
+			deprecated: p.deprecated ?? false
 		};
 	});
 	const addOns = Object.entries(config.addOns ?? {}).map(([key, a]) => {

package/dist/react.mjs

@@ -41,15 +41,20 @@ function PricingTable({ billing, currentPlan, onSelectPlan, ctaLabel, renderIncl
 		},
 		"data-vibes-pricing-table": true,
 		children: React.useMemo(() => {
-			const list = [...billing.plans];
+			const list = billing.plans.filter((p) => !p.deprecated || p.key === currentPlan);
 			if (sortByPrice) list.sort((a, b) => a.price - b.price);
 			return list;
-		}, [billing.plans, sortByPrice]).map((plan) => {
+		}, [
+			billing.plans,
+			currentPlan,
+			sortByPrice
+		]).map((plan) => {
 			const isCurrent = currentPlan === plan.key;
 			const lines = inclusionLines(plan, billing, renderInclusion);
 			return /* @__PURE__ */ jsxs("div", {
 				"data-plan": plan.key,
 				"data-default": plan.default || void 0,
+				"data-deprecated": plan.deprecated || void 0,
 				style: {
 					border: "1px solid var(--border, #e5e7eb)",
 					borderRadius: "0.75rem",
@@ -109,7 +114,7 @@ function PricingTable({ billing, currentPlan, onSelectPlan, ctaLabel, renderIncl
 							padding: "0.5rem"
 						},
 						"data-current": true,
-						children: "Current plan"
+						children: plan.deprecated ? "Current plan — no longer offered" : "Current plan"
 					}) : onSelectPlan ? /* @__PURE__ */ jsx("button", {
 						type: "button",
 						onClick: () => onSelectPlan(plan.key),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omg-dev/billing",
-  "version": "0.4.33",
+  "version": "0.4.35",
   "type": "module",
   "exports": {
     ".": {

package/src/catalog.ts

@@ -29,6 +29,12 @@ export interface CatalogPlan {
     window?: "day" | "week" | "month";
     overage?: { allow: boolean };
   }>;
+  /** Closed to new subscriptions; grandfathered holders keep it. Omitted when
+   *  false so an all-current catalog serializes exactly as it did before this
+   *  field existed. Deliberately outside BOTH hashes: retiring a plan changes
+   *  nothing the provider bills or the ledger meters, so it must not churn a
+   *  Stripe product or look like a price change. */
+  deprecated?: true;
   /** Stable hash of this plan's FULL billable shape (price + interval +
    *  inclusions + windows). Reference / change-detection. */
   hash: string;
@@ -161,6 +167,7 @@ export function toCatalog(billing: Billing): Catalog {
       price: p.price,
       interval: p.interval,
       default: p.default,
+      deprecated: p.deprecated ? (true as const) : undefined,
       inclusions: p.inclusions.map((i) => ({
         feature: i.feature,
         kind: i.kind,

package/src/index.ts

@@ -156,6 +156,18 @@ export interface PlanInput {
   includes?: Record<string, Inclusion>;
   /** Per-feature overage policy once the inclusion is exhausted. */
   usage?: Record<string, Overage>;
+  /**
+   * Closed to NEW subscriptions; existing holders are grandfathered.
+   *
+   * A retired plan cannot simply be deleted: the key still has to resolve for
+   * everyone still on it (allowance grants, entitlement lookups, the provider
+   * price their subscription already renews against). So it stays in the
+   * catalog and this flag carries the one fact every consumer needs — do not
+   * sell it. Pricing surfaces skip it, checkout refuses it, and the plan a
+   * grandfathered customer holds can be labelled honestly instead of read as a
+   * peer of the tiers on sale.
+   */
+  deprecated?: boolean;
 }
 
 export interface PlanDef extends PlanInput {
@@ -255,6 +267,8 @@ export interface NormalizedPlan {
   interval?: "month" | "year";
   default: boolean;
   inclusions: NormalizedPlanInclusion[];
+  /** Closed to new subscriptions; grandfathered holders keep it. */
+  deprecated: boolean;
 }
 
 export interface NormalizedAddOn {
@@ -306,6 +320,15 @@ export function defineBilling(config: BillingConfig): Billing {
     );
   }
 
+  // The default plan is what every new customer lands on, so retiring it would
+  // close signup itself — a contradiction worth catching at declaration time
+  // rather than at the first checkout.
+  if (config.plans[defaults[0]].deprecated) {
+    throw new Error(
+      `@omg-dev/billing: the default plan "${defaults[0]}" cannot be deprecated — new customers land on it`,
+    );
+  }
+
   // rate cards may only reference declared metered features
   const rateCards = config.usage ?? {};
   for (const fkey of Object.keys(rateCards)) {
@@ -377,6 +400,7 @@ export function defineBilling(config: BillingConfig): Billing {
       interval: p.interval,
       default: p.default ?? false,
       inclusions,
+      deprecated: p.deprecated ?? false,
     };
   });
 

package/src/react.tsx

@@ -80,10 +80,14 @@ export function PricingTable({
   sortByPrice = true,
 }: PricingTableProps) {
   const plans = React.useMemo(() => {
-    const list = [...billing.plans];
+    // A retired plan is not on sale, so it is not a column — with one
+    // exception: the person currently ON it. Dropping their card outright
+    // would render the table as if they were on the free tier, which is the
+    // one reading a pricing table must never produce.
+    const list = billing.plans.filter((p) => !p.deprecated || p.key === currentPlan);
     if (sortByPrice) list.sort((a, b) => a.price - b.price);
     return list;
-  }, [billing.plans, sortByPrice]);
+  }, [billing.plans, currentPlan, sortByPrice]);
 
   return (
     <div
@@ -105,6 +109,7 @@ export function PricingTable({
             key={plan.key}
             data-plan={plan.key}
             data-default={plan.default || undefined}
+            data-deprecated={plan.deprecated || undefined}
             style={{
               border: "1px solid var(--border, #e5e7eb)",
               borderRadius: "0.75rem",
@@ -147,7 +152,7 @@ export function PricingTable({
                 }}
                 data-current
               >
-                Current plan
+                {plan.deprecated ? "Current plan — no longer offered" : "Current plan"}
               </div>
             ) : onSelectPlan ? (
               <button

package/src/test/billing.test.ts

@@ -224,3 +224,62 @@ describe("catalog serialization", () => {
     expect(addOnHash(pricier)).not.toBe(addOnHash(base));
   });
 });
+
+describe("deprecated plans", () => {
+  function withRetired() {
+    return defineBilling({
+      provider: stripe(),
+      credit: { unit: "usd", peg: usd(1) },
+      features: { llm_usage: { kind: "metered", label: "AI usage" } },
+      plans: {
+        free: plan({ price: usd(0), default: true, includes: { llm_usage: limit("$5") } }),
+        legacy: plan({
+          price: usd(20),
+          interval: "month",
+          deprecated: true,
+          includes: { llm_usage: limit("$25") },
+        }),
+      },
+    });
+  }
+
+  it("defaults to false so an ordinary plan is unchanged", () => {
+    for (const p of fixture().plans) expect(p.deprecated).toBe(false);
+  });
+
+  it("normalizes the flag onto the plan", () => {
+    const plans = withRetired().plans;
+    expect(plans.find((p) => p.key === "legacy")!.deprecated).toBe(true);
+    expect(plans.find((p) => p.key === "free")!.deprecated).toBe(false);
+  });
+
+  it("refuses to retire the default plan — new customers land on it", () => {
+    expect(() =>
+      defineBilling({
+        provider: stripe(),
+        credit: { unit: "usd", peg: usd(1) },
+        features: { llm_usage: { kind: "metered" } },
+        plans: {
+          free: plan({ price: usd(0), default: true, deprecated: true }),
+        },
+      }),
+    ).toThrow(/default plan "free" cannot be deprecated/);
+  });
+
+  // Retiring a plan changes nothing the provider bills and nothing the ledger
+  // meters, so it must not look like a price change — a churned hash would mint
+  // a new Stripe product for a plan we are trying to stop selling.
+  it("does not touch either hash", () => {
+    const before = fixture().plans.find((p) => p.key === "pro")!;
+    expect(planHash({ ...before, deprecated: true })).toBe(planHash(before));
+    const serialized = toCatalog(withRetired()).plans.find((p) => p.key === "legacy")!;
+    expect(serialized.deprecated).toBe(true);
+  });
+
+  // Omitted-when-false keeps an all-current catalog byte-identical to what the
+  // serializer emitted before this field existed.
+  it("omits the flag entirely for a current plan", () => {
+    expect(serializeCatalog(fixture())).not.toContain("deprecated");
+    expect(serializeCatalog(withRetired())).toContain('"deprecated":true');
+  });
+});