@basaltkit/subscriptions 2.0.0 → 2.1.0

package/dist/index.d.ts

@@ -412,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;
@@ -420,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
@@ -441,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>;
     /**
@@ -811,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, assertMinorUnits, billingRoutes, billingWebhookRoute, currencyDecimals, definePlans, featureLimit, formatMoney, isMeter, isMinorUnits, meter, planPrice, subscriptionsPlugin, toMajor, toMinor };
+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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/subscriptions",
-  "version": "2.0.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"