@classytic/revenue 1.1.2 → 1.1.4

package/dist/settlement.service-DmdKv0Zu.mjs

@@ -0,0 +1,2511 @@
+import { a as reverseCommission, c as retry, i as calculateCommission, n as calculateSplits, t as calculateOrganizationPayout } from "./commission-split-BzB8cd39.mjs";
+import { C as ValidationError, S as TransactionNotFoundError, _ as RefundNotSupportedError, a as InvalidAmountError, b as SubscriptionNotActiveError, c as ModelNotRegisteredError, d as PaymentIntentCreationError, f as PaymentVerificationError, g as RefundError, h as ProviderNotFoundError, m as ProviderError, n as AlreadyVerifiedError, o as InvalidStateTransitionError, p as ProviderCapabilityError, s as MissingRequiredFieldError, t as resolveCategory, x as SubscriptionNotFoundError } from "./category-resolver-DV83N8ok.mjs";
+import { a as TRANSACTION_STATUS, r as TRANSACTION_FLOW } from "./transaction.enums-pCyMFT4Z.mjs";
+import { a as RELEASE_REASON, f as SETTLEMENT_TYPE, g as MONETIZATION_TYPES, r as HOLD_STATUS, t as HOLD_REASON, u as SETTLEMENT_STATUS } from "./escrow.enums-CZGrrdg7.mjs";
+import { f as SUBSCRIPTION_STATUS, r as SPLIT_STATUS } from "./split.enums-BrjabxIX.mjs";
+import { nanoid } from "nanoid";
+
+//#region src/infrastructure/config/resolver.ts
+/**
+* Resolve builder options to service config
+*
+* Converts singular commission rates to category/gateway maps
+* Uses '*' as global default key (applies to all categories/gateways)
+*
+* @param options - Builder options
+* @returns Service-ready config
+*
+* @example
+* ```typescript
+* const options = {
+*   commissionRate: 0.10,        // 10% global default
+*   gatewayFeeRate: 0.029,      // 2.9% global default
+* };
+*
+* const config = resolveConfig(options);
+* // {
+* //   commissionRates: { '*': 0.10 },
+* //   gatewayFeeRates: { '*': 0.029 }
+* // }
+*
+* // Services can then:
+* const rate = config.commissionRates?.['course_purchase']
+*   ?? config.commissionRates?.['*']  // Fallback to global default
+*   ?? 0;
+* ```
+*/
+function resolveConfig(options) {
+	const config = {
+		targetModels: [],
+		categoryMappings: {}
+	};
+	if (options.commissionRate !== void 0) config.commissionRates = { "*": options.commissionRate };
+	if (options.gatewayFeeRate !== void 0) config.gatewayFeeRates = { "*": options.gatewayFeeRate };
+	return config;
+}
+/**
+* Get commission rate for a category
+*
+* Follows precedence: specific category → global default → 0
+*
+* @param config - Revenue config
+* @param category - Transaction category
+* @returns Commission rate (0-1)
+*
+* @example
+* ```typescript
+* const rate = getCommissionRate(config, 'course_purchase');
+* // Checks:
+* // 1. config.commissionRates?.['course_purchase']
+* // 2. config.commissionRates?.['*']
+* // 3. 0 (fallback)
+* ```
+*/
+function getCommissionRate(config, category) {
+	if (!config?.commissionRates) return 0;
+	if (category in config.commissionRates) return config.commissionRates[category];
+	return config.commissionRates["*"] ?? 0;
+}
+/**
+* Get gateway fee rate for a gateway
+*
+* Follows precedence: specific gateway → global default → 0
+*
+* @param config - Revenue config
+* @param gateway - Gateway name (e.g., 'stripe', 'paypal')
+* @returns Gateway fee rate (0-1)
+*/
+function getGatewayFeeRate(config, gateway) {
+	if (!config?.gatewayFeeRates) return 0;
+	if (gateway in config.gatewayFeeRates) return config.gatewayFeeRates[gateway];
+	return config.gatewayFeeRates["*"] ?? 0;
+}
+
+//#endregion
+//#region src/core/state-machine/StateMachine.ts
+/**
+* Generic State Machine Validator
+* @classytic/revenue
+*
+* Inspired by Stripe's state transition validation
+* Provides centralized, type-safe state transition management
+*/
+/**
+* Generic State Machine for validating state transitions
+*
+* @template TState - The state type (typically a union of string literals)
+*
+* @example
+* ```typescript
+* const stateMachine = new StateMachine(
+*   new Map([
+*     ['pending', new Set(['processing', 'failed'])],
+*     ['processing', new Set(['completed', 'failed'])],
+*     ['completed', new Set([])], // Terminal state
+*     ['failed', new Set([])],     // Terminal state
+*   ]),
+*   'payment'
+* );
+*
+* // Validate transition
+* stateMachine.validate('pending', 'processing', 'pay_123'); // ✅ OK
+* stateMachine.validate('completed', 'pending', 'pay_123');  // ❌ Throws InvalidStateTransitionError
+*
+* // Check without throwing
+* stateMachine.canTransition('pending', 'processing'); // true
+* stateMachine.canTransition('completed', 'pending');  // false
+* ```
+*/
+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) {
+		if (!this.transitions.get(from)?.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
+		};
+	}
+};
+
+//#endregion
+//#region src/core/state-machine/definitions.ts
+/**
+* State Machine Definitions
+* @classytic/revenue
+*
+* Centralized state transition rules for all entities
+* Inspired by Stripe, PayPal, and Shopify state management patterns
+*/
+/**
+* Transaction State Machine
+*
+* Flow:
+* ```
+* pending → payment_initiated → processing → verified → completed
+*           ↓                    ↓           ↓
+*         failed         requires_action  refunded
+*                                ↓       partially_refunded
+*                             failed
+* ```
+*
+* Terminal states: failed, refunded, cancelled, expired
+*/
+const TRANSACTION_STATE_MACHINE = new StateMachine(new Map([
+	[TRANSACTION_STATUS.PENDING, new Set([
+		TRANSACTION_STATUS.PAYMENT_INITIATED,
+		TRANSACTION_STATUS.PROCESSING,
+		TRANSACTION_STATUS.VERIFIED,
+		TRANSACTION_STATUS.FAILED,
+		TRANSACTION_STATUS.CANCELLED
+	])],
+	[TRANSACTION_STATUS.PAYMENT_INITIATED, new Set([
+		TRANSACTION_STATUS.PROCESSING,
+		TRANSACTION_STATUS.VERIFIED,
+		TRANSACTION_STATUS.REQUIRES_ACTION,
+		TRANSACTION_STATUS.FAILED,
+		TRANSACTION_STATUS.CANCELLED
+	])],
+	[TRANSACTION_STATUS.PROCESSING, new Set([
+		TRANSACTION_STATUS.VERIFIED,
+		TRANSACTION_STATUS.REQUIRES_ACTION,
+		TRANSACTION_STATUS.FAILED
+	])],
+	[TRANSACTION_STATUS.REQUIRES_ACTION, new Set([
+		TRANSACTION_STATUS.VERIFIED,
+		TRANSACTION_STATUS.FAILED,
+		TRANSACTION_STATUS.CANCELLED,
+		TRANSACTION_STATUS.EXPIRED
+	])],
+	[TRANSACTION_STATUS.VERIFIED, new Set([
+		TRANSACTION_STATUS.COMPLETED,
+		TRANSACTION_STATUS.REFUNDED,
+		TRANSACTION_STATUS.PARTIALLY_REFUNDED,
+		TRANSACTION_STATUS.CANCELLED
+	])],
+	[TRANSACTION_STATUS.COMPLETED, new Set([TRANSACTION_STATUS.REFUNDED, TRANSACTION_STATUS.PARTIALLY_REFUNDED])],
+	[TRANSACTION_STATUS.PARTIALLY_REFUNDED, new Set([TRANSACTION_STATUS.REFUNDED])],
+	[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");
+/**
+* Subscription State Machine
+*
+* Flow:
+* ```
+* pending → active → paused → active
+*            ↓        ↓
+*        cancelled  cancelled
+*            ↓
+*         expired
+* ```
+*
+* Terminal states: cancelled, expired
+*/
+const SUBSCRIPTION_STATE_MACHINE = new StateMachine(new Map([
+	[SUBSCRIPTION_STATUS.PENDING, new Set([SUBSCRIPTION_STATUS.ACTIVE, SUBSCRIPTION_STATUS.CANCELLED])],
+	[SUBSCRIPTION_STATUS.ACTIVE, new Set([
+		SUBSCRIPTION_STATUS.PAUSED,
+		SUBSCRIPTION_STATUS.PENDING_RENEWAL,
+		SUBSCRIPTION_STATUS.CANCELLED,
+		SUBSCRIPTION_STATUS.EXPIRED
+	])],
+	[SUBSCRIPTION_STATUS.PENDING_RENEWAL, new Set([
+		SUBSCRIPTION_STATUS.ACTIVE,
+		SUBSCRIPTION_STATUS.CANCELLED,
+		SUBSCRIPTION_STATUS.EXPIRED
+	])],
+	[SUBSCRIPTION_STATUS.PAUSED, new Set([SUBSCRIPTION_STATUS.ACTIVE, SUBSCRIPTION_STATUS.CANCELLED])],
+	[SUBSCRIPTION_STATUS.INACTIVE, new Set([SUBSCRIPTION_STATUS.ACTIVE, SUBSCRIPTION_STATUS.CANCELLED])],
+	[SUBSCRIPTION_STATUS.CANCELLED, /* @__PURE__ */ new Set([])],
+	[SUBSCRIPTION_STATUS.EXPIRED, /* @__PURE__ */ new Set([])]
+]), "subscription");
+/**
+* Settlement State Machine
+*
+* Flow:
+* ```
+* pending → processing → completed
+*            ↓
+*          failed → pending (retry allowed)
+* ```
+*
+* Terminal states: completed, cancelled
+* Note: failed can retry to pending
+*/
+const SETTLEMENT_STATE_MACHINE = new StateMachine(new Map([
+	[SETTLEMENT_STATUS.PENDING, new Set([SETTLEMENT_STATUS.PROCESSING, SETTLEMENT_STATUS.CANCELLED])],
+	[SETTLEMENT_STATUS.PROCESSING, new Set([SETTLEMENT_STATUS.COMPLETED, SETTLEMENT_STATUS.FAILED])],
+	[SETTLEMENT_STATUS.FAILED, new Set([SETTLEMENT_STATUS.PENDING, SETTLEMENT_STATUS.CANCELLED])],
+	[SETTLEMENT_STATUS.COMPLETED, /* @__PURE__ */ new Set([])],
+	[SETTLEMENT_STATUS.CANCELLED, /* @__PURE__ */ new Set([])]
+]), "settlement");
+/**
+* Escrow Hold State Machine
+*
+* Flow:
+* ```
+* held → partially_released → released
+*  ↓
+* cancelled
+* ```
+*
+* Terminal states: released, cancelled, expired
+*/
+const HOLD_STATE_MACHINE = new StateMachine(new Map([
+	[HOLD_STATUS.HELD, new Set([
+		HOLD_STATUS.RELEASED,
+		HOLD_STATUS.PARTIALLY_RELEASED,
+		HOLD_STATUS.CANCELLED,
+		HOLD_STATUS.EXPIRED
+	])],
+	[HOLD_STATUS.PARTIALLY_RELEASED, new Set([HOLD_STATUS.RELEASED, HOLD_STATUS.CANCELLED])],
+	[HOLD_STATUS.RELEASED, /* @__PURE__ */ new Set([])],
+	[HOLD_STATUS.CANCELLED, /* @__PURE__ */ new Set([])],
+	[HOLD_STATUS.EXPIRED, /* @__PURE__ */ new Set([])]
+]), "escrow_hold");
+/**
+* Split Payment State Machine
+*
+* Flow:
+* ```
+* pending → due → paid
+*   ↓
+* waived
+* cancelled
+* ```
+*
+* Terminal states: paid, waived, cancelled
+*/
+const SPLIT_STATE_MACHINE = new StateMachine(new Map([
+	[SPLIT_STATUS.PENDING, new Set([
+		SPLIT_STATUS.DUE,
+		SPLIT_STATUS.PAID,
+		SPLIT_STATUS.WAIVED,
+		SPLIT_STATUS.CANCELLED
+	])],
+	[SPLIT_STATUS.DUE, new Set([
+		SPLIT_STATUS.PAID,
+		SPLIT_STATUS.WAIVED,
+		SPLIT_STATUS.CANCELLED
+	])],
+	[SPLIT_STATUS.PAID, /* @__PURE__ */ new Set([])],
+	[SPLIT_STATUS.WAIVED, /* @__PURE__ */ new Set([])],
+	[SPLIT_STATUS.CANCELLED, /* @__PURE__ */ new Set([])]
+]), "split");
+
+//#endregion
+//#region src/infrastructure/audit/types.ts
+/**
+* Helper to append audit event to document metadata
+*
+* This is a metadata-based approach that stores audit trail
+* directly in the document's metadata.stateHistory array.
+*
+* Example:
+* ```typescript
+* const transaction = await Transaction.findById(id);
+*
+* const auditEvent = {
+*   resourceType: 'transaction',
+*   resourceId: transaction._id.toString(),
+*   fromState: 'pending',
+*   toState: 'verified',
+*   changedAt: new Date(),
+*   changedBy: 'admin_123',
+* };
+*
+* const updated = appendAuditEvent(transaction, auditEvent);
+* await updated.save();
+* ```
+*
+* @param document - Mongoose document or plain object with optional metadata field
+* @param event - State change event to append
+* @returns Updated document with event in metadata.stateHistory
+*/
+function appendAuditEvent(document, event) {
+	const stateHistory = document.metadata?.stateHistory ?? [];
+	return {
+		...document,
+		metadata: {
+			...document.metadata,
+			stateHistory: [...stateHistory, event]
+		}
+	};
+}
+/**
+* Helper to get audit trail from document metadata
+*
+* Example:
+* ```typescript
+* const transaction = await Transaction.findById(id);
+* const history = getAuditTrail(transaction);
+*
+* console.log(history);
+* // [
+* //   { fromState: 'pending', toState: 'processing', changedAt: ... },
+* //   { fromState: 'processing', toState: 'verified', changedAt: ... },
+* // ]
+* ```
+*
+* @param document - Document to extract audit trail from
+* @returns Array of state change events (empty array if none)
+*/
+function getAuditTrail(document) {
+	return document.metadata?.stateHistory ?? [];
+}
+/**
+* Helper to get the last state change from audit trail
+*
+* @param document - Document to extract last change from
+* @returns Last state change event or undefined if none
+*/
+function getLastStateChange(document) {
+	const history = getAuditTrail(document);
+	return history[history.length - 1];
+}
+/**
+* Helper to find state changes by criteria
+*
+* Example:
+* ```typescript
+* const transaction = await Transaction.findById(id);
+*
+* // Find all changes made by a specific user
+* const userChanges = filterAuditTrail(transaction, {
+*   changedBy: 'admin_123'
+* });
+*
+* // Find all transitions to 'failed' state
+* const failures = filterAuditTrail(transaction, {
+*   toState: 'failed'
+* });
+* ```
+*
+* @param document - Document to filter audit trail from
+* @param criteria - Filter criteria
+* @returns Filtered array of state change events
+*/
+function filterAuditTrail(document, criteria) {
+	return getAuditTrail(document).filter((event) => {
+		return Object.entries(criteria).every(([key, value]) => {
+			return event[key] === value;
+		});
+	});
+}
+
+//#endregion
+//#region src/application/services/monetization.service.ts
+/**
+* Monetization Service
+* @classytic/revenue
+*
+* Framework-agnostic monetization management service with DI
+* Handles purchases, subscriptions, and free items using provider system
+*/
+/**
+* Monetization Service
+* Uses DI container for all dependencies
+*
+* Architecture:
+* - PluginManager: Wraps operations with lifecycle hooks (before/after)
+* - EventBus: Fire-and-forget notifications for completed operations
+*/
+var MonetizationService = class {
+	models;
+	providers;
+	config;
+	plugins;
+	logger;
+	events;
+	retryConfig;
+	circuitBreaker;
+	constructor(container) {
+		this.models = container.get("models");
+		this.providers = container.get("providers");
+		this.config = container.get("config");
+		this.plugins = container.get("plugins");
+		this.logger = container.get("logger");
+		this.events = container.get("events");
+		this.retryConfig = container.get("retryConfig");
+		this.circuitBreaker = container.get("circuitBreaker");
+	}
+	/**
+	* Create plugin context for hook execution
+	* @private
+	*/
+	getPluginContext(idempotencyKey) {
+		return {
+			events: this.events,
+			logger: this.logger,
+			storage: /* @__PURE__ */ new Map(),
+			meta: {
+				idempotencyKey: idempotencyKey ?? void 0,
+				requestId: nanoid(),
+				timestamp: /* @__PURE__ */ new Date()
+			}
+		};
+	}
+	/**
+	* Execute provider call with retry and circuit breaker protection
+	* @private
+	*/
+	async executeProviderCall(operation, operationName) {
+		const withCircuitBreaker = this.circuitBreaker ? () => this.circuitBreaker.execute(operation) : operation;
+		if (this.retryConfig && Object.keys(this.retryConfig).length > 0) return retry(withCircuitBreaker, {
+			...this.retryConfig,
+			onRetry: (error, attempt, delay) => {
+				this.logger.warn(`[${operationName}] Retry attempt ${attempt} after ${delay}ms:`, error);
+				this.retryConfig.onRetry?.(error, attempt, delay);
+			}
+		});
+		return withCircuitBreaker();
+	}
+	/**
+	* Create a new monetization (purchase, subscription, or free item)
+	*
+	* @param params - Monetization parameters
+	*
+	* @example
+	* // One-time purchase
+	* await revenue.monetization.create({
+	*   data: {
+	*     organizationId: '...',
+	*     customerId: '...',
+	*     sourceId: order._id,
+	*     sourceModel: 'Order',
+	*   },
+	*   planKey: 'one_time',
+	*   monetizationType: 'purchase',
+	*   gateway: 'bkash',
+	*   amount: 1500,
+	* });
+	*
+	* // Recurring subscription
+	* await revenue.monetization.create({
+	*   data: {
+	*     organizationId: '...',
+	*     customerId: '...',
+	*     sourceId: subscription._id,
+	*     sourceModel: 'Subscription',
+	*   },
+	*   planKey: 'monthly',
+	*   monetizationType: 'subscription',
+	*   gateway: 'stripe',
+	*   amount: 2000,
+	* });
+	*
+	* @returns Result with subscription, transaction, and paymentIntent
+	*/
+	async create(params) {
+		return this.plugins.executeHook("monetization.create.before", this.getPluginContext(params.idempotencyKey), params, async () => {
+			const { data, planKey, amount, currency = "BDT", gateway = "manual", entity = null, monetizationType = MONETIZATION_TYPES.SUBSCRIPTION, paymentData, metadata = {}, idempotencyKey = null } = params;
+			if (!planKey) throw new MissingRequiredFieldError("planKey");
+			if (amount < 0) throw new InvalidAmountError(amount);
+			const isFree = amount === 0;
+			const provider = this.providers[gateway];
+			if (!provider) throw new ProviderNotFoundError(gateway, Object.keys(this.providers));
+			let paymentIntent = null;
+			let transaction = null;
+			if (!isFree) {
+				try {
+					paymentIntent = await this.executeProviderCall(() => provider.createIntent({
+						amount,
+						currency,
+						metadata: {
+							...metadata,
+							type: "subscription",
+							planKey
+						}
+					}), `${gateway}.createIntent`);
+				} catch (error) {
+					throw new PaymentIntentCreationError(gateway, error);
+				}
+				const category = resolveCategory(entity, monetizationType, this.config.categoryMappings);
+				const transactionFlow = this.config.transactionTypeMapping?.[category] ?? this.config.transactionTypeMapping?.[monetizationType] ?? TRANSACTION_FLOW.INFLOW;
+				const commission = calculateCommission(amount, getCommissionRate(this.config, category), getGatewayFeeRate(this.config, gateway));
+				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,
+					type: category,
+					flow: transactionFlow,
+					tags: category === "subscription" ? ["recurring", "subscription"] : [],
+					amount: baseAmount,
+					currency,
+					fee: feeAmount,
+					tax: taxAmount,
+					net: netAmount,
+					...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",
+					gateway: {
+						type: gateway,
+						provider: gateway,
+						sessionId: paymentIntent.sessionId,
+						paymentIntentId: paymentIntent.paymentIntentId,
+						chargeId: paymentIntent.id,
+						metadata: paymentIntent.metadata
+					},
+					paymentDetails: { ...paymentData },
+					...commission && { commission },
+					...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;
+				subscription = (await this.plugins.executeHook("subscription.create.before", this.getPluginContext(idempotencyKey), {
+					subscriptionId: void 0,
+					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;
+			}
+			this.events.emit("monetization.created", {
+				monetizationType,
+				subscription: subscription ?? void 0,
+				transaction: transaction ?? void 0,
+				paymentIntent: paymentIntent ?? void 0
+			});
+			if (monetizationType === MONETIZATION_TYPES.PURCHASE) {
+				if (transaction) this.events.emit("purchase.created", {
+					monetizationType,
+					subscription: subscription ?? void 0,
+					transaction,
+					paymentIntent: paymentIntent ?? void 0
+				});
+			} else if (monetizationType === MONETIZATION_TYPES.SUBSCRIPTION) {
+				if (subscription) this.events.emit("subscription.created", {
+					subscriptionId: subscription._id.toString(),
+					subscription,
+					transactionId: transaction?._id?.toString()
+				});
+			} else if (monetizationType === MONETIZATION_TYPES.FREE) this.events.emit("free.created", {
+				monetizationType,
+				subscription: subscription ?? void 0,
+				transaction: transaction ?? void 0,
+				paymentIntent: paymentIntent ?? void 0
+			});
+			const result = {
+				subscription,
+				transaction,
+				paymentIntent
+			};
+			return this.plugins.executeHook("monetization.create.after", this.getPluginContext(params.idempotencyKey), params, async () => result);
+		});
+	}
+	/**
+	* Activate subscription after payment verification
+	*
+	* @param subscriptionId - Subscription ID or transaction ID
+	* @param options - Activation options
+	* @returns Updated subscription
+	*/
+	async activate(subscriptionId, options = {}) {
+		return this.plugins.executeHook("subscription.activate.before", this.getPluginContext(), {
+			subscriptionId,
+			...options
+		}, async () => {
+			const { timestamp = /* @__PURE__ */ new Date() } = options;
+			if (!this.models.Subscription) throw new ModelNotRegisteredError("Subscription");
+			const subscription = await this.models.Subscription.findById(subscriptionId);
+			if (!subscription) throw new SubscriptionNotFoundError(subscriptionId);
+			if (subscription.isActive) {
+				this.logger.warn("Subscription already active", { subscriptionId });
+				return subscription;
+			}
+			const periodEnd = this._calculatePeriodEnd(subscription.planKey, timestamp);
+			const auditEvent = SUBSCRIPTION_STATE_MACHINE.validateAndCreateAuditEvent(subscription.status, "active", subscription._id.toString(), {
+				changedBy: "system",
+				reason: `Subscription activated for plan: ${subscription.planKey}`,
+				metadata: {
+					planKey: subscription.planKey,
+					startDate: timestamp,
+					endDate: periodEnd
+				}
+			});
+			subscription.isActive = true;
+			subscription.status = "active";
+			subscription.startDate = timestamp;
+			subscription.endDate = periodEnd;
+			subscription.activatedAt = timestamp;
+			Object.assign(subscription, appendAuditEvent(subscription, auditEvent));
+			await subscription.save();
+			this.events.emit("subscription.activated", {
+				subscription,
+				activatedAt: timestamp
+			});
+			return this.plugins.executeHook("subscription.activate.after", this.getPluginContext(), {
+				subscriptionId,
+				...options
+			}, async () => subscription);
+		});
+	}
+	/**
+	* Renew subscription
+	*
+	* @param subscriptionId - Subscription ID
+	* @param params - Renewal parameters
+	* @returns { subscription, transaction, paymentIntent }
+	*/
+	async renew(subscriptionId, params = {}) {
+		const { gateway = "manual", entity = null, paymentData, metadata = {}, idempotencyKey = null } = params;
+		if (!this.models.Subscription) throw new ModelNotRegisteredError("Subscription");
+		const subscription = await this.models.Subscription.findById(subscriptionId);
+		if (!subscription) throw new SubscriptionNotFoundError(subscriptionId);
+		if (subscription.amount === 0) throw new InvalidAmountError(0, "Free subscriptions do not require renewal");
+		const provider = this.providers[gateway];
+		if (!provider) throw new ProviderNotFoundError(gateway, Object.keys(this.providers));
+		let paymentIntent = null;
+		try {
+			paymentIntent = await provider.createIntent({
+				amount: subscription.amount,
+				currency: subscription.currency ?? "BDT",
+				metadata: {
+					...metadata,
+					type: "subscription_renewal",
+					subscriptionId: subscription._id.toString()
+				}
+			});
+		} catch (error) {
+			this.logger.error("Failed to create payment intent for renewal:", error);
+			throw new PaymentIntentCreationError(gateway, error);
+		}
+		const effectiveEntity = entity ?? subscription.metadata?.entity;
+		const effectiveMonetizationType = subscription.metadata?.monetizationType ?? MONETIZATION_TYPES.SUBSCRIPTION;
+		const category = resolveCategory(effectiveEntity, effectiveMonetizationType, this.config.categoryMappings);
+		const transactionFlow = this.config.transactionTypeMapping?.[category] ?? this.config.transactionTypeMapping?.subscription_renewal ?? this.config.transactionTypeMapping?.[effectiveMonetizationType] ?? TRANSACTION_FLOW.INFLOW;
+		const commissionRate = getCommissionRate(this.config, category);
+		const gatewayFeeRate = getGatewayFeeRate(this.config, gateway);
+		const commission = calculateCommission(subscription.amount, commissionRate, gatewayFeeRate);
+		const feeAmount = commission?.gatewayFeeAmount || 0;
+		const netAmount = subscription.amount - feeAmount;
+		const transaction = await this.models.Transaction.create({
+			organizationId: subscription.organizationId,
+			customerId: subscription.customerId,
+			type: category,
+			flow: transactionFlow,
+			tags: [
+				"recurring",
+				"subscription",
+				"renewal"
+			],
+			amount: subscription.amount,
+			currency: subscription.currency ?? "BDT",
+			fee: feeAmount,
+			tax: 0,
+			net: netAmount,
+			method: paymentData?.method ?? "manual",
+			status: paymentIntent.status === "succeeded" ? "verified" : "pending",
+			gateway: {
+				provider: gateway,
+				sessionId: paymentIntent.sessionId,
+				paymentIntentId: paymentIntent.paymentIntentId,
+				chargeId: paymentIntent.id,
+				metadata: paymentIntent.metadata
+			},
+			paymentDetails: {
+				provider: gateway,
+				...paymentData
+			},
+			...commission && { commission },
+			sourceId: subscription._id,
+			sourceModel: "Subscription",
+			metadata: {
+				...metadata,
+				subscriptionId: subscription._id.toString(),
+				entity: effectiveEntity,
+				monetizationType: effectiveMonetizationType,
+				isRenewal: true,
+				paymentIntentId: paymentIntent.id
+			},
+			idempotencyKey: idempotencyKey ?? `renewal_${nanoid(16)}`
+		});
+		subscription.status = "pending_renewal";
+		subscription.renewalTransactionId = transaction._id;
+		subscription.renewalCount = (subscription.renewalCount ?? 0) + 1;
+		await subscription.save();
+		this.events.emit("subscription.renewed", {
+			subscription,
+			transaction,
+			paymentIntent: paymentIntent ?? void 0,
+			renewalCount: subscription.renewalCount
+		});
+		return {
+			subscription,
+			transaction,
+			paymentIntent
+		};
+	}
+	/**
+	* Cancel subscription
+	*
+	* @param subscriptionId - Subscription ID
+	* @param options - Cancellation options
+	* @returns Updated subscription
+	*/
+	async cancel(subscriptionId, options = {}) {
+		return this.plugins.executeHook("subscription.cancel.before", this.getPluginContext(), {
+			subscriptionId,
+			...options
+		}, async () => {
+			const { immediate = false, reason = null } = options;
+			if (!this.models.Subscription) throw new ModelNotRegisteredError("Subscription");
+			const subscription = await this.models.Subscription.findById(subscriptionId);
+			if (!subscription) throw new SubscriptionNotFoundError(subscriptionId);
+			const now = /* @__PURE__ */ new Date();
+			if (immediate) {
+				const auditEvent = SUBSCRIPTION_STATE_MACHINE.validateAndCreateAuditEvent(subscription.status, "cancelled", subscription._id.toString(), {
+					changedBy: "system",
+					reason: `Subscription cancelled immediately${reason ? ": " + reason : ""}`,
+					metadata: {
+						cancellationReason: reason,
+						immediate: true
+					}
+				});
+				subscription.isActive = false;
+				subscription.status = "cancelled";
+				subscription.canceledAt = now;
+				subscription.cancellationReason = reason;
+				Object.assign(subscription, appendAuditEvent(subscription, auditEvent));
+			} else {
+				subscription.cancelAt = subscription.endDate ?? now;
+				subscription.cancellationReason = reason;
+			}
+			await subscription.save();
+			this.events.emit("subscription.cancelled", {
+				subscription,
+				immediate,
+				reason: reason ?? void 0,
+				canceledAt: immediate ? now : subscription.cancelAt
+			});
+			return this.plugins.executeHook("subscription.cancel.after", this.getPluginContext(), {
+				subscriptionId,
+				...options
+			}, async () => subscription);
+		});
+	}
+	/**
+	* Pause subscription
+	*
+	* @param subscriptionId - Subscription ID
+	* @param options - Pause options
+	* @returns Updated subscription
+	*/
+	async pause(subscriptionId, options = {}) {
+		return this.plugins.executeHook("subscription.pause.before", this.getPluginContext(), {
+			subscriptionId,
+			...options
+		}, async () => {
+			const { reason = null } = options;
+			if (!this.models.Subscription) throw new ModelNotRegisteredError("Subscription");
+			const subscription = await this.models.Subscription.findById(subscriptionId);
+			if (!subscription) throw new SubscriptionNotFoundError(subscriptionId);
+			if (!subscription.isActive) throw new SubscriptionNotActiveError(subscriptionId, "Only active subscriptions can be paused");
+			const pausedAt = /* @__PURE__ */ new Date();
+			const auditEvent = SUBSCRIPTION_STATE_MACHINE.validateAndCreateAuditEvent(subscription.status, "paused", subscription._id.toString(), {
+				changedBy: "system",
+				reason: `Subscription paused${reason ? ": " + reason : ""}`,
+				metadata: {
+					pauseReason: reason,
+					pausedAt
+				}
+			});
+			subscription.isActive = false;
+			subscription.status = "paused";
+			subscription.pausedAt = pausedAt;
+			subscription.pauseReason = reason;
+			Object.assign(subscription, appendAuditEvent(subscription, auditEvent));
+			await subscription.save();
+			this.events.emit("subscription.paused", {
+				subscription,
+				reason: reason ?? void 0,
+				pausedAt
+			});
+			return this.plugins.executeHook("subscription.pause.after", this.getPluginContext(), {
+				subscriptionId,
+				...options
+			}, async () => subscription);
+		});
+	}
+	/**
+	* Resume subscription
+	*
+	* @param subscriptionId - Subscription ID
+	* @param options - Resume options
+	* @returns Updated subscription
+	*/
+	async resume(subscriptionId, options = {}) {
+		return this.plugins.executeHook("subscription.resume.before", this.getPluginContext(), {
+			subscriptionId,
+			...options
+		}, async () => {
+			const { extendPeriod = false } = options;
+			if (!this.models.Subscription) throw new ModelNotRegisteredError("Subscription");
+			const subscription = await this.models.Subscription.findById(subscriptionId);
+			if (!subscription) throw new SubscriptionNotFoundError(subscriptionId);
+			if (!subscription.pausedAt) throw new InvalidStateTransitionError("resume", "paused", subscription.status, "Only paused subscriptions can be resumed");
+			const now = /* @__PURE__ */ new Date();
+			const pausedAt = new Date(subscription.pausedAt);
+			const pauseDuration = now.getTime() - pausedAt.getTime();
+			const auditEvent = SUBSCRIPTION_STATE_MACHINE.validateAndCreateAuditEvent(subscription.status, "active", subscription._id.toString(), {
+				changedBy: "system",
+				reason: "Subscription resumed from paused state",
+				metadata: {
+					pausedAt,
+					pauseDuration,
+					extendPeriod,
+					newEndDate: extendPeriod && subscription.endDate ? new Date(new Date(subscription.endDate).getTime() + pauseDuration) : void 0
+				}
+			});
+			subscription.isActive = true;
+			subscription.status = "active";
+			subscription.pausedAt = null;
+			subscription.pauseReason = null;
+			if (extendPeriod && subscription.endDate) {
+				const currentEnd = new Date(subscription.endDate);
+				subscription.endDate = new Date(currentEnd.getTime() + pauseDuration);
+			}
+			Object.assign(subscription, appendAuditEvent(subscription, auditEvent));
+			await subscription.save();
+			this.events.emit("subscription.resumed", {
+				subscription,
+				extendPeriod,
+				pauseDuration,
+				resumedAt: now
+			});
+			return this.plugins.executeHook("subscription.resume.after", this.getPluginContext(), {
+				subscriptionId,
+				...options
+			}, async () => subscription);
+		});
+	}
+	/**
+	* List subscriptions with filters
+	*
+	* @param filters - Query filters
+	* @param options - Query options (limit, skip, sort)
+	* @returns Subscriptions
+	*/
+	async list(filters = {}, options = {}) {
+		if (!this.models.Subscription) throw new ModelNotRegisteredError("Subscription");
+		const SubscriptionModel = this.models.Subscription;
+		const { limit = 50, skip = 0, sort = { createdAt: -1 } } = options;
+		return await SubscriptionModel.find(filters).limit(limit).skip(skip).sort(sort);
+	}
+	/**
+	* Get subscription by ID
+	*
+	* @param subscriptionId - Subscription ID
+	* @returns Subscription
+	*/
+	async get(subscriptionId) {
+		if (!this.models.Subscription) throw new ModelNotRegisteredError("Subscription");
+		const subscription = await this.models.Subscription.findById(subscriptionId);
+		if (!subscription) throw new SubscriptionNotFoundError(subscriptionId);
+		return subscription;
+	}
+	/**
+	* Calculate period end date based on plan key
+	* @private
+	*/
+	_calculatePeriodEnd(planKey, startDate = /* @__PURE__ */ new Date()) {
+		const start = new Date(startDate);
+		const end = new Date(start);
+		switch (planKey) {
+			case "monthly":
+				end.setMonth(end.getMonth() + 1);
+				break;
+			case "quarterly":
+				end.setMonth(end.getMonth() + 3);
+				break;
+			case "yearly":
+				end.setFullYear(end.getFullYear() + 1);
+				break;
+			default: end.setDate(end.getDate() + 30);
+		}
+		return end;
+	}
+};
+
+//#endregion
+//#region src/application/services/payment.service.ts
+/**
+* Payment Service
+* @classytic/revenue
+*
+* Framework-agnostic payment verification and management service with DI
+* Handles payment verification, refunds, and status updates
+*/
+/**
+* Payment Service
+* Uses DI container for all dependencies
+*
+* Architecture:
+* - PluginManager: Wraps operations with lifecycle hooks (before/after)
+* - EventBus: Fire-and-forget notifications for completed operations
+*/
+var PaymentService = class {
+	models;
+	providers;
+	config;
+	plugins;
+	logger;
+	events;
+	retryConfig;
+	circuitBreaker;
+	constructor(container) {
+		this.models = container.get("models");
+		this.providers = container.get("providers");
+		this.config = container.get("config");
+		this.plugins = container.get("plugins");
+		this.logger = container.get("logger");
+		this.events = container.get("events");
+		this.retryConfig = container.get("retryConfig");
+		this.circuitBreaker = container.get("circuitBreaker");
+	}
+	/**
+	* Create plugin context for hook execution
+	* @private
+	*/
+	getPluginContext(idempotencyKey) {
+		return {
+			events: this.events,
+			logger: this.logger,
+			storage: /* @__PURE__ */ new Map(),
+			meta: {
+				idempotencyKey,
+				requestId: nanoid(),
+				timestamp: /* @__PURE__ */ new Date()
+			}
+		};
+	}
+	/**
+	* Execute provider call with retry and circuit breaker protection
+	* @private
+	*/
+	async executeProviderCall(operation, operationName) {
+		const withCircuitBreaker = this.circuitBreaker ? () => this.circuitBreaker.execute(operation) : operation;
+		if (this.retryConfig && Object.keys(this.retryConfig).length > 0) return retry(withCircuitBreaker, {
+			...this.retryConfig,
+			onRetry: (error, attempt, delay) => {
+				this.logger.warn(`[${operationName}] Retry attempt ${attempt} after ${delay}ms:`, error);
+				this.retryConfig.onRetry?.(error, attempt, delay);
+			}
+		});
+		return withCircuitBreaker();
+	}
+	/**
+	* Verify a payment
+	*
+	* @param paymentIntentId - Payment intent ID, session ID, or transaction ID
+	* @param options - Verification options
+	* @returns { transaction, status }
+	*/
+	async verify(paymentIntentId, options = {}) {
+		return this.plugins.executeHook("payment.verify.before", this.getPluginContext(), {
+			id: paymentIntentId,
+			...options
+		}, async () => {
+			const { verifiedBy = null } = options;
+			const TransactionModel = this.models.Transaction;
+			const transaction = await this._findTransaction(TransactionModel, paymentIntentId);
+			if (!transaction) throw new TransactionNotFoundError(paymentIntentId);
+			if (transaction.status === "verified" || transaction.status === "completed") throw new AlreadyVerifiedError(transaction._id.toString());
+			const gatewayType = transaction.gateway?.type ?? "manual";
+			const provider = this.providers[gatewayType];
+			if (!provider) throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
+			let paymentResult = null;
+			try {
+				const actualIntentId = transaction.gateway?.paymentIntentId || transaction.gateway?.sessionId || paymentIntentId;
+				paymentResult = await this.executeProviderCall(() => provider.verifyPayment(actualIntentId), `${gatewayType}.verifyPayment`);
+			} catch (error) {
+				this.logger.error("Payment verification failed:", error);
+				const auditEvent = 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, auditEvent));
+				transaction.metadata = {
+					...transaction.metadata,
+					verificationError: error.message,
+					failedAt: (/* @__PURE__ */ new Date()).toISOString()
+				};
+				await transaction.save();
+				this.events.emit("payment.failed", {
+					transaction,
+					error: error.message,
+					provider: gatewayType,
+					paymentIntentId
+				});
+				throw new PaymentVerificationError(paymentIntentId, error.message);
+			}
+			if (paymentResult.amount && paymentResult.amount !== transaction.amount) throw new ValidationError(`Amount mismatch: expected ${transaction.amount}, got ${paymentResult.amount}`, {
+				expected: transaction.amount,
+				actual: paymentResult.amount
+			});
+			if (paymentResult.currency && paymentResult.currency.toUpperCase() !== transaction.currency.toUpperCase()) throw new ValidationError(`Currency mismatch: expected ${transaction.currency}, got ${paymentResult.currency}`, {
+				expected: transaction.currency,
+				actual: paymentResult.currency
+			});
+			const newStatus = paymentResult.status === "succeeded" ? "verified" : paymentResult.status;
+			const auditEvent = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(transaction.status, newStatus, transaction._id.toString(), {
+				changedBy: verifiedBy ?? "system",
+				reason: `Payment verification ${paymentResult.status === "succeeded" ? "succeeded" : "resulted in status: " + newStatus}`,
+				metadata: { paymentResult: paymentResult.metadata }
+			});
+			transaction.status = newStatus;
+			transaction.verifiedAt = paymentResult.paidAt ?? /* @__PURE__ */ new Date();
+			transaction.verifiedBy = verifiedBy;
+			transaction.gateway = {
+				...transaction.gateway,
+				type: transaction.gateway?.type ?? "manual",
+				verificationData: paymentResult.metadata
+			};
+			Object.assign(transaction, appendAuditEvent(transaction, auditEvent));
+			await transaction.save();
+			if (newStatus === "verified") this.events.emit("payment.verified", {
+				transaction,
+				paymentResult,
+				verifiedBy: verifiedBy || void 0
+			});
+			else if (newStatus === "failed") this.events.emit("payment.failed", {
+				transaction,
+				error: paymentResult.metadata?.errorMessage || "Payment verification failed",
+				provider: gatewayType,
+				paymentIntentId: transaction.gateway?.paymentIntentId || transaction.gateway?.sessionId || paymentIntentId
+			});
+			else if (newStatus === "requires_action") this.events.emit("payment.requires_action", {
+				transaction,
+				paymentResult,
+				action: paymentResult.metadata?.requiredAction
+			});
+			else if (newStatus === "processing") this.events.emit("payment.processing", {
+				transaction,
+				paymentResult
+			});
+			const result = {
+				transaction,
+				paymentResult,
+				status: transaction.status
+			};
+			return this.plugins.executeHook("payment.verify.after", this.getPluginContext(), {
+				id: paymentIntentId,
+				...options
+			}, async () => result);
+		});
+	}
+	/**
+	* Get payment status
+	*
+	* @param paymentIntentId - Payment intent ID, session ID, or transaction ID
+	* @returns { transaction, status }
+	*/
+	async getStatus(paymentIntentId) {
+		const TransactionModel = this.models.Transaction;
+		const transaction = await this._findTransaction(TransactionModel, paymentIntentId);
+		if (!transaction) throw new TransactionNotFoundError(paymentIntentId);
+		const gatewayType = transaction.gateway?.type ?? "manual";
+		const provider = this.providers[gatewayType];
+		if (!provider) throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
+		let paymentResult = null;
+		try {
+			const actualIntentId = transaction.gateway?.paymentIntentId || transaction.gateway?.sessionId || paymentIntentId;
+			paymentResult = await this.executeProviderCall(() => provider.getStatus(actualIntentId), `${gatewayType}.getStatus`);
+		} catch (error) {
+			this.logger.warn("Failed to get payment status from provider:", error);
+			return {
+				transaction,
+				status: transaction.status,
+				provider: gatewayType
+			};
+		}
+		return {
+			transaction,
+			paymentResult,
+			status: paymentResult.status,
+			provider: gatewayType
+		};
+	}
+	/**
+	* Refund a payment
+	*
+	* @param paymentId - Payment intent ID, session ID, or transaction ID
+	* @param amount - Amount to refund (optional, full refund if not provided)
+	* @param options - Refund options
+	* @returns { transaction, refundResult }
+	*/
+	async refund(paymentId, amount = null, options = {}) {
+		return this.plugins.executeHook("payment.refund.before", this.getPluginContext(), {
+			transactionId: paymentId,
+			amount,
+			...options
+		}, async () => {
+			const { reason = null } = options;
+			const TransactionModel = this.models.Transaction;
+			const transaction = await this._findTransaction(TransactionModel, paymentId);
+			if (!transaction) throw new TransactionNotFoundError(paymentId);
+			if (transaction.status !== "verified" && transaction.status !== "completed" && transaction.status !== "partially_refunded") throw new InvalidStateTransitionError("transaction", transaction._id.toString(), transaction.status, "verified, completed, or partially_refunded");
+			const gatewayType = transaction.gateway?.type ?? "manual";
+			const provider = this.providers[gatewayType];
+			if (!provider) throw new ProviderNotFoundError(gatewayType, Object.keys(this.providers));
+			if (!provider.getCapabilities().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 && 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,
+				type: "refund",
+				flow: refundFlow,
+				tags: ["refund"],
+				amount: refundAmount,
+				currency: transaction.currency,
+				fee: refundFeeAmount,
+				tax: refundTaxAmount,
+				net: refundNetAmount,
+				...transaction.taxDetails && { taxDetails: transaction.taxDetails },
+				method: transaction.method ?? "manual",
+				status: "completed",
+				gateway: {
+					type: transaction.gateway?.type ?? gatewayType,
+					provider: transaction.gateway?.provider ?? "manual",
+					paymentIntentId: refundResult.id,
+					chargeId: refundResult.id
+				},
+				paymentDetails: transaction.paymentDetails,
+				...refundCommission && { commission: refundCommission },
+				...transaction.sourceId && { sourceId: transaction.sourceId },
+				...transaction.sourceModel && { sourceModel: transaction.sourceModel },
+				relatedTransactionId: transaction._id,
+				metadata: {
+					...transaction.metadata,
+					isRefund: true,
+					originalTransactionId: transaction._id.toString(),
+					refundReason: reason,
+					refundResult: refundResult.metadata
+				},
+				idempotencyKey: `refund_${transaction._id}_${Date.now()}`
+			});
+			const isPartialRefund = refundAmount < refundableAmount;
+			const refundStatus = isPartialRefund ? "partially_refunded" : "refunded";
+			const auditEvent = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(transaction.status, refundStatus, transaction._id.toString(), {
+				changedBy: "system",
+				reason: `Refund processed: ${isPartialRefund ? "partial" : "full"} refund of ${refundAmount}${reason ? " - " + reason : ""}`,
+				metadata: {
+					refundAmount,
+					isPartialRefund,
+					refundTransactionId: refundTransaction._id.toString()
+				}
+			});
+			transaction.status = refundStatus;
+			transaction.refundedAmount = (transaction.refundedAmount ?? 0) + refundAmount;
+			transaction.refundedAt = refundResult.refundedAt ?? /* @__PURE__ */ new Date();
+			Object.assign(transaction, appendAuditEvent(transaction, auditEvent));
+			transaction.metadata = {
+				...transaction.metadata,
+				refundTransactionId: refundTransaction._id.toString(),
+				refundReason: reason
+			};
+			await transaction.save();
+			this.events.emit("payment.refunded", {
+				transaction,
+				refundTransaction,
+				refundResult: {
+					...refundResult,
+					currency: refundResult.currency ?? "USD",
+					metadata: refundResult.metadata ?? {}
+				},
+				refundAmount,
+				reason: reason ?? void 0,
+				isPartialRefund
+			});
+			const result = {
+				transaction,
+				refundTransaction,
+				refundResult,
+				status: transaction.status
+			};
+			return this.plugins.executeHook("payment.refund.after", this.getPluginContext(), {
+				transactionId: paymentId,
+				amount,
+				...options
+			}, async () => result);
+		});
+	}
+	/**
+	* Handle webhook from payment provider
+	*
+	* @param provider - Provider name
+	* @param payload - Webhook payload
+	* @param headers - Request headers
+	* @returns { event, transaction }
+	*/
+	async handleWebhook(providerName, payload, headers = {}) {
+		const provider = this.providers[providerName];
+		if (!provider) throw new ProviderNotFoundError(providerName, Object.keys(this.providers));
+		if (!provider.getCapabilities().supportsWebhooks) throw new ProviderCapabilityError(providerName, "webhooks");
+		let webhookEvent;
+		try {
+			webhookEvent = await this.executeProviderCall(() => provider.handleWebhook(payload, headers), `${providerName}.handleWebhook`);
+		} catch (error) {
+			this.logger.error("Webhook processing failed:", error);
+			throw new ProviderError(`Webhook processing failed for ${providerName}: ${error.message}`, "WEBHOOK_PROCESSING_FAILED", { retryable: false });
+		}
+		if (!webhookEvent?.data?.sessionId && !webhookEvent?.data?.paymentIntentId) throw new ValidationError(`Invalid webhook event structure from ${providerName}: missing sessionId or paymentIntentId`, {
+			provider: providerName,
+			eventType: webhookEvent?.type
+		});
+		const TransactionModel = this.models.Transaction;
+		let transaction = null;
+		if (webhookEvent.data.sessionId) transaction = await TransactionModel.findOne({ "gateway.sessionId": webhookEvent.data.sessionId });
+		if (!transaction && webhookEvent.data.paymentIntentId) transaction = await TransactionModel.findOne({ "gateway.paymentIntentId": webhookEvent.data.paymentIntentId });
+		if (!transaction) {
+			this.logger.warn("Transaction not found for webhook event", {
+				provider: providerName,
+				eventId: webhookEvent.id,
+				sessionId: webhookEvent.data.sessionId,
+				paymentIntentId: webhookEvent.data.paymentIntentId
+			});
+			throw new TransactionNotFoundError(webhookEvent.data.sessionId ?? webhookEvent.data.paymentIntentId ?? "unknown");
+		}
+		if (webhookEvent.data.sessionId && !transaction.gateway?.sessionId) transaction.gateway = {
+			...transaction.gateway,
+			type: transaction.gateway?.type ?? "manual",
+			sessionId: webhookEvent.data.sessionId
+		};
+		if (webhookEvent.data.paymentIntentId && !transaction.gateway?.paymentIntentId) transaction.gateway = {
+			...transaction.gateway,
+			type: transaction.gateway?.type ?? "manual",
+			paymentIntentId: webhookEvent.data.paymentIntentId
+		};
+		if (transaction.webhook?.eventId === webhookEvent.id && transaction.webhook?.processedAt) {
+			this.logger.warn("Webhook already processed", {
+				transactionId: transaction._id,
+				eventId: webhookEvent.id
+			});
+			return {
+				event: webhookEvent,
+				transaction,
+				status: "already_processed"
+			};
+		}
+		transaction.webhook = {
+			eventId: webhookEvent.id,
+			eventType: webhookEvent.type,
+			receivedAt: /* @__PURE__ */ new Date(),
+			processedAt: /* @__PURE__ */ new Date(),
+			data: webhookEvent.data
+		};
+		let newStatus = transaction.status;
+		if (webhookEvent.type === "payment.succeeded") newStatus = "verified";
+		else if (webhookEvent.type === "payment.failed") newStatus = "failed";
+		else if (webhookEvent.type === "refund.succeeded") newStatus = "refunded";
+		if (newStatus !== transaction.status) {
+			const auditEvent = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(transaction.status, newStatus, transaction._id.toString(), {
+				changedBy: "webhook",
+				reason: `Webhook event: ${webhookEvent.type}`,
+				metadata: {
+					webhookId: webhookEvent.id,
+					webhookType: webhookEvent.type,
+					webhookData: webhookEvent.data
+				}
+			});
+			transaction.status = newStatus;
+			if (newStatus === "verified") transaction.verifiedAt = webhookEvent.createdAt;
+			else if (newStatus === "refunded") transaction.refundedAt = webhookEvent.createdAt;
+			else if (newStatus === "failed") transaction.failedAt = webhookEvent.createdAt;
+			Object.assign(transaction, appendAuditEvent(transaction, auditEvent));
+		}
+		await transaction.save();
+		this.events.emit("webhook.processed", {
+			webhookType: webhookEvent.type,
+			provider: webhookEvent.provider,
+			event: webhookEvent,
+			transaction,
+			processedAt: /* @__PURE__ */ new Date()
+		});
+		return {
+			event: webhookEvent,
+			transaction,
+			status: "processed"
+		};
+	}
+	/**
+	* List payments/transactions with filters
+	*
+	* @param filters - Query filters
+	* @param options - Query options (limit, skip, sort)
+	* @returns Transactions
+	*/
+	async list(filters = {}, options = {}) {
+		const TransactionModel = this.models.Transaction;
+		const { limit = 50, skip = 0, sort = { createdAt: -1 } } = options;
+		return await TransactionModel.find(filters).limit(limit).skip(skip).sort(sort);
+	}
+	/**
+	* Get payment/transaction by ID
+	*
+	* @param transactionId - Transaction ID
+	* @returns Transaction
+	*/
+	async get(transactionId) {
+		const transaction = await this.models.Transaction.findById(transactionId);
+		if (!transaction) throw new TransactionNotFoundError(transactionId);
+		return transaction;
+	}
+	/**
+	* Get provider instance
+	*
+	* @param providerName - Provider name
+	* @returns Provider instance
+	*/
+	getProvider(providerName) {
+		const provider = this.providers[providerName];
+		if (!provider) throw new ProviderNotFoundError(providerName, Object.keys(this.providers));
+		return provider;
+	}
+	/**
+	* Find transaction by sessionId, paymentIntentId, or transaction ID
+	* @private
+	*/
+	async _findTransaction(TransactionModel, identifier) {
+		let transaction = await TransactionModel.findOne({ "gateway.sessionId": identifier });
+		if (!transaction) transaction = await TransactionModel.findOne({ "gateway.paymentIntentId": identifier });
+		if (!transaction) transaction = await TransactionModel.findById(identifier);
+		return transaction;
+	}
+};
+
+//#endregion
+//#region src/application/services/transaction.service.ts
+/**
+* Transaction Service
+* @classytic/revenue
+*
+* Thin, focused transaction service for core operations
+* Users handle their own analytics, exports, and complex queries
+*
+* Works with ANY model implementation:
+* - Plain Mongoose models
+* - @classytic/mongokit Repository instances
+* - Any other abstraction with compatible interface
+*/
+/**
+* Transaction Service
+* Focused on core transaction lifecycle operations
+*
+* Architecture:
+* - PluginManager: Wraps operations with lifecycle hooks (before/after)
+* - EventBus: Fire-and-forget notifications for completed operations
+*/
+var TransactionService = class {
+	models;
+	plugins;
+	events;
+	logger;
+	constructor(container) {
+		this.models = container.get("models");
+		this.plugins = container.get("plugins");
+		this.events = container.get("events");
+		this.logger = container.get("logger");
+	}
+	/**
+	* Create plugin context for hook execution
+	* @private
+	*/
+	getPluginContext() {
+		return {
+			events: this.events,
+			logger: this.logger,
+			storage: /* @__PURE__ */ new Map(),
+			meta: {
+				requestId: nanoid(),
+				timestamp: /* @__PURE__ */ new Date()
+			}
+		};
+	}
+	/**
+	* Get transaction by ID
+	*
+	* @param transactionId - Transaction ID
+	* @returns Transaction
+	*/
+	async get(transactionId) {
+		const transaction = await this.models.Transaction.findById(transactionId);
+		if (!transaction) throw new TransactionNotFoundError(transactionId);
+		return transaction;
+	}
+	/**
+	* List transactions with filters
+	*
+	* @param filters - Query filters
+	* @param options - Query options (limit, skip, sort, populate)
+	* @returns { transactions, total, page, limit }
+	*/
+	async list(filters = {}, options = {}) {
+		const TransactionModel = this.models.Transaction;
+		const { limit = 50, skip = 0, page = null, sort = { createdAt: -1 }, populate = [] } = options;
+		const actualSkip = page ? (page - 1) * limit : skip;
+		let query = TransactionModel.find(filters).limit(limit).skip(actualSkip).sort(sort);
+		if (populate.length > 0 && typeof query.populate === "function") populate.forEach((field) => {
+			query = query.populate(field);
+		});
+		const transactions = await query;
+		const model = TransactionModel;
+		const total = await (model.countDocuments ? model.countDocuments(filters) : model.count?.(filters)) ?? 0;
+		return {
+			transactions,
+			total,
+			page: page ?? Math.floor(actualSkip / limit) + 1,
+			limit,
+			pages: Math.ceil(total / limit)
+		};
+	}
+	/**
+	* Update transaction
+	*
+	* @param transactionId - Transaction ID
+	* @param updates - Fields to update
+	* @returns Updated transaction
+	*/
+	async update(transactionId, updates) {
+		const hookInput = {
+			transactionId,
+			updates
+		};
+		return this.plugins.executeHook("transaction.update.before", this.getPluginContext(), hookInput, async () => {
+			const TransactionModel = this.models.Transaction;
+			const effectiveUpdates = hookInput.updates;
+			const model = TransactionModel;
+			let transaction;
+			if (typeof model.update === "function") transaction = await model.update(transactionId, effectiveUpdates);
+			else if (typeof model.findByIdAndUpdate === "function") transaction = await model.findByIdAndUpdate(transactionId, { $set: effectiveUpdates }, { new: true });
+			else throw new Error("Transaction model does not support update operations");
+			if (!transaction) throw new TransactionNotFoundError(transactionId);
+			this.events.emit("transaction.updated", {
+				transaction,
+				updates: effectiveUpdates
+			});
+			return this.plugins.executeHook("transaction.update.after", this.getPluginContext(), {
+				transactionId,
+				updates: effectiveUpdates
+			}, async () => transaction);
+		});
+	}
+};
+
+//#endregion
+//#region src/application/services/escrow.service.ts
+/**
+* Escrow Service
+* @classytic/revenue
+*
+* Platform-as-intermediary payment flow
+* Hold funds → Verify → Split/Deduct → Release to organization
+*/
+/**
+* Escrow Service
+* Uses DI container for all dependencies
+*
+* Architecture:
+* - PluginManager: Wraps operations with lifecycle hooks (before/after)
+* - EventBus: Fire-and-forget notifications for completed operations
+*/
+var EscrowService = class {
+	models;
+	plugins;
+	logger;
+	events;
+	constructor(container) {
+		this.models = container.get("models");
+		this.plugins = container.get("plugins");
+		this.logger = container.get("logger");
+		this.events = container.get("events");
+	}
+	/**
+	* Create plugin context for hook execution
+	* @private
+	*/
+	getPluginContext() {
+		return {
+			events: this.events,
+			logger: this.logger,
+			storage: /* @__PURE__ */ new Map(),
+			meta: {
+				requestId: nanoid(),
+				timestamp: /* @__PURE__ */ new Date()
+			}
+		};
+	}
+	/**
+	* Hold funds in escrow
+	*
+	* @param transactionId - Transaction to hold
+	* @param options - Hold options
+	* @returns Updated transaction
+	*/
+	async hold(transactionId, options = {}) {
+		return this.plugins.executeHook("escrow.hold.before", this.getPluginContext(), {
+			transactionId,
+			...options
+		}, async () => {
+			const { reason = HOLD_REASON.PAYMENT_VERIFICATION, holdUntil = null, metadata = {} } = options;
+			const transaction = await this.models.Transaction.findById(transactionId);
+			if (!transaction) throw new TransactionNotFoundError(transactionId);
+			if (transaction.status !== TRANSACTION_STATUS.VERIFIED) throw new InvalidStateTransitionError("transaction", transaction._id.toString(), transaction.status, TRANSACTION_STATUS.VERIFIED);
+			const heldAmount = transaction.amount;
+			transaction.hold = {
+				status: HOLD_STATUS.HELD,
+				heldAmount,
+				releasedAmount: 0,
+				reason,
+				heldAt: /* @__PURE__ */ new Date(),
+				...holdUntil && { holdUntil },
+				releases: [],
+				metadata
+			};
+			await transaction.save();
+			this.events.emit("escrow.held", {
+				transaction,
+				heldAmount,
+				reason
+			});
+			return this.plugins.executeHook("escrow.hold.after", this.getPluginContext(), {
+				transactionId,
+				...options
+			}, async () => transaction);
+		});
+	}
+	/**
+	* Release funds from escrow to recipient
+	*
+	* @param transactionId - Transaction to release
+	* @param options - Release options
+	* @returns { transaction, releaseTransaction }
+	*/
+	async release(transactionId, options) {
+		return this.plugins.executeHook("escrow.release.before", this.getPluginContext(), {
+			transactionId,
+			...options
+		}, async () => {
+			const { amount = null, recipientId, recipientType = "organization", reason = RELEASE_REASON.PAYMENT_VERIFIED, releasedBy = null, createTransaction = true, metadata = {} } = options;
+			const TransactionModel = this.models.Transaction;
+			const transaction = await TransactionModel.findById(transactionId);
+			if (!transaction) throw new TransactionNotFoundError(transactionId);
+			if (!transaction.hold || transaction.hold.status !== HOLD_STATUS.HELD) throw new InvalidStateTransitionError("escrow_hold", transaction._id.toString(), transaction.hold?.status ?? "none", HOLD_STATUS.HELD);
+			if (!recipientId) throw new ValidationError("recipientId is required for release", { transactionId });
+			const releaseAmount = amount ?? transaction.hold.heldAmount - transaction.hold.releasedAmount;
+			const availableAmount = transaction.hold.heldAmount - transaction.hold.releasedAmount;
+			if (releaseAmount > availableAmount) throw new ValidationError(`Release amount (${releaseAmount}) exceeds available held amount (${availableAmount})`, {
+				releaseAmount,
+				availableAmount,
+				transactionId
+			});
+			const releaseRecord = {
+				amount: releaseAmount,
+				recipientId,
+				recipientType,
+				releasedAt: /* @__PURE__ */ new Date(),
+				releasedBy,
+				reason,
+				metadata
+			};
+			transaction.hold.releases.push(releaseRecord);
+			transaction.hold.releasedAmount += releaseAmount;
+			const isFullRelease = transaction.hold.releasedAmount >= transaction.hold.heldAmount;
+			const isPartialRelease = transaction.hold.releasedAmount > 0 && transaction.hold.releasedAmount < transaction.hold.heldAmount;
+			if (isFullRelease) {
+				const holdAuditEvent = HOLD_STATE_MACHINE.validateAndCreateAuditEvent(transaction.hold.status, HOLD_STATUS.RELEASED, transaction._id.toString(), {
+					changedBy: releasedBy ?? "system",
+					reason: `Escrow hold fully released: ${releaseAmount} to ${recipientId}${reason ? " - " + reason : ""}`,
+					metadata: {
+						releaseAmount,
+						recipientId,
+						releaseReason: reason
+					}
+				});
+				transaction.hold.status = HOLD_STATUS.RELEASED;
+				transaction.hold.releasedAt = /* @__PURE__ */ new Date();
+				const transactionAuditEvent = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(transaction.status, TRANSACTION_STATUS.COMPLETED, transaction._id.toString(), {
+					changedBy: releasedBy ?? "system",
+					reason: `Transaction completed after full escrow release`,
+					metadata: {
+						releaseAmount,
+						recipientId
+					}
+				});
+				transaction.status = TRANSACTION_STATUS.COMPLETED;
+				Object.assign(transaction, appendAuditEvent(transaction, holdAuditEvent));
+				Object.assign(transaction, appendAuditEvent(transaction, transactionAuditEvent));
+			} else if (isPartialRelease) {
+				const auditEvent = HOLD_STATE_MACHINE.validateAndCreateAuditEvent(transaction.hold.status, HOLD_STATUS.PARTIALLY_RELEASED, transaction._id.toString(), {
+					changedBy: releasedBy ?? "system",
+					reason: `Partial escrow release: ${releaseAmount} of ${transaction.hold.heldAmount} to ${recipientId}${reason ? " - " + reason : ""}`,
+					metadata: {
+						releaseAmount,
+						recipientId,
+						releaseReason: reason,
+						remainingHeld: transaction.hold.heldAmount - transaction.hold.releasedAmount
+					}
+				});
+				transaction.hold.status = HOLD_STATUS.PARTIALLY_RELEASED;
+				Object.assign(transaction, appendAuditEvent(transaction, auditEvent));
+			}
+			if ("markModified" in transaction) transaction.markModified("hold");
+			await transaction.save();
+			let releaseTaxAmount = 0;
+			if (transaction.tax && transaction.tax > 0) if (releaseAmount === availableAmount && !amount) {
+				const releasedTaxSoFar = transaction.hold.releasedTaxAmount ?? 0;
+				releaseTaxAmount = transaction.tax - releasedTaxSoFar;
+			} else {
+				const totalAmount = transaction.amount + transaction.tax;
+				if (totalAmount > 0) {
+					const taxRatio = transaction.tax / totalAmount;
+					releaseTaxAmount = Math.round(releaseAmount * taxRatio);
+				}
+			}
+			const releaseNetAmount = releaseAmount - releaseTaxAmount;
+			let releaseTransaction = null;
+			if (createTransaction) releaseTransaction = await TransactionModel.create({
+				organizationId: transaction.organizationId,
+				customerId: recipientId,
+				type: "escrow_release",
+				flow: "inflow",
+				tags: ["escrow", "release"],
+				amount: releaseAmount,
+				currency: transaction.currency,
+				fee: 0,
+				tax: releaseTaxAmount,
+				net: releaseNetAmount,
+				...transaction.taxDetails && { taxDetails: transaction.taxDetails },
+				method: transaction.method,
+				status: "completed",
+				gateway: transaction.gateway,
+				sourceId: transaction._id,
+				sourceModel: "Transaction",
+				relatedTransactionId: transaction._id,
+				metadata: {
+					...metadata,
+					isRelease: true,
+					heldTransactionId: transaction._id.toString(),
+					releaseReason: reason,
+					recipientType,
+					originalCategory: transaction.category
+				},
+				idempotencyKey: `release_${transaction._id}_${Date.now()}`
+			});
+			this.events.emit("escrow.released", {
+				transaction,
+				releaseTransaction,
+				releaseAmount,
+				recipientId,
+				recipientType,
+				reason,
+				isFullRelease,
+				isPartialRelease
+			});
+			const result = {
+				transaction,
+				releaseTransaction,
+				releaseAmount,
+				isFullRelease,
+				isPartialRelease
+			};
+			return this.plugins.executeHook("escrow.release.after", this.getPluginContext(), {
+				transactionId,
+				...options
+			}, async () => result);
+		});
+	}
+	/**
+	* Cancel hold and release back to customer
+	*
+	* @param transactionId - Transaction to cancel hold
+	* @param options - Cancel options
+	* @returns Updated transaction
+	*/
+	async cancel(transactionId, options = {}) {
+		const { reason = "Hold cancelled", metadata = {} } = options;
+		const transaction = await this.models.Transaction.findById(transactionId);
+		if (!transaction) throw new TransactionNotFoundError(transactionId);
+		if (!transaction.hold || transaction.hold.status !== HOLD_STATUS.HELD) throw new InvalidStateTransitionError("escrow_hold", transaction._id.toString(), transaction.hold?.status ?? "none", HOLD_STATUS.HELD);
+		const holdAuditEvent = HOLD_STATE_MACHINE.validateAndCreateAuditEvent(transaction.hold.status, HOLD_STATUS.CANCELLED, transaction._id.toString(), {
+			changedBy: "system",
+			reason: `Escrow hold cancelled${reason ? ": " + reason : ""}`,
+			metadata: {
+				cancelReason: reason,
+				...metadata
+			}
+		});
+		transaction.hold.status = HOLD_STATUS.CANCELLED;
+		transaction.hold.cancelledAt = /* @__PURE__ */ new Date();
+		transaction.hold.metadata = {
+			...transaction.hold.metadata,
+			...metadata,
+			cancelReason: reason
+		};
+		const transactionAuditEvent = TRANSACTION_STATE_MACHINE.validateAndCreateAuditEvent(transaction.status, TRANSACTION_STATUS.CANCELLED, transaction._id.toString(), {
+			changedBy: "system",
+			reason: `Transaction cancelled due to escrow hold cancellation`,
+			metadata: { cancelReason: reason }
+		});
+		transaction.status = TRANSACTION_STATUS.CANCELLED;
+		Object.assign(transaction, appendAuditEvent(transaction, holdAuditEvent));
+		Object.assign(transaction, appendAuditEvent(transaction, transactionAuditEvent));
+		if ("markModified" in transaction) transaction.markModified("hold");
+		await transaction.save();
+		this.events.emit("escrow.cancelled", {
+			transaction,
+			reason
+		});
+		return transaction;
+	}
+	/**
+	* Split payment to multiple recipients
+	* Deducts splits from held amount and releases remainder to organization
+	*
+	* @param transactionId - Transaction to split
+	* @param splitRules - Split configuration
+	* @returns { transaction, splitTransactions, organizationTransaction }
+	*/
+	async split(transactionId, splitRules = []) {
+		const TransactionModel = this.models.Transaction;
+		const transaction = await TransactionModel.findById(transactionId);
+		if (!transaction) throw new TransactionNotFoundError(transactionId);
+		if (!transaction.hold || transaction.hold.status !== HOLD_STATUS.HELD) throw new InvalidStateTransitionError("escrow_hold", transaction._id.toString(), transaction.hold?.status ?? "none", HOLD_STATUS.HELD);
+		if (!splitRules || splitRules.length === 0) throw new ValidationError("splitRules cannot be empty", { transactionId });
+		const splits = calculateSplits(transaction.amount, splitRules, transaction.commission?.gatewayFeeRate ?? 0);
+		transaction.splits = splits;
+		await transaction.save();
+		const splitTransactions = [];
+		const totalTax = transaction.tax ?? 0;
+		const totalBaseAmount = transaction.amount;
+		let allocatedTaxAmount = 0;
+		const splitTaxAmounts = splits.map((split) => {
+			if (!totalTax || totalBaseAmount <= 0) return 0;
+			const ratio = split.grossAmount / totalBaseAmount;
+			const taxAmount = Math.round(totalTax * ratio);
+			allocatedTaxAmount += taxAmount;
+			return taxAmount;
+		});
+		for (const [index, split] of splits.entries()) {
+			const splitTaxAmount = totalTax > 0 ? splitTaxAmounts[index] ?? 0 : 0;
+			const splitNetAmount = split.grossAmount - split.gatewayFeeAmount - splitTaxAmount;
+			const splitTransaction = await TransactionModel.create({
+				organizationId: transaction.organizationId,
+				customerId: split.recipientId,
+				type: split.type,
+				flow: "outflow",
+				tags: ["split", "commission"],
+				amount: split.grossAmount,
+				currency: transaction.currency,
+				fee: split.gatewayFeeAmount,
+				tax: splitTaxAmount,
+				net: splitNetAmount,
+				...transaction.taxDetails && splitTaxAmount > 0 && { taxDetails: transaction.taxDetails },
+				method: transaction.method,
+				status: "completed",
+				gateway: transaction.gateway,
+				sourceId: transaction._id,
+				sourceModel: "Transaction",
+				relatedTransactionId: transaction._id,
+				metadata: {
+					isSplit: true,
+					splitType: split.type,
+					recipientType: split.recipientType,
+					originalTransactionId: transaction._id.toString(),
+					splitGrossAmount: split.grossAmount,
+					splitNetAmount: split.netAmount,
+					gatewayFeeAmount: split.gatewayFeeAmount
+				},
+				idempotencyKey: `split_${transaction._id}_${split.recipientId}_${Date.now()}`
+			});
+			split.payoutTransactionId = splitTransaction._id.toString();
+			split.status = SPLIT_STATUS.PAID;
+			split.paidDate = /* @__PURE__ */ new Date();
+			splitTransactions.push(splitTransaction);
+		}
+		await transaction.save();
+		const organizationPayout = calculateOrganizationPayout(transaction.amount, splits);
+		const organizationTaxAmount = totalTax > 0 ? Math.max(0, totalTax - allocatedTaxAmount) : 0;
+		const organizationPayoutTotal = totalTax > 0 ? organizationPayout + organizationTaxAmount : organizationPayout;
+		const organizationTransaction = await this.release(transactionId, {
+			amount: organizationPayoutTotal,
+			recipientId: transaction.organizationId?.toString() ?? "",
+			recipientType: "organization",
+			reason: RELEASE_REASON.PAYMENT_VERIFIED,
+			createTransaction: true,
+			metadata: {
+				afterSplits: true,
+				totalSplits: splits.length,
+				totalSplitAmount: transaction.amount - organizationPayout
+			}
+		});
+		this.events.emit("escrow.split", {
+			transaction,
+			splits,
+			splitTransactions,
+			organizationTransaction: organizationTransaction.releaseTransaction,
+			organizationPayout
+		});
+		return {
+			transaction,
+			splits,
+			splitTransactions,
+			organizationTransaction: organizationTransaction.releaseTransaction,
+			organizationPayout
+		};
+	}
+	/**
+	* Get escrow status
+	*
+	* @param transactionId - Transaction ID
+	* @returns Escrow status
+	*/
+	async getStatus(transactionId) {
+		const transaction = await this.models.Transaction.findById(transactionId);
+		if (!transaction) throw new TransactionNotFoundError(transactionId);
+		return {
+			transaction,
+			hold: transaction.hold ?? null,
+			splits: transaction.splits ?? [],
+			hasHold: !!transaction.hold,
+			hasSplits: transaction.splits ? transaction.splits.length > 0 : false
+		};
+	}
+};
+
+//#endregion
+//#region src/application/services/settlement.service.ts
+/**
+* Settlement Service
+*
+* Handles payout tracking after splits are released from escrow:
+*
+* Flow:
+* 1. Transaction has splits → 2. Escrow released → 3. Create settlements → 4. Process payouts → 5. Mark complete
+*
+* @example
+* ```typescript
+* // Auto-create settlements from transaction splits
+* await revenue.settlement.createFromSplits(transactionId);
+*
+* // Schedule a manual payout
+* await revenue.settlement.schedule({
+*   recipientId: vendorId,
+*   amount: 8500,
+*   payoutMethod: 'bank_transfer',
+* });
+*
+* // Process pending payouts
+* const result = await revenue.settlement.processPending({ limit: 100 });
+*
+* // Mark as completed after bank confirms
+* await revenue.settlement.complete(settlementId, { transferReference: 'TRF123' });
+* ```
+*/
+/**
+* Settlement Service
+* Uses DI container for all dependencies
+*
+* Architecture:
+* - PluginManager: Wraps operations with lifecycle hooks (before/after)
+* - EventBus: Fire-and-forget notifications for completed operations
+*/
+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");
+		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 transaction = await this.models.Transaction.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 settlement = await this.models.Settlement.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 settlement = await this.models.Settlement.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 settlement = await this.models.Settlement.findById(settlementId);
+		if (!settlement) throw new ValidationError("Settlement not found", { settlementId });
+		const { code, retry = false } = options;
+		if (retry) {
+			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() + 3600 * 1e3)
+				}
+			});
+			settlement.status = SETTLEMENT_STATUS.PENDING;
+			settlement.retryCount = (settlement.retryCount || 0) + 1;
+			settlement.scheduledAt = new Date(Date.now() + 3600 * 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
+		});
+		this.logger.warn("Settlement failed", {
+			settlementId: settlement._id,
+			reason,
+			retry
+		});
+		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;
+		}
+		return await SettlementModel.find(query).limit(limit).skip(skip).sort(sort);
+	}
+	/**
+	* 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 settlement = await this.models.Settlement.findById(settlementId);
+		if (!settlement) throw new ValidationError("Settlement not found", { settlementId });
+		return settlement;
+	}
+};
+
+//#endregion
+export { MonetizationService as a, getAuditTrail as c, SETTLEMENT_STATE_MACHINE as d, SPLIT_STATE_MACHINE as f, resolveConfig as g, StateMachine as h, PaymentService as i, getLastStateChange as l, TRANSACTION_STATE_MACHINE as m, EscrowService as n, appendAuditEvent as o, SUBSCRIPTION_STATE_MACHINE as p, TransactionService as r, filterAuditTrail as s, SettlementService as t, HOLD_STATE_MACHINE as u };