@qcobro/common 1.13.0 → 1.14.1

package/dist/billing/evaluate.d.ts

@@ -0,0 +1,36 @@
+import type { BillingConfig } from "../config.js";
+import type { LedgerEntry, UsageRecord } from "./ledger.js";
+import { type BillingMeter } from "./rates.js";
+/**
+ * Billing evaluation (billing-evaluation spec) — the pure, deployment-agnostic
+ * invariants, judged over a set of usage records + ledger entries (from the
+ * simulation or exported from a live deployment). Sibling of the engine
+ * scorecard: under-detects, never false-positives.
+ */
+export interface BillingInvariantResult {
+    id: string;
+    description: string;
+    verdict: "pass" | "fail";
+    details?: string;
+}
+export interface BillingScorecard {
+    verdict: "pass" | "fail";
+    invariants: BillingInvariantResult[];
+}
+/**
+ * Rough per-unit provider floors (USD): what QCobro itself pays per unit, so a
+ * configured rate below its floor sells at a loss. Overridable per deployment;
+ * voice floors are per minute.
+ */
+export declare const DEFAULT_PROVIDER_FLOORS: Record<BillingMeter, number>;
+export interface BillingEvaluationInput {
+    billing: NonNullable<BillingConfig>;
+    usageRecords: UsageRecord[];
+    ledgerEntries: LedgerEntry[];
+    /** Per-meter floors; defaults to {@link DEFAULT_PROVIDER_FLOORS}. */
+    providerFloors?: Partial<Record<BillingMeter, number>>;
+}
+export declare function evaluateBilling(input: BillingEvaluationInput): BillingScorecard;
+/** Convenience: the worst tolerated negative balance for N in-flight voice calls. */
+export declare function voiceOvershootBoundMicro(perMinute: number, increments: string, estimateSeconds: number, maxAnsweredSeconds: number, concurrentCalls: number): number;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/billing/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/billing/evaluate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7E;;;;;GAKG;AAEH,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,UAAU,EAAE,sBAAsB,EAAE,CAAC;CACtC;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAQhE,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC;IACpC,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,aAAa,EAAE,WAAW,EAAE,CAAC;IAC7B,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;CACxD;AAUD,wBAAgB,eAAe,CAAC,KAAK,EAAE,sBAAsB,GAAG,gBAAgB,CA4G/E;AAED,qFAAqF;AACrF,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,kBAAkB,EAAE,MAAM,EAC1B,eAAe,EAAE,MAAM,GACtB,MAAM,CAQR"}

package/dist/billing/evaluate.js

@@ -0,0 +1,136 @@
+import { billedSeconds, parseIncrements } from "./pricing.js";
+import { sumMicroUnits, toMicroUnits } from "./money.js";
+import { MESSAGE_METERS, VOICE_METERS } from "./rates.js";
+/**
+ * Rough per-unit provider floors (USD): what QCobro itself pays per unit, so a
+ * configured rate below its floor sells at a loss. Overridable per deployment;
+ * voice floors are per minute.
+ */
+export const DEFAULT_PROVIDER_FLOORS = {
+    sms: 0.0079, // Twilio US outbound per segment
+    email: 0.0004, // Resend at volume
+    whatsappMessage: 0.004, // Meta marketing/utility blend, region-dependent
+    voicePrerecorded: 0.014, // carrier per-minute
+    voiceAi: 0.09, // carrier + STT/LLM/TTS per-minute blend
+    whatsappVoicePrerecorded: 0.005,
+    whatsappVoiceAi: 0.09
+};
+const CANONICAL_VECTORS = [
+    { answered: 0, billed: 0 },
+    { answered: 1, billed: 15 },
+    { answered: 15, billed: 15 },
+    { answered: 16, billed: 30 },
+    { answered: 35, billed: 45 }
+];
+export function evaluateBilling(input) {
+    const invariants = [];
+    const floors = { ...DEFAULT_PROVIDER_FLOORS, ...input.providerFloors };
+    // BIL-1 — Ledger conservation: total usage spend in the ledger equals the sum
+    // of priced usage records, exact to the micro-unit (settlements included).
+    {
+        const debits = sumMicroUnits(input.ledgerEntries
+            .filter((entry) => entry.kind === "USAGE_DEBIT" || entry.kind === "ADJUSTMENT")
+            .map((entry) => entry.amountMicro));
+        const priced = sumMicroUnits(input.usageRecords.map((record) => record.amountMicro));
+        const ok = -debits === priced;
+        invariants.push({
+            id: "BIL-1",
+            description: "sum(ledger usage debits + adjustments) equals sum(priced usage records)",
+            verdict: ok ? "pass" : "fail",
+            details: ok ? undefined : `ledger ${-debits} vs records ${priced} micro-units`
+        });
+    }
+    // BIL-2 — Balance derivation: every workspace balance is exactly the entry sum
+    // (guards against cached-balance drift when the input carries one).
+    {
+        const balance = sumMicroUnits(input.ledgerEntries.map((entry) => entry.amountMicro));
+        invariants.push({
+            id: "BIL-2",
+            description: "derived balances are exact integer micro-unit sums",
+            verdict: Number.isSafeInteger(balance) ? "pass" : "fail"
+        });
+    }
+    // BIL-3 — Canonical increment vectors under 15/15.
+    {
+        const pair = parseIncrements("15/15");
+        const failed = CANONICAL_VECTORS.filter((v) => billedSeconds(v.answered, pair) !== v.billed);
+        invariants.push({
+            id: "BIL-3",
+            description: "canonical 15/15 vectors (1→15, 15→15, 16→30, 35→45, unanswered→0)",
+            verdict: failed.length === 0 ? "pass" : "fail",
+            details: failed.length ? JSON.stringify(failed) : undefined
+        });
+    }
+    // BIL-4 — Settled voice records: quantity matches the increment formula for
+    // the frozen increments (records must never carry off-grid quantities).
+    {
+        const offenders = input.usageRecords.filter((record) => {
+            if (!VOICE_METERS.includes(record.meter))
+                return false;
+            const increments = record.increments;
+            if (!increments)
+                return true;
+            const pair = parseIncrements(increments);
+            return billedSeconds(record.quantity, pair) !== record.quantity;
+        });
+        invariants.push({
+            id: "BIL-4",
+            description: "voice usage quantities land on the increment grid",
+            verdict: offenders.length === 0 ? "pass" : "fail",
+            details: offenders.length ? `${offenders.length} off-grid records` : undefined
+        });
+    }
+    // BIL-5 — Margin guard: every configured rate covers its provider floor.
+    {
+        const violations = [];
+        for (const plan of input.billing.plans) {
+            for (const meter of MESSAGE_METERS) {
+                if (plan.rates[meter].perMessage < floors[meter]) {
+                    violations.push(`${plan.key}.${meter}`);
+                }
+            }
+            for (const meter of VOICE_METERS) {
+                if (plan.rates[meter].perMinute < floors[meter]) {
+                    violations.push(`${plan.key}.${meter}`);
+                }
+            }
+        }
+        invariants.push({
+            id: "BIL-5",
+            description: "every plan rate is at or above its provider floor",
+            verdict: violations.length === 0 ? "pass" : "fail",
+            details: violations.length ? violations.join(", ") : undefined
+        });
+    }
+    // BIL-6 — Grant/void idempotency shape: at most one GRANT and one VOID per
+    // (workspace, stripeInvoiceId) — replayed webhooks must not double-book.
+    {
+        const seen = new Map();
+        for (const entry of input.ledgerEntries) {
+            if (!entry.stripeInvoiceId)
+                continue;
+            const key = `${entry.workspaceRef}|${entry.stripeInvoiceId}|${entry.kind}`;
+            seen.set(key, (seen.get(key) ?? 0) + 1);
+        }
+        const duplicated = [...seen.entries()].filter(([, count]) => count > 1);
+        invariants.push({
+            id: "BIL-6",
+            description: "one grant/void per (workspace, invoice) — replays no-op",
+            verdict: duplicated.length === 0 ? "pass" : "fail",
+            details: duplicated.length ? duplicated.map(([k]) => k).join(", ") : undefined
+        });
+    }
+    return {
+        verdict: invariants.some((inv) => inv.verdict === "fail") ? "fail" : "pass",
+        invariants
+    };
+}
+/** Convenience: the worst tolerated negative balance for N in-flight voice calls. */
+export function voiceOvershootBoundMicro(perMinute, increments, estimateSeconds, maxAnsweredSeconds, concurrentCalls) {
+    const pair = parseIncrements(increments);
+    const perMinuteMicro = toMicroUnits(perMinute);
+    const estimate = Math.round((billedSeconds(Math.max(estimateSeconds, pair.initialSeconds), pair) * perMinuteMicro) / 60);
+    const worst = Math.round((billedSeconds(maxAnsweredSeconds, pair) * perMinuteMicro) / 60);
+    return Math.max(0, worst - estimate) * concurrentCalls;
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/billing/evaluate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.js","sourceRoot":"","sources":["../../src/billing/evaluate.ts"],"names":[],"mappings":"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"}

package/dist/billing/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./money.js";
+export * from "./rates.js";
+export * from "./pricing.js";
+export * from "./ledger.js";
+export * from "./proration.js";
+export * from "./evaluate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/billing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/billing/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC"}

package/dist/billing/index.js

@@ -0,0 +1,7 @@
+export * from "./money.js";
+export * from "./rates.js";
+export * from "./pricing.js";
+export * from "./ledger.js";
+export * from "./proration.js";
+export * from "./evaluate.js";
+//# sourceMappingURL=index.js.map

package/dist/billing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/billing/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC"}

package/dist/billing/ledger.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+/**
+ * Usage-ledger contracts: the durable, priced-at-write-time record of every
+ * billable event and the signed entries a workspace balance derives from.
+ *
+ * These are deliberately separate from the engine flight recorder
+ * (`engineEvents`), which is lossy, pruned telemetry. Usage records are written
+ * in the same transaction as the dispatch's contact log and are never pruned.
+ */
+/**
+ * Signed ledger entry kinds. Sign conventions: GRANT positive (allowance
+ * opens a cycle), USAGE_DEBIT negative (a priced dispatch), VOID negative
+ * (unused remainder at cycle close — no rollover), ADJUSTMENT either sign
+ * (voice settlement replacing the dispatch-time estimate).
+ */
+export declare const ledgerEntryKindSchema: z.ZodEnum<{
+    GRANT: "GRANT";
+    USAGE_DEBIT: "USAGE_DEBIT";
+    VOID: "VOID";
+    ADJUSTMENT: "ADJUSTMENT";
+}>;
+export type LedgerEntryKind = z.infer<typeof ledgerEntryKindSchema>;
+export declare const ledgerEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    workspaceRef: z.ZodString;
+    kind: z.ZodEnum<{
+        GRANT: "GRANT";
+        USAGE_DEBIT: "USAGE_DEBIT";
+        VOID: "VOID";
+        ADJUSTMENT: "ADJUSTMENT";
+    }>;
+    amountMicro: z.ZodNumber;
+    at: z.ZodString;
+    usageRecordId: z.ZodOptional<z.ZodString>;
+    stripeInvoiceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LedgerEntry = z.infer<typeof ledgerEntrySchema>;
+/**
+ * One priced billable event. Quantity semantics per meter kind: message meters
+ * store quantity = messages (1) and unitPriceMicro per message; voice meters
+ * store quantity = increment-billed seconds and unitPriceMicro per minute, with
+ * amountMicro = quantity × unitPriceMicro / 60 rounded to the micro-unit.
+ */
+export declare const usageRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    workspaceRef: z.ZodString;
+    meter: z.ZodEnum<{
+        sms: "sms";
+        email: "email";
+        whatsappMessage: "whatsappMessage";
+        voicePrerecorded: "voicePrerecorded";
+        voiceAi: "voiceAi";
+        whatsappVoicePrerecorded: "whatsappVoicePrerecorded";
+        whatsappVoiceAi: "whatsappVoiceAi";
+    }>;
+    quantity: z.ZodNumber;
+    unitPriceMicro: z.ZodNumber;
+    amountMicro: z.ZodNumber;
+    campaignId: z.ZodOptional<z.ZodString>;
+    portfolioAccountId: z.ZodOptional<z.ZodString>;
+    providerRef: z.ZodOptional<z.ZodString>;
+    at: z.ZodString;
+}, z.core.$strip>;
+export type UsageRecord = z.infer<typeof usageRecordSchema>;
+/**
+ * Derives a workspace balance from its ledger entries. The ledger is the source
+ * of truth — any cached balance is an optimization that must equal this sum.
+ */
+export declare function deriveBalanceMicro(entries: Iterable<Pick<LedgerEntry, "amountMicro">>): number;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/billing/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/billing/ledger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;EAAyD,CAAC;AAC5F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;iBAY5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;iBAa5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,GAAG,MAAM,CAE9F"}

package/dist/billing/ledger.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { sumMicroUnits } from "./money.js";
+import { billingMeterSchema } from "./rates.js";
+/**
+ * Usage-ledger contracts: the durable, priced-at-write-time record of every
+ * billable event and the signed entries a workspace balance derives from.
+ *
+ * These are deliberately separate from the engine flight recorder
+ * (`engineEvents`), which is lossy, pruned telemetry. Usage records are written
+ * in the same transaction as the dispatch's contact log and are never pruned.
+ */
+/**
+ * Signed ledger entry kinds. Sign conventions: GRANT positive (allowance
+ * opens a cycle), USAGE_DEBIT negative (a priced dispatch), VOID negative
+ * (unused remainder at cycle close — no rollover), ADJUSTMENT either sign
+ * (voice settlement replacing the dispatch-time estimate).
+ */
+export const ledgerEntryKindSchema = z.enum(["GRANT", "USAGE_DEBIT", "VOID", "ADJUSTMENT"]);
+export const ledgerEntrySchema = z.object({
+    id: z.string().min(1),
+    workspaceRef: z.string().min(1),
+    kind: ledgerEntryKindSchema,
+    /** Signed integer micro-units (see kind sign conventions). */
+    amountMicro: z.number().int(),
+    /** Entry instant, ISO. */
+    at: z.string().min(1),
+    /** The usage record this debit/adjustment prices, when applicable. */
+    usageRecordId: z.string().min(1).optional(),
+    /** Cycle-turnover idempotency key: set on GRANT and VOID entries. */
+    stripeInvoiceId: z.string().min(1).optional()
+});
+/**
+ * One priced billable event. Quantity semantics per meter kind: message meters
+ * store quantity = messages (1) and unitPriceMicro per message; voice meters
+ * store quantity = increment-billed seconds and unitPriceMicro per minute, with
+ * amountMicro = quantity × unitPriceMicro / 60 rounded to the micro-unit.
+ */
+export const usageRecordSchema = z.object({
+    id: z.string().min(1),
+    workspaceRef: z.string().min(1),
+    meter: billingMeterSchema,
+    quantity: z.number().int().nonnegative(),
+    unitPriceMicro: z.number().int().nonnegative(),
+    amountMicro: z.number().int().nonnegative(),
+    /** Correlation spine (mirrors the contact log / engine events). */
+    campaignId: z.string().min(1).optional(),
+    portfolioAccountId: z.string().min(1).optional(),
+    /** Provider ref of the dispatch; the settlement idempotency key for voice. */
+    providerRef: z.string().min(1).optional(),
+    at: z.string().min(1)
+});
+/**
+ * Derives a workspace balance from its ledger entries. The ledger is the source
+ * of truth — any cached balance is an optimization that must equal this sum.
+ */
+export function deriveBalanceMicro(entries) {
+    return sumMicroUnits(Array.from(entries, (entry) => entry.amountMicro));
+}
+//# sourceMappingURL=ledger.js.map

package/dist/billing/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/billing/ledger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;AAG5F,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,IAAI,EAAE,qBAAqB;IAC3B,8DAA8D;IAC9D,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC7B,0BAA0B;IAC1B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,sEAAsE;IACtE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC3C,qEAAqE;IACrE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC9C,CAAC,CAAC;AAGH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,KAAK,EAAE,kBAAkB;IACzB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACxC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC9C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC3C,mEAAmE;IACnE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACxC,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChD,8EAA8E;IAC9E,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACtB,CAAC,CAAC;AAGH;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAmD;IACpF,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;AAC1E,CAAC"}

package/dist/billing/money.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Micro-unit money arithmetic for billing.
+ *
+ * All persisted monetary amounts are integer micro-units of the billing currency
+ * (1 unit = 1,000,000 micro-units). Config rates are decimal JSON numbers converted
+ * once at the config boundary; everything past it is integer-only so thousands of
+ * sub-cent records aggregate with zero drift. Rounding to display/invoice precision
+ * happens only at aggregation, never per record.
+ */
+export declare const MICRO_UNITS_PER_UNIT = 1000000;
+/** Throws unless `value` is a safe-integer micro-unit amount. */
+export declare function assertMicroUnits(value: number): void;
+/**
+ * Converts a decimal currency amount (the config boundary) to integer micro-units,
+ * absorbing binary float representation error (e.g. 0.0004 → exactly 400).
+ */
+export declare function toMicroUnits(amount: number): number;
+/** Sums micro-unit amounts, guarding every operand and the running total. */
+export declare function sumMicroUnits(amounts: Iterable<number>): number;
+/**
+ * Aggregation-time rounding: renders micro-units as a fixed-point decimal string
+ * (default 2 fraction digits), rounding half away from zero using integer math.
+ * This is the ONLY place billing amounts lose precision.
+ */
+export declare function microUnitsToDecimalString(micro: number, fractionDigits?: number): string;
+//# sourceMappingURL=money.d.ts.map

package/dist/billing/money.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../../src/billing/money.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAE9C,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAIpD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,CAQ/D;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,SAAI,GAAG,MAAM,CAanF"}

package/dist/billing/money.js

@@ -0,0 +1,58 @@
+/**
+ * Micro-unit money arithmetic for billing.
+ *
+ * All persisted monetary amounts are integer micro-units of the billing currency
+ * (1 unit = 1,000,000 micro-units). Config rates are decimal JSON numbers converted
+ * once at the config boundary; everything past it is integer-only so thousands of
+ * sub-cent records aggregate with zero drift. Rounding to display/invoice precision
+ * happens only at aggregation, never per record.
+ */
+export const MICRO_UNITS_PER_UNIT = 1_000_000;
+/** Throws unless `value` is a safe-integer micro-unit amount. */
+export function assertMicroUnits(value) {
+    if (!Number.isSafeInteger(value)) {
+        throw new RangeError(`Not an integer micro-unit amount: ${value}`);
+    }
+}
+/**
+ * Converts a decimal currency amount (the config boundary) to integer micro-units,
+ * absorbing binary float representation error (e.g. 0.0004 → exactly 400).
+ */
+export function toMicroUnits(amount) {
+    if (!Number.isFinite(amount))
+        throw new RangeError(`Not a finite amount: ${amount}`);
+    const micro = Math.round(amount * MICRO_UNITS_PER_UNIT);
+    assertMicroUnits(micro);
+    return micro;
+}
+/** Sums micro-unit amounts, guarding every operand and the running total. */
+export function sumMicroUnits(amounts) {
+    let total = 0;
+    for (const amount of amounts) {
+        assertMicroUnits(amount);
+        total += amount;
+        assertMicroUnits(total);
+    }
+    return total;
+}
+/**
+ * Aggregation-time rounding: renders micro-units as a fixed-point decimal string
+ * (default 2 fraction digits), rounding half away from zero using integer math.
+ * This is the ONLY place billing amounts lose precision.
+ */
+export function microUnitsToDecimalString(micro, fractionDigits = 2) {
+    assertMicroUnits(micro);
+    if (!Number.isInteger(fractionDigits) || fractionDigits < 0 || fractionDigits > 6) {
+        throw new RangeError(`fractionDigits must be an integer in [0, 6]: ${fractionDigits}`);
+    }
+    const scale = 10 ** fractionDigits;
+    const microPerStep = MICRO_UNITS_PER_UNIT / scale;
+    const steps = Math.round(Math.abs(micro) / microPerStep);
+    const sign = micro < 0 && steps > 0 ? "-" : "";
+    const whole = Math.floor(steps / scale);
+    if (fractionDigits === 0)
+        return `${sign}${whole}`;
+    const frac = String(steps % scale).padStart(fractionDigits, "0");
+    return `${sign}${whole}.${frac}`;
+}
+//# sourceMappingURL=money.js.map

package/dist/billing/money.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.js","sourceRoot":"","sources":["../../src/billing/money.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C,iEAAiE;AACjE,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,UAAU,CAAC,qCAAqC,KAAK,EAAE,CAAC,CAAC;IACrE,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC;IACrF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,oBAAoB,CAAC,CAAC;IACxD,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,aAAa,CAAC,OAAyB;IACrD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACzB,KAAK,IAAI,MAAM,CAAC;QAChB,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAa,EAAE,cAAc,GAAG,CAAC;IACzE,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,UAAU,CAAC,gDAAgD,cAAc,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,MAAM,KAAK,GAAG,EAAE,IAAI,cAAc,CAAC;IACnC,MAAM,YAAY,GAAG,oBAAoB,GAAG,KAAK,CAAC;IAClD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;IACxC,IAAI,cAAc,KAAK,CAAC;QAAE,OAAO,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC;IACnD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACjE,OAAO,GAAG,IAAI,GAAG,KAAK,IAAI,IAAI,EAAE,CAAC;AACnC,CAAC"}

package/dist/billing/pricing.d.ts

@@ -0,0 +1,58 @@
+import type { BillingMeter, MessageMeter, MessageRate, RateOverrides, Rates, VoiceMeter, VoiceRate } from "./rates.js";
+/**
+ * Pricing math: increment billing, meter pricing, and rate resolution.
+ *
+ * Rates are resolved and applied exactly once, when a usage record is written;
+ * the resulting unit price and amount are stored on the record so history never
+ * reprices (see the usage-ledger spec).
+ */
+/** A parsed increment pair (seconds). */
+export interface IncrementPair {
+    initialSeconds: number;
+    subsequentSeconds: number;
+}
+/** Parses `"initial/subsequent"` notation (e.g. `"15/15"`, `"60/6"`). */
+export declare function parseIncrements(notation: string): IncrementPair;
+/**
+ * Billed seconds for an answered duration under an increment pair:
+ * 0 when never answered; the initial increment for any answered duration up to
+ * it; then rounded up to whole subsequent increments. Canonical 15/15 vectors:
+ * 1→15, 15→15, 16→30, 35→45, unanswered→0.
+ */
+export declare function billedSeconds(answeredSeconds: number, increments: IncrementPair): number;
+/** The unit price of one message on a message meter, in micro-units. */
+export declare function priceMessageMicro(rate: MessageRate): number;
+/** A priced voice usage: what gets stored on the usage record. */
+export interface VoicePrice {
+    /** Increment-billed seconds (the record's quantity). */
+    billedSeconds: number;
+    /** The per-minute rate in micro-units (the record's unit price). */
+    perMinuteMicro: number;
+    /** billedSeconds × perMinuteMicro / 60, rounded to the nearest micro-unit. */
+    amountMicro: number;
+}
+/** Prices an answered duration on a voice meter. Unanswered (≤ 0s) prices to zero. */
+export declare function priceVoiceMicro(answeredSeconds: number, rate: VoiceRate): VoicePrice;
+/**
+ * The pre-dispatch credit-bucket debit for a voice call: the configured
+ * estimate, never less than the initial increment (an answered call can never
+ * bill less than that).
+ */
+export declare function estimateVoiceDebitMicro(rate: VoiceRate, estimateSeconds: number): number;
+/**
+ * Resolves the effective rate for a meter: a per-workspace enterprise override
+ * when present, otherwise the plan's rate.
+ */
+export declare function resolveRate(meter: MessageMeter, rates: Rates, overrides?: RateOverrides): MessageRate;
+export declare function resolveRate(meter: VoiceMeter, rates: Rates, overrides?: RateOverrides): VoiceRate;
+/** Whether a meter bills per message (vs. per voice increment). */
+export declare function isMessageMeter(meter: BillingMeter): meter is MessageMeter;
+/**
+ * The pre-dispatch cost of one dispatch on a meter, in micro-units: the exact
+ * unit price for message meters, the voice estimate (never below the initial
+ * increment) for voice meters. THE single definition of "what a dispatch costs
+ * up front" — the engine's credit bucket and the manual-outreach gate both
+ * check/debit this amount.
+ */
+export declare function estimateDispatchCostMicro(meter: BillingMeter, rates: Rates, overrides: RateOverrides | undefined, voiceDebitEstimateSeconds: number): number;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/billing/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/billing/pricing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,KAAK,EACL,UAAU,EACV,SAAS,EACV,MAAM,YAAY,CAAC;AAGpB;;;;;;GAMG;AAEH,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAI/D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,eAAe,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,GAAG,MAAM,CAQxF;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAE3D;AAED,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,UAAU,CAQpF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAGxF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,KAAK,EACZ,SAAS,CAAC,EAAE,aAAa,GACxB,WAAW,CAAC;AACf,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;AASnG,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,IAAI,YAAY,CAEzE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,aAAa,GAAG,SAAS,EACpC,yBAAyB,EAAE,MAAM,GAChC,MAAM,CAKR"}

package/dist/billing/pricing.js

@@ -0,0 +1,68 @@
+import { toMicroUnits } from "./money.js";
+import { MESSAGE_METERS } from "./rates.js";
+/** Parses `"initial/subsequent"` notation (e.g. `"15/15"`, `"60/6"`). */
+export function parseIncrements(notation) {
+    const match = /^([1-9]\d*)\/([1-9]\d*)$/.exec(notation);
+    if (!match)
+        throw new RangeError(`Invalid increment notation: "${notation}"`);
+    return { initialSeconds: Number(match[1]), subsequentSeconds: Number(match[2]) };
+}
+/**
+ * Billed seconds for an answered duration under an increment pair:
+ * 0 when never answered; the initial increment for any answered duration up to
+ * it; then rounded up to whole subsequent increments. Canonical 15/15 vectors:
+ * 1→15, 15→15, 16→30, 35→45, unanswered→0.
+ */
+export function billedSeconds(answeredSeconds, increments) {
+    if (answeredSeconds <= 0)
+        return 0;
+    const { initialSeconds, subsequentSeconds } = increments;
+    if (answeredSeconds <= initialSeconds)
+        return initialSeconds;
+    return (initialSeconds +
+        Math.ceil((answeredSeconds - initialSeconds) / subsequentSeconds) * subsequentSeconds);
+}
+/** The unit price of one message on a message meter, in micro-units. */
+export function priceMessageMicro(rate) {
+    return toMicroUnits(rate.perMessage);
+}
+/** Prices an answered duration on a voice meter. Unanswered (≤ 0s) prices to zero. */
+export function priceVoiceMicro(answeredSeconds, rate) {
+    const seconds = billedSeconds(answeredSeconds, parseIncrements(rate.increments));
+    const perMinuteMicro = toMicroUnits(rate.perMinute);
+    return {
+        billedSeconds: seconds,
+        perMinuteMicro,
+        amountMicro: Math.round((seconds * perMinuteMicro) / 60)
+    };
+}
+/**
+ * The pre-dispatch credit-bucket debit for a voice call: the configured
+ * estimate, never less than the initial increment (an answered call can never
+ * bill less than that).
+ */
+export function estimateVoiceDebitMicro(rate, estimateSeconds) {
+    const { initialSeconds } = parseIncrements(rate.increments);
+    return priceVoiceMicro(Math.max(estimateSeconds, initialSeconds), rate).amountMicro;
+}
+export function resolveRate(meter, rates, overrides) {
+    return overrides?.[meter] ?? rates[meter];
+}
+/** Whether a meter bills per message (vs. per voice increment). */
+export function isMessageMeter(meter) {
+    return MESSAGE_METERS.includes(meter);
+}
+/**
+ * The pre-dispatch cost of one dispatch on a meter, in micro-units: the exact
+ * unit price for message meters, the voice estimate (never below the initial
+ * increment) for voice meters. THE single definition of "what a dispatch costs
+ * up front" — the engine's credit bucket and the manual-outreach gate both
+ * check/debit this amount.
+ */
+export function estimateDispatchCostMicro(meter, rates, overrides, voiceDebitEstimateSeconds) {
+    if (isMessageMeter(meter)) {
+        return priceMessageMicro(resolveRate(meter, rates, overrides));
+    }
+    return estimateVoiceDebitMicro(resolveRate(meter, rates, overrides), voiceDebitEstimateSeconds);
+}
+//# sourceMappingURL=pricing.js.map

package/dist/billing/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../../src/billing/pricing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAU1C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAgB5C,yEAAyE;AACzE,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,MAAM,KAAK,GAAG,0BAA0B,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,UAAU,CAAC,gCAAgC,QAAQ,GAAG,CAAC,CAAC;IAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACnF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,eAAuB,EAAE,UAAyB;IAC9E,IAAI,eAAe,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACnC,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,GAAG,UAAU,CAAC;IACzD,IAAI,eAAe,IAAI,cAAc;QAAE,OAAO,cAAc,CAAC;IAC7D,OAAO,CACL,cAAc;QACd,IAAI,CAAC,IAAI,CAAC,CAAC,eAAe,GAAG,cAAc,CAAC,GAAG,iBAAiB,CAAC,GAAG,iBAAiB,CACtF,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,iBAAiB,CAAC,IAAiB;IACjD,OAAO,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACvC,CAAC;AAYD,sFAAsF;AACtF,MAAM,UAAU,eAAe,CAAC,eAAuB,EAAE,IAAe;IACtE,MAAM,OAAO,GAAG,aAAa,CAAC,eAAe,EAAE,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IACjF,MAAM,cAAc,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACpD,OAAO;QACL,aAAa,EAAE,OAAO;QACtB,cAAc;QACd,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,cAAc,CAAC,GAAG,EAAE,CAAC;KACzD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAe,EAAE,eAAuB;IAC9E,MAAM,EAAE,cAAc,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC5D,OAAO,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,cAAc,CAAC,EAAE,IAAI,CAAC,CAAC,WAAW,CAAC;AACtF,CAAC;AAYD,MAAM,UAAU,WAAW,CACzB,KAAmB,EACnB,KAAY,EACZ,SAAyB;IAEzB,OAAO,SAAS,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;AAC5C,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,cAAc,CAAC,KAAmB;IAChD,OAAQ,cAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAmB,EACnB,KAAY,EACZ,SAAoC,EACpC,yBAAiC;IAEjC,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,iBAAiB,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,uBAAuB,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,yBAAyB,CAAC,CAAC;AAClG,CAAC"}

package/dist/billing/proration.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Prorates a cycle allowance to the remaining fraction of the billing period —
+ * used when a workspace joins mid-cycle or upgrades: Stripe prorates the charge
+ * and QCobro grants the matching fraction of the allowance. Integer micro-units
+ * out; clamped to [0, allowance] so clock skew can't over- or under-grant.
+ */
+export declare function proratedGrantMicro(allowanceMicro: number, at: Date, periodStart: Date, periodEnd: Date): number;
+//# sourceMappingURL=proration.d.ts.map

package/dist/billing/proration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proration.d.ts","sourceRoot":"","sources":["../../src/billing/proration.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,IAAI,EACR,WAAW,EAAE,IAAI,EACjB,SAAS,EAAE,IAAI,GACd,MAAM,CAOR"}

package/dist/billing/proration.js

@@ -0,0 +1,17 @@
+import { assertMicroUnits } from "./money.js";
+/**
+ * Prorates a cycle allowance to the remaining fraction of the billing period —
+ * used when a workspace joins mid-cycle or upgrades: Stripe prorates the charge
+ * and QCobro grants the matching fraction of the allowance. Integer micro-units
+ * out; clamped to [0, allowance] so clock skew can't over- or under-grant.
+ */
+export function proratedGrantMicro(allowanceMicro, at, periodStart, periodEnd) {
+    assertMicroUnits(allowanceMicro);
+    const period = periodEnd.getTime() - periodStart.getTime();
+    if (period <= 0)
+        return 0;
+    const remaining = periodEnd.getTime() - at.getTime();
+    const fraction = Math.min(1, Math.max(0, remaining / period));
+    return Math.round(allowanceMicro * fraction);
+}
+//# sourceMappingURL=proration.js.map

package/dist/billing/proration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proration.js","sourceRoot":"","sources":["../../src/billing/proration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,cAAsB,EACtB,EAAQ,EACR,WAAiB,EACjB,SAAe;IAEf,gBAAgB,CAAC,cAAc,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC;IAC3D,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1B,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,QAAQ,CAAC,CAAC;AAC/C,CAAC"}