@venturekit-pro/billing 0.0.41 → 0.0.43

package/dist/meters/store.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Where a meter keeps its counters: one row per (subject, meter, period) and a ledger of
+ * credits. {@link createMemoryMeterStore} for tests and local runs;
+ * `createPostgresMeterStore` (`postgres.ts`) for `vk_billing_meter_usage` /
+ * `vk_billing_credit_ledger`; or the consumer's own tables behind the same interface — a
+ * product whose counters live in its own schema, under its own row-level security, writes
+ * the SQL and keeps every rule here.
+ */
+import type { MeterSplit, PeriodUsage } from './rules.js';
+/** One period's counters, as stored. */
+export interface MeterPeriodRow {
+    used: number;
+    fromCredits: number;
+    onDebt: number;
+    /** Alert keys already sent this period (`rules.ts` `alertsCrossed`). */
+    alerts: string[];
+}
+export type CreditKind = 'purchase' | 'grant' | 'auto_topup' | 'refund' | 'void' | 'adjustment';
+export interface CreditEntry {
+    subjectId: string;
+    meterKey: string;
+    /** Signed: a purchase adds, a void takes back. Never zero. */
+    units: number;
+    kind: CreditKind;
+    /** What the entry is for — an order, an invoice — free text the consumer reads back. */
+    reference?: string | null;
+    /** Makes the entry once-only: a second add with the same key changes nothing. */
+    idempotencyKey?: string | null;
+    /**
+     * This lot's life in periods, overriding the meter's (`1` = this period only, `0` = never
+     * expires): a promotional grant good for three months on a meter whose purchases roll over.
+     * `null` / absent = the meter's policy.
+     */
+    expiresAfterPeriods?: number | null;
+    /** When it was made — the period it counts from. Default now. */
+    at?: Date;
+}
+/** A ledger entry as the meter reads it back. */
+export interface CreditEntryRow {
+    units: number;
+    kind: CreditKind;
+    createdAt: Date;
+    expiresAfterPeriods: number | null;
+}
+export interface MeterStore {
+    /**
+     * The period's row, created at zero if absent, and **held** for the rest of the
+     * transaction (a Postgres row lock): what a consumption reads here cannot be read by a
+     * concurrent one until it commits. `included` is recorded on the row as it stands now.
+     */
+    lockPeriod(subjectId: string, meterKey: string, period: string, included: number): Promise<MeterPeriodRow>;
+    /** The period's row without taking it, or `null` when nothing was consumed in it. */
+    readPeriod(subjectId: string, meterKey: string, period: string): Promise<MeterPeriodRow | null>;
+    /** Every period before `period`, oldest first — what the replay reads when credits expire or allowances carry over. */
+    history(subjectId: string, meterKey: string, period: string): Promise<PeriodUsage[]>;
+    /** Credits drawn in every period before `period` (`fromCredits + onDebt`) — all a meter whose credits never expire needs. */
+    drawnBefore(subjectId: string, meterKey: string, period: string): Promise<number>;
+    /** Add a consumption's split to the period, and record the alerts it claimed. */
+    addUsage(subjectId: string, meterKey: string, period: string, split: MeterSplit, alerts: readonly string[]): Promise<void>;
+    /** Take a split back off the period (clamped at zero). */
+    releaseUsage(subjectId: string, meterKey: string, period: string, split: MeterSplit): Promise<void>;
+    /** Every ledger entry of the subject's meter, oldest first. */
+    lots(subjectId: string, meterKey: string): Promise<CreditEntryRow[]>;
+    /** Append to the ledger. `added: false` when the idempotency key was already used. */
+    addCredits(entry: CreditEntry): Promise<{
+        added: boolean;
+    }>;
+}
+/** The shape every store refuses the same way. */
+export declare function assertCreditEntry(entry: CreditEntry): void;
+/** In-memory store. Single-process only: no lock is needed because nothing interleaves inside one call. */
+export declare function createMemoryMeterStore(): MeterStore & {
+    ledger: Array<CreditEntry & {
+        createdAt: Date;
+    }>;
+};
+//# sourceMappingURL=store.d.ts.map

package/dist/meters/store.d.ts.map

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

package/dist/meters/store.js

@@ -0,0 +1,78 @@
+/**
+ * Where a meter keeps its counters: one row per (subject, meter, period) and a ledger of
+ * credits. {@link createMemoryMeterStore} for tests and local runs;
+ * `createPostgresMeterStore` (`postgres.ts`) for `vk_billing_meter_usage` /
+ * `vk_billing_credit_ledger`; or the consumer's own tables behind the same interface — a
+ * product whose counters live in its own schema, under its own row-level security, writes
+ * the SQL and keeps every rule here.
+ */
+/** The shape every store refuses the same way. */
+export function assertCreditEntry(entry) {
+    if (!Number.isInteger(entry.units) || entry.units === 0)
+        throw new Error('meter credits: units must be a non-zero integer');
+    if (entry.expiresAfterPeriods !== null && entry.expiresAfterPeriods !== undefined && !(Number.isInteger(entry.expiresAfterPeriods) && entry.expiresAfterPeriods >= 0)) {
+        throw new Error('meter credits: expiresAfterPeriods is a whole number of periods (0 = never)');
+    }
+}
+const keyOf = (...parts) => parts.join('\u0000');
+/** In-memory store. Single-process only: no lock is needed because nothing interleaves inside one call. */
+export function createMemoryMeterStore() {
+    const periods = new Map();
+    const ledger = [];
+    const row = (subjectId, meterKey, period) => periods.get(keyOf(subjectId, meterKey, period));
+    const copy = (r) => ({ used: r.used, fromCredits: r.fromCredits, onDebt: r.onDebt, alerts: [...r.alerts] });
+    const earlier = (subjectId, meterKey, period) => [...periods.values()].filter((r) => r.subjectId === subjectId && r.meterKey === meterKey && r.period < period).sort((a, b) => (a.period < b.period ? -1 : 1));
+    return {
+        ledger,
+        async lockPeriod(subjectId, meterKey, period, included) {
+            const k = keyOf(subjectId, meterKey, period);
+            const existing = periods.get(k) ?? { subjectId, meterKey, period, included, used: 0, fromCredits: 0, onDebt: 0, alerts: [] };
+            existing.included = included;
+            periods.set(k, existing);
+            return copy(existing);
+        },
+        async readPeriod(subjectId, meterKey, period) {
+            const r = row(subjectId, meterKey, period);
+            return r ? copy(r) : null;
+        },
+        async history(subjectId, meterKey, period) {
+            return earlier(subjectId, meterKey, period).map((r) => ({ period: r.period, included: r.included, used: r.used, fromCredits: r.fromCredits, onDebt: r.onDebt }));
+        },
+        async drawnBefore(subjectId, meterKey, period) {
+            return earlier(subjectId, meterKey, period).reduce((n, r) => n + r.fromCredits + r.onDebt, 0);
+        },
+        async addUsage(subjectId, meterKey, period, split, alerts) {
+            const r = row(subjectId, meterKey, period);
+            if (!r)
+                throw new Error(`meter ${meterKey}: addUsage before lockPeriod (${subjectId}, ${period})`);
+            r.used += split.included + split.credits + split.debt;
+            r.fromCredits += split.credits;
+            r.onDebt += split.debt;
+            for (const a of alerts)
+                if (!r.alerts.includes(a))
+                    r.alerts.push(a);
+        },
+        async releaseUsage(subjectId, meterKey, period, split) {
+            const r = row(subjectId, meterKey, period);
+            if (!r)
+                return;
+            r.used = Math.max(0, r.used - (split.included + split.credits + split.debt));
+            r.fromCredits = Math.max(0, r.fromCredits - split.credits);
+            r.onDebt = Math.max(0, r.onDebt - split.debt);
+        },
+        async lots(subjectId, meterKey) {
+            return ledger
+                .filter((e) => e.subjectId === subjectId && e.meterKey === meterKey)
+                .map((e) => ({ units: e.units, kind: e.kind, createdAt: e.createdAt, expiresAfterPeriods: e.expiresAfterPeriods ?? null }));
+        },
+        async addCredits(entry) {
+            assertCreditEntry(entry);
+            if (entry.idempotencyKey && ledger.some((e) => e.subjectId === entry.subjectId && e.meterKey === entry.meterKey && e.idempotencyKey === entry.idempotencyKey)) {
+                return { added: false };
+            }
+            ledger.push({ ...entry, createdAt: entry.at ?? new Date() });
+            return { added: true };
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/meters/store.js.map

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

package/dist/migrations/vk_billing_0002_meters.sql

@@ -0,0 +1,50 @@
+-- @venturekit-pro/billing — metered allowances (`src/meters`).
+--
+-- `vk_billing_meter_usage`: one row per subject, meter and period. `used` is everything
+-- consumed in the period; `from_credits` the part paid with credits; `on_debt` the part
+-- consumed with nothing left (exempt consumptions only), owed and taken from the next
+-- credits. `included` records the period's allowance as it stood at the latest
+-- consumption. `alerts` are the alert keys already sent this period.
+--
+-- `vk_billing_credit_ledger`: every credit movement — a purchase, a grant, an automatic
+-- top-up, a void — signed, each a lot dated by `created_at`. What the credits are worth in a
+-- period is a replay of the lots against the periods' draws (`src/meters/rules.ts`
+-- `openingCredits`), so a lot can expire: `expires_after_periods` is its life in periods
+-- (1 = the period it was made in, 0 = never), NULL = the meter's policy. Nothing is ever
+-- updated in place, so the balance can be explained entry by entry. An idempotency key
+-- makes an entry once-only (an automatic top-up noticed by several concurrent consumptions).
+--
+-- No RLS policy is installed: `vk_install_tenant_guards()` needs the consumer's
+-- application role. Call it yourself if `subject_id` is a tenant you scope by.
+
+CREATE TABLE IF NOT EXISTS vk_billing_meter_usage (
+  subject_id   VARCHAR(128) NOT NULL,
+  meter_key    VARCHAR(128) NOT NULL,
+  period       VARCHAR(16)  NOT NULL,
+  included     INTEGER      NOT NULL DEFAULT 0 CHECK (included >= 0),
+  used         INTEGER      NOT NULL DEFAULT 0 CHECK (used >= 0),
+  from_credits INTEGER      NOT NULL DEFAULT 0 CHECK (from_credits >= 0),
+  on_debt      INTEGER      NOT NULL DEFAULT 0 CHECK (on_debt >= 0),
+  alerts       TEXT[]       NOT NULL DEFAULT '{}',
+  created_at   TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+  updated_at   TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (subject_id, meter_key, period),
+  CONSTRAINT vk_billing_meter_usage_buckets CHECK (from_credits + on_debt <= used)
+);
+
+CREATE TABLE IF NOT EXISTS vk_billing_credit_ledger (
+  id              UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+  subject_id      VARCHAR(128) NOT NULL,
+  meter_key       VARCHAR(128) NOT NULL,
+  units           INTEGER      NOT NULL CHECK (units <> 0),
+  kind            VARCHAR(20)  NOT NULL CHECK (kind IN ('purchase', 'grant', 'auto_topup', 'refund', 'void', 'adjustment')),
+  reference       TEXT,
+  idempotency_key VARCHAR(200),
+  expires_after_periods INTEGER CHECK (expires_after_periods >= 0),
+  created_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_vk_billing_credit_ledger_subject ON vk_billing_credit_ledger (subject_id, meter_key, created_at);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_vk_billing_credit_ledger_idempotency
+  ON vk_billing_credit_ledger (subject_id, meter_key, idempotency_key)
+  WHERE idempotency_key IS NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venturekit-pro/billing",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "description": "Invoicing, plans, usage tracking, and feature gating for VentureKit",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,7 +30,7 @@
     }
   },
   "dependencies": {
-    "@venturekit/core": "0.0.41"
+    "@venturekit/core": "0.0.43"
   },
   "devDependencies": {
     "@types/node": "^26.5.1",

package/src/migrations/vk_billing_0002_meters.sql

@@ -0,0 +1,50 @@
+-- @venturekit-pro/billing — metered allowances (`src/meters`).
+--
+-- `vk_billing_meter_usage`: one row per subject, meter and period. `used` is everything
+-- consumed in the period; `from_credits` the part paid with credits; `on_debt` the part
+-- consumed with nothing left (exempt consumptions only), owed and taken from the next
+-- credits. `included` records the period's allowance as it stood at the latest
+-- consumption. `alerts` are the alert keys already sent this period.
+--
+-- `vk_billing_credit_ledger`: every credit movement — a purchase, a grant, an automatic
+-- top-up, a void — signed, each a lot dated by `created_at`. What the credits are worth in a
+-- period is a replay of the lots against the periods' draws (`src/meters/rules.ts`
+-- `openingCredits`), so a lot can expire: `expires_after_periods` is its life in periods
+-- (1 = the period it was made in, 0 = never), NULL = the meter's policy. Nothing is ever
+-- updated in place, so the balance can be explained entry by entry. An idempotency key
+-- makes an entry once-only (an automatic top-up noticed by several concurrent consumptions).
+--
+-- No RLS policy is installed: `vk_install_tenant_guards()` needs the consumer's
+-- application role. Call it yourself if `subject_id` is a tenant you scope by.
+
+CREATE TABLE IF NOT EXISTS vk_billing_meter_usage (
+  subject_id   VARCHAR(128) NOT NULL,
+  meter_key    VARCHAR(128) NOT NULL,
+  period       VARCHAR(16)  NOT NULL,
+  included     INTEGER      NOT NULL DEFAULT 0 CHECK (included >= 0),
+  used         INTEGER      NOT NULL DEFAULT 0 CHECK (used >= 0),
+  from_credits INTEGER      NOT NULL DEFAULT 0 CHECK (from_credits >= 0),
+  on_debt      INTEGER      NOT NULL DEFAULT 0 CHECK (on_debt >= 0),
+  alerts       TEXT[]       NOT NULL DEFAULT '{}',
+  created_at   TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+  updated_at   TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (subject_id, meter_key, period),
+  CONSTRAINT vk_billing_meter_usage_buckets CHECK (from_credits + on_debt <= used)
+);
+
+CREATE TABLE IF NOT EXISTS vk_billing_credit_ledger (
+  id              UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+  subject_id      VARCHAR(128) NOT NULL,
+  meter_key       VARCHAR(128) NOT NULL,
+  units           INTEGER      NOT NULL CHECK (units <> 0),
+  kind            VARCHAR(20)  NOT NULL CHECK (kind IN ('purchase', 'grant', 'auto_topup', 'refund', 'void', 'adjustment')),
+  reference       TEXT,
+  idempotency_key VARCHAR(200),
+  expires_after_periods INTEGER CHECK (expires_after_periods >= 0),
+  created_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_vk_billing_credit_ledger_subject ON vk_billing_credit_ledger (subject_id, meter_key, created_at);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_vk_billing_credit_ledger_idempotency
+  ON vk_billing_credit_ledger (subject_id, meter_key, idempotency_key)
+  WHERE idempotency_key IS NOT NULL;