@classytic/revenue 0.0.24 → 0.2.0

package/schemas/split/split.schema.js

@@ -0,0 +1,86 @@
+/**
+ * Split Payment Schema
+ * @classytic/revenue
+ *
+ * Schema for multi-party commission splits
+ * Spread into transaction schema when needed
+ */
+
+import { SPLIT_TYPE, SPLIT_TYPE_VALUES, SPLIT_STATUS, SPLIT_STATUS_VALUES, PAYOUT_METHOD, PAYOUT_METHOD_VALUES } from '../../enums/split.enums.js';
+
+export const splitItemSchema = {
+  type: {
+    type: String,
+    enum: SPLIT_TYPE_VALUES,
+    required: true,
+  },
+
+  recipientId: {
+    type: String,
+    required: true,
+    index: true,
+  },
+
+  recipientType: {
+    type: String,
+    required: true,
+  },
+
+  rate: {
+    type: Number,
+    required: true,
+    min: 0,
+    max: 1,
+  },
+
+  grossAmount: {
+    type: Number,
+    required: true,
+  },
+
+  gatewayFeeRate: {
+    type: Number,
+    default: 0,
+  },
+
+  gatewayFeeAmount: {
+    type: Number,
+    default: 0,
+  },
+
+  netAmount: {
+    type: Number,
+    required: true,
+  },
+
+  status: {
+    type: String,
+    enum: SPLIT_STATUS_VALUES,
+    default: SPLIT_STATUS.PENDING,
+  },
+
+  dueDate: Date,
+  paidDate: Date,
+
+  payoutMethod: {
+    type: String,
+    enum: PAYOUT_METHOD_VALUES,
+    required: false,
+  },
+
+  payoutTransactionId: String,
+
+  metadata: {
+    type: Object,
+    default: {},
+  },
+};
+
+export const splitsSchema = {
+  splits: {
+    type: [splitItemSchema],
+    default: [],
+  },
+};
+
+export default splitsSchema;

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';
@@ -81,15 +83,40 @@ export class PaymentService {
 
       // Update transaction as failed
       transaction.status = 'failed';
+      transaction.failureReason = error.message;
       transaction.metadata = {
         ...transaction.metadata,
         verificationError: error.message,
+        failedAt: new Date().toISOString(),
       };
       await transaction.save();
 
+      // Trigger payment.failed hook
+      this._triggerHook('payment.failed', {
+        transaction,
+        error: error.message,
+        provider: gatewayType,
+        paymentIntentId,
+      });
+
       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 +138,7 @@ export class PaymentService {
     return {
       transaction,
       paymentResult,
-      status: 'verified',
+      status: transaction.status,
     };
   }
 
@@ -212,8 +239,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 +349,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

@@ -45,14 +45,14 @@ export class SubscriptionService {
    * @param {String} params.planKey - Plan key ('monthly', 'quarterly', 'yearly')
    * @param {Number} params.amount - Subscription amount
    * @param {String} params.currency - Currency code (default: 'BDT')
-   * @param {String} params.gateway - Payment gateway to use (default: 'manual')
+   * @param {String} params.gateway - Payment gateway name (default: 'manual') - Use ANY registered provider name: 'manual', 'bkash', 'nagad', 'stripe', etc.
    * @param {String} params.entity - Logical entity identifier (e.g., 'Order', 'PlatformSubscription', 'Membership')
    *                                 NOTE: This is NOT a database model name - it's just a logical identifier for categoryMappings
    * @param {String} params.monetizationType - Monetization type ('free', 'subscription', 'purchase')
    * @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({
@@ -62,10 +62,11 @@ export class SubscriptionService {
    *     referenceId: subscription._id,      // Links to entity
    *     referenceModel: 'Subscription',     // Model name
    *   },
+   *   gateway: 'bkash',  // Any registered provider
    *   amount: 1500,
    *   // ...
    * });
-   * 
+   *
    * @returns {Promise<Object>} { subscription, transaction, paymentIntent }
    */
   async create(params) {
@@ -204,13 +205,26 @@ export class SubscriptionService {
       subscription = await SubscriptionModel.create(subscriptionData);
     }
 
-    // Trigger hook
-    this._triggerHook('subscription.created', {
+    // Trigger hooks - emit specific event based on monetization type
+    const eventData = {
       subscription,
       transaction,
       paymentIntent,
       isFree,
-    });
+      monetizationType,
+    };
+
+    // Emit specific monetization event
+    if (monetizationType === MONETIZATION_TYPES.PURCHASE) {
+      this._triggerHook('purchase.created', eventData);
+    } else if (monetizationType === MONETIZATION_TYPES.SUBSCRIPTION) {
+      this._triggerHook('subscription.created', eventData);
+    } else if (monetizationType === MONETIZATION_TYPES.FREE) {
+      this._triggerHook('free.created', eventData);
+    }
+
+    // Also emit generic event for backward compatibility
+    this._triggerHook('monetization.created', eventData);
 
     return {
       subscription,
@@ -271,7 +285,7 @@ export class SubscriptionService {
    *
    * @param {String} subscriptionId - Subscription ID
    * @param {Object} params - Renewal parameters
-   * @param {String} params.gateway - Payment gateway to use (default: 'manual')
+   * @param {String} params.gateway - Payment gateway name (default: 'manual') - Use ANY registered provider name: 'manual', 'bkash', 'nagad', 'stripe', etc.
    * @param {String} params.entity - Logical entity identifier (optional, inherits from subscription)
    * @param {Object} params.paymentData - Payment method details
    * @param {Object} params.metadata - Additional metadata
@@ -309,15 +323,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;