@classytic/revenue 1.0.2 → 1.1.2

package/dist/utils/index.d.ts

@@ -1,24 +1,498 @@
-export { O as DurationUnit, E as EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION, h as IdempotencyConfig, c as IdempotencyError, I as IdempotencyManager, e as IdempotencyRecord, g as IdempotencyStore, z as MANUAL_TRANSACTION_CREATE_FIELDS, A as MANUAL_TRANSACTION_UPDATE_FIELDS, b as MemoryIdempotencyStore, M as Money, a as MoneyValue, P as PROTECTED_MONETIZATION_FIELDS, T as TRANSACTION_MANAGEMENT_TYPE, N as TransactionManagementType, B as addDuration, i as calculateCommission, n as calculateCommissionWithSplits, k as calculateOrganizationPayout, C as calculatePeriodRange, D as calculateProratedAmount, j as calculateSplits, J as canCancelSubscription, K as canPauseSubscription, H as canRenewSubscription, L as canResumeSubscription, y as canSelfVerify, d as createIdempotencyManager, f as fromSmallestUnit, w as getAllowedUpdateFields, v as getTransactionType, p as isCategoryValid, u as isManualTransaction, q as isMonetizationTransaction, G as isSubscriptionActive, l as logger, l as loggerDefault, o as resolveCategory, F as resolveIntervalToDuration, r as reverseCommission, m as reverseSplits, s as setLogger, t as toSmallestUnit, x as validateFieldUpdate } from '../actions-CwG-b7fR.js';
-export { C as CircuitBreaker, w as CircuitBreakerConfig, q as CircuitOpenError, v as CircuitState, x as RetryConfig, n as RetryExhaustedError, y as RetryState, k as calculateDelay, p as createCircuitBreaker, l as isRetryableError, s as resilientExecute, r as retry, j as retryWithResult } from '../retry-80lBCmSe.js';
-import { z as HooksRegistry, L as Logger } from '../index-ChVD3P9k.js';
+import { C as CommissionInfo, c as SplitRule, a as SplitInfo, d as MonetizationTypeValue, T as TransactionDocument, e as TransactionTypeOptions, F as FieldUpdateValidationResult, L as Logger, f as PeriodRangeParams, g as PeriodRangeResult, h as ProratedAmountParams, D as DurationResult, S as SubscriptionDocument, i as SubscriptionEntity } from '../index-cLJBLUvx.js';
+import { T as TaxConfig, a as TaxCalculation, b as TaxType } from '../tax-CV8A0sxl.js';
+export { M as Money, a as MoneyValue, f as fromSmallestUnit, t as toSmallestUnit } from '../money-widWVD7r.js';
+import { R as Result } from '../retry-D4hFUwVk.js';
+export { C as CircuitBreaker, l as CircuitBreakerConfig, n as CircuitState, k as RetryConfig, j as createCircuitBreaker, r as retry } from '../retry-D4hFUwVk.js';
 import 'mongoose';
+import '@classytic/shared-types';
 
 /**
- * Hook Utilities
+ * Commission Calculation Utility
  * @classytic/revenue
  *
- * Fire-and-forget hook execution - never blocks main flow
+ * Handles platform commission calculation with gateway fee deduction
  */
 
 /**
- * Trigger hooks asynchronously without waiting
- * Errors are logged but never thrown
+ * Build commission object for transaction
  *
- * @param hooks - Hooks object
- * @param event - Event name
- * @param data - Event data
- * @param logger - Logger instance
+ * @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 triggerHook(hooks: HooksRegistry, event: string, data: unknown, logger: Logger): void;
+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;
+
+/**
+ * Tax Utilities
+ * @classytic/revenue
+ *
+ * Tax calculation utilities
+ * Philosophy: Apps provide rates, library does math (like Stripe)
+ */
+
+/**
+ * Calculate tax for a transaction
+ *
+ * Handles both tax-inclusive and tax-exclusive pricing:
+ * - Tax-exclusive: Customer pays baseAmount + tax
+ * - Tax-inclusive: Customer pays totalAmount (which includes tax)
+ *
+ * @param amount - Transaction amount (in smallest currency unit, e.g., cents)
+ * @param category - Transaction category (for exemption check)
+ * @param config - Tax configuration from app
+ * @returns Tax calculation result
+ *
+ * @example
+ * ```typescript
+ * // Tax-exclusive pricing (customer pays base + tax)
+ * const result = calculateTax(10000, 'subscription', {
+ *   isRegistered: true,
+ *   defaultRate: 0.15,
+ *   pricesIncludeTax: false,
+ * });
+ * // result = {
+ * //   isApplicable: true,
+ * //   rate: 0.15,
+ * //   baseAmount: 10000,
+ * //   taxAmount: 1500,
+ * //   totalAmount: 11500,
+ * //   pricesIncludeTax: false
+ * // }
+ *
+ * // Tax-inclusive pricing (price already includes tax)
+ * const result2 = calculateTax(11500, 'subscription', {
+ *   isRegistered: true,
+ *   defaultRate: 0.15,
+ *   pricesIncludeTax: true,
+ * });
+ * // result2 = {
+ * //   isApplicable: true,
+ * //   rate: 0.15,
+ * //   baseAmount: 10000,
+ * //   taxAmount: 1500,
+ * //   totalAmount: 11500,
+ * //   pricesIncludeTax: true
+ * // }
+ * ```
+ */
+declare function calculateTax(amount: number, category: string, config: TaxConfig | null): TaxCalculation;
+/**
+ * Get tax type based on transaction flow
+ *
+ * - Inflow transactions → tax is "collected" (you collect from customer)
+ * - Outflow transactions → tax is "paid" (you pay to supplier)
+ * - Exempt categories → "exempt"
+ *
+ * @param transactionFlow - 'inflow' or 'outflow'
+ * @param category - Transaction category
+ * @param exemptCategories - List of exempt categories
+ * @returns Tax type
+ *
+ * @example
+ * ```typescript
+ * getTaxType('inflow', 'subscription', []) // 'collected'
+ * getTaxType('outflow', 'refund', []) // 'paid'
+ * getTaxType('inflow', 'education', ['education']) // 'exempt'
+ * ```
+ */
+declare function getTaxType(transactionFlow: 'inflow' | 'outflow', category: string, exemptCategories?: string[]): TaxType;
+/**
+ * Reverse tax calculation for refunds
+ * When refunding a transaction, tax must be reversed proportionally
+ *
+ * @param originalTax - Tax from original transaction
+ * @param originalAmount - Original transaction amount
+ * @param refundAmount - Amount being refunded
+ * @returns Reversed tax calculation
+ *
+ * @example
+ * ```typescript
+ * // Original: $100 + $15 tax = $115
+ * const originalTax = {
+ *   isApplicable: true,
+ *   rate: 0.15,
+ *   baseAmount: 10000,
+ *   taxAmount: 1500,
+ *   totalAmount: 11500,
+ *   type: 'collected',
+ * };
+ *
+ * // Refund 50% ($57.50)
+ * const refundTax = reverseTax(originalTax, 11500, 5750);
+ * // refundTax = {
+ * //   isApplicable: true,
+ * //   rate: 0.15,
+ * //   baseAmount: 5000,
+ * //   taxAmount: 750,
+ * //   totalAmount: 5750,
+ * //   type: 'paid',  // Reversed!
+ * // }
+ * ```
+ */
+declare function reverseTax(originalTax: TaxCalculation & {
+    type?: TaxType;
+}, originalAmount: number, refundAmount: number): TaxCalculation & {
+    type?: TaxType;
+};
+
+/**
+ * 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[];
+
+/**
+ * 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;
+}
+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
+     * Uses deterministic JSON serialization and simple hash function
+     */
+    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>;
+    /**
+     * Destroy the idempotency manager and cleanup resources
+     * Call this when shutting down to prevent memory leaks
+     */
+    destroy(): void;
+}
+/**
+ * Create idempotency manager
+ */
+declare function createIdempotencyManager(config?: IdempotencyConfig): IdempotencyManager;
+
+/**
+ * Category Resolver Utility
+ * @classytic/revenue
+ *
+ * Resolves transaction category based on 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;
+
+/**
+ * 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", "sourceModel", "sourceId"];
+/**
+ * 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;
+
+/**
+ * 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 { triggerHook };
+export { type DurationUnit, EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION, IdempotencyManager, MANUAL_TRANSACTION_CREATE_FIELDS, MANUAL_TRANSACTION_UPDATE_FIELDS, PROTECTED_MONETIZATION_FIELDS, TRANSACTION_MANAGEMENT_TYPE, type TransactionManagementType, addDuration, calculateCommission, calculateOrganizationPayout, calculatePeriodRange, calculateProratedAmount, calculateSplits, calculateTax, canCancelSubscription, canPauseSubscription, canRenewSubscription, canResumeSubscription, canSelfVerify, createIdempotencyManager, getAllowedUpdateFields, getTaxType, getTransactionType, isManualTransaction, isMonetizationTransaction, isSubscriptionActive, logger, logger as loggerDefault, resolveCategory, resolveIntervalToDuration, reverseCommission, reverseSplits, reverseTax, setLogger, validateFieldUpdate };