@classytic/revenue 0.2.4 → 1.0.0

package/dist/actions-CwG-b7fR.d.ts

@@ -0,0 +1,519 @@
+import { R as Result } from './retry-80lBCmSe.js';
+import { d as TransactionDocument, ac as TransactionTypeOptions, ad as FieldUpdateValidationResult, L as Logger, C as CommissionInfo, o as SplitRule, p as SplitInfo, ab as CommissionWithSplitsOptions, h as MonetizationTypeValue, a6 as PeriodRangeParams, a7 as PeriodRangeResult, a8 as ProratedAmountParams, a9 as DurationResult, e as SubscriptionDocument, aa as SubscriptionEntity } from './index-ChVD3P9k.js';
+
+/**
+ * Money Utility - Integer-safe currency handling
+ * @classytic/revenue
+ *
+ * Never use floating point for money!
+ * All amounts stored as smallest unit (cents, paisa, etc.)
+ *
+ * Inspired by: Stripe, Dinero.js, tc39/proposal-decimal
+ */
+interface MoneyValue {
+    /** Amount in smallest currency unit (cents, paisa, etc.) */
+    readonly amount: number;
+    /** ISO 4217 currency code */
+    readonly currency: string;
+}
+/**
+ * Money class - immutable money representation
+ */
+declare class Money implements MoneyValue {
+    readonly amount: number;
+    readonly currency: string;
+    private constructor();
+    /**
+     * Create money from smallest unit (cents, paisa)
+     * @example Money.cents(1999, 'USD') // $19.99
+     */
+    static cents(amount: number, currency?: string): Money;
+    /**
+     * Create money from major unit (dollars, taka)
+     * @example Money.of(19.99, 'USD') // $19.99 (stored as 1999 cents)
+     */
+    static of(amount: number, currency?: string): Money;
+    /**
+     * Create zero money
+     */
+    static zero(currency?: string): Money;
+    static usd(cents: number): Money;
+    static eur(cents: number): Money;
+    static gbp(pence: number): Money;
+    static bdt(paisa: number): Money;
+    static inr(paisa: number): Money;
+    static jpy(yen: number): Money;
+    /**
+     * Add two money values (must be same currency)
+     */
+    add(other: Money): Money;
+    /**
+     * Subtract money (must be same currency)
+     */
+    subtract(other: Money): Money;
+    /**
+     * Multiply by a factor (rounds to nearest integer)
+     */
+    multiply(factor: number): Money;
+    /**
+     * Divide by a divisor (rounds to nearest integer)
+     */
+    divide(divisor: number): Money;
+    /**
+     * Calculate percentage
+     * @example money.percentage(10) // 10% of money
+     */
+    percentage(percent: number): Money;
+    /**
+     * Allocate money among recipients (handles rounding)
+     * @example Money.usd(100).allocate([1, 1, 1]) // [34, 33, 33] cents
+     */
+    allocate(ratios: number[]): Money[];
+    /**
+     * Split equally among n recipients
+     */
+    split(parts: number): Money[];
+    isZero(): boolean;
+    isPositive(): boolean;
+    isNegative(): boolean;
+    equals(other: Money): boolean;
+    greaterThan(other: Money): boolean;
+    lessThan(other: Money): boolean;
+    greaterThanOrEqual(other: Money): boolean;
+    lessThanOrEqual(other: Money): boolean;
+    /**
+     * Get amount in major unit (dollars, taka)
+     */
+    toUnit(): number;
+    /**
+     * Format for display
+     * @example Money.usd(1999).format() // "$19.99"
+     */
+    format(locale?: string): string;
+    /**
+     * Format without currency symbol
+     */
+    formatAmount(locale?: string): string;
+    /**
+     * Convert to JSON-serializable object
+     */
+    toJSON(): MoneyValue;
+    /**
+     * Create from JSON
+     */
+    static fromJSON(json: MoneyValue): Money;
+    toString(): string;
+    private assertSameCurrency;
+}
+/**
+ * Helper functions for legacy compatibility
+ */
+declare function toSmallestUnit(amount: number, currency?: string): number;
+declare function fromSmallestUnit(amount: number, currency?: string): number;
+
+/**
+ * Idempotency Utilities
+ * @classytic/revenue
+ *
+ * Prevent duplicate operations with idempotency keys
+ * Inspired by: Stripe, Amazon SQS deduplication
+ */
+
+interface IdempotencyRecord<T = unknown> {
+    /** Idempotency key */
+    key: string;
+    /** Operation result (if completed) */
+    result?: T;
+    /** Operation status */
+    status: 'pending' | 'completed' | 'failed';
+    /** Creation timestamp */
+    createdAt: Date;
+    /** Completion timestamp */
+    completedAt?: Date;
+    /** Request hash for validation */
+    requestHash: string;
+    /** TTL - when record expires */
+    expiresAt: Date;
+}
+interface IdempotencyStore {
+    /** Get record by key */
+    get<T>(key: string): Promise<IdempotencyRecord<T> | null>;
+    /** Set or update record */
+    set<T>(key: string, record: IdempotencyRecord<T>): Promise<void>;
+    /** Delete record */
+    delete(key: string): Promise<void>;
+    /** Check if key exists */
+    exists(key: string): Promise<boolean>;
+}
+interface IdempotencyConfig {
+    /** TTL in milliseconds (default: 24 hours) */
+    ttl?: number;
+    /** Custom store implementation */
+    store?: IdempotencyStore;
+    /** Key prefix */
+    prefix?: string;
+}
+/**
+ * Simple in-memory idempotency store
+ * Use Redis/database store in production
+ */
+declare class MemoryIdempotencyStore implements IdempotencyStore {
+    private records;
+    private cleanupInterval;
+    constructor(cleanupIntervalMs?: number);
+    get<T>(key: string): Promise<IdempotencyRecord<T> | null>;
+    set<T>(key: string, record: IdempotencyRecord<T>): Promise<void>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    private cleanup;
+    destroy(): void;
+}
+declare class IdempotencyError extends Error {
+    readonly code: 'DUPLICATE_REQUEST' | 'REQUEST_IN_PROGRESS' | 'REQUEST_MISMATCH';
+    constructor(message: string, code: 'DUPLICATE_REQUEST' | 'REQUEST_IN_PROGRESS' | 'REQUEST_MISMATCH');
+}
+/**
+ * Idempotency manager
+ */
+declare class IdempotencyManager {
+    private store;
+    private ttl;
+    private prefix;
+    constructor(config?: IdempotencyConfig);
+    /**
+     * Generate a unique idempotency key
+     */
+    generateKey(): string;
+    /**
+     * Hash request parameters for validation
+     */
+    private hashRequest;
+    /**
+     * Execute operation with idempotency protection
+     */
+    execute<T>(key: string, params: unknown, operation: () => Promise<T>): Promise<Result<T, IdempotencyError>>;
+    /**
+     * Check if operation with key was already completed
+     */
+    wasCompleted(key: string): Promise<boolean>;
+    /**
+     * Get cached result for key
+     */
+    getCached<T>(key: string): Promise<T | null>;
+    /**
+     * Invalidate a key (force re-execution on next call)
+     */
+    invalidate(key: string): Promise<void>;
+}
+/**
+ * Create idempotency manager
+ */
+declare function createIdempotencyManager(config?: IdempotencyConfig): IdempotencyManager;
+
+/**
+ * Transaction Type Detection & Classification
+ *
+ * Distinguishes between:
+ * - Monetization-managed transactions (library-controlled, strict rules)
+ * - Manual admin transactions (flexible, admin-controlled)
+ *
+ * @module @classytic/revenue/utils/transaction-type
+ */
+
+/**
+ * Transaction types with different protection rules
+ */
+declare const TRANSACTION_MANAGEMENT_TYPE: {
+    readonly MONETIZATION: "monetization";
+    readonly MANUAL: "manual";
+};
+type TransactionManagementType = typeof TRANSACTION_MANAGEMENT_TYPE[keyof typeof TRANSACTION_MANAGEMENT_TYPE];
+/**
+ * Check if transaction is monetization-managed
+ *
+ * Monetization-managed means:
+ * - Created through subscription/purchase flows via the library
+ * - Status controlled by payment webhooks/verification
+ * - Amount/commission calculated by library
+ * - Protected fields: status, amount, commission, gateway, verifiedAt, verifiedBy
+ *
+ * @param transaction - Transaction document or data
+ * @param options - Options
+ */
+declare function isMonetizationTransaction(transaction: Partial<TransactionDocument>, options?: TransactionTypeOptions): boolean;
+/**
+ * Check if transaction is manual admin transaction
+ *
+ * Manual transactions:
+ * - Created directly by admins for operational expenses/income
+ * - Can be self-verified by admins
+ * - More flexible updates allowed
+ * - No commission/gateway complexity
+ *
+ * @param transaction - Transaction document or data
+ * @param options - Options (same as isMonetizationTransaction)
+ */
+declare function isManualTransaction(transaction: Partial<TransactionDocument>, options?: TransactionTypeOptions): boolean;
+/**
+ * Get transaction type
+ *
+ * @param transaction - Transaction document or data
+ * @param options - Options (same as isMonetizationTransaction)
+ */
+declare function getTransactionType(transaction: Partial<TransactionDocument>, options?: TransactionTypeOptions): TransactionManagementType;
+/**
+ * Protected fields for monetization transactions
+ * These fields cannot be updated directly by admins
+ */
+declare const PROTECTED_MONETIZATION_FIELDS: readonly ["status", "amount", "platformCommission", "netAmount", "verifiedAt", "verifiedBy", "gateway", "webhook", "metadata.commission", "metadata.gateway", "type", "category", "referenceModel", "referenceId"];
+/**
+ * Editable fields for monetization transactions (before verification)
+ * These fields can be updated by frontend/customer before payment is verified
+ */
+declare const EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION: readonly ["reference", "paymentDetails", "notes"];
+/**
+ * Allowed fields for manual transaction creation
+ */
+declare const MANUAL_TRANSACTION_CREATE_FIELDS: readonly ["organizationId", "type", "category", "amount", "method", "reference", "paymentDetails", "notes", "date", "description"];
+/**
+ * Allowed fields for manual transaction updates
+ */
+declare const MANUAL_TRANSACTION_UPDATE_FIELDS: readonly ["amount", "method", "reference", "paymentDetails", "notes", "date", "description"];
+/**
+ * Get allowed update fields based on transaction type and status
+ *
+ * @param transaction - Transaction document
+ * @param options - Options for transaction type detection
+ */
+declare function getAllowedUpdateFields(transaction: Partial<TransactionDocument>, options?: TransactionTypeOptions): readonly string[];
+/**
+ * Validate if field update is allowed
+ *
+ * @param transaction - Transaction document
+ * @param fieldName - Field being updated
+ * @param options - Options for transaction type detection
+ */
+declare function validateFieldUpdate(transaction: Partial<TransactionDocument>, fieldName: string, options?: TransactionTypeOptions): FieldUpdateValidationResult;
+/**
+ * Check if transaction can be self-verified by admin
+ *
+ * @param transaction - Transaction document
+ * @param options - Options for transaction type detection
+ */
+declare function canSelfVerify(transaction: Partial<TransactionDocument>, options?: TransactionTypeOptions): boolean;
+
+/**
+ * Logger Abstraction for Monetization Library
+ *
+ * Defaults to console for standalone usage
+ * Can be overridden with custom logger (pino, winston, etc)
+ *
+ * Usage:
+ * ```typescript
+ * import { setLogger } from '@classytic/revenue';
+ *
+ * // Optional: Use your own logger
+ * setLogger(myPinoLogger);
+ * ```
+ */
+
+/**
+ * Set custom logger implementation
+ * @param customLogger - Logger instance with info, warn, error, debug methods
+ */
+declare function setLogger(customLogger: Logger): void;
+/**
+ * Logger proxy - delegates to current logger implementation
+ */
+declare const logger: Logger;
+
+/**
+ * Commission Calculation Utility
+ * @classytic/revenue
+ *
+ * Handles platform commission calculation with gateway fee deduction
+ */
+
+/**
+ * Build commission object for transaction
+ *
+ * @param amount - Transaction amount
+ * @param commissionRate - Commission rate (0 to 1, e.g., 0.10 for 10%)
+ * @param gatewayFeeRate - Gateway fee rate (0 to 1, e.g., 0.018 for 1.8%)
+ * @returns Commission object or null
+ */
+declare function calculateCommission(amount: number, commissionRate: number, gatewayFeeRate?: number): CommissionInfo | null;
+/**
+ * Reverse commission on refund (proportional)
+ *
+ * @param originalCommission - Original commission object
+ * @param originalAmount - Original transaction amount
+ * @param refundAmount - Amount being refunded
+ * @returns Reversed commission or null
+ */
+declare function reverseCommission(originalCommission: CommissionInfo | null | undefined, originalAmount: number, refundAmount: number): CommissionInfo | null;
+
+/**
+ * Commission Split Utilities
+ * @classytic/revenue
+ *
+ * Multi-party commission split calculation for affiliate/referral systems
+ */
+
+/**
+ * Calculate multi-party commission splits
+ *
+ * @param amount - Transaction amount
+ * @param splitRules - Split configuration
+ * @param gatewayFeeRate - Gateway fee rate (optional)
+ * @returns Split objects
+ *
+ * @example
+ * calculateSplits(1000, [
+ *   { type: 'platform_commission', recipientId: 'platform', recipientType: 'platform', rate: 0.10 },
+ *   { type: 'affiliate_commission', recipientId: 'affiliate-123', recipientType: 'user', rate: 0.02 },
+ * ], 0.018);
+ *
+ * Returns:
+ * [
+ *   { type: 'platform_commission', recipientId: 'platform', grossAmount: 100, gatewayFeeAmount: 18, netAmount: 82, ... },
+ *   { type: 'affiliate_commission', recipientId: 'affiliate-123', grossAmount: 20, gatewayFeeAmount: 0, netAmount: 20, ... },
+ * ]
+ */
+declare function calculateSplits(amount: number, splitRules?: SplitRule[], gatewayFeeRate?: number): SplitInfo[];
+/**
+ * Calculate organization payout after splits
+ *
+ * @param amount - Total transaction amount
+ * @param splits - Calculated splits
+ * @returns Amount organization receives
+ */
+declare function calculateOrganizationPayout(amount: number, splits?: SplitInfo[]): number;
+/**
+ * Reverse splits proportionally on refund
+ *
+ * @param originalSplits - Original split objects
+ * @param originalAmount - Original transaction amount
+ * @param refundAmount - Amount being refunded
+ * @returns Reversed splits
+ */
+declare function reverseSplits(originalSplits: SplitInfo[] | undefined | null, originalAmount: number, refundAmount: number): SplitInfo[];
+/**
+ * Build commission object with splits support
+ * Backward compatible with existing calculateCommission
+ *
+ * @param amount - Transaction amount
+ * @param commissionRate - Platform commission rate
+ * @param gatewayFeeRate - Gateway fee rate
+ * @param options - Additional options
+ * @returns Commission with optional splits
+ */
+declare function calculateCommissionWithSplits(amount: number, commissionRate: number, gatewayFeeRate?: number, options?: CommissionWithSplitsOptions): CommissionInfo | null;
+
+/**
+ * Category Resolver Utility
+ * @classytic/revenue
+ *
+ * Resolves transaction category based on referenceModel and categoryMappings
+ */
+
+/**
+ * Resolve category for a transaction based on entity and monetizationType
+ *
+ * Resolution Logic:
+ * 1. If categoryMappings[entity] exists → use it
+ * 2. Otherwise → fall back to default library category
+ *
+ * @param entity - The logical entity/identifier (e.g., 'Order', 'PlatformSubscription', 'Membership')
+ *                 NOTE: This is NOT a database model name - it's just a logical identifier
+ * @param monetizationType - The monetization type ('subscription', 'purchase', 'free')
+ * @param categoryMappings - User-defined category mappings from config
+ * @returns Category name for the transaction
+ *
+ * @example
+ * // With mapping defined
+ * resolveCategory('Order', 'subscription', { Order: 'order_subscription' })
+ * // Returns: 'order_subscription'
+ *
+ * @example
+ * // Without mapping, falls back to library default
+ * resolveCategory('Order', 'subscription', {})
+ * // Returns: 'subscription'
+ *
+ * @example
+ * // Different entities with different mappings
+ * const mappings = {
+ *   Order: 'order_subscription',
+ *   PlatformSubscription: 'platform_subscription',
+ *   TenantUpgrade: 'tenant_upgrade',
+ *   Membership: 'gym_membership',
+ *   Enrollment: 'course_enrollment',
+ * };
+ * resolveCategory('PlatformSubscription', 'subscription', mappings)
+ * // Returns: 'platform_subscription'
+ */
+declare function resolveCategory(entity: string | null | undefined, monetizationType: MonetizationTypeValue, categoryMappings?: Record<string, string>): string;
+/**
+ * Validate that a category is defined in user's Transaction model enum
+ * This is informational - actual validation happens at Mongoose schema level
+ *
+ * @param category - Category to validate
+ * @param allowedCategories - List of allowed categories
+ * @returns Whether category is valid
+ */
+declare function isCategoryValid(category: string, allowedCategories?: string[]): boolean;
+
+/**
+ * Subscription Period Utilities
+ * @classytic/revenue/utils/subscription
+ *
+ * Universal period calculation, proration, and date utilities
+ */
+
+type DurationUnit = 'days' | 'day' | 'weeks' | 'week' | 'months' | 'month' | 'years' | 'year';
+/**
+ * Add duration to date
+ */
+declare function addDuration(startDate: Date, duration: number, unit?: DurationUnit): Date;
+/**
+ * Calculate subscription period start/end dates
+ */
+declare function calculatePeriodRange(params: PeriodRangeParams): PeriodRangeResult;
+/**
+ * Calculate prorated refund amount for unused period
+ */
+declare function calculateProratedAmount(params: ProratedAmountParams): number;
+/**
+ * Convert interval + count to duration/unit
+ */
+declare function resolveIntervalToDuration(interval?: string, intervalCount?: number): DurationResult;
+
+/**
+ * Subscription Action Utilities
+ * @classytic/revenue/utils/subscription
+ *
+ * Eligibility checks for subscription actions
+ */
+
+/**
+ * Check if subscription is active
+ */
+declare function isSubscriptionActive(subscription: Partial<SubscriptionDocument> | null | undefined): boolean;
+/**
+ * Check if can renew
+ */
+declare function canRenewSubscription(entity: SubscriptionEntity | null | undefined): boolean;
+/**
+ * Check if can cancel
+ */
+declare function canCancelSubscription(entity: SubscriptionEntity | null | undefined): boolean;
+/**
+ * Check if can pause
+ */
+declare function canPauseSubscription(entity: SubscriptionEntity | null | undefined): boolean;
+/**
+ * Check if can resume
+ */
+declare function canResumeSubscription(entity: SubscriptionEntity | null | undefined): boolean;
+
+export { MANUAL_TRANSACTION_UPDATE_FIELDS as A, addDuration as B, calculatePeriodRange as C, calculateProratedAmount as D, EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION as E, resolveIntervalToDuration as F, isSubscriptionActive as G, canRenewSubscription as H, IdempotencyManager as I, canCancelSubscription as J, canPauseSubscription as K, canResumeSubscription as L, Money as M, type TransactionManagementType as N, type DurationUnit as O, PROTECTED_MONETIZATION_FIELDS as P, TRANSACTION_MANAGEMENT_TYPE as T, type MoneyValue as a, MemoryIdempotencyStore as b, IdempotencyError as c, createIdempotencyManager as d, type IdempotencyRecord as e, fromSmallestUnit as f, type IdempotencyStore as g, type IdempotencyConfig as h, calculateCommission as i, calculateSplits as j, calculateOrganizationPayout as k, logger as l, reverseSplits as m, calculateCommissionWithSplits as n, resolveCategory as o, isCategoryValid as p, isMonetizationTransaction as q, reverseCommission as r, setLogger as s, toSmallestUnit as t, isManualTransaction as u, getTransactionType as v, getAllowedUpdateFields as w, validateFieldUpdate as x, canSelfVerify as y, MANUAL_TRANSACTION_CREATE_FIELDS as z };