@classytic/revenue 1.0.2 → 1.1.2

package/dist/application/services/index.js

@@ -0,0 +1,3288 @@
+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/shared/utils/resilience/retry.ts
+var DEFAULT_CONFIG = {
+  maxAttempts: 3,
+  baseDelay: 1e3,
+  maxDelay: 3e4,
+  backoffMultiplier: 2,
+  jitter: 0.1,
+  retryIf: isRetryableError
+};
+function calculateDelay(attempt, config) {
+  const exponentialDelay = config.baseDelay * Math.pow(config.backoffMultiplier, attempt);
+  const cappedDelay = Math.min(exponentialDelay, config.maxDelay);
+  const jitterRange = cappedDelay * config.jitter;
+  const jitter = Math.random() * jitterRange * 2 - jitterRange;
+  return Math.round(Math.max(0, cappedDelay + jitter));
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryableError(error) {
+  if (!(error instanceof Error)) return false;
+  if (error.message.includes("ECONNREFUSED")) return true;
+  if (error.message.includes("ETIMEDOUT")) return true;
+  if (error.message.includes("ENOTFOUND")) return true;
+  if (error.message.includes("network")) return true;
+  if (error.message.includes("timeout")) return true;
+  if (error.message.includes("429")) return true;
+  if (error.message.includes("rate limit")) return true;
+  if (error.message.includes("500")) return true;
+  if (error.message.includes("502")) return true;
+  if (error.message.includes("503")) return true;
+  if (error.message.includes("504")) return true;
+  if ("retryable" in error && error.retryable === true) return true;
+  return false;
+}
+async function retry(operation, config = {}) {
+  const fullConfig = { ...DEFAULT_CONFIG, ...config };
+  const state = {
+    attempt: 0,
+    totalDelay: 0,
+    errors: []
+  };
+  while (state.attempt < fullConfig.maxAttempts) {
+    try {
+      return await operation();
+    } catch (error) {
+      state.errors.push(error instanceof Error ? error : new Error(String(error)));
+      state.attempt++;
+      const shouldRetry = fullConfig.retryIf?.(error) ?? isRetryableError(error);
+      if (!shouldRetry || state.attempt >= fullConfig.maxAttempts) {
+        throw new RetryExhaustedError(
+          `Operation failed after ${state.attempt} attempts`,
+          state.errors
+        );
+      }
+      const delay = calculateDelay(state.attempt - 1, fullConfig);
+      state.totalDelay += delay;
+      fullConfig.onRetry?.(error, state.attempt, delay);
+      await sleep(delay);
+    }
+  }
+  throw new RetryExhaustedError(
+    `Operation failed after ${state.attempt} attempts`,
+    state.errors
+  );
+}
+var RetryExhaustedError = class extends Error {
+  attempts;
+  errors;
+  constructor(message, errors) {
+    super(message);
+    this.name = "RetryExhaustedError";
+    this.attempts = errors.length;
+    this.errors = errors;
+  }
+  /**
+   * Get the last error
+   */
+  get lastError() {
+    return this.errors[this.errors.length - 1];
+  }
+  /**
+   * Get the first error
+   */
+  get firstError() {
+    return this.errors[0];
+  }
+};
+
+// src/enums/transaction.enums.ts
+var TRANSACTION_FLOW = {
+  INFLOW: "inflow",
+  OUTFLOW: "outflow"
+};
+var TRANSACTION_FLOW_VALUES = Object.values(
+  TRANSACTION_FLOW
+);
+var TRANSACTION_STATUS = {
+  PENDING: "pending",
+  PAYMENT_INITIATED: "payment_initiated",
+  PROCESSING: "processing",
+  REQUIRES_ACTION: "requires_action",
+  VERIFIED: "verified",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+  EXPIRED: "expired",
+  REFUNDED: "refunded",
+  PARTIALLY_REFUNDED: "partially_refunded"
+};
+var TRANSACTION_STATUS_VALUES = Object.values(
+  TRANSACTION_STATUS
+);
+var LIBRARY_CATEGORIES = {
+  SUBSCRIPTION: "subscription",
+  PURCHASE: "purchase"
+};
+var LIBRARY_CATEGORY_VALUES = Object.values(
+  LIBRARY_CATEGORIES
+);
+new Set(TRANSACTION_FLOW_VALUES);
+new Set(
+  TRANSACTION_STATUS_VALUES
+);
+new Set(LIBRARY_CATEGORY_VALUES);
+
+// src/shared/utils/validators/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/shared/utils/calculators/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);
+  const gatewayFeeAmount = Math.round(amount * gatewayFeeRate);
+  const netAmount = Math.max(0, grossAmount - gatewayFeeAmount);
+  return {
+    rate: commissionRate,
+    grossAmount,
+    gatewayFeeRate,
+    gatewayFeeAmount,
+    netAmount,
+    status: "pending"
+  };
+}
+function reverseCommission(originalCommission, originalAmount, refundAmount) {
+  if (!originalCommission?.netAmount) {
+    return null;
+  }
+  if (!originalAmount || originalAmount <= 0) {
+    throw new ValidationError("Original amount must be greater than 0", { originalAmount });
+  }
+  if (refundAmount < 0) {
+    throw new ValidationError("Refund amount cannot be negative", { refundAmount });
+  }
+  if (refundAmount > originalAmount) {
+    throw new ValidationError(
+      `Refund amount (${refundAmount}) exceeds original amount (${originalAmount})`,
+      { refundAmount, originalAmount }
+    );
+  }
+  const refundRatio = refundAmount / originalAmount;
+  const reversedNetAmount = Math.round(originalCommission.netAmount * refundRatio);
+  const reversedGrossAmount = Math.round(originalCommission.grossAmount * refundRatio);
+  const reversedGatewayFee = Math.round(originalCommission.gatewayFeeAmount * refundRatio);
+  return {
+    rate: originalCommission.rate,
+    grossAmount: reversedGrossAmount,
+    gatewayFeeRate: originalCommission.gatewayFeeRate,
+    gatewayFeeAmount: reversedGatewayFee,
+    netAmount: reversedNetAmount,
+    status: "waived"
+    // Commission waived due to refund
+  };
+}
+
+// src/infrastructure/config/resolver.ts
+function getCommissionRate(config, category) {
+  if (!config?.commissionRates) return 0;
+  if (category in config.commissionRates) {
+    return config.commissionRates[category];
+  }
+  return config.commissionRates["*"] ?? 0;
+}
+function getGatewayFeeRate(config, gateway) {
+  if (!config?.gatewayFeeRates) return 0;
+  if (gateway in config.gatewayFeeRates) {
+    return config.gatewayFeeRates[gateway];
+  }
+  return config.gatewayFeeRates["*"] ?? 0;
+}
+
+// src/enums/monetization.enums.ts
+var MONETIZATION_TYPES = {
+  FREE: "free",
+  PURCHASE: "purchase",
+  SUBSCRIPTION: "subscription"
+};
+var MONETIZATION_TYPE_VALUES = Object.values(
+  MONETIZATION_TYPES
+);
+new Set(MONETIZATION_TYPE_VALUES);
+
+// src/core/state-machine/StateMachine.ts
+var StateMachine = class {
+  /**
+   * @param transitions - Map of state → allowed next states
+   * @param resourceType - Type of resource (for error messages)
+   */
+  constructor(transitions, resourceType) {
+    this.transitions = transitions;
+    this.resourceType = resourceType;
+  }
+  /**
+   * Validate state transition is allowed
+   *
+   * @param from - Current state
+   * @param to - Target state
+   * @param resourceId - ID of the resource being transitioned
+   * @throws InvalidStateTransitionError if transition is invalid
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   stateMachine.validate('pending', 'completed', 'tx_123');
+   * } catch (error) {
+   *   if (error instanceof InvalidStateTransitionError) {
+   *     console.error('Invalid transition:', error.message);
+   *   }
+   * }
+   * ```
+   */
+  validate(from, to, resourceId) {
+    const allowedTransitions = this.transitions.get(from);
+    if (!allowedTransitions?.has(to)) {
+      throw new InvalidStateTransitionError(
+        this.resourceType,
+        resourceId,
+        from,
+        to
+      );
+    }
+  }
+  /**
+   * Check if transition is valid (non-throwing)
+   *
+   * @param from - Current state
+   * @param to - Target state
+   * @returns true if transition is allowed
+   *
+   * @example
+   * ```typescript
+   * if (stateMachine.canTransition('pending', 'processing')) {
+   *   // Safe to proceed with transition
+   *   transaction.status = 'processing';
+   * }
+   * ```
+   */
+  canTransition(from, to) {
+    return this.transitions.get(from)?.has(to) ?? false;
+  }
+  /**
+   * Get all allowed next states from current state
+   *
+   * @param from - Current state
+   * @returns Array of allowed next states
+   *
+   * @example
+   * ```typescript
+   * const nextStates = stateMachine.getAllowedTransitions('pending');
+   * console.log(nextStates); // ['processing', 'failed']
+   * ```
+   */
+  getAllowedTransitions(from) {
+    return Array.from(this.transitions.get(from) ?? []);
+  }
+  /**
+   * Check if state is terminal (no outgoing transitions)
+   *
+   * @param state - State to check
+   * @returns true if state has no outgoing transitions
+   *
+   * @example
+   * ```typescript
+   * stateMachine.isTerminalState('completed'); // true
+   * stateMachine.isTerminalState('pending');   // false
+   * ```
+   */
+  isTerminalState(state) {
+    const transitions = this.transitions.get(state);
+    return !transitions || transitions.size === 0;
+  }
+  /**
+   * Get the resource type this state machine manages
+   *
+   * @returns Resource type string
+   */
+  getResourceType() {
+    return this.resourceType;
+  }
+  /**
+   * Validate state transition and create audit event
+   *
+   * This is a convenience method that combines validation with audit event creation.
+   * Use this when you want to both validate a transition and record it in the audit trail.
+   *
+   * @param from - Current state
+   * @param to - Target state
+   * @param resourceId - ID of the resource being transitioned
+   * @param context - Optional audit context (who, why, metadata)
+   * @returns StateChangeEvent ready to be appended to document metadata
+   * @throws InvalidStateTransitionError if transition is invalid
+   *
+   * @example
+   * ```typescript
+   * import { appendAuditEvent } from '@classytic/revenue';
+   *
+   * // Validate and create audit event
+   * const auditEvent = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(
+   *   transaction.status,
+   *   'verified',
+   *   transaction._id.toString(),
+   *   {
+   *     changedBy: 'admin_123',
+   *     reason: 'Payment verified by payment gateway',
+   *     metadata: { verificationId: 'ver_abc' }
+   *   }
+   * );
+   *
+   * // Apply state change
+   * transaction.status = 'verified';
+   *
+   * // Append audit event to metadata
+   * Object.assign(transaction, appendAuditEvent(transaction, auditEvent));
+   *
+   * // Save
+   * await transaction.save();
+   * ```
+   */
+  validateAndCreateAuditEvent(from, to, resourceId, context) {
+    this.validate(from, to, resourceId);
+    return {
+      resourceType: this.resourceType,
+      resourceId,
+      fromState: from,
+      toState: to,
+      changedAt: /* @__PURE__ */ new Date(),
+      changedBy: context?.changedBy,
+      reason: context?.reason,
+      metadata: context?.metadata
+    };
+  }
+};
+
+// src/enums/subscription.enums.ts
+var SUBSCRIPTION_STATUS = {
+  ACTIVE: "active",
+  PAUSED: "paused",
+  CANCELLED: "cancelled",
+  EXPIRED: "expired",
+  PENDING: "pending",
+  PENDING_RENEWAL: "pending_renewal",
+  INACTIVE: "inactive"
+};
+var SUBSCRIPTION_STATUS_VALUES = Object.values(
+  SUBSCRIPTION_STATUS
+);
+var PLAN_KEYS = {
+  MONTHLY: "monthly",
+  QUARTERLY: "quarterly",
+  YEARLY: "yearly"
+};
+var PLAN_KEY_VALUES = Object.values(PLAN_KEYS);
+new Set(
+  SUBSCRIPTION_STATUS_VALUES
+);
+new Set(PLAN_KEY_VALUES);
+
+// src/enums/settlement.enums.ts
+var SETTLEMENT_STATUS = {
+  PENDING: "pending",
+  PROCESSING: "processing",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled"
+};
+var SETTLEMENT_TYPE = {
+  SPLIT_PAYOUT: "split_payout"};
+
+// src/enums/escrow.enums.ts
+var HOLD_STATUS = {
+  PENDING: "pending",
+  HELD: "held",
+  RELEASED: "released",
+  CANCELLED: "cancelled",
+  EXPIRED: "expired",
+  PARTIALLY_RELEASED: "partially_released"
+};
+var HOLD_STATUS_VALUES = Object.values(HOLD_STATUS);
+var RELEASE_REASON = {
+  PAYMENT_VERIFIED: "payment_verified",
+  MANUAL_RELEASE: "manual_release",
+  AUTO_RELEASE: "auto_release",
+  DISPUTE_RESOLVED: "dispute_resolved"
+};
+var RELEASE_REASON_VALUES = Object.values(
+  RELEASE_REASON
+);
+var HOLD_REASON = {
+  PAYMENT_VERIFICATION: "payment_verification",
+  FRAUD_CHECK: "fraud_check",
+  MANUAL_REVIEW: "manual_review",
+  DISPUTE: "dispute",
+  COMPLIANCE: "compliance"
+};
+var HOLD_REASON_VALUES = Object.values(HOLD_REASON);
+new Set(HOLD_STATUS_VALUES);
+new Set(RELEASE_REASON_VALUES);
+new Set(HOLD_REASON_VALUES);
+
+// src/enums/split.enums.ts
+var SPLIT_TYPE = {
+  PLATFORM_COMMISSION: "platform_commission",
+  AFFILIATE_COMMISSION: "affiliate_commission",
+  REFERRAL_COMMISSION: "referral_commission",
+  PARTNER_COMMISSION: "partner_commission",
+  CUSTOM: "custom"
+};
+var SPLIT_TYPE_VALUES = Object.values(SPLIT_TYPE);
+var SPLIT_STATUS = {
+  PENDING: "pending",
+  DUE: "due",
+  PAID: "paid",
+  WAIVED: "waived",
+  CANCELLED: "cancelled"
+};
+var SPLIT_STATUS_VALUES = Object.values(
+  SPLIT_STATUS
+);
+var PAYOUT_METHOD = {
+  BANK_TRANSFER: "bank_transfer",
+  MOBILE_WALLET: "mobile_wallet",
+  PLATFORM_BALANCE: "platform_balance",
+  CRYPTO: "crypto",
+  CHECK: "check",
+  MANUAL: "manual"
+};
+var PAYOUT_METHOD_VALUES = Object.values(PAYOUT_METHOD);
+new Set(SPLIT_TYPE_VALUES);
+new Set(SPLIT_STATUS_VALUES);
+new Set(PAYOUT_METHOD_VALUES);
+
+// src/core/state-machine/definitions.ts
+var TRANSACTION_STATE_MACHINE = new StateMachine(
+  /* @__PURE__ */ new Map([
+    [
+      TRANSACTION_STATUS.PENDING,
+      /* @__PURE__ */ new Set([
+        TRANSACTION_STATUS.PAYMENT_INITIATED,
+        TRANSACTION_STATUS.PROCESSING,
+        TRANSACTION_STATUS.VERIFIED,
+        // Allow direct verification (manual payments)
+        TRANSACTION_STATUS.FAILED,
+        TRANSACTION_STATUS.CANCELLED
+      ])
+    ],
+    [
+      TRANSACTION_STATUS.PAYMENT_INITIATED,
+      /* @__PURE__ */ new Set([
+        TRANSACTION_STATUS.PROCESSING,
+        TRANSACTION_STATUS.VERIFIED,
+        // Allow direct verification (webhook/instant payments)
+        TRANSACTION_STATUS.REQUIRES_ACTION,
+        TRANSACTION_STATUS.FAILED,
+        TRANSACTION_STATUS.CANCELLED
+      ])
+    ],
+    [
+      TRANSACTION_STATUS.PROCESSING,
+      /* @__PURE__ */ new Set([
+        TRANSACTION_STATUS.VERIFIED,
+        TRANSACTION_STATUS.REQUIRES_ACTION,
+        TRANSACTION_STATUS.FAILED
+      ])
+    ],
+    [
+      TRANSACTION_STATUS.REQUIRES_ACTION,
+      /* @__PURE__ */ new Set([
+        TRANSACTION_STATUS.VERIFIED,
+        TRANSACTION_STATUS.FAILED,
+        TRANSACTION_STATUS.CANCELLED,
+        TRANSACTION_STATUS.EXPIRED
+      ])
+    ],
+    [
+      TRANSACTION_STATUS.VERIFIED,
+      /* @__PURE__ */ new Set([
+        TRANSACTION_STATUS.COMPLETED,
+        TRANSACTION_STATUS.REFUNDED,
+        TRANSACTION_STATUS.PARTIALLY_REFUNDED,
+        TRANSACTION_STATUS.CANCELLED
+      ])
+    ],
+    [
+      TRANSACTION_STATUS.COMPLETED,
+      /* @__PURE__ */ new Set([
+        TRANSACTION_STATUS.REFUNDED,
+        TRANSACTION_STATUS.PARTIALLY_REFUNDED
+      ])
+    ],
+    [
+      TRANSACTION_STATUS.PARTIALLY_REFUNDED,
+      /* @__PURE__ */ new Set([TRANSACTION_STATUS.REFUNDED])
+    ],
+    // Terminal states
+    [TRANSACTION_STATUS.FAILED, /* @__PURE__ */ new Set([])],
+    [TRANSACTION_STATUS.REFUNDED, /* @__PURE__ */ new Set([])],
+    [TRANSACTION_STATUS.CANCELLED, /* @__PURE__ */ new Set([])],
+    [TRANSACTION_STATUS.EXPIRED, /* @__PURE__ */ new Set([])]
+  ]),
+  "transaction"
+);
+var SUBSCRIPTION_STATE_MACHINE = new StateMachine(
+  /* @__PURE__ */ new Map([
+    [
+      SUBSCRIPTION_STATUS.PENDING,
+      /* @__PURE__ */ new Set([
+        SUBSCRIPTION_STATUS.ACTIVE,
+        SUBSCRIPTION_STATUS.CANCELLED
+      ])
+    ],
+    [
+      SUBSCRIPTION_STATUS.ACTIVE,
+      /* @__PURE__ */ new Set([
+        SUBSCRIPTION_STATUS.PAUSED,
+        SUBSCRIPTION_STATUS.PENDING_RENEWAL,
+        SUBSCRIPTION_STATUS.CANCELLED,
+        SUBSCRIPTION_STATUS.EXPIRED
+      ])
+    ],
+    [
+      SUBSCRIPTION_STATUS.PENDING_RENEWAL,
+      /* @__PURE__ */ new Set([
+        SUBSCRIPTION_STATUS.ACTIVE,
+        SUBSCRIPTION_STATUS.CANCELLED,
+        SUBSCRIPTION_STATUS.EXPIRED
+      ])
+    ],
+    [
+      SUBSCRIPTION_STATUS.PAUSED,
+      /* @__PURE__ */ new Set([
+        SUBSCRIPTION_STATUS.ACTIVE,
+        SUBSCRIPTION_STATUS.CANCELLED
+      ])
+    ],
+    [
+      SUBSCRIPTION_STATUS.INACTIVE,
+      /* @__PURE__ */ new Set([
+        SUBSCRIPTION_STATUS.ACTIVE,
+        SUBSCRIPTION_STATUS.CANCELLED
+      ])
+    ],
+    // Terminal states
+    [SUBSCRIPTION_STATUS.CANCELLED, /* @__PURE__ */ new Set([])],
+    [SUBSCRIPTION_STATUS.EXPIRED, /* @__PURE__ */ new Set([])]
+  ]),
+  "subscription"
+);
+var SETTLEMENT_STATE_MACHINE = new StateMachine(
+  /* @__PURE__ */ new Map([
+    [
+      SETTLEMENT_STATUS.PENDING,
+      /* @__PURE__ */ new Set([
+        SETTLEMENT_STATUS.PROCESSING,
+        SETTLEMENT_STATUS.CANCELLED
+      ])
+    ],
+    [
+      SETTLEMENT_STATUS.PROCESSING,
+      /* @__PURE__ */ new Set([
+        SETTLEMENT_STATUS.COMPLETED,
+        SETTLEMENT_STATUS.FAILED
+      ])
+    ],
+    [
+      SETTLEMENT_STATUS.FAILED,
+      /* @__PURE__ */ new Set([
+        SETTLEMENT_STATUS.PENDING,
+        // Allow retry
+        SETTLEMENT_STATUS.CANCELLED
+      ])
+    ],
+    // Terminal states
+    [SETTLEMENT_STATUS.COMPLETED, /* @__PURE__ */ new Set([])],
+    [SETTLEMENT_STATUS.CANCELLED, /* @__PURE__ */ new Set([])]
+  ]),
+  "settlement"
+);
+var HOLD_STATE_MACHINE = new StateMachine(
+  /* @__PURE__ */ new Map([
+    [
+      HOLD_STATUS.HELD,
+      /* @__PURE__ */ new Set([
+        HOLD_STATUS.RELEASED,
+        HOLD_STATUS.PARTIALLY_RELEASED,
+        HOLD_STATUS.CANCELLED,
+        HOLD_STATUS.EXPIRED
+      ])
+    ],
+    [
+      HOLD_STATUS.PARTIALLY_RELEASED,
+      /* @__PURE__ */ new Set([
+        HOLD_STATUS.RELEASED,
+        HOLD_STATUS.CANCELLED
+      ])
+    ],
+    // Terminal states
+    [HOLD_STATUS.RELEASED, /* @__PURE__ */ new Set([])],
+    [HOLD_STATUS.CANCELLED, /* @__PURE__ */ new Set([])],
+    [HOLD_STATUS.EXPIRED, /* @__PURE__ */ new Set([])]
+  ]),
+  "escrow_hold"
+);
+
+// src/infrastructure/audit/types.ts
+function appendAuditEvent(document, event) {
+  const stateHistory = document.metadata?.stateHistory ?? [];
+  return {
+    ...document,
+    metadata: {
+      ...document.metadata,
+      stateHistory: [...stateHistory, event]
+    }
+  };
+}
+
+// src/application/services/monetization.service.ts
+var MonetizationService = class {
+  models;
+  providers;
+  config;
+  plugins;
+  logger;
+  events;
+  retryConfig;
+  circuitBreaker;
+  constructor(container) {
+    this.models = container.get("models");
+    this.providers = container.get("providers");
+    this.config = container.get("config");
+    this.plugins = container.get("plugins");
+    this.logger = container.get("logger");
+    this.events = container.get("events");
+    this.retryConfig = container.get("retryConfig");
+    this.circuitBreaker = container.get("circuitBreaker");
+  }
+  /**
+   * Create plugin context for hook execution
+   * @private
+   */
+  getPluginContext(idempotencyKey) {
+    return {
+      events: this.events,
+      logger: this.logger,
+      storage: /* @__PURE__ */ new Map(),
+      meta: {
+        idempotencyKey: idempotencyKey ?? void 0,
+        requestId: nanoid(),
+        timestamp: /* @__PURE__ */ new Date()
+      }
+    };
+  }
+  /**
+   * Execute provider call with retry and circuit breaker protection
+   * @private
+   */
+  async executeProviderCall(operation, operationName) {
+    const withCircuitBreaker = this.circuitBreaker ? () => this.circuitBreaker.execute(operation) : operation;
+    if (this.retryConfig && Object.keys(this.retryConfig).length > 0) {
+      return retry(withCircuitBreaker, {
+        ...this.retryConfig,
+        onRetry: (error, attempt, delay) => {
+          this.logger.warn(
+            `[${operationName}] Retry attempt ${attempt} after ${delay}ms:`,
+            error
+          );
+          this.retryConfig.onRetry?.(error, attempt, delay);
+        }
+      });
+    }
+    return withCircuitBreaker();
+  }
+  /**
+   * Create a new monetization (purchase, subscription, or free item)
+   *
+   * @param params - Monetization parameters
+   *
+   * @example
+   * // One-time purchase
+   * await revenue.monetization.create({
+   *   data: {
+   *     organizationId: '...',
+   *     customerId: '...',
+   *     sourceId: order._id,
+   *     sourceModel: 'Order',
+   *   },
+   *   planKey: 'one_time',
+   *   monetizationType: 'purchase',
+   *   gateway: 'bkash',
+   *   amount: 1500,
+   * });
+   *
+   * // Recurring subscription
+   * await revenue.monetization.create({
+   *   data: {
+   *     organizationId: '...',
+   *     customerId: '...',
+   *     sourceId: subscription._id,
+   *     sourceModel: 'Subscription',
+   *   },
+   *   planKey: 'monthly',
+   *   monetizationType: 'subscription',
+   *   gateway: 'stripe',
+   *   amount: 2000,
+   * });
+   *
+   * @returns Result with subscription, transaction, and paymentIntent
+   */
+  async create(params) {
+    return this.plugins.executeHook(
+      "monetization.create.before",
+      this.getPluginContext(params.idempotencyKey),
+      params,
+      async () => {
+        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 this.executeProviderCall(
+              () => provider.createIntent({
+                amount,
+                currency,
+                metadata: {
+                  ...metadata,
+                  type: "subscription",
+                  planKey
+                }
+              }),
+              `${gateway}.createIntent`
+            );
+          } catch (error) {
+            throw new PaymentIntentCreationError(gateway, error);
+          }
+          const category = resolveCategory(entity, monetizationType, this.config.categoryMappings);
+          const transactionFlow = this.config.transactionTypeMapping?.[category] ?? this.config.transactionTypeMapping?.[monetizationType] ?? TRANSACTION_FLOW.INFLOW;
+          const commissionRate = getCommissionRate(this.config, category);
+          const gatewayFeeRate = getGatewayFeeRate(this.config, gateway);
+          const commission = calculateCommission(amount, commissionRate, gatewayFeeRate);
+          const tax = params.tax;
+          const TransactionModel = this.models.Transaction;
+          const baseAmount = tax?.pricesIncludeTax ? tax.baseAmount : amount;
+          const feeAmount = commission?.gatewayFeeAmount || 0;
+          const taxAmount = tax?.taxAmount || 0;
+          const netAmount = baseAmount - feeAmount - taxAmount;
+          transaction = await TransactionModel.create({
+            organizationId: data.organizationId,
+            customerId: data.customerId ?? null,
+            // ✅ UNIFIED: Use category as type directly
+            type: category,
+            // 'subscription', 'purchase', etc.
+            flow: transactionFlow,
+            // ✅ Use config-driven transaction type
+            // Auto-tagging (middleware will handle, but we can set explicitly)
+            tags: category === "subscription" ? ["recurring", "subscription"] : [],
+            // ✅ UNIFIED: Amount structure
+            // When prices include tax, use baseAmount (tax already extracted)
+            amount: baseAmount,
+            currency,
+            fee: feeAmount,
+            tax: taxAmount,
+            net: netAmount,
+            // ✅ UNIFIED: Tax details (if tax plugin used)
+            ...tax && {
+              taxDetails: {
+                type: tax.type === "collected" ? "sales_tax" : tax.type === "paid" ? "vat" : "none",
+                rate: tax.rate || 0,
+                isInclusive: tax.pricesIncludeTax || false
+              }
+            },
+            method: paymentData?.method ?? "manual",
+            status: paymentIntent.status === "succeeded" ? "verified" : "pending",
+            // ✅ Map 'succeeded' to valid TransactionStatusValue
+            gateway: {
+              type: gateway,
+              // Gateway/provider type (e.g., 'stripe', 'manual')
+              provider: gateway,
+              sessionId: paymentIntent.sessionId,
+              paymentIntentId: paymentIntent.paymentIntentId,
+              chargeId: paymentIntent.id,
+              metadata: paymentIntent.metadata
+            },
+            paymentDetails: {
+              ...paymentData
+            },
+            // Commission (for marketplace/splits)
+            ...commission && { commission },
+            // ✅ UNIFIED: Source reference (renamed from reference)
+            ...data.sourceId && { sourceId: data.sourceId },
+            ...data.sourceModel && { sourceModel: data.sourceModel },
+            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 result2 = await this.plugins.executeHook(
+            "subscription.create.before",
+            this.getPluginContext(idempotencyKey),
+            {
+              subscriptionId: void 0,
+              // Not yet created - populated in after hook
+              planKey,
+              customerId: data.customerId,
+              organizationId: data.organizationId,
+              entity
+            },
+            async () => {
+              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.sourceId;
+              delete subscriptionData.sourceModel;
+              const sub = await SubscriptionModel.create(subscriptionData);
+              await this.plugins.executeHook(
+                "subscription.create.after",
+                this.getPluginContext(idempotencyKey),
+                {
+                  subscriptionId: sub._id.toString(),
+                  planKey,
+                  customerId: data.customerId,
+                  organizationId: data.organizationId,
+                  entity
+                },
+                async () => ({ subscription: sub, transaction })
+              );
+              return { subscription: sub, transaction };
+            }
+          );
+          subscription = result2.subscription;
+        }
+        this.events.emit("monetization.created", {
+          monetizationType,
+          subscription: subscription ?? void 0,
+          transaction: transaction ?? void 0,
+          paymentIntent: paymentIntent ?? void 0
+        });
+        if (monetizationType === MONETIZATION_TYPES.PURCHASE) {
+          if (transaction) {
+            this.events.emit("purchase.created", {
+              monetizationType,
+              subscription: subscription ?? void 0,
+              transaction,
+              paymentIntent: paymentIntent ?? void 0
+            });
+          }
+        } else if (monetizationType === MONETIZATION_TYPES.SUBSCRIPTION) {
+          if (subscription) {
+            this.events.emit("subscription.created", {
+              subscriptionId: subscription._id.toString(),
+              subscription,
+              transactionId: transaction?._id?.toString()
+            });
+          }
+        } else if (monetizationType === MONETIZATION_TYPES.FREE) {
+          this.events.emit("free.created", {
+            monetizationType,
+            subscription: subscription ?? void 0,
+            transaction: transaction ?? void 0,
+            paymentIntent: paymentIntent ?? void 0
+          });
+        }
+        const result = {
+          subscription,
+          transaction,
+          paymentIntent
+        };
+        return this.plugins.executeHook(
+          "monetization.create.after",
+          this.getPluginContext(params.idempotencyKey),
+          params,
+          async () => result
+        );
+      }
+    );
+  }
+  /**
+   * Activate subscription after payment verification
+   *
+   * @param subscriptionId - Subscription ID or transaction ID
+   * @param options - Activation options
+   * @returns Updated subscription
+   */
+  async activate(subscriptionId, options = {}) {
+    return this.plugins.executeHook(
+      "subscription.activate.before",
+      this.getPluginContext(),
+      { subscriptionId, ...options },
+      async () => {
+        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);
+        const auditEvent = SUBSCRIPTION_STATE_MACHINE.validateAndCreateAuditEvent(
+          subscription.status,
+          "active",
+          subscription._id.toString(),
+          {
+            changedBy: "system",
+            reason: `Subscription activated for plan: ${subscription.planKey}`,
+            metadata: { planKey: subscription.planKey, startDate: timestamp, endDate: periodEnd }
+          }
+        );
+        subscription.isActive = true;
+        subscription.status = "active";
+        subscription.startDate = timestamp;
+        subscription.endDate = periodEnd;
+        subscription.activatedAt = timestamp;
+        Object.assign(subscription, appendAuditEvent(subscription, auditEvent));
+        await subscription.save();
+        this.events.emit("subscription.activated", {
+          subscription,
+          activatedAt: timestamp
+        });
+        return this.plugins.executeHook(
+          "subscription.activate.after",
+          this.getPluginContext(),
+          { subscriptionId, ...options },
+          async () => 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 transactionFlow = this.config.transactionTypeMapping?.[category] ?? this.config.transactionTypeMapping?.subscription_renewal ?? this.config.transactionTypeMapping?.[effectiveMonetizationType] ?? TRANSACTION_FLOW.INFLOW;
+    const commissionRate = getCommissionRate(this.config, category);
+    const gatewayFeeRate = getGatewayFeeRate(this.config, gateway);
+    const commission = calculateCommission(subscription.amount, commissionRate, gatewayFeeRate);
+    const feeAmount = commission?.gatewayFeeAmount || 0;
+    const netAmount = subscription.amount - feeAmount;
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.create({
+      organizationId: subscription.organizationId,
+      customerId: subscription.customerId,
+      // ✅ UNIFIED: Use category as type directly
+      type: category,
+      // 'subscription', etc.
+      flow: transactionFlow,
+      // ✅ Use config-driven transaction type
+      tags: ["recurring", "subscription", "renewal"],
+      // ✅ UNIFIED: Amount structure
+      amount: subscription.amount,
+      currency: subscription.currency ?? "BDT",
+      fee: feeAmount,
+      tax: 0,
+      // Tax plugin would add this
+      net: netAmount,
+      method: paymentData?.method ?? "manual",
+      status: paymentIntent.status === "succeeded" ? "verified" : "pending",
+      // ✅ Map 'succeeded' to valid TransactionStatusValue
+      gateway: {
+        provider: gateway,
+        sessionId: paymentIntent.sessionId,
+        paymentIntentId: paymentIntent.paymentIntentId,
+        chargeId: paymentIntent.id,
+        metadata: paymentIntent.metadata
+      },
+      paymentDetails: {
+        provider: gateway,
+        ...paymentData
+      },
+      // Commission (for marketplace/splits)
+      ...commission && { commission },
+      // ✅ UNIFIED: Source reference (renamed from reference)
+      sourceId: subscription._id,
+      sourceModel: "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.events.emit("subscription.renewed", {
+      subscription,
+      transaction,
+      paymentIntent: paymentIntent ?? void 0,
+      renewalCount: subscription.renewalCount
+    });
+    return {
+      subscription,
+      transaction,
+      paymentIntent
+    };
+  }
+  /**
+   * Cancel subscription
+   *
+   * @param subscriptionId - Subscription ID
+   * @param options - Cancellation options
+   * @returns Updated subscription
+   */
+  async cancel(subscriptionId, options = {}) {
+    return this.plugins.executeHook(
+      "subscription.cancel.before",
+      this.getPluginContext(),
+      { subscriptionId, ...options },
+      async () => {
+        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) {
+          const auditEvent = SUBSCRIPTION_STATE_MACHINE.validateAndCreateAuditEvent(
+            subscription.status,
+            "cancelled",
+            subscription._id.toString(),
+            {
+              changedBy: "system",
+              reason: `Subscription cancelled immediately${reason ? ": " + reason : ""}`,
+              metadata: { cancellationReason: reason, immediate: true }
+            }
+          );
+          subscription.isActive = false;
+          subscription.status = "cancelled";
+          subscription.canceledAt = now;
+          subscription.cancellationReason = reason;
+          Object.assign(subscription, appendAuditEvent(subscription, auditEvent));
+        } else {
+          subscription.cancelAt = subscription.endDate ?? now;
+          subscription.cancellationReason = reason;
+        }
+        await subscription.save();
+        this.events.emit("subscription.cancelled", {
+          subscription,
+          immediate,
+          reason: reason ?? void 0,
+          canceledAt: immediate ? now : subscription.cancelAt
+        });
+        return this.plugins.executeHook(
+          "subscription.cancel.after",
+          this.getPluginContext(),
+          { subscriptionId, ...options },
+          async () => subscription
+        );
+      }
+    );
+  }
+  /**
+   * Pause subscription
+   *
+   * @param subscriptionId - Subscription ID
+   * @param options - Pause options
+   * @returns Updated subscription
+   */
+  async pause(subscriptionId, options = {}) {
+    return this.plugins.executeHook(
+      "subscription.pause.before",
+      this.getPluginContext(),
+      { subscriptionId, ...options },
+      async () => {
+        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();
+        const auditEvent = SUBSCRIPTION_STATE_MACHINE.validateAndCreateAuditEvent(
+          subscription.status,
+          "paused",
+          subscription._id.toString(),
+          {
+            changedBy: "system",
+            reason: `Subscription paused${reason ? ": " + reason : ""}`,
+            metadata: { pauseReason: reason, pausedAt }
+          }
+        );
+        subscription.isActive = false;
+        subscription.status = "paused";
+        subscription.pausedAt = pausedAt;
+        subscription.pauseReason = reason;
+        Object.assign(subscription, appendAuditEvent(subscription, auditEvent));
+        await subscription.save();
+        this.events.emit("subscription.paused", {
+          subscription,
+          reason: reason ?? void 0,
+          pausedAt
+        });
+        return this.plugins.executeHook(
+          "subscription.pause.after",
+          this.getPluginContext(),
+          { subscriptionId, ...options },
+          async () => subscription
+        );
+      }
+    );
+  }
+  /**
+   * Resume subscription
+   *
+   * @param subscriptionId - Subscription ID
+   * @param options - Resume options
+   * @returns Updated subscription
+   */
+  async resume(subscriptionId, options = {}) {
+    return this.plugins.executeHook(
+      "subscription.resume.before",
+      this.getPluginContext(),
+      { subscriptionId, ...options },
+      async () => {
+        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();
+        const auditEvent = SUBSCRIPTION_STATE_MACHINE.validateAndCreateAuditEvent(
+          subscription.status,
+          "active",
+          subscription._id.toString(),
+          {
+            changedBy: "system",
+            reason: "Subscription resumed from paused state",
+            metadata: {
+              pausedAt,
+              pauseDuration,
+              extendPeriod,
+              newEndDate: extendPeriod && subscription.endDate ? new Date(new Date(subscription.endDate).getTime() + pauseDuration) : void 0
+            }
+          }
+        );
+        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);
+        }
+        Object.assign(subscription, appendAuditEvent(subscription, auditEvent));
+        await subscription.save();
+        this.events.emit("subscription.resumed", {
+          subscription,
+          extendPeriod,
+          pauseDuration,
+          resumedAt: now
+        });
+        return this.plugins.executeHook(
+          "subscription.resume.after",
+          this.getPluginContext(),
+          { subscriptionId, ...options },
+          async () => 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;
+  }
+};
+var PaymentService = class {
+  models;
+  providers;
+  config;
+  plugins;
+  logger;
+  events;
+  retryConfig;
+  circuitBreaker;
+  constructor(container) {
+    this.models = container.get("models");
+    this.providers = container.get("providers");
+    this.config = container.get("config");
+    this.plugins = container.get("plugins");
+    this.logger = container.get("logger");
+    this.events = container.get("events");
+    this.retryConfig = container.get("retryConfig");
+    this.circuitBreaker = container.get("circuitBreaker");
+  }
+  /**
+   * Create plugin context for hook execution
+   * @private
+   */
+  getPluginContext(idempotencyKey) {
+    return {
+      events: this.events,
+      logger: this.logger,
+      storage: /* @__PURE__ */ new Map(),
+      meta: {
+        idempotencyKey,
+        requestId: nanoid(),
+        timestamp: /* @__PURE__ */ new Date()
+      }
+    };
+  }
+  /**
+   * Execute provider call with retry and circuit breaker protection
+   * @private
+   */
+  async executeProviderCall(operation, operationName) {
+    const withCircuitBreaker = this.circuitBreaker ? () => this.circuitBreaker.execute(operation) : operation;
+    if (this.retryConfig && Object.keys(this.retryConfig).length > 0) {
+      return retry(withCircuitBreaker, {
+        ...this.retryConfig,
+        onRetry: (error, attempt, delay) => {
+          this.logger.warn(
+            `[${operationName}] Retry attempt ${attempt} after ${delay}ms:`,
+            error
+          );
+          this.retryConfig.onRetry?.(error, attempt, delay);
+        }
+      });
+    }
+    return withCircuitBreaker();
+  }
+  /**
+   * Verify a payment
+   *
+   * @param paymentIntentId - Payment intent ID, session ID, or transaction ID
+   * @param options - Verification options
+   * @returns { transaction, status }
+   */
+  async verify(paymentIntentId, options = {}) {
+    return this.plugins.executeHook(
+      "payment.verify.before",
+      this.getPluginContext(),
+      { id: paymentIntentId, ...options },
+      async () => {
+        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 {
+          const actualIntentId = transaction.gateway?.paymentIntentId || transaction.gateway?.sessionId || paymentIntentId;
+          paymentResult = await this.executeProviderCall(
+            () => provider.verifyPayment(actualIntentId),
+            `${gatewayType}.verifyPayment`
+          );
+        } catch (error) {
+          this.logger.error("Payment verification failed:", error);
+          const auditEvent2 = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(
+            transaction.status,
+            "failed",
+            transaction._id.toString(),
+            {
+              changedBy: "system",
+              reason: `Payment verification failed: ${error.message}`,
+              metadata: { error: error.message }
+            }
+          );
+          transaction.status = "failed";
+          transaction.failureReason = error.message;
+          Object.assign(transaction, appendAuditEvent(transaction, auditEvent2));
+          transaction.metadata = {
+            ...transaction.metadata,
+            verificationError: error.message,
+            failedAt: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          await transaction.save();
+          this.events.emit("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 }
+          );
+        }
+        const newStatus = paymentResult.status === "succeeded" ? "verified" : paymentResult.status;
+        const auditEvent = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(
+          transaction.status,
+          newStatus,
+          transaction._id.toString(),
+          {
+            changedBy: verifiedBy ?? "system",
+            reason: `Payment verification ${paymentResult.status === "succeeded" ? "succeeded" : "resulted in status: " + newStatus}`,
+            metadata: { paymentResult: paymentResult.metadata }
+          }
+        );
+        transaction.status = newStatus;
+        transaction.verifiedAt = paymentResult.paidAt ?? /* @__PURE__ */ new Date();
+        transaction.verifiedBy = verifiedBy;
+        transaction.gateway = {
+          ...transaction.gateway,
+          type: transaction.gateway?.type ?? "manual",
+          verificationData: paymentResult.metadata
+        };
+        Object.assign(transaction, appendAuditEvent(transaction, auditEvent));
+        await transaction.save();
+        if (newStatus === "verified") {
+          this.events.emit("payment.verified", {
+            transaction,
+            paymentResult,
+            verifiedBy: verifiedBy || void 0
+          });
+        } else if (newStatus === "failed") {
+          this.events.emit("payment.failed", {
+            transaction,
+            error: paymentResult.metadata?.errorMessage || "Payment verification failed",
+            provider: gatewayType,
+            paymentIntentId: transaction.gateway?.paymentIntentId || transaction.gateway?.sessionId || paymentIntentId
+          });
+        } else if (newStatus === "requires_action") {
+          this.events.emit("payment.requires_action", {
+            transaction,
+            paymentResult,
+            action: paymentResult.metadata?.requiredAction
+          });
+        } else if (newStatus === "processing") {
+          this.events.emit("payment.processing", {
+            transaction,
+            paymentResult
+          });
+        }
+        const result = {
+          transaction,
+          paymentResult,
+          status: transaction.status
+        };
+        return this.plugins.executeHook(
+          "payment.verify.after",
+          this.getPluginContext(),
+          { id: paymentIntentId, ...options },
+          async () => result
+        );
+      }
+    );
+  }
+  /**
+   * 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 {
+      const actualIntentId = transaction.gateway?.paymentIntentId || transaction.gateway?.sessionId || paymentIntentId;
+      paymentResult = await this.executeProviderCall(
+        () => provider.getStatus(actualIntentId),
+        `${gatewayType}.getStatus`
+      );
+    } 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 = {}) {
+    return this.plugins.executeHook(
+      "payment.refund.before",
+      this.getPluginContext(),
+      { transactionId: paymentId, amount, ...options },
+      async () => {
+        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" && transaction.status !== "partially_refunded") {
+          throw new InvalidStateTransitionError(
+            "transaction",
+            transaction._id.toString(),
+            transaction.status,
+            "verified, completed, or partially_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 {
+          const actualIntentId = transaction.gateway?.paymentIntentId || transaction.gateway?.sessionId || paymentId;
+          refundResult = await this.executeProviderCall(
+            () => provider.refund(actualIntentId, refundAmount, { reason: reason ?? void 0 }),
+            `${gatewayType}.refund`
+          );
+        } catch (error) {
+          this.logger.error("Refund failed:", error);
+          throw new RefundError(paymentId, error.message);
+        }
+        const refundFlow = this.config.transactionTypeMapping?.refund ?? TRANSACTION_FLOW.OUTFLOW;
+        const refundCommission = transaction.commission ? reverseCommission(transaction.commission, transaction.amount, refundAmount) : null;
+        let refundTaxAmount = 0;
+        if (transaction.tax && transaction.tax > 0) {
+          if (transaction.amount > 0) {
+            const ratio = refundAmount / transaction.amount;
+            refundTaxAmount = Math.round(transaction.tax * ratio);
+          }
+        }
+        const refundFeeAmount = refundCommission?.gatewayFeeAmount || 0;
+        const refundNetAmount = refundAmount - refundFeeAmount - refundTaxAmount;
+        const refundTransaction = await TransactionModel.create({
+          organizationId: transaction.organizationId,
+          customerId: transaction.customerId,
+          // ✅ UNIFIED: Type = category (semantic), Flow = direction (from config)
+          type: "refund",
+          // Category: this is a refund transaction
+          flow: refundFlow,
+          // Direction: income or expense (from config)
+          tags: ["refund"],
+          // ✅ UNIFIED: Amount structure
+          amount: refundAmount,
+          currency: transaction.currency,
+          fee: refundFeeAmount,
+          tax: refundTaxAmount,
+          net: refundNetAmount,
+          // Tax details (if tax existed on original)
+          ...transaction.taxDetails && {
+            taxDetails: transaction.taxDetails
+          },
+          method: transaction.method ?? "manual",
+          status: "completed",
+          gateway: {
+            provider: transaction.gateway?.provider ?? "manual",
+            paymentIntentId: refundResult.id,
+            chargeId: refundResult.id
+          },
+          paymentDetails: transaction.paymentDetails,
+          // Reversed commission
+          ...refundCommission && { commission: refundCommission },
+          // ✅ UNIFIED: Source reference + related transaction
+          ...transaction.sourceId && { sourceId: transaction.sourceId },
+          ...transaction.sourceModel && { sourceModel: transaction.sourceModel },
+          relatedTransactionId: transaction._id,
+          // Link to original transaction
+          metadata: {
+            ...transaction.metadata,
+            isRefund: true,
+            originalTransactionId: transaction._id.toString(),
+            refundReason: reason,
+            refundResult: refundResult.metadata
+          },
+          idempotencyKey: `refund_${transaction._id}_${Date.now()}`
+        });
+        const isPartialRefund = refundAmount < refundableAmount;
+        const refundStatus = isPartialRefund ? "partially_refunded" : "refunded";
+        const auditEvent = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(
+          transaction.status,
+          refundStatus,
+          transaction._id.toString(),
+          {
+            changedBy: "system",
+            reason: `Refund processed: ${isPartialRefund ? "partial" : "full"} refund of ${refundAmount}${reason ? " - " + reason : ""}`,
+            metadata: {
+              refundAmount,
+              isPartialRefund,
+              refundTransactionId: refundTransaction._id.toString()
+            }
+          }
+        );
+        transaction.status = refundStatus;
+        transaction.refundedAmount = (transaction.refundedAmount ?? 0) + refundAmount;
+        transaction.refundedAt = refundResult.refundedAt ?? /* @__PURE__ */ new Date();
+        Object.assign(transaction, appendAuditEvent(transaction, auditEvent));
+        transaction.metadata = {
+          ...transaction.metadata,
+          refundTransactionId: refundTransaction._id.toString(),
+          refundReason: reason
+        };
+        await transaction.save();
+        this.events.emit("payment.refunded", {
+          transaction,
+          refundTransaction,
+          refundResult: {
+            ...refundResult,
+            currency: refundResult.currency ?? "USD",
+            metadata: refundResult.metadata ?? {}
+          },
+          refundAmount,
+          reason: reason ?? void 0,
+          isPartialRefund
+        });
+        const result = {
+          transaction,
+          refundTransaction,
+          refundResult,
+          status: transaction.status
+        };
+        return this.plugins.executeHook(
+          "payment.refund.after",
+          this.getPluginContext(),
+          { transactionId: paymentId, amount, ...options },
+          async () => result
+        );
+      }
+    );
+  }
+  /**
+   * 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 this.executeProviderCall(
+        () => provider.handleWebhook(payload, headers),
+        `${providerName}.handleWebhook`
+      );
+    } 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
+    };
+    let newStatus = transaction.status;
+    if (webhookEvent.type === "payment.succeeded") {
+      newStatus = "verified";
+    } else if (webhookEvent.type === "payment.failed") {
+      newStatus = "failed";
+    } else if (webhookEvent.type === "refund.succeeded") {
+      newStatus = "refunded";
+    }
+    if (newStatus !== transaction.status) {
+      const auditEvent = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(
+        transaction.status,
+        newStatus,
+        transaction._id.toString(),
+        {
+          changedBy: "webhook",
+          reason: `Webhook event: ${webhookEvent.type}`,
+          metadata: {
+            webhookId: webhookEvent.id,
+            webhookType: webhookEvent.type,
+            webhookData: webhookEvent.data
+          }
+        }
+      );
+      transaction.status = newStatus;
+      if (newStatus === "verified") {
+        transaction.verifiedAt = webhookEvent.createdAt;
+      } else if (newStatus === "refunded") {
+        transaction.refundedAt = webhookEvent.createdAt;
+      } else if (newStatus === "failed") {
+        transaction.failedAt = webhookEvent.createdAt;
+      }
+      Object.assign(transaction, appendAuditEvent(transaction, auditEvent));
+    }
+    await transaction.save();
+    this.events.emit("webhook.processed", {
+      webhookType: webhookEvent.type,
+      provider: webhookEvent.provider,
+      event: webhookEvent,
+      transaction,
+      processedAt: /* @__PURE__ */ new Date()
+    });
+    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;
+  }
+  /**
+   * 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;
+  }
+};
+var TransactionService = class {
+  models;
+  plugins;
+  events;
+  logger;
+  constructor(container) {
+    this.models = container.get("models");
+    this.plugins = container.get("plugins");
+    this.events = container.get("events");
+    this.logger = container.get("logger");
+  }
+  /**
+   * Create plugin context for hook execution
+   * @private
+   */
+  getPluginContext() {
+    return {
+      events: this.events,
+      logger: this.logger,
+      storage: /* @__PURE__ */ new Map(),
+      meta: {
+        requestId: nanoid(),
+        timestamp: /* @__PURE__ */ new Date()
+      }
+    };
+  }
+  /**
+   * 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 hookInput = { transactionId, updates };
+    return this.plugins.executeHook(
+      "transaction.update.before",
+      this.getPluginContext(),
+      hookInput,
+      async () => {
+        const TransactionModel = this.models.Transaction;
+        const effectiveUpdates = hookInput.updates;
+        const model = TransactionModel;
+        let transaction;
+        if (typeof model.update === "function") {
+          transaction = await model.update(transactionId, effectiveUpdates);
+        } else if (typeof model.findByIdAndUpdate === "function") {
+          transaction = await model.findByIdAndUpdate(
+            transactionId,
+            { $set: effectiveUpdates },
+            { new: true }
+          );
+        } else {
+          throw new Error("Transaction model does not support update operations");
+        }
+        if (!transaction) {
+          throw new TransactionNotFoundError(transactionId);
+        }
+        this.events.emit("transaction.updated", {
+          transaction,
+          updates: effectiveUpdates
+        });
+        return this.plugins.executeHook(
+          "transaction.update.after",
+          this.getPluginContext(),
+          { transactionId, updates: effectiveUpdates },
+          async () => transaction
+        );
+      }
+    );
+  }
+};
+
+// src/shared/utils/calculators/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);
+    const gatewayFeeAmount = index === 0 && gatewayFeeRate > 0 ? Math.round(amount * gatewayFeeRate) : 0;
+    const netAmount = Math.max(0, grossAmount - gatewayFeeAmount);
+    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, amount - totalSplitAmount);
+}
+
+// src/application/services/escrow.service.ts
+var EscrowService = class {
+  models;
+  plugins;
+  logger;
+  events;
+  constructor(container) {
+    this.models = container.get("models");
+    this.plugins = container.get("plugins");
+    this.logger = container.get("logger");
+    this.events = container.get("events");
+  }
+  /**
+   * Create plugin context for hook execution
+   * @private
+   */
+  getPluginContext() {
+    return {
+      events: this.events,
+      logger: this.logger,
+      storage: /* @__PURE__ */ new Map(),
+      meta: {
+        requestId: nanoid(),
+        timestamp: /* @__PURE__ */ new Date()
+      }
+    };
+  }
+  /**
+   * Hold funds in escrow
+   *
+   * @param transactionId - Transaction to hold
+   * @param options - Hold options
+   * @returns Updated transaction
+   */
+  async hold(transactionId, options = {}) {
+    return this.plugins.executeHook(
+      "escrow.hold.before",
+      this.getPluginContext(),
+      { transactionId, ...options },
+      async () => {
+        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 InvalidStateTransitionError(
+            "transaction",
+            transaction._id.toString(),
+            transaction.status,
+            TRANSACTION_STATUS.VERIFIED
+          );
+        }
+        const heldAmount = transaction.amount;
+        transaction.hold = {
+          status: HOLD_STATUS.HELD,
+          heldAmount,
+          releasedAmount: 0,
+          reason,
+          heldAt: /* @__PURE__ */ new Date(),
+          ...holdUntil && { holdUntil },
+          releases: [],
+          metadata
+        };
+        await transaction.save();
+        this.events.emit("escrow.held", {
+          transaction,
+          heldAmount,
+          reason
+        });
+        return this.plugins.executeHook(
+          "escrow.hold.after",
+          this.getPluginContext(),
+          { transactionId, ...options },
+          async () => transaction
+        );
+      }
+    );
+  }
+  /**
+   * Release funds from escrow to recipient
+   *
+   * @param transactionId - Transaction to release
+   * @param options - Release options
+   * @returns { transaction, releaseTransaction }
+   */
+  async release(transactionId, options) {
+    return this.plugins.executeHook(
+      "escrow.release.before",
+      this.getPluginContext(),
+      { transactionId, ...options },
+      async () => {
+        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 InvalidStateTransitionError(
+            "escrow_hold",
+            transaction._id.toString(),
+            transaction.hold?.status ?? "none",
+            HOLD_STATUS.HELD
+          );
+        }
+        if (!recipientId) {
+          throw new ValidationError("recipientId is required for release", { transactionId });
+        }
+        const releaseAmount = amount ?? transaction.hold.heldAmount - transaction.hold.releasedAmount;
+        const availableAmount = transaction.hold.heldAmount - transaction.hold.releasedAmount;
+        if (releaseAmount > availableAmount) {
+          throw new ValidationError(
+            `Release amount (${releaseAmount}) exceeds available held amount (${availableAmount})`,
+            { releaseAmount, availableAmount, transactionId }
+          );
+        }
+        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) {
+          const holdAuditEvent = HOLD_STATE_MACHINE.validateAndCreateAuditEvent(
+            transaction.hold.status,
+            HOLD_STATUS.RELEASED,
+            transaction._id.toString(),
+            {
+              changedBy: releasedBy ?? "system",
+              reason: `Escrow hold fully released: ${releaseAmount} to ${recipientId}${reason ? " - " + reason : ""}`,
+              metadata: { releaseAmount, recipientId, releaseReason: reason }
+            }
+          );
+          transaction.hold.status = HOLD_STATUS.RELEASED;
+          transaction.hold.releasedAt = /* @__PURE__ */ new Date();
+          const transactionAuditEvent = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(
+            transaction.status,
+            TRANSACTION_STATUS.COMPLETED,
+            transaction._id.toString(),
+            {
+              changedBy: releasedBy ?? "system",
+              reason: `Transaction completed after full escrow release`,
+              metadata: { releaseAmount, recipientId }
+            }
+          );
+          transaction.status = TRANSACTION_STATUS.COMPLETED;
+          Object.assign(transaction, appendAuditEvent(transaction, holdAuditEvent));
+          Object.assign(transaction, appendAuditEvent(transaction, transactionAuditEvent));
+        } else if (isPartialRelease) {
+          const auditEvent = HOLD_STATE_MACHINE.validateAndCreateAuditEvent(
+            transaction.hold.status,
+            HOLD_STATUS.PARTIALLY_RELEASED,
+            transaction._id.toString(),
+            {
+              changedBy: releasedBy ?? "system",
+              reason: `Partial escrow release: ${releaseAmount} of ${transaction.hold.heldAmount} to ${recipientId}${reason ? " - " + reason : ""}`,
+              metadata: {
+                releaseAmount,
+                recipientId,
+                releaseReason: reason,
+                remainingHeld: transaction.hold.heldAmount - transaction.hold.releasedAmount
+              }
+            }
+          );
+          transaction.hold.status = HOLD_STATUS.PARTIALLY_RELEASED;
+          Object.assign(transaction, appendAuditEvent(transaction, auditEvent));
+        }
+        if ("markModified" in transaction) {
+          transaction.markModified("hold");
+        }
+        await transaction.save();
+        let releaseTaxAmount = 0;
+        if (transaction.tax && transaction.tax > 0) {
+          if (releaseAmount === availableAmount && !amount) {
+            const releasedTaxSoFar = transaction.hold.releasedTaxAmount ?? 0;
+            releaseTaxAmount = transaction.tax - releasedTaxSoFar;
+          } else {
+            const totalAmount = transaction.amount + transaction.tax;
+            if (totalAmount > 0) {
+              const taxRatio = transaction.tax / totalAmount;
+              releaseTaxAmount = Math.round(releaseAmount * taxRatio);
+            }
+          }
+        }
+        const releaseNetAmount = releaseAmount - releaseTaxAmount;
+        let releaseTransaction = null;
+        if (createTransaction) {
+          releaseTransaction = await TransactionModel.create({
+            organizationId: transaction.organizationId,
+            customerId: recipientId,
+            // ✅ UNIFIED: Use 'escrow_release' as type, inflow
+            type: "escrow_release",
+            flow: "inflow",
+            tags: ["escrow", "release"],
+            // ✅ UNIFIED: Amount structure
+            amount: releaseAmount,
+            currency: transaction.currency,
+            fee: 0,
+            // No processing fees on releases
+            tax: releaseTaxAmount,
+            // ✅ Top-level number
+            net: releaseNetAmount,
+            // Copy tax details from original transaction
+            ...transaction.taxDetails && {
+              taxDetails: transaction.taxDetails
+            },
+            method: transaction.method,
+            status: "completed",
+            gateway: transaction.gateway,
+            // ✅ UNIFIED: Source reference (link to held transaction)
+            sourceId: transaction._id,
+            sourceModel: "Transaction",
+            relatedTransactionId: transaction._id,
+            metadata: {
+              ...metadata,
+              isRelease: true,
+              heldTransactionId: transaction._id.toString(),
+              releaseReason: reason,
+              recipientType,
+              // Store original category for reference
+              originalCategory: transaction.category
+            },
+            idempotencyKey: `release_${transaction._id}_${Date.now()}`
+          });
+        }
+        this.events.emit("escrow.released", {
+          transaction,
+          releaseTransaction,
+          releaseAmount,
+          recipientId,
+          recipientType,
+          reason,
+          isFullRelease,
+          isPartialRelease
+        });
+        const result = {
+          transaction,
+          releaseTransaction,
+          releaseAmount,
+          isFullRelease,
+          isPartialRelease
+        };
+        return this.plugins.executeHook(
+          "escrow.release.after",
+          this.getPluginContext(),
+          { transactionId, ...options },
+          async () => result
+        );
+      }
+    );
+  }
+  /**
+   * 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 InvalidStateTransitionError(
+        "escrow_hold",
+        transaction._id.toString(),
+        transaction.hold?.status ?? "none",
+        HOLD_STATUS.HELD
+      );
+    }
+    const holdAuditEvent = HOLD_STATE_MACHINE.validateAndCreateAuditEvent(
+      transaction.hold.status,
+      HOLD_STATUS.CANCELLED,
+      transaction._id.toString(),
+      {
+        changedBy: "system",
+        reason: `Escrow hold cancelled${reason ? ": " + reason : ""}`,
+        metadata: { cancelReason: reason, ...metadata }
+      }
+    );
+    transaction.hold.status = HOLD_STATUS.CANCELLED;
+    transaction.hold.cancelledAt = /* @__PURE__ */ new Date();
+    transaction.hold.metadata = {
+      ...transaction.hold.metadata,
+      ...metadata,
+      cancelReason: reason
+    };
+    const transactionAuditEvent = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(
+      transaction.status,
+      TRANSACTION_STATUS.CANCELLED,
+      transaction._id.toString(),
+      {
+        changedBy: "system",
+        reason: `Transaction cancelled due to escrow hold cancellation`,
+        metadata: { cancelReason: reason }
+      }
+    );
+    transaction.status = TRANSACTION_STATUS.CANCELLED;
+    Object.assign(transaction, appendAuditEvent(transaction, holdAuditEvent));
+    Object.assign(transaction, appendAuditEvent(transaction, transactionAuditEvent));
+    if ("markModified" in transaction) {
+      transaction.markModified("hold");
+    }
+    await transaction.save();
+    this.events.emit("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 InvalidStateTransitionError(
+        "escrow_hold",
+        transaction._id.toString(),
+        transaction.hold?.status ?? "none",
+        HOLD_STATUS.HELD
+      );
+    }
+    if (!splitRules || splitRules.length === 0) {
+      throw new ValidationError("splitRules cannot be empty", { transactionId });
+    }
+    const splits = calculateSplits(
+      transaction.amount,
+      splitRules,
+      transaction.commission?.gatewayFeeRate ?? 0
+    );
+    transaction.splits = splits;
+    await transaction.save();
+    const splitTransactions = [];
+    const totalTax = transaction.tax ?? 0;
+    const totalBaseAmount = transaction.amount;
+    let allocatedTaxAmount = 0;
+    const splitTaxAmounts = splits.map((split) => {
+      if (!totalTax || totalBaseAmount <= 0) {
+        return 0;
+      }
+      const ratio = split.grossAmount / totalBaseAmount;
+      const taxAmount = Math.round(totalTax * ratio);
+      allocatedTaxAmount += taxAmount;
+      return taxAmount;
+    });
+    for (const [index, split] of splits.entries()) {
+      const splitTaxAmount = totalTax > 0 ? splitTaxAmounts[index] ?? 0 : 0;
+      const splitNetAmount = split.grossAmount - split.gatewayFeeAmount - splitTaxAmount;
+      const splitTransaction = await TransactionModel.create({
+        organizationId: transaction.organizationId,
+        customerId: split.recipientId,
+        // ✅ UNIFIED: Use split type directly (commission, platform_fee, etc.)
+        type: split.type,
+        flow: "outflow",
+        // Splits are money going out
+        tags: ["split", "commission"],
+        // ✅ UNIFIED: Amount structure (gross, fee, tax, net)
+        amount: split.grossAmount,
+        // ✅ Gross amount (before deductions)
+        currency: transaction.currency,
+        fee: split.gatewayFeeAmount,
+        tax: splitTaxAmount,
+        // ✅ Top-level number
+        net: splitNetAmount,
+        // ✅ Net = gross - fee - tax
+        // Copy tax details from original transaction (if applicable)
+        ...transaction.taxDetails && splitTaxAmount > 0 && {
+          taxDetails: transaction.taxDetails
+        },
+        method: transaction.method,
+        status: "completed",
+        gateway: transaction.gateway,
+        // ✅ UNIFIED: Source reference (link to original transaction)
+        sourceId: transaction._id,
+        sourceModel: "Transaction",
+        relatedTransactionId: transaction._id,
+        metadata: {
+          isSplit: true,
+          splitType: split.type,
+          recipientType: split.recipientType,
+          originalTransactionId: transaction._id.toString(),
+          // Store split details for reference
+          splitGrossAmount: split.grossAmount,
+          splitNetAmount: split.netAmount,
+          // Original calculation
+          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 organizationTaxAmount = totalTax > 0 ? Math.max(0, totalTax - allocatedTaxAmount) : 0;
+    const organizationPayoutTotal = totalTax > 0 ? organizationPayout + organizationTaxAmount : organizationPayout;
+    const organizationTransaction = await this.release(transactionId, {
+      amount: organizationPayoutTotal,
+      recipientId: transaction.organizationId?.toString() ?? "",
+      recipientType: "organization",
+      reason: RELEASE_REASON.PAYMENT_VERIFIED,
+      createTransaction: true,
+      metadata: {
+        afterSplits: true,
+        totalSplits: splits.length,
+        totalSplitAmount: transaction.amount - organizationPayout
+      }
+    });
+    this.events.emit("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
+    };
+  }
+};
+
+// src/application/services/settlement.service.ts
+var SettlementService = class {
+  models;
+  plugins;
+  logger;
+  events;
+  constructor(container) {
+    this.models = container.get("models");
+    this.plugins = container.get("plugins");
+    this.logger = container.get("logger");
+    this.events = container.get("events");
+    void this.plugins;
+  }
+  /**
+   * Create settlements from transaction splits
+   * Typically called after escrow is released
+   *
+   * @param transactionId - Transaction ID with splits
+   * @param options - Creation options
+   * @returns Array of created settlements
+   */
+  async createFromSplits(transactionId, options = {}) {
+    const {
+      scheduledAt = /* @__PURE__ */ new Date(),
+      payoutMethod = "bank_transfer",
+      metadata = {}
+    } = options;
+    if (!this.models.Settlement) {
+      throw new ModelNotRegisteredError("Settlement");
+    }
+    const TransactionModel = this.models.Transaction;
+    const transaction = await TransactionModel.findById(transactionId);
+    if (!transaction) {
+      throw new TransactionNotFoundError(transactionId);
+    }
+    if (!transaction.splits || transaction.splits.length === 0) {
+      throw new ValidationError("Transaction has no splits to settle", { transactionId });
+    }
+    const SettlementModel = this.models.Settlement;
+    const settlements = [];
+    for (const split of transaction.splits) {
+      if (split.status === "paid") {
+        this.logger.info("Split already paid, skipping", { splitId: split._id });
+        continue;
+      }
+      const settlement = await SettlementModel.create({
+        organizationId: transaction.organizationId,
+        recipientId: split.recipientId,
+        recipientType: split.recipientType,
+        type: SETTLEMENT_TYPE.SPLIT_PAYOUT,
+        status: SETTLEMENT_STATUS.PENDING,
+        payoutMethod,
+        amount: split.netAmount,
+        currency: transaction.currency,
+        sourceTransactionIds: [transaction._id],
+        sourceSplitIds: [split._id?.toString() || ""],
+        scheduledAt,
+        metadata: {
+          ...metadata,
+          splitType: split.type,
+          transactionCategory: transaction.category
+        }
+      });
+      settlements.push(settlement);
+    }
+    this.events.emit("settlement.created", {
+      settlements,
+      transactionId,
+      count: settlements.length
+    });
+    this.logger.info("Created settlements from splits", {
+      transactionId,
+      count: settlements.length
+    });
+    return settlements;
+  }
+  /**
+   * Schedule a payout
+   *
+   * @param params - Settlement parameters
+   * @returns Created settlement
+   */
+  async schedule(params) {
+    if (!this.models.Settlement) {
+      throw new ModelNotRegisteredError("Settlement");
+    }
+    const {
+      organizationId,
+      recipientId,
+      recipientType,
+      type,
+      amount,
+      currency = "USD",
+      payoutMethod,
+      sourceTransactionIds = [],
+      sourceSplitIds = [],
+      scheduledAt = /* @__PURE__ */ new Date(),
+      bankTransferDetails,
+      mobileWalletDetails,
+      cryptoDetails,
+      notes,
+      metadata = {}
+    } = params;
+    if (amount <= 0) {
+      throw new ValidationError("Settlement amount must be positive", { amount });
+    }
+    const SettlementModel = this.models.Settlement;
+    const settlement = await SettlementModel.create({
+      organizationId,
+      recipientId,
+      recipientType,
+      type,
+      status: SETTLEMENT_STATUS.PENDING,
+      payoutMethod,
+      amount,
+      currency,
+      sourceTransactionIds,
+      sourceSplitIds,
+      scheduledAt,
+      bankTransferDetails,
+      mobileWalletDetails,
+      cryptoDetails,
+      notes,
+      metadata
+    });
+    this.events.emit("settlement.scheduled", {
+      settlement,
+      scheduledAt
+    });
+    this.logger.info("Settlement scheduled", {
+      settlementId: settlement._id,
+      recipientId,
+      amount
+    });
+    return settlement;
+  }
+  /**
+   * Process pending settlements
+   * Batch process settlements that are due
+   *
+   * @param options - Processing options
+   * @returns Processing result
+   */
+  async processPending(options = {}) {
+    if (!this.models.Settlement) {
+      throw new ModelNotRegisteredError("Settlement");
+    }
+    const {
+      limit = 100,
+      organizationId,
+      payoutMethod,
+      dryRun = false
+    } = options;
+    const SettlementModel = this.models.Settlement;
+    const query = {
+      status: SETTLEMENT_STATUS.PENDING,
+      scheduledAt: { $lte: /* @__PURE__ */ new Date() }
+    };
+    if (organizationId) query.organizationId = organizationId;
+    if (payoutMethod) query.payoutMethod = payoutMethod;
+    const settlements = await SettlementModel.find(query).limit(limit).sort({ scheduledAt: 1 });
+    const result = {
+      processed: 0,
+      succeeded: 0,
+      failed: 0,
+      settlements: [],
+      errors: []
+    };
+    if (dryRun) {
+      this.logger.info("Dry run: would process settlements", { count: settlements.length });
+      result.settlements = settlements;
+      return result;
+    }
+    for (const settlement of settlements) {
+      result.processed++;
+      try {
+        const auditEvent = SETTLEMENT_STATE_MACHINE.validateAndCreateAuditEvent(
+          settlement.status,
+          SETTLEMENT_STATUS.PROCESSING,
+          settlement._id.toString(),
+          {
+            changedBy: "system",
+            reason: "Settlement processing started",
+            metadata: { recipientId: settlement.recipientId, amount: settlement.amount }
+          }
+        );
+        settlement.status = SETTLEMENT_STATUS.PROCESSING;
+        settlement.processedAt = /* @__PURE__ */ new Date();
+        Object.assign(settlement, appendAuditEvent(settlement, auditEvent));
+        await settlement.save();
+        result.succeeded++;
+        result.settlements.push(settlement);
+        this.events.emit("settlement.processing", {
+          settlement,
+          processedAt: settlement.processedAt
+        });
+      } catch (error) {
+        result.failed++;
+        result.errors.push({
+          settlementId: settlement._id.toString(),
+          error: error.message
+        });
+        this.logger.error("Failed to process settlement", {
+          settlementId: settlement._id,
+          error
+        });
+      }
+    }
+    this.logger.info("Processed settlements", result);
+    return result;
+  }
+  /**
+   * Mark settlement as completed
+   * Call this after bank confirms the transfer
+   *
+   * @param settlementId - Settlement ID
+   * @param details - Completion details
+   * @returns Updated settlement
+   */
+  async complete(settlementId, details = {}) {
+    if (!this.models.Settlement) {
+      throw new ModelNotRegisteredError("Settlement");
+    }
+    const SettlementModel = this.models.Settlement;
+    const settlement = await SettlementModel.findById(settlementId);
+    if (!settlement) {
+      throw new ValidationError("Settlement not found", { settlementId });
+    }
+    if (settlement.status !== SETTLEMENT_STATUS.PROCESSING && settlement.status !== SETTLEMENT_STATUS.PENDING) {
+      throw new InvalidStateTransitionError(
+        "complete",
+        SETTLEMENT_STATUS.PROCESSING,
+        settlement.status,
+        "Only processing or pending settlements can be completed"
+      );
+    }
+    const {
+      transferReference,
+      transferredAt = /* @__PURE__ */ new Date(),
+      transactionHash,
+      notes,
+      metadata = {}
+    } = details;
+    const auditEvent = SETTLEMENT_STATE_MACHINE.validateAndCreateAuditEvent(
+      settlement.status,
+      SETTLEMENT_STATUS.COMPLETED,
+      settlement._id.toString(),
+      {
+        changedBy: "system",
+        reason: "Settlement completed successfully",
+        metadata: {
+          transferReference,
+          transferredAt,
+          transactionHash,
+          payoutMethod: settlement.payoutMethod,
+          amount: settlement.amount
+        }
+      }
+    );
+    settlement.status = SETTLEMENT_STATUS.COMPLETED;
+    settlement.completedAt = /* @__PURE__ */ new Date();
+    if (settlement.payoutMethod === "bank_transfer" && transferReference) {
+      settlement.bankTransferDetails = {
+        ...settlement.bankTransferDetails,
+        transferReference,
+        transferredAt
+      };
+    } else if (settlement.payoutMethod === "crypto" && transactionHash) {
+      settlement.cryptoDetails = {
+        ...settlement.cryptoDetails,
+        transactionHash,
+        transferredAt
+      };
+    } else if (settlement.payoutMethod === "mobile_wallet") {
+      settlement.mobileWalletDetails = {
+        ...settlement.mobileWalletDetails,
+        transferredAt
+      };
+    } else if (settlement.payoutMethod === "platform_balance") {
+      settlement.platformBalanceDetails = {
+        ...settlement.platformBalanceDetails,
+        appliedAt: transferredAt
+      };
+    }
+    if (notes) settlement.notes = notes;
+    settlement.metadata = { ...settlement.metadata, ...metadata };
+    Object.assign(settlement, appendAuditEvent(settlement, auditEvent));
+    await settlement.save();
+    this.events.emit("settlement.completed", {
+      settlement,
+      completedAt: settlement.completedAt
+    });
+    this.logger.info("Settlement completed", {
+      settlementId: settlement._id,
+      recipientId: settlement.recipientId,
+      amount: settlement.amount
+    });
+    return settlement;
+  }
+  /**
+   * Mark settlement as failed
+   *
+   * @param settlementId - Settlement ID
+   * @param reason - Failure reason
+   * @returns Updated settlement
+   */
+  async fail(settlementId, reason, options = {}) {
+    if (!this.models.Settlement) {
+      throw new ModelNotRegisteredError("Settlement");
+    }
+    const SettlementModel = this.models.Settlement;
+    const settlement = await SettlementModel.findById(settlementId);
+    if (!settlement) {
+      throw new ValidationError("Settlement not found", { settlementId });
+    }
+    const { code, retry: retry2 = false } = options;
+    if (retry2) {
+      const auditEvent = SETTLEMENT_STATE_MACHINE.validateAndCreateAuditEvent(
+        settlement.status,
+        SETTLEMENT_STATUS.PENDING,
+        settlement._id.toString(),
+        {
+          changedBy: "system",
+          reason: `Settlement failed, retrying: ${reason}`,
+          metadata: {
+            failureReason: reason,
+            failureCode: code,
+            retryCount: (settlement.retryCount || 0) + 1,
+            scheduledAt: new Date(Date.now() + 60 * 60 * 1e3)
+          }
+        }
+      );
+      settlement.status = SETTLEMENT_STATUS.PENDING;
+      settlement.retryCount = (settlement.retryCount || 0) + 1;
+      settlement.scheduledAt = new Date(Date.now() + 60 * 60 * 1e3);
+      Object.assign(settlement, appendAuditEvent(settlement, auditEvent));
+    } else {
+      const auditEvent = SETTLEMENT_STATE_MACHINE.validateAndCreateAuditEvent(
+        settlement.status,
+        SETTLEMENT_STATUS.FAILED,
+        settlement._id.toString(),
+        {
+          changedBy: "system",
+          reason: `Settlement failed: ${reason}`,
+          metadata: {
+            failureReason: reason,
+            failureCode: code
+          }
+        }
+      );
+      settlement.status = SETTLEMENT_STATUS.FAILED;
+      settlement.failedAt = /* @__PURE__ */ new Date();
+      Object.assign(settlement, appendAuditEvent(settlement, auditEvent));
+    }
+    settlement.failureReason = reason;
+    if (code) settlement.failureCode = code;
+    await settlement.save();
+    this.events.emit("settlement.failed", {
+      settlement,
+      reason,
+      code,
+      retry: retry2
+    });
+    this.logger.warn("Settlement failed", {
+      settlementId: settlement._id,
+      reason,
+      retry: retry2
+    });
+    return settlement;
+  }
+  /**
+   * List settlements with filters
+   *
+   * @param filters - Query filters
+   * @returns Settlements
+   */
+  async list(filters = {}) {
+    if (!this.models.Settlement) {
+      throw new ModelNotRegisteredError("Settlement");
+    }
+    const SettlementModel = this.models.Settlement;
+    const {
+      organizationId,
+      recipientId,
+      status,
+      type,
+      payoutMethod,
+      scheduledAfter,
+      scheduledBefore,
+      limit = 50,
+      skip = 0,
+      sort = { createdAt: -1 }
+    } = filters;
+    const query = {};
+    if (organizationId) query.organizationId = organizationId;
+    if (recipientId) query.recipientId = recipientId;
+    if (status) query.status = Array.isArray(status) ? { $in: status } : status;
+    if (type) query.type = type;
+    if (payoutMethod) query.payoutMethod = payoutMethod;
+    if (scheduledAfter || scheduledBefore) {
+      query.scheduledAt = {};
+      if (scheduledAfter) query.scheduledAt.$gte = scheduledAfter;
+      if (scheduledBefore) query.scheduledAt.$lte = scheduledBefore;
+    }
+    const settlements = await SettlementModel.find(query).limit(limit).skip(skip).sort(sort);
+    return settlements;
+  }
+  /**
+   * Get payout summary for recipient
+   *
+   * @param recipientId - Recipient ID
+   * @param options - Summary options
+   * @returns Settlement summary
+   */
+  async getSummary(recipientId, options = {}) {
+    if (!this.models.Settlement) {
+      throw new ModelNotRegisteredError("Settlement");
+    }
+    const { organizationId, startDate, endDate } = options;
+    const SettlementModel = this.models.Settlement;
+    const query = { recipientId };
+    if (organizationId) query.organizationId = organizationId;
+    if (startDate || endDate) {
+      query.createdAt = {};
+      if (startDate) query.createdAt.$gte = startDate;
+      if (endDate) query.createdAt.$lte = endDate;
+    }
+    const settlements = await SettlementModel.find(query);
+    const summary = {
+      recipientId,
+      totalPending: 0,
+      totalProcessing: 0,
+      totalCompleted: 0,
+      totalFailed: 0,
+      amountPending: 0,
+      amountCompleted: 0,
+      amountFailed: 0,
+      currency: settlements[0]?.currency || "USD",
+      settlements: {
+        pending: 0,
+        processing: 0,
+        completed: 0,
+        failed: 0,
+        cancelled: 0
+      }
+    };
+    for (const settlement of settlements) {
+      summary.settlements[settlement.status]++;
+      if (settlement.status === SETTLEMENT_STATUS.PENDING) {
+        summary.totalPending++;
+        summary.amountPending += settlement.amount;
+      } else if (settlement.status === SETTLEMENT_STATUS.PROCESSING) {
+        summary.totalProcessing++;
+      } else if (settlement.status === SETTLEMENT_STATUS.COMPLETED) {
+        summary.totalCompleted++;
+        summary.amountCompleted += settlement.amount;
+        if (!summary.lastSettlementDate || settlement.completedAt > summary.lastSettlementDate) {
+          summary.lastSettlementDate = settlement.completedAt;
+        }
+      } else if (settlement.status === SETTLEMENT_STATUS.FAILED) {
+        summary.totalFailed++;
+        summary.amountFailed += settlement.amount;
+      }
+    }
+    return summary;
+  }
+  /**
+   * Get settlement by ID
+   *
+   * @param settlementId - Settlement ID
+   * @returns Settlement
+   */
+  async get(settlementId) {
+    if (!this.models.Settlement) {
+      throw new ModelNotRegisteredError("Settlement");
+    }
+    const SettlementModel = this.models.Settlement;
+    const settlement = await SettlementModel.findById(settlementId);
+    if (!settlement) {
+      throw new ValidationError("Settlement not found", { settlementId });
+    }
+    return settlement;
+  }
+};
+
+export { EscrowService, MonetizationService, PaymentService, SettlementService, TransactionService };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map