@classytic/revenue 1.0.2 → 1.1.2

package/dist/core/index.js

@@ -132,12 +132,10 @@ var EventBus = class {
     this.handlers.get(event)?.delete(handler);
     this.onceHandlers.get(event)?.delete(handler);
   }
-  /**
-   * Emit an event (fire and forget, non-blocking)
-   */
-  emit(event, payload) {
+  emit(event, data) {
     const fullPayload = {
-      ...payload,
+      ...data,
+      type: event,
       timestamp: /* @__PURE__ */ new Date()
     };
     const handlers = this.handlers.get(event);
@@ -174,6 +172,7 @@ var EventBus = class {
   async emitAsync(event, payload) {
     const fullPayload = {
       ...payload,
+      type: event,
       timestamp: /* @__PURE__ */ new Date()
     };
     const promises = [];
@@ -324,19 +323,19 @@ function loggingPlugin(options = {}) {
     version: "1.0.0",
     description: "Logs all revenue operations",
     hooks: {
-      "payment.create.before": async (ctx, input, next) => {
+      "payment.create.after": async (ctx, input, next) => {
         ctx.logger[level]("Creating payment", { amount: input.amount, currency: input.currency });
         const result = await next();
-        ctx.logger[level]("Payment created", { transactionId: result?.transactionId });
+        ctx.logger[level]("Payment created", { paymentIntentId: result?.paymentIntentId });
         return result;
       },
-      "payment.verify.before": async (ctx, input, next) => {
+      "payment.verify.after": async (ctx, input, next) => {
         ctx.logger[level]("Verifying payment", { id: input.id });
         const result = await next();
         ctx.logger[level]("Payment verified", { verified: result?.verified });
         return result;
       },
-      "payment.refund.before": async (ctx, input, next) => {
+      "payment.refund.after": async (ctx, input, next) => {
         ctx.logger[level]("Processing refund", { transactionId: input.transactionId, amount: input.amount });
         const result = await next();
         ctx.logger[level]("Refund processed", { refundId: result?.refundId });
@@ -569,16 +568,29 @@ var IdempotencyManager = class {
   }
   /**
    * Hash request parameters for validation
+   * Uses deterministic JSON serialization and simple hash function
    */
   hashRequest(params) {
-    const json = JSON.stringify(params, Object.keys(params).sort());
+    let normalized;
+    if (params === null || params === void 0) {
+      normalized = null;
+    } else if (typeof params === "object" && !Array.isArray(params)) {
+      const sortedKeys = Object.keys(params).sort();
+      normalized = sortedKeys.reduce((acc, key) => {
+        acc[key] = params[key];
+        return acc;
+      }, {});
+    } else {
+      normalized = params;
+    }
+    const json = JSON.stringify(normalized);
     let hash = 0;
     for (let i = 0; i < json.length; i++) {
       const char = json.charCodeAt(i);
       hash = (hash << 5) - hash + char;
       hash = hash & hash;
     }
-    return hash.toString(36);
+    return Math.abs(hash).toString(36);
   }
   /**
    * Execute operation with idempotency protection
@@ -651,12 +663,21 @@ var IdempotencyManager = class {
     const fullKey = key.startsWith(this.prefix) ? key : `${this.prefix}${key}`;
     await this.store.delete(fullKey);
   }
+  /**
+   * Destroy the idempotency manager and cleanup resources
+   * Call this when shutting down to prevent memory leaks
+   */
+  destroy() {
+    if (this.store instanceof MemoryIdempotencyStore) {
+      this.store.destroy();
+    }
+  }
 };
 function createIdempotencyManager(config) {
   return new IdempotencyManager(config);
 }
 
-// src/utils/retry.ts
+// src/shared/utils/resilience/retry.ts
 var DEFAULT_CONFIG = {
   maxAttempts: 3,
   baseDelay: 1e3,
@@ -1059,43 +1080,44 @@ function isRevenueError(error) {
   return error instanceof RevenueError;
 }
 
-// src/utils/hooks.ts
-function triggerHook(hooks, event, data, logger) {
-  const handlers = hooks[event] ?? [];
-  if (handlers.length === 0) {
-    return;
-  }
-  Promise.all(
-    handlers.map(
-      (handler) => Promise.resolve(handler(data)).catch((error) => {
-        logger.error(`Hook "${event}" failed:`, {
-          error: error.message,
-          stack: error.stack,
-          event,
-          // Don't log full data (could be huge)
-          dataKeys: Object.keys(data)
-        });
-      })
-    )
-  ).catch(() => {
-  });
-}
-
 // src/enums/transaction.enums.ts
-var TRANSACTION_TYPE = {
-  INCOME: "income",
-  EXPENSE: "expense"
+var TRANSACTION_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",
-  CANCELLED: "cancelled"};
+  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/utils/category-resolver.ts
+// src/shared/utils/validators/category-resolver.ts
 function resolveCategory(entity, monetizationType, categoryMappings = {}) {
   if (entity && categoryMappings[entity]) {
     return categoryMappings[entity];
@@ -1112,7 +1134,7 @@ function resolveCategory(entity, monetizationType, categoryMappings = {}) {
   }
 }
 
-// src/utils/commission.ts
+// src/shared/utils/calculators/commission.ts
 function calculateCommission(amount, commissionRate, gatewayFeeRate = 0) {
   if (!commissionRate || commissionRate <= 0) {
     return null;
@@ -1126,9 +1148,9 @@ function calculateCommission(amount, commissionRate, gatewayFeeRate = 0) {
   if (gatewayFeeRate < 0 || gatewayFeeRate > 1) {
     throw new Error("Gateway fee rate must be between 0 and 1");
   }
-  const grossAmount = Math.round(amount * commissionRate * 100) / 100;
-  const gatewayFeeAmount = Math.round(amount * gatewayFeeRate * 100) / 100;
-  const netAmount = Math.max(0, Math.round((grossAmount - gatewayFeeAmount) * 100) / 100);
+  const grossAmount = Math.round(amount * commissionRate);
+  const gatewayFeeAmount = Math.round(amount * gatewayFeeRate);
+  const netAmount = Math.max(0, grossAmount - gatewayFeeAmount);
   return {
     rate: commissionRate,
     grossAmount,
@@ -1142,10 +1164,22 @@ 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 * 100) / 100;
-  const reversedGrossAmount = Math.round(originalCommission.grossAmount * refundRatio * 100) / 100;
-  const reversedGatewayFee = Math.round(originalCommission.gatewayFeeAmount * refundRatio * 100) / 100;
+  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,
@@ -1157,26 +1191,566 @@ function reverseCommission(originalCommission, originalAmount, refundAmount) {
   };
 }
 
+// src/infrastructure/config/resolver.ts
+function resolveConfig(options) {
+  const config = {
+    targetModels: [],
+    categoryMappings: {}
+  };
+  if (options.commissionRate !== void 0) {
+    config.commissionRates = {
+      "*": options.commissionRate
+      // Global default for all categories
+    };
+  }
+  if (options.gatewayFeeRate !== void 0) {
+    config.gatewayFeeRates = {
+      "*": options.gatewayFeeRate
+      // Global default for all gateways
+    };
+  }
+  return config;
+}
+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"
+);
+var SPLIT_STATE_MACHINE = new StateMachine(
+  /* @__PURE__ */ new Map([
+    [
+      SPLIT_STATUS.PENDING,
+      /* @__PURE__ */ new Set([
+        SPLIT_STATUS.DUE,
+        SPLIT_STATUS.PAID,
+        SPLIT_STATUS.WAIVED,
+        SPLIT_STATUS.CANCELLED
+      ])
+    ],
+    [
+      SPLIT_STATUS.DUE,
+      /* @__PURE__ */ new Set([
+        SPLIT_STATUS.PAID,
+        SPLIT_STATUS.WAIVED,
+        SPLIT_STATUS.CANCELLED
+      ])
+    ],
+    // Terminal states
+    [SPLIT_STATUS.PAID, /* @__PURE__ */ new Set([])],
+    [SPLIT_STATUS.WAIVED, /* @__PURE__ */ new Set([])],
+    [SPLIT_STATUS.CANCELLED, /* @__PURE__ */ new Set([])]
+  ]),
+  "split"
+);
+
+// src/infrastructure/audit/types.ts
+function appendAuditEvent(document, event) {
+  const stateHistory = document.metadata?.stateHistory ?? [];
+  return {
+    ...document,
+    metadata: {
+      ...document.metadata,
+      stateHistory: [...stateHistory, event]
+    }
+  };
+}
 
-// src/services/monetization.service.ts
+// src/application/services/monetization.service.ts
 var MonetizationService = class {
   models;
   providers;
   config;
-  hooks;
+  plugins;
   logger;
+  events;
+  retryConfig;
+  circuitBreaker;
   constructor(container) {
     this.models = container.get("models");
     this.providers = container.get("providers");
     this.config = container.get("config");
-    this.hooks = container.get("hooks");
+    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)
@@ -1189,8 +1763,8 @@ var MonetizationService = class {
    *   data: {
    *     organizationId: '...',
    *     customerId: '...',
-   *     referenceId: order._id,
-   *     referenceModel: 'Order',
+   *     sourceId: order._id,
+   *     sourceModel: 'Order',
    *   },
    *   planKey: 'one_time',
    *   monetizationType: 'purchase',
@@ -1203,8 +1777,8 @@ var MonetizationService = class {
    *   data: {
    *     organizationId: '...',
    *     customerId: '...',
-   *     referenceId: subscription._id,
-   *     referenceModel: 'Subscription',
+   *     sourceId: subscription._id,
+   *     sourceModel: 'Subscription',
    *   },
    *   planKey: 'monthly',
    *   monetizationType: 'subscription',
@@ -1215,132 +1789,217 @@ var MonetizationService = class {
    * @returns Result with subscription, transaction, and paymentIntent
    */
   async create(params) {
-    const {
-      data,
-      planKey,
-      amount,
-      currency = "BDT",
-      gateway = "manual",
-      entity = null,
-      monetizationType = MONETIZATION_TYPES.SUBSCRIPTION,
-      paymentData,
-      metadata = {},
-      idempotencyKey = null
-    } = params;
-    if (!planKey) {
-      throw new MissingRequiredFieldError("planKey");
-    }
-    if (amount < 0) {
-      throw new InvalidAmountError(amount);
-    }
-    const isFree = amount === 0;
-    const provider = this.providers[gateway];
-    if (!provider) {
-      throw new ProviderNotFoundError(gateway, Object.keys(this.providers));
-    }
-    let paymentIntent = null;
-    let transaction = null;
-    if (!isFree) {
-      try {
-        paymentIntent = await provider.createIntent({
+    return this.plugins.executeHook(
+      "monetization.create.before",
+      this.getPluginContext(params.idempotencyKey),
+      params,
+      async () => {
+        const {
+          data,
+          planKey,
           amount,
-          currency,
-          metadata: {
-            ...metadata,
-            type: "subscription",
-            planKey
+          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
         });
-      } catch (error) {
-        throw new PaymentIntentCreationError(gateway, error);
+        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
+        );
       }
-      const category = resolveCategory(entity, monetizationType, this.config.categoryMappings);
-      const transactionType = this.config.transactionTypeMapping?.subscription ?? this.config.transactionTypeMapping?.[monetizationType] ?? TRANSACTION_TYPE.INCOME;
-      const commissionRate = this.config.commissionRates?.[category] ?? 0;
-      const gatewayFeeRate = this.config.gatewayFeeRates?.[gateway] ?? 0;
-      const commission = calculateCommission(amount, commissionRate, gatewayFeeRate);
-      const TransactionModel = this.models.Transaction;
-      transaction = await TransactionModel.create({
-        organizationId: data.organizationId,
-        customerId: data.customerId ?? null,
-        amount,
-        currency,
-        category,
-        type: transactionType,
-        method: paymentData?.method ?? "manual",
-        status: paymentIntent.status === "succeeded" ? "verified" : "pending",
-        gateway: {
-          type: gateway,
-          sessionId: paymentIntent.sessionId,
-          paymentIntentId: paymentIntent.paymentIntentId,
-          provider: paymentIntent.provider,
-          metadata: paymentIntent.metadata
-        },
-        paymentDetails: {
-          provider: gateway,
-          ...paymentData
-        },
-        ...commission && { commission },
-        // Only include if commission exists
-        // Polymorphic reference (top-level, not metadata)
-        ...data.referenceId && { referenceId: data.referenceId },
-        ...data.referenceModel && { referenceModel: data.referenceModel },
-        metadata: {
-          ...metadata,
-          planKey,
-          entity,
-          monetizationType,
-          paymentIntentId: paymentIntent.id
-        },
-        idempotencyKey: idempotencyKey ?? `sub_${nanoid(16)}`
-      });
-    }
-    let subscription = null;
-    if (this.models.Subscription) {
-      const SubscriptionModel = this.models.Subscription;
-      const subscriptionData = {
-        organizationId: data.organizationId,
-        customerId: data.customerId ?? null,
-        planKey,
-        amount,
-        currency,
-        status: isFree ? "active" : "pending",
-        isActive: isFree,
-        gateway,
-        transactionId: transaction?._id ?? null,
-        paymentIntentId: paymentIntent?.id ?? null,
-        metadata: {
-          ...metadata,
-          isFree,
-          entity,
-          monetizationType
-        },
-        ...data
-      };
-      delete subscriptionData.referenceId;
-      delete subscriptionData.referenceModel;
-      subscription = await SubscriptionModel.create(subscriptionData);
-    }
-    const eventData = {
-      subscription,
-      transaction,
-      paymentIntent,
-      isFree,
-      monetizationType
-    };
-    if (monetizationType === MONETIZATION_TYPES.PURCHASE) {
-      this._triggerHook("purchase.created", eventData);
-    } else if (monetizationType === MONETIZATION_TYPES.SUBSCRIPTION) {
-      this._triggerHook("subscription.created", eventData);
-    } else if (monetizationType === MONETIZATION_TYPES.FREE) {
-      this._triggerHook("free.created", eventData);
-    }
-    this._triggerHook("monetization.created", eventData);
-    return {
-      subscription,
-      transaction,
-      paymentIntent
-    };
+    );
   }
   /**
    * Activate subscription after payment verification
@@ -1350,31 +2009,54 @@ var MonetizationService = class {
    * @returns Updated subscription
    */
   async activate(subscriptionId, options = {}) {
-    const { timestamp = /* @__PURE__ */ new Date() } = options;
-    if (!this.models.Subscription) {
-      throw new ModelNotRegisteredError("Subscription");
-    }
-    const SubscriptionModel = this.models.Subscription;
-    const subscription = await SubscriptionModel.findById(subscriptionId);
-    if (!subscription) {
-      throw new SubscriptionNotFoundError(subscriptionId);
-    }
-    if (subscription.isActive) {
-      this.logger.warn("Subscription already active", { subscriptionId });
-      return subscription;
-    }
-    const periodEnd = this._calculatePeriodEnd(subscription.planKey, timestamp);
-    subscription.isActive = true;
-    subscription.status = "active";
-    subscription.startDate = timestamp;
-    subscription.endDate = periodEnd;
-    subscription.activatedAt = timestamp;
-    await subscription.save();
-    this._triggerHook("subscription.activated", {
-      subscription,
-      activatedAt: timestamp
-    });
-    return subscription;
+    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
@@ -1424,36 +2106,48 @@ var MonetizationService = class {
     const effectiveEntity = entity ?? subscription.metadata?.entity;
     const effectiveMonetizationType = subscription.metadata?.monetizationType ?? MONETIZATION_TYPES.SUBSCRIPTION;
     const category = resolveCategory(effectiveEntity, effectiveMonetizationType, this.config.categoryMappings);
-    const transactionType = this.config.transactionTypeMapping?.subscription_renewal ?? this.config.transactionTypeMapping?.subscription ?? this.config.transactionTypeMapping?.[effectiveMonetizationType] ?? TRANSACTION_TYPE.INCOME;
-    const commissionRate = this.config.commissionRates?.[category] ?? 0;
-    const gatewayFeeRate = this.config.gatewayFeeRates?.[gateway] ?? 0;
+    const 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",
-      category,
-      type: transactionType,
+      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: {
-        type: gateway,
+        provider: gateway,
         sessionId: paymentIntent.sessionId,
         paymentIntentId: paymentIntent.paymentIntentId,
-        provider: paymentIntent.provider,
+        chargeId: paymentIntent.id,
         metadata: paymentIntent.metadata
       },
       paymentDetails: {
         provider: gateway,
         ...paymentData
       },
+      // Commission (for marketplace/splits)
       ...commission && { commission },
-      // Only include if commission exists
-      // Polymorphic reference to subscription
-      referenceId: subscription._id,
-      referenceModel: "Subscription",
+      // ✅ UNIFIED: Source reference (renamed from reference)
+      sourceId: subscription._id,
+      sourceModel: "Subscription",
       metadata: {
         ...metadata,
         subscriptionId: subscription._id.toString(),
@@ -1469,10 +2163,10 @@ var MonetizationService = class {
     subscription.renewalTransactionId = transaction._id;
     subscription.renewalCount = (subscription.renewalCount ?? 0) + 1;
     await subscription.save();
-    this._triggerHook("subscription.renewed", {
+    this.events.emit("subscription.renewed", {
       subscription,
       transaction,
-      paymentIntent,
+      paymentIntent: paymentIntent ?? void 0,
       renewalCount: subscription.renewalCount
     });
     return {
@@ -1489,33 +2183,56 @@ var MonetizationService = class {
    * @returns Updated subscription
    */
   async cancel(subscriptionId, options = {}) {
-    const { immediate = false, reason = null } = options;
-    if (!this.models.Subscription) {
-      throw new ModelNotRegisteredError("Subscription");
-    }
-    const SubscriptionModel = this.models.Subscription;
-    const subscription = await SubscriptionModel.findById(subscriptionId);
-    if (!subscription) {
-      throw new SubscriptionNotFoundError(subscriptionId);
-    }
-    const now = /* @__PURE__ */ new Date();
-    if (immediate) {
-      subscription.isActive = false;
-      subscription.status = "cancelled";
-      subscription.canceledAt = now;
-      subscription.cancellationReason = reason;
-    } else {
-      subscription.cancelAt = subscription.endDate ?? now;
-      subscription.cancellationReason = reason;
-    }
-    await subscription.save();
-    this._triggerHook("subscription.cancelled", {
-      subscription,
-      immediate,
-      reason,
-      canceledAt: immediate ? now : subscription.cancelAt
-    });
-    return subscription;
+    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
@@ -1525,30 +2242,53 @@ var MonetizationService = class {
    * @returns Updated subscription
    */
   async pause(subscriptionId, options = {}) {
-    const { reason = null } = options;
-    if (!this.models.Subscription) {
-      throw new ModelNotRegisteredError("Subscription");
-    }
-    const SubscriptionModel = this.models.Subscription;
-    const subscription = await SubscriptionModel.findById(subscriptionId);
-    if (!subscription) {
-      throw new SubscriptionNotFoundError(subscriptionId);
-    }
-    if (!subscription.isActive) {
-      throw new SubscriptionNotActiveError(subscriptionId, "Only active subscriptions can be paused");
-    }
-    const pausedAt = /* @__PURE__ */ new Date();
-    subscription.isActive = false;
-    subscription.status = "paused";
-    subscription.pausedAt = pausedAt;
-    subscription.pauseReason = reason;
-    await subscription.save();
-    this._triggerHook("subscription.paused", {
-      subscription,
-      reason,
-      pausedAt
-    });
-    return subscription;
+    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
@@ -1558,42 +2298,70 @@ var MonetizationService = class {
    * @returns Updated subscription
    */
   async resume(subscriptionId, options = {}) {
-    const { extendPeriod = false } = options;
-    if (!this.models.Subscription) {
-      throw new ModelNotRegisteredError("Subscription");
-    }
-    const SubscriptionModel = this.models.Subscription;
-    const subscription = await SubscriptionModel.findById(subscriptionId);
-    if (!subscription) {
-      throw new SubscriptionNotFoundError(subscriptionId);
-    }
-    if (!subscription.pausedAt) {
-      throw new InvalidStateTransitionError(
-        "resume",
-        "paused",
-        subscription.status,
-        "Only paused subscriptions can be resumed"
-      );
-    }
-    const now = /* @__PURE__ */ new Date();
-    const pausedAt = new Date(subscription.pausedAt);
-    const pauseDuration = now.getTime() - pausedAt.getTime();
-    subscription.isActive = true;
-    subscription.status = "active";
-    subscription.pausedAt = null;
-    subscription.pauseReason = null;
-    if (extendPeriod && subscription.endDate) {
-      const currentEnd = new Date(subscription.endDate);
-      subscription.endDate = new Date(currentEnd.getTime() + pauseDuration);
-    }
-    await subscription.save();
-    this._triggerHook("subscription.resumed", {
-      subscription,
-      extendPeriod,
-      pauseDuration,
-      resumedAt: now
-    });
-    return subscription;
+    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
@@ -1650,28 +2418,61 @@ var MonetizationService = class {
     }
     return end;
   }
-  /**
-   * Trigger event hook (fire-and-forget, non-blocking)
-   * @private
-   */
-  _triggerHook(event, data) {
-    triggerHook(this.hooks, event, data, this.logger);
-  }
 };
-
-// src/services/payment.service.ts
 var PaymentService = class {
   models;
   providers;
   config;
-  hooks;
+  plugins;
   logger;
+  events;
+  retryConfig;
+  circuitBreaker;
   constructor(container) {
     this.models = container.get("models");
     this.providers = container.get("providers");
     this.config = container.get("config");
-    this.hooks = container.get("hooks");
+    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
@@ -1681,72 +2482,132 @@ var PaymentService = class {
    * @returns { transaction, status }
    */
   async verify(paymentIntentId, options = {}) {
-    const { verifiedBy = null } = options;
-    const TransactionModel = this.models.Transaction;
-    const transaction = await this._findTransaction(TransactionModel, paymentIntentId);
-    if (!transaction) {
-      throw new TransactionNotFoundError(paymentIntentId);
-    }
-    if (transaction.status === "verified" || transaction.status === "completed") {
-      throw new AlreadyVerifiedError(transaction._id.toString());
-    }
-    const gatewayType = transaction.gateway?.type ?? "manual";
-    const provider = this.providers[gatewayType];
-    if (!provider) {
-      throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
-    }
-    let paymentResult = null;
-    try {
-      paymentResult = await provider.verifyPayment(paymentIntentId);
-    } catch (error) {
-      this.logger.error("Payment verification failed:", error);
-      transaction.status = "failed";
-      transaction.failureReason = error.message;
-      transaction.metadata = {
-        ...transaction.metadata,
-        verificationError: error.message,
-        failedAt: (/* @__PURE__ */ new Date()).toISOString()
-      };
-      await transaction.save();
-      this._triggerHook("payment.failed", {
-        transaction,
-        error: error.message,
-        provider: gatewayType,
-        paymentIntentId
-      });
-      throw new PaymentVerificationError(paymentIntentId, error.message);
-    }
-    if (paymentResult.amount && paymentResult.amount !== transaction.amount) {
-      throw new ValidationError(
-        `Amount mismatch: expected ${transaction.amount}, got ${paymentResult.amount}`,
-        { expected: transaction.amount, actual: paymentResult.amount }
-      );
-    }
-    if (paymentResult.currency && paymentResult.currency.toUpperCase() !== transaction.currency.toUpperCase()) {
-      throw new ValidationError(
-        `Currency mismatch: expected ${transaction.currency}, got ${paymentResult.currency}`,
-        { expected: transaction.currency, actual: paymentResult.currency }
-      );
-    }
-    transaction.status = paymentResult.status === "succeeded" ? "verified" : paymentResult.status;
-    transaction.verifiedAt = paymentResult.paidAt ?? /* @__PURE__ */ new Date();
-    transaction.verifiedBy = verifiedBy;
-    transaction.gateway = {
-      ...transaction.gateway,
-      type: transaction.gateway?.type ?? "manual",
-      verificationData: paymentResult.metadata
-    };
-    await transaction.save();
-    this._triggerHook("payment.verified", {
-      transaction,
-      paymentResult,
-      verifiedBy
-    });
-    return {
-      transaction,
-      paymentResult,
-      status: transaction.status
-    };
+    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
@@ -1767,7 +2628,11 @@ var PaymentService = class {
     }
     let paymentResult = null;
     try {
-      paymentResult = await provider.getStatus(paymentIntentId);
+      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 {
@@ -1792,99 +2657,163 @@ var PaymentService = class {
    * @returns { transaction, refundResult }
    */
   async refund(paymentId, amount = null, options = {}) {
-    const { reason = null } = options;
-    const TransactionModel = this.models.Transaction;
-    const transaction = await this._findTransaction(TransactionModel, paymentId);
-    if (!transaction) {
-      throw new TransactionNotFoundError(paymentId);
-    }
-    if (transaction.status !== "verified" && transaction.status !== "completed") {
-      throw new RefundError(transaction._id.toString(), "Only verified/completed transactions can be refunded");
-    }
-    const gatewayType = transaction.gateway?.type ?? "manual";
-    const provider = this.providers[gatewayType];
-    if (!provider) {
-      throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
-    }
-    const capabilities = provider.getCapabilities();
-    if (!capabilities.supportsRefunds) {
-      throw new RefundNotSupportedError(gatewayType);
-    }
-    const refundedSoFar = transaction.refundedAmount ?? 0;
-    const refundableAmount = transaction.amount - refundedSoFar;
-    const refundAmount = amount ?? refundableAmount;
-    if (refundAmount <= 0) {
-      throw new ValidationError(`Refund amount must be positive, got ${refundAmount}`);
-    }
-    if (refundAmount > refundableAmount) {
-      throw new ValidationError(
-        `Refund amount (${refundAmount}) exceeds refundable balance (${refundableAmount})`,
-        { refundAmount, refundableAmount, alreadyRefunded: refundedSoFar }
-      );
-    }
-    let refundResult;
-    try {
-      refundResult = await provider.refund(paymentId, refundAmount, { reason: reason ?? void 0 });
-    } catch (error) {
-      this.logger.error("Refund failed:", error);
-      throw new RefundError(paymentId, error.message);
-    }
-    const refundTransactionType = this.config.transactionTypeMapping?.refund ?? TRANSACTION_TYPE.EXPENSE;
-    const refundCommission = transaction.commission ? reverseCommission(transaction.commission, transaction.amount, refundAmount) : null;
-    const refundTransaction = await TransactionModel.create({
-      organizationId: transaction.organizationId,
-      customerId: transaction.customerId,
-      amount: refundAmount,
-      currency: transaction.currency,
-      category: transaction.category,
-      type: refundTransactionType,
-      // EXPENSE - money going out
-      method: transaction.method ?? "manual",
-      status: "completed",
-      gateway: {
-        type: transaction.gateway?.type ?? "manual",
-        paymentIntentId: refundResult.id,
-        provider: refundResult.provider
-      },
-      paymentDetails: transaction.paymentDetails,
-      ...refundCommission && { commission: refundCommission },
-      // Reversed commission
-      // Polymorphic reference (copy from original transaction)
-      ...transaction.referenceId && { referenceId: transaction.referenceId },
-      ...transaction.referenceModel && { referenceModel: transaction.referenceModel },
-      metadata: {
-        ...transaction.metadata,
-        isRefund: true,
-        originalTransactionId: transaction._id.toString(),
-        refundReason: reason,
-        refundResult: refundResult.metadata
-      },
-      idempotencyKey: `refund_${transaction._id}_${Date.now()}`
-    });
-    const isPartialRefund = refundAmount < transaction.amount;
-    transaction.status = isPartialRefund ? "partially_refunded" : "refunded";
-    transaction.refundedAmount = (transaction.refundedAmount ?? 0) + refundAmount;
-    transaction.refundedAt = refundResult.refundedAt ?? /* @__PURE__ */ new Date();
-    transaction.metadata = {
-      ...transaction.metadata,
-      refundTransactionId: refundTransaction._id.toString(),
-      refundReason: reason
-    };
-    await transaction.save();
-    this._triggerHook("payment.refunded", {
-      transaction,
-      refundTransaction,
-      refundResult,
-      refundAmount,
-      reason,
-      isPartialRefund
-    });
-    return {
-      transaction,
-      refundTransaction,
-      refundResult,
-      status: transaction.status
-    };
+    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
@@ -1905,7 +2834,10 @@ var PaymentService = class {
     }
     let webhookEvent;
     try {
-      webhookEvent = await provider.handleWebhook(payload, headers);
+      webhookEvent = await this.executeProviderCall(
+        () => provider.handleWebhook(payload, headers),
+        `${providerName}.handleWebhook`
+      );
     } catch (error) {
       this.logger.error("Webhook processing failed:", error);
       throw new ProviderError(
@@ -1975,19 +2907,46 @@ var PaymentService = class {
       processedAt: /* @__PURE__ */ new Date(),
       data: webhookEvent.data
     };
+    let newStatus = transaction.status;
     if (webhookEvent.type === "payment.succeeded") {
-      transaction.status = "verified";
-      transaction.verifiedAt = webhookEvent.createdAt;
+      newStatus = "verified";
     } else if (webhookEvent.type === "payment.failed") {
-      transaction.status = "failed";
+      newStatus = "failed";
     } else if (webhookEvent.type === "refund.succeeded") {
-      transaction.status = "refunded";
-      transaction.refundedAt = webhookEvent.createdAt;
+      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._triggerHook(`payment.webhook.${webhookEvent.type}`, {
+    this.events.emit("webhook.processed", {
+      webhookType: webhookEvent.type,
+      provider: webhookEvent.provider,
       event: webhookEvent,
-      transaction
+      transaction,
+      processedAt: /* @__PURE__ */ new Date()
     });
     return {
       event: webhookEvent,
@@ -2035,13 +2994,6 @@ var PaymentService = class {
     }
     return provider;
   }
-  /**
-   * Trigger event hook (fire-and-forget, non-blocking)
-   * @private
-   */
-  _triggerHook(event, data) {
-    triggerHook(this.hooks, event, data, this.logger);
-  }
   /**
    * Find transaction by sessionId, paymentIntentId, or transaction ID
    * @private
@@ -2061,17 +3013,32 @@ var PaymentService = class {
     return transaction;
   }
 };
-
-// src/services/transaction.service.ts
 var TransactionService = class {
   models;
-  hooks;
+  plugins;
+  events;
   logger;
   constructor(container) {
     this.models = container.get("models");
-    this.hooks = container.get("hooks");
+    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
    *
@@ -2128,59 +3095,46 @@ var TransactionService = class {
    * @returns Updated transaction
    */
   async update(transactionId, updates) {
-    const TransactionModel = this.models.Transaction;
-    const model = TransactionModel;
-    let transaction;
-    if (typeof model.update === "function") {
-      transaction = await model.update(transactionId, updates);
-    } else if (typeof model.findByIdAndUpdate === "function") {
-      transaction = await model.findByIdAndUpdate(
-        transactionId,
-        { $set: updates },
-        { new: true }
-      );
-    } else {
-      throw new Error("Transaction model does not support update operations");
-    }
-    if (!transaction) {
-      throw new TransactionNotFoundError(transactionId);
-    }
-    this._triggerHook("transaction.updated", {
-      transaction,
-      updates
-    });
-    return transaction;
-  }
-  /**
-   * Trigger event hook (fire-and-forget, non-blocking)
-   * @private
-   */
-  _triggerHook(event, data) {
-    triggerHook(this.hooks, event, data, this.logger);
+    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/enums/escrow.enums.ts
-var HOLD_STATUS = {
-  HELD: "held",
-  RELEASED: "released",
-  CANCELLED: "cancelled",
-  PARTIALLY_RELEASED: "partially_released"
-};
-var RELEASE_REASON = {
-  PAYMENT_VERIFIED: "payment_verified"};
-var HOLD_REASON = {
-  PAYMENT_VERIFICATION: "payment_verification"};
-
-// src/enums/split.enums.ts
-var SPLIT_TYPE = {
-  CUSTOM: "custom"
-};
-var SPLIT_STATUS = {
-  PENDING: "pending",
-  PAID: "paid"};
-
-// src/utils/commission-split.ts
+// src/shared/utils/calculators/commission-split.ts
 function calculateSplits(amount, splitRules = [], gatewayFeeRate = 0) {
   if (!splitRules || splitRules.length === 0) {
     return [];
@@ -2199,9 +3153,9 @@ function calculateSplits(amount, splitRules = [], gatewayFeeRate = 0) {
     if (rule.rate < 0 || rule.rate > 1) {
       throw new Error(`Split rate must be between 0 and 1 for split ${index}`);
     }
-    const grossAmount = Math.round(amount * rule.rate * 100) / 100;
-    const gatewayFeeAmount = index === 0 && gatewayFeeRate > 0 ? Math.round(amount * gatewayFeeRate * 100) / 100 : 0;
-    const netAmount = Math.max(0, Math.round((grossAmount - gatewayFeeAmount) * 100) / 100);
+    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,
@@ -2219,18 +3173,35 @@ function calculateSplits(amount, splitRules = [], gatewayFeeRate = 0) {
 }
 function calculateOrganizationPayout(amount, splits = []) {
   const totalSplitAmount = splits.reduce((sum, split) => sum + split.grossAmount, 0);
-  return Math.max(0, Math.round((amount - totalSplitAmount) * 100) / 100);
+  return Math.max(0, amount - totalSplitAmount);
 }
 
-// src/services/escrow.service.ts
+// src/application/services/escrow.service.ts
 var EscrowService = class {
   models;
-  hooks;
+  plugins;
   logger;
+  events;
   constructor(container) {
     this.models = container.get("models");
-    this.hooks = container.get("hooks");
+    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
@@ -2240,36 +3211,54 @@ var EscrowService = class {
    * @returns Updated transaction
    */
   async hold(transactionId, options = {}) {
-    const {
-      reason = HOLD_REASON.PAYMENT_VERIFICATION,
-      holdUntil = null,
-      metadata = {}
-    } = options;
-    const TransactionModel = this.models.Transaction;
-    const transaction = await TransactionModel.findById(transactionId);
-    if (!transaction) {
-      throw new TransactionNotFoundError(transactionId);
-    }
-    if (transaction.status !== TRANSACTION_STATUS.VERIFIED) {
-      throw new Error(`Cannot hold transaction with status: ${transaction.status}. Must be verified.`);
-    }
-    transaction.hold = {
-      status: HOLD_STATUS.HELD,
-      heldAmount: transaction.amount,
-      releasedAmount: 0,
-      reason,
-      heldAt: /* @__PURE__ */ new Date(),
-      ...holdUntil && { holdUntil },
-      releases: [],
-      metadata
-    };
-    await transaction.save();
-    this._triggerHook("escrow.held", {
-      transaction,
-      heldAmount: transaction.amount,
-      reason
-    });
-    return transaction;
+    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
@@ -2279,93 +3268,185 @@ var EscrowService = class {
    * @returns { transaction, releaseTransaction }
    */
   async release(transactionId, options) {
-    const {
-      amount = null,
-      recipientId,
-      recipientType = "organization",
-      reason = RELEASE_REASON.PAYMENT_VERIFIED,
-      releasedBy = null,
-      createTransaction = true,
-      metadata = {}
-    } = options;
-    const TransactionModel = this.models.Transaction;
-    const transaction = await TransactionModel.findById(transactionId);
-    if (!transaction) {
-      throw new TransactionNotFoundError(transactionId);
-    }
-    if (!transaction.hold || transaction.hold.status !== HOLD_STATUS.HELD) {
-      throw new Error(`Transaction is not in held status. Current: ${transaction.hold?.status ?? "none"}`);
-    }
-    if (!recipientId) {
-      throw new Error("recipientId is required for release");
-    }
-    const releaseAmount = amount ?? transaction.hold.heldAmount - transaction.hold.releasedAmount;
-    const availableAmount = transaction.hold.heldAmount - transaction.hold.releasedAmount;
-    if (releaseAmount > availableAmount) {
-      throw new Error(`Release amount (${releaseAmount}) exceeds available held amount (${availableAmount})`);
-    }
-    const releaseRecord = {
-      amount: releaseAmount,
-      recipientId,
-      recipientType,
-      releasedAt: /* @__PURE__ */ new Date(),
-      releasedBy,
-      reason,
-      metadata
-    };
-    transaction.hold.releases.push(releaseRecord);
-    transaction.hold.releasedAmount += releaseAmount;
-    const isFullRelease = transaction.hold.releasedAmount >= transaction.hold.heldAmount;
-    const isPartialRelease = transaction.hold.releasedAmount > 0 && transaction.hold.releasedAmount < transaction.hold.heldAmount;
-    if (isFullRelease) {
-      transaction.hold.status = HOLD_STATUS.RELEASED;
-      transaction.hold.releasedAt = /* @__PURE__ */ new Date();
-      transaction.status = TRANSACTION_STATUS.COMPLETED;
-    } else if (isPartialRelease) {
-      transaction.hold.status = HOLD_STATUS.PARTIALLY_RELEASED;
-    }
-    await transaction.save();
-    let releaseTransaction = null;
-    if (createTransaction) {
-      releaseTransaction = await TransactionModel.create({
-        organizationId: transaction.organizationId,
-        customerId: recipientId,
-        amount: releaseAmount,
-        currency: transaction.currency,
-        category: transaction.category,
-        type: TRANSACTION_TYPE.INCOME,
-        method: transaction.method,
-        status: TRANSACTION_STATUS.COMPLETED,
-        gateway: transaction.gateway,
-        referenceId: transaction.referenceId,
-        referenceModel: transaction.referenceModel,
-        metadata: {
-          ...metadata,
-          isRelease: true,
-          heldTransactionId: transaction._id.toString(),
-          releaseReason: reason,
-          recipientType
-        },
-        idempotencyKey: `release_${transaction._id}_${Date.now()}`
-      });
-    }
-    this._triggerHook("escrow.released", {
-      transaction,
-      releaseTransaction,
-      releaseAmount,
-      recipientId,
-      recipientType,
-      reason,
-      isFullRelease,
-      isPartialRelease
-    });
-    return {
-      transaction,
-      releaseTransaction,
-      releaseAmount,
-      isFullRelease,
-      isPartialRelease
-    };
+    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
@@ -2382,8 +3463,23 @@ var EscrowService = class {
       throw new TransactionNotFoundError(transactionId);
     }
     if (!transaction.hold || transaction.hold.status !== HOLD_STATUS.HELD) {
-      throw new Error(`Transaction is not in held status. Current: ${transaction.hold?.status ?? "none"}`);
+      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 = {
@@ -2391,9 +3487,24 @@ var EscrowService = class {
       ...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._triggerHook("escrow.cancelled", {
+    this.events.emit("escrow.cancelled", {
       transaction,
       reason
     });
@@ -2414,10 +3525,15 @@ var EscrowService = class {
       throw new TransactionNotFoundError(transactionId);
     }
     if (!transaction.hold || transaction.hold.status !== HOLD_STATUS.HELD) {
-      throw new Error(`Transaction must be held before splitting. Current: ${transaction.hold?.status ?? "none"}`);
+      throw new InvalidStateTransitionError(
+        "escrow_hold",
+        transaction._id.toString(),
+        transaction.hold?.status ?? "none",
+        HOLD_STATUS.HELD
+      );
     }
     if (!splitRules || splitRules.length === 0) {
-      throw new Error("splitRules cannot be empty");
+      throw new ValidationError("splitRules cannot be empty", { transactionId });
     }
     const splits = calculateSplits(
       transaction.amount,
@@ -2427,25 +3543,58 @@ var EscrowService = class {
     transaction.splits = splits;
     await transaction.save();
     const splitTransactions = [];
-    for (const split of splits) {
+    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,
-        amount: split.netAmount,
+        // ✅ 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,
-        category: split.type,
-        type: TRANSACTION_TYPE.EXPENSE,
+        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: TRANSACTION_STATUS.COMPLETED,
+        status: "completed",
         gateway: transaction.gateway,
-        referenceId: transaction.referenceId,
-        referenceModel: transaction.referenceModel,
+        // ✅ 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(),
-          grossAmount: split.grossAmount,
+          // Store split details for reference
+          splitGrossAmount: split.grossAmount,
+          splitNetAmount: split.netAmount,
+          // Original calculation
           gatewayFeeAmount: split.gatewayFeeAmount
         },
         idempotencyKey: `split_${transaction._id}_${split.recipientId}_${Date.now()}`
@@ -2457,8 +3606,10 @@ var EscrowService = class {
     }
     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: organizationPayout,
+      amount: organizationPayoutTotal,
       recipientId: transaction.organizationId?.toString() ?? "",
       recipientType: "organization",
       reason: RELEASE_REASON.PAYMENT_VERIFIED,
@@ -2469,7 +3620,7 @@ var EscrowService = class {
         totalSplitAmount: transaction.amount - organizationPayout
       }
     });
-    this._triggerHook("escrow.split", {
+    this.events.emit("escrow.split", {
       transaction,
       splits,
       splitTransactions,
@@ -2504,8 +3655,490 @@ var EscrowService = class {
       hasSplits: transaction.splits ? transaction.splits.length > 0 : false
     };
   }
-  _triggerHook(event, data) {
-    triggerHook(this.hooks, event, data, this.logger);
+};
+
+// 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;
   }
 };
 
@@ -2530,6 +4163,8 @@ var Revenue = class {
   transactions;
   /** Escrow service - hold, release, splits */
   escrow;
+  /** Settlement service - payout tracking */
+  settlement;
   constructor(container, events, plugins, options, providers, config) {
     this._container = container;
     this._events = events;
@@ -2542,16 +4177,20 @@ var Revenue = class {
       ttl: options.idempotencyTtl
     });
     if (options.circuitBreaker) {
-      this._circuitBreaker = createCircuitBreaker();
+      const cbConfig = typeof options.circuitBreaker === "boolean" ? {} : options.circuitBreaker;
+      this._circuitBreaker = createCircuitBreaker(cbConfig);
     }
     container.singleton("events", events);
     container.singleton("plugins", plugins);
     container.singleton("idempotency", this._idempotency);
     container.singleton("logger", this._logger);
+    container.singleton("retryConfig", options.retry || {});
+    container.singleton("circuitBreaker", this._circuitBreaker || null);
     this.monetization = new MonetizationService(container);
     this.payments = new PaymentService(container);
     this.transactions = new TransactionService(container);
     this.escrow = new EscrowService(container);
+    this.settlement = new SettlementService(container);
     Object.freeze(this._providers);
     Object.freeze(this._config);
   }
@@ -2627,8 +4266,8 @@ var Revenue = class {
    *
    * @example
    * ```typescript
-   * revenue.on('payment.succeeded', (event) => {
-   *   console.log('Payment:', event.transactionId);
+   * revenue.on('payment.verified', (event) => {
+   *   console.log('Payment:', event.transaction._id);
    * });
    * ```
    */
@@ -2685,7 +4324,6 @@ var Revenue = class {
     return {
       events: this._events,
       logger: this._logger,
-      get: (key) => this._container.get(key),
       storage: /* @__PURE__ */ new Map(),
       meta: {
         ...meta,
@@ -2700,6 +4338,7 @@ var Revenue = class {
   async destroy() {
     await this._plugins.destroy();
     this._events.clear();
+    this._idempotency.destroy();
   }
 };
 var RevenueBuilder = class {
@@ -2707,8 +4346,8 @@ var RevenueBuilder = class {
   models = null;
   providers = {};
   plugins = [];
-  hooks = {};
   categoryMappings = {};
+  transactionTypeMapping = {};
   constructor(options = {}) {
     this.options = options;
   }
@@ -2732,7 +4371,7 @@ var RevenueBuilder = class {
    */
   withModel(name, model) {
     if (!this.models) {
-      this.models = { Transaction: model };
+      this.models = {};
     }
     this.models[name] = model;
     return this;
@@ -2777,15 +4416,6 @@ var RevenueBuilder = class {
     this.plugins.push(...plugins);
     return this;
   }
-  withHooks(hooks) {
-    const normalized = {};
-    for (const [event, handlerOrHandlers] of Object.entries(hooks)) {
-      if (!handlerOrHandlers) continue;
-      normalized[event] = Array.isArray(handlerOrHandlers) ? handlerOrHandlers : [handlerOrHandlers];
-    }
-    this.hooks = { ...this.hooks, ...normalized };
-    return this;
-  }
   /**
    * Set retry configuration
    *
@@ -2827,7 +4457,15 @@ var RevenueBuilder = class {
     return this;
   }
   /**
-   * Set commission rate (0-100)
+   * Set commission rate as decimal (0-1, e.g., 0.10 for 10%)
+   *
+   * @param rate - Commission rate (0-1 decimal format)
+   * @param gatewayFeeRate - Gateway fee rate (0-1 decimal format, e.g., 0.029 for 2.9%)
+   *
+   * @example
+   * ```typescript
+   * .withCommission(0.10, 0.029) // 10% commission + 2.9% gateway fee
+   * ```
    */
   withCommission(rate, gatewayFeeRate = 0) {
     this.options.commissionRate = rate;
@@ -2850,6 +4488,22 @@ var RevenueBuilder = class {
     this.categoryMappings = { ...this.categoryMappings, ...mappings };
     return this;
   }
+  /**
+   * Set transaction flow mapping by category or monetization type
+   *
+   * @example
+   * ```typescript
+   * .withTransactionTypeMapping({
+   *   platform_subscription: 'inflow',
+   *   subscription: 'inflow',
+   *   refund: 'outflow',
+   * })
+   * ```
+   */
+  withTransactionTypeMapping(mapping) {
+    this.transactionTypeMapping = { ...this.transactionTypeMapping, ...mapping };
+    return this;
+  }
   /**
    * Build the Revenue instance
    */
@@ -2888,14 +4542,19 @@ var RevenueBuilder = class {
       gatewayFeeRate: this.options.gatewayFeeRate ?? 0
     };
     const config = {
-      defaultCurrency: resolvedOptions.defaultCurrency,
-      commissionRate: resolvedOptions.commissionRate,
-      gatewayFeeRate: resolvedOptions.gatewayFeeRate,
-      categoryMappings: this.categoryMappings
+      ...resolveConfig(resolvedOptions),
+      // Converts singular → plural with '*' global default
+      targetModels: [],
+      categoryMappings: this.categoryMappings,
+      transactionTypeMapping: this.transactionTypeMapping
     };
+    for (const provider of Object.values(this.providers)) {
+      if (typeof provider.setDefaultCurrency === "function") {
+        provider.setDefaultCurrency(resolvedOptions.defaultCurrency);
+      }
+    }
     container.singleton("models", this.models);
     container.singleton("providers", this.providers);
-    container.singleton("hooks", this.hooks);
     container.singleton("config", config);
     const events = createEventBus();
     const pluginManager = new PluginManager();
@@ -2924,12 +4583,9 @@ function createRevenue(config) {
   if (config.plugins) {
     builder = builder.withPlugins(config.plugins);
   }
-  if (config.hooks) {
-    builder = builder.withHooks(config.hooks);
-  }
   return builder.build();
 }
 
-export { AlreadyVerifiedError, ConfigurationError, Container, ERROR_CODES, EventBus, InvalidAmountError, InvalidStateTransitionError, MissingRequiredFieldError, ModelNotRegisteredError, NotFoundError, OperationError, PaymentIntentCreationError, PaymentVerificationError, PluginManager, ProviderCapabilityError, ProviderError, ProviderNotFoundError, RefundError, RefundNotSupportedError, Result, Revenue, RevenueBuilder, RevenueError, StateError, SubscriptionNotActiveError, SubscriptionNotFoundError, TransactionNotFoundError, ValidationError, all, auditPlugin, createEventBus, createRevenue, definePlugin, err, flatMap, isErr, isOk, isRetryable, isRevenueError, loggingPlugin, map, mapErr, match, metricsPlugin, ok, tryCatch, tryCatchSync, unwrap, unwrapOr };
+export { AlreadyVerifiedError, ConfigurationError, Container, ERROR_CODES, EventBus, HOLD_STATE_MACHINE, InvalidAmountError, InvalidStateTransitionError, MissingRequiredFieldError, ModelNotRegisteredError, NotFoundError, OperationError, PaymentIntentCreationError, PaymentVerificationError, PluginManager, ProviderCapabilityError, ProviderError, ProviderNotFoundError, RefundError, RefundNotSupportedError, Result, Revenue, RevenueBuilder, RevenueError, SETTLEMENT_STATE_MACHINE, SPLIT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, StateError, StateMachine, SubscriptionNotActiveError, SubscriptionNotFoundError, TRANSACTION_STATE_MACHINE, TransactionNotFoundError, ValidationError, all, auditPlugin, createEventBus, createRevenue, definePlugin, err, flatMap, isErr, isOk, isRetryable, isRevenueError, loggingPlugin, map, mapErr, match, metricsPlugin, ok, tryCatch, tryCatchSync, unwrap, unwrapOr };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map