@absolutejs/billing 0.1.0

package/LICENSE

@@ -0,0 +1,93 @@
+# Business Source License 1.1
+
+**Licensor:** Alex Kahn
+
+**Licensed Work:** @absolutejs/billing (https://github.com/absolutejs/billing)
+
+**Change Date:** May 31, 2030
+
+**Change License:** Apache License, Version 2.0
+
+---
+
+## Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, permitting limited production use.
+
+### Additional Use Grant
+
+You may use the Licensed Work in production, provided your use does not include
+any of the following:
+
+1. **Offering a Competing Service.** You may not offer the Licensed Work, or
+   any derivative or substantial portion of it, to third parties as a hosted or
+   managed metering, rating, or usage-based-billing service that competes with
+   hosted SaaS-billing offerings (including, but not limited to, Metronome,
+   Orb, Lago, Stripe Billing, m3ter, Chargebee, Recurly, Maxio, Zuora, Sage
+   Intacct Subscriptions, OctaneAI Billing, Togai, or any similar hosted
+   offering whose primary value to its users is metering, rating, and invoicing
+   usage-based products). This includes any product whose primary value to its
+   users is the functionality the Licensed Work provides.
+
+2. **Resale or Redistribution as a Standalone Product.** You may not sell,
+   license, or distribute the Licensed Work, or any derivative or fork of it,
+   as a standalone commercial product.
+
+3. **Removal of Attribution.** Any derivative work, fork, or redistribution of
+   the Licensed Work must prominently credit AbsoluteJS and include a link to
+   the original project repository (https://github.com/absolutejs/billing).
+
+For clarity, the following uses are expressly permitted:
+
+- Using the Licensed Work to compute invoices for your own customers, internal
+  cost dashboards, finance reports, or SaaS products (whether commercial or
+  non-commercial), so long as the Licensed Work itself is not the primary
+  product you are selling.
+- Using the Licensed Work as a dependency in commercial software you build and
+  sell, as long as the software is not itself a competing hosted billing
+  service of the kind described in clause 1.
+- Providing consulting, development, or professional services to clients using
+  the Licensed Work.
+- Forking and modifying the Licensed Work for your own internal use, provided
+  attribution is maintained.
+
+### Change Date and Change License
+
+On the Change Date specified above, or on such other date as the Licensor may
+specify by written notice, the Licensed Work will be made available under the
+Change License (Apache License, Version 2.0). Until the Change Date, the terms
+of this Business Source License 1.1 apply.
+
+### Trademark
+
+This license does not grant you any rights to use the "AbsoluteJS" or
+"@absolutejs" name, logo, or any related trademarks. Forks and derivative works
+must not be named or branded in a manner that suggests endorsement by or
+affiliation with AbsoluteJS or the Licensor.
+
+### Notices
+
+You must not remove or obscure any licensing, copyright, or other notices
+included in the Licensed Work.
+
+### No Warranty
+
+THE LICENSED WORK IS PROVIDED "AS IS". THE LICENSOR HEREBY DISCLAIMS ALL
+WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR
+IN CONNECTION WITH THE LICENSED WORK OR THE USE OR OTHER DEALINGS IN THE
+LICENSED WORK.
+
+---
+
+## Contact
+
+For commercial licensing inquiries or additional permissions, contact:
+
+- **Alex Kahn**
+- alexkahndev@gmail.com
+- alexkahndev.github.io

package/README.md

@@ -0,0 +1,92 @@
+# `@absolutejs/billing`
+
+> Cost-model substrate for the AbsoluteJS PaaS.
+
+`@absolutejs/billing` is the pure-function layer between
+`@absolutejs/metering` (which collects usage events) and an
+invoicing backend (Stripe, QuickBooks, an internal billing engine).
+
+It does two things:
+
+1. **`createPlan(...)`** — declares a priced product: optional flat
+   base fee, per-dimension unit prices, optional graduated tiers,
+   optional per-dimension free allowances.
+2. **`computeInvoice({ plan, period, tenant, usage })`** — pure
+   function that turns a `Usage` snapshot into an `Invoice` with
+   line items and a total.
+
+All money math is done in integer **micros** (1 micro = 1/1,000,000
+of a currency unit — the same denomination Stripe stores prices in
+internally). Float drift is structurally impossible: a $0.0002
+per-request price is `200` and rounding policy is explicit.
+
+```ts
+import { createPlan, computeInvoice, formatMicros } from '@absolutejs/billing';
+
+const plan = createPlan({
+  name: 'pro',
+  currency: 'usd',
+  basePriceMicros: 20_000_000, // $20/mo
+  pricedDimensions: {
+    requests:             { perUnitMicros: 200, freeTier: 1_000_000 },
+    cpuMs:                { perUnitMicros: 50, unit: 1000, freeTier: 60_000 * 60 * 10 },
+    bytesEgress:          { perUnitMicros: 100, unit: 1024 * 1024, freeTier: 100 * 1024 * 1024 },
+    hibernationGbSeconds: { perUnitMicros: 5 },
+  },
+});
+
+const invoice = computeInvoice({
+  plan,
+  tenant: 'acme',
+  period: { start, end },
+  usage, // a Usage from @absolutejs/metering
+});
+
+console.log(formatMicros(invoice.totalMicros, invoice.currency));
+// "27.50 USD"
+```
+
+## Pricing shapes
+
+A `PricedDimension` is one of three:
+
+- **Flat per-unit** — `{ perUnitMicros: 200, unit: 1 }`
+- **Tiered (graduated)** — `{ tiers: [{ upTo: 1_000_000, perUnitMicros: 200 }, { upTo: Infinity, perUnitMicros: 100 }] }`
+- **Custom** — `{ price: (chargedQuantity) => micros }` (escape hatch for surge / caps / non-monotonic pricing)
+
+Optional knobs:
+
+- **`freeTier`** — units subtracted before pricing
+- **`unit`** — divisor so `bytesEgress` priced as MB ↔ `unit:
+  1024*1024`
+- **`label`** — invoice line-item display name
+
+Plan-level knobs:
+
+- **`basePriceMicros`** — flat fee per period
+- **`minimumChargeMicros`** — floor; an adjustment line item fills
+  any gap
+- **`rounding`** — `'truncate'` (default; sub-cent → $0.00) or
+  `'round-half-up'`
+- **`currency`** — display label; not converted
+- **`metadata`** — arbitrary keys that flow through to the invoice
+
+## Why pure?
+
+The control plane needs to:
+
+- **Preview** an upcoming invoice before the period closes
+- **Re-price** a past period under a new plan ("what would this
+  customer have paid on the proposed enterprise tier?")
+- **Dry-run** plan changes before publishing them
+
+A pure cost-model function makes all three trivial — no Stripe SDK,
+no side effects, no IO. The Stripe push (or QuickBooks export, or
+mailed-PDF generator) lives outside this package, in
+`@absolutejs/billing-adapters/*`.
+
+## License
+
+BSL-1.1 with named carveout against hosted SaaS billing platforms
+(Metronome, Orb, Lago, Stripe Billing, m3ter, Chargebee). See
+`LICENSE`. Change date: **2030-05-31** → Apache 2.0.

package/dist/index.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @absolutejs/billing — cost-model substrate for the AbsoluteJS PaaS.
+ *
+ * Two pieces:
+ *
+ *   - `createPlan(...)` — declarative pricing config: optional flat
+ *     base fee + per-dimension unit prices, with optional graduated
+ *     tiers and free-tier allowances per dimension.
+ *
+ *   - `computeInvoice({ plan, period, tenant, usage, currency? })`
+ *     — pure function that turns a `@absolutejs/metering`-shaped
+ *     `Usage` snapshot (or any record of metered numbers) into an
+ *     `Invoice` of line items + total. All money math is done in
+ *     integer **micros** (1 micro = 1/1,000,000 of a currency unit
+ *     — the same denomination Stripe uses internally) so float
+ *     drift is structurally impossible.
+ *
+ * Invoice sinks (push to Stripe, post to QuickBooks, mail a PDF)
+ * live OUTSIDE this package, in `@absolutejs/billing-adapters/*`.
+ * Keeping the substrate pure means the control plane can preview
+ * invoices, run dry-run "would-charge" projections, and replay an
+ * old usage snapshot through a new plan without touching any
+ * vendor SDK.
+ */
+/** Integer micros — 1,000,000 micros = 1 unit of the currency. */
+export type Micros = number;
+/**
+ * Round a fractional micros value to an integer. The substrate uses
+ * **truncation** (banker's-style would surprise callers expecting
+ * "$0.0009 → $0.00" not "$0.0009 → $0.001"). Plans override per-plan.
+ */
+export type Rounding = 'truncate' | 'round-half-up';
+/**
+ * One step in a graduated-tier price table. `upTo` is the inclusive
+ * upper bound (in metered units, NOT micros) for this band.
+ * `perUnitMicros` is what the customer pays per single metered unit
+ * within this band. The last entry must have `upTo: Infinity` to
+ * cover any overflow.
+ */
+export type PricingTier = {
+    upTo: number;
+    perUnitMicros: number;
+};
+/**
+ * Per-dimension pricing. Three shapes:
+ *
+ *   - Flat per-unit: `{ perUnitMicros: 200, unit: 1024 * 1024 }`
+ *     charges 200 micros ($0.0002) per MB of usage.
+ *
+ *   - Tiered: `{ tiers: [...], unit: 1 }` charges per the first
+ *     matching `PricingTier` band.
+ *
+ *   - Custom: `{ price: (quantity) => micros, unit: 1 }` — escape
+ *     hatch for surge / caps / non-monotonic pricing. The substrate
+ *     stays pure; you ship whatever function you want.
+ *
+ * `freeTier` is subtracted from the metered quantity BEFORE pricing
+ * — the conventional "first N units free" rule.
+ *
+ * `unit` is the metered-unit denominator: 1 means "price per single
+ * metered unit", 1024*1024 means "price per MB when quantity is in
+ * bytes." Default 1.
+ *
+ * `label` overrides the line-item display name.
+ */
+export type PricedDimension = {
+    label?: string;
+    freeTier?: number;
+    unit?: number;
+} & ({
+    perUnitMicros: number;
+    tiers?: never;
+    price?: never;
+} | {
+    tiers: PricingTier[];
+    perUnitMicros?: never;
+    price?: never;
+} | {
+    price: (chargedQuantity: number) => Micros;
+    perUnitMicros?: never;
+    tiers?: never;
+});
+export type Plan = {
+    /** Human label for the invoice (`'pro'`, `'enterprise'`, etc.). */
+    name: string;
+    /** Optional flat base fee charged once per invoice period. */
+    basePriceMicros?: Micros;
+    /**
+     * Dimensions priced from usage. Keys must match keys on the
+     * `usage` record passed to `computeInvoice`. Anything not listed
+     * is ignored.
+     */
+    pricedDimensions: Record<string, PricedDimension>;
+    /** Default currency for invoices generated from this plan. */
+    currency?: string;
+    /** Rounding strategy applied per line item. Default `'truncate'`. */
+    rounding?: Rounding;
+    /**
+     * Minimum charge (in micros) — if the computed total is below
+     * this floor, the invoice total is raised to the floor and a
+     * single `'minimum-charge-adjustment'` line item captures the
+     * difference. Defaults to 0 (no floor).
+     */
+    minimumChargeMicros?: Micros;
+    /** Arbitrary plan-level metadata that flows through to invoices. */
+    metadata?: Record<string, string>;
+};
+export declare const createPlan: (plan: Plan) => Plan;
+export type LineItem = {
+    /**
+     * Stable key for the line item. For priced dimensions it's the
+     * usage-record key (`'requests'`, `'cpuMs'`, etc.). For the base
+     * fee it's `'base'`. For minimum-charge top-up it's
+     * `'minimum-charge-adjustment'`.
+     */
+    key: string;
+    /** Human-readable label. */
+    label: string;
+    /** Metered units BEFORE applying free tier. 0 for the base fee. */
+    quantity: number;
+    /** Metered units AFTER applying free tier (what's actually charged). */
+    chargedQuantity: number;
+    /** Free-tier units subtracted from `quantity`. */
+    freeTier?: number;
+    /** Charge for this line in integer micros. */
+    amountMicros: Micros;
+    /**
+     * Tier-by-tier breakdown when graduated pricing was used. Each
+     * entry: `{ tierIndex, unitsInTier, perUnitMicros, amountMicros }`.
+     */
+    tierBreakdown?: Array<{
+        tierIndex: number;
+        unitsInTier: number;
+        perUnitMicros: number;
+        amountMicros: Micros;
+    }>;
+};
+export type InvoicePeriod = {
+    /** Inclusive period start (`Date.now()` ms). */
+    start: number;
+    /** Exclusive period end. */
+    end: number;
+};
+export type Invoice = {
+    tenant: string;
+    plan: string;
+    currency: string;
+    period: InvoicePeriod;
+    lineItems: LineItem[];
+    /** Sum of all `lineItems[].amountMicros`. */
+    totalMicros: Micros;
+    /** Convenience: `totalMicros / 1_000_000` as a number. */
+    totalUnits: number;
+    /** Plan-level metadata copied through unchanged. */
+    metadata?: Record<string, string>;
+};
+export type ComputeInvoiceInput = {
+    plan: Plan;
+    tenant: string;
+    period: InvoicePeriod;
+    /** Metered numbers keyed by the same names as `plan.pricedDimensions`. */
+    usage: Record<string, number>;
+    /** Override the plan's currency (e.g. for tenant-local invoicing). */
+    currency?: string;
+};
+export declare const computeInvoice: ({ plan, tenant, period, usage, currency }: ComputeInvoiceInput) => Invoice;
+/**
+ * Format an integer micros amount as a human currency string. Pure
+ * — no Intl side effects. For locales / advanced formatting, pipe
+ * through `Intl.NumberFormat` yourself.
+ */
+export declare const formatMicros: (amount: Micros, currency: string, { minorUnits }?: {
+    minorUnits?: number;
+}) => string;

package/dist/index.js

@@ -0,0 +1,160 @@
+// @bun
+// src/index.ts
+var roundMicros = (value, rounding) => {
+  if (rounding === "truncate")
+    return Math.trunc(value);
+  return Math.round(value);
+};
+var createPlan = (plan) => {
+  for (const [key, dim] of Object.entries(plan.pricedDimensions)) {
+    if (dim.tiers !== undefined) {
+      if (dim.tiers.length === 0) {
+        throw new Error(`billing: dimension '${key}' has no tiers`);
+      }
+      const last = dim.tiers[dim.tiers.length - 1];
+      if (last !== undefined && Number.isFinite(last.upTo)) {
+        throw new Error(`billing: dimension '${key}' final tier must have upTo: Infinity`);
+      }
+      let prev = 0;
+      for (let i = 0;i < dim.tiers.length; i += 1) {
+        const tier = dim.tiers[i];
+        if (tier.upTo < prev) {
+          throw new Error(`billing: dimension '${key}' tier #${i} upTo (${tier.upTo}) must be >= previous (${prev})`);
+        }
+        prev = tier.upTo;
+      }
+    }
+  }
+  return plan;
+};
+var computeDimension = ({
+  quantity,
+  dim,
+  rounding
+}) => {
+  const free = dim.freeTier ?? 0;
+  const charged = Math.max(0, quantity - free);
+  const unit = dim.unit ?? 1;
+  const chargedUnits = unit === 1 ? charged : charged / unit;
+  if (dim.perUnitMicros !== undefined) {
+    const amountMicros = roundMicros(chargedUnits * dim.perUnitMicros, rounding);
+    return { amountMicros, chargedQuantity: charged };
+  }
+  if (dim.price !== undefined) {
+    const amountMicros = roundMicros(dim.price(charged), rounding);
+    return { amountMicros, chargedQuantity: charged };
+  }
+  const tierBreakdown = [];
+  let remaining = chargedUnits;
+  let bandFloor = 0;
+  let totalMicros = 0;
+  for (let i = 0;i < dim.tiers.length && remaining > 0; i += 1) {
+    const tier = dim.tiers[i];
+    const bandWidth = tier.upTo - bandFloor;
+    const unitsInTier = Math.min(remaining, bandWidth);
+    if (unitsInTier > 0) {
+      const tierMicros = roundMicros(unitsInTier * tier.perUnitMicros, rounding);
+      tierBreakdown.push({
+        amountMicros: tierMicros,
+        perUnitMicros: tier.perUnitMicros,
+        tierIndex: i,
+        unitsInTier
+      });
+      totalMicros += tierMicros;
+    }
+    remaining -= unitsInTier;
+    bandFloor = tier.upTo;
+  }
+  return {
+    amountMicros: totalMicros,
+    chargedQuantity: charged,
+    tierBreakdown
+  };
+};
+var computeInvoice = ({
+  plan,
+  tenant,
+  period,
+  usage,
+  currency
+}) => {
+  const rounding = plan.rounding ?? "truncate";
+  const lineItems = [];
+  if (plan.basePriceMicros !== undefined && plan.basePriceMicros > 0) {
+    lineItems.push({
+      amountMicros: plan.basePriceMicros,
+      chargedQuantity: 1,
+      key: "base",
+      label: `${plan.name} base fee`,
+      quantity: 1
+    });
+  }
+  for (const [key, dim] of Object.entries(plan.pricedDimensions)) {
+    const quantity = usage[key] ?? 0;
+    if (!Number.isFinite(quantity) || quantity < 0)
+      continue;
+    const result = computeDimension({ dim, quantity, rounding });
+    if (result.amountMicros === 0 && result.chargedQuantity === 0)
+      continue;
+    const item = {
+      amountMicros: result.amountMicros,
+      chargedQuantity: result.chargedQuantity,
+      key,
+      label: dim.label ?? key,
+      quantity
+    };
+    if (dim.freeTier !== undefined)
+      item.freeTier = dim.freeTier;
+    if (result.tierBreakdown !== undefined && result.tierBreakdown.length > 0) {
+      item.tierBreakdown = result.tierBreakdown;
+    }
+    lineItems.push(item);
+  }
+  let totalMicros = lineItems.reduce((sum, item) => sum + item.amountMicros, 0);
+  const floor = plan.minimumChargeMicros ?? 0;
+  if (floor > 0 && totalMicros < floor) {
+    const gap = floor - totalMicros;
+    lineItems.push({
+      amountMicros: gap,
+      chargedQuantity: 1,
+      key: "minimum-charge-adjustment",
+      label: "Minimum charge adjustment",
+      quantity: 1
+    });
+    totalMicros = floor;
+  }
+  const invoice = {
+    currency: currency ?? plan.currency ?? "usd",
+    lineItems,
+    period,
+    plan: plan.name,
+    tenant,
+    totalMicros,
+    totalUnits: totalMicros / 1e6
+  };
+  if (plan.metadata !== undefined)
+    invoice.metadata = plan.metadata;
+  return invoice;
+};
+var formatMicros = (amount, currency, { minorUnits = 2 } = {}) => {
+  const sign = amount < 0 ? "-" : "";
+  const abs = Math.abs(amount);
+  const wholeMicrosPerMinor = 10 ** (6 - minorUnits);
+  const minorTotal = Math.round(abs / wholeMicrosPerMinor);
+  const divisor = 10 ** minorUnits;
+  const whole = Math.trunc(minorTotal / divisor);
+  const upper = currency.toUpperCase();
+  if (minorUnits === 0)
+    return `${sign}${whole} ${upper}`;
+  const fraction = minorTotal % divisor;
+  const fractionStr = fraction.toString().padStart(minorUnits, "0");
+  return `${sign}${whole}.${fractionStr} ${upper}`;
+};
+export {
+  formatMicros,
+  createPlan,
+  computeInvoice
+};
+
+//# debugId=1E2BA78C0466F20664756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * @absolutejs/billing — cost-model substrate for the AbsoluteJS PaaS.\n *\n * Two pieces:\n *\n *   - `createPlan(...)` — declarative pricing config: optional flat\n *     base fee + per-dimension unit prices, with optional graduated\n *     tiers and free-tier allowances per dimension.\n *\n *   - `computeInvoice({ plan, period, tenant, usage, currency? })`\n *     — pure function that turns a `@absolutejs/metering`-shaped\n *     `Usage` snapshot (or any record of metered numbers) into an\n *     `Invoice` of line items + total. All money math is done in\n *     integer **micros** (1 micro = 1/1,000,000 of a currency unit\n *     — the same denomination Stripe uses internally) so float\n *     drift is structurally impossible.\n *\n * Invoice sinks (push to Stripe, post to QuickBooks, mail a PDF)\n * live OUTSIDE this package, in `@absolutejs/billing-adapters/*`.\n * Keeping the substrate pure means the control plane can preview\n * invoices, run dry-run \"would-charge\" projections, and replay an\n * old usage snapshot through a new plan without touching any\n * vendor SDK.\n */\n\n// =============================================================================\n// Money primitives\n// =============================================================================\n\n/** Integer micros — 1,000,000 micros = 1 unit of the currency. */\nexport type Micros = number;\n\n/**\n * Round a fractional micros value to an integer. The substrate uses\n * **truncation** (banker's-style would surprise callers expecting\n * \"$0.0009 → $0.00\" not \"$0.0009 → $0.001\"). Plans override per-plan.\n */\nexport type Rounding = 'truncate' | 'round-half-up';\n\nconst roundMicros = (value: number, rounding: Rounding): Micros => {\n\tif (rounding === 'truncate') return Math.trunc(value);\n\treturn Math.round(value);\n};\n\n// =============================================================================\n// Pricing config\n// =============================================================================\n\n/**\n * One step in a graduated-tier price table. `upTo` is the inclusive\n * upper bound (in metered units, NOT micros) for this band.\n * `perUnitMicros` is what the customer pays per single metered unit\n * within this band. The last entry must have `upTo: Infinity` to\n * cover any overflow.\n */\nexport type PricingTier = {\n\tupTo: number;\n\tperUnitMicros: number;\n};\n\n/**\n * Per-dimension pricing. Three shapes:\n *\n *   - Flat per-unit: `{ perUnitMicros: 200, unit: 1024 * 1024 }`\n *     charges 200 micros ($0.0002) per MB of usage.\n *\n *   - Tiered: `{ tiers: [...], unit: 1 }` charges per the first\n *     matching `PricingTier` band.\n *\n *   - Custom: `{ price: (quantity) => micros, unit: 1 }` — escape\n *     hatch for surge / caps / non-monotonic pricing. The substrate\n *     stays pure; you ship whatever function you want.\n *\n * `freeTier` is subtracted from the metered quantity BEFORE pricing\n * — the conventional \"first N units free\" rule.\n *\n * `unit` is the metered-unit denominator: 1 means \"price per single\n * metered unit\", 1024*1024 means \"price per MB when quantity is in\n * bytes.\" Default 1.\n *\n * `label` overrides the line-item display name.\n */\nexport type PricedDimension = {\n\tlabel?: string;\n\tfreeTier?: number;\n\tunit?: number;\n} & (\n\t| { perUnitMicros: number; tiers?: never; price?: never }\n\t| { tiers: PricingTier[]; perUnitMicros?: never; price?: never }\n\t| {\n\t\t\tprice: (chargedQuantity: number) => Micros;\n\t\t\tperUnitMicros?: never;\n\t\t\ttiers?: never;\n\t  }\n);\n\nexport type Plan = {\n\t/** Human label for the invoice (`'pro'`, `'enterprise'`, etc.). */\n\tname: string;\n\t/** Optional flat base fee charged once per invoice period. */\n\tbasePriceMicros?: Micros;\n\t/**\n\t * Dimensions priced from usage. Keys must match keys on the\n\t * `usage` record passed to `computeInvoice`. Anything not listed\n\t * is ignored.\n\t */\n\tpricedDimensions: Record<string, PricedDimension>;\n\t/** Default currency for invoices generated from this plan. */\n\tcurrency?: string;\n\t/** Rounding strategy applied per line item. Default `'truncate'`. */\n\trounding?: Rounding;\n\t/**\n\t * Minimum charge (in micros) — if the computed total is below\n\t * this floor, the invoice total is raised to the floor and a\n\t * single `'minimum-charge-adjustment'` line item captures the\n\t * difference. Defaults to 0 (no floor).\n\t */\n\tminimumChargeMicros?: Micros;\n\t/** Arbitrary plan-level metadata that flows through to invoices. */\n\tmetadata?: Record<string, string>;\n};\n\nexport const createPlan = (plan: Plan): Plan => {\n\tfor (const [key, dim] of Object.entries(plan.pricedDimensions)) {\n\t\tif (dim.tiers !== undefined) {\n\t\t\tif (dim.tiers.length === 0) {\n\t\t\t\tthrow new Error(`billing: dimension '${key}' has no tiers`);\n\t\t\t}\n\t\t\tconst last = dim.tiers[dim.tiers.length - 1];\n\t\t\tif (last !== undefined && Number.isFinite(last.upTo)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`billing: dimension '${key}' final tier must have upTo: Infinity`\n\t\t\t\t);\n\t\t\t}\n\t\t\tlet prev = 0;\n\t\t\tfor (let i = 0; i < dim.tiers.length; i += 1) {\n\t\t\t\tconst tier = dim.tiers[i]!;\n\t\t\t\tif (tier.upTo < prev) {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`billing: dimension '${key}' tier #${i} upTo (${tier.upTo}) must be >= previous (${prev})`\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tprev = tier.upTo;\n\t\t\t}\n\t\t}\n\t}\n\treturn plan;\n};\n\n// =============================================================================\n// Invoice shape\n// =============================================================================\n\nexport type LineItem = {\n\t/**\n\t * Stable key for the line item. For priced dimensions it's the\n\t * usage-record key (`'requests'`, `'cpuMs'`, etc.). For the base\n\t * fee it's `'base'`. For minimum-charge top-up it's\n\t * `'minimum-charge-adjustment'`.\n\t */\n\tkey: string;\n\t/** Human-readable label. */\n\tlabel: string;\n\t/** Metered units BEFORE applying free tier. 0 for the base fee. */\n\tquantity: number;\n\t/** Metered units AFTER applying free tier (what's actually charged). */\n\tchargedQuantity: number;\n\t/** Free-tier units subtracted from `quantity`. */\n\tfreeTier?: number;\n\t/** Charge for this line in integer micros. */\n\tamountMicros: Micros;\n\t/**\n\t * Tier-by-tier breakdown when graduated pricing was used. Each\n\t * entry: `{ tierIndex, unitsInTier, perUnitMicros, amountMicros }`.\n\t */\n\ttierBreakdown?: Array<{\n\t\ttierIndex: number;\n\t\tunitsInTier: number;\n\t\tperUnitMicros: number;\n\t\tamountMicros: Micros;\n\t}>;\n};\n\nexport type InvoicePeriod = {\n\t/** Inclusive period start (`Date.now()` ms). */\n\tstart: number;\n\t/** Exclusive period end. */\n\tend: number;\n};\n\nexport type Invoice = {\n\ttenant: string;\n\tplan: string;\n\tcurrency: string;\n\tperiod: InvoicePeriod;\n\tlineItems: LineItem[];\n\t/** Sum of all `lineItems[].amountMicros`. */\n\ttotalMicros: Micros;\n\t/** Convenience: `totalMicros / 1_000_000` as a number. */\n\ttotalUnits: number;\n\t/** Plan-level metadata copied through unchanged. */\n\tmetadata?: Record<string, string>;\n};\n\n// =============================================================================\n// Pricing math\n// =============================================================================\n\ntype ComputeDimensionInput = {\n\tquantity: number;\n\tdim: PricedDimension;\n\trounding: Rounding;\n};\n\ntype ComputeDimensionResult = {\n\tamountMicros: Micros;\n\tchargedQuantity: number;\n\ttierBreakdown?: LineItem['tierBreakdown'];\n};\n\nconst computeDimension = ({\n\tquantity,\n\tdim,\n\trounding\n}: ComputeDimensionInput): ComputeDimensionResult => {\n\tconst free = dim.freeTier ?? 0;\n\tconst charged = Math.max(0, quantity - free);\n\tconst unit = dim.unit ?? 1;\n\tconst chargedUnits = unit === 1 ? charged : charged / unit;\n\n\tif (dim.perUnitMicros !== undefined) {\n\t\tconst amountMicros = roundMicros(\n\t\t\tchargedUnits * dim.perUnitMicros,\n\t\t\trounding\n\t\t);\n\t\treturn { amountMicros, chargedQuantity: charged };\n\t}\n\n\tif (dim.price !== undefined) {\n\t\tconst amountMicros = roundMicros(dim.price(charged), rounding);\n\t\treturn { amountMicros, chargedQuantity: charged };\n\t}\n\n\t// Tiered pricing — walk tiers, allocate chargedUnits into bands.\n\tconst tierBreakdown: NonNullable<LineItem['tierBreakdown']> = [];\n\tlet remaining = chargedUnits;\n\tlet bandFloor = 0;\n\tlet totalMicros = 0;\n\tfor (let i = 0; i < dim.tiers!.length && remaining > 0; i += 1) {\n\t\tconst tier = dim.tiers![i]!;\n\t\tconst bandWidth = tier.upTo - bandFloor;\n\t\tconst unitsInTier = Math.min(remaining, bandWidth);\n\t\tif (unitsInTier > 0) {\n\t\t\tconst tierMicros = roundMicros(\n\t\t\t\tunitsInTier * tier.perUnitMicros,\n\t\t\t\trounding\n\t\t\t);\n\t\t\ttierBreakdown.push({\n\t\t\t\tamountMicros: tierMicros,\n\t\t\t\tperUnitMicros: tier.perUnitMicros,\n\t\t\t\ttierIndex: i,\n\t\t\t\tunitsInTier\n\t\t\t});\n\t\t\ttotalMicros += tierMicros;\n\t\t}\n\t\tremaining -= unitsInTier;\n\t\tbandFloor = tier.upTo;\n\t}\n\treturn {\n\t\tamountMicros: totalMicros,\n\t\tchargedQuantity: charged,\n\t\ttierBreakdown\n\t};\n};\n\n// =============================================================================\n// computeInvoice — pure\n// =============================================================================\n\nexport type ComputeInvoiceInput = {\n\tplan: Plan;\n\ttenant: string;\n\tperiod: InvoicePeriod;\n\t/** Metered numbers keyed by the same names as `plan.pricedDimensions`. */\n\tusage: Record<string, number>;\n\t/** Override the plan's currency (e.g. for tenant-local invoicing). */\n\tcurrency?: string;\n};\n\nexport const computeInvoice = ({\n\tplan,\n\ttenant,\n\tperiod,\n\tusage,\n\tcurrency\n}: ComputeInvoiceInput): Invoice => {\n\tconst rounding = plan.rounding ?? 'truncate';\n\tconst lineItems: LineItem[] = [];\n\n\tif (plan.basePriceMicros !== undefined && plan.basePriceMicros > 0) {\n\t\tlineItems.push({\n\t\t\tamountMicros: plan.basePriceMicros,\n\t\t\tchargedQuantity: 1,\n\t\t\tkey: 'base',\n\t\t\tlabel: `${plan.name} base fee`,\n\t\t\tquantity: 1\n\t\t});\n\t}\n\n\tfor (const [key, dim] of Object.entries(plan.pricedDimensions)) {\n\t\tconst quantity = usage[key] ?? 0;\n\t\tif (!Number.isFinite(quantity) || quantity < 0) continue;\n\t\tconst result = computeDimension({ dim, quantity, rounding });\n\t\tif (result.amountMicros === 0 && result.chargedQuantity === 0) continue;\n\t\tconst item: LineItem = {\n\t\t\tamountMicros: result.amountMicros,\n\t\t\tchargedQuantity: result.chargedQuantity,\n\t\t\tkey,\n\t\t\tlabel: dim.label ?? key,\n\t\t\tquantity\n\t\t};\n\t\tif (dim.freeTier !== undefined) item.freeTier = dim.freeTier;\n\t\tif (result.tierBreakdown !== undefined && result.tierBreakdown.length > 0) {\n\t\t\titem.tierBreakdown = result.tierBreakdown;\n\t\t}\n\t\tlineItems.push(item);\n\t}\n\n\tlet totalMicros = lineItems.reduce(\n\t\t(sum, item) => sum + item.amountMicros,\n\t\t0\n\t);\n\n\tconst floor = plan.minimumChargeMicros ?? 0;\n\tif (floor > 0 && totalMicros < floor) {\n\t\tconst gap = floor - totalMicros;\n\t\tlineItems.push({\n\t\t\tamountMicros: gap,\n\t\t\tchargedQuantity: 1,\n\t\t\tkey: 'minimum-charge-adjustment',\n\t\t\tlabel: 'Minimum charge adjustment',\n\t\t\tquantity: 1\n\t\t});\n\t\ttotalMicros = floor;\n\t}\n\n\tconst invoice: Invoice = {\n\t\tcurrency: currency ?? plan.currency ?? 'usd',\n\t\tlineItems,\n\t\tperiod,\n\t\tplan: plan.name,\n\t\ttenant,\n\t\ttotalMicros,\n\t\ttotalUnits: totalMicros / 1_000_000\n\t};\n\tif (plan.metadata !== undefined) invoice.metadata = plan.metadata;\n\treturn invoice;\n};\n\n// =============================================================================\n// Display helpers\n// =============================================================================\n\n/**\n * Format an integer micros amount as a human currency string. Pure\n * — no Intl side effects. For locales / advanced formatting, pipe\n * through `Intl.NumberFormat` yourself.\n */\nexport const formatMicros = (\n\tamount: Micros,\n\tcurrency: string,\n\t{ minorUnits = 2 }: { minorUnits?: number } = {}\n): string => {\n\tconst sign = amount < 0 ? '-' : '';\n\tconst abs = Math.abs(amount);\n\tconst wholeMicrosPerMinor = 10 ** (6 - minorUnits);\n\tconst minorTotal = Math.round(abs / wholeMicrosPerMinor);\n\tconst divisor = 10 ** minorUnits;\n\tconst whole = Math.trunc(minorTotal / divisor);\n\tconst upper = currency.toUpperCase();\n\tif (minorUnits === 0) return `${sign}${whole} ${upper}`;\n\tconst fraction = minorTotal % divisor;\n\tconst fractionStr = fraction.toString().padStart(minorUnits, '0');\n\treturn `${sign}${whole}.${fractionStr} ${upper}`;\n};\n"
+  ],
+  "mappings": "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",
+  "debugId": "1E2BA78C0466F20664756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@absolutejs/billing",
+  "version": "0.1.0",
+  "description": "Cost-model substrate for the AbsoluteJS PaaS. createPlan declares a priced product (base fee + per-dimension unit prices + tiered / free-tier rules); computeInvoice turns a @absolutejs/metering Usage snapshot into Invoice line items in integer micros (no float drift). Pluggable invoice sinks (Stripe / etc.) live in @absolutejs/billing-adapters/*.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/absolutejs/billing.git"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "license": "BSL-1.1",
+  "author": "Alex Kahn",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --sourcemap --target=bun && tsc --project tsconfig.build.json",
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"./**/*.{ts,json,md}\"",
+    "check:package": "bun run typecheck && bun run build && bun run test",
+    "release": "bun run format && bun run check:package && bun publish"
+  },
+  "keywords": ["absolutejs", "billing", "cost-model", "metering", "invoicing", "saas", "pricing"],
+  "peerDependencies": {
+    "bun-types": "^1.3.14"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "prettier": "^3.8.3",
+    "typescript": "^5.9.0"
+  }
+}