@classytic/revenue 0.2.4 → 1.0.0

package/utils/category-resolver.js

@@ -1,74 +0,0 @@
-/**
- * Category Resolver Utility
- * @classytic/revenue
- *
- * Resolves transaction category based on referenceModel and categoryMappings
- */
-
-import { LIBRARY_CATEGORIES } from '../enums/transaction.enums.js';
-
-/**
- * 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 {String} 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 {String} monetizationType - The monetization type ('subscription', 'purchase', 'free')
- * @param {Object} categoryMappings - User-defined category mappings from config
- * @returns {String} 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'
- */
-export function resolveCategory(entity, monetizationType, categoryMappings = {}) {
-  // If user has defined a custom mapping for this entity, use it
-  if (entity && categoryMappings[entity]) {
-    return categoryMappings[entity];
-  }
-
-  // Otherwise, fall back to library default based on monetization type
-  switch (monetizationType) {
-    case 'subscription':
-      return LIBRARY_CATEGORIES.SUBSCRIPTION; // 'subscription'
-    case 'purchase':
-      return LIBRARY_CATEGORIES.PURCHASE; // 'purchase'
-    default:
-      return LIBRARY_CATEGORIES.SUBSCRIPTION; // Default to subscription
-  }
-}
-
-/**
- * Validate that a category is defined in user's Transaction model enum
- * This is informational - actual validation happens at Mongoose schema level
- *
- * @param {String} category - Category to validate
- * @param {Array<String>} allowedCategories - List of allowed categories
- * @returns {Boolean} Whether category is valid
- */
-export function isCategoryValid(category, allowedCategories = []) {
-  return allowedCategories.includes(category);
-}
-
-export default resolveCategory;

package/utils/commission-split.js

@@ -1,180 +0,0 @@
-/**
- * Commission Split Utilities
- * @classytic/revenue
- *
- * Multi-party commission split calculation for affiliate/referral systems
- */
-
-import { SPLIT_TYPE, SPLIT_STATUS } from '../enums/split.enums.js';
-
-/**
- * Calculate multi-party commission splits
- *
- * @param {Number} amount - Transaction amount
- * @param {Array} splitRules - Split configuration
- * @param {Number} gatewayFeeRate - Gateway fee rate (optional)
- * @returns {Array} 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, ... },
- * ]
- */
-export function calculateSplits(amount, splitRules = [], gatewayFeeRate = 0) {
-  if (!splitRules || splitRules.length === 0) {
-    return [];
-  }
-
-  if (amount < 0) {
-    throw new Error('Transaction amount cannot be negative');
-  }
-
-  if (gatewayFeeRate < 0 || gatewayFeeRate > 1) {
-    throw new Error('Gateway fee rate must be between 0 and 1');
-  }
-
-  const totalRate = splitRules.reduce((sum, rule) => sum + rule.rate, 0);
-  if (totalRate > 1) {
-    throw new Error(`Total split rate (${totalRate}) cannot exceed 1.0`);
-  }
-
-  return splitRules.map((rule, index) => {
-    if (rule.rate < 0 || rule.rate > 1) {
-      throw new Error(`Split rate must be between 0 and 1 for split ${index}`);
-    }
-
-    const grossAmount = Math.round(amount * rule.rate * 100) / 100;
-
-    const gatewayFeeAmount = index === 0 && gatewayFeeRate > 0
-      ? Math.round(amount * gatewayFeeRate * 100) / 100
-      : 0;
-
-    const netAmount = Math.max(0, Math.round((grossAmount - gatewayFeeAmount) * 100) / 100);
-
-    return {
-      type: rule.type || SPLIT_TYPE.CUSTOM,
-      recipientId: rule.recipientId,
-      recipientType: rule.recipientType,
-      rate: rule.rate,
-      grossAmount,
-      gatewayFeeRate: gatewayFeeAmount > 0 ? gatewayFeeRate : 0,
-      gatewayFeeAmount,
-      netAmount,
-      status: SPLIT_STATUS.PENDING,
-      dueDate: rule.dueDate || null,
-      metadata: rule.metadata || {},
-    };
-  });
-}
-
-/**
- * Calculate organization payout after splits
- *
- * @param {Number} amount - Total transaction amount
- * @param {Array} splits - Calculated splits
- * @returns {Number} Amount organization receives
- */
-export function calculateOrganizationPayout(amount, splits = []) {
-  const totalSplitAmount = splits.reduce((sum, split) => sum + split.grossAmount, 0);
-  return Math.max(0, Math.round((amount - totalSplitAmount) * 100) / 100);
-}
-
-/**
- * Reverse splits proportionally on refund
- *
- * @param {Array} originalSplits - Original split objects
- * @param {Number} originalAmount - Original transaction amount
- * @param {Number} refundAmount - Amount being refunded
- * @returns {Array} Reversed splits
- */
-export function reverseSplits(originalSplits, originalAmount, refundAmount) {
-  if (!originalSplits || originalSplits.length === 0) {
-    return [];
-  }
-
-  const refundRatio = refundAmount / originalAmount;
-
-  return originalSplits.map(split => ({
-    ...split,
-    grossAmount: Math.round(split.grossAmount * refundRatio * 100) / 100,
-    gatewayFeeAmount: Math.round(split.gatewayFeeAmount * refundRatio * 100) / 100,
-    netAmount: Math.round(split.netAmount * refundRatio * 100) / 100,
-    status: SPLIT_STATUS.WAIVED,
-  }));
-}
-
-/**
- * Build commission object with splits support
- * Backward compatible with existing calculateCommission
- *
- * @param {Number} amount - Transaction amount
- * @param {Number} commissionRate - Platform commission rate
- * @param {Number} gatewayFeeRate - Gateway fee rate
- * @param {Object} options - Additional options
- * @returns {Object} Commission with optional splits
- */
-export function calculateCommissionWithSplits(amount, commissionRate, gatewayFeeRate = 0, options = {}) {
-  const { affiliateRate = 0, affiliateId = null, affiliateType = 'user' } = options;
-
-  if (commissionRate <= 0 && affiliateRate <= 0) {
-    return null;
-  }
-
-  const splitRules = [];
-
-  if (commissionRate > 0) {
-    splitRules.push({
-      type: SPLIT_TYPE.PLATFORM_COMMISSION,
-      recipientId: 'platform',
-      recipientType: 'platform',
-      rate: commissionRate,
-    });
-  }
-
-  if (affiliateRate > 0 && affiliateId) {
-    splitRules.push({
-      type: SPLIT_TYPE.AFFILIATE_COMMISSION,
-      recipientId: affiliateId,
-      recipientType: affiliateType,
-      rate: affiliateRate,
-    });
-  }
-
-  const splits = calculateSplits(amount, splitRules, gatewayFeeRate);
-
-  const platformSplit = splits.find(s => s.type === SPLIT_TYPE.PLATFORM_COMMISSION);
-  const affiliateSplit = splits.find(s => s.type === SPLIT_TYPE.AFFILIATE_COMMISSION);
-
-  return {
-    rate: commissionRate,
-    grossAmount: platformSplit?.grossAmount || 0,
-    gatewayFeeRate: platformSplit?.gatewayFeeRate || 0,
-    gatewayFeeAmount: platformSplit?.gatewayFeeAmount || 0,
-    netAmount: platformSplit?.netAmount || 0,
-    status: SPLIT_STATUS.PENDING,
-    ...(splits.length > 0 && { splits }),
-    ...(affiliateSplit && {
-      affiliate: {
-        recipientId: affiliateSplit.recipientId,
-        recipientType: affiliateSplit.recipientType,
-        rate: affiliateSplit.rate,
-        grossAmount: affiliateSplit.grossAmount,
-        netAmount: affiliateSplit.netAmount,
-      },
-    }),
-  };
-}
-
-export default {
-  calculateSplits,
-  calculateOrganizationPayout,
-  reverseSplits,
-  calculateCommissionWithSplits,
-};

package/utils/commission.js

@@ -1,83 +0,0 @@
-/**
- * Commission Calculation Utility
- * @classytic/revenue
- *
- * Handles platform commission calculation with gateway fee deduction
- */
-
-/**
- * Build commission object for transaction
- *
- * @param {Number} amount - Transaction amount
- * @param {Number} commissionRate - Commission rate (0 to 1, e.g., 0.10 for 10%)
- * @param {Number} gatewayFeeRate - Gateway fee rate (0 to 1, e.g., 0.018 for 1.8%)
- * @returns {Object} Commission object or null
- */
-export function calculateCommission(amount, commissionRate, gatewayFeeRate = 0) {
-  // No commission if rate is 0 or negative
-  if (!commissionRate || commissionRate <= 0) {
-    return null;
-  }
-
-  // Validate inputs
-  if (amount < 0) {
-    throw new Error('Transaction amount cannot be negative');
-  }
-
-  if (commissionRate < 0 || commissionRate > 1) {
-    throw new Error('Commission rate must be between 0 and 1');
-  }
-
-  if (gatewayFeeRate < 0 || gatewayFeeRate > 1) {
-    throw new Error('Gateway fee rate must be between 0 and 1');
-  }
-
-  // Calculate commission
-  const grossAmount = Math.round(amount * commissionRate * 100) / 100; // Round to 2 decimals
-  const gatewayFeeAmount = Math.round(amount * gatewayFeeRate * 100) / 100;
-  const netAmount = Math.max(0, Math.round((grossAmount - gatewayFeeAmount) * 100) / 100);
-
-  return {
-    rate: commissionRate,
-    grossAmount,
-    gatewayFeeRate,
-    gatewayFeeAmount,
-    netAmount,
-    status: 'pending',
-  };
-}
-
-/**
- * Reverse commission on refund (proportional)
- *
- * @param {Object} originalCommission - Original commission object
- * @param {Number} originalAmount - Original transaction amount
- * @param {Number} refundAmount - Amount being refunded
- * @returns {Object} Reversed commission or null
- */
-export function reverseCommission(originalCommission, originalAmount, refundAmount) {
-  if (!originalCommission || !originalCommission.netAmount) {
-    return null;
-  }
-
-  // Calculate proportional refund
-  const refundRatio = refundAmount / originalAmount;
-  const reversedNetAmount = Math.round(originalCommission.netAmount * refundRatio * 100) / 100;
-  const reversedGrossAmount = Math.round(originalCommission.grossAmount * refundRatio * 100) / 100;
-  const reversedGatewayFee = Math.round(originalCommission.gatewayFeeAmount * refundRatio * 100) / 100;
-
-  return {
-    rate: originalCommission.rate,
-    grossAmount: reversedGrossAmount,
-    gatewayFeeRate: originalCommission.gatewayFeeRate,
-    gatewayFeeAmount: reversedGatewayFee,
-    netAmount: reversedNetAmount,
-    status: 'waived', // Commission waived due to refund
-  };
-}
-
-export default {
-  calculateCommission,
-  reverseCommission,
-};
-

package/utils/hooks.js

@@ -1,44 +0,0 @@
-/**
- * Hook Utilities
- * @classytic/revenue
- *
- * Fire-and-forget hook execution - never blocks main flow
- */
-
-/**
- * Trigger hooks asynchronously without waiting
- * Errors are logged but never thrown
- *
- * @param {Object} hooks - Hooks object
- * @param {string} event - Event name
- * @param {Object} data - Event data
- * @param {Object} logger - Logger instance
- */
-export function triggerHook(hooks, event, data, logger) {
-  const handlers = hooks[event] || [];
-
-  if (handlers.length === 0) {
-    return; // No handlers, return immediately
-  }
-
-  // Fire-and-forget: Don't await, don't block
-  Promise.all(
-    handlers.map(handler =>
-      Promise.resolve(handler(data)).catch(error => {
-        logger.error(`Hook "${event}" failed:`, {
-          error: error.message,
-          stack: error.stack,
-          event,
-          // Don't log full data (could be huge)
-          dataKeys: Object.keys(data),
-        });
-      })
-    )
-  ).catch(() => {
-    // Swallow any Promise.all errors (already logged individually)
-  });
-
-  // Return immediately - hooks run in background
-}
-
-export default triggerHook;

package/utils/index.d.ts

@@ -1,164 +0,0 @@
-/**
- * TypeScript definitions for @classytic/revenue/utils
- * Core utilities
- */
-
-// ============ TRANSACTION TYPE UTILITIES ============
-
-export const TRANSACTION_TYPE: {
-  readonly MONETIZATION: 'monetization';
-  readonly MANUAL: 'manual';
-};
-
-export const PROTECTED_MONETIZATION_FIELDS: readonly string[];
-export const EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION: readonly string[];
-export const MANUAL_TRANSACTION_CREATE_FIELDS: readonly string[];
-export const MANUAL_TRANSACTION_UPDATE_FIELDS: readonly string[];
-
-export interface TransactionTypeOptions {
-  targetModels?: string[];
-  additionalCategories?: string[];
-}
-
-export function isMonetizationTransaction(
-  transaction: any,
-  options?: TransactionTypeOptions
-): boolean;
-
-export function isManualTransaction(
-  transaction: any,
-  options?: TransactionTypeOptions
-): boolean;
-
-export function getTransactionType(
-  transaction: any,
-  options?: TransactionTypeOptions
-): 'monetization' | 'manual';
-
-export function getAllowedUpdateFields(
-  transaction: any,
-  options?: TransactionTypeOptions
-): string[];
-
-export interface FieldValidationResult {
-  allowed: boolean;
-  reason?: string;
-}
-
-export function validateFieldUpdate(
-  transaction: any,
-  fieldName: string,
-  options?: TransactionTypeOptions
-): FieldValidationResult;
-
-export function canSelfVerify(
-  transaction: any,
-  options?: TransactionTypeOptions
-): boolean;
-
-// ============ LOGGER UTILITIES ============
-
-export interface Logger {
-  info(...args: any[]): void;
-  warn(...args: any[]): void;
-  error(...args: any[]): void;
-  debug(...args: any[]): void;
-}
-
-export const logger: Logger;
-export function setLogger(logger: Logger | Console): void;
-
-// ============ HOOK UTILITIES ============
-
-export function triggerHook(
-  hooks: Record<string, Function[]>,
-  event: string,
-  data: any,
-  logger: Logger
-): void;
-
-// ============ COMMISSION UTILITIES ============
-
-export interface CommissionObject {
-  rate: number;
-  grossAmount: number;
-  gatewayFeeRate: number;
-  gatewayFeeAmount: number;
-  netAmount: number;
-  status: 'pending' | 'due' | 'paid' | 'waived';
-}
-
-export function calculateCommission(
-  amount: number,
-  commissionRate: number,
-  gatewayFeeRate?: number
-): CommissionObject | null;
-
-export function reverseCommission(
-  originalCommission: CommissionObject,
-  originalAmount: number,
-  refundAmount: number
-): CommissionObject | null;
-
-// ============ SUBSCRIPTION UTILITIES ============
-
-export function addDuration(startDate: Date, duration: number, unit?: string): Date;
-
-export function calculatePeriodRange(params: {
-  currentEndDate?: Date | null;
-  startDate?: Date | null;
-  duration: number;
-  unit?: string;
-  now?: Date;
-}): { startDate: Date; endDate: Date };
-
-export function calculateProratedAmount(params: {
-  amountPaid: number;
-  startDate: Date;
-  endDate: Date;
-  asOfDate?: Date;
-  precision?: number;
-}): number;
-
-export function resolveIntervalToDuration(
-  interval?: string,
-  intervalCount?: number
-): { duration: number; unit: string };
-
-export function isSubscriptionActive(subscription: any): boolean;
-export function canRenewSubscription(entity: any): boolean;
-export function canCancelSubscription(entity: any): boolean;
-export function canPauseSubscription(entity: any): boolean;
-export function canResumeSubscription(entity: any): boolean;
-
-// ============ DEFAULT EXPORT ============
-
-declare const _default: {
-  TRANSACTION_TYPE: typeof TRANSACTION_TYPE;
-  isMonetizationTransaction: typeof isMonetizationTransaction;
-  isManualTransaction: typeof isManualTransaction;
-  getTransactionType: typeof getTransactionType;
-  PROTECTED_MONETIZATION_FIELDS: typeof PROTECTED_MONETIZATION_FIELDS;
-  EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION: typeof EDITABLE_MONETIZATION_FIELDS_PRE_VERIFICATION;
-  MANUAL_TRANSACTION_CREATE_FIELDS: typeof MANUAL_TRANSACTION_CREATE_FIELDS;
-  MANUAL_TRANSACTION_UPDATE_FIELDS: typeof MANUAL_TRANSACTION_UPDATE_FIELDS;
-  getAllowedUpdateFields: typeof getAllowedUpdateFields;
-  validateFieldUpdate: typeof validateFieldUpdate;
-  canSelfVerify: typeof canSelfVerify;
-  logger: typeof logger;
-  setLogger: typeof setLogger;
-  triggerHook: typeof triggerHook;
-  calculateCommission: typeof calculateCommission;
-  reverseCommission: typeof reverseCommission;
-  addDuration: typeof addDuration;
-  calculatePeriodRange: typeof calculatePeriodRange;
-  calculateProratedAmount: typeof calculateProratedAmount;
-  resolveIntervalToDuration: typeof resolveIntervalToDuration;
-  isSubscriptionActive: typeof isSubscriptionActive;
-  canRenewSubscription: typeof canRenewSubscription;
-  canCancelSubscription: typeof canCancelSubscription;
-  canPauseSubscription: typeof canPauseSubscription;
-  canResumeSubscription: typeof canResumeSubscription;
-};
-
-export default _default;

package/utils/index.js

@@ -1,16 +0,0 @@
-/**
- * Core Utilities
- * @classytic/revenue
- */
-
-export * from './transaction-type.js';
-export { default as logger, setLogger } from './logger.js';
-export { triggerHook } from './hooks.js';
-export { calculateCommission, reverseCommission } from './commission.js';
-export {
-  calculateSplits,
-  calculateOrganizationPayout,
-  reverseSplits,
-  calculateCommissionWithSplits,
-} from './commission-split.js';
-export * from './subscription/index.js';

package/utils/logger.js

@@ -1,36 +0,0 @@
-/**
- * Logger Abstraction for Monetization Library
- *
- * Defaults to console for standalone usage
- * Can be overridden with custom logger (pino, winston, etc)
- *
- * Usage:
- * ```javascript
- * import { setLogger } from '@classytic/revenue';
- *
- * // Optional: Use your own logger
- * setLogger(myPinoLogger);
- * ```
- */
-
-let _logger = console;
-
-/**
- * Set custom logger implementation
- * @param {Object} customLogger - Logger instance with info, warn, error, debug methods
- */
-export function setLogger(customLogger) {
-  _logger = customLogger;
-}
-
-/**
- * Logger proxy - delegates to current logger implementation
- */
-export const logger = {
-  info: (...args) => _logger.info?.(...args) || _logger.log?.('INFO:', ...args),
-  warn: (...args) => _logger.warn?.(...args) || _logger.log?.('WARN:', ...args),
-  error: (...args) => _logger.error?.(...args) || _logger.log?.('ERROR:', ...args),
-  debug: (...args) => _logger.debug?.(...args) || _logger.log?.('DEBUG:', ...args),
-};
-
-export default logger;

package/utils/subscription/actions.js

@@ -1,68 +0,0 @@
-/**
- * Subscription Action Utilities
- * @classytic/revenue/utils/subscription
- *
- * Eligibility checks for subscription actions
- */
-
-import { SUBSCRIPTION_STATUS } from '../../enums/subscription.enums.js';
-
-/**
- * Check if subscription is active
- */
-export function isSubscriptionActive(subscription) {
-  if (!subscription) return false;
-  if (!subscription.isActive) return false;
-
-  if (subscription.endDate) {
-    const now = new Date();
-    const endDate = new Date(subscription.endDate);
-    if (endDate < now) return false;
-  }
-
-  return true;
-}
-
-/**
- * Check if can renew
- */
-export function canRenewSubscription(entity) {
-  if (!entity || !entity.subscription) return false;
-  return isSubscriptionActive(entity.subscription);
-}
-
-/**
- * Check if can cancel
- */
-export function canCancelSubscription(entity) {
-  if (!entity || !entity.subscription) return false;
-  if (!isSubscriptionActive(entity.subscription)) return false;
-  return !entity.subscription.canceledAt;
-}
-
-/**
- * Check if can pause
- */
-export function canPauseSubscription(entity) {
-  if (!entity || !entity.subscription) return false;
-  if (entity.status === SUBSCRIPTION_STATUS.PAUSED) return false;
-  if (entity.status === SUBSCRIPTION_STATUS.CANCELLED) return false;
-  return isSubscriptionActive(entity.subscription);
-}
-
-/**
- * Check if can resume
- */
-export function canResumeSubscription(entity) {
-  if (!entity || !entity.subscription) return false;
-  return entity.status === SUBSCRIPTION_STATUS.PAUSED;
-}
-
-export default {
-  isSubscriptionActive,
-  canRenewSubscription,
-  canCancelSubscription,
-  canPauseSubscription,
-  canResumeSubscription,
-};
-

package/utils/subscription/index.js

@@ -1,20 +0,0 @@
-/**
- * Subscription Utilities Index
- * @classytic/revenue/utils/subscription
- */
-
-export {
-  addDuration,
-  calculatePeriodRange,
-  calculateProratedAmount,
-  resolveIntervalToDuration,
-} from './period.js';
-
-export {
-  isSubscriptionActive,
-  canRenewSubscription,
-  canCancelSubscription,
-  canPauseSubscription,
-  canResumeSubscription,
-} from './actions.js';
-