@basaltkit/subscriptions 1.2.0 → 2.1.0

package/dist/index.d.ts

@@ -19,7 +19,12 @@ declare function meter(limit: number): Meter;
 type FeatureValue = boolean | number | Meter;
 type BillingPeriod = 'monthly' | 'yearly';
 interface PlanDefinition {
-    /** 0 = free · number = same price both periods · object = per period · 'custom' = sales-led */
+    /**
+     * Price in the currency's minor unit (integer; cents — `2900` = $29.00).
+     * 0 = free · number = same price both periods · object = per period ·
+     * 'custom' = sales-led. Only gated (`> 0`) and displayed here; the actual
+     * Stripe charge uses a pre-created price id on the gateway.
+     */
     price: number | {
         monthly: number;
         yearly: number;
@@ -268,12 +273,16 @@ declare class FakeBillingGateway implements BillingGateway {
  * `BillingGateway` (card subscriptions). Recurring billing is modelled by
  * creating one payment per period (invoice → reference → webhook confirms → the
  * period is activated).
+ *
+ * **All amounts are integers in the currency's minor unit** (cents; `100 = 1.00`)
+ * — the Stripe convention. Use the `money` helpers (`toMinor`/`formatMoney`) at
+ * the human boundary. Drivers translate to each provider's expected format.
  */
 /** A one-off payment request handed to a `PaymentGateway`. */
 interface PaymentRequest {
     /** Who is paying — a tenant/user/customer id you reconcile against. */
     billableId: string;
-    /** Amount in the currency's major unit (e.g. 5000 = 5000,00 Kz). */
+    /** Amount in the currency's minor unit (integer; `500000` = 5.000,00 Kz). */
     amount: number;
     /** ISO 4217. Defaults to the gateway's own (AOA for Angolan gateways). */
     currency?: string;
@@ -403,6 +412,26 @@ interface PaymentApplyResult {
     fresh: boolean;
     record?: PaymentRecord;
 }
+/** Lifecycle events emitted by the ledger — subscribe with `ledger.on(...)`. */
+interface PaymentLedgerEvents {
+    /** A payment was recorded as pending (on `created`). */
+    recorded: {
+        record: PaymentRecord | undefined;
+        payment: NewPayment;
+    };
+    /** A payment was confirmed paid (fresh `apply` of a `payment.succeeded`). */
+    confirmed: {
+        record: PaymentRecord | undefined;
+        event: PaymentEvent;
+    };
+    /** A payment failed (fresh `apply` of a `payment.failed`). */
+    failed: {
+        record: PaymentRecord | undefined;
+        event: PaymentEvent;
+    };
+}
+type PaymentLedgerEvent = keyof PaymentLedgerEvents;
+type PaymentLedgerListener<K extends PaymentLedgerEvent> = (payload: PaymentLedgerEvents[K]) => void | Promise<void>;
 interface PaymentLedgerOptions {
     /** Where payments are stored. Default: in-memory. */
     store?: PaymentStore;
@@ -411,6 +440,12 @@ interface PaymentLedgerOptions {
      * Redis) across the app so a retried callback is applied exactly once.
      */
     webhooks?: WebhookStore;
+    /**
+     * Called when a lifecycle listener throws. Listeners are best-effort side
+     * effects (notifications, analytics) that never roll back a payment — a
+     * throwing one is reported here instead. Default: swallow.
+     */
+    onListenerError?: (error: unknown, event: PaymentLedgerEvent) => void;
 }
 /**
  * Ties a `PaymentStore` to webhook idempotency so a retried callback is applied
@@ -432,7 +467,17 @@ interface PaymentLedgerOptions {
 declare class PaymentLedger {
     private readonly store;
     private readonly webhooks;
+    private readonly onListenerError;
+    private readonly listeners;
     constructor(options?: PaymentLedgerOptions);
+    /**
+     * Subscribe to a lifecycle event (`recorded`/`confirmed`/`failed`). Listeners
+     * are best-effort: they run after the payment is safely persisted and a
+     * throwing one never rolls it back (it's reported via `onListenerError`).
+     * Returns an unsubscribe function.
+     */
+    on<K extends PaymentLedgerEvent>(event: K, listener: PaymentLedgerListener<K>): () => void;
+    private emit;
     /** Record a just-created payment as pending. Call after `createPayment`. */
     created(instruction: PaymentInstruction, request: PaymentRequest): Promise<void>;
     /**
@@ -464,7 +509,7 @@ interface RecurringSubscription {
     /** The customer/tenant this subscription bills. One per billableId. */
     billableId: string;
     plan: string;
-    /** Price per period, in the currency's major unit. */
+    /** Price per period, in the currency's minor unit (integer; cents). */
     amount: number;
     interval: RecurringInterval;
     status: RecurringStatus;
@@ -558,6 +603,38 @@ declare class RecurringReferenceBilling {
     cancel(billableId: string): Promise<void>;
 }
 
+/**
+ * Money handling for the subscriptions ecosystem. **All amounts in the public
+ * API are integers in the currency's minor unit** — cents, `100 = 1.00`. This
+ * is the Stripe/Adyen convention: exact, no floating-point rounding, and no
+ * ambiguity about units. Use these helpers to convert at the human boundary
+ * (input forms, display) and to validate.
+ *
+ * ```ts
+ * toMinor(5000, 'AOA')      // 500000  (5.000,00 Kz)
+ * toMajor(500000, 'AOA')    // 5000
+ * formatMoney(500000, 'AOA', 'pt-AO') // "5.000,00 AOA"
+ * assertMinorUnits(2999)    // ok      ($29.99)
+ * assertMinorUnits(29.99)   // throws
+ * ```
+ */
+/** Number of minor-unit decimal places for a currency (default 2). */
+declare function currencyDecimals(currency: string): number;
+/** Convert a major-unit amount (e.g. `5000` Kz) to minor units (`500000`). */
+declare function toMinor(major: number, currency: string): number;
+/** Convert minor units (`500000`) back to a major-unit amount (`5000` Kz). */
+declare function toMajor(minor: number, currency: string): number;
+/** Format a minor-unit amount for display. Falls back to a plain string if Intl lacks the currency. */
+declare function formatMoney(minor: number, currency: string, locale?: string): string;
+/** True when `amount` is a valid minor-unit value (a non-negative integer). */
+declare function isMinorUnits(amount: number): boolean;
+/**
+ * Throw unless `amount` is a valid minor-unit value. Drivers call this so a
+ * major-unit slip (e.g. `29.99` instead of `2999`) fails fast instead of
+ * silently under/over-charging.
+ */
+declare function assertMinorUnits(amount: number, label?: string): void;
+
 declare class StripeRequestError extends BasaltError {
     readonly httpStatus: number;
     constructor(httpStatus: number, message: string);
@@ -770,4 +847,4 @@ declare function billingRoutes(options: BillingRoutesOptions): BasaltRoute[];
  */
 declare function billingWebhookRoute(gateway: BillingGateway): BasaltRoute;
 
-export { type BillingGateway, type BillingPeriod, type BillingRoutesOptions, type CheckoutInput, type CreateSubscriptionInput, FakeBillingGateway, FakePaymentGateway, FeatureUnavailableError, type FeatureValue, GatewayUnsupportedError, type HandleEventResult, MemoryPaymentStore, MemoryRecurringStore, MemorySubscriptionStore, MemoryUsageStore, MemoryWebhookStore, type Meter, type NewPayment, NotSubscribedError, type PaymentApplyResult, type PaymentEvent, type PaymentGateway, type PaymentInstruction, PaymentLedger, type PaymentLedgerOptions, type PaymentRecord, type PaymentRecordStatus, type PaymentRequest, type PaymentStore, type PlanDefinition, type Plans, type PortalInput, QuotaExceededError, type RecurringBillingOptions, type RecurringInterval, RecurringReferenceBilling, type RecurringStatus, type RecurringStore, type RecurringSubscription, type RedisLike, RedisUsageStore, type RedisUsageStoreOptions, type RedisWebhookClient, RedisWebhookStore, type RedisWebhookStoreOptions, SUBSCRIPTIONS, StripeBillingGateway, type StripeGatewayOptions, StripeRequestError, type SubscribeInput, type SubscriptionRecord, type SubscriptionStatus, type SubscriptionStore, Subscriptions, type SubscriptionsOptions, type SubscriptionsPluginOptions, type SwapInput, UnknownPlanError, type UsageConsumeResult, type UsageStore, type WebhookEvent, WebhookInvalidError, type WebhookStore, addInterval, billingRoutes, billingWebhookRoute, definePlans, featureLimit, isMeter, meter, planPrice, subscriptionsPlugin };
+export { type BillingGateway, type BillingPeriod, type BillingRoutesOptions, type CheckoutInput, type CreateSubscriptionInput, FakeBillingGateway, FakePaymentGateway, FeatureUnavailableError, type FeatureValue, GatewayUnsupportedError, type HandleEventResult, MemoryPaymentStore, MemoryRecurringStore, MemorySubscriptionStore, MemoryUsageStore, MemoryWebhookStore, type Meter, type NewPayment, NotSubscribedError, type PaymentApplyResult, type PaymentEvent, type PaymentGateway, type PaymentInstruction, PaymentLedger, type PaymentLedgerEvent, type PaymentLedgerEvents, type PaymentLedgerListener, type PaymentLedgerOptions, type PaymentRecord, type PaymentRecordStatus, type PaymentRequest, type PaymentStore, type PlanDefinition, type Plans, type PortalInput, QuotaExceededError, type RecurringBillingOptions, type RecurringInterval, RecurringReferenceBilling, type RecurringStatus, type RecurringStore, type RecurringSubscription, type RedisLike, RedisUsageStore, type RedisUsageStoreOptions, type RedisWebhookClient, RedisWebhookStore, type RedisWebhookStoreOptions, SUBSCRIPTIONS, StripeBillingGateway, type StripeGatewayOptions, StripeRequestError, type SubscribeInput, type SubscriptionRecord, type SubscriptionStatus, type SubscriptionStore, Subscriptions, type SubscriptionsOptions, type SubscriptionsPluginOptions, type SwapInput, UnknownPlanError, type UsageConsumeResult, type UsageStore, type WebhookEvent, WebhookInvalidError, type WebhookStore, addInterval, assertMinorUnits, billingRoutes, billingWebhookRoute, currencyDecimals, definePlans, featureLimit, formatMoney, isMeter, isMinorUnits, meter, planPrice, subscriptionsPlugin, toMajor, toMinor };

package/dist/index.js

@@ -246,19 +246,46 @@ var MemoryPaymentStore = class {
 var PaymentLedger = class {
   store;
   webhooks;
+  onListenerError;
+  listeners = { recorded: /* @__PURE__ */ new Set(), confirmed: /* @__PURE__ */ new Set(), failed: /* @__PURE__ */ new Set() };
   constructor(options = {}) {
     this.store = options.store ?? new MemoryPaymentStore();
     this.webhooks = options.webhooks ?? new MemoryWebhookStore();
+    this.onListenerError = options.onListenerError ?? (() => {
+    });
+  }
+  /**
+   * Subscribe to a lifecycle event (`recorded`/`confirmed`/`failed`). Listeners
+   * are best-effort: they run after the payment is safely persisted and a
+   * throwing one never rolls it back (it's reported via `onListenerError`).
+   * Returns an unsubscribe function.
+   */
+  on(event, listener) {
+    this.listeners[event].add(listener);
+    return () => {
+      this.listeners[event].delete(listener);
+    };
+  }
+  async emit(event, payload) {
+    for (const listener of this.listeners[event]) {
+      try {
+        await listener(payload);
+      } catch (error) {
+        this.onListenerError(error, event);
+      }
+    }
   }
   /** Record a just-created payment as pending. Call after `createPayment`. */
   async created(instruction, request) {
-    await this.store.create({
+    const payment = {
       id: instruction.id,
       amount: request.amount,
       ...request.billableId ? { billableId: request.billableId } : {},
       ...request.reference ? { reference: request.reference } : {},
       ...instruction.raw !== void 0 ? { raw: instruction.raw } : {}
-    });
+    };
+    await this.store.create(payment);
+    await this.emit("recorded", { record: await this.store.get(instruction.id), payment });
   }
   /**
    * Apply a verified `PaymentEvent` idempotently. Dedupes by `event.id`; on a
@@ -273,19 +300,21 @@ var PaymentLedger = class {
   async apply(event, onFresh) {
     const fresh = await this.webhooks.markProcessed(event.id);
     if (!fresh) return { fresh: false };
+    let record;
     try {
       const status = event.type === "payment.succeeded" ? "paid" : "failed";
       await this.store.setStatus(event.paymentId, status, {
         amount: event.amount,
         ...event.raw !== void 0 ? { raw: event.raw } : {}
       });
-      const record = await this.store.get(event.paymentId);
+      record = await this.store.get(event.paymentId);
       if (onFresh) await onFresh(record, event);
-      return { fresh: true, ...record ? { record } : {} };
     } catch (error) {
       await this.webhooks.release(event.id);
       throw error;
     }
+    await this.emit(event.type === "payment.succeeded" ? "confirmed" : "failed", { record, event });
+    return { fresh: true, ...record ? { record } : {} };
   }
   get(id) {
     return this.store.get(id);
@@ -419,6 +448,52 @@ var RecurringReferenceBilling = class {
   }
 };
 
+// src/money.ts
+var CURRENCY_DECIMALS = {
+  AOA: 2,
+  USD: 2,
+  EUR: 2,
+  GBP: 2,
+  BRL: 2,
+  ZAR: 2,
+  MZN: 2,
+  CVE: 2,
+  NGN: 2,
+  KES: 2,
+  JPY: 0,
+  XOF: 0,
+  XAF: 0,
+  CLP: 0
+};
+var DEFAULT_DECIMALS = 2;
+function currencyDecimals(currency) {
+  return CURRENCY_DECIMALS[currency.toUpperCase()] ?? DEFAULT_DECIMALS;
+}
+function toMinor(major, currency) {
+  return Math.round(major * 10 ** currencyDecimals(currency));
+}
+function toMajor(minor, currency) {
+  return minor / 10 ** currencyDecimals(currency);
+}
+function formatMoney(minor, currency, locale = "en-US") {
+  const major = toMajor(minor, currency);
+  try {
+    return new Intl.NumberFormat(locale, { style: "currency", currency }).format(major);
+  } catch {
+    return `${major.toFixed(currencyDecimals(currency))} ${currency.toUpperCase()}`;
+  }
+}
+function isMinorUnits(amount) {
+  return Number.isInteger(amount) && amount >= 0;
+}
+function assertMinorUnits(amount, label = "amount") {
+  if (!isMinorUnits(amount)) {
+    throw new RangeError(
+      `${label} must be a non-negative integer in minor units (e.g. cents), got ${amount}`
+    );
+  }
+}
+
 // src/drivers/stripe.ts
 import { createHmac, timingSafeEqual } from "crypto";
 import { BasaltError as BasaltError3 } from "@basaltkit/core";
@@ -939,12 +1014,18 @@ export {
   UnknownPlanError,
   WebhookInvalidError,
   addInterval,
+  assertMinorUnits,
   billingRoutes,
   billingWebhookRoute,
+  currencyDecimals,
   definePlans,
   featureLimit,
+  formatMoney,
   isMeter,
+  isMinorUnits,
   meter,
   planPrice,
-  subscriptionsPlugin
+  subscriptionsPlugin,
+  toMajor,
+  toMinor
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/subscriptions",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "description": "Billing for Basalt, Cashier/Soulbscription-style: declarative plans, subscriptions with trials, feature flags, usage limits, gateway drivers and idempotent webhooks.",
   "license": "MIT",
   "type": "module",
@@ -14,8 +14,8 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.0.0",
-    "@basaltkit/fastify": "^1.0.0"
+    "@basaltkit/fastify": "^1.0.0",
+    "@basaltkit/core": "^1.0.0"
   },
   "peerDependencies": {
     "zod": "^3.24.0 || ^4.0.0"