@omg-dev/billing 0.4.24

package/src/index.ts

@@ -0,0 +1,412 @@
+// @omg-dev/billing — code-declared, framework-reconciled billing.
+//
+// The declaration in this file is the SOURCE OF TRUTH ("code wins"). The Go
+// reconciler projects it into a connected provider (Stripe/Polar); the React
+// <PricingTable> renders from the same object. Money is integer MICRO-UNITS of
+// the tenant credit (µ-unit), so there is never a float in the ledger.
+
+// ---------------------------------------------------------------------------
+// Money — integer micro-units. usd(1) === 1_000_000. Never a float at rest.
+// ---------------------------------------------------------------------------
+
+export type Money = number & { readonly __brand: "Money" };
+
+export const MICROS_PER_UNIT = 1_000_000;
+
+/** Dollars (or whole credit units) → integer micro-units. usd(0.000015) → 15. */
+export function usd(amount: number): Money {
+  return Math.round(amount * MICROS_PER_UNIT) as Money;
+}
+
+/** Parse a "$5" / "$0.25" / "5" string, or pass Money through unchanged. */
+export function money(input: Money | string | number): Money {
+  if (typeof input === "number") return input as Money;
+  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. */
+export function formatMoney(m: Money, opts: { symbol?: string } = {}): string {
+  const symbol = opts.symbol ?? "$";
+  const v = m / MICROS_PER_UNIT;
+  // whole numbers render without cents; fractional keeps up to 6 sig digits
+  const str = Number.isInteger(v) ? v.toString() : trimFloat(v);
+  return `${symbol}${str}`;
+}
+
+function trimFloat(v: number): string {
+  return v.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+// ---------------------------------------------------------------------------
+// Features — what a plan can include / meter.
+// ---------------------------------------------------------------------------
+
+export type FeatureKind = "metered" | "boolean";
+
+export interface FeatureDef {
+  kind: FeatureKind;
+  /** Human label for the pricing UI. Defaults to a title-cased key. */
+  label?: string;
+  /** Unit noun shown in the UI for metered features ("tokens", "builds"). */
+  unit?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Plan inclusions / overage policy.
+// ---------------------------------------------------------------------------
+
+/**
+ * Recurring window a limit resets on. Omitted = the plan's billing period
+ * (monthly). "day"/"week"/"month" → the allowance is a windowed hard-cap that
+ * refills each calendar window (use-it-or-lose-it), like a Claude usage limit.
+ */
+export type BillingWindow = "day" | "week" | "month";
+
+/** A metered allowance bundled into a plan (e.g. $5 of llm_usage per week). */
+export interface Limit {
+  readonly __kind: "limit";
+  amount: Money;
+  /** Reset cadence. Undefined → granted once per billing period (legacy
+   *  monthly). Set → a windowed limit that refills every calendar window. */
+  window?: BillingWindow;
+}
+
+/** Overage policy once the included allowance is exhausted. */
+export interface Overage {
+  readonly __kind: "overage";
+  /** If false, hard-stop at the limit. If true, meter beyond at rate-card price. */
+  allow: boolean;
+}
+
+export function limit(
+  amount: Money | string | number,
+  opts: { per?: BillingWindow } = {},
+): Limit {
+  return { __kind: "limit", amount: money(amount), window: opts.per };
+}
+
+export function overage(opts: { allow?: boolean } = {}): Overage {
+  return { __kind: "overage", allow: opts.allow ?? true };
+}
+
+/** A per-feature inclusion: a metered allowance, or a boolean entitlement. */
+export type Inclusion = Limit | boolean;
+
+// ---------------------------------------------------------------------------
+// Rate card — synthetic PRICE per metered unit (NOT pass-through cost).
+// Per-model token pricing; cache buckets are first-class (see llm.go).
+// ---------------------------------------------------------------------------
+
+export interface ModelRate {
+  in: Money;
+  out: Money;
+  cacheRead?: Money;
+  cacheCreation?: Money;
+  /** Lowest plan key allowed to use this model. Omitted = default plan. */
+  minPlan?: string;
+}
+
+export interface RateCard {
+  readonly __kind: "rateCard";
+  models: Record<string, ModelRate>;
+}
+
+export function rateCard(models: Record<string, ModelRate>): RateCard {
+  return { __kind: "rateCard", models };
+}
+
+// ---------------------------------------------------------------------------
+// Provider descriptors.
+// ---------------------------------------------------------------------------
+
+export type ProviderName = "stripe" | "polar";
+
+export interface ProviderDef {
+  name: ProviderName;
+  /** Use provider-side meters? We deliberately keep this false — our ledger meters. */
+  useProviderMeters: false;
+}
+
+export function stripe(): ProviderDef {
+  return { name: "stripe", useProviderMeters: false };
+}
+
+export function polar(): ProviderDef {
+  return { name: "polar", useProviderMeters: false };
+}
+
+// ---------------------------------------------------------------------------
+// Plan definition (authoring shape).
+// ---------------------------------------------------------------------------
+
+export interface PlanInput {
+  /** Recurring price. usd(0) for a free plan. */
+  price: Money;
+  interval?: "month" | "year";
+  /** Exactly one plan should set default:true (the plan new customers land on). */
+  default?: boolean;
+  label?: string;
+  description?: string;
+  /** Per-feature inclusions: feature key → Limit | boolean. */
+  includes?: Record<string, Inclusion>;
+  /** Per-feature overage policy once the inclusion is exhausted. */
+  usage?: Record<string, Overage>;
+}
+
+export interface PlanDef extends PlanInput {
+  readonly __kind: "plan";
+}
+
+export function plan(input: PlanInput): PlanDef {
+  return { __kind: "plan", ...input };
+}
+
+// ---------------------------------------------------------------------------
+// Add-ons — recurring provider items that sit beside the base plan.
+// ---------------------------------------------------------------------------
+
+export interface AddOnInput {
+  price: Money;
+  interval: "month" | "year";
+  label?: string;
+  description?: string;
+  unit?: string;
+  /**
+   * Optional size multipliers for add-ons whose quantity is weighted by an
+   * app/runtime size. The engine does not interpret these; platform code reads
+   * them from the catalog so rate-card config remains code-owned.
+   */
+  sizeMultipliers?: Record<string, number>;
+  /**
+   * Extra stable config for platform-owned add-ons, e.g. the VM scaling mode
+   * this add-on prices. Kept stringly so the SDK stays provider-agnostic.
+   */
+  metadata?: Record<string, string>;
+}
+
+export interface AddOnDef extends AddOnInput {
+  readonly __kind: "addOn";
+}
+
+export function addOn(input: AddOnInput): AddOnDef {
+  return { __kind: "addOn", ...input };
+}
+
+// ---------------------------------------------------------------------------
+// Grants — automatic credit grants on a lifecycle event.
+// ---------------------------------------------------------------------------
+
+export interface GrantDef {
+  /** Lifecycle trigger, e.g. "customer.created" for the signup grant. */
+  on: string;
+  amount: Money;
+  /** Which metered feature the grant funds. */
+  feature: string;
+  /** Optional: expire the grant N days after issue (undefined = never). */
+  expiresInDays?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Top-level config.
+// ---------------------------------------------------------------------------
+
+export interface BillingConfig {
+  provider: ProviderDef;
+  /** Credit unit + peg. omg: { unit: "usd", peg: usd(1) } => 1 credit = $1. */
+  credit: { unit: string; peg: Money };
+  features: Record<string, FeatureDef>;
+  usage?: Record<string, RateCard>;
+  plans: Record<string, PlanDef>;
+  addOns?: Record<string, AddOnDef>;
+  grants?: Record<string, GrantDef>;
+}
+
+// ---------------------------------------------------------------------------
+// Normalized, introspectable Billing object — the single shape the serializer
+// AND the <PricingTable> read from. defineBilling validates + normalizes.
+// ---------------------------------------------------------------------------
+
+export interface NormalizedFeature extends FeatureDef {
+  key: string;
+}
+
+export interface NormalizedPlanInclusion {
+  feature: string;
+  /** "metered" inclusion carries an allowance; "boolean" carries enabled. */
+  kind: FeatureKind;
+  allowance?: Money;
+  enabled?: boolean;
+  /** Reset window for a metered allowance (undefined = monthly billing period). */
+  window?: BillingWindow;
+  /** Overage policy for this feature on this plan, if any. */
+  overage?: Overage;
+}
+
+export interface NormalizedPlan {
+  key: string;
+  label: string;
+  description?: string;
+  price: Money;
+  interval?: "month" | "year";
+  default: boolean;
+  inclusions: NormalizedPlanInclusion[];
+}
+
+export interface NormalizedAddOn {
+  key: string;
+  label: string;
+  description?: string;
+  price: Money;
+  interval: "month" | "year";
+  unit?: string;
+  sizeMultipliers?: Record<string, number>;
+  metadata?: Record<string, string>;
+}
+
+export interface Billing {
+  provider: ProviderDef;
+  credit: { unit: string; peg: Money };
+  features: NormalizedFeature[];
+  plans: NormalizedPlan[];
+  addOns: NormalizedAddOn[];
+  rateCards: Record<string, RateCard>;
+  grants: GrantDef[];
+  /** The raw validated config, for callers that want the authoring shape. */
+  config: BillingConfig;
+}
+
+function titleCase(key: string): string {
+  return key
+    .split(/[_\s-]+/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+export function defineBilling(config: BillingConfig): Billing {
+  // --- validation (fail loud; never silently default) ----------------------
+  const featureKeys = new Set(Object.keys(config.features));
+  if (featureKeys.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(", ")}])`,
+    );
+  }
+
+  // rate cards may only reference declared metered features
+  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}"`);
+    }
+  }
+
+  // grants must reference declared metered features
+  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}"`);
+    }
+  }
+
+  // --- normalize -----------------------------------------------------------
+  const features: NormalizedFeature[] = Object.entries(config.features).map(
+    ([key, def]) => ({ key, ...def, label: def.label ?? titleCase(key) }),
+  );
+
+  const plans: NormalizedPlan[] = Object.entries(config.plans).map(([key, p]) => {
+    const includes = p.includes ?? {};
+    const usage = p.usage ?? {};
+    const inclusions: NormalizedPlanInclusion[] = 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 as Limit).amount,
+            window: (inc as Limit).window,
+            overage: usage[feature],
+          };
+        }
+        // boolean 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: NormalizedAddOn[] = 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,
+  };
+}

package/src/react.tsx

@@ -0,0 +1,175 @@
+// Reusable pricing UI, rendered straight from the Billing declaration so the
+// table can never drift from the code that the reconciler/ledger enforce.
+
+import * as React from "react";
+import {
+  type Billing,
+  type Money,
+  type NormalizedPlan,
+  type NormalizedPlanInclusion,
+  formatMoney,
+} from "./index.ts";
+
+export interface PricingTableProps {
+  billing: Billing;
+  /** Currently active plan key — renders "Current plan" instead of a CTA. */
+  currentPlan?: string;
+  /** CTA handler. Omit to render the table read-only (marketing pages). */
+  onSelectPlan?: (planKey: string) => void;
+  /** Override CTA label (default: "Choose <Plan>"). */
+  ctaLabel?: (plan: NormalizedPlan) => string;
+  /**
+   * Override the rendered text of a single inclusion line. Return a string to
+   * replace the default (e.g. "$3 Build AI"), or null/undefined to keep it.
+   * Lets a caller display usage multipliers ("5× Build AI") instead of raw
+   * dollar allowances without forking the table.
+   */
+  renderInclusion?: (
+    inc: NormalizedPlanInclusion,
+    ctx: { plan: NormalizedPlan; billing: Billing },
+  ) => string | null | undefined;
+  className?: string;
+  /** Order plans by price ascending (default true). */
+  sortByPrice?: boolean;
+}
+
+function intervalSuffix(interval?: "month" | "year"): string {
+  if (!interval) return "";
+  return interval === "month" ? "/mo" : "/yr";
+}
+
+function priceLabel(price: Money, interval?: "month" | "year"): string {
+  if (price === 0) return "Free";
+  return `${formatMoney(price)}${intervalSuffix(interval)}`;
+}
+
+/** One human-readable line per inclusion, derived from the normalized plan. */
+function inclusionLines(
+  plan: NormalizedPlan,
+  billing: Billing,
+  renderInclusion?: PricingTableProps["renderInclusion"],
+): string[] {
+  const labelFor = (key: string) =>
+    billing.features.find((f) => f.key === key)?.label ?? key;
+  const lines: string[] = [];
+  for (const inc of plan.inclusions) {
+    const override = renderInclusion?.(inc, { plan, billing });
+    if (override != null) {
+      lines.push(override);
+      continue;
+    }
+    if (inc.kind === "metered") {
+      const amount = inc.allowance != null ? formatMoney(inc.allowance) : "—";
+      let line = `${amount} ${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;
+}
+
+export function PricingTable({
+  billing,
+  currentPlan,
+  onSelectPlan,
+  ctaLabel,
+  renderInclusion,
+  className,
+  sortByPrice = true,
+}: PricingTableProps) {
+  const plans = React.useMemo(() => {
+    const list = [...billing.plans];
+    if (sortByPrice) list.sort((a, b) => a.price - b.price);
+    return list;
+  }, [billing.plans, sortByPrice]);
+
+  return (
+    <div
+      className={className}
+      style={{
+        display: "grid",
+        // auto-fit lets the cards stack on narrow screens without a media
+        // query (inline styles can't carry one) — 220px min per card.
+        gridTemplateColumns: "repeat(auto-fit, minmax(220px, 1fr))",
+        gap: "1rem",
+      }}
+      data-vibes-pricing-table
+    >
+      {plans.map((plan) => {
+        const isCurrent = currentPlan === plan.key;
+        const lines = inclusionLines(plan, billing, renderInclusion);
+        return (
+          <div
+            key={plan.key}
+            data-plan={plan.key}
+            data-default={plan.default || undefined}
+            style={{
+              border: "1px solid var(--border, #e5e7eb)",
+              borderRadius: "0.75rem",
+              padding: "1.25rem",
+              display: "flex",
+              flexDirection: "column",
+              gap: "0.75rem",
+            }}
+          >
+            <div>
+              <div style={{ fontWeight: 600, fontSize: "1rem" }}>{plan.label}</div>
+              {plan.description ? (
+                <div style={{ fontSize: "0.8125rem", opacity: 0.7 }}>
+                  {plan.description}
+                </div>
+              ) : null}
+            </div>
+
+            <div style={{ fontSize: "1.5rem", fontWeight: 700 }}>
+              {priceLabel(plan.price, plan.interval)}
+            </div>
+
+            <ul style={{ listStyle: "none", padding: 0, margin: 0, display: "grid", gap: "0.375rem", flex: 1 }}>
+              {lines.map((line, i) => (
+                <li key={i} style={{ fontSize: "0.875rem", display: "flex", gap: "0.5rem" }}>
+                  <span aria-hidden>✓</span>
+                  <span>{line}</span>
+                </li>
+              ))}
+            </ul>
+
+            {isCurrent ? (
+              <div
+                style={{
+                  textAlign: "center",
+                  fontSize: "0.875rem",
+                  fontWeight: 600,
+                  opacity: 0.7,
+                  padding: "0.5rem",
+                }}
+                data-current
+              >
+                Current plan
+              </div>
+            ) : onSelectPlan ? (
+              <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",
+                }}
+              >
+                {ctaLabel ? ctaLabel(plan) : `Choose ${plan.label}`}
+              </button>
+            ) : null}
+          </div>
+        );
+      })}
+    </div>
+  );
+}