@omg-dev/billing 0.4.24

package/dist/catalog.mjs

@@ -0,0 +1,127 @@
+//#region src/catalog.ts
+/** Recursively sort object keys so JSON.stringify is order-independent. */
+function sortDeep(value) {
+	if (Array.isArray(value)) return value.map(sortDeep);
+	if (value && typeof value === "object") {
+		const out = {};
+		for (const k of Object.keys(value).sort()) {
+			const v = value[k];
+			if (v !== void 0) out[k] = sortDeep(v);
+		}
+		return out;
+	}
+	return value;
+}
+/** Canonical stringify: sorted keys, undefined dropped, no incidental whitespace. */
+function stableStringify(value) {
+	return JSON.stringify(sortDeep(value));
+}
+function fnv1a(str) {
+	let h = 2166136261;
+	for (let i = 0; i < str.length; i++) {
+		h ^= str.charCodeAt(i);
+		h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+	}
+	return h.toString(16).padStart(8, "0");
+}
+/** The billable shape of a plan — only fields that, if changed, require a new
+* provider Price (immutable) or entitlement migration. label/description are
+* cosmetic and excluded so copy edits don't churn the provider. */
+function planHashInput(plan) {
+	return {
+		price: plan.price,
+		interval: plan.interval,
+		inclusions: plan.inclusions.map((i) => ({
+			feature: i.feature,
+			kind: i.kind,
+			allowance: i.allowance,
+			enabled: i.enabled,
+			window: i.window,
+			overage: i.overage ? { allow: i.overage.allow } : void 0
+		}))
+	};
+}
+function planHash(plan) {
+	return fnv1a(stableStringify(planHashInput(plan)));
+}
+/** Hash of ONLY what the payment provider needs (price + interval). The
+* reconciler keys on this so allowance/window/overage edits — which our own
+* ledger enforces, not the provider — never mint a new provider product. */
+function planPriceHash(plan) {
+	return fnv1a(stableStringify({
+		price: plan.price,
+		interval: plan.interval
+	}));
+}
+function addOnHashInput(addOn) {
+	return {
+		price: addOn.price,
+		interval: addOn.interval,
+		unit: addOn.unit,
+		sizeMultipliers: addOn.sizeMultipliers,
+		metadata: addOn.metadata
+	};
+}
+function addOnHash(addOn) {
+	return fnv1a(stableStringify(addOnHashInput(addOn)));
+}
+function addOnPriceHash(addOn) {
+	return fnv1a(stableStringify({
+		price: addOn.price,
+		interval: addOn.interval
+	}));
+}
+function toCatalog(billing) {
+	return {
+		version: 1,
+		provider: {
+			name: billing.provider.name,
+			useProviderMeters: false
+		},
+		credit: billing.credit,
+		features: billing.features.map((f) => ({
+			key: f.key,
+			kind: f.kind,
+			label: f.label ?? f.key,
+			unit: f.unit
+		})),
+		rateCards: billing.rateCards,
+		plans: billing.plans.map((p) => ({
+			key: p.key,
+			label: p.label,
+			description: p.description,
+			price: p.price,
+			interval: p.interval,
+			default: p.default,
+			inclusions: p.inclusions.map((i) => ({
+				feature: i.feature,
+				kind: i.kind,
+				allowance: i.allowance,
+				enabled: i.enabled,
+				window: i.window,
+				overage: i.overage ? { allow: i.overage.allow } : void 0
+			})),
+			hash: planHash(p),
+			priceHash: planPriceHash(p)
+		})),
+		addOns: billing.addOns.map((a) => ({
+			key: a.key,
+			label: a.label,
+			description: a.description,
+			price: a.price,
+			interval: a.interval,
+			unit: a.unit,
+			sizeMultipliers: a.sizeMultipliers,
+			metadata: a.metadata,
+			hash: addOnHash(a),
+			priceHash: addOnPriceHash(a)
+		})),
+		grants: billing.grants
+	};
+}
+/** Emit the canonical catalog string the Go reconciler reads. */
+function serializeCatalog(billing) {
+	return stableStringify(toCatalog(billing));
+}
+//#endregion
+export { addOnHash, addOnPriceHash, fnv1a, planHash, planPriceHash, serializeCatalog, stableStringify, toCatalog };

package/dist/index.mjs

@@ -0,0 +1,152 @@
+//#region src/index.ts
+const MICROS_PER_UNIT = 1e6;
+/** Dollars (or whole credit units) → integer micro-units. usd(0.000015) → 15. */
+function usd(amount) {
+	return Math.round(amount * MICROS_PER_UNIT);
+}
+/** Parse a "$5" / "$0.25" / "5" string, or pass Money through unchanged. */
+function money(input) {
+	if (typeof input === "number") return input;
+	const cleaned = input.trim().replace(/^\$/, "").replace(/,/g, "");
+	const n = Number(cleaned);
+	if (!Number.isFinite(n)) throw new Error(`@omg-dev/billing: cannot parse money value ${JSON.stringify(input)}`);
+	return usd(n);
+}
+/** Render µ-units back to a "$X.XX" string for the UI. */
+function formatMoney(m, opts = {}) {
+	const symbol = opts.symbol ?? "$";
+	const v = m / MICROS_PER_UNIT;
+	return `${symbol}${Number.isInteger(v) ? v.toString() : trimFloat(v)}`;
+}
+function trimFloat(v) {
+	return v.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
+}
+function limit(amount, opts = {}) {
+	return {
+		__kind: "limit",
+		amount: money(amount),
+		window: opts.per
+	};
+}
+function overage(opts = {}) {
+	return {
+		__kind: "overage",
+		allow: opts.allow ?? true
+	};
+}
+function rateCard(models) {
+	return {
+		__kind: "rateCard",
+		models
+	};
+}
+function stripe() {
+	return {
+		name: "stripe",
+		useProviderMeters: false
+	};
+}
+function polar() {
+	return {
+		name: "polar",
+		useProviderMeters: false
+	};
+}
+function plan(input) {
+	return {
+		__kind: "plan",
+		...input
+	};
+}
+function addOn(input) {
+	return {
+		__kind: "addOn",
+		...input
+	};
+}
+function titleCase(key) {
+	return key.split(/[_\s-]+/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+function defineBilling(config) {
+	if (new Set(Object.keys(config.features)).size === 0) throw new Error("@omg-dev/billing: at least one feature must be declared");
+	const planKeys = Object.keys(config.plans);
+	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(", ")}])`);
+	const rateCards = config.usage ?? {};
+	for (const fkey of Object.keys(rateCards)) {
+		const f = config.features[fkey];
+		if (!f) throw new Error(`@omg-dev/billing: rate card references unknown feature "${fkey}"`);
+		if (f.kind !== "metered") throw new Error(`@omg-dev/billing: rate card on non-metered feature "${fkey}"`);
+	}
+	const grants = Object.values(config.grants ?? {});
+	for (const g of grants) {
+		const f = config.features[g.feature];
+		if (!f) throw new Error(`@omg-dev/billing: grant references unknown feature "${g.feature}"`);
+		if (f.kind !== "metered") throw new Error(`@omg-dev/billing: grant on non-metered feature "${g.feature}"`);
+	}
+	const features = Object.entries(config.features).map(([key, def]) => ({
+		key,
+		...def,
+		label: def.label ?? titleCase(key)
+	}));
+	const plans = Object.entries(config.plans).map(([key, p]) => {
+		const includes = p.includes ?? {};
+		const usage = p.usage ?? {};
+		const inclusions = Object.entries(includes).map(([feature, inc]) => {
+			const f = config.features[feature];
+			if (!f) throw new Error(`@omg-dev/billing: plan "${key}" includes unknown feature "${feature}"`);
+			if (f.kind === "metered") {
+				if (typeof inc === "boolean") throw new Error(`@omg-dev/billing: plan "${key}" feature "${feature}" is metered but got a boolean inclusion`);
+				return {
+					feature,
+					kind: "metered",
+					allowance: inc.amount,
+					window: inc.window,
+					overage: usage[feature]
+				};
+			}
+			if (typeof inc !== "boolean") throw new Error(`@omg-dev/billing: plan "${key}" feature "${feature}" is boolean but got a limit inclusion`);
+			return {
+				feature,
+				kind: "boolean",
+				enabled: inc
+			};
+		});
+		return {
+			key,
+			label: p.label ?? titleCase(key),
+			description: p.description,
+			price: p.price,
+			interval: p.interval,
+			default: p.default ?? false,
+			inclusions
+		};
+	});
+	const addOns = Object.entries(config.addOns ?? {}).map(([key, a]) => {
+		if (!Number.isInteger(a.price) || a.price < 0) throw new Error(`@omg-dev/billing: add-on "${key}" price must be a non-negative integer`);
+		if (a.interval !== "month" && a.interval !== "year") throw new Error(`@omg-dev/billing: add-on "${key}" interval must be month or year`);
+		return {
+			key,
+			label: a.label ?? titleCase(key),
+			description: a.description,
+			price: a.price,
+			interval: a.interval,
+			unit: a.unit,
+			sizeMultipliers: a.sizeMultipliers,
+			metadata: a.metadata
+		};
+	});
+	return {
+		provider: config.provider,
+		credit: config.credit,
+		features,
+		plans,
+		addOns,
+		rateCards,
+		grants,
+		config
+	};
+}
+//#endregion
+export { MICROS_PER_UNIT, addOn, defineBilling, formatMoney, limit, money, overage, plan, polar, rateCard, stripe, usd };

package/dist/react.mjs

@@ -0,0 +1,134 @@
+import { formatMoney } from "./index.mjs";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/react.tsx
+function intervalSuffix(interval) {
+	if (!interval) return "";
+	return interval === "month" ? "/mo" : "/yr";
+}
+function priceLabel(price, interval) {
+	if (price === 0) return "Free";
+	return `${formatMoney(price)}${intervalSuffix(interval)}`;
+}
+/** One human-readable line per inclusion, derived from the normalized plan. */
+function inclusionLines(plan, billing, renderInclusion) {
+	const labelFor = (key) => billing.features.find((f) => f.key === key)?.label ?? key;
+	const lines = [];
+	for (const inc of plan.inclusions) {
+		const override = renderInclusion?.(inc, {
+			plan,
+			billing
+		});
+		if (override != null) {
+			lines.push(override);
+			continue;
+		}
+		if (inc.kind === "metered") {
+			let line = `${inc.allowance != null ? formatMoney(inc.allowance) : "—"} ${labelFor(inc.feature)}`;
+			if (inc.overage?.allow) line += ", then pay-as-you-go";
+			lines.push(line);
+		} else if (inc.enabled) lines.push(labelFor(inc.feature));
+	}
+	return lines;
+}
+function PricingTable({ billing, currentPlan, onSelectPlan, ctaLabel, renderInclusion, className, sortByPrice = true }) {
+	return /* @__PURE__ */ jsx("div", {
+		className,
+		style: {
+			display: "grid",
+			gridTemplateColumns: "repeat(auto-fit, minmax(220px, 1fr))",
+			gap: "1rem"
+		},
+		"data-vibes-pricing-table": true,
+		children: React.useMemo(() => {
+			const list = [...billing.plans];
+			if (sortByPrice) list.sort((a, b) => a.price - b.price);
+			return list;
+		}, [billing.plans, 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,
+				style: {
+					border: "1px solid var(--border, #e5e7eb)",
+					borderRadius: "0.75rem",
+					padding: "1.25rem",
+					display: "flex",
+					flexDirection: "column",
+					gap: "0.75rem"
+				},
+				children: [
+					/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("div", {
+						style: {
+							fontWeight: 600,
+							fontSize: "1rem"
+						},
+						children: plan.label
+					}), plan.description ? /* @__PURE__ */ jsx("div", {
+						style: {
+							fontSize: "0.8125rem",
+							opacity: .7
+						},
+						children: plan.description
+					}) : null] }),
+					/* @__PURE__ */ jsx("div", {
+						style: {
+							fontSize: "1.5rem",
+							fontWeight: 700
+						},
+						children: priceLabel(plan.price, plan.interval)
+					}),
+					/* @__PURE__ */ jsx("ul", {
+						style: {
+							listStyle: "none",
+							padding: 0,
+							margin: 0,
+							display: "grid",
+							gap: "0.375rem",
+							flex: 1
+						},
+						children: lines.map((line, i) => /* @__PURE__ */ jsxs("li", {
+							style: {
+								fontSize: "0.875rem",
+								display: "flex",
+								gap: "0.5rem"
+							},
+							children: [/* @__PURE__ */ jsx("span", {
+								"aria-hidden": true,
+								children: "✓"
+							}), /* @__PURE__ */ jsx("span", { children: line })]
+						}, i))
+					}),
+					isCurrent ? /* @__PURE__ */ jsx("div", {
+						style: {
+							textAlign: "center",
+							fontSize: "0.875rem",
+							fontWeight: 600,
+							opacity: .7,
+							padding: "0.5rem"
+						},
+						"data-current": true,
+						children: "Current plan"
+					}) : onSelectPlan ? /* @__PURE__ */ jsx("button", {
+						type: "button",
+						onClick: () => onSelectPlan(plan.key),
+						style: {
+							cursor: "pointer",
+							border: "1px solid var(--border, #e5e7eb)",
+							borderRadius: "0.5rem",
+							padding: "0.5rem 0.75rem",
+							fontSize: "0.875rem",
+							fontWeight: 600,
+							background: plan.default ? "var(--primary, #111)" : "transparent",
+							color: plan.default ? "var(--primary-foreground, #fff)" : "inherit"
+						},
+						children: ctaLabel ? ctaLabel(plan) : `Choose ${plan.label}`
+					}) : null
+				]
+			}, plan.key);
+		})
+	});
+}
+//#endregion
+export { PricingTable };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@omg-dev/billing",
+  "version": "0.4.24",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./react": {
+      "types": "./src/react.tsx",
+      "default": "./dist/react.mjs"
+    },
+    "./catalog": {
+      "types": "./src/catalog.ts",
+      "default": "./dist/catalog.mjs"
+    }
+  },
+  "scripts": {
+    "test": "vp test run"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BennyKok/vibes.git"
+  },
+  "homepage": "https://docs.omg.dev",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,194 @@
+// Catalog serializer: Billing → canonical JSON the Go reconciler consumes.
+//
+// Go cannot execute the TS defineBilling declaration, so we emit a stable,
+// hashable catalog. Determinism matters: the per-plan `hash` is what the
+// reconciler diffs to decide create / update / version-bump / archive, so the
+// same config MUST always serialize byte-identically.
+
+import type {
+  Billing,
+  GrantDef,
+  Money,
+  NormalizedAddOn,
+  NormalizedPlan,
+  RateCard,
+} from "./index.ts";
+
+export interface CatalogPlan {
+  key: string;
+  label: string;
+  description?: string;
+  price: Money;
+  interval?: "month" | "year";
+  default: boolean;
+  inclusions: Array<{
+    feature: string;
+    kind: "metered" | "boolean";
+    allowance?: Money;
+    enabled?: boolean;
+    window?: "day" | "week" | "month";
+    overage?: { allow: boolean };
+  }>;
+  /** Stable hash of this plan's FULL billable shape (price + interval +
+   *  inclusions + windows). Reference / change-detection. */
+  hash: string;
+  /** Hash of ONLY the provider-relevant shape (price + interval). The Stripe/
+   *  Polar reconciler diffs on THIS, so changing an allowance/window/overage is
+   *  a pure ledger config change that never churns a provider product — only a
+   *  real price change does. */
+  priceHash: string;
+}
+
+export interface CatalogAddOn {
+  key: string;
+  label: string;
+  description?: string;
+  price: Money;
+  interval: "month" | "year";
+  unit?: string;
+  sizeMultipliers?: Record<string, number>;
+  metadata?: Record<string, string>;
+  hash: string;
+  priceHash: string;
+}
+
+export interface Catalog {
+  version: 1;
+  provider: { name: string; useProviderMeters: false };
+  credit: { unit: string; peg: Money };
+  features: Array<{ key: string; kind: string; label: string; unit?: string }>;
+  rateCards: Record<string, RateCard>;
+  plans: CatalogPlan[];
+  addOns: CatalogAddOn[];
+  grants: GrantDef[];
+}
+
+/** Recursively sort object keys so JSON.stringify is order-independent. */
+function sortDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortDeep);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(value as Record<string, unknown>).sort()) {
+      const v = (value as Record<string, unknown>)[k];
+      if (v !== undefined) out[k] = sortDeep(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** Canonical stringify: sorted keys, undefined dropped, no incidental whitespace. */
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(sortDeep(value));
+}
+
+// FNV-1a 32-bit — small, dependency-free, stable across TS and Go.
+export function fnv1a(str: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
+}
+
+/** The billable shape of a plan — only fields that, if changed, require a new
+ * provider Price (immutable) or entitlement migration. label/description are
+ * cosmetic and excluded so copy edits don't churn the provider. */
+function planHashInput(plan: NormalizedPlan) {
+  return {
+    price: plan.price,
+    interval: plan.interval,
+    inclusions: plan.inclusions.map((i) => ({
+      feature: i.feature,
+      kind: i.kind,
+      allowance: i.allowance,
+      enabled: i.enabled,
+      window: i.window,
+      overage: i.overage ? { allow: i.overage.allow } : undefined,
+    })),
+  };
+}
+
+export function planHash(plan: NormalizedPlan): string {
+  return fnv1a(stableStringify(planHashInput(plan)));
+}
+
+/** Hash of ONLY what the payment provider needs (price + interval). The
+ * reconciler keys on this so allowance/window/overage edits — which our own
+ * ledger enforces, not the provider — never mint a new provider product. */
+export function planPriceHash(plan: NormalizedPlan): string {
+  return fnv1a(stableStringify({ price: plan.price, interval: plan.interval }));
+}
+
+function addOnHashInput(addOn: NormalizedAddOn) {
+  return {
+    price: addOn.price,
+    interval: addOn.interval,
+    unit: addOn.unit,
+    sizeMultipliers: addOn.sizeMultipliers,
+    metadata: addOn.metadata,
+  };
+}
+
+export function addOnHash(addOn: NormalizedAddOn): string {
+  return fnv1a(stableStringify(addOnHashInput(addOn)));
+}
+
+export function addOnPriceHash(addOn: NormalizedAddOn): string {
+  return fnv1a(stableStringify({ price: addOn.price, interval: addOn.interval }));
+}
+
+export function toCatalog(billing: Billing): Catalog {
+  return {
+    version: 1,
+    provider: {
+      name: billing.provider.name,
+      useProviderMeters: false,
+    },
+    credit: billing.credit,
+    features: billing.features.map((f) => ({
+      key: f.key,
+      kind: f.kind,
+      label: f.label ?? f.key,
+      unit: f.unit,
+    })),
+    rateCards: billing.rateCards,
+    plans: billing.plans.map((p) => ({
+      key: p.key,
+      label: p.label,
+      description: p.description,
+      price: p.price,
+      interval: p.interval,
+      default: p.default,
+      inclusions: p.inclusions.map((i) => ({
+        feature: i.feature,
+        kind: i.kind,
+        allowance: i.allowance,
+        enabled: i.enabled,
+        window: i.window,
+        overage: i.overage ? { allow: i.overage.allow } : undefined,
+      })),
+      hash: planHash(p),
+      priceHash: planPriceHash(p),
+    })),
+    addOns: billing.addOns.map((a) => ({
+      key: a.key,
+      label: a.label,
+      description: a.description,
+      price: a.price,
+      interval: a.interval,
+      unit: a.unit,
+      sizeMultipliers: a.sizeMultipliers,
+      metadata: a.metadata,
+      hash: addOnHash(a),
+      priceHash: addOnPriceHash(a),
+    })),
+    grants: billing.grants,
+  };
+}
+
+/** Emit the canonical catalog string the Go reconciler reads. */
+export function serializeCatalog(billing: Billing): string {
+  return stableStringify(toCatalog(billing));
+}