@classytic/revenue 1.0.6 → 1.1.3

package/dist/utils/index.d.mts

@@ -0,0 +1,428 @@
+import { B as TransactionDocument, E as ProratedAmountParams, F as SplitInfo, L as SplitRule, R as SubscriptionDocument, T as PeriodRangeResult, U as TransactionTypeOptions, c as FieldUpdateValidationResult, d as Logger, i as CommissionInfo, m as MonetizationTypeValue, o as DurationResult, w as PeriodRangeParams, z as SubscriptionEntity } from "../index-Dsp7H5Wb.mjs";
+import { a as createCircuitBreaker, i as RetryConfig, l as Result, n as CircuitBreakerConfig, o as retry, r as CircuitState, t as CircuitBreaker } from "../retry-HHCOXYdn.mjs";
+import { i as toSmallestUnit, n as MoneyValue, r as fromSmallestUnit, t as Money } from "../money-DPG8AtJ8.mjs";
+import { n as TaxConfig, r as TaxType, t as TaxCalculation } from "../tax-BoCt5cEd.mjs";
+
+//#region src/shared/utils/calculators/commission.d.ts
+/**
+ * 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;
+//#endregion
+//#region src/shared/utils/calculators/tax.d.ts
+/**
+ * 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;
+};
+//#endregion
+//#region src/shared/utils/calculators/commission-split.d.ts
+/**
+ * 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[];
+//#endregion
+//#region src/shared/utils/resilience/idempotency.d.ts
+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;
+//#endregion
+//#region src/shared/utils/validators/category-resolver.d.ts
+/**
+ * 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;
+//#endregion
+//#region src/utils/transaction-type.d.ts
+/**
+ * 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;
+//#endregion
+//#region src/utils/logger.d.ts
+/**
+ * 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;
+//#endregion
+//#region src/utils/subscription/period.d.ts
+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;
+//#endregion
+//#region src/utils/subscription/actions.d.ts
+/**
+ * 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;
+//#endregion
+export { CircuitBreaker, CircuitBreakerConfig, CircuitState, type DurationUnit, EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION, IdempotencyManager, MANUAL_TRANSACTION_CREATE_FIELDS, MANUAL_TRANSACTION_UPDATE_FIELDS, Money, MoneyValue, PROTECTED_MONETIZATION_FIELDS, RetryConfig, TRANSACTION_MANAGEMENT_TYPE, TransactionManagementType, addDuration, calculateCommission, calculateOrganizationPayout, calculatePeriodRange, calculateProratedAmount, calculateSplits, calculateTax, canCancelSubscription, canPauseSubscription, canRenewSubscription, canResumeSubscription, canSelfVerify, createCircuitBreaker, createIdempotencyManager, fromSmallestUnit, getAllowedUpdateFields, getTaxType, getTransactionType, isManualTransaction, isMonetizationTransaction, isSubscriptionActive, logger, logger as loggerDefault, resolveCategory, resolveIntervalToDuration, retry, reverseCommission, reverseSplits, reverseTax, setLogger, toSmallestUnit, validateFieldUpdate };