@fonderie/billing 5.3.0 → 6.0.0

package/README.md

@@ -30,6 +30,40 @@ import { requirePlan, requireFeature, hasFeature, getPlanLimit } from '@fonderie
 `StripeProvider` handles checkout and webhook events; usage counters run
 on `MemoryCounterBackend` or `DBCounterBackend`.
 
+## Stored-value wallet (opt-in)
+
+Setting `wallet` on the billing config turns on a ledger-backed credit
+wallet: subscribers hold a balance (`bigint`, smallest currency unit), buy
+config-defined credit packs through one-time provider checkout, and plans
+price metered actions in credits.
+
+```ts
+new BillingModule(store, {
+  provider: new StripeProvider(secretKey),
+  successUrl, cancelUrl, webhookSecret,
+  wallet: {
+    currency: 'USD',
+    webhookSecret: process.env.STRIPE_PAYMENT_WEBHOOK_SECRET, // separate endpoint
+    creditPacks: [{ id: 'small', name: 'Small pack', credits: 5000n, priceAmount: 499n }],
+  },
+  plans: [{
+    name: 'payg',
+    wallet: {
+      grantAmount: 50n, // auto-granted lazily, once per period
+      rates: { 'sms:send': { cost: 75n, unit: 'msg' } },
+    },
+  }],
+});
+```
+
+Every mutation goes through the append-only ledger with an idempotency
+key — the balance table is a cache, debits are atomic (`FOR UPDATE` plus a
+conditional-update floor), and webhook replays are no-ops. In routes:
+`requireWalletBalance('sms:send')` gates on affordability; inside the unit
+of work, `debitWalletForMetric(ctx, 'sms:send', { idempotencyKey: taskId }, store)`
+charges the plan rate exactly once. Wallet amounts cross HTTP as digit
+strings (`IWalletDTO`).
+
 ## Why this exists
 
 You've shipped this plumbing before — auth, teams, billing, messaging —

package/brain/outcomes.md

@@ -22,6 +22,20 @@ created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
 -- CONSTRAINT fonderie_billing_notifications_unique UNIQUE (subscriber_type, subscriber_id, policy_key, notification, window_key)
 ```
 
+### `fonderie_credit_packs`
+
+```sql
+id                       TEXT PRIMARY KEY
+name                     TEXT NOT NULL
+currency                 TEXT NOT NULL DEFAULT 'USD'
+credits                  BIGINT NOT NULL
+price_amount             BIGINT NOT NULL
+price_id                 TEXT
+active                   BOOLEAN NOT NULL DEFAULT true
+metadata                 JSONB NOT NULL DEFAULT '{}'
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+```
+
 ### `fonderie_plans`
 
 ```sql
@@ -39,6 +53,7 @@ description              TEXT
 tier                     INT NOT NULL DEFAULT 0
 features                 JSONB NOT NULL DEFAULT '[]'
 metadata                 JSONB NOT NULL DEFAULT '{}'
+wallet                   JSONB
 ```
 
 ### `fonderie_subscriptions`
@@ -72,6 +87,52 @@ subscriber_id            UUID NOT NULL
 CONSTRAINT               fonderie_usage_records_subscriber_type_check CHECK (subscriber_type IN ('user', 'workspace'))
 ```
 
+### `fonderie_wallet_balances`
+
+```sql
+subscriber_type          TEXT NOT NULL
+subscriber_id            UUID NOT NULL
+currency                 TEXT NOT NULL DEFAULT 'USD'
+amount                   BIGINT NOT NULL DEFAULT 0
+version                  BIGINT NOT NULL DEFAULT 1
+updated_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+-- CONSTRAINT fonderie_wallet_balances_subscriber_type_check CHECK (subscriber_type IN ('user', 'workspace'))
+-- PRIMARY KEY (subscriber_type, subscriber_id, currency)
+```
+
+### `fonderie_wallet_grants`
+
+```sql
+subscriber_type          TEXT NOT NULL
+subscriber_id            UUID NOT NULL
+currency                 TEXT NOT NULL
+period                   TEXT NOT NULL
+amount                   BIGINT NOT NULL
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+-- CONSTRAINT fonderie_wallet_grants_subscriber_type_check CHECK (subscriber_type IN ('user', 'workspace'))
+-- PRIMARY KEY (subscriber_type, subscriber_id, currency, period)
+```
+
+### `fonderie_wallet_ledger`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+subscriber_type          TEXT NOT NULL
+subscriber_id            UUID NOT NULL
+currency                 TEXT NOT NULL DEFAULT 'USD'
+type                     TEXT NOT NULL
+amount                   BIGINT NOT NULL
+balance_after            BIGINT NOT NULL
+description              TEXT
+idempotency_key          TEXT NOT NULL UNIQUE
+metadata                 JSONB NOT NULL DEFAULT '{}'
+provider_tx_id           TEXT
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+-- CONSTRAINT fonderie_wallet_ledger_subscriber_type_check CHECK (subscriber_type IN ('user', 'workspace'))
+-- CONSTRAINT fonderie_wallet_ledger_type_check CHECK (type IN ('purchase', 'grant', 'usage', 'refund', 'adjustment'))
+-- CONSTRAINT fonderie_wallet_ledger_amount_nonzero_check CHECK (amount <> 0)
+```
+
 Raw SQL ships in `node_modules/@fonderie/billing/dist/migrations/sql/` — read it there if you must; never download tarballs.
 
 ## HTTP routes registered
@@ -83,9 +144,19 @@ Raw SQL ships in `node_modules/@fonderie/billing/dist/migrations/sql/` — read
 | GET | `/billing/subscription` | `requireAuth → subscription.get` |
 | POST | `/billing/usage` | `requireAuth → validate(recordUsageSchema) → usage.record` |
 | GET | `/billing/usage/:metric` | `requireAuth → usage.get` |
+| GET | `/billing/wallet` | `requireAuth → wallet.get` |
+| POST | `/billing/wallet/checkout` | `requireAuth → validate(walletCheckoutSchema) → wallet.checkout` |
+| POST | `/billing/wallet/grant` | `requireAdminToken(config.wallet.adminToken) → validate(grantWalletSchema) → wallet.grant` |
+| GET | `/billing/wallet/transactions` | `requireAuth → wallet.transactions` |
 | POST | `/billing/webhook` | `webhook.handle` |
+| POST | `/billing/webhook/payment` | `paymentWebhook.handle` |
 | GET | `/plans` | `plan.list` |
 | POST | `/plans` | `validate(createPlanSchema) → plan.create` |
 | DELETE | `/plans/:planId` | `plan.delete` |
 | GET | `/plans/:planId` | `plan.get` |
 | PUT | `/plans/:planId` | `validate(updatePlanSchema) → plan.update` |
+
+## Migration statements not replayed (verify in raw SQL)
+
+- `fonderie_plans: ALTER COLUMN monthly_amount TYPE BIGINT`
+- `fonderie_plans: ALTER COLUMN yearly_amount TYPE BIGINT`

package/brain/signatures.md

@@ -16,6 +16,10 @@ new StripeProvider(secretKey: string, webhookSecret?: string | undefined): Strip
   .name: "stripe"
   .createCustomer(opts: { email: string; subscriberType: SubscriberType; subscriberId: string; userId: string; }): Promise<{ customerId: string; }>
   .createCheckoutSession(opts: { customerId: string; priceId: string; subscriberType: SubscriberType; subscriberId: string; trialDays?: number; successUrl: string; cancelUrl: string; }): 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<...>
+  .resolvePriceById(priceId: string): Promise<IResolvedPrice | null>
+  .resolvePricesByLookupKey(lookupKeys: string[]): Promise<Map<string, IResolvedPrice>>
+  .updateSubscription(opts: { subscriptionId: string; priceId: string; }): Promise<{ status: string; currentPeriodStart: Date | null; currentPeriodEnd: Date | null; }>
   .createPortalSession(opts: { customerId: string; returnUrl: string; }): Promise<{ url: string; }>
   .constructEvent(opts: { payload: string; signature: string; secret: string; }): Promise<IBillingEvent>
 
@@ -31,6 +35,16 @@ function getLimitStatus(ctx: IFonderieContext, key: string): IPolicyStatus | nul
 
 function requireFeature(key: string): Middleware
 
+function getWalletStatus(ctx: IFonderieContext): IWalletContext | null
+
+function getWalletRate(ctx: IFonderieContext, metric: string): bigint | null
+
+function requireWalletBalance(metric: string): Middleware
+
+function debitWalletForMetric(ctx: IFonderieContext, metric: string, opts: { idempotencyKey: string; quantity?: number; description?: string; metadata?: Record<string, unknown>; }, store: IStoreAdapter): Promise<...>
+
+function insufficientCreditsResponse(err: InsufficientFundsError, metric?: string | undefined): Response
+
 const MESSAGE_KEYS: { readonly limitWarning: "billing.limit-warning"; readonly limitReached: "billing.limit-reached"; readonly limitBlocked: "billing.limit-blocked"; }
 
 interface IBillingConfig {
@@ -43,6 +57,19 @@ interface IBillingConfig {
         backend?: RateLimitBackendConfig;
     };
     notifications?: IBillingNotificationsConfig;
+    pricing?: IBillingPricingConfig;
+    wallet?: IBillingWalletConfig;
+}
+
+interface IBillingCreditPack {
+    id: string;
+    name: string;
+    credits: bigint;
+    priceAmount: bigint;
+    currency?: string;
+    priceId?: string;
+    active?: boolean;
+    metadata?: Record<string, unknown>;
 }
 
 interface IBillingPlan {
@@ -54,6 +81,7 @@ interface IBillingPlan {
     yearly?: IBillingPlanPrice;
     defaults?: IBillingPlanDefaults;
     policy?: Record<string, PolicyEntry>;
+    wallet?: IBillingPlanWallet;
     metadata?: Record<string, unknown>;
 }
 
@@ -62,6 +90,36 @@ interface IBillingPlanDefaults {
     buffer?: number;
 }
 
+interface IBillingPlanPrice {
+    lookupKey?: string;
+    priceId?: string;
+    amount?: bigint;
+}
+
+interface IBillingPlanWallet {
+    currency?: string;
+    precision?: number;
+    grantAmount?: bigint;
+    grantPeriod?: 'month' | 'week' | 'day';
+    overdraftLimit?: bigint;
+    rates?: Record<string, IWalletRate>;
+}
+
+interface IBillingPricingConfig {
+    hydration?: boolean;
+    cacheTtlMs?: number;
+    transferGraceMs?: number;
+    maxStaleMs?: number;
+}
+
+interface IBillingWalletConfig {
+    currency?: string;
+    precision?: number;
+    adminToken?: string;
+    webhookSecret?: string;
+    creditPacks?: IBillingCreditPack[];
+}
+
 type RateLimitBackendConfig = 'memory' | 'db' | ICounterBackend;
 
 interface IBillingNotificationsConfig {
@@ -84,6 +142,18 @@ interface ICounterBackend {
     get(key: string, windowMs: number | null): Promise<number>;
 }
 
+const BILLING_INTERVAL: { readonly MONTH: "month"; readonly YEAR: "year"; }
+
+const BILLING_INTERVALS: readonly ["month", "year"]
+
+function isBillingInterval(value: unknown): value is "month" | "year"
+
+const WALLET_LEDGER_TYPES: readonly ["purchase", "grant", "usage", "refund", "adjustment"]
+
+type BillingInterval = (typeof BILLING_INTERVALS)[number];
+
+type WalletLedgerType = (typeof WALLET_LEDGER_TYPES)[number];
+
 interface IBillingProvider {
     name: string;
     createCustomer(opts: {
@@ -105,6 +175,30 @@ 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: {
+        subscriptionId: string;
+        priceId: string;
+    }): Promise<{
+        status: string;
+        currentPeriodStart: Date | null;
+        currentPeriodEnd: Date | null;
+    }>;
     createPortalSession(opts: {
         customerId: string;
         returnUrl: string;
@@ -121,6 +215,27 @@ interface IBillingProvider {
 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 IResolvedPrice {
+    priceId: string;
+    lookupKey: string | null;
+    unitAmount: bigint;
+    currency: string;
+    interval: BillingInterval;
+    nickname: string | null;
+    productId: string;
+    active: boolean;
 }
 
 interface IPlan {
@@ -143,7 +258,7 @@ interface ISubscription {
     subscriberType: SubscriberType;
     subscriberId: string;
     plan: string;
-    interval: 'month' | 'year';
+    interval: BillingInterval;
     status: SubscriptionStatus;
     providerCustomerId: string | null;
     providerSubscriptionId: string | null;
@@ -154,13 +269,38 @@ interface ISubscription {
     createdAt: string;
 }
 
-interface IUsageRecord {
+interface IWalletBalance {
+    balance: bigint;
+    version: number;
+    updatedAt: string | null;
+}
+
+interface IWalletContext {
+    balance: bigint;
+    currency: string;
+    precision: number;
+    overdraftLimit: bigint;
+    rates: Record<string, IWalletRate>;
+}
+
+interface IWalletLedgerEntry {
     id: string;
     subscriberType: SubscriberType;
     subscriberId: string;
-    metric: string;
-    quantity: number;
-    recordedAt: string;
+    currency: string;
+    type: WalletLedgerType;
+    amount: bigint;
+    balanceAfter: bigint;
+    description: string | null;
+    idempotencyKey: string;
+    metadata: Record<string, unknown>;
+    providerTxId: string | null;
+    createdAt: string;
+}
+
+interface IWalletRate {
+    cost: bigint;
+    unit?: string;
 }
 
 type SubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'canceled' | 'incomplete' | 'paused';
@@ -196,6 +336,7 @@ interface IBillingContext {
     plan: string;
     active: boolean;
     statuses: Record<string, IPolicyStatus>;
+    wallet?: IWalletContext;
 }
 
 interface IPlanDTO {
@@ -211,6 +352,7 @@ interface IPlanDTO {
         yearly: number;
         currency: string;
     };
+    pricingStale?: boolean;
     features: IPlanFeature[];
     metadata: Record<string, unknown>;
 }
@@ -229,20 +371,95 @@ interface ISubscriptionDTO {
     createdAt: string;
 }
 
-interface IUsageRecordDTO {
+interface IWalletDTO {
+    balance: string;
+    currency: string;
+    precision: number;
+}
+
+interface IWalletTransactionDTO {
     id: string;
-    subscriberType: SubscriberType;
-    subscriberId: string;
-    metric: string;
-    quantity: number;
-    recordedAt: string;
+    type: WalletLedgerType;
+    amount: string;
+    balanceAfter: string;
+    currency: string;
+    description: string | null;
+    providerTxId: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
 }
 
 function toPlanDTO(plan: IPlan): IPlanDTO
 
 function toSubscriptionDTO(sub: ISubscription): ISubscriptionDTO
 
-function toUsageRecordDTO(record: IUsageRecord): IUsageRecordDTO
+function toWalletDTO(balance: bigint, currency: string, precision: number): IWalletDTO
+
+function toWalletTransactionDTO(entry: IWalletLedgerEntry): IWalletTransactionDTO
+
+function creditWallet(opts: IWalletSubscriber & { amount: bigint; idempotencyKey: string; type?: "purchase" | "grant" | "usage" | "refund" | "adjustment"; description?: string; metadata?: Record<...>; providerTxId?: string; }, store: IStoreAdapter): Promise<...>
+
+function debitWallet(opts: IWalletSubscriber & { amount: bigint; idempotencyKey: string; type?: "purchase" | "grant" | "usage" | "refund" | "adjustment"; overdraftLimit?: bigint; description?: string; metadata?: Record<...>; }, store: IStoreAdapter): Promise<...>
+
+function getWalletBalance(sub: IWalletSubscriber, store: IStoreAdapter): Promise<IWalletBalance>
+
+function getWalletLedger(opts: IWalletSubscriber & { limit?: number; cursor?: { createdAt: string; id: string; }; }, store: IStoreAdapter): Promise<IWalletLedgerPage>
+
+function ensurePeriodicGrant(opts: IWalletSubscriber & { amount: bigint; period: string; description?: string; }, store: IStoreAdapter): Promise<IGrantResult>
+
+function currentGrantPeriod(period: "month" | "week" | "day", now?: Date): string
+
+function resolvePlanWallet(plan: IBillingPlan, config: IBillingConfig): IResolvedPlanWallet | null
+
+function encodeLedgerCursor(createdAt: string, id: string): string
+
+function decodeLedgerCursor(cursor: string): { createdAt: string; id: string; } | null
+
+interface IWalletSubscriber {
+    subscriberType: SubscriberType;
+    subscriberId: string;
+    currency: string;
+}
+
+interface IWalletMutationResult {
+    balance: bigint;
+    duplicate: boolean;
+}
+
+interface IWalletLedgerPage {
+    entries: IWalletLedgerEntry[];
+    nextCursor: string | null;
+}
+
+interface IGrantResult {
+    granted: boolean;
+    balance: bigint | null;
+}
+
+interface IResolvedPlanWallet {
+    currency: string;
+    precision: number;
+    overdraftLimit: bigint;
+    grantAmount: bigint | null;
+    grantPeriod: 'month' | 'week' | 'day';
+    rates: Record<string, IWalletRate>;
+}
+
+new InsufficientFundsError(available: bigint, required: bigint, currency: string): InsufficientFundsError
+  .available: bigint
+  .required: bigint
+  .currency: string
+  .name: string
+  .message: string
+  .stack: string
+  .cause: unknown
+
+new DuplicateTransactionError(idempotencyKey: string): DuplicateTransactionError
+  .idempotencyKey: string
+  .name: string
+  .message: string
+  .stack: string
+  .cause: unknown
 
 function recordUsage(opts: { subscriberType: SubscriberType; subscriberId: string; metric: string; quantity: number; }, store: IStoreAdapter): Promise<void>
 
@@ -264,5 +481,5 @@ function deletePlan(id: string, store: IStoreAdapter): Promise<boolean>
 
 function getSubscription(subscriberType: SubscriberType, subscriberId: string, store: IStoreAdapter): Promise<ISubscription | null>
 
-namespace schemas — exports: checkoutSchema, createPlanSchema, recordUsageSchema, updatePlanSchema
+namespace schemas — exports: checkoutSchema, createPlanSchema, grantWalletSchema, recordUsageSchema, updatePlanSchema, walletCheckoutSchema
 ```

package/dist/{index-CBhthuMn.d.ts → index-BdNYDuhk.d.ts}

@@ -1,10 +1,19 @@
 import { Middleware, IFonderieContext } from '@fonderie/core';
 import { IStoreAdapter } from '@fonderie/store';
-import { SubscriberType, PolicyEntry } from './types.js';
+import { SubscriberType, BillingInterval, PolicyEntry, IWalletRate } from './types.js';
 
 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,10 +111,12 @@ interface IBillingPlanPrice {
     /** Stripe price id. Used for hydration and as a lookup_key fallback. */
     priceId?: string;
     /**
-     * @deprecated Display amount in cents. When pricing hydration is on and the
-     * price resolves from Stripe, the live amount wins; this is the fallback only.
+     * 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
@@ -99,7 +124,7 @@ interface IBillingPlanPrice {
  * See packages/billing/docs/pricing-hydration.md.
  */
 interface IBillingPricingConfig {
-    /** Kill-switch. When false (default), use the deprecated hardcoded amount/USD path. */
+    /** Kill-switch. When false (default), serve the configured amount/USD directly. */
     hydration?: boolean;
     /** Fresh-cache TTL. Default 300_000 (5m). */
     cacheTtlMs?: number;
@@ -112,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;
@@ -121,6 +168,7 @@ interface IBillingPlan {
     yearly?: IBillingPlanPrice;
     defaults?: IBillingPlanDefaults;
     policy?: Record<string, PolicyEntry>;
+    wallet?: IBillingPlanWallet;
     metadata?: Record<string, unknown>;
 }
 type RateLimitBackendConfig = 'memory' | 'db' | ICounterBackend;
@@ -128,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[];
@@ -139,6 +237,7 @@ interface IBillingConfig {
     };
     notifications?: IBillingNotificationsConfig;
     pricing?: IBillingPricingConfig;
+    wallet?: IBillingWalletConfig;
 }
 declare const MESSAGE_KEYS: {
     readonly limitWarning: "billing.limit-warning";
@@ -152,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 };