@venturekit-pro/billing 0.0.42 → 0.0.43

package/README.md

@@ -18,6 +18,7 @@ npm install @venturekit-pro/billing@dev
 - **Subscription management** — create, upgrade, downgrade, cancel, pause, resume
 - **Invoice generation** — from plan + usage, with tax calculation
 - **Usage tracking** — record and meter feature usage
+- **Metered allowances** — an included quantity per period, credits that roll over, exempt consumptions on debt, automatic top-ups
 - **Feature gating** — plan-based and usage-based access control
 - **Auto-migrations** — billing tables created automatically via `vk migrate`
 
@@ -113,6 +114,55 @@ The latest step whose day has come is due; each step goes once; steps skipped ov
 are gone (the schedule says *when to nudge*, not how many messages to catch up on);
 and a reminder a person sent since the previous step covers the current one.
 
+## Metered Allowances
+
+For anything a subject consumes and pays for per unit — WhatsApp messages, SMS, AI tokens:
+an **included** quantity per period (the plan's limit or a negotiated one), **credits** on
+top (packs bought, grants, automatic top-ups), and **debt** for the consumptions that must
+never be refused (a safety alert, a sign-in code) — paid from the next credits, so nothing
+is free.
+
+```typescript
+import { createMeter, createPostgresMeterStore } from '@venturekit-pro/billing';
+
+const whatsapp = createMeter({
+  key: 'whatsapp_messages',
+  store: createPostgresMeterStore(tx.query),            // vk_billing_meter_usage + vk_billing_credit_ledger
+  included: (tenantId) => planLimit(tenantId, 'whatsapp_messages'),
+  autoTopUp: { packSize: 100, request: (tenantId, req) => orders.autoTopUp(tenantId, req) },
+  onAlert: (tenantId, alert, balance) => notifyOwners(tenantId, alert, balance), // 80 %, nothing left
+});
+
+await whatsapp.check(tenantId, { reserved: queued });   // room for one more? nothing written
+await whatsapp.consume(tenantId, { exempt: true });      // never refused; on debt when nothing is left
+await whatsapp.addCredits(tenantId, 500, { kind: 'purchase', reference: invoiceId });
+await whatsapp.balance(tenantId);                       // { included, used, fromCredits, onDebt, opening, expiring, credits }
+```
+
+Every policy is a product decision, and off by default:
+
+| Option | What it does |
+| --- | --- |
+| `credits: { expiresAfterPeriods: 1 }` | Bought credits expire with the period they were bought in (`12` = a year). Default: they roll over until spent. Per lot: `addCredits(…, { expiresAfterPeriods })`, `0` = never. |
+| `carryOver: { max, expiresAfterPeriods }` | What a period included and did not use is carried into the next ones, capped. |
+| `overage: { allow: 'all', maxDebt }` | Pay as you go: nobody is refused while what is owed stays under the cap. Default: only exempt consumptions may run a debt. |
+| `autoTopUp: { packSize, below?, request }` | Ask for packs as soon as a debt appears (or the balance drops under `below`), under a key that holds until they arrive. |
+| `timeZone: 'Africa/Casablanca'` | Periods follow the subject's clock rather than UTC. |
+| `thresholds: [0.5, 0.8]` | Alerts on the included quantity; "nothing left" and "a debt began" alert once per credit level. |
+
+What credits are worth in a period is a **replay** of the lots against every earlier
+period's draws (`openingCredits`), spending the soonest-to-expire first, so expiry, voids
+(what a voided pack had paid is owed again) and carry-over compose. With none of them on,
+it is the running total — credits bought, less credits spent — read in one query.
+
+`consume` takes the period row under a lock for the rest of the caller's transaction, so
+concurrent consumptions cannot both take the last unit. Credits bought in another service
+are supplied with `creditsFrom`: a running total (it never expires) or the lots with their
+periods (any policy). A product that keeps the counters in its own tables, under its own
+row-level security, implements `MeterStore` — eight small queries — and keeps every rule
+here; the pure rules (`meterGate`, `splitOf`, `openingCredits`, `alertsCrossed`,
+`topUpFor`, `packsFor`, `periodKey`, `shiftPeriod`) are exported too.
+
 ## Usage-to-Invoice Mapping
 
 ```typescript

package/dist/index.d.ts

@@ -30,6 +30,8 @@ export { createFeatureGate, } from './gating/feature-gate.js';
 export type { FeatureCheckResult, FeatureGateOptions, } from './gating/feature-gate.js';
 export { resolveEntitlements, createEntitlementsResolver, EntitlementError, } from './entitlements/entitlements.js';
 export type { Entitlements, EntitlementOverrides, EntitlementErrorCode, EntitlementsResolver, EntitlementsResolverOptions, ResolvedFeature, LimitCheck, } from './entitlements/entitlements.js';
+export { BEFORE_ANY_PERIOD, NO_SPLIT, afterConsume, afterRelease, alertsCrossed, carryOverSources, creditsLeft, debtOf, expiringLeft, gate as meterGate, includedLeft, openingCredits, packsFor, periodFromIndex, periodIndex, periodKey, remainingOf, shiftPeriod, splitOf, topUpFor, assertCreditEntry, createMemoryMeterStore, createPostgresMeterStore, createMeter, isExhausted, } from './meters/index.js';
+export type { CarryOverPolicy, CreditLot, CreditPolicy, GateDecision as MeterGateDecision, GateInput as MeterGateInput, MeterAlert, MeterAlertKind, MeterBalance, MeterPeriod, MeterSplit, OpeningCredits, OveragePolicy, PeriodOptions, PeriodUsage, ReplayInput, TopUpPolicy, TopUpRequest, CreditEntry, CreditEntryRow, CreditKind, MeterPeriodRow, MeterStore, MeterQuerier, PostgresMeterStoreOptions, AutoTopUpOptions, ConsumeInput, ConsumeResult, Meter, MeterOptions, } from './meters/index.js';
 export { nextDunningStep, dunningScheduleRefusal, normalizeDunningSteps, DUNNING_SCHEDULE_LIMITS, } from './dunning/schedule.js';
 export type { DunningSchedule, DunningReminderSent, NextDunningStepInput, } from './dunning/schedule.js';
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,WAAW,EACX,eAAe,EACf,UAAU,EACV,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpE,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,iBAAiB,EACjB,0BAA0B,EAC1B,eAAe,GAChB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,YAAY,EACZ,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,WAAW,EACX,YAAY,EACZ,UAAU,GACX,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,2BAA2B,EAC3B,eAAe,EACf,UAAU,GACX,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAGhD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,WAAW,EACX,eAAe,EACf,UAAU,EACV,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpE,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,iBAAiB,EACjB,0BAA0B,EAC1B,eAAe,GAChB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,YAAY,EACZ,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,WAAW,EACX,YAAY,EACZ,UAAU,GACX,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,2BAA2B,EAC3B,eAAe,EACf,UAAU,GACX,MAAM,gCAAgC,CAAC;AAIxC,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,MAAM,EACN,YAAY,EACZ,IAAI,IAAI,SAAS,EACjB,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,eAAe,EACf,WAAW,EACX,SAAS,EACT,WAAW,EACX,WAAW,EACX,OAAO,EACP,QAAQ,EACR,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,WAAW,EACX,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,eAAe,EACf,SAAS,EACT,YAAY,EACZ,YAAY,IAAI,iBAAiB,EACjC,SAAS,IAAI,cAAc,EAC3B,UAAU,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,WAAW,EACX,cAAc,EACd,UAAU,EACV,cAAc,EACd,UAAU,EACV,YAAY,EACZ,yBAAyB,EACzB,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,KAAK,EACL,YAAY,GACb,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAGhD"}

package/dist/index.js

@@ -33,6 +33,9 @@ export { createUsageTracker, createMemoryUsageStore, } from './usage/tracker.js'
 export { createFeatureGate, } from './gating/feature-gate.js';
 // Entitlements (plan + overrides → what a tenant may do, HTTP-mapped refusals)
 export { resolveEntitlements, createEntitlementsResolver, EntitlementError, } from './entitlements/entitlements.js';
+// Metered allowances (included per period, credits that roll over or expire, carry-over,
+// exempt or pay-as-you-go debt, automatic top-ups)
+export { BEFORE_ANY_PERIOD, NO_SPLIT, afterConsume, afterRelease, alertsCrossed, carryOverSources, creditsLeft, debtOf, expiringLeft, gate as meterGate, includedLeft, openingCredits, packsFor, periodFromIndex, periodIndex, periodKey, remainingOf, shiftPeriod, splitOf, topUpFor, assertCreditEntry, createMemoryMeterStore, createPostgresMeterStore, createMeter, isExhausted, } from './meters/index.js';
 // Dunning (which payment reminder an unpaid invoice is due — pure, for a cron)
 export { nextDunningStep, dunningScheduleRefusal, normalizeDunningSteps, DUNNING_SCHEDULE_LIMITS, } from './dunning/schedule.js';
 /**

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,QAAQ;AACR,cAAc,kBAAkB,CAAC;AAEjC,0BAA0B;AAC1B,OAAO,EACL,WAAW,EACX,eAAe,EACf,UAAU,EACV,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAG1B,0BAA0B;AAC1B,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AAOpC,qBAAqB;AACrB,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AAMjC,iBAAiB;AACjB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAO5B,iBAAiB;AACjB,OAAO,EACL,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAMlC,+EAA+E;AAC/E,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AAWxC,+EAA+E;AAC/E,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAO/B;;;;GAIG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,QAAQ;AACR,cAAc,kBAAkB,CAAC;AAEjC,0BAA0B;AAC1B,OAAO,EACL,WAAW,EACX,eAAe,EACf,UAAU,EACV,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAG1B,0BAA0B;AAC1B,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AAOpC,qBAAqB;AACrB,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AAMjC,iBAAiB;AACjB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAO5B,iBAAiB;AACjB,OAAO,EACL,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAMlC,+EAA+E;AAC/E,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AAWxC,yFAAyF;AACzF,mDAAmD;AACnD,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,MAAM,EACN,YAAY,EACZ,IAAI,IAAI,SAAS,EACjB,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,eAAe,EACf,WAAW,EACX,SAAS,EACT,WAAW,EACX,WAAW,EACX,OAAO,EACP,QAAQ,EACR,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,WAAW,EACX,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAiC3B,+EAA+E;AAC/E,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAO/B;;;;GAIG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAC5C,CAAC"}

package/dist/meters/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Metered allowances: an included quantity per period, credits on top that roll over or
+ * expire, unused quantities carried over, exempt (or pay-as-you-go) consumptions on debt,
+ * and automatic top-ups that pay it.
+ */
+export { BEFORE_ANY_PERIOD, NO_SPLIT, afterConsume, afterRelease, alertsCrossed, carryOverSources, creditsLeft, debtOf, expiringLeft, gate, includedLeft, openingCredits, packsFor, periodFromIndex, periodIndex, periodKey, remainingOf, shiftPeriod, splitOf, topUpFor, } from './rules.js';
+export type { CarryOverPolicy, CreditLot, CreditPolicy, GateDecision, GateInput, MeterAlert, MeterAlertKind, MeterBalance, MeterPeriod, MeterSplit, OpeningCredits, OveragePolicy, PeriodOptions, PeriodUsage, ReplayInput, TopUpPolicy, TopUpRequest, } from './rules.js';
+export { assertCreditEntry, createMemoryMeterStore } from './store.js';
+export type { CreditEntry, CreditEntryRow, CreditKind, MeterPeriodRow, MeterStore } from './store.js';
+export { createPostgresMeterStore } from './postgres.js';
+export type { MeterQuerier, PostgresMeterStoreOptions } from './postgres.js';
+export { createMeter, isExhausted } from './meter.js';
+export type { AutoTopUpOptions, ConsumeInput, ConsumeResult, Meter, MeterOptions } from './meter.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/meters/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,MAAM,EACN,YAAY,EACZ,IAAI,EACJ,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,eAAe,EACf,WAAW,EACX,SAAS,EACT,WAAW,EACX,WAAW,EACX,OAAO,EACP,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,UAAU,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACvE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACtG,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/meters/index.js

@@ -0,0 +1,10 @@
+/**
+ * Metered allowances: an included quantity per period, credits on top that roll over or
+ * expire, unused quantities carried over, exempt (or pay-as-you-go) consumptions on debt,
+ * and automatic top-ups that pay it.
+ */
+export { BEFORE_ANY_PERIOD, NO_SPLIT, afterConsume, afterRelease, alertsCrossed, carryOverSources, creditsLeft, debtOf, expiringLeft, gate, includedLeft, openingCredits, packsFor, periodFromIndex, periodIndex, periodKey, remainingOf, shiftPeriod, splitOf, topUpFor, } from './rules.js';
+export { assertCreditEntry, createMemoryMeterStore } from './store.js';
+export { createPostgresMeterStore } from './postgres.js';
+export { createMeter, isExhausted } from './meter.js';
+//# sourceMappingURL=index.js.map

package/dist/meters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/meters/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,MAAM,EACN,YAAY,EACZ,IAAI,EACJ,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,eAAe,EACf,WAAW,EACX,SAAS,EACT,WAAW,EACX,WAAW,EACX,OAAO,EACP,QAAQ,GACT,MAAM,YAAY,CAAC;AAoBpB,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAEzD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/meters/meter.d.ts

@@ -0,0 +1,134 @@
+/**
+ * A metered allowance: the rules (`rules.ts`) over a store (`store.ts`), for one meter.
+ *
+ * ```ts
+ * const whatsapp = createMeter({
+ *   key: 'whatsapp_messages',
+ *   store: createPostgresMeterStore(tx.query),
+ *   included: (tenantId) => entitlements.forSubject(tenantId).then((e) => e.limitOf('whatsapp_messages') ?? 0),
+ *   autoTopUp: {
+ *     packSize: 100,
+ *     // no free messages: an exempt send that found nothing left buys a small pack
+ *     request: (tenantId, req) => orders.autoTopUp(tenantId, req),   // invoices it, then meter.addCredits(...)
+ *   },
+ *   onAlert: (tenantId, alert, balance) => notifyOwners(tenantId, alert, balance),
+ * });
+ *
+ * // at enqueue: is there room, counting what is already queued?
+ * if (!(await whatsapp.check(tenantId, { reserved: queued })).allowed) return skip('quota');
+ * // when the message leaves (or reserve-then-release, around a synchronous send)
+ * const used = await whatsapp.consume(tenantId, { exempt: isSafetyAlert });
+ * if (!used.allowed) return skip('quota');
+ * // the provider refused it synchronously: give the units back
+ * await whatsapp.release(tenantId, used);
+ * ```
+ *
+ * **The policies** — each a product decision, each off by default:
+ *
+ * - `credits: { expiresAfterPeriods: 1 }` — bought credits expire with the period they were
+ *   bought in (`12` = a year; per lot with `addCredits(…, { expiresAfterPeriods })`).
+ *   Default: they roll over until spent.
+ * - `carryOver: { max, expiresAfterPeriods }` — what a period included and did not use is
+ *   carried into the next ones.
+ * - `overage: { allow: 'all', maxDebt }` — pay as you go: nobody is refused while what is
+ *   owed stays under the cap. Default: only exempt consumptions may run a debt.
+ * - `autoTopUp: { packSize, below? }` — ask for packs as soon as a debt appears (or the
+ *   balance drops under `below`), under an idempotency key that holds until they arrive.
+ * - `timeZone` — the periods follow the subject's clock, not UTC.
+ *
+ * **Credits** come from the store's ledger by default (`addCredits`). A product whose
+ * credits are bought elsewhere — another service, another database — passes `creditsFrom`
+ * instead: a running total (they never expire), or the lots with their periods (any policy).
+ *
+ * **Exempt** consumptions (`exempt: true`) are never refused. With nothing left they land
+ * on debt, which the next credits pay. `autoTopUp.request` is called after the usage is
+ * written, and a failure there never undoes the consumption: it is reported on the result
+ * (`topUp.error`) and asked again by the next consumption that still sees the debt.
+ */
+import type { CarryOverPolicy, CreditLot, CreditPolicy, GateDecision, MeterAlert, MeterBalance, MeterPeriod, MeterSplit, OveragePolicy, TopUpPolicy, TopUpRequest } from './rules.js';
+import type { CreditEntry, MeterStore } from './store.js';
+type MaybePromise<T> = T | Promise<T>;
+export interface AutoTopUpOptions extends TopUpPolicy {
+    /**
+     * Buy (or grant) `req.units` credits for the subject — typically an order and its
+     * invoice, then {@link Meter.addCredits} with `req.idempotencyKey`. Must be idempotent
+     * on that key.
+     */
+    request(subjectId: string, req: TopUpRequest & {
+        balance: MeterBalance;
+    }): MaybePromise<void>;
+}
+export interface MeterOptions {
+    /** The meter's name in the store (`whatsapp_messages`, `sms`, `ai_tokens`). */
+    key: string;
+    period?: MeterPeriod;
+    /** IANA zone the periods follow. Default UTC. */
+    timeZone?: string;
+    store: MeterStore;
+    /** What a period includes for this subject: its plan's limit, or one negotiated for it. */
+    included: (subjectId: string, period: string) => MaybePromise<number>;
+    /**
+     * The subject's credits, when they are kept outside the store's ledger: a running total
+     * (dated before any period, so it never expires) or the lots, each with its period.
+     */
+    creditsFrom?: (subjectId: string) => MaybePromise<number | readonly CreditLot[]>;
+    credits?: CreditPolicy;
+    carryOver?: CarryOverPolicy;
+    overage?: OveragePolicy;
+    /** Fractions of the included quantity to alert at, once per period. Default `[0.8]`. */
+    thresholds?: readonly number[];
+    autoTopUp?: AutoTopUpOptions;
+    /** Called once per alert key; a failure is swallowed — an alert never blocks a consumption. */
+    onAlert?: (subjectId: string, alert: MeterAlert, balance: MeterBalance) => MaybePromise<void>;
+    /** For tests. */
+    now?: () => Date;
+}
+export interface ConsumeInput {
+    cost?: number;
+    exempt?: boolean;
+    now?: Date;
+}
+export type ConsumeResult = {
+    allowed: true;
+    period: string;
+    split: MeterSplit;
+    /** The balance after this consumption. */
+    balance: MeterBalance;
+    alerts: MeterAlert[];
+    /** The automatic pack asked for, when the consumption left a debt (or crossed `below`). */
+    topUp?: TopUpRequest & {
+        error?: string;
+    };
+} | {
+    allowed: false;
+    period: string;
+    reason: NonNullable<GateDecision['reason']>;
+    balance: MeterBalance;
+};
+export interface Meter {
+    readonly key: string;
+    /** The period `at` is counted in, on this meter's clock. */
+    periodOf(at?: Date): string;
+    balance(subjectId: string, now?: Date): Promise<MeterBalance>;
+    /** Room for one more, counting `reserved` units already spoken for; nothing is written. */
+    check(subjectId: string, input?: ConsumeInput & {
+        reserved?: number;
+    }): Promise<GateDecision & {
+        balance: MeterBalance;
+    }>;
+    /** Consume `cost` units: refused when there is no room (unless exempt, or paying as it goes), counted otherwise. */
+    consume(subjectId: string, input?: ConsumeInput): Promise<ConsumeResult>;
+    /** Give back what a consumption took — a send the provider refused before it left. */
+    release(subjectId: string, consumed: Pick<Extract<ConsumeResult, {
+        allowed: true;
+    }>, 'period' | 'split'>): Promise<void>;
+    /** Add credits to the store's ledger (a pack bought, a grant, an automatic top-up, a void). */
+    addCredits(subjectId: string, units: number, entry: Omit<CreditEntry, 'subjectId' | 'meterKey' | 'units'>): Promise<{
+        added: boolean;
+    }>;
+}
+export declare function createMeter(options: MeterOptions): Meter;
+/** Whether nothing at all is left — for a UI that disables a "send" button exactly when the send would be refused. */
+export declare function isExhausted(b: MeterBalance, cost?: number): boolean;
+export {};
+//# sourceMappingURL=meter.d.ts.map

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

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

package/dist/meters/meter.js

@@ -0,0 +1,150 @@
+/**
+ * A metered allowance: the rules (`rules.ts`) over a store (`store.ts`), for one meter.
+ *
+ * ```ts
+ * const whatsapp = createMeter({
+ *   key: 'whatsapp_messages',
+ *   store: createPostgresMeterStore(tx.query),
+ *   included: (tenantId) => entitlements.forSubject(tenantId).then((e) => e.limitOf('whatsapp_messages') ?? 0),
+ *   autoTopUp: {
+ *     packSize: 100,
+ *     // no free messages: an exempt send that found nothing left buys a small pack
+ *     request: (tenantId, req) => orders.autoTopUp(tenantId, req),   // invoices it, then meter.addCredits(...)
+ *   },
+ *   onAlert: (tenantId, alert, balance) => notifyOwners(tenantId, alert, balance),
+ * });
+ *
+ * // at enqueue: is there room, counting what is already queued?
+ * if (!(await whatsapp.check(tenantId, { reserved: queued })).allowed) return skip('quota');
+ * // when the message leaves (or reserve-then-release, around a synchronous send)
+ * const used = await whatsapp.consume(tenantId, { exempt: isSafetyAlert });
+ * if (!used.allowed) return skip('quota');
+ * // the provider refused it synchronously: give the units back
+ * await whatsapp.release(tenantId, used);
+ * ```
+ *
+ * **The policies** — each a product decision, each off by default:
+ *
+ * - `credits: { expiresAfterPeriods: 1 }` — bought credits expire with the period they were
+ *   bought in (`12` = a year; per lot with `addCredits(…, { expiresAfterPeriods })`).
+ *   Default: they roll over until spent.
+ * - `carryOver: { max, expiresAfterPeriods }` — what a period included and did not use is
+ *   carried into the next ones.
+ * - `overage: { allow: 'all', maxDebt }` — pay as you go: nobody is refused while what is
+ *   owed stays under the cap. Default: only exempt consumptions may run a debt.
+ * - `autoTopUp: { packSize, below? }` — ask for packs as soon as a debt appears (or the
+ *   balance drops under `below`), under an idempotency key that holds until they arrive.
+ * - `timeZone` — the periods follow the subject's clock, not UTC.
+ *
+ * **Credits** come from the store's ledger by default (`addCredits`). A product whose
+ * credits are bought elsewhere — another service, another database — passes `creditsFrom`
+ * instead: a running total (they never expire), or the lots with their periods (any policy).
+ *
+ * **Exempt** consumptions (`exempt: true`) are never refused. With nothing left they land
+ * on debt, which the next credits pay. `autoTopUp.request` is called after the usage is
+ * written, and a failure there never undoes the consumption: it is reported on the result
+ * (`topUp.error`) and asked again by the next consumption that still sees the debt.
+ */
+import { BEFORE_ANY_PERIOD, afterConsume, alertsCrossed, carryOverSources, gate, openingCredits, periodKey, remainingOf, splitOf, topUpFor } from './rules.js';
+const wholeOf = (n) => Math.max(0, Math.floor(Number(n) || 0));
+export function createMeter(options) {
+    const { key, store } = options;
+    const kind = options.period ?? 'month';
+    const thresholds = options.thresholds ?? [0.8];
+    const clock = options.now ?? (() => new Date());
+    const periodOf = (at = clock()) => periodKey(at, kind, { timeZone: options.timeZone });
+    const includedOf = async (subjectId, p) => wholeOf(await options.included(subjectId, p));
+    async function lotsOf(subjectId) {
+        if (options.creditsFrom) {
+            const from = await options.creditsFrom(subjectId);
+            return typeof from === 'number' ? (from > 0 ? [{ units: Math.floor(from), period: BEFORE_ANY_PERIOD, expiresAfterPeriods: 0 }] : []) : [...from];
+        }
+        return (await store.lots(subjectId, key)).map((e) => ({ units: e.units, period: periodOf(e.createdAt), expiresAfterPeriods: e.expiresAfterPeriods }));
+    }
+    /** Everything but this period's counters: what credits are worth in it. */
+    async function opening(subjectId, p) {
+        const lots = await lotsOf(subjectId);
+        const credits = Math.max(0, lots.reduce((n, l) => n + l.units, 0));
+        const expires = (options.credits?.expiresAfterPeriods ?? 0) > 0 || lots.some((l) => (l.expiresAfterPeriods ?? 0) > 0);
+        let history;
+        if (expires || options.carryOver) {
+            history = await store.history(subjectId, key, p);
+        }
+        else {
+            /* nothing expires: the replay is the running total, and one figure stands for every earlier period */
+            const drawn = await store.drawnBefore(subjectId, key, p);
+            history = drawn > 0 ? [{ period: BEFORE_ANY_PERIOD, included: 0, used: drawn, fromCredits: drawn, onDebt: 0 }] : [];
+        }
+        const replay = { period: p, kind, lots, history, credits: options.credits, carryOver: options.carryOver };
+        const sources = options.carryOver ? carryOverSources(replay) : [];
+        const known = new Map(await Promise.all(sources.map(async (s) => [s, await includedOf(subjectId, s)])));
+        return { ...openingCredits({ ...replay, includedOf: (s) => known.get(s) ?? 0 }), credits };
+    }
+    const balanceFrom = (p, included, row, open) => ({
+        period: p,
+        included,
+        used: row?.used ?? 0,
+        fromCredits: row?.fromCredits ?? 0,
+        onDebt: row?.onDebt ?? 0,
+        ...open,
+    });
+    async function balance(subjectId, now = clock()) {
+        const p = periodOf(now);
+        const [included, row, open] = await Promise.all([includedOf(subjectId, p), store.readPeriod(subjectId, key, p), opening(subjectId, p)]);
+        return balanceFrom(p, included, row, open);
+    }
+    return {
+        key,
+        periodOf,
+        balance,
+        async check(subjectId, input = {}) {
+            const b = await balance(subjectId, input.now ?? clock());
+            return { ...gate(b, { ...input, overage: options.overage }), balance: b };
+        },
+        async consume(subjectId, input = {}) {
+            const p = periodOf(input.now ?? clock());
+            const included = await includedOf(subjectId, p);
+            /* the period row first: from here to commit, no other consumption of this subject reads it */
+            const row = await store.lockPeriod(subjectId, key, p, included);
+            const before = balanceFrom(p, included, row, await opening(subjectId, p));
+            const decision = gate(before, { cost: input.cost, exempt: input.exempt, overage: options.overage });
+            if (!decision.allowed)
+                return { allowed: false, period: p, reason: decision.reason, balance: before };
+            const split = splitOf(before, input.cost);
+            const after = afterConsume(before, split);
+            const alerts = alertsCrossed(before, after, thresholds, row.alerts);
+            await store.addUsage(subjectId, key, p, split, alerts.map((a) => a.key));
+            for (const alert of alerts) {
+                try {
+                    await options.onAlert?.(subjectId, alert, after);
+                }
+                catch {
+                    /* the slot is claimed either way: an alert is a courtesy, never a reason to refuse */
+                }
+            }
+            const result = { allowed: true, period: p, split, balance: after, alerts };
+            const due = options.autoTopUp ? topUpFor(after, options.autoTopUp) : null;
+            if (options.autoTopUp && due) {
+                try {
+                    await options.autoTopUp.request(subjectId, { ...due, balance: after });
+                    result.topUp = due;
+                }
+                catch (err) {
+                    result.topUp = { ...due, error: err instanceof Error ? err.message : String(err) };
+                }
+            }
+            return result;
+        },
+        async release(subjectId, consumed) {
+            await store.releaseUsage(subjectId, key, consumed.period, consumed.split);
+        },
+        async addCredits(subjectId, units, entry) {
+            return store.addCredits({ subjectId, meterKey: key, units, ...entry });
+        },
+    };
+}
+/** Whether nothing at all is left — for a UI that disables a "send" button exactly when the send would be refused. */
+export function isExhausted(b, cost = 1) {
+    return remainingOf(b) < Math.max(1, Math.floor(cost));
+}
+//# sourceMappingURL=meter.js.map

package/dist/meters/meter.js.map

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

package/dist/meters/postgres.d.ts

@@ -0,0 +1,23 @@
+/**
+ * {@link MeterStore} over `vk_billing_meter_usage` and `vk_billing_credit_ledger`
+ * (`vk_billing_0002_meters.sql`).
+ *
+ * Pass the transaction's `query` as `querier`: `lockPeriod` takes the period row with
+ * `INSERT … ON CONFLICT … DO UPDATE … RETURNING`, which holds its row lock until the
+ * transaction ends, so the read-decide-write of a consumption is serialised per subject
+ * and meter — two concurrent sends cannot both take the last unit. Typed structurally, so
+ * this package does not depend on `@venturekit/data`; its `query` and `tx.query` fit.
+ *
+ * Table names are options because a consumer may keep the counters next to its own data
+ * (a schema, a prefix); the columns are fixed. A consumer with tables of its own shape
+ * implements {@link MeterStore} instead — it is eight small queries.
+ */
+import type { MeterStore } from './store.js';
+/** `@venturekit/data`'s `query` / `tx.query` shape. */
+export type MeterQuerier = <T = Record<string, unknown>[]>(sql: string, params?: unknown[]) => Promise<T>;
+export interface PostgresMeterStoreOptions {
+    usageTable?: string;
+    ledgerTable?: string;
+}
+export declare function createPostgresMeterStore(querier: MeterQuerier, options?: PostgresMeterStoreOptions): MeterStore;
+//# sourceMappingURL=postgres.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/meters/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAA2D,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtG,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAE1G,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAmBD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,yBAA8B,GAAG,UAAU,CAoFnH"}

package/dist/meters/postgres.js

@@ -0,0 +1,81 @@
+/**
+ * {@link MeterStore} over `vk_billing_meter_usage` and `vk_billing_credit_ledger`
+ * (`vk_billing_0002_meters.sql`).
+ *
+ * Pass the transaction's `query` as `querier`: `lockPeriod` takes the period row with
+ * `INSERT … ON CONFLICT … DO UPDATE … RETURNING`, which holds its row lock until the
+ * transaction ends, so the read-decide-write of a consumption is serialised per subject
+ * and meter — two concurrent sends cannot both take the last unit. Typed structurally, so
+ * this package does not depend on `@venturekit/data`; its `query` and `tx.query` fit.
+ *
+ * Table names are options because a consumer may keep the counters next to its own data
+ * (a schema, a prefix); the columns are fixed. A consumer with tables of its own shape
+ * implements {@link MeterStore} instead — it is eight small queries.
+ */
+import { assertCreditEntry } from './store.js';
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
+function identifier(name) {
+    /* interpolated into SQL — Postgres has no parameterised identifiers — so only plain names pass */
+    if (!IDENTIFIER.test(name))
+        throw new Error(`meter store: invalid table name '${name}'`);
+    return name;
+}
+const rowOf = (r) => ({ used: Number(r.used), fromCredits: Number(r.fromCredits), onDebt: Number(r.onDebt), alerts: [...(r.alerts ?? [])] });
+export function createPostgresMeterStore(querier, options = {}) {
+    const usage = identifier(options.usageTable ?? 'vk_billing_meter_usage');
+    const ledger = identifier(options.ledgerTable ?? 'vk_billing_credit_ledger');
+    const COLUMNS = `used, from_credits AS "fromCredits", on_debt AS "onDebt", alerts`;
+    return {
+        async lockPeriod(subjectId, meterKey, period, included) {
+            const rows = await querier(`INSERT INTO ${usage} (subject_id, meter_key, period, included)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (subject_id, meter_key, period) DO UPDATE SET included = EXCLUDED.included, updated_at = NOW()
+         RETURNING ${COLUMNS}`, [subjectId, meterKey, period, included]);
+            if (!rows[0])
+                throw new Error(`meter ${meterKey}: no period row returned for ${subjectId} ${period}`);
+            return rowOf(rows[0]);
+        },
+        async readPeriod(subjectId, meterKey, period) {
+            const rows = await querier(`SELECT ${COLUMNS} FROM ${usage} WHERE subject_id = $1 AND meter_key = $2 AND period = $3`, [subjectId, meterKey, period]);
+            return rows[0] ? rowOf(rows[0]) : null;
+        },
+        async history(subjectId, meterKey, period) {
+            const rows = await querier(`SELECT period, included, ${COLUMNS} FROM ${usage} WHERE subject_id = $1 AND meter_key = $2 AND period < $3 ORDER BY period`, [subjectId, meterKey, period]);
+            return rows.map((r) => ({ period: r.period, included: Number(r.included), used: Number(r.used), fromCredits: Number(r.fromCredits), onDebt: Number(r.onDebt) }));
+        },
+        async drawnBefore(subjectId, meterKey, period) {
+            const rows = await querier(`SELECT COALESCE(SUM(from_credits + on_debt), 0) AS n FROM ${usage} WHERE subject_id = $1 AND meter_key = $2 AND period < $3`, [subjectId, meterKey, period]);
+            return Number(rows[0]?.n ?? 0);
+        },
+        async addUsage(subjectId, meterKey, period, split, alerts) {
+            await querier(`UPDATE ${usage}
+            SET used = used + $4 + $5 + $6, from_credits = from_credits + $5, on_debt = on_debt + $6,
+                alerts = ARRAY(SELECT DISTINCT unnest(alerts || $7::text[])), updated_at = NOW()
+          WHERE subject_id = $1 AND meter_key = $2 AND period = $3`, [subjectId, meterKey, period, split.included, split.credits, split.debt, [...alerts]]);
+        },
+        async releaseUsage(subjectId, meterKey, period, split) {
+            await querier(`UPDATE ${usage}
+            SET used = GREATEST(0, used - ($4 + $5 + $6)), from_credits = GREATEST(0, from_credits - $5), on_debt = GREATEST(0, on_debt - $6), updated_at = NOW()
+          WHERE subject_id = $1 AND meter_key = $2 AND period = $3`, [subjectId, meterKey, period, split.included, split.credits, split.debt]);
+        },
+        async lots(subjectId, meterKey) {
+            const rows = await querier(`SELECT units, kind, created_at AS "createdAt", expires_after_periods AS "expiresAfterPeriods"
+           FROM ${ledger} WHERE subject_id = $1 AND meter_key = $2 ORDER BY created_at, id`, [subjectId, meterKey]);
+            return rows.map((r) => ({
+                units: Number(r.units),
+                kind: r.kind,
+                createdAt: r.createdAt instanceof Date ? r.createdAt : new Date(r.createdAt),
+                expiresAfterPeriods: r.expiresAfterPeriods === null ? null : Number(r.expiresAfterPeriods),
+            }));
+        },
+        async addCredits(entry) {
+            assertCreditEntry(entry);
+            const rows = await querier(`INSERT INTO ${ledger} (subject_id, meter_key, units, kind, reference, idempotency_key, expires_after_periods, created_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, COALESCE($8::timestamptz, NOW()))
+         ON CONFLICT (subject_id, meter_key, idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
+         RETURNING id`, [entry.subjectId, entry.meterKey, entry.units, entry.kind, entry.reference ?? null, entry.idempotencyKey ?? null, entry.expiresAfterPeriods ?? null, entry.at?.toISOString() ?? null]);
+            return { added: rows.length > 0 };
+        },
+    };
+}
+//# sourceMappingURL=postgres.js.map

package/dist/meters/postgres.js.map

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