@basaltkit/subscriptions 2.0.0 → 2.2.0

package/dist/index.d.ts

@@ -161,6 +161,24 @@ declare class WebhookInvalidError extends BasaltError {
     readonly status = 400;
     constructor();
 }
+/**
+ * Thrown when a gateway is asked to verify a webhook but no signing secret is
+ * configured. Verification fails closed: an unauthenticated callback must never
+ * be trusted (anyone could forge a `payment.succeeded`).
+ */
+declare class WebhookSecretMissingError extends BasaltError {
+    readonly status = 500;
+    constructor(gateway: string);
+}
+/**
+ * Thrown when a confirmed payment's amount does not match the amount that was
+ * originally requested for that payment id — an underpayment, or a forged /
+ * mis-routed callback trying to settle an invoice for less.
+ */
+declare class PaymentAmountMismatchError extends BasaltError {
+    readonly status = 400;
+    constructor(paymentId: string, expected: number, actual: number);
+}
 /** Gateway-agnostic webhook event, already translated to domain terms. */
 interface WebhookEvent {
     /** Unique id at the gateway — used for idempotent processing. */
@@ -412,6 +430,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 +458,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 +485,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 +865,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, PaymentAmountMismatchError, 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, WebhookSecretMissingError, type WebhookStore, addInterval, assertMinorUnits, billingRoutes, billingWebhookRoute, currencyDecimals, definePlans, featureLimit, formatMoney, isMeter, isMinorUnits, meter, planPrice, subscriptionsPlugin, toMajor, toMinor };

package/dist/index.js

@@ -160,6 +160,24 @@ var WebhookInvalidError = class extends BasaltError2 {
     super("BILLING_WEBHOOK_INVALID", "Webhook signature verification failed.");
   }
 };
+var WebhookSecretMissingError = class extends BasaltError2 {
+  status = 500;
+  constructor(gateway) {
+    super(
+      "BILLING_WEBHOOK_SECRET_MISSING",
+      `${gateway}: cannot verify a webhook without a configured signing secret \u2014 refusing to trust an unsigned callback.`
+    );
+  }
+};
+var PaymentAmountMismatchError = class extends BasaltError2 {
+  status = 400;
+  constructor(paymentId, expected, actual) {
+    super(
+      "BILLING_PAYMENT_AMOUNT_MISMATCH",
+      `Payment ${paymentId} was requested for ${expected} but the webhook confirmed ${actual} \u2014 refusing to mark it paid.`
+    );
+  }
+};
 var FakeBillingGateway = class {
   name = "fake";
   created = [];
@@ -246,19 +264,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 +318,27 @@ 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";
+      if (status === "paid") {
+        const existing = await this.store.get(event.paymentId);
+        if (existing && existing.amount > 0 && event.amount !== existing.amount) {
+          throw new PaymentAmountMismatchError(event.paymentId, existing.amount, event.amount);
+        }
+      }
       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);
@@ -973,6 +1026,7 @@ export {
   MemoryUsageStore,
   MemoryWebhookStore,
   NotSubscribedError,
+  PaymentAmountMismatchError,
   PaymentLedger,
   QuotaExceededError,
   RecurringReferenceBilling,
@@ -984,6 +1038,7 @@ export {
   Subscriptions,
   UnknownPlanError,
   WebhookInvalidError,
+  WebhookSecretMissingError,
   addInterval,
   assertMinorUnits,
   billingRoutes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/subscriptions",
-  "version": "2.0.0",
+  "version": "2.2.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",
@@ -15,7 +15,7 @@
   ],
   "dependencies": {
     "@basaltkit/core": "^1.0.0",
-    "@basaltkit/fastify": "^1.0.0"
+    "@basaltkit/fastify": "^1.1.0"
   },
   "peerDependencies": {
     "zod": "^3.24.0 || ^4.0.0"