@basaltkit/subscriptions 1.0.1 → 1.2.0

package/dist/index.d.ts

@@ -349,6 +349,214 @@ declare class FakePaymentGateway implements PaymentGateway {
     createPayment(request: PaymentRequest): Promise<PaymentInstruction>;
     verifyWebhook(rawBody: string, signature: string | undefined): PaymentEvent;
 }
+type PaymentRecordStatus = 'pending' | 'paid' | 'failed';
+/** A payment as tracked in your app's ledger, keyed by the gateway payment id. */
+interface PaymentRecord {
+    /** Gateway payment id — `PaymentInstruction.id` / `PaymentEvent.paymentId`. */
+    id: string;
+    status: PaymentRecordStatus;
+    amount: number;
+    billableId?: string;
+    reference?: string;
+    /** Epoch ms. */
+    createdAt: number;
+    updatedAt: number;
+    raw?: unknown;
+}
+/** Input to record a freshly-created (pending) payment. */
+interface NewPayment {
+    id: string;
+    amount: number;
+    billableId?: string;
+    reference?: string;
+    raw?: unknown;
+}
+/**
+ * A ledger of payments keyed by the gateway payment id. Apps record a payment
+ * as `pending` on `createPayment` and let the webhook flip it to `paid`/`failed`
+ * — no more hand-rolling this per app. A memory implementation ships here; back
+ * it with your database in production (a `Payment` table keyed by `id`).
+ */
+interface PaymentStore {
+    /** Insert a pending payment. Idempotent: a no-op if the id already exists. */
+    create(payment: NewPayment): Promise<void>;
+    /** Apply a terminal status; upserts if the payment wasn't recorded first. */
+    setStatus(id: string, status: PaymentRecordStatus, patch?: {
+        amount?: number;
+        raw?: unknown;
+    }): Promise<void>;
+    get(id: string): Promise<PaymentRecord | undefined>;
+}
+/** In-memory `PaymentStore` — per-process; swap for a durable one in production. */
+declare class MemoryPaymentStore implements PaymentStore {
+    private readonly records;
+    create(payment: NewPayment): Promise<void>;
+    setStatus(id: string, status: PaymentRecordStatus, patch?: {
+        amount?: number;
+        raw?: unknown;
+    }): Promise<void>;
+    get(id: string): Promise<PaymentRecord | undefined>;
+}
+/** Result of applying a `PaymentEvent` to the ledger. */
+interface PaymentApplyResult {
+    /** false = this event id was already processed (deduped) — you did nothing. */
+    fresh: boolean;
+    record?: PaymentRecord;
+}
+interface PaymentLedgerOptions {
+    /** Where payments are stored. Default: in-memory. */
+    store?: PaymentStore;
+    /**
+     * Webhook-id dedupe store. Default: in-memory. Share one durable store (e.g.
+     * Redis) across the app so a retried callback is applied exactly once.
+     */
+    webhooks?: WebhookStore;
+}
+/**
+ * Ties a `PaymentStore` to webhook idempotency so a retried callback is applied
+ * once. Record a payment on create, then feed every verified `PaymentEvent`
+ * through `apply` — it dedupes by `event.id` and updates the ledger.
+ *
+ * ```ts
+ * const ledger = new PaymentLedger()
+ * const inst = await gateway.createPayment(req)
+ * await ledger.created(inst, req)              // pending
+ * // in the webhook route:
+ * const event = gateway.verifyWebhook(raw, sig)
+ * if (event) {
+ *   const { fresh, record } = await ledger.apply(event)
+ *   if (fresh && record?.status === 'paid') activate(record.billableId!)
+ * }
+ * ```
+ */
+declare class PaymentLedger {
+    private readonly store;
+    private readonly webhooks;
+    constructor(options?: PaymentLedgerOptions);
+    /** Record a just-created payment as pending. Call after `createPayment`. */
+    created(instruction: PaymentInstruction, request: PaymentRequest): Promise<void>;
+    /**
+     * Apply a verified `PaymentEvent` idempotently. Dedupes by `event.id`; on a
+     * fresh event, flips the ledger record to paid/failed. If persisting fails the
+     * dedupe claim is released so the gateway's retry can reprocess.
+     *
+     * `onFresh` runs **inside the idempotency claim**, after the ledger is
+     * updated — use it for domain side effects (activate a subscription, mark a
+     * booking paid) that must apply exactly once with the payment. If it throws,
+     * the claim is released so the whole thing reprocesses on the gateway's retry.
+     */
+    apply(event: PaymentEvent, onFresh?: (record: PaymentRecord | undefined, event: PaymentEvent) => Promise<void> | void): Promise<PaymentApplyResult>;
+    get(id: string): Promise<PaymentRecord | undefined>;
+}
+
+/**
+ * Recurring billing for gateways with **no card-on-file** (ProxyPay, AppyPay,
+ * Multicaixa/EMIS): model a subscription as **one payment reference per period**.
+ * Each period you issue a fresh reference; when the webhook confirms it, the
+ * subscription's paid-through date is extended by one interval.
+ *
+ * Drive it with a scheduler: periodically call `due()` and `issueNext()` for the
+ * ones returned, and feed every verified `PaymentEvent` through `handleEvent()`.
+ */
+type RecurringInterval = 'monthly' | 'yearly';
+type RecurringStatus = 'pending' | 'active' | 'past_due' | 'canceled';
+interface RecurringSubscription {
+    /** The customer/tenant this subscription bills. One per billableId. */
+    billableId: string;
+    plan: string;
+    /** Price per period, in the currency's major unit. */
+    amount: number;
+    interval: RecurringInterval;
+    status: RecurringStatus;
+    /** Active until this instant (epoch ms). Undefined before the first payment. */
+    paidThrough?: number;
+    /** The outstanding (unpaid) payment id awaiting confirmation, if any. */
+    pendingPaymentId?: string;
+    /** Kept for gateways that need it each period (e.g. phone for Express push). */
+    customer?: PaymentRequest['customer'];
+    createdAt: number;
+    updatedAt: number;
+}
+interface RecurringStore {
+    save(sub: RecurringSubscription): Promise<void>;
+    get(billableId: string): Promise<RecurringSubscription | undefined>;
+    list(): Promise<RecurringSubscription[]>;
+}
+/** In-memory `RecurringStore` — swap for a durable one in production. */
+declare class MemoryRecurringStore implements RecurringStore {
+    private readonly subs;
+    save(sub: RecurringSubscription): Promise<void>;
+    get(billableId: string): Promise<RecurringSubscription | undefined>;
+    list(): Promise<RecurringSubscription[]>;
+}
+/** Add one billing interval to an epoch-ms instant (calendar-aware). */
+declare function addInterval(ms: number, interval: RecurringInterval): number;
+interface RecurringBillingOptions {
+    /** Payment driver (ProxyPay / AppyPay / …). */
+    gateway: PaymentGateway;
+    /** Ledger for payment records + webhook idempotency. Default: in-memory. */
+    ledger?: PaymentLedger;
+    /** Where subscriptions live. Default: in-memory. */
+    store?: RecurringStore;
+    /** Days before period end that a subscription becomes `due()`. Default 5. */
+    leadDays?: number;
+    /** ISO 4217 currency passed to the gateway (defaults to the gateway's own). */
+    currency?: string;
+}
+interface SubscribeInput {
+    billableId: string;
+    plan: string;
+    amount: number;
+    interval: RecurringInterval;
+    customer?: PaymentRequest['customer'];
+    /** Extra fields passed to the gateway and echoed on the webhook. */
+    metadata?: Record<string, string>;
+}
+interface HandleEventResult {
+    /** false = the event was a duplicate (already applied) — nothing changed. */
+    applied: boolean;
+    subscription?: RecurringSubscription;
+}
+/**
+ * Coordinates reference-per-period recurring billing over a `PaymentGateway`.
+ * Stateful pieces are pluggable (`store`, `ledger`) so you can back them with a
+ * database; the defaults are in-memory.
+ */
+declare class RecurringReferenceBilling {
+    private readonly gateway;
+    private readonly ledger;
+    private readonly store;
+    private readonly leadMs;
+    private readonly currency;
+    constructor(options: RecurringBillingOptions);
+    get(billableId: string): Promise<RecurringSubscription | undefined>;
+    /** Start a subscription and issue the first period's reference. */
+    subscribe(input: SubscribeInput): Promise<{
+        subscription: RecurringSubscription;
+        instruction: PaymentInstruction;
+    }>;
+    /**
+     * Issue the next period's reference for a subscription (call for the ones
+     * `due()` returns, or to re-collect after a lapse). Replaces any outstanding
+     * reference as the one now awaited.
+     */
+    issueNext(billableId: string, metadata?: Record<string, string>): Promise<PaymentInstruction>;
+    private issueFor;
+    /**
+     * Feed a verified `PaymentEvent`. Applies it once (via the ledger's
+     * idempotency): on success for the outstanding reference, extends
+     * `paidThrough` by one interval and marks the subscription active; on failure,
+     * marks it `past_due`.
+     */
+    handleEvent(event: PaymentEvent): Promise<HandleEventResult>;
+    /**
+     * Subscriptions that need their next reference issued now: not canceled,
+     * nothing outstanding, and within `leadDays` of the paid-through date (or
+     * never paid). Run this on a schedule and call `issueNext()` for each.
+     */
+    due(now?: number): Promise<RecurringSubscription[]>;
+    cancel(billableId: string): Promise<void>;
+}
 
 declare class StripeRequestError extends BasaltError {
     readonly httpStatus: number;
@@ -562,4 +770,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, MemorySubscriptionStore, MemoryUsageStore, MemoryWebhookStore, type Meter, NotSubscribedError, type PaymentEvent, type PaymentGateway, type PaymentInstruction, type PaymentRequest, type PlanDefinition, type Plans, type PortalInput, QuotaExceededError, type RedisLike, RedisUsageStore, type RedisUsageStoreOptions, type RedisWebhookClient, RedisWebhookStore, type RedisWebhookStoreOptions, SUBSCRIPTIONS, StripeBillingGateway, type StripeGatewayOptions, StripeRequestError, type SubscriptionRecord, type SubscriptionStatus, type SubscriptionStore, Subscriptions, type SubscriptionsOptions, type SubscriptionsPluginOptions, type SwapInput, UnknownPlanError, type UsageConsumeResult, type UsageStore, type WebhookEvent, WebhookInvalidError, type WebhookStore, 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 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 };

package/dist/index.js

@@ -208,6 +208,216 @@ var FakePaymentGateway = class {
     return JSON.parse(rawBody);
   }
 };
+var MemoryPaymentStore = class {
+  records = /* @__PURE__ */ new Map();
+  async create(payment) {
+    if (this.records.has(payment.id)) return;
+    const now = Date.now();
+    this.records.set(payment.id, {
+      id: payment.id,
+      status: "pending",
+      amount: payment.amount,
+      ...payment.billableId ? { billableId: payment.billableId } : {},
+      ...payment.reference ? { reference: payment.reference } : {},
+      createdAt: now,
+      updatedAt: now,
+      ...payment.raw !== void 0 ? { raw: payment.raw } : {}
+    });
+  }
+  async setStatus(id, status, patch = {}) {
+    const now = Date.now();
+    const rec = this.records.get(id) ?? {
+      id,
+      status,
+      amount: patch.amount ?? 0,
+      createdAt: now,
+      updatedAt: now
+    };
+    rec.status = status;
+    rec.updatedAt = now;
+    if (patch.amount != null) rec.amount = patch.amount;
+    if (patch.raw !== void 0) rec.raw = patch.raw;
+    this.records.set(id, rec);
+  }
+  async get(id) {
+    return this.records.get(id);
+  }
+};
+var PaymentLedger = class {
+  store;
+  webhooks;
+  constructor(options = {}) {
+    this.store = options.store ?? new MemoryPaymentStore();
+    this.webhooks = options.webhooks ?? new MemoryWebhookStore();
+  }
+  /** Record a just-created payment as pending. Call after `createPayment`. */
+  async created(instruction, request) {
+    await this.store.create({
+      id: instruction.id,
+      amount: request.amount,
+      ...request.billableId ? { billableId: request.billableId } : {},
+      ...request.reference ? { reference: request.reference } : {},
+      ...instruction.raw !== void 0 ? { raw: instruction.raw } : {}
+    });
+  }
+  /**
+   * Apply a verified `PaymentEvent` idempotently. Dedupes by `event.id`; on a
+   * fresh event, flips the ledger record to paid/failed. If persisting fails the
+   * dedupe claim is released so the gateway's retry can reprocess.
+   *
+   * `onFresh` runs **inside the idempotency claim**, after the ledger is
+   * updated — use it for domain side effects (activate a subscription, mark a
+   * booking paid) that must apply exactly once with the payment. If it throws,
+   * the claim is released so the whole thing reprocesses on the gateway's retry.
+   */
+  async apply(event, onFresh) {
+    const fresh = await this.webhooks.markProcessed(event.id);
+    if (!fresh) return { fresh: false };
+    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);
+      if (onFresh) await onFresh(record, event);
+      return { fresh: true, ...record ? { record } : {} };
+    } catch (error) {
+      await this.webhooks.release(event.id);
+      throw error;
+    }
+  }
+  get(id) {
+    return this.store.get(id);
+  }
+};
+
+// src/recurring.ts
+var MemoryRecurringStore = class {
+  subs = /* @__PURE__ */ new Map();
+  async save(sub) {
+    this.subs.set(sub.billableId, sub);
+  }
+  async get(billableId) {
+    return this.subs.get(billableId);
+  }
+  async list() {
+    return [...this.subs.values()];
+  }
+};
+function addInterval(ms, interval) {
+  const d = new Date(ms);
+  if (interval === "yearly") d.setFullYear(d.getFullYear() + 1);
+  else d.setMonth(d.getMonth() + 1);
+  return d.getTime();
+}
+var RecurringReferenceBilling = class {
+  gateway;
+  ledger;
+  store;
+  leadMs;
+  currency;
+  constructor(options) {
+    this.gateway = options.gateway;
+    this.ledger = options.ledger ?? new PaymentLedger();
+    this.store = options.store ?? new MemoryRecurringStore();
+    this.leadMs = (options.leadDays ?? 5) * 864e5;
+    this.currency = options.currency;
+  }
+  get(billableId) {
+    return this.store.get(billableId);
+  }
+  /** Start a subscription and issue the first period's reference. */
+  async subscribe(input) {
+    const now = Date.now();
+    const subscription = {
+      billableId: input.billableId,
+      plan: input.plan,
+      amount: input.amount,
+      interval: input.interval,
+      status: "pending",
+      ...input.customer ? { customer: input.customer } : {},
+      createdAt: now,
+      updatedAt: now
+    };
+    const instruction = await this.issueFor(subscription, input.metadata);
+    return { subscription, instruction };
+  }
+  /**
+   * Issue the next period's reference for a subscription (call for the ones
+   * `due()` returns, or to re-collect after a lapse). Replaces any outstanding
+   * reference as the one now awaited.
+   */
+  async issueNext(billableId, metadata) {
+    const sub = await this.store.get(billableId);
+    if (!sub) throw new Error(`no recurring subscription for ${billableId}`);
+    if (sub.status === "canceled") throw new Error(`subscription ${billableId} is canceled`);
+    return this.issueFor(sub, metadata);
+  }
+  async issueFor(sub, metadata) {
+    const reference = `${sub.billableId}:${sub.plan}:${Date.now()}`;
+    const request = {
+      billableId: sub.billableId,
+      amount: sub.amount,
+      reference,
+      ...this.currency ? { currency: this.currency } : {},
+      ...sub.customer ? { customer: sub.customer } : {},
+      metadata: { recurring: "1", plan: sub.plan, interval: sub.interval, ...metadata }
+    };
+    const instruction = await this.gateway.createPayment(request);
+    await this.ledger.created(instruction, request);
+    sub.pendingPaymentId = instruction.id;
+    sub.updatedAt = Date.now();
+    await this.store.save(sub);
+    return instruction;
+  }
+  /**
+   * Feed a verified `PaymentEvent`. Applies it once (via the ledger's
+   * idempotency): on success for the outstanding reference, extends
+   * `paidThrough` by one interval and marks the subscription active; on failure,
+   * marks it `past_due`.
+   */
+  async handleEvent(event) {
+    let subscription;
+    const { fresh } = await this.ledger.apply(event, async (record) => {
+      const billableId = event.billableId ?? record?.billableId;
+      if (!billableId) return;
+      const sub = await this.store.get(billableId);
+      if (!sub || event.paymentId !== sub.pendingPaymentId) return;
+      if (event.type === "payment.succeeded") {
+        const base = sub.paidThrough && sub.paidThrough > Date.now() ? sub.paidThrough : Date.now();
+        sub.paidThrough = addInterval(base, sub.interval);
+        sub.status = "active";
+        delete sub.pendingPaymentId;
+      } else {
+        sub.status = "past_due";
+      }
+      sub.updatedAt = Date.now();
+      await this.store.save(sub);
+      subscription = sub;
+    });
+    return { applied: fresh, ...subscription ? { subscription } : {} };
+  }
+  /**
+   * Subscriptions that need their next reference issued now: not canceled,
+   * nothing outstanding, and within `leadDays` of the paid-through date (or
+   * never paid). Run this on a schedule and call `issueNext()` for each.
+   */
+  async due(now = Date.now()) {
+    const subs = await this.store.list();
+    return subs.filter(
+      (s) => s.status !== "canceled" && !s.pendingPaymentId && (s.paidThrough == null || s.paidThrough - now <= this.leadMs)
+    );
+  }
+  async cancel(billableId) {
+    const sub = await this.store.get(billableId);
+    if (!sub) return;
+    sub.status = "canceled";
+    delete sub.pendingPaymentId;
+    sub.updatedAt = Date.now();
+    await this.store.save(sub);
+  }
+};
 
 // src/drivers/stripe.ts
 import { createHmac, timingSafeEqual } from "crypto";
@@ -711,11 +921,15 @@ export {
   FakePaymentGateway,
   FeatureUnavailableError,
   GatewayUnsupportedError,
+  MemoryPaymentStore,
+  MemoryRecurringStore,
   MemorySubscriptionStore,
   MemoryUsageStore,
   MemoryWebhookStore,
   NotSubscribedError,
+  PaymentLedger,
   QuotaExceededError,
+  RecurringReferenceBilling,
   RedisUsageStore,
   RedisWebhookStore,
   SUBSCRIPTIONS,
@@ -724,6 +938,7 @@ export {
   Subscriptions,
   UnknownPlanError,
   WebhookInvalidError,
+  addInterval,
   billingRoutes,
   billingWebhookRoute,
   definePlans,

package/package.json

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