@classytic/revenue 0.0.22 → 0.0.24

package/services/subscription.service.js

@@ -19,6 +19,7 @@ import {
 } from '../core/errors.js';
 import { triggerHook } from '../utils/hooks.js';
 import { resolveCategory } from '../utils/category-resolver.js';
+import { calculateCommission } from '../utils/commission.js';
 import { MONETIZATION_TYPES } from '../enums/monetization.enums.js';
 import { TRANSACTION_TYPE } from '../enums/transaction.enums.js';
 
@@ -40,7 +41,7 @@ export class SubscriptionService {
    * Create a new subscription
    *
    * @param {Object} params - Subscription parameters
-   * @param {Object} params.data - Subscription data (organizationId, customerId, etc.)
+   * @param {Object} params.data - Subscription data (organizationId, customerId, referenceId, referenceModel, etc.)
    * @param {String} params.planKey - Plan key ('monthly', 'quarterly', 'yearly')
    * @param {Number} params.amount - Subscription amount
    * @param {String} params.currency - Currency code (default: 'BDT')
@@ -51,6 +52,20 @@ export class SubscriptionService {
    * @param {Object} params.paymentData - Payment method details
    * @param {Object} params.metadata - Additional metadata
    * @param {String} params.idempotencyKey - Idempotency key for duplicate prevention
+   * 
+   * @example
+   * // With polymorphic reference (recommended)
+   * await revenue.subscriptions.create({
+   *   data: {
+   *     organizationId: '...',
+   *     customerId: '...',
+   *     referenceId: subscription._id,      // Links to entity
+   *     referenceModel: 'Subscription',     // Model name
+   *   },
+   *   amount: 1500,
+   *   // ...
+   * });
+   * 
    * @returns {Promise<Object>} { subscription, transaction, paymentIntent }
    */
   async create(params) {
@@ -116,6 +131,11 @@ export class SubscriptionService {
         || this.config.transactionTypeMapping?.[monetizationType]
         || TRANSACTION_TYPE.INCOME;
 
+      // Calculate commission if configured
+      const commissionRate = this.config.commissionRates?.[category] || 0;
+      const gatewayFeeRate = this.config.gatewayFeeRates?.[gateway] || 0;
+      const commission = calculateCommission(amount, commissionRate, gatewayFeeRate);
+
       // Create transaction record
       const TransactionModel = this.models.Transaction;
       transaction = await TransactionModel.create({
@@ -136,6 +156,10 @@ export class SubscriptionService {
           provider: gateway,
           ...paymentData,
         },
+        ...(commission && { commission }), // Only include if commission exists
+        // Polymorphic reference (top-level, not metadata)
+        ...(data.referenceId && { referenceId: data.referenceId }),
+        ...(data.referenceModel && { referenceModel: data.referenceModel }),
         metadata: {
           ...metadata,
           planKey,
@@ -152,7 +176,8 @@ export class SubscriptionService {
     if (this.models.Subscription) {
       const SubscriptionModel = this.models.Subscription;
 
-      subscription = await SubscriptionModel.create({
+      // Create subscription with proper reference tracking
+      const subscriptionData = {
         organizationId: data.organizationId,
         customerId: data.customerId || null,
         planKey,
@@ -170,7 +195,13 @@ export class SubscriptionService {
           monetizationType,
         },
         ...data,
-      });
+      };
+
+      // Remove referenceId/referenceModel from subscription (they're for transactions)
+      delete subscriptionData.referenceId;
+      delete subscriptionData.referenceModel;
+
+      subscription = await SubscriptionModel.create(subscriptionData);
     }
 
     // Trigger hook
@@ -299,6 +330,11 @@ export class SubscriptionService {
       || this.config.transactionTypeMapping?.[effectiveMonetizationType]
       || TRANSACTION_TYPE.INCOME;
 
+    // Calculate commission if configured
+    const commissionRate = this.config.commissionRates?.[category] || 0;
+    const gatewayFeeRate = this.config.gatewayFeeRates?.[gateway] || 0;
+    const commission = calculateCommission(subscription.amount, commissionRate, gatewayFeeRate);
+
     // Create transaction
     const TransactionModel = this.models.Transaction;
     const transaction = await TransactionModel.create({
@@ -319,9 +355,13 @@ export class SubscriptionService {
         provider: gateway,
         ...paymentData,
       },
+      ...(commission && { commission }), // Only include if commission exists
+      // Polymorphic reference to subscription
+      referenceId: subscription._id,
+      referenceModel: 'Subscription',
       metadata: {
         ...metadata,
-        subscriptionId: subscription._id.toString(),
+        subscriptionId: subscription._id.toString(), // Keep for backward compat
         entity: effectiveEntity,
         monetizationType: effectiveMonetizationType,
         isRenewal: true,

package/utils/commission.js

@@ -0,0 +1,83 @@
+/**
+ * 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/index.d.ts

@@ -1,99 +1,164 @@
-/**
- * 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;
-
-// ============ 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;
-};
-
-export default _default;
+/**
+ * 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,8 +1,10 @@
-/**
- * Core Utilities
- * @classytic/revenue
- */
-
-export * from './transaction-type.js';
-export { default as logger, setLogger } from './logger.js';
-export { triggerHook } from './hooks.js';
+/**
+ * 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 * from './subscription/index.js';

package/utils/subscription/actions.js

@@ -0,0 +1,68 @@
+/**
+ * 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

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

package/utils/subscription/period.js

@@ -0,0 +1,123 @@
+/**
+ * Subscription Period Utilities
+ * @classytic/revenue/utils/subscription
+ *
+ * Universal period calculation, proration, and date utilities
+ */
+
+/**
+ * Add duration to date
+ */
+export function addDuration(startDate, duration, unit = 'days') {
+  const date = new Date(startDate);
+  
+  switch (unit) {
+    case 'months':
+    case 'month':
+      date.setMonth(date.getMonth() + duration);
+      return date;
+    case 'years':
+    case 'year':
+      date.setFullYear(date.getFullYear() + duration);
+      return date;
+    case 'weeks':
+    case 'week':
+      date.setDate(date.getDate() + (duration * 7));
+      return date;
+    case 'days':
+    case 'day':
+    default:
+      date.setDate(date.getDate() + duration);
+      return date;
+  }
+}
+
+/**
+ * Calculate subscription period start/end dates
+ */
+export function calculatePeriodRange({
+  currentEndDate = null,
+  startDate = null,
+  duration,
+  unit = 'days',
+  now = new Date(),
+}) {
+  let periodStart;
+
+  if (startDate) {
+    periodStart = new Date(startDate);
+  } else if (currentEndDate) {
+    const end = new Date(currentEndDate);
+    periodStart = end > now ? end : now;
+  } else {
+    periodStart = now;
+  }
+
+  const periodEnd = addDuration(periodStart, duration, unit);
+
+  return { startDate: periodStart, endDate: periodEnd };
+}
+
+/**
+ * Calculate prorated refund amount for unused period
+ */
+export function calculateProratedAmount({
+  amountPaid,
+  startDate,
+  endDate,
+  asOfDate = new Date(),
+  precision = 2,
+}) {
+  if (!amountPaid || amountPaid <= 0) return 0;
+
+  const start = new Date(startDate);
+  const end = new Date(endDate);
+  const asOf = new Date(asOfDate);
+
+  const totalMs = end - start;
+  if (totalMs <= 0) return 0;
+
+  const remainingMs = Math.max(0, end - asOf);
+  if (remainingMs <= 0) return 0;
+
+  const ratio = remainingMs / totalMs;
+  const amount = amountPaid * ratio;
+  
+  const factor = 10 ** precision;
+  return Math.round(amount * factor) / factor;
+}
+
+/**
+ * Convert interval + count to duration/unit
+ */
+export function resolveIntervalToDuration(interval = 'month', intervalCount = 1) {
+  const normalized = (interval || 'month').toLowerCase();
+  const count = Number(intervalCount) > 0 ? Number(intervalCount) : 1;
+
+  switch (normalized) {
+    case 'year':
+    case 'years':
+      return { duration: count, unit: 'years' };
+    case 'week':
+    case 'weeks':
+      return { duration: count, unit: 'weeks' };
+    case 'quarter':
+    case 'quarters':
+      return { duration: count * 3, unit: 'months' };
+    case 'day':
+    case 'days':
+      return { duration: count, unit: 'days' };
+    case 'month':
+    case 'months':
+    default:
+      return { duration: count, unit: 'months' };
+  }
+}
+
+export default {
+  addDuration,
+  calculatePeriodRange,
+  calculateProratedAmount,
+  resolveIntervalToDuration,
+};
+