@fonderie/billing 5.3.1 → 6.0.0

package/dist/{index-DjAGcrSi.d.cts → index-Ca4pXx07.d.cts}

@@ -1,10 +1,19 @@
 import { Middleware, IFonderieContext } from '@fonderie/core';
 import { IStoreAdapter } from '@fonderie/store';
-import { SubscriberType, PolicyEntry } from './types.cjs';
+import { SubscriberType, BillingInterval, PolicyEntry, IWalletRate } from './types.cjs';
 
 interface IBillingEvent {
     type: string;
     subscription: INormalizedSubscription | null;
+    payment?: INormalizedPayment | null;
+}
+interface INormalizedPayment {
+    sessionId: string;
+    providerTxId: string | null;
+    amountTotal: bigint | null;
+    currency: string | null;
+    paymentStatus: string | null;
+    metadata: Record<string, string>;
 }
 interface INormalizedSubscription {
     subscriberType: SubscriberType;
@@ -21,14 +30,14 @@ interface INormalizedSubscription {
     currentPeriodEnd: Date;
     cancelAtPeriodEnd: boolean;
     trialEndsAt: Date | null;
-    interval: 'month' | 'year';
+    interval: BillingInterval;
 }
 interface IResolvedPrice {
     priceId: string;
     lookupKey: string | null;
-    unitAmount: number;
+    unitAmount: bigint;
     currency: string;
-    interval: 'month' | 'year';
+    interval: BillingInterval;
     nickname: string | null;
     productId: string;
     active: boolean;
@@ -54,6 +63,20 @@ interface IBillingProvider {
     }): Promise<{
         url: string;
     }>;
+    createPaymentCheckoutSession?(opts: {
+        customerId: string;
+        amount: bigint;
+        currency: string;
+        name: string;
+        quantity?: number;
+        priceId?: string;
+        metadata: Record<string, string>;
+        successUrl: string;
+        cancelUrl: string;
+    }): Promise<{
+        url: string;
+        sessionId: string;
+    }>;
     resolvePriceById(priceId: string): Promise<IResolvedPrice | null>;
     resolvePricesByLookupKey(lookupKeys: string[]): Promise<Map<string, IResolvedPrice>>;
     updateSubscription(opts: {
@@ -88,11 +111,12 @@ interface IBillingPlanPrice {
     /** Stripe price id. Used for hydration and as a lookup_key fallback. */
     priceId?: string;
     /**
-     * Display amount in cents — the seed value written to fonderie_plans and the
-     * fallback shown (flagged pricingStale) when hydration is off or Stripe is
-     * unreachable. When hydration resolves a live price, the live amount wins.
+     * Display amount in the smallest currency unit (bigint, e.g. 1999n = $19.99) —
+     * the seed value written to fonderie_plans and the fallback shown (flagged
+     * pricingStale) when hydration is off or Stripe is unreachable. When
+     * hydration resolves a live price, the live amount wins.
      */
-    amount?: number;
+    amount?: bigint;
 }
 /**
  * Read-through pricing: amount/currency come from Stripe (source of truth) rather
@@ -113,6 +137,28 @@ interface IBillingPlanDefaults {
     warnAt?: number;
     buffer?: number;
 }
+/**
+ * Per-plan wallet economics. Requires config.wallet to be set — a plan-level
+ * wallet without the global opt-in is ignored (with a boot warning).
+ */
+interface IBillingPlanWallet {
+    /** Overrides the global wallet currency for this plan's grants and rates. */
+    currency?: string;
+    /** Display precision override. */
+    precision?: number;
+    /**
+     * Credits auto-granted once per grantPeriod, applied lazily by withBilling
+     * on the subscriber's first request of the period. Only granted while the
+     * subscription is active or trialing (no new credit while payment fails).
+     */
+    grantAmount?: bigint;
+    /** Grant cadence for grantAmount. Default 'month'. */
+    grantPeriod?: 'month' | 'week' | 'day';
+    /** How far below zero rate debits may take the balance. Default 0n (block at zero). */
+    overdraftLimit?: bigint;
+    /** Per-metric unit costs, e.g. { 'sms:send': { cost: 75n, unit: 'msg' } }. */
+    rates?: Record<string, IWalletRate>;
+}
 interface IBillingPlan {
     name: string;
     description?: string;
@@ -122,6 +168,7 @@ interface IBillingPlan {
     yearly?: IBillingPlanPrice;
     defaults?: IBillingPlanDefaults;
     policy?: Record<string, PolicyEntry>;
+    wallet?: IBillingPlanWallet;
     metadata?: Record<string, unknown>;
 }
 type RateLimitBackendConfig = 'memory' | 'db' | ICounterBackend;
@@ -129,6 +176,56 @@ interface IBillingNotificationsConfig {
     warnAt?: boolean;
     softHit?: boolean;
 }
+/**
+ * A purchasable credit top-up, synced to fonderie_credit_packs at boot (same
+ * pattern as plans). Purchases go through the provider's one-time checkout;
+ * the payment webhook credits `credits` to the buyer's wallet.
+ */
+interface IBillingCreditPack {
+    /** Stable identifier used by POST /billing/wallet/checkout, e.g. 'small'. */
+    id: string;
+    name: string;
+    /** Wallet credits granted on purchase, in the smallest wallet unit. */
+    credits: bigint;
+    /** Purchase price in the provider's smallest currency unit. */
+    priceAmount: bigint;
+    /**
+     * ISO 4217 PAYMENT currency for the provider charge; defaults to the
+     * buyer's wallet currency. Credits always land in the buyer's wallet
+     * currency regardless of what the charge was priced in.
+     */
+    currency?: string;
+    /** Existing provider Price id — used instead of the ad-hoc priceAmount. */
+    priceId?: string;
+    /** Inactive packs stay in the DB but can no longer be checked out. */
+    active?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Opt-in stored-value wallet. Presence of this object activates the wallet
+ * subsystem (routes, credit packs, per-plan grants and rates); leaving it out
+ * changes nothing for existing subscription-only consumers.
+ */
+interface IBillingWalletConfig {
+    /** Default wallet currency when a plan doesn't override it. Default 'USD'. */
+    currency?: string;
+    /** Display precision — decimal places of the smallest unit. Default 2. */
+    precision?: number;
+    /**
+     * Bearer token guarding POST /billing/wallet/grant (manual support/ops
+     * grants). The route is only registered when a token is configured.
+     */
+    adminToken?: string;
+    /**
+     * Signing secret for POST /billing/webhook/payment. REQUIRED for pack
+     * purchases: the route answers 500 until it is set, and it deliberately
+     * does NOT fall back to the subscription webhook's secret — per-endpoint
+     * secrets keep a delivery captured for one endpoint from replaying
+     * against the other.
+     */
+    webhookSecret?: string;
+    creditPacks?: IBillingCreditPack[];
+}
 interface IBillingConfig {
     provider: IBillingProvider;
     plans: IBillingPlan[];
@@ -140,6 +237,7 @@ interface IBillingConfig {
     };
     notifications?: IBillingNotificationsConfig;
     pricing?: IBillingPricingConfig;
+    wallet?: IBillingWalletConfig;
 }
 declare const MESSAGE_KEYS: {
     readonly limitWarning: "billing.limit-warning";
@@ -153,4 +251,4 @@ declare function requirePlan(plans: string | string[], store: IStoreAdapter, ctx
 
 declare function withBilling(store: IStoreAdapter, config: IBillingConfig, backend: ICounterBackend): Middleware;
 
-export { type BillingMessageKey as B, type IBillingConfig as I, MESSAGE_KEYS as M, type RateLimitBackendConfig as R, type IBillingProvider as a, type IResolvedPrice as b, type IBillingEvent as c, type ICounterBackend as d, type IBillingPlan as e, type IBillingNotificationsConfig as f, type IBillingPlanDefaults as g, type IBillingPlanPrice as h, type IBillingPricingConfig as i, requirePlan as r, withBilling as w };
+export { type BillingMessageKey as B, type IBillingConfig as I, MESSAGE_KEYS as M, type RateLimitBackendConfig as R, type IBillingProvider as a, type IResolvedPrice as b, type IBillingEvent as c, type IBillingPlan as d, type ICounterBackend as e, type IBillingCreditPack as f, type IBillingNotificationsConfig as g, type IBillingPlanDefaults as h, type IBillingPlanPrice as i, type IBillingPlanWallet as j, type IBillingPricingConfig as k, type IBillingWalletConfig as l, type INormalizedPayment as m, requirePlan as r, withBilling as w };