@classytic/revenue 0.0.24 → 0.1.0

package/services/escrow.service.js

@@ -0,0 +1,353 @@
+/**
+ * Escrow Service
+ * @classytic/revenue
+ *
+ * Platform-as-intermediary payment flow
+ * Hold funds → Verify → Split/Deduct → Release to organization
+ */
+
+import { TransactionNotFoundError } from '../core/errors.js';
+import { HOLD_STATUS, RELEASE_REASON, HOLD_REASON } from '../enums/escrow.enums.js';
+import { TRANSACTION_TYPE, TRANSACTION_STATUS } from '../enums/transaction.enums.js';
+import { SPLIT_STATUS } from '../enums/split.enums.js';
+import { triggerHook } from '../utils/hooks.js';
+import { calculateSplits, calculateOrganizationPayout } from '../utils/commission-split.js';
+
+export class EscrowService {
+  constructor(container) {
+    this.container = container;
+    this.models = container.get('models');
+    this.providers = container.get('providers');
+    this.config = container.get('config');
+    this.hooks = container.get('hooks');
+    this.logger = container.get('logger');
+  }
+
+  /**
+   * Hold funds in escrow
+   *
+   * @param {String} transactionId - Transaction to hold
+   * @param {Object} options - Hold options
+   * @returns {Promise<Object>} Updated transaction
+   */
+  async hold(transactionId, options = {}) {
+    const {
+      reason = HOLD_REASON.PAYMENT_VERIFICATION,
+      holdUntil = null,
+      metadata = {},
+    } = options;
+
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.findById(transactionId);
+
+    if (!transaction) {
+      throw new TransactionNotFoundError(transactionId);
+    }
+
+    if (transaction.status !== TRANSACTION_STATUS.VERIFIED) {
+      throw new Error(`Cannot hold transaction with status: ${transaction.status}. Must be verified.`);
+    }
+
+    transaction.hold = {
+      status: HOLD_STATUS.HELD,
+      heldAmount: transaction.amount,
+      releasedAmount: 0,
+      reason,
+      heldAt: new Date(),
+      ...(holdUntil && { holdUntil }),
+      releases: [],
+      metadata,
+    };
+
+    await transaction.save();
+
+    this._triggerHook('escrow.held', {
+      transaction,
+      heldAmount: transaction.amount,
+      reason,
+    });
+
+    return transaction;
+  }
+
+  /**
+   * Release funds from escrow to recipient
+   *
+   * @param {String} transactionId - Transaction to release
+   * @param {Object} options - Release options
+   * @returns {Promise<Object>} { transaction, releaseTransaction }
+   */
+  async release(transactionId, options = {}) {
+    const {
+      amount = null,
+      recipientId,
+      recipientType = 'organization',
+      reason = RELEASE_REASON.PAYMENT_VERIFIED,
+      releasedBy = null,
+      createTransaction = true,
+      metadata = {},
+    } = options;
+
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.findById(transactionId);
+
+    if (!transaction) {
+      throw new TransactionNotFoundError(transactionId);
+    }
+
+    if (!transaction.hold || transaction.hold.status !== HOLD_STATUS.HELD) {
+      throw new Error(`Transaction is not in held status. Current: ${transaction.hold?.status || 'none'}`);
+    }
+
+    if (!recipientId) {
+      throw new Error('recipientId is required for release');
+    }
+
+    const releaseAmount = amount || (transaction.hold.heldAmount - transaction.hold.releasedAmount);
+    const availableAmount = transaction.hold.heldAmount - transaction.hold.releasedAmount;
+
+    if (releaseAmount > availableAmount) {
+      throw new Error(`Release amount (${releaseAmount}) exceeds available held amount (${availableAmount})`);
+    }
+
+    const releaseRecord = {
+      amount: releaseAmount,
+      recipientId,
+      recipientType,
+      releasedAt: new Date(),
+      releasedBy,
+      reason,
+      metadata,
+    };
+
+    transaction.hold.releases.push(releaseRecord);
+    transaction.hold.releasedAmount += releaseAmount;
+
+    const isFullRelease = transaction.hold.releasedAmount >= transaction.hold.heldAmount;
+    const isPartialRelease = transaction.hold.releasedAmount > 0 && transaction.hold.releasedAmount < transaction.hold.heldAmount;
+
+    if (isFullRelease) {
+      transaction.hold.status = HOLD_STATUS.RELEASED;
+      transaction.hold.releasedAt = new Date();
+      transaction.status = TRANSACTION_STATUS.COMPLETED;
+    } else if (isPartialRelease) {
+      transaction.hold.status = HOLD_STATUS.PARTIALLY_RELEASED;
+    }
+
+    await transaction.save();
+
+    let releaseTransaction = null;
+    if (createTransaction) {
+      releaseTransaction = await TransactionModel.create({
+        organizationId: transaction.organizationId,
+        customerId: recipientId,
+        amount: releaseAmount,
+        currency: transaction.currency,
+        category: transaction.category,
+        type: TRANSACTION_TYPE.INCOME,
+        method: transaction.method,
+        status: TRANSACTION_STATUS.COMPLETED,
+        gateway: transaction.gateway,
+        referenceId: transaction.referenceId,
+        referenceModel: transaction.referenceModel,
+        metadata: {
+          ...metadata,
+          isRelease: true,
+          heldTransactionId: transaction._id.toString(),
+          releaseReason: reason,
+          recipientType,
+        },
+        idempotencyKey: `release_${transaction._id}_${Date.now()}`,
+      });
+    }
+
+    this._triggerHook('escrow.released', {
+      transaction,
+      releaseTransaction,
+      releaseAmount,
+      recipientId,
+      recipientType,
+      reason,
+      isFullRelease,
+      isPartialRelease,
+    });
+
+    return {
+      transaction,
+      releaseTransaction,
+      releaseAmount,
+      isFullRelease,
+      isPartialRelease,
+    };
+  }
+
+  /**
+   * Cancel hold and release back to customer
+   *
+   * @param {String} transactionId - Transaction to cancel hold
+   * @param {Object} options - Cancel options
+   * @returns {Promise<Object>} Updated transaction
+   */
+  async cancel(transactionId, options = {}) {
+    const { reason = 'Hold cancelled', metadata = {} } = options;
+
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.findById(transactionId);
+
+    if (!transaction) {
+      throw new TransactionNotFoundError(transactionId);
+    }
+
+    if (!transaction.hold || transaction.hold.status !== HOLD_STATUS.HELD) {
+      throw new Error(`Transaction is not in held status. Current: ${transaction.hold?.status || 'none'}`);
+    }
+
+    transaction.hold.status = HOLD_STATUS.CANCELLED;
+    transaction.hold.cancelledAt = new Date();
+    transaction.hold.metadata = {
+      ...transaction.hold.metadata,
+      ...metadata,
+      cancelReason: reason,
+    };
+
+    transaction.status = TRANSACTION_STATUS.CANCELLED;
+
+    await transaction.save();
+
+    this._triggerHook('escrow.cancelled', {
+      transaction,
+      reason,
+    });
+
+    return transaction;
+  }
+
+  /**
+   * Split payment to multiple recipients
+   * Deducts splits from held amount and releases remainder to organization
+   *
+   * @param {String} transactionId - Transaction to split
+   * @param {Array} splitRules - Split configuration
+   * @returns {Promise<Object>} { transaction, splitTransactions, organizationTransaction }
+   */
+  async split(transactionId, splitRules = []) {
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.findById(transactionId);
+
+    if (!transaction) {
+      throw new TransactionNotFoundError(transactionId);
+    }
+
+    if (!transaction.hold || transaction.hold.status !== HOLD_STATUS.HELD) {
+      throw new Error(`Transaction must be held before splitting. Current: ${transaction.hold?.status || 'none'}`);
+    }
+
+    if (!splitRules || splitRules.length === 0) {
+      throw new Error('splitRules cannot be empty');
+    }
+
+    const splits = calculateSplits(
+      transaction.amount,
+      splitRules,
+      transaction.commission?.gatewayFeeRate || 0
+    );
+
+    transaction.splits = splits;
+    await transaction.save();
+
+    const splitTransactions = [];
+
+    for (const split of splits) {
+      const splitTransaction = await TransactionModel.create({
+        organizationId: transaction.organizationId,
+        customerId: split.recipientId,
+        amount: split.netAmount,
+        currency: transaction.currency,
+        category: split.type,
+        type: TRANSACTION_TYPE.EXPENSE,
+        method: transaction.method,
+        status: TRANSACTION_STATUS.COMPLETED,
+        gateway: transaction.gateway,
+        referenceId: transaction.referenceId,
+        referenceModel: transaction.referenceModel,
+        metadata: {
+          isSplit: true,
+          splitType: split.type,
+          recipientType: split.recipientType,
+          originalTransactionId: transaction._id.toString(),
+          grossAmount: split.grossAmount,
+          gatewayFeeAmount: split.gatewayFeeAmount,
+        },
+        idempotencyKey: `split_${transaction._id}_${split.recipientId}_${Date.now()}`,
+      });
+
+      split.payoutTransactionId = splitTransaction._id.toString();
+      split.status = SPLIT_STATUS.PAID;
+      split.paidDate = new Date();
+
+      splitTransactions.push(splitTransaction);
+    }
+
+    await transaction.save();
+
+    const organizationPayout = calculateOrganizationPayout(transaction.amount, splits);
+
+    const organizationTransaction = await this.release(transactionId, {
+      amount: organizationPayout,
+      recipientId: transaction.organizationId,
+      recipientType: 'organization',
+      reason: RELEASE_REASON.PAYMENT_VERIFIED,
+      createTransaction: true,
+      metadata: {
+        afterSplits: true,
+        totalSplits: splits.length,
+        totalSplitAmount: transaction.amount - organizationPayout,
+      },
+    });
+
+    this._triggerHook('escrow.split', {
+      transaction,
+      splits,
+      splitTransactions,
+      organizationTransaction: organizationTransaction.releaseTransaction,
+      organizationPayout,
+    });
+
+    return {
+      transaction,
+      splits,
+      splitTransactions,
+      organizationTransaction: organizationTransaction.releaseTransaction,
+      organizationPayout,
+    };
+  }
+
+  /**
+   * Get escrow status
+   *
+   * @param {String} transactionId - Transaction ID
+   * @returns {Promise<Object>} Escrow status
+   */
+  async getStatus(transactionId) {
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.findById(transactionId);
+
+    if (!transaction) {
+      throw new TransactionNotFoundError(transactionId);
+    }
+
+    return {
+      transaction,
+      hold: transaction.hold || null,
+      splits: transaction.splits || [],
+      hasHold: !!transaction.hold,
+      hasSplits: transaction.splits && transaction.splits.length > 0,
+    };
+  }
+
+  _triggerHook(event, data) {
+    triggerHook(this.hooks, event, data, this.logger);
+  }
+}
+
+export default EscrowService;

package/services/payment.service.js

@@ -9,11 +9,13 @@
 import {
   TransactionNotFoundError,
   ProviderNotFoundError,
+  ProviderError,
   AlreadyVerifiedError,
   PaymentVerificationError,
   RefundNotSupportedError,
   RefundError,
   ProviderCapabilityError,
+  ValidationError,
 } from '../core/errors.js';
 import { triggerHook } from '../utils/hooks.js';
 import { reverseCommission } from '../utils/commission.js';
@@ -90,6 +92,21 @@ export class PaymentService {
       throw new PaymentVerificationError(paymentIntentId, error.message);
     }
 
+    // Validate amount and currency match
+    if (paymentResult.amount && paymentResult.amount !== transaction.amount) {
+      throw new ValidationError(
+        `Amount mismatch: expected ${transaction.amount}, got ${paymentResult.amount}`,
+        { expected: transaction.amount, actual: paymentResult.amount }
+      );
+    }
+
+    if (paymentResult.currency && paymentResult.currency.toUpperCase() !== transaction.currency.toUpperCase()) {
+      throw new ValidationError(
+        `Currency mismatch: expected ${transaction.currency}, got ${paymentResult.currency}`,
+        { expected: transaction.currency, actual: paymentResult.currency }
+      );
+    }
+
     // Update transaction based on verification result
     transaction.status = paymentResult.status === 'succeeded' ? 'verified' : paymentResult.status;
     transaction.verifiedAt = paymentResult.paidAt || new Date();
@@ -111,7 +128,7 @@ export class PaymentService {
     return {
       transaction,
       paymentResult,
-      status: 'verified',
+      status: transaction.status,
     };
   }
 
@@ -212,8 +229,24 @@ export class PaymentService {
       throw new RefundNotSupportedError(gatewayType);
     }
 
+    // Calculate refundable amount
+    const refundedSoFar = transaction.refundedAmount || 0;
+    const refundableAmount = transaction.amount - refundedSoFar;
+    const refundAmount = amount || refundableAmount;
+
+    // Validate refund amount
+    if (refundAmount <= 0) {
+      throw new ValidationError(`Refund amount must be positive, got ${refundAmount}`);
+    }
+
+    if (refundAmount > refundableAmount) {
+      throw new ValidationError(
+        `Refund amount (${refundAmount}) exceeds refundable balance (${refundableAmount})`,
+        { refundAmount, refundableAmount, alreadyRefunded: refundedSoFar }
+      );
+    }
+
     // Refund via provider
-    const refundAmount = amount || transaction.amount;
     let refundResult = null;
 
     try {
@@ -306,13 +339,31 @@ export class PaymentService {
       throw new ProviderNotFoundError(providerName, Object.keys(this.providers));
     }
 
+    // Check if provider supports webhooks
+    const capabilities = provider.getCapabilities();
+    if (!capabilities.supportsWebhooks) {
+      throw new ProviderCapabilityError(providerName, 'webhooks');
+    }
+
     // Process webhook via provider
     let webhookEvent = null;
     try {
       webhookEvent = await provider.handleWebhook(payload, headers);
     } catch (error) {
       this.logger.error('Webhook processing failed:', error);
-      throw new ProviderError(providerName, `Webhook processing failed: ${error.message}`);
+      throw new ProviderError(
+        `Webhook processing failed for ${providerName}: ${error.message}`,
+        'WEBHOOK_PROCESSING_FAILED',
+        { retryable: false }
+      );
+    }
+
+    // Validate webhook event structure
+    if (!webhookEvent?.data?.paymentIntentId) {
+      throw new ValidationError(
+        `Invalid webhook event structure from ${providerName}: missing paymentIntentId`,
+        { provider: providerName, eventType: webhookEvent?.type }
+      );
     }
 
     // Find transaction by payment intent ID from webhook

package/services/subscription.service.js

@@ -309,15 +309,21 @@ export class SubscriptionService {
     }
 
     // Create payment intent
-    const paymentIntent = await provider.createIntent({
-      amount: subscription.amount,
-      currency: subscription.currency || 'BDT',
-      metadata: {
-        ...metadata,
-        type: 'subscription_renewal',
-        subscriptionId: subscription._id.toString(),
-      },
-    });
+    let paymentIntent = null;
+    try {
+      paymentIntent = await provider.createIntent({
+        amount: subscription.amount,
+        currency: subscription.currency || 'BDT',
+        metadata: {
+          ...metadata,
+          type: 'subscription_renewal',
+          subscriptionId: subscription._id.toString(),
+        },
+      });
+    } catch (error) {
+      this.logger.error('Failed to create payment intent for renewal:', error);
+      throw new PaymentIntentCreationError(gateway, error);
+    }
 
     // Resolve category - use provided entity or inherit from subscription metadata
     const effectiveEntity = entity || subscription.metadata?.entity;

package/utils/commission-split.js

@@ -0,0 +1,180 @@
+/**
+ * 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/index.js

@@ -7,4 +7,10 @@ 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';