@classytic/revenue 0.2.3 → 1.0.0

package/dist/services/index.js

@@ -0,0 +1,1632 @@
+import { nanoid } from 'nanoid';
+
+// @classytic/revenue - Enterprise Revenue Management System
+
+
+// src/core/errors.ts
+var RevenueError = class extends Error {
+  code;
+  retryable;
+  metadata;
+  constructor(message, code, options = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.retryable = options.retryable ?? false;
+    this.metadata = options.metadata ?? {};
+    Error.captureStackTrace(this, this.constructor);
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      retryable: this.retryable,
+      metadata: this.metadata
+    };
+  }
+};
+var ConfigurationError = class extends RevenueError {
+  constructor(message, metadata = {}) {
+    super(message, "CONFIGURATION_ERROR", { retryable: false, metadata });
+  }
+};
+var ModelNotRegisteredError = class extends ConfigurationError {
+  constructor(modelName) {
+    super(
+      `Model "${modelName}" is not registered. Register it via createRevenue({ models: { ${modelName}: ... } })`,
+      { modelName }
+    );
+  }
+};
+var ProviderError = class extends RevenueError {
+  constructor(message, code, options = {}) {
+    super(message, code, options);
+  }
+};
+var ProviderNotFoundError = class extends ProviderError {
+  constructor(providerName, availableProviders = []) {
+    super(
+      `Payment provider "${providerName}" not found. Available: ${availableProviders.join(", ")}`,
+      "PROVIDER_NOT_FOUND",
+      { retryable: false, metadata: { providerName, availableProviders } }
+    );
+  }
+};
+var ProviderCapabilityError = class extends ProviderError {
+  constructor(providerName, capability) {
+    super(
+      `Provider "${providerName}" does not support ${capability}`,
+      "PROVIDER_CAPABILITY_NOT_SUPPORTED",
+      { retryable: false, metadata: { providerName, capability } }
+    );
+  }
+};
+var PaymentIntentCreationError = class extends ProviderError {
+  constructor(providerName, originalError) {
+    super(
+      `Failed to create payment intent with provider "${providerName}": ${originalError.message}`,
+      "PAYMENT_INTENT_CREATION_FAILED",
+      { retryable: true, metadata: { providerName, originalError: originalError.message } }
+    );
+  }
+};
+var PaymentVerificationError = class extends ProviderError {
+  constructor(paymentIntentId, reason) {
+    super(
+      `Payment verification failed for intent "${paymentIntentId}": ${reason}`,
+      "PAYMENT_VERIFICATION_FAILED",
+      { retryable: true, metadata: { paymentIntentId, reason } }
+    );
+  }
+};
+var NotFoundError = class extends RevenueError {
+  constructor(message, code, metadata = {}) {
+    super(message, code, { retryable: false, metadata });
+  }
+};
+var SubscriptionNotFoundError = class extends NotFoundError {
+  constructor(subscriptionId) {
+    super(
+      `Subscription not found: ${subscriptionId}`,
+      "SUBSCRIPTION_NOT_FOUND",
+      { subscriptionId }
+    );
+  }
+};
+var TransactionNotFoundError = class extends NotFoundError {
+  constructor(transactionId) {
+    super(
+      `Transaction not found: ${transactionId}`,
+      "TRANSACTION_NOT_FOUND",
+      { transactionId }
+    );
+  }
+};
+var ValidationError = class extends RevenueError {
+  constructor(message, metadata = {}) {
+    super(message, "VALIDATION_ERROR", { retryable: false, metadata });
+  }
+};
+var InvalidAmountError = class extends ValidationError {
+  constructor(amount, message) {
+    super(
+      message ?? `Invalid amount: ${amount}. Amount must be non-negative`,
+      { amount }
+    );
+  }
+};
+var MissingRequiredFieldError = class extends ValidationError {
+  constructor(fieldName) {
+    super(`Missing required field: ${fieldName}`, { fieldName });
+  }
+};
+var StateError = class extends RevenueError {
+  constructor(message, code, metadata = {}) {
+    super(message, code, { retryable: false, metadata });
+  }
+};
+var AlreadyVerifiedError = class extends StateError {
+  constructor(transactionId) {
+    super(
+      `Transaction ${transactionId} is already verified`,
+      "ALREADY_VERIFIED",
+      { transactionId }
+    );
+  }
+};
+var InvalidStateTransitionError = class extends StateError {
+  constructor(resourceType, resourceId, fromState, toState) {
+    super(
+      `Invalid state transition for ${resourceType} ${resourceId}: ${fromState} \u2192 ${toState}`,
+      "INVALID_STATE_TRANSITION",
+      { resourceType, resourceId, fromState, toState }
+    );
+  }
+};
+var SubscriptionNotActiveError = class extends StateError {
+  constructor(subscriptionId, message) {
+    super(
+      message ?? `Subscription ${subscriptionId} is not active`,
+      "SUBSCRIPTION_NOT_ACTIVE",
+      { subscriptionId }
+    );
+  }
+};
+var OperationError = class extends RevenueError {
+  constructor(message, code, options = {}) {
+    super(message, code, options);
+  }
+};
+var RefundNotSupportedError = class extends OperationError {
+  constructor(providerName) {
+    super(
+      `Refunds are not supported by provider "${providerName}"`,
+      "REFUND_NOT_SUPPORTED",
+      { retryable: false, metadata: { providerName } }
+    );
+  }
+};
+var RefundError = class extends OperationError {
+  constructor(transactionId, reason) {
+    super(
+      `Refund failed for transaction ${transactionId}: ${reason}`,
+      "REFUND_FAILED",
+      { retryable: true, metadata: { transactionId, reason } }
+    );
+  }
+};
+
+// src/utils/hooks.ts
+function triggerHook(hooks, event, data, logger) {
+  const handlers = hooks[event] ?? [];
+  if (handlers.length === 0) {
+    return;
+  }
+  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(() => {
+  });
+}
+
+// src/enums/transaction.enums.ts
+var TRANSACTION_TYPE = {
+  INCOME: "income",
+  EXPENSE: "expense"
+};
+var TRANSACTION_STATUS = {
+  VERIFIED: "verified",
+  COMPLETED: "completed",
+  CANCELLED: "cancelled"};
+var LIBRARY_CATEGORIES = {
+  SUBSCRIPTION: "subscription",
+  PURCHASE: "purchase"
+};
+
+// src/utils/category-resolver.ts
+function resolveCategory(entity, monetizationType, categoryMappings = {}) {
+  if (entity && categoryMappings[entity]) {
+    return categoryMappings[entity];
+  }
+  switch (monetizationType) {
+    case "subscription":
+      return LIBRARY_CATEGORIES.SUBSCRIPTION;
+    // 'subscription'
+    case "purchase":
+      return LIBRARY_CATEGORIES.PURCHASE;
+    // 'purchase'
+    default:
+      return LIBRARY_CATEGORIES.SUBSCRIPTION;
+  }
+}
+
+// src/utils/commission.ts
+function calculateCommission(amount, commissionRate, gatewayFeeRate = 0) {
+  if (!commissionRate || commissionRate <= 0) {
+    return null;
+  }
+  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");
+  }
+  const grossAmount = Math.round(amount * commissionRate * 100) / 100;
+  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"
+  };
+}
+function reverseCommission(originalCommission, originalAmount, refundAmount) {
+  if (!originalCommission?.netAmount) {
+    return null;
+  }
+  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
+  };
+}
+
+// src/enums/monetization.enums.ts
+var MONETIZATION_TYPES = {
+  FREE: "free",
+  PURCHASE: "purchase",
+  SUBSCRIPTION: "subscription"
+};
+
+// src/services/monetization.service.ts
+var MonetizationService = class {
+  models;
+  providers;
+  config;
+  hooks;
+  logger;
+  constructor(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");
+  }
+  /**
+   * Create a new monetization (purchase, subscription, or free item)
+   *
+   * @param params - Monetization parameters
+   *
+   * @example
+   * // One-time purchase
+   * await revenue.monetization.create({
+   *   data: {
+   *     organizationId: '...',
+   *     customerId: '...',
+   *     referenceId: order._id,
+   *     referenceModel: 'Order',
+   *   },
+   *   planKey: 'one_time',
+   *   monetizationType: 'purchase',
+   *   gateway: 'bkash',
+   *   amount: 1500,
+   * });
+   *
+   * // Recurring subscription
+   * await revenue.monetization.create({
+   *   data: {
+   *     organizationId: '...',
+   *     customerId: '...',
+   *     referenceId: subscription._id,
+   *     referenceModel: 'Subscription',
+   *   },
+   *   planKey: 'monthly',
+   *   monetizationType: 'subscription',
+   *   gateway: 'stripe',
+   *   amount: 2000,
+   * });
+   *
+   * @returns Result with subscription, transaction, and paymentIntent
+   */
+  async create(params) {
+    const {
+      data,
+      planKey,
+      amount,
+      currency = "BDT",
+      gateway = "manual",
+      entity = null,
+      monetizationType = MONETIZATION_TYPES.SUBSCRIPTION,
+      paymentData,
+      metadata = {},
+      idempotencyKey = null
+    } = params;
+    if (!planKey) {
+      throw new MissingRequiredFieldError("planKey");
+    }
+    if (amount < 0) {
+      throw new InvalidAmountError(amount);
+    }
+    const isFree = amount === 0;
+    const provider = this.providers[gateway];
+    if (!provider) {
+      throw new ProviderNotFoundError(gateway, Object.keys(this.providers));
+    }
+    let paymentIntent = null;
+    let transaction = null;
+    if (!isFree) {
+      try {
+        paymentIntent = await provider.createIntent({
+          amount,
+          currency,
+          metadata: {
+            ...metadata,
+            type: "subscription",
+            planKey
+          }
+        });
+      } catch (error) {
+        throw new PaymentIntentCreationError(gateway, error);
+      }
+      const category = resolveCategory(entity, monetizationType, this.config.categoryMappings);
+      const transactionType = this.config.transactionTypeMapping?.subscription ?? this.config.transactionTypeMapping?.[monetizationType] ?? TRANSACTION_TYPE.INCOME;
+      const commissionRate = this.config.commissionRates?.[category] ?? 0;
+      const gatewayFeeRate = this.config.gatewayFeeRates?.[gateway] ?? 0;
+      const commission = calculateCommission(amount, commissionRate, gatewayFeeRate);
+      const TransactionModel = this.models.Transaction;
+      transaction = await TransactionModel.create({
+        organizationId: data.organizationId,
+        customerId: data.customerId ?? null,
+        amount,
+        currency,
+        category,
+        type: transactionType,
+        method: paymentData?.method ?? "manual",
+        status: paymentIntent.status === "succeeded" ? "verified" : "pending",
+        gateway: {
+          type: gateway,
+          sessionId: paymentIntent.sessionId,
+          paymentIntentId: paymentIntent.paymentIntentId,
+          provider: paymentIntent.provider,
+          metadata: paymentIntent.metadata
+        },
+        paymentDetails: {
+          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,
+          entity,
+          monetizationType,
+          paymentIntentId: paymentIntent.id
+        },
+        idempotencyKey: idempotencyKey ?? `sub_${nanoid(16)}`
+      });
+    }
+    let subscription = null;
+    if (this.models.Subscription) {
+      const SubscriptionModel = this.models.Subscription;
+      const subscriptionData = {
+        organizationId: data.organizationId,
+        customerId: data.customerId ?? null,
+        planKey,
+        amount,
+        currency,
+        status: isFree ? "active" : "pending",
+        isActive: isFree,
+        gateway,
+        transactionId: transaction?._id ?? null,
+        paymentIntentId: paymentIntent?.id ?? null,
+        metadata: {
+          ...metadata,
+          isFree,
+          entity,
+          monetizationType
+        },
+        ...data
+      };
+      delete subscriptionData.referenceId;
+      delete subscriptionData.referenceModel;
+      subscription = await SubscriptionModel.create(subscriptionData);
+    }
+    const eventData = {
+      subscription,
+      transaction,
+      paymentIntent,
+      isFree,
+      monetizationType
+    };
+    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);
+    }
+    this._triggerHook("monetization.created", eventData);
+    return {
+      subscription,
+      transaction,
+      paymentIntent
+    };
+  }
+  /**
+   * Activate subscription after payment verification
+   *
+   * @param subscriptionId - Subscription ID or transaction ID
+   * @param options - Activation options
+   * @returns Updated subscription
+   */
+  async activate(subscriptionId, options = {}) {
+    const { timestamp = /* @__PURE__ */ new Date() } = options;
+    if (!this.models.Subscription) {
+      throw new ModelNotRegisteredError("Subscription");
+    }
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+    if (!subscription) {
+      throw new SubscriptionNotFoundError(subscriptionId);
+    }
+    if (subscription.isActive) {
+      this.logger.warn("Subscription already active", { subscriptionId });
+      return subscription;
+    }
+    const periodEnd = this._calculatePeriodEnd(subscription.planKey, timestamp);
+    subscription.isActive = true;
+    subscription.status = "active";
+    subscription.startDate = timestamp;
+    subscription.endDate = periodEnd;
+    subscription.activatedAt = timestamp;
+    await subscription.save();
+    this._triggerHook("subscription.activated", {
+      subscription,
+      activatedAt: timestamp
+    });
+    return subscription;
+  }
+  /**
+   * Renew subscription
+   *
+   * @param subscriptionId - Subscription ID
+   * @param params - Renewal parameters
+   * @returns { subscription, transaction, paymentIntent }
+   */
+  async renew(subscriptionId, params = {}) {
+    const {
+      gateway = "manual",
+      entity = null,
+      paymentData,
+      metadata = {},
+      idempotencyKey = null
+    } = params;
+    if (!this.models.Subscription) {
+      throw new ModelNotRegisteredError("Subscription");
+    }
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+    if (!subscription) {
+      throw new SubscriptionNotFoundError(subscriptionId);
+    }
+    if (subscription.amount === 0) {
+      throw new InvalidAmountError(0, "Free subscriptions do not require renewal");
+    }
+    const provider = this.providers[gateway];
+    if (!provider) {
+      throw new ProviderNotFoundError(gateway, Object.keys(this.providers));
+    }
+    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);
+    }
+    const effectiveEntity = entity ?? subscription.metadata?.entity;
+    const effectiveMonetizationType = subscription.metadata?.monetizationType ?? MONETIZATION_TYPES.SUBSCRIPTION;
+    const category = resolveCategory(effectiveEntity, effectiveMonetizationType, this.config.categoryMappings);
+    const transactionType = this.config.transactionTypeMapping?.subscription_renewal ?? this.config.transactionTypeMapping?.subscription ?? this.config.transactionTypeMapping?.[effectiveMonetizationType] ?? TRANSACTION_TYPE.INCOME;
+    const commissionRate = this.config.commissionRates?.[category] ?? 0;
+    const gatewayFeeRate = this.config.gatewayFeeRates?.[gateway] ?? 0;
+    const commission = calculateCommission(subscription.amount, commissionRate, gatewayFeeRate);
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.create({
+      organizationId: subscription.organizationId,
+      customerId: subscription.customerId,
+      amount: subscription.amount,
+      currency: subscription.currency ?? "BDT",
+      category,
+      type: transactionType,
+      method: paymentData?.method ?? "manual",
+      status: paymentIntent.status === "succeeded" ? "verified" : "pending",
+      gateway: {
+        type: gateway,
+        sessionId: paymentIntent.sessionId,
+        paymentIntentId: paymentIntent.paymentIntentId,
+        provider: paymentIntent.provider,
+        metadata: paymentIntent.metadata
+      },
+      paymentDetails: {
+        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(),
+        // Keep for backward compat
+        entity: effectiveEntity,
+        monetizationType: effectiveMonetizationType,
+        isRenewal: true,
+        paymentIntentId: paymentIntent.id
+      },
+      idempotencyKey: idempotencyKey ?? `renewal_${nanoid(16)}`
+    });
+    subscription.status = "pending_renewal";
+    subscription.renewalTransactionId = transaction._id;
+    subscription.renewalCount = (subscription.renewalCount ?? 0) + 1;
+    await subscription.save();
+    this._triggerHook("subscription.renewed", {
+      subscription,
+      transaction,
+      paymentIntent,
+      renewalCount: subscription.renewalCount
+    });
+    return {
+      subscription,
+      transaction,
+      paymentIntent
+    };
+  }
+  /**
+   * Cancel subscription
+   *
+   * @param subscriptionId - Subscription ID
+   * @param options - Cancellation options
+   * @returns Updated subscription
+   */
+  async cancel(subscriptionId, options = {}) {
+    const { immediate = false, reason = null } = options;
+    if (!this.models.Subscription) {
+      throw new ModelNotRegisteredError("Subscription");
+    }
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+    if (!subscription) {
+      throw new SubscriptionNotFoundError(subscriptionId);
+    }
+    const now = /* @__PURE__ */ new Date();
+    if (immediate) {
+      subscription.isActive = false;
+      subscription.status = "cancelled";
+      subscription.canceledAt = now;
+      subscription.cancellationReason = reason;
+    } else {
+      subscription.cancelAt = subscription.endDate ?? now;
+      subscription.cancellationReason = reason;
+    }
+    await subscription.save();
+    this._triggerHook("subscription.cancelled", {
+      subscription,
+      immediate,
+      reason,
+      canceledAt: immediate ? now : subscription.cancelAt
+    });
+    return subscription;
+  }
+  /**
+   * Pause subscription
+   *
+   * @param subscriptionId - Subscription ID
+   * @param options - Pause options
+   * @returns Updated subscription
+   */
+  async pause(subscriptionId, options = {}) {
+    const { reason = null } = options;
+    if (!this.models.Subscription) {
+      throw new ModelNotRegisteredError("Subscription");
+    }
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+    if (!subscription) {
+      throw new SubscriptionNotFoundError(subscriptionId);
+    }
+    if (!subscription.isActive) {
+      throw new SubscriptionNotActiveError(subscriptionId, "Only active subscriptions can be paused");
+    }
+    const pausedAt = /* @__PURE__ */ new Date();
+    subscription.isActive = false;
+    subscription.status = "paused";
+    subscription.pausedAt = pausedAt;
+    subscription.pauseReason = reason;
+    await subscription.save();
+    this._triggerHook("subscription.paused", {
+      subscription,
+      reason,
+      pausedAt
+    });
+    return subscription;
+  }
+  /**
+   * Resume subscription
+   *
+   * @param subscriptionId - Subscription ID
+   * @param options - Resume options
+   * @returns Updated subscription
+   */
+  async resume(subscriptionId, options = {}) {
+    const { extendPeriod = false } = options;
+    if (!this.models.Subscription) {
+      throw new ModelNotRegisteredError("Subscription");
+    }
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+    if (!subscription) {
+      throw new SubscriptionNotFoundError(subscriptionId);
+    }
+    if (!subscription.pausedAt) {
+      throw new InvalidStateTransitionError(
+        "resume",
+        "paused",
+        subscription.status,
+        "Only paused subscriptions can be resumed"
+      );
+    }
+    const now = /* @__PURE__ */ new Date();
+    const pausedAt = new Date(subscription.pausedAt);
+    const pauseDuration = now.getTime() - pausedAt.getTime();
+    subscription.isActive = true;
+    subscription.status = "active";
+    subscription.pausedAt = null;
+    subscription.pauseReason = null;
+    if (extendPeriod && subscription.endDate) {
+      const currentEnd = new Date(subscription.endDate);
+      subscription.endDate = new Date(currentEnd.getTime() + pauseDuration);
+    }
+    await subscription.save();
+    this._triggerHook("subscription.resumed", {
+      subscription,
+      extendPeriod,
+      pauseDuration,
+      resumedAt: now
+    });
+    return subscription;
+  }
+  /**
+   * List subscriptions with filters
+   *
+   * @param filters - Query filters
+   * @param options - Query options (limit, skip, sort)
+   * @returns Subscriptions
+   */
+  async list(filters = {}, options = {}) {
+    if (!this.models.Subscription) {
+      throw new ModelNotRegisteredError("Subscription");
+    }
+    const SubscriptionModel = this.models.Subscription;
+    const { limit = 50, skip = 0, sort = { createdAt: -1 } } = options;
+    const subscriptions = await SubscriptionModel.find(filters).limit(limit).skip(skip).sort(sort);
+    return subscriptions;
+  }
+  /**
+   * Get subscription by ID
+   *
+   * @param subscriptionId - Subscription ID
+   * @returns Subscription
+   */
+  async get(subscriptionId) {
+    if (!this.models.Subscription) {
+      throw new ModelNotRegisteredError("Subscription");
+    }
+    const SubscriptionModel = this.models.Subscription;
+    const subscription = await SubscriptionModel.findById(subscriptionId);
+    if (!subscription) {
+      throw new SubscriptionNotFoundError(subscriptionId);
+    }
+    return subscription;
+  }
+  /**
+   * Calculate period end date based on plan key
+   * @private
+   */
+  _calculatePeriodEnd(planKey, startDate = /* @__PURE__ */ new Date()) {
+    const start = new Date(startDate);
+    const end = new Date(start);
+    switch (planKey) {
+      case "monthly":
+        end.setMonth(end.getMonth() + 1);
+        break;
+      case "quarterly":
+        end.setMonth(end.getMonth() + 3);
+        break;
+      case "yearly":
+        end.setFullYear(end.getFullYear() + 1);
+        break;
+      default:
+        end.setDate(end.getDate() + 30);
+    }
+    return end;
+  }
+  /**
+   * Trigger event hook (fire-and-forget, non-blocking)
+   * @private
+   */
+  _triggerHook(event, data) {
+    triggerHook(this.hooks, event, data, this.logger);
+  }
+};
+
+// src/services/payment.service.ts
+var PaymentService = class {
+  models;
+  providers;
+  config;
+  hooks;
+  logger;
+  constructor(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");
+  }
+  /**
+   * Verify a payment
+   *
+   * @param paymentIntentId - Payment intent ID, session ID, or transaction ID
+   * @param options - Verification options
+   * @returns { transaction, status }
+   */
+  async verify(paymentIntentId, options = {}) {
+    const { verifiedBy = null } = options;
+    const TransactionModel = this.models.Transaction;
+    const transaction = await this._findTransaction(TransactionModel, paymentIntentId);
+    if (!transaction) {
+      throw new TransactionNotFoundError(paymentIntentId);
+    }
+    if (transaction.status === "verified" || transaction.status === "completed") {
+      throw new AlreadyVerifiedError(transaction._id.toString());
+    }
+    const gatewayType = transaction.gateway?.type ?? "manual";
+    const provider = this.providers[gatewayType];
+    if (!provider) {
+      throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
+    }
+    let paymentResult = null;
+    try {
+      paymentResult = await provider.verifyPayment(paymentIntentId);
+    } catch (error) {
+      this.logger.error("Payment verification failed:", error);
+      transaction.status = "failed";
+      transaction.failureReason = error.message;
+      transaction.metadata = {
+        ...transaction.metadata,
+        verificationError: error.message,
+        failedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await transaction.save();
+      this._triggerHook("payment.failed", {
+        transaction,
+        error: error.message,
+        provider: gatewayType,
+        paymentIntentId
+      });
+      throw new PaymentVerificationError(paymentIntentId, error.message);
+    }
+    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 }
+      );
+    }
+    transaction.status = paymentResult.status === "succeeded" ? "verified" : paymentResult.status;
+    transaction.verifiedAt = paymentResult.paidAt ?? /* @__PURE__ */ new Date();
+    transaction.verifiedBy = verifiedBy;
+    transaction.gateway = {
+      ...transaction.gateway,
+      type: transaction.gateway?.type ?? "manual",
+      verificationData: paymentResult.metadata
+    };
+    await transaction.save();
+    this._triggerHook("payment.verified", {
+      transaction,
+      paymentResult,
+      verifiedBy
+    });
+    return {
+      transaction,
+      paymentResult,
+      status: transaction.status
+    };
+  }
+  /**
+   * Get payment status
+   *
+   * @param paymentIntentId - Payment intent ID, session ID, or transaction ID
+   * @returns { transaction, status }
+   */
+  async getStatus(paymentIntentId) {
+    const TransactionModel = this.models.Transaction;
+    const transaction = await this._findTransaction(TransactionModel, paymentIntentId);
+    if (!transaction) {
+      throw new TransactionNotFoundError(paymentIntentId);
+    }
+    const gatewayType = transaction.gateway?.type ?? "manual";
+    const provider = this.providers[gatewayType];
+    if (!provider) {
+      throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
+    }
+    let paymentResult = null;
+    try {
+      paymentResult = await provider.getStatus(paymentIntentId);
+    } catch (error) {
+      this.logger.warn("Failed to get payment status from provider:", error);
+      return {
+        transaction,
+        status: transaction.status,
+        provider: gatewayType
+      };
+    }
+    return {
+      transaction,
+      paymentResult,
+      status: paymentResult.status,
+      provider: gatewayType
+    };
+  }
+  /**
+   * Refund a payment
+   *
+   * @param paymentId - Payment intent ID, session ID, or transaction ID
+   * @param amount - Amount to refund (optional, full refund if not provided)
+   * @param options - Refund options
+   * @returns { transaction, refundResult }
+   */
+  async refund(paymentId, amount = null, options = {}) {
+    const { reason = null } = options;
+    const TransactionModel = this.models.Transaction;
+    const transaction = await this._findTransaction(TransactionModel, paymentId);
+    if (!transaction) {
+      throw new TransactionNotFoundError(paymentId);
+    }
+    if (transaction.status !== "verified" && transaction.status !== "completed") {
+      throw new RefundError(transaction._id.toString(), "Only verified/completed transactions can be refunded");
+    }
+    const gatewayType = transaction.gateway?.type ?? "manual";
+    const provider = this.providers[gatewayType];
+    if (!provider) {
+      throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
+    }
+    const capabilities = provider.getCapabilities();
+    if (!capabilities.supportsRefunds) {
+      throw new RefundNotSupportedError(gatewayType);
+    }
+    const refundedSoFar = transaction.refundedAmount ?? 0;
+    const refundableAmount = transaction.amount - refundedSoFar;
+    const refundAmount = amount ?? refundableAmount;
+    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 }
+      );
+    }
+    let refundResult;
+    try {
+      refundResult = await provider.refund(paymentId, refundAmount, { reason: reason ?? void 0 });
+    } catch (error) {
+      this.logger.error("Refund failed:", error);
+      throw new RefundError(paymentId, error.message);
+    }
+    const refundTransactionType = this.config.transactionTypeMapping?.refund ?? TRANSACTION_TYPE.EXPENSE;
+    const refundCommission = transaction.commission ? reverseCommission(transaction.commission, transaction.amount, refundAmount) : null;
+    const refundTransaction = await TransactionModel.create({
+      organizationId: transaction.organizationId,
+      customerId: transaction.customerId,
+      amount: refundAmount,
+      currency: transaction.currency,
+      category: transaction.category,
+      type: refundTransactionType,
+      // EXPENSE - money going out
+      method: transaction.method ?? "manual",
+      status: "completed",
+      gateway: {
+        type: transaction.gateway?.type ?? "manual",
+        paymentIntentId: refundResult.id,
+        provider: refundResult.provider
+      },
+      paymentDetails: transaction.paymentDetails,
+      ...refundCommission && { commission: refundCommission },
+      // Reversed commission
+      // Polymorphic reference (copy from original transaction)
+      ...transaction.referenceId && { referenceId: transaction.referenceId },
+      ...transaction.referenceModel && { referenceModel: transaction.referenceModel },
+      metadata: {
+        ...transaction.metadata,
+        isRefund: true,
+        originalTransactionId: transaction._id.toString(),
+        refundReason: reason,
+        refundResult: refundResult.metadata
+      },
+      idempotencyKey: `refund_${transaction._id}_${Date.now()}`
+    });
+    const isPartialRefund = refundAmount < transaction.amount;
+    transaction.status = isPartialRefund ? "partially_refunded" : "refunded";
+    transaction.refundedAmount = (transaction.refundedAmount ?? 0) + refundAmount;
+    transaction.refundedAt = refundResult.refundedAt ?? /* @__PURE__ */ new Date();
+    transaction.metadata = {
+      ...transaction.metadata,
+      refundTransactionId: refundTransaction._id.toString(),
+      refundReason: reason
+    };
+    await transaction.save();
+    this._triggerHook("payment.refunded", {
+      transaction,
+      refundTransaction,
+      refundResult,
+      refundAmount,
+      reason,
+      isPartialRefund
+    });
+    return {
+      transaction,
+      refundTransaction,
+      refundResult,
+      status: transaction.status
+    };
+  }
+  /**
+   * Handle webhook from payment provider
+   *
+   * @param provider - Provider name
+   * @param payload - Webhook payload
+   * @param headers - Request headers
+   * @returns { event, transaction }
+   */
+  async handleWebhook(providerName, payload, headers = {}) {
+    const provider = this.providers[providerName];
+    if (!provider) {
+      throw new ProviderNotFoundError(providerName, Object.keys(this.providers));
+    }
+    const capabilities = provider.getCapabilities();
+    if (!capabilities.supportsWebhooks) {
+      throw new ProviderCapabilityError(providerName, "webhooks");
+    }
+    let webhookEvent;
+    try {
+      webhookEvent = await provider.handleWebhook(payload, headers);
+    } catch (error) {
+      this.logger.error("Webhook processing failed:", error);
+      throw new ProviderError(
+        `Webhook processing failed for ${providerName}: ${error.message}`,
+        "WEBHOOK_PROCESSING_FAILED",
+        { retryable: false }
+      );
+    }
+    if (!webhookEvent?.data?.sessionId && !webhookEvent?.data?.paymentIntentId) {
+      throw new ValidationError(
+        `Invalid webhook event structure from ${providerName}: missing sessionId or paymentIntentId`,
+        { provider: providerName, eventType: webhookEvent?.type }
+      );
+    }
+    const TransactionModel = this.models.Transaction;
+    let transaction = null;
+    if (webhookEvent.data.sessionId) {
+      transaction = await TransactionModel.findOne({
+        "gateway.sessionId": webhookEvent.data.sessionId
+      });
+    }
+    if (!transaction && webhookEvent.data.paymentIntentId) {
+      transaction = await TransactionModel.findOne({
+        "gateway.paymentIntentId": webhookEvent.data.paymentIntentId
+      });
+    }
+    if (!transaction) {
+      this.logger.warn("Transaction not found for webhook event", {
+        provider: providerName,
+        eventId: webhookEvent.id,
+        sessionId: webhookEvent.data.sessionId,
+        paymentIntentId: webhookEvent.data.paymentIntentId
+      });
+      throw new TransactionNotFoundError(
+        webhookEvent.data.sessionId ?? webhookEvent.data.paymentIntentId ?? "unknown"
+      );
+    }
+    if (webhookEvent.data.sessionId && !transaction.gateway?.sessionId) {
+      transaction.gateway = {
+        ...transaction.gateway,
+        type: transaction.gateway?.type ?? "manual",
+        sessionId: webhookEvent.data.sessionId
+      };
+    }
+    if (webhookEvent.data.paymentIntentId && !transaction.gateway?.paymentIntentId) {
+      transaction.gateway = {
+        ...transaction.gateway,
+        type: transaction.gateway?.type ?? "manual",
+        paymentIntentId: webhookEvent.data.paymentIntentId
+      };
+    }
+    if (transaction.webhook?.eventId === webhookEvent.id && transaction.webhook?.processedAt) {
+      this.logger.warn("Webhook already processed", {
+        transactionId: transaction._id,
+        eventId: webhookEvent.id
+      });
+      return {
+        event: webhookEvent,
+        transaction,
+        status: "already_processed"
+      };
+    }
+    transaction.webhook = {
+      eventId: webhookEvent.id,
+      eventType: webhookEvent.type,
+      receivedAt: /* @__PURE__ */ new Date(),
+      processedAt: /* @__PURE__ */ new Date(),
+      data: webhookEvent.data
+    };
+    if (webhookEvent.type === "payment.succeeded") {
+      transaction.status = "verified";
+      transaction.verifiedAt = webhookEvent.createdAt;
+    } else if (webhookEvent.type === "payment.failed") {
+      transaction.status = "failed";
+    } else if (webhookEvent.type === "refund.succeeded") {
+      transaction.status = "refunded";
+      transaction.refundedAt = webhookEvent.createdAt;
+    }
+    await transaction.save();
+    this._triggerHook(`payment.webhook.${webhookEvent.type}`, {
+      event: webhookEvent,
+      transaction
+    });
+    return {
+      event: webhookEvent,
+      transaction,
+      status: "processed"
+    };
+  }
+  /**
+   * List payments/transactions with filters
+   *
+   * @param filters - Query filters
+   * @param options - Query options (limit, skip, sort)
+   * @returns Transactions
+   */
+  async list(filters = {}, options = {}) {
+    const TransactionModel = this.models.Transaction;
+    const { limit = 50, skip = 0, sort = { createdAt: -1 } } = options;
+    const transactions = await TransactionModel.find(filters).limit(limit).skip(skip).sort(sort);
+    return transactions;
+  }
+  /**
+   * Get payment/transaction by ID
+   *
+   * @param transactionId - Transaction ID
+   * @returns Transaction
+   */
+  async get(transactionId) {
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.findById(transactionId);
+    if (!transaction) {
+      throw new TransactionNotFoundError(transactionId);
+    }
+    return transaction;
+  }
+  /**
+   * Get provider instance
+   *
+   * @param providerName - Provider name
+   * @returns Provider instance
+   */
+  getProvider(providerName) {
+    const provider = this.providers[providerName];
+    if (!provider) {
+      throw new ProviderNotFoundError(providerName, Object.keys(this.providers));
+    }
+    return provider;
+  }
+  /**
+   * Trigger event hook (fire-and-forget, non-blocking)
+   * @private
+   */
+  _triggerHook(event, data) {
+    triggerHook(this.hooks, event, data, this.logger);
+  }
+  /**
+   * Find transaction by sessionId, paymentIntentId, or transaction ID
+   * @private
+   */
+  async _findTransaction(TransactionModel, identifier) {
+    let transaction = await TransactionModel.findOne({
+      "gateway.sessionId": identifier
+    });
+    if (!transaction) {
+      transaction = await TransactionModel.findOne({
+        "gateway.paymentIntentId": identifier
+      });
+    }
+    if (!transaction) {
+      transaction = await TransactionModel.findById(identifier);
+    }
+    return transaction;
+  }
+};
+
+// src/services/transaction.service.ts
+var TransactionService = class {
+  models;
+  hooks;
+  logger;
+  constructor(container) {
+    this.models = container.get("models");
+    this.hooks = container.get("hooks");
+    this.logger = container.get("logger");
+  }
+  /**
+   * Get transaction by ID
+   *
+   * @param transactionId - Transaction ID
+   * @returns Transaction
+   */
+  async get(transactionId) {
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.findById(transactionId);
+    if (!transaction) {
+      throw new TransactionNotFoundError(transactionId);
+    }
+    return transaction;
+  }
+  /**
+   * List transactions with filters
+   *
+   * @param filters - Query filters
+   * @param options - Query options (limit, skip, sort, populate)
+   * @returns { transactions, total, page, limit }
+   */
+  async list(filters = {}, options = {}) {
+    const TransactionModel = this.models.Transaction;
+    const {
+      limit = 50,
+      skip = 0,
+      page = null,
+      sort = { createdAt: -1 },
+      populate = []
+    } = options;
+    const actualSkip = page ? (page - 1) * limit : skip;
+    let query = TransactionModel.find(filters).limit(limit).skip(actualSkip).sort(sort);
+    if (populate.length > 0 && typeof query.populate === "function") {
+      populate.forEach((field) => {
+        query = query.populate(field);
+      });
+    }
+    const transactions = await query;
+    const model = TransactionModel;
+    const total = await (model.countDocuments ? model.countDocuments(filters) : model.count?.(filters)) ?? 0;
+    return {
+      transactions,
+      total,
+      page: page ?? Math.floor(actualSkip / limit) + 1,
+      limit,
+      pages: Math.ceil(total / limit)
+    };
+  }
+  /**
+   * Update transaction
+   *
+   * @param transactionId - Transaction ID
+   * @param updates - Fields to update
+   * @returns Updated transaction
+   */
+  async update(transactionId, updates) {
+    const TransactionModel = this.models.Transaction;
+    const model = TransactionModel;
+    let transaction;
+    if (typeof model.update === "function") {
+      transaction = await model.update(transactionId, updates);
+    } else if (typeof model.findByIdAndUpdate === "function") {
+      transaction = await model.findByIdAndUpdate(
+        transactionId,
+        { $set: updates },
+        { new: true }
+      );
+    } else {
+      throw new Error("Transaction model does not support update operations");
+    }
+    if (!transaction) {
+      throw new TransactionNotFoundError(transactionId);
+    }
+    this._triggerHook("transaction.updated", {
+      transaction,
+      updates
+    });
+    return transaction;
+  }
+  /**
+   * Trigger event hook (fire-and-forget, non-blocking)
+   * @private
+   */
+  _triggerHook(event, data) {
+    triggerHook(this.hooks, event, data, this.logger);
+  }
+};
+
+// src/enums/escrow.enums.ts
+var HOLD_STATUS = {
+  HELD: "held",
+  RELEASED: "released",
+  CANCELLED: "cancelled",
+  PARTIALLY_RELEASED: "partially_released"
+};
+var RELEASE_REASON = {
+  PAYMENT_VERIFIED: "payment_verified"};
+var HOLD_REASON = {
+  PAYMENT_VERIFICATION: "payment_verification"};
+
+// src/enums/split.enums.ts
+var SPLIT_TYPE = {
+  CUSTOM: "custom"
+};
+var SPLIT_STATUS = {
+  PENDING: "pending",
+  PAID: "paid"};
+
+// src/utils/commission-split.ts
+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 ?? {}
+    };
+  });
+}
+function calculateOrganizationPayout(amount, splits = []) {
+  const totalSplitAmount = splits.reduce((sum, split) => sum + split.grossAmount, 0);
+  return Math.max(0, Math.round((amount - totalSplitAmount) * 100) / 100);
+}
+
+// src/services/escrow.service.ts
+var EscrowService = class {
+  models;
+  hooks;
+  logger;
+  constructor(container) {
+    this.models = container.get("models");
+    this.hooks = container.get("hooks");
+    this.logger = container.get("logger");
+  }
+  /**
+   * Hold funds in escrow
+   *
+   * @param transactionId - Transaction to hold
+   * @param options - Hold options
+   * @returns 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: /* @__PURE__ */ 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 transactionId - Transaction to release
+   * @param options - Release options
+   * @returns { 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: /* @__PURE__ */ 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 = /* @__PURE__ */ 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 transactionId - Transaction to cancel hold
+   * @param options - Cancel options
+   * @returns 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 = /* @__PURE__ */ 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 transactionId - Transaction to split
+   * @param splitRules - Split configuration
+   * @returns { 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 = /* @__PURE__ */ 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?.toString() ?? "",
+      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 transactionId - Transaction ID
+   * @returns 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 : false
+    };
+  }
+  _triggerHook(event, data) {
+    triggerHook(this.hooks, event, data, this.logger);
+  }
+};
+
+export { EscrowService, MonetizationService, PaymentService, TransactionService };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map