@fonderie/billing 5.3.1 → 6.0.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 import { IFonderieModule, IFonderieApp, IFonderieContext, Middleware } from '@fonderie/core';
 import { IStoreAdapter } from '@fonderie/store';
-import { I as IBillingConfig, a as IBillingProvider, b as IResolvedPrice, c as IBillingEvent, d as ICounterBackend, e as IBillingPlan } from './index-DjAGcrSi.cjs';
-export { B as BillingMessageKey, f as IBillingNotificationsConfig, g as IBillingPlanDefaults, h as IBillingPlanPrice, i as IBillingPricingConfig, M as MESSAGE_KEYS, R as RateLimitBackendConfig, r as requirePlan, w as withBilling } from './index-DjAGcrSi.cjs';
-import { SubscriberType, IPolicyStatus, IPlanFeature, IPlan, ISubscription, IUsageRecord } from './types.cjs';
-export { BILLING_INTERVAL, BillingInterval, IBillingContext, LimitStatus, PolicyEntry, SubscriptionStatus } from './types.cjs';
+import { I as IBillingConfig, a as IBillingProvider, b as IResolvedPrice, c as IBillingEvent, d as IBillingPlan, e as ICounterBackend } from './index-Ca4pXx07.cjs';
+export { B as BillingMessageKey, f as IBillingCreditPack, g as IBillingNotificationsConfig, h as IBillingPlanDefaults, i as IBillingPlanPrice, j as IBillingPlanWallet, k as IBillingPricingConfig, l as IBillingWalletConfig, m as INormalizedPayment, M as MESSAGE_KEYS, R as RateLimitBackendConfig, r as requirePlan, w as withBilling } from './index-Ca4pXx07.cjs';
+import { SubscriberType, IWalletRate, IWalletLedgerEntry, WalletLedgerType, IWalletBalance, IPolicyStatus, IWalletContext, IPlanFeature, IPlan, ISubscription } from './types.cjs';
+export { BILLING_INTERVAL, BILLING_INTERVALS, BillingInterval, IBillingContext, LimitStatus, PolicyEntry, SubscriptionStatus, WALLET_LEDGER_TYPES, isBillingInterval } from './types.cjs';
 import { z } from 'zod';
 
 declare class BillingModule implements IFonderieModule {
@@ -40,6 +40,20 @@ declare class StripeProvider implements 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: {
@@ -63,9 +77,92 @@ declare class StripeProvider implements IBillingProvider {
     }): Promise<IBillingEvent>;
 }
 
+declare class InsufficientFundsError extends Error {
+    readonly available: bigint;
+    readonly required: bigint;
+    readonly currency: string;
+    constructor(available: bigint, required: bigint, currency: string);
+}
+declare class DuplicateTransactionError extends Error {
+    readonly idempotencyKey: string;
+    constructor(idempotencyKey: string);
+}
+
+interface IWalletSubscriber {
+    subscriberType: SubscriberType;
+    subscriberId: string;
+    currency: string;
+}
+interface IWalletMutationResult {
+    balance: bigint;
+    duplicate: boolean;
+}
+declare function creditWallet(opts: IWalletSubscriber & {
+    amount: bigint;
+    idempotencyKey: string;
+    type?: WalletLedgerType;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    providerTxId?: string;
+}, store: IStoreAdapter): Promise<IWalletMutationResult>;
+declare function debitWallet(opts: IWalletSubscriber & {
+    amount: bigint;
+    idempotencyKey: string;
+    type?: WalletLedgerType;
+    overdraftLimit?: bigint;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}, store: IStoreAdapter): Promise<IWalletMutationResult>;
+declare function getWalletBalance(sub: IWalletSubscriber, store: IStoreAdapter): Promise<IWalletBalance>;
+interface IWalletLedgerPage {
+    entries: IWalletLedgerEntry[];
+    nextCursor: string | null;
+}
+declare function encodeLedgerCursor(createdAt: string, id: string): string;
+declare function decodeLedgerCursor(cursor: string): {
+    createdAt: string;
+    id: string;
+} | null;
+declare function getWalletLedger(opts: IWalletSubscriber & {
+    limit?: number;
+    cursor?: {
+        createdAt: string;
+        id: string;
+    };
+}, store: IStoreAdapter): Promise<IWalletLedgerPage>;
+interface IResolvedPlanWallet {
+    currency: string;
+    precision: number;
+    overdraftLimit: bigint;
+    grantAmount: bigint | null;
+    grantPeriod: 'month' | 'week' | 'day';
+    rates: Record<string, IWalletRate>;
+}
+declare function resolvePlanWallet(plan: IBillingPlan, config: IBillingConfig): IResolvedPlanWallet | null;
+declare function currentGrantPeriod(period: 'month' | 'week' | 'day', now?: Date): string;
+interface IGrantResult {
+    granted: boolean;
+    balance: bigint | null;
+}
+declare function ensurePeriodicGrant(opts: IWalletSubscriber & {
+    amount: bigint;
+    period: string;
+    description?: string;
+}, store: IStoreAdapter): Promise<IGrantResult>;
+
 declare function hasFeature(ctx: IFonderieContext, key: string): boolean;
 declare function getPlanLimit(ctx: IFonderieContext, key: string): number | null;
 declare function getLimitStatus(ctx: IFonderieContext, key: string): IPolicyStatus | null;
+declare function getWalletStatus(ctx: IFonderieContext): IWalletContext | null;
+declare function getWalletRate(ctx: IFonderieContext, metric: string): bigint | null;
+declare function requireWalletBalance(metric: string): Middleware;
+declare function debitWalletForMetric(ctx: IFonderieContext, metric: string, opts: {
+    idempotencyKey: string;
+    quantity?: number;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}, store: IStoreAdapter): Promise<IWalletMutationResult | null>;
+declare function insufficientCreditsResponse(err: InsufficientFundsError, metric?: string): Response;
 declare function requireFeature(key: string): Middleware;
 
 declare class MemoryCounterBackend implements ICounterBackend {
@@ -112,17 +209,26 @@ interface ISubscriptionDTO {
     trialEndsAt: string | null;
     createdAt: string;
 }
-interface IUsageRecordDTO {
-    id: string;
-    subscriberType: SubscriberType;
-    subscriberId: string;
-    metric: string;
-    quantity: number;
-    recordedAt: string;
-}
 declare function toPlanDTO(plan: IPlan): IPlanDTO;
 declare function toSubscriptionDTO(sub: ISubscription): ISubscriptionDTO;
-declare function toUsageRecordDTO(record: IUsageRecord): IUsageRecordDTO;
+interface IWalletDTO {
+    balance: string;
+    currency: string;
+    precision: number;
+}
+interface IWalletTransactionDTO {
+    id: string;
+    type: WalletLedgerType;
+    amount: string;
+    balanceAfter: string;
+    currency: string;
+    description: string | null;
+    providerTxId: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+declare function toWalletDTO(balance: bigint, currency: string, precision: number): IWalletDTO;
+declare function toWalletTransactionDTO(entry: IWalletLedgerEntry): IWalletTransactionDTO;
 
 declare function recordUsage(opts: {
     subscriberType: SubscriberType;
@@ -191,13 +297,29 @@ declare const recordUsageSchema: z.ZodObject<{
     metric: z.ZodString;
     quantity: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+declare const walletCheckoutSchema: z.ZodObject<{
+    packId: z.ZodString;
+}, z.core.$strip>;
+declare const grantWalletSchema: z.ZodObject<{
+    subscriberType: z.ZodEnum<{
+        user: "user";
+        workspace: "workspace";
+    }>;
+    subscriberId: z.ZodString;
+    amount: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<bigint, string | number>>;
+    currency: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    description: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strip>;
 
 declare const schemas_checkoutSchema: typeof checkoutSchema;
 declare const schemas_createPlanSchema: typeof createPlanSchema;
+declare const schemas_grantWalletSchema: typeof grantWalletSchema;
 declare const schemas_recordUsageSchema: typeof recordUsageSchema;
 declare const schemas_updatePlanSchema: typeof updatePlanSchema;
+declare const schemas_walletCheckoutSchema: typeof walletCheckoutSchema;
 declare namespace schemas {
-  export { schemas_checkoutSchema as checkoutSchema, schemas_createPlanSchema as createPlanSchema, schemas_recordUsageSchema as recordUsageSchema, schemas_updatePlanSchema as updatePlanSchema };
+  export { schemas_checkoutSchema as checkoutSchema, schemas_createPlanSchema as createPlanSchema, schemas_grantWalletSchema as grantWalletSchema, schemas_recordUsageSchema as recordUsageSchema, schemas_updatePlanSchema as updatePlanSchema, schemas_walletCheckoutSchema as walletCheckoutSchema };
 }
 
-export { BillingModule, DBCounterBackend, IBillingConfig, IBillingEvent, IBillingPlan, IBillingProvider, ICounterBackend, IPlan, type IPlanDTO, IPolicyStatus, IResolvedPrice, ISubscription, type ISubscriptionDTO, IUsageRecord, type IUsageRecordDTO, MemoryCounterBackend, StripeProvider, createPlan, deletePlan, getDBPlans, getLimitStatus, getPlanById, getPlanByName, getPlanLimit, getPlans, getSubscription, getUsage, hasFeature, recordUsage, requireFeature, schemas, toPlanDTO, toSubscriptionDTO, toUsageRecordDTO, updatePlan };
+export { BillingModule, DBCounterBackend, DuplicateTransactionError, IBillingConfig, IBillingEvent, IBillingPlan, IBillingProvider, ICounterBackend, type IGrantResult, IPlan, type IPlanDTO, IPolicyStatus, type IResolvedPlanWallet, IResolvedPrice, ISubscription, type ISubscriptionDTO, IWalletBalance, IWalletContext, type IWalletDTO, IWalletLedgerEntry, type IWalletLedgerPage, type IWalletMutationResult, IWalletRate, type IWalletSubscriber, type IWalletTransactionDTO, InsufficientFundsError, MemoryCounterBackend, StripeProvider, WalletLedgerType, createPlan, creditWallet, currentGrantPeriod, debitWallet, debitWalletForMetric, decodeLedgerCursor, deletePlan, encodeLedgerCursor, ensurePeriodicGrant, getDBPlans, getLimitStatus, getPlanById, getPlanByName, getPlanLimit, getPlans, getSubscription, getUsage, getWalletBalance, getWalletLedger, getWalletRate, getWalletStatus, hasFeature, insufficientCreditsResponse, recordUsage, requireFeature, requireWalletBalance, resolvePlanWallet, schemas, toPlanDTO, toSubscriptionDTO, toWalletDTO, toWalletTransactionDTO, updatePlan };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { IFonderieModule, IFonderieApp, IFonderieContext, Middleware } from '@fonderie/core';
 import { IStoreAdapter } from '@fonderie/store';
-import { I as IBillingConfig, a as IBillingProvider, b as IResolvedPrice, c as IBillingEvent, d as ICounterBackend, e as IBillingPlan } from './index-Byy5mBE4.js';
-export { B as BillingMessageKey, f as IBillingNotificationsConfig, g as IBillingPlanDefaults, h as IBillingPlanPrice, i as IBillingPricingConfig, M as MESSAGE_KEYS, R as RateLimitBackendConfig, r as requirePlan, w as withBilling } from './index-Byy5mBE4.js';
-import { SubscriberType, IPolicyStatus, IPlanFeature, IPlan, ISubscription, IUsageRecord } from './types.js';
-export { BILLING_INTERVAL, BillingInterval, IBillingContext, LimitStatus, PolicyEntry, SubscriptionStatus } from './types.js';
+import { I as IBillingConfig, a as IBillingProvider, b as IResolvedPrice, c as IBillingEvent, d as IBillingPlan, e as ICounterBackend } from './index-BdNYDuhk.js';
+export { B as BillingMessageKey, f as IBillingCreditPack, g as IBillingNotificationsConfig, h as IBillingPlanDefaults, i as IBillingPlanPrice, j as IBillingPlanWallet, k as IBillingPricingConfig, l as IBillingWalletConfig, m as INormalizedPayment, M as MESSAGE_KEYS, R as RateLimitBackendConfig, r as requirePlan, w as withBilling } from './index-BdNYDuhk.js';
+import { SubscriberType, IWalletRate, IWalletLedgerEntry, WalletLedgerType, IWalletBalance, IPolicyStatus, IWalletContext, IPlanFeature, IPlan, ISubscription } from './types.js';
+export { BILLING_INTERVAL, BILLING_INTERVALS, BillingInterval, IBillingContext, LimitStatus, PolicyEntry, SubscriptionStatus, WALLET_LEDGER_TYPES, isBillingInterval } from './types.js';
 import { z } from 'zod';
 
 declare class BillingModule implements IFonderieModule {
@@ -40,6 +40,20 @@ declare class StripeProvider implements 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: {
@@ -63,9 +77,92 @@ declare class StripeProvider implements IBillingProvider {
     }): Promise<IBillingEvent>;
 }
 
+declare class InsufficientFundsError extends Error {
+    readonly available: bigint;
+    readonly required: bigint;
+    readonly currency: string;
+    constructor(available: bigint, required: bigint, currency: string);
+}
+declare class DuplicateTransactionError extends Error {
+    readonly idempotencyKey: string;
+    constructor(idempotencyKey: string);
+}
+
+interface IWalletSubscriber {
+    subscriberType: SubscriberType;
+    subscriberId: string;
+    currency: string;
+}
+interface IWalletMutationResult {
+    balance: bigint;
+    duplicate: boolean;
+}
+declare function creditWallet(opts: IWalletSubscriber & {
+    amount: bigint;
+    idempotencyKey: string;
+    type?: WalletLedgerType;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    providerTxId?: string;
+}, store: IStoreAdapter): Promise<IWalletMutationResult>;
+declare function debitWallet(opts: IWalletSubscriber & {
+    amount: bigint;
+    idempotencyKey: string;
+    type?: WalletLedgerType;
+    overdraftLimit?: bigint;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}, store: IStoreAdapter): Promise<IWalletMutationResult>;
+declare function getWalletBalance(sub: IWalletSubscriber, store: IStoreAdapter): Promise<IWalletBalance>;
+interface IWalletLedgerPage {
+    entries: IWalletLedgerEntry[];
+    nextCursor: string | null;
+}
+declare function encodeLedgerCursor(createdAt: string, id: string): string;
+declare function decodeLedgerCursor(cursor: string): {
+    createdAt: string;
+    id: string;
+} | null;
+declare function getWalletLedger(opts: IWalletSubscriber & {
+    limit?: number;
+    cursor?: {
+        createdAt: string;
+        id: string;
+    };
+}, store: IStoreAdapter): Promise<IWalletLedgerPage>;
+interface IResolvedPlanWallet {
+    currency: string;
+    precision: number;
+    overdraftLimit: bigint;
+    grantAmount: bigint | null;
+    grantPeriod: 'month' | 'week' | 'day';
+    rates: Record<string, IWalletRate>;
+}
+declare function resolvePlanWallet(plan: IBillingPlan, config: IBillingConfig): IResolvedPlanWallet | null;
+declare function currentGrantPeriod(period: 'month' | 'week' | 'day', now?: Date): string;
+interface IGrantResult {
+    granted: boolean;
+    balance: bigint | null;
+}
+declare function ensurePeriodicGrant(opts: IWalletSubscriber & {
+    amount: bigint;
+    period: string;
+    description?: string;
+}, store: IStoreAdapter): Promise<IGrantResult>;
+
 declare function hasFeature(ctx: IFonderieContext, key: string): boolean;
 declare function getPlanLimit(ctx: IFonderieContext, key: string): number | null;
 declare function getLimitStatus(ctx: IFonderieContext, key: string): IPolicyStatus | null;
+declare function getWalletStatus(ctx: IFonderieContext): IWalletContext | null;
+declare function getWalletRate(ctx: IFonderieContext, metric: string): bigint | null;
+declare function requireWalletBalance(metric: string): Middleware;
+declare function debitWalletForMetric(ctx: IFonderieContext, metric: string, opts: {
+    idempotencyKey: string;
+    quantity?: number;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}, store: IStoreAdapter): Promise<IWalletMutationResult | null>;
+declare function insufficientCreditsResponse(err: InsufficientFundsError, metric?: string): Response;
 declare function requireFeature(key: string): Middleware;
 
 declare class MemoryCounterBackend implements ICounterBackend {
@@ -112,17 +209,26 @@ interface ISubscriptionDTO {
     trialEndsAt: string | null;
     createdAt: string;
 }
-interface IUsageRecordDTO {
-    id: string;
-    subscriberType: SubscriberType;
-    subscriberId: string;
-    metric: string;
-    quantity: number;
-    recordedAt: string;
-}
 declare function toPlanDTO(plan: IPlan): IPlanDTO;
 declare function toSubscriptionDTO(sub: ISubscription): ISubscriptionDTO;
-declare function toUsageRecordDTO(record: IUsageRecord): IUsageRecordDTO;
+interface IWalletDTO {
+    balance: string;
+    currency: string;
+    precision: number;
+}
+interface IWalletTransactionDTO {
+    id: string;
+    type: WalletLedgerType;
+    amount: string;
+    balanceAfter: string;
+    currency: string;
+    description: string | null;
+    providerTxId: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+declare function toWalletDTO(balance: bigint, currency: string, precision: number): IWalletDTO;
+declare function toWalletTransactionDTO(entry: IWalletLedgerEntry): IWalletTransactionDTO;
 
 declare function recordUsage(opts: {
     subscriberType: SubscriberType;
@@ -191,13 +297,29 @@ declare const recordUsageSchema: z.ZodObject<{
     metric: z.ZodString;
     quantity: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+declare const walletCheckoutSchema: z.ZodObject<{
+    packId: z.ZodString;
+}, z.core.$strip>;
+declare const grantWalletSchema: z.ZodObject<{
+    subscriberType: z.ZodEnum<{
+        user: "user";
+        workspace: "workspace";
+    }>;
+    subscriberId: z.ZodString;
+    amount: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<bigint, string | number>>;
+    currency: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    description: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strip>;
 
 declare const schemas_checkoutSchema: typeof checkoutSchema;
 declare const schemas_createPlanSchema: typeof createPlanSchema;
+declare const schemas_grantWalletSchema: typeof grantWalletSchema;
 declare const schemas_recordUsageSchema: typeof recordUsageSchema;
 declare const schemas_updatePlanSchema: typeof updatePlanSchema;
+declare const schemas_walletCheckoutSchema: typeof walletCheckoutSchema;
 declare namespace schemas {
-  export { schemas_checkoutSchema as checkoutSchema, schemas_createPlanSchema as createPlanSchema, schemas_recordUsageSchema as recordUsageSchema, schemas_updatePlanSchema as updatePlanSchema };
+  export { schemas_checkoutSchema as checkoutSchema, schemas_createPlanSchema as createPlanSchema, schemas_grantWalletSchema as grantWalletSchema, schemas_recordUsageSchema as recordUsageSchema, schemas_updatePlanSchema as updatePlanSchema, schemas_walletCheckoutSchema as walletCheckoutSchema };
 }
 
-export { BillingModule, DBCounterBackend, IBillingConfig, IBillingEvent, IBillingPlan, IBillingProvider, ICounterBackend, IPlan, type IPlanDTO, IPolicyStatus, IResolvedPrice, ISubscription, type ISubscriptionDTO, IUsageRecord, type IUsageRecordDTO, MemoryCounterBackend, StripeProvider, createPlan, deletePlan, getDBPlans, getLimitStatus, getPlanById, getPlanByName, getPlanLimit, getPlans, getSubscription, getUsage, hasFeature, recordUsage, requireFeature, schemas, toPlanDTO, toSubscriptionDTO, toUsageRecordDTO, updatePlan };
+export { BillingModule, DBCounterBackend, DuplicateTransactionError, IBillingConfig, IBillingEvent, IBillingPlan, IBillingProvider, ICounterBackend, type IGrantResult, IPlan, type IPlanDTO, IPolicyStatus, type IResolvedPlanWallet, IResolvedPrice, ISubscription, type ISubscriptionDTO, IWalletBalance, IWalletContext, type IWalletDTO, IWalletLedgerEntry, type IWalletLedgerPage, type IWalletMutationResult, IWalletRate, type IWalletSubscriber, type IWalletTransactionDTO, InsufficientFundsError, MemoryCounterBackend, StripeProvider, WalletLedgerType, createPlan, creditWallet, currentGrantPeriod, debitWallet, debitWalletForMetric, decodeLedgerCursor, deletePlan, encodeLedgerCursor, ensurePeriodicGrant, getDBPlans, getLimitStatus, getPlanById, getPlanByName, getPlanLimit, getPlans, getSubscription, getUsage, getWalletBalance, getWalletLedger, getWalletRate, getWalletStatus, hasFeature, insufficientCreditsResponse, recordUsage, requireFeature, requireWalletBalance, resolvePlanWallet, schemas, toPlanDTO, toSubscriptionDTO, toWalletDTO, toWalletTransactionDTO, updatePlan };