@classytic/revenue 2.0.1 → 2.1.3

package/dist/settlement.repository-BAdc9qGl.mjs

@@ -0,0 +1,1444 @@
+import { _ as TRANSACTION_STATUS, a as TRANSACTION_KIND, s as initialStatusFor } from "./bank-feed.enums-kYTLTTbe.mjs";
+import { n as createEvent, t as REVENUE_EVENTS } from "./event-constants-Dn1TKahe.mjs";
+import { g as SETTLEMENT_STATUS, r as SUBSCRIPTION_STATUS, w as HOLD_STATUS } from "./subscription.enums-95othr0i.mjs";
+import { f as SettlementNotFoundError, g as WrongTransactionKindError, h as ValidationError, m as TransactionNotFoundError, n as BankFeedImportError, p as SubscriptionNotFoundError } from "./errors-LYYg9wcs.mjs";
+import { SETTLEMENT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, TRANSACTION_STATE_MACHINE, smFor } from "./core/state-machines.mjs";
+import { a as reverseTax, c as reverseCommission, n as calculateSplits, s as calculateCommission, t as calculateOrganizationPayout } from "./splits-CNfQj92L.mjs";
+import { Repository, repoOptionsFromCtx, withTransaction } from "@classytic/mongokit";
+
+//#region src/repositories/base.repository.ts
+/**
+* RevenueRepositoryBase — shared scaffolding for every revenue repo.
+*
+* Eliminates the three places ctx-threading and event-dispatch were
+* hand-rolled (transaction / subscription / settlement) and previously
+* drifted: subscription + settlement repos forgot to forward
+* `ctx.organizationId` into their inner `getById` / `update` calls,
+* which surfaced as `Missing 'organizationId' in context for 'getById'`
+* the moment a host enabled `multiTenantPlugin` (the canonical 2026-Q2
+* bug — fixed in 2.1.1).
+*
+* Two responsibilities:
+*
+*   1. **Thread request context into mongokit options.** Every domain
+*      verb that touches the DB (read or write) ends with a mongokit
+*      method whose options bag is what `multiTenantPlugin`,
+*      `softDeletePlugin`, the audit plugins, and `withTransaction`
+*      read from. {@link optsFromCtx} centralises that translation
+*      using mongokit's typed extractor — adding a new canonical field
+*      to `RevenueContext` is now a single line, not three.
+*
+*   2. **Dispatch domain events.** Outbox-save (session-bound when the
+*      caller threads a Mongoose `ClientSession`) followed by
+*      transport-publish, with isolated try/catch so a transport
+*      failure never aborts the business write. PACKAGE_RULES P8 / §5.5.
+*
+* Subclasses inject their domain-specific deps via {@link inject}; this
+* base only requires the cross-cutting trio (events / outbox / logger)
+* which every revenue repo has.
+*
+* @typeParam TDoc - The Mongoose document type the subclass operates on.
+* @typeParam TDeps - The full deps shape (must extend `BaseRevenueRepoDeps`).
+*
+* @example
+* ```ts
+* export class SubscriptionRepository extends RevenueRepositoryBase<
+*   SubscriptionDocument,
+*   SubscriptionRepoDeps
+* > {
+*   async activate(id: string, ctx: RevenueContext = {}) {
+*     const sub = await this.getById(id, this.optsFromCtx(ctx));
+*     // ...
+*     await this.dispatch(createEvent(...), ctx);
+*     return updated;
+*   }
+* }
+* ```
+*/
+/**
+* Abstract base for `TransactionRepository`, `SubscriptionRepository`,
+* `SettlementRepository`.
+*
+* Concrete subclasses MUST:
+* - declare a `Deps` interface that extends {@link BaseRevenueRepoDeps}
+* - call `super(model, plugins)` from the constructor
+* - call `inject(deps)` once during engine boot
+*
+* Subclasses SHOULD use {@link optsFromCtx} for every mongokit call
+* that takes an options bag, and {@link dispatch} for every event
+* publish.
+*/
+var RevenueRepositoryBase = class extends Repository {
+	/**
+	* Subclass-specific deps. `!` because the engine wires this once via
+	* `inject(deps)` immediately after construction; calling any domain
+	* verb before injection is a programming error and the runtime
+	* will fail-loud with `Cannot read properties of undefined`.
+	*/
+	deps;
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	/**
+	* Wire engine-managed deps. Called exactly once per repository
+	* instance during {@link createRevenue} bootstrap. Subclasses with
+	* extra steps (caching, prebuilding state machine maps) override and
+	* call `super.inject(deps)`.
+	*/
+	inject(deps) {
+		this.deps = deps;
+	}
+	/**
+	* Translate {@link RevenueContext} into a mongokit options bag.
+	*
+	* Forwards every canonical field mongokit's bundled plugins read —
+	* `organizationId` (multiTenant), `userId` / `user` (audit),
+	* `session` (transactions), `requestId` (observability) — plus
+	* the revenue-specific `_bypassTenant` flag for platform-admin
+	* cross-org reads.
+	*
+	* Pass `extra` for caller-specific options like `throwOnNotFound`,
+	* `lean`, `populate`, `select` — the spread is `extra`-first so
+	* ctx wins on a key collision (intentional: callers shouldn't
+	* be smuggling tenant fields through `extra`).
+	*
+	* @param ctx - The request-scoped revenue context.
+	* @param extra - Additional mongokit options merged in.
+	*/
+	optsFromCtx(ctx = {}, extra = {}) {
+		const out = {
+			...extra,
+			...repoOptionsFromCtx(ctx)
+		};
+		if (ctx._bypassTenant === true) out._bypassTenant = true;
+		return out;
+	}
+	/**
+	* Persist an event to the host outbox, then publish to the in-process
+	* transport. The two sides have asymmetric failure handling — see
+	* PACKAGE_RULES §P8.
+	*
+	* When `ctx.session` is set, the outbox `save` runs inside the same
+	* Mongoose transaction (true P8 session-bound write); when absent, the
+	* outbox row lands after commit — still durable via the host's relay,
+	* with only a small at-most-once window on process crash.
+	*
+	*   1. **`outbox.save` failures PROPAGATE.** If we can't durably record
+	*      the event, the caller's transaction MUST roll back so the
+	*      business doc and the event row land atomically (or neither
+	*      lands). Swallowing a save failure breaks the transactional-
+	*      outbox correctness argument — the parent doc would land while
+	*      the event vanishes.
+	*
+	*   2. **`events.publish` failures are SWALLOWED.** The host's outbox
+	*      relay re-publishes from the durable row on its next poll. Even
+	*      without an outbox, in-process subscribers shouldn't be able to
+	*      break the business operation — they're best-effort consumers.
+	*
+	* @param event - Pre-built domain event (use `createEvent(REVENUE_EVENTS.X, payload, ctx, meta)`).
+	* @param ctx - The same context that produced the business write.
+	*/
+	async dispatch(event, ctx = {}) {
+		if (this.deps.outbox) try {
+			await this.deps.outbox.save(event, ctx.session !== void 0 ? { session: ctx.session } : {});
+		} catch (err) {
+			this.deps.logger?.error("[revenue] outbox.save failed for", event.type, err);
+			throw err;
+		}
+		try {
+			await this.deps.events.publish(event);
+		} catch (err) {
+			this.deps.logger?.error("[revenue] events.publish failed for", event.type, err);
+		}
+	}
+};
+
+//#endregion
+//#region src/repositories/transaction.repository.ts
+var TransactionRepository = class extends RevenueRepositoryBase {
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	/**
+	* Save an event to the host-owned outbox, session-bound when available.
+	*
+	* Called INSIDE a `withTransaction` body. The outbox row commits
+	* atomically with the business write (P8 true session-bound write) —
+	* if outbox.save fails, this method re-throws so `withTransaction`
+	* rolls the parent write back. Without propagation, the parent doc
+	* would commit while the event row vanishes, defeating the whole
+	* transactional-outbox correctness argument.
+	*
+	* Logging happens before the re-throw so the failure surfaces in
+	* observability without losing the original stack trace.
+	*/
+	async saveToOutbox(event, session) {
+		if (!this.deps.outbox) return;
+		try {
+			await this.deps.outbox.save(event, session !== void 0 ? { session } : {});
+		} catch (err) {
+			this.deps.logger?.error("[revenue] outbox.save failed for", event.type, err);
+			throw err;
+		}
+	}
+	/**
+	* Publish an event to the in-process `EventTransport` after commit.
+	* Transport failure is logged and swallowed — the host relay re-delivers
+	* from the durable outbox row on the next poll, so in-process
+	* subscribers missing an event is recoverable. Best-effort by design.
+	*/
+	async publishToTransport(event) {
+		try {
+			await this.deps.events.publish(event);
+		} catch (err) {
+			this.deps.logger?.error("[revenue] events.publish failed for", event.type, err);
+		}
+	}
+	/** Creates transaction + calls provider. Returns the created transaction doc. */
+	async createPaymentIntent(params, ctx = {}) {
+		const currency = params.currency ?? this.deps.defaultCurrency;
+		const provider = this.deps.providers.get(params.gateway);
+		if (params.idempotencyKey) {
+			const existing = await this.getByQuery({ idempotencyKey: params.idempotencyKey }, this.optsFromCtx(ctx, { throwOnNotFound: false }));
+			if (existing) return existing;
+		}
+		const commissionRate = this.deps.commission?.defaultRate ?? 0;
+		const gatewayFeeRate = this.deps.commission?.gatewayFeeRate ?? 0;
+		const commission = calculateCommission(params.amount, commissionRate, gatewayFeeRate);
+		let gatewayData = { type: params.gateway };
+		if (params.amount > 0) {
+			const intent = await provider.createIntent({
+				amount: {
+					amount: params.amount,
+					currency
+				},
+				metadata: params.metadata,
+				...params.paymentData
+			});
+			gatewayData = {
+				type: params.gateway,
+				sessionId: intent.sessionId,
+				paymentIntentId: intent.paymentIntentId ?? intent.id,
+				metadata: {
+					clientSecret: intent.clientSecret,
+					paymentUrl: intent.paymentUrl,
+					instructions: intent.instructions
+				}
+			};
+		}
+		const transaction = await this.create({
+			organizationId: ctx.organizationId,
+			customerId: params.data?.customerId ?? null,
+			type: params.monetizationType === "subscription" ? "subscription" : "purchase",
+			flow: "inflow",
+			tags: params.monetizationType ? [params.monetizationType] : [],
+			amount: params.amount,
+			currency,
+			fee: commission?.gatewayFeeAmount ?? 0,
+			tax: 0,
+			net: params.amount - (commission?.gatewayFeeAmount ?? 0),
+			method: params.gateway,
+			status: params.amount === 0 ? TRANSACTION_STATUS.VERIFIED : TRANSACTION_STATUS.PENDING,
+			gateway: gatewayData,
+			commission: commission ?? void 0,
+			sourceId: params.data?.sourceId,
+			sourceModel: params.data?.sourceModel,
+			idempotencyKey: params.idempotencyKey,
+			metadata: params.metadata
+		}, this.optsFromCtx(ctx));
+		await this.dispatch(createEvent(REVENUE_EVENTS.MONETIZATION_CREATED, {
+			monetizationType: params.monetizationType,
+			transaction
+		}, ctx, {
+			resource: "transaction",
+			resourceId: transaction.publicId
+		}), ctx);
+		return transaction;
+	}
+	/** Verifies payment via provider, updates status. Returns the updated doc. */
+	async verify(paymentIntentId, options = {}, ctx = {}) {
+		const readOpts = this.optsFromCtx(ctx, { throwOnNotFound: false });
+		let transaction = await this.getByQuery({ "gateway.sessionId": paymentIntentId }, readOpts);
+		if (!transaction) transaction = await this.getByQuery({ "gateway.paymentIntentId": paymentIntentId }, readOpts);
+		if (!transaction) transaction = await this.getById(paymentIntentId, readOpts);
+		if (!transaction) throw new TransactionNotFoundError(paymentIntentId);
+		const provider = this.deps.providers.get(transaction.method);
+		const intentId = transaction.gateway?.paymentIntentId ?? transaction.gateway?.sessionId ?? paymentIntentId;
+		const paymentResult = await provider.verifyPayment(intentId);
+		let newStatus;
+		if (paymentResult.status === "succeeded") newStatus = TRANSACTION_STATUS.VERIFIED;
+		else if (paymentResult.status === "failed") newStatus = TRANSACTION_STATUS.FAILED;
+		else if (paymentResult.status === "requires_action") newStatus = TRANSACTION_STATUS.REQUIRES_ACTION;
+		else newStatus = TRANSACTION_STATUS.PROCESSING;
+		TRANSACTION_STATE_MACHINE.validate(transaction.status, newStatus, String(transaction._id));
+		const updates = { status: newStatus };
+		if (newStatus === TRANSACTION_STATUS.VERIFIED) {
+			updates.verifiedAt = /* @__PURE__ */ new Date();
+			updates.verifiedBy = options.verifiedBy;
+		} else if (newStatus === TRANSACTION_STATUS.FAILED) {
+			updates.failedAt = /* @__PURE__ */ new Date();
+			updates.failureReason = "Payment verification failed";
+		}
+		const updated = await this.update(transaction._id, updates, this.optsFromCtx(ctx));
+		if (newStatus === TRANSACTION_STATUS.VERIFIED) {
+			await this.deps.bridges.ledger?.onPaymentVerified?.(updated, ctx);
+			await this.deps.bridges.notification?.onPaymentVerified?.(updated, ctx);
+		}
+		const eventName = newStatus === TRANSACTION_STATUS.VERIFIED ? REVENUE_EVENTS.PAYMENT_VERIFIED : newStatus === TRANSACTION_STATUS.FAILED ? REVENUE_EVENTS.PAYMENT_FAILED : newStatus === TRANSACTION_STATUS.REQUIRES_ACTION ? REVENUE_EVENTS.PAYMENT_REQUIRES_ACTION : REVENUE_EVENTS.PAYMENT_PROCESSING;
+		await this.dispatch(createEvent(eventName, {
+			transaction: updated,
+			paymentResult,
+			verifiedBy: options.verifiedBy
+		}, ctx, {
+			resource: "transaction",
+			resourceId: updated?.publicId
+		}), ctx);
+		return updated;
+	}
+	/**
+	* Creates refund transaction, updates original. Returns the refund transaction doc.
+	*
+	* The provider call happens OUTSIDE the transaction — it's a non-idempotent external
+	* side effect we can't roll back. The two Mongo writes (create refund + update original)
+	* run inside `withTransaction` so they commit atomically or both abort. Bridges and
+	* event emission run AFTER commit because they're independent side effects; rolling
+	* them back would not undo external state anyway.
+	*
+	* Powered by mongokit 3.6's module-level `withTransaction` helper. Automatically
+	* retries on `TransientTransactionError` / `UnknownTransactionCommitResult`.
+	*/
+	async refund(transactionId, amount, options = {}, ctx = {}) {
+		const transaction = await this.getById(transactionId, this.optsFromCtx(ctx));
+		if (!transaction) throw new TransactionNotFoundError(transactionId);
+		const refundAmount = amount ?? transaction.amount;
+		const existingRefunded = transaction.refundedAmount ?? 0;
+		const isPartialRefund = existingRefunded + refundAmount < transaction.amount;
+		const newStatus = isPartialRefund ? TRANSACTION_STATUS.PARTIALLY_REFUNDED : TRANSACTION_STATUS.REFUNDED;
+		TRANSACTION_STATE_MACHINE.validate(transaction.status, newStatus, transactionId);
+		const provider = this.deps.providers.get(transaction.method);
+		const paymentId = transaction.gateway?.paymentIntentId ?? transaction.gateway?.sessionId ?? transactionId;
+		await provider.refund(paymentId, refundAmount, { reason: options.reason });
+		const reversedCommission = reverseCommission(transaction.commission, transaction.amount, refundAmount);
+		const reversedTax = transaction.tax ? reverseTax({
+			isApplicable: true,
+			rate: 0,
+			baseAmount: transaction.amount,
+			taxAmount: transaction.tax,
+			totalAmount: transaction.amount + transaction.tax,
+			pricesIncludeTax: false
+		}, transaction.amount, refundAmount) : void 0;
+		const pendingEvents = [];
+		const refundTransaction = await withTransaction(this.Model.db, async (session) => {
+			const writeOpts = this.optsFromCtx(ctx, { session });
+			const refundTxn = await this.create({
+				organizationId: transaction.organizationId,
+				customerId: transaction.customerId,
+				type: "refund",
+				flow: "outflow",
+				tags: ["refund"],
+				amount: refundAmount,
+				currency: transaction.currency,
+				fee: reversedCommission?.gatewayFeeAmount ?? 0,
+				tax: reversedTax?.taxAmount ?? 0,
+				net: refundAmount - (reversedCommission?.gatewayFeeAmount ?? 0) - (reversedTax?.taxAmount ?? 0),
+				method: transaction.method,
+				status: TRANSACTION_STATUS.VERIFIED,
+				gateway: transaction.gateway,
+				commission: reversedCommission ?? void 0,
+				relatedTransactionId: transaction._id,
+				sourceId: transaction.sourceId,
+				sourceModel: transaction.sourceModel,
+				verifiedAt: /* @__PURE__ */ new Date(),
+				metadata: { reason: options.reason }
+			}, writeOpts);
+			await this.update(transactionId, {
+				status: newStatus,
+				refundedAmount: existingRefunded + refundAmount,
+				refundedAt: /* @__PURE__ */ new Date()
+			}, writeOpts);
+			const event = createEvent(REVENUE_EVENTS.PAYMENT_REFUNDED, {
+				transaction,
+				refundTransaction: refundTxn,
+				refundAmount,
+				reason: options.reason,
+				isPartialRefund
+			}, ctx, {
+				resource: "transaction",
+				resourceId: transaction.publicId
+			});
+			await this.saveToOutbox(event, session);
+			pendingEvents.push(event);
+			return refundTxn;
+		});
+		await this.deps.bridges.ledger?.onRefundProcessed?.(transaction, refundTransaction, ctx);
+		await this.deps.bridges.notification?.onRefundProcessed?.(refundTransaction, ctx);
+		for (const ev of pendingEvents) await this.publishToTransport(ev);
+		return refundTransaction;
+	}
+	/** Handles provider webhook. Returns the updated transaction doc (or null if not found). */
+	async handleWebhook(providerName, payload, headers, ctx = {}) {
+		const webhookEvent = await this.deps.providers.get(providerName).handleWebhook(payload, headers);
+		const readOpts = this.optsFromCtx(ctx, { throwOnNotFound: false });
+		const sessionId = webhookEvent.data?.sessionId;
+		const intentId = webhookEvent.data?.paymentIntentId;
+		let transaction = sessionId ? await this.getByQuery({ "gateway.sessionId": sessionId }, readOpts) : null;
+		if (!transaction && intentId) transaction = await this.getByQuery({ "gateway.paymentIntentId": intentId }, readOpts);
+		if (!transaction) return null;
+		if (transaction.webhook?.eventId === webhookEvent.id) return transaction;
+		const nextWebhook = {
+			eventId: webhookEvent.id,
+			eventType: webhookEvent.type,
+			receivedAt: /* @__PURE__ */ new Date(),
+			processedAt: /* @__PURE__ */ new Date(),
+			data: webhookEvent.data
+		};
+		const updated = await this.findOneAndUpdate({
+			_id: transaction._id,
+			"webhook.eventId": { $ne: webhookEvent.id }
+		}, { $set: { webhook: nextWebhook } }, { returnDocument: "after" });
+		if (!updated) return await this.getByQuery({ _id: transaction._id }, readOpts) ?? transaction;
+		await this.dispatch(createEvent(REVENUE_EVENTS.WEBHOOK_PROCESSED, {
+			webhookType: webhookEvent.type,
+			provider: providerName,
+			event: webhookEvent,
+			transaction: updated
+		}, ctx, {
+			resource: "transaction",
+			resourceId: updated?.publicId
+		}), ctx);
+		return updated;
+	}
+	/** Places hold on verified transaction. Returns the updated doc. */
+	async hold(transactionId, options = {}, ctx = {}) {
+		const transaction = await this.getById(transactionId, this.optsFromCtx(ctx));
+		if (!transaction) throw new TransactionNotFoundError(transactionId);
+		if (transaction.status !== TRANSACTION_STATUS.VERIFIED) throw new ValidationError("Can only hold verified transactions", { status: transaction.status });
+		const holdAmount = options.amount ?? transaction.amount;
+		const updated = await this.update(transactionId, { hold: {
+			status: HOLD_STATUS.HELD,
+			heldAmount: holdAmount,
+			releasedAmount: 0,
+			reason: options.reason ?? "manual_hold",
+			heldAt: /* @__PURE__ */ new Date(),
+			holdUntil: options.holdUntil,
+			releases: [],
+			metadata: options.metadata
+		} }, this.optsFromCtx(ctx));
+		await this.dispatch(createEvent(REVENUE_EVENTS.ESCROW_HELD, {
+			transaction: updated,
+			heldAmount: holdAmount,
+			reason: options.reason
+		}, ctx, {
+			resource: "transaction",
+			resourceId: updated?.publicId
+		}), ctx);
+		return updated;
+	}
+	/**
+	* Releases held funds. Returns the updated transaction doc.
+	*
+	* The hold update and the escrow_release transaction create happen inside
+	* `withTransaction` — a mid-flow crash can't leave the hold marked released
+	* without the corresponding outflow record (or vice versa).
+	*/
+	async release(transactionId, options, ctx = {}) {
+		const transaction = await this.getById(transactionId, this.optsFromCtx(ctx));
+		if (!transaction) throw new TransactionNotFoundError(transactionId);
+		if (!transaction.hold || transaction.hold.status !== HOLD_STATUS.HELD && transaction.hold.status !== HOLD_STATUS.PARTIALLY_RELEASED) throw new ValidationError("Transaction does not have an active hold");
+		const releaseAmount = options.amount ?? transaction.hold.heldAmount - transaction.hold.releasedAmount;
+		const newReleasedAmount = transaction.hold.releasedAmount + releaseAmount;
+		const isFullRelease = newReleasedAmount >= transaction.hold.heldAmount;
+		const release = {
+			amount: releaseAmount,
+			recipientId: options.recipientId,
+			recipientType: options.recipientType,
+			releasedAt: /* @__PURE__ */ new Date(),
+			releasedBy: options.releasedBy,
+			reason: options.reason,
+			metadata: options.metadata
+		};
+		const pendingEvents = [];
+		const updated = await withTransaction(this.Model.db, async (session) => {
+			const writeOpts = this.optsFromCtx(ctx, { session });
+			const result = await this.update(transactionId, { hold: {
+				...transaction.hold,
+				status: isFullRelease ? HOLD_STATUS.RELEASED : HOLD_STATUS.PARTIALLY_RELEASED,
+				releasedAmount: newReleasedAmount,
+				releasedAt: isFullRelease ? /* @__PURE__ */ new Date() : transaction.hold.releasedAt,
+				releases: [...transaction.hold.releases ?? [], release]
+			} }, writeOpts);
+			if (options.createTransaction !== false) await this.create({
+				organizationId: transaction.organizationId,
+				customerId: options.recipientId,
+				type: "escrow_release",
+				flow: "outflow",
+				tags: ["escrow", "release"],
+				amount: releaseAmount,
+				currency: transaction.currency,
+				fee: 0,
+				tax: 0,
+				net: releaseAmount,
+				method: transaction.method,
+				status: TRANSACTION_STATUS.VERIFIED,
+				relatedTransactionId: transaction._id,
+				sourceId: transaction.sourceId,
+				sourceModel: transaction.sourceModel,
+				verifiedAt: /* @__PURE__ */ new Date(),
+				metadata: options.metadata
+			}, writeOpts);
+			const event = createEvent(REVENUE_EVENTS.ESCROW_RELEASED, {
+				transaction: result,
+				releaseAmount,
+				recipientId: options.recipientId,
+				recipientType: options.recipientType,
+				isFullRelease,
+				isPartialRelease: !isFullRelease
+			}, ctx, {
+				resource: "transaction",
+				resourceId: result?.publicId
+			});
+			await this.saveToOutbox(event, session);
+			pendingEvents.push(event);
+			return result;
+		});
+		for (const ev of pendingEvents) await this.publishToTransport(ev);
+		return updated;
+	}
+	/**
+	* Splits payment among recipients. Returns the updated transaction doc.
+	*
+	* N + 2 writes (one create per recipient, one update on the parent, one
+	* platform_revenue create) all commit atomically. Partial splits are the
+	* worst class of bug in a payments system — this is exactly what
+	* `withTransaction` is for.
+	*/
+	async split(transactionId, rules, ctx = {}) {
+		const transaction = await this.getById(transactionId, this.optsFromCtx(ctx));
+		if (!transaction) throw new TransactionNotFoundError(transactionId);
+		const gatewayFeeRate = this.deps.commission?.gatewayFeeRate ?? 0;
+		const splits = calculateSplits(transaction.amount, rules, gatewayFeeRate);
+		const orgPayout = calculateOrganizationPayout(transaction.amount, splits);
+		const pendingEvents = [];
+		const updated = await withTransaction(this.Model.db, async (session) => {
+			const writeOpts = this.optsFromCtx(ctx, { session });
+			for (const s of splits) await this.create({
+				organizationId: transaction.organizationId,
+				customerId: s.recipientId,
+				type: "commission",
+				flow: "outflow",
+				tags: ["split", s.type],
+				amount: s.grossAmount,
+				currency: transaction.currency,
+				fee: s.gatewayFeeAmount,
+				tax: 0,
+				net: s.netAmount,
+				method: transaction.method,
+				status: TRANSACTION_STATUS.VERIFIED,
+				relatedTransactionId: transaction._id,
+				sourceId: transaction.sourceId,
+				sourceModel: transaction.sourceModel,
+				verifiedAt: /* @__PURE__ */ new Date()
+			}, writeOpts);
+			const result = await this.update(transactionId, {
+				splits,
+				metadata: {
+					...transaction.metadata,
+					organizationPayout: orgPayout
+				}
+			}, writeOpts);
+			await this.create({
+				organizationId: transaction.organizationId,
+				type: "platform_revenue",
+				flow: "inflow",
+				tags: ["split", "platform"],
+				amount: orgPayout,
+				currency: transaction.currency,
+				fee: 0,
+				tax: 0,
+				net: orgPayout,
+				method: transaction.method,
+				status: TRANSACTION_STATUS.VERIFIED,
+				relatedTransactionId: transaction._id,
+				verifiedAt: /* @__PURE__ */ new Date()
+			}, writeOpts);
+			const event = createEvent(REVENUE_EVENTS.ESCROW_SPLIT, {
+				transaction: result,
+				splits,
+				organizationPayout: orgPayout
+			}, ctx, {
+				resource: "transaction",
+				resourceId: transaction.publicId
+			});
+			await this.saveToOutbox(event, session);
+			pendingEvents.push(event);
+			return result;
+		});
+		for (const ev of pendingEvents) await this.publishToTransport(ev);
+		return updated;
+	}
+	/**
+	* Idempotent bulk import of bank-feed rows.
+	*
+	* Each row is upserted by `(orgId, bankAccountId, externalId)` — the
+	* partial unique index declared in `create-models.ts`. Re-running the
+	* same Plaid sync, OFX upload, or QBO CDC drain produces zero new
+	* inserts on the second call (modified counts may rise as
+	* descriptions/categories evolve upstream).
+	*
+	* Signed bank `amount` is normalized into the (`amount` >= 0, `flow`)
+	* shape revenue uses internally so downstream queries (`flow:
+	* 'inflow'`) work uniformly across kinds.
+	*
+	* Emits one `revenue:transaction.imported` event per **inserted** row
+	* (not per row in `rows` — re-imports do not re-fire). Hosts wanting
+	* batch-level signal subscribe to the per-doc events and aggregate.
+	*
+	* Per-row failures (validation, hash collisions on a non-unique
+	* `externalId`) collect into `errors[]` instead of aborting the whole
+	* batch — the typical Plaid drain pulls thousands of rows; one bad
+	* row should not block the rest.
+	*
+	* @param rows  Canonical bank transactions, structurally compatible
+	*              with `@classytic/fin-io` parsers' output.
+	* @param opts  `bankAccountId` (required, polymorphic ID) and
+	*              `source` (provenance — `'plaid'`, `'ofx'`, …).
+	*/
+	async import(rows, opts, ctx = {}) {
+		const startedAt = Date.now();
+		if (!Array.isArray(rows) || rows.length === 0) return {
+			inserted: 0,
+			updated: 0,
+			skipped: 0,
+			errors: [],
+			durationMs: 0
+		};
+		const repo = this;
+		if (!repo.bulkWrite) throw new BankFeedImportError("TransactionRepository requires `batchOperationsPlugin` for `import()`. Pass it via `createRevenue({ repositoryPlugins: { transaction: [batchOperationsPlugin()] } })` — or rely on the engine default which wires it automatically.");
+		const errors = [];
+		const tenantOption = ctx.organizationId !== void 0 ? { organizationId: ctx.organizationId } : {};
+		const ops = [];
+		for (const row of rows) {
+			if (!row.externalId || typeof row.externalId !== "string") {
+				errors.push({
+					externalId: String(row.externalId),
+					reason: "missing_external_id",
+					row
+				});
+				continue;
+			}
+			const signed = row.amount.amount;
+			if (!Number.isFinite(signed) || !Number.isInteger(signed)) {
+				errors.push({
+					externalId: row.externalId,
+					reason: "invalid_amount",
+					row
+				});
+				continue;
+			}
+			const isInflow = signed >= 0;
+			const absoluteAmount = Math.abs(signed);
+			const filter = {
+				bankAccountId: opts.bankAccountId,
+				externalId: row.externalId
+			};
+			if (ctx.organizationId !== void 0) filter.organizationId = ctx.organizationId;
+			const set = {
+				amount: absoluteAmount,
+				currency: row.amount.currency,
+				flow: isInflow ? "inflow" : "outflow",
+				postedDate: row.postedDate,
+				description: row.description,
+				method: opts.method ?? opts.source
+			};
+			if (row.valueDate !== void 0) set.valueDate = row.valueDate;
+			if (row.counterparty !== void 0) set.counterparty = row.counterparty;
+			if (row.reference !== void 0) set.reference = row.reference;
+			if (row.category !== void 0) set.vendorCategory = row.category;
+			if (row.balanceAfter !== void 0) set.balanceAfter = row.balanceAfter.amount;
+			const setOnInsert = {
+				kind: TRANSACTION_KIND.BANK_FEED,
+				status: initialStatusFor(TRANSACTION_KIND.BANK_FEED),
+				bankAccountId: opts.bankAccountId,
+				externalId: row.externalId,
+				source: opts.source,
+				type: "bank_feed",
+				tags: ["bank_feed", opts.source],
+				fee: 0,
+				tax: 0,
+				net: absoluteAmount,
+				deletedAt: null
+			};
+			if (ctx.organizationId !== void 0) setOnInsert.organizationId = ctx.organizationId;
+			ops.push({ updateOne: {
+				filter,
+				update: {
+					$set: set,
+					$setOnInsert: setOnInsert
+				},
+				upsert: true
+			} });
+		}
+		if (ops.length === 0) return {
+			inserted: 0,
+			updated: 0,
+			skipped: rows.length,
+			errors,
+			durationMs: Date.now() - startedAt
+		};
+		const sessionOption = ctx.session !== void 0 ? { session: ctx.session } : {};
+		const result = await repo.bulkWrite(ops, {
+			ordered: false,
+			...sessionOption,
+			...tenantOption
+		});
+		const inserted = (result.upsertedCount ?? 0) + (result.insertedCount ?? 0);
+		const updated = result.modifiedCount ?? 0;
+		const upsertedIds = Object.values(result.upsertedIds ?? {});
+		if (upsertedIds.length > 0) for (let i = 0; i < upsertedIds.length; i++) {
+			const id = upsertedIds[i];
+			if (id === void 0 || id === null) continue;
+			const doc = await this.getById(String(id), this.optsFromCtx(ctx, { throwOnNotFound: false }));
+			if (!doc) continue;
+			const txn = doc;
+			await this.dispatch(createEvent(REVENUE_EVENTS.TRANSACTION_IMPORTED, {
+				transaction: txn,
+				source: opts.source,
+				bankAccountId: opts.bankAccountId,
+				externalId: txn.externalId ?? ""
+			}, ctx, {
+				resource: "transaction",
+				resourceId: txn.publicId
+			}), ctx);
+			await this.deps.bridges.ledger?.onTransactionImported?.(txn, ctx);
+		}
+		return {
+			inserted,
+			updated,
+			skipped: errors.length,
+			errors,
+			durationMs: Date.now() - startedAt
+		};
+	}
+	/**
+	* Drain a bank-feed provider into the collection.
+	*
+	* Pulls pages from `provider.fetchTransactions()` (Plaid cursor, QBO
+	* CDC) and feeds each batch through `import()`. Yields the running
+	* report so a host cron can stream-progress-report to logs / metrics.
+	*
+	* Stops when the provider returns no new rows AND no removals AND no
+	* `nextCursor`. Caller is responsible for persisting the final cursor
+	* in their own checkpoint table — `result.nextCursor` is returned so
+	* the host can write it after a successful drain.
+	*
+	* Plaid `removed[]` rows (and any provider that retracts entries) are
+	* routed through `removeByFeed` so the host's LedgerBridge can void
+	* any JE that was already posted.
+	*/
+	async drainSync(providerName, params, ctx = {}) {
+		if (!this.deps.bankFeedProviders) throw new ValidationError("`bankFeedProviders` not wired on the engine. Pass `providers.bankFeed` to `createRevenue`.");
+		const provider = this.deps.bankFeedProviders.get(providerName);
+		let totalImported = 0;
+		let totalUpdated = 0;
+		let totalRemoved = 0;
+		let lastCursor;
+		const errors = [];
+		for await (const page of provider.drain(params)) {
+			if (page.transactions && page.transactions.length > 0) {
+				const report = await this.import(page.transactions, {
+					bankAccountId: params.bankAccountId,
+					source: providerName
+				}, ctx);
+				totalImported += report.inserted;
+				totalUpdated += report.updated;
+				if (report.errors.length > 0) errors.push(...report.errors);
+			}
+			if (page.removed && page.removed.length > 0) {
+				const removed = await this.removeByFeed(page.removed.map((r) => r.externalId), {
+					bankAccountId: params.bankAccountId,
+					source: providerName
+				}, ctx);
+				totalRemoved += removed.removed;
+			}
+			if (page.nextCursor) lastCursor = page.nextCursor;
+		}
+		return {
+			totalImported,
+			totalUpdated,
+			totalRemoved,
+			...lastCursor !== void 0 ? { nextCursor: lastCursor } : {},
+			errors
+		};
+	}
+	/**
+	* Parse an upload (OFX / CAMT.053 / MT940 / CSV) via a registered
+	* bank-feed provider, then `import()` the result.
+	*
+	* Convenience over manually calling `provider.parseUpload()` and
+	* threading the canonical rows into `import()` — the file-upload
+	* route handler is one line.
+	*/
+	async parseAndImport(providerName, upload, ctx = {}) {
+		if (!this.deps.bankFeedProviders) throw new ValidationError("`bankFeedProviders` not wired on the engine.");
+		const provider = this.deps.bankFeedProviders.get(providerName);
+		if (!provider.parseUpload) throw new ValidationError(`Provider '${providerName}' does not support parseUpload`);
+		const parsed = await provider.parseUpload({
+			buffer: upload.buffer,
+			...upload.format !== void 0 ? { format: upload.format } : {},
+			bankAccountId: upload.bankAccountId
+		});
+		return this.import(parsed.transactions, {
+			bankAccountId: upload.bankAccountId,
+			source: providerName
+		}, ctx);
+	}
+	/**
+	* Hand-keyed entry — treasurer logs a cash deposit, owner injects
+	* capital, refund correction. Created in `pending` (manual SM); host
+	* proceeds with `match()` → `journalize()` to post it to the ledger.
+	*
+	* `kind: 'manual'` is enforced — calls passing other kinds throw.
+	*/
+	async createManual(data, ctx = {}) {
+		return await this.create({
+			organizationId: ctx.organizationId,
+			kind: TRANSACTION_KIND.MANUAL,
+			type: data.type,
+			flow: data.flow,
+			tags: ["manual"],
+			amount: data.amount,
+			currency: data.currency,
+			fee: 0,
+			tax: 0,
+			net: data.amount,
+			method: "manual",
+			status: initialStatusFor(TRANSACTION_KIND.MANUAL),
+			source: "manual",
+			...data.description !== void 0 ? { description: data.description } : {},
+			...data.counterparty !== void 0 ? { counterparty: data.counterparty } : {},
+			...data.reference !== void 0 ? { reference: data.reference } : {},
+			...data.postedDate !== void 0 ? { postedDate: data.postedDate } : {},
+			...data.valueDate !== void 0 ? { valueDate: data.valueDate } : {},
+			...data.bankAccountId !== void 0 ? { bankAccountId: data.bankAccountId } : {},
+			...data.sourceId !== void 0 ? { sourceId: data.sourceId } : {},
+			...data.sourceModel !== void 0 ? { sourceModel: data.sourceModel } : {},
+			...data.metadata !== void 0 ? { metadata: data.metadata } : {}
+		}, this.optsFromCtx(ctx));
+	}
+	/**
+	* Match a bank-feed / manual transaction to GL accounts, optionally
+	* cross-linking to an upstream payment-flow transaction.
+	*
+	* Atomic state CAS via `claim()` — the `where: { kind: { $in: [...] } }`
+	* predicate prevents a payment-flow row from being matched through this
+	* verb. Multi-source `from` (`['imported', 'matched']`) supports
+	* re-match after `unmatch()` (`matched → imported → matched`) without
+	* losing the prior mapping if the host wants to overwrite it.
+	*
+	* After a successful claim, `LedgerBridge.onTransactionMatched` runs
+	* — the canonical implementation creates a journal entry and chains
+	* `journalize()` to record the JE ref. The bridge call is OUTSIDE the
+	* claim's CAS window because JE posting is a side effect that may
+	* take seconds (cross-process call to ledger).
+	*/
+	async match(id, data, ctx = {}) {
+		const existing = await this.getById(id, this.optsFromCtx(ctx));
+		if (!existing) throw new TransactionNotFoundError(id);
+		if (existing.kind !== TRANSACTION_KIND.BANK_FEED && existing.kind !== TRANSACTION_KIND.MANUAL) throw new WrongTransactionKindError(id, "bank_feed | manual", existing.kind);
+		smFor(existing.kind).validate(existing.status, TRANSACTION_STATUS.MATCHED, id);
+		const patch = {
+			$set: {
+				matching: {
+					...data.mapping,
+					...data.matchedBy !== void 0 ? { matchedBy: data.matchedBy } : {},
+					matchedAt: /* @__PURE__ */ new Date()
+				},
+				...data.matchedBy !== void 0 ? { verifiedBy: data.matchedBy } : {},
+				verifiedAt: /* @__PURE__ */ new Date()
+			},
+			$unset: { journalEntryRef: 1 }
+		};
+		if (data.relatedTransactionId !== void 0) patch.$set.relatedTransactionId = data.relatedTransactionId;
+		const claimed = await this.claim(existing._id, {
+			from: [
+				TRANSACTION_STATUS.IMPORTED,
+				TRANSACTION_STATUS.MATCHED,
+				TRANSACTION_STATUS.PENDING
+			],
+			to: TRANSACTION_STATUS.MATCHED,
+			where: { kind: existing.kind }
+		}, patch, this.optsFromCtx(ctx));
+		if (!claimed) throw new ValidationError(`Transaction ${id} could not be matched (race-loss or illegal state)`);
+		await this.deps.bridges.ledger?.onTransactionMatched?.(claimed, data.mapping, ctx);
+		await this.dispatch(createEvent(REVENUE_EVENTS.TRANSACTION_MATCHED, {
+			transaction: claimed,
+			mapping: data.mapping,
+			...data.relatedTransactionId !== void 0 ? { relatedTransactionId: data.relatedTransactionId } : {},
+			...data.matchedBy !== void 0 ? { matchedBy: data.matchedBy } : {}
+		}, ctx, {
+			resource: "transaction",
+			resourceId: claimed.publicId
+		}), ctx);
+		return claimed;
+	}
+	/**
+	* Revert a matched transaction back to `imported`. Clears the
+	* `matching` block and `relatedTransactionId`. Notifies the
+	* LedgerBridge (which typically voids the journal entry) AFTER the
+	* state CAS lands.
+	*
+	* Only legal for `kind: 'bank_feed'` — manual entries don't allow
+	* un-match (the manual SM has no `matched → pending` edge).
+	*/
+	async unmatch(id, options = {}, ctx = {}) {
+		const existing = await this.getById(id, this.optsFromCtx(ctx));
+		if (!existing) throw new TransactionNotFoundError(id);
+		if (existing.kind !== TRANSACTION_KIND.BANK_FEED) throw new WrongTransactionKindError(id, "bank_feed", existing.kind);
+		const priorJournalEntryRef = existing.journalEntryRef;
+		const claimed = await this.claim(existing._id, {
+			from: TRANSACTION_STATUS.MATCHED,
+			to: TRANSACTION_STATUS.IMPORTED,
+			where: { kind: TRANSACTION_KIND.BANK_FEED }
+		}, { $unset: {
+			matching: 1,
+			relatedTransactionId: 1,
+			journalEntryRef: 1,
+			verifiedBy: 1,
+			verifiedAt: 1
+		} }, this.optsFromCtx(ctx));
+		if (!claimed) throw new ValidationError(`Transaction ${id} could not be unmatched (current state is not 'matched')`);
+		await this.deps.bridges.ledger?.onTransactionUnmatched?.(claimed, priorJournalEntryRef, ctx);
+		await this.dispatch(createEvent(REVENUE_EVENTS.TRANSACTION_UNMATCHED, {
+			transaction: claimed,
+			...options.unmatchedBy !== void 0 ? { unmatchedBy: options.unmatchedBy } : {}
+		}, ctx, {
+			resource: "transaction",
+			resourceId: claimed.publicId
+		}), ctx);
+		return claimed;
+	}
+	/**
+	* Stamp the journal entry reference and transition `matched →
+	* journalized`. Typical caller is the `LedgerBridge.onTransactionMatched`
+	* implementation — after creating a JE, it calls this verb so the row
+	* carries the back-reference.
+	*/
+	async journalize(id, data, ctx = {}) {
+		const existing = await this.getById(id, this.optsFromCtx(ctx));
+		if (!existing) throw new TransactionNotFoundError(id);
+		if (existing.kind !== TRANSACTION_KIND.BANK_FEED && existing.kind !== TRANSACTION_KIND.MANUAL) throw new WrongTransactionKindError(id, "bank_feed | manual", existing.kind);
+		smFor(existing.kind).validate(existing.status, TRANSACTION_STATUS.JOURNALIZED, id);
+		const claimed = await this.claim(existing._id, {
+			from: TRANSACTION_STATUS.MATCHED,
+			to: TRANSACTION_STATUS.JOURNALIZED,
+			where: { kind: existing.kind }
+		}, { $set: { journalEntryRef: data.journalEntryRef } }, this.optsFromCtx(ctx));
+		if (!claimed) throw new ValidationError(`Transaction ${id} could not be journalized (current state is not 'matched')`);
+		await this.deps.bridges.ledger?.onTransactionJournalized?.(claimed, data.journalEntryRef, ctx);
+		await this.dispatch(createEvent(REVENUE_EVENTS.TRANSACTION_JOURNALIZED, {
+			transaction: claimed,
+			journalEntryRef: data.journalEntryRef,
+			...data.journalizedBy !== void 0 ? { journalizedBy: data.journalizedBy } : {}
+		}, ctx, {
+			resource: "transaction",
+			resourceId: claimed.publicId
+		}), ctx);
+		return claimed;
+	}
+	/**
+	* Operator skip — marks an imported / matched / pending row as
+	* rejected (terminal). Use cases: duplicate of an already-imported
+	* row, non-cash entry the host doesn't want in the ledger, manual
+	* correction overrides.
+	*
+	* `relatedTransactionId` is preserved; reversal is the host's call.
+	*/
+	async reject(id, data, ctx = {}) {
+		const existing = await this.getById(id, this.optsFromCtx(ctx));
+		if (!existing) throw new TransactionNotFoundError(id);
+		if (existing.kind !== TRANSACTION_KIND.BANK_FEED && existing.kind !== TRANSACTION_KIND.MANUAL) throw new WrongTransactionKindError(id, "bank_feed | manual", existing.kind);
+		smFor(existing.kind).validate(existing.status, TRANSACTION_STATUS.REJECTED, id);
+		const claimed = await this.claim(existing._id, {
+			from: [
+				TRANSACTION_STATUS.IMPORTED,
+				TRANSACTION_STATUS.MATCHED,
+				TRANSACTION_STATUS.PENDING
+			],
+			to: TRANSACTION_STATUS.REJECTED,
+			where: { kind: existing.kind }
+		}, { $set: {
+			failureReason: data.reason,
+			failedAt: /* @__PURE__ */ new Date(),
+			...data.rejectedBy !== void 0 ? { verifiedBy: data.rejectedBy } : {}
+		} }, this.optsFromCtx(ctx));
+		if (!claimed) throw new ValidationError(`Transaction ${id} could not be rejected (illegal current state)`);
+		await this.deps.bridges.ledger?.onTransactionRejected?.(claimed, data.reason, ctx);
+		await this.dispatch(createEvent(REVENUE_EVENTS.TRANSACTION_REJECTED, {
+			transaction: claimed,
+			reason: data.reason,
+			...data.rejectedBy !== void 0 ? { rejectedBy: data.rejectedBy } : {}
+		}, ctx, {
+			resource: "transaction",
+			resourceId: claimed.publicId
+		}), ctx);
+		return claimed;
+	}
+	/**
+	* Soft-delete bank-feed rows that the upstream feed has retracted
+	* (Plaid `removed[]`, OFX correction).
+	*
+	* Each row is matched by `(orgId, bankAccountId, externalId)`; rows
+	* already journalized are NOT silently kept — they're surfaced in
+	* `retainedJournalized` so the caller can surface them in the UI
+	* ("the feed retracted these N rows but they're posted; reverse
+	* manually"). The host's `LedgerBridge` should post a reversing JE
+	* for those before any subsequent `delete()` can succeed.
+	*
+	* @returns `removed` (count soft-deleted), `retainedJournalized`
+	*          (rows kept because they're already in the GL).
+	*/
+	async removeByFeed(externalIds, opts, ctx = {}) {
+		if (externalIds.length === 0) return {
+			removed: 0,
+			retainedJournalized: []
+		};
+		const allFilter = {
+			kind: TRANSACTION_KIND.BANK_FEED,
+			bankAccountId: opts.bankAccountId,
+			externalId: { $in: externalIds },
+			deletedAt: null
+		};
+		const allDocs = await this.findAll(allFilter, this.optsFromCtx(ctx));
+		if (!Array.isArray(allDocs) || allDocs.length === 0) return {
+			removed: 0,
+			retainedJournalized: []
+		};
+		const retainedJournalized = [];
+		const removable = [];
+		for (const doc of allDocs) if (doc.status === TRANSACTION_STATUS.JOURNALIZED) retainedJournalized.push(doc);
+		else removable.push(doc);
+		let removed = 0;
+		for (const doc of removable) {
+			await this.delete(doc._id, this.optsFromCtx(ctx));
+			removed += 1;
+			await this.deps.bridges.ledger?.onTransactionRemovedByFeed?.(doc, ctx);
+			await this.dispatch(createEvent(REVENUE_EVENTS.TRANSACTION_REMOVED_BY_FEED, {
+				transaction: doc,
+				source: opts.source,
+				externalId: doc.externalId ?? ""
+			}, ctx, {
+				resource: "transaction",
+				resourceId: doc.publicId
+			}), ctx);
+		}
+		return {
+			removed,
+			retainedJournalized
+		};
+	}
+	/**
+	* Find candidate matches for cross-referencing a payment-flow row to
+	* its bank deposit (or vice-versa).
+	*
+	* Heuristic:
+	*   - same currency by default; cross-currency requires `fxRate` on
+	*     the candidate row (multi-currency reconciliation).
+	*   - amount within `amountTolerancePct` (default 1%) — accounts for
+	*     gateway fees / FX rounding.
+	*   - posted/created within `toleranceDays` of the target date
+	*     (default 3 days — covers ACH delays, weekend settlement).
+	*   - terminal verified states only (`verified` / `completed` for
+	*     payment_flow, `imported` / `matched` for bank_feed).
+	*
+	* Returned candidates are unsorted; callers rank by their own
+	* confidence model (counterparty fuzzy match, currency identity,
+	* exact-amount preference, …).
+	*/
+	async findMatchCandidates(filter, ctx = {}) {
+		const tolerance = filter.toleranceDays ?? 3;
+		const pct = filter.amountTolerancePct ?? .01;
+		const start = /* @__PURE__ */ new Date(filter.postedDate.getTime() - tolerance * 864e5);
+		const end = new Date(filter.postedDate.getTime() + tolerance * 864e5);
+		const minAmount = filter.amount * (1 - pct);
+		const maxAmount = filter.amount * (1 + pct);
+		const targetKind = filter.kind ?? TRANSACTION_KIND.PAYMENT_FLOW;
+		const validStatuses = targetKind === TRANSACTION_KIND.PAYMENT_FLOW ? [TRANSACTION_STATUS.VERIFIED, TRANSACTION_STATUS.COMPLETED] : [TRANSACTION_STATUS.IMPORTED, TRANSACTION_STATUS.MATCHED];
+		const dateClauses = targetKind === TRANSACTION_KIND.BANK_FEED ? [{ postedDate: {
+			$gte: start,
+			$lte: end
+		} }] : [{ verifiedAt: {
+			$gte: start,
+			$lte: end
+		} }, { createdAt: {
+			$gte: start,
+			$lte: end
+		} }];
+		const query = {
+			kind: targetKind,
+			status: { $in: validStatuses },
+			amount: {
+				$gte: minAmount,
+				$lte: maxAmount
+			},
+			$or: dateClauses
+		};
+		if (filter.currency !== void 0) query.currency = filter.currency;
+		if (filter.counterpartyName !== void 0) query["counterparty.name"] = {
+			$regex: escapeRegex(filter.counterpartyName),
+			$options: "i"
+		};
+		const docs = await this.findAll(query, this.optsFromCtx(ctx, { limit: 50 }));
+		return Array.isArray(docs) ? docs : [];
+	}
+	/**
+	* Running balance for a bank account as of `asOf` (defaults to now).
+	*
+	* Uses mongokit's tenant-scoped read via `findAll` — inflows minus
+	* outflows over `kind: 'bank_feed'`, terminal states only. For audit
+	* pages where exact-to-the-cent reconciliation is required, prefer
+	* the most recent row's `balanceAfter` (banks ship that field on
+	* every entry).
+	*/
+	async getRunningBalance(bankAccountId, asOf = /* @__PURE__ */ new Date(), ctx = {}) {
+		const filter = {
+			kind: TRANSACTION_KIND.BANK_FEED,
+			bankAccountId,
+			postedDate: { $lte: asOf },
+			status: { $in: [
+				TRANSACTION_STATUS.IMPORTED,
+				TRANSACTION_STATUS.MATCHED,
+				TRANSACTION_STATUS.JOURNALIZED
+			] },
+			deletedAt: null
+		};
+		const rows = await this.findAll(filter, this.optsFromCtx(ctx));
+		let balance = 0;
+		let currency = null;
+		for (const row of rows) {
+			if (currency === null) currency = row.currency;
+			balance += row.flow === "inflow" ? row.amount : -row.amount;
+		}
+		return {
+			balance,
+			currency,
+			rowCount: rows.length,
+			asOf
+		};
+	}
+};
+/** Escape user-provided strings before embedding in `$regex`. */
+function escapeRegex(input) {
+	return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+//#endregion
+//#region src/repositories/subscription.repository.ts
+/**
+* SubscriptionRepository — data layer + domain verbs for the recurring-
+* billing lifecycle.
+*
+* **CRUD inherited** from mongokit (via {@link RevenueRepositoryBase}):
+* `getById`, `getByQuery`, `getAll`, `create`, `update`, `delete`,
+* `findOneAndUpdate`, `count`, `exists`, `claim`, `cursor`, `updateMany`,
+* `deleteMany`. All participate in `multiTenantPlugin` scope filtering
+* when wired.
+*
+* **Domain verbs (state transitions):** `activate`, `cancel`, `pause`,
+* `resume`. Each runs the state-machine guard (`SUBSCRIPTION_STATE_MACHINE`
+* — invalid transitions throw, never silently no-op), persists the
+* resulting writes through {@link RevenueRepositoryBase.optsFromCtx} so
+* tenant scope is preserved end-to-end, then dispatches its
+* `revenue:subscription.*` event via {@link RevenueRepositoryBase.dispatch}.
+*
+* **Multi-tenant correctness.** Every internal `getById`/`update` call
+* threads `ctx.organizationId` through `optsFromCtx(ctx)`. Without this
+* threading the inner read would either throw
+* `Missing 'organizationId' in context` (when `multiTenantPlugin` is
+* required) or — worse — return another tenant's subscription matching
+* the same `_id` shape (when `required: false`). 2.1.0 had this bug; 2.1.1+
+* is correct.
+*
+* @example Activate a pending sub
+* ```ts
+* const ctx = { organizationId: 'org_42', actorId: 'user_99' };
+* const sub = await subRepo.create(
+*   { customerId: 'cust_1', planKey: 'monthly', amount: 999, currency: 'USD',
+*     status: SUBSCRIPTION_STATUS.PENDING, isActive: false },
+*   ctx,
+* );
+* await subRepo.activate(String(sub._id), {}, ctx);
+* ```
+*/
+var SubscriptionRepository = class extends RevenueRepositoryBase {
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	async activate(subscriptionId, options = {}, ctx = {}) {
+		const opts = this.optsFromCtx(ctx);
+		const sub = await this.getById(subscriptionId, opts);
+		if (!sub) throw new SubscriptionNotFoundError(subscriptionId);
+		SUBSCRIPTION_STATE_MACHINE.validate(sub.status, SUBSCRIPTION_STATUS.ACTIVE, subscriptionId);
+		const now = options.timestamp ?? /* @__PURE__ */ new Date();
+		const endDate = new Date(now);
+		if (sub.planKey === "monthly") endDate.setMonth(endDate.getMonth() + 1);
+		else if (sub.planKey === "quarterly") endDate.setMonth(endDate.getMonth() + 3);
+		else if (sub.planKey === "yearly") endDate.setFullYear(endDate.getFullYear() + 1);
+		else endDate.setDate(endDate.getDate() + 30);
+		const updated = await this.update(subscriptionId, {
+			status: SUBSCRIPTION_STATUS.ACTIVE,
+			isActive: true,
+			activatedAt: now,
+			endDate
+		}, this.optsFromCtx(ctx, { throwOnNotFound: true }));
+		if (!updated) throw new SubscriptionNotFoundError(subscriptionId);
+		await this.dispatch(createEvent(REVENUE_EVENTS.SUBSCRIPTION_ACTIVATED, {
+			subscription: updated,
+			activatedAt: now
+		}, ctx, {
+			resource: "subscription",
+			resourceId: updated?.publicId
+		}), ctx);
+		return updated;
+	}
+	async cancel(subscriptionId, options = {}, ctx = {}) {
+		const opts = this.optsFromCtx(ctx);
+		const sub = await this.getById(subscriptionId, opts);
+		if (!sub) throw new SubscriptionNotFoundError(subscriptionId);
+		SUBSCRIPTION_STATE_MACHINE.validate(sub.status, SUBSCRIPTION_STATUS.CANCELLED, subscriptionId);
+		const updates = {
+			status: SUBSCRIPTION_STATUS.CANCELLED,
+			isActive: false,
+			canceledAt: /* @__PURE__ */ new Date(),
+			cancellationReason: options.reason
+		};
+		if (!options.immediate && sub.endDate) {
+			updates.cancelAt = sub.endDate;
+			updates.status = sub.status;
+			updates.isActive = sub.isActive;
+			delete updates.canceledAt;
+		}
+		const updated = await this.update(subscriptionId, updates, this.optsFromCtx(ctx, { throwOnNotFound: true }));
+		if (!updated) throw new SubscriptionNotFoundError(subscriptionId);
+		await this.dispatch(createEvent(REVENUE_EVENTS.SUBSCRIPTION_CANCELLED, {
+			subscription: updated,
+			immediate: options.immediate,
+			reason: options.reason
+		}, ctx, {
+			resource: "subscription",
+			resourceId: updated?.publicId
+		}), ctx);
+		return updated;
+	}
+	async pause(subscriptionId, options = {}, ctx = {}) {
+		const opts = this.optsFromCtx(ctx);
+		const sub = await this.getById(subscriptionId, opts);
+		if (!sub) throw new SubscriptionNotFoundError(subscriptionId);
+		SUBSCRIPTION_STATE_MACHINE.validate(sub.status, SUBSCRIPTION_STATUS.PAUSED, subscriptionId);
+		const updated = await this.update(subscriptionId, {
+			status: SUBSCRIPTION_STATUS.PAUSED,
+			isActive: false,
+			pausedAt: /* @__PURE__ */ new Date(),
+			pauseReason: options.reason
+		}, this.optsFromCtx(ctx, { throwOnNotFound: true }));
+		if (!updated) throw new SubscriptionNotFoundError(subscriptionId);
+		await this.dispatch(createEvent(REVENUE_EVENTS.SUBSCRIPTION_PAUSED, {
+			subscription: updated,
+			reason: options.reason
+		}, ctx, {
+			resource: "subscription",
+			resourceId: updated?.publicId
+		}), ctx);
+		return updated;
+	}
+	async resume(subscriptionId, options = {}, ctx = {}) {
+		const opts = this.optsFromCtx(ctx);
+		const sub = await this.getById(subscriptionId, opts);
+		if (!sub) throw new SubscriptionNotFoundError(subscriptionId);
+		SUBSCRIPTION_STATE_MACHINE.validate(sub.status, SUBSCRIPTION_STATUS.ACTIVE, subscriptionId);
+		const updates = {
+			status: SUBSCRIPTION_STATUS.ACTIVE,
+			isActive: true
+		};
+		if (options.extendPeriod && sub.pausedAt && sub.endDate) {
+			const pauseDuration = Date.now() - sub.pausedAt.getTime();
+			updates.endDate = new Date(sub.endDate.getTime() + pauseDuration);
+		}
+		const updated = await this.update(subscriptionId, updates, this.optsFromCtx(ctx, { throwOnNotFound: true }));
+		if (!updated) throw new SubscriptionNotFoundError(subscriptionId);
+		await this.dispatch(createEvent(REVENUE_EVENTS.SUBSCRIPTION_RESUMED, {
+			subscription: updated,
+			extendPeriod: options.extendPeriod
+		}, ctx, {
+			resource: "subscription",
+			resourceId: updated?.publicId
+		}), ctx);
+		return updated;
+	}
+};
+
+//#endregion
+//#region src/repositories/settlement.repository.ts
+/**
+* SettlementRepository — payouts to recipients (organizations, vendors,
+* affiliates).
+*
+* **CRUD inherited** via {@link RevenueRepositoryBase}. **Domain verbs:**
+* `schedule`, `processPending`, `complete`, `fail`. State machine:
+* `pending → processing → completed | failed`; `failed` with
+* `retry: true` resets to `pending` with a delayed `scheduledAt`.
+*
+* **Multi-tenant correctness.** Every read/write threads `ctx` through
+* {@link RevenueRepositoryBase.optsFromCtx} so `multiTenantPlugin`
+* scope filters apply. 2.1.0 had several `getById`/`update` calls that
+* dropped ctx — fixed in 2.1.1+.
+*
+* Bridges (`ledger`, `notification`) fire on `complete()` so a host
+* can pin double-entry book-keeping or push a "you got paid" email
+* without the repo knowing about either subsystem.
+*/
+var SettlementRepository = class extends RevenueRepositoryBase {
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	async schedule(params, ctx = {}) {
+		const settlement = await this.create({
+			...params,
+			status: SETTLEMENT_STATUS.PENDING,
+			scheduledAt: params.scheduledAt ?? /* @__PURE__ */ new Date(),
+			retryCount: 0
+		}, this.optsFromCtx(ctx));
+		await this.dispatch(createEvent(REVENUE_EVENTS.SETTLEMENT_SCHEDULED, {
+			settlement,
+			scheduledAt: settlement.scheduledAt
+		}, ctx, {
+			resource: "settlement",
+			resourceId: settlement.publicId
+		}), ctx);
+		return settlement;
+	}
+	async processPending(options = {}, ctx = {}) {
+		const query = {
+			status: "pending",
+			scheduledAt: { $lte: /* @__PURE__ */ new Date() }
+		};
+		if (options.organizationId) query.organizationId = options.organizationId;
+		if (options.payoutMethod) query.payoutMethod = options.payoutMethod;
+		const pending = (await this.getAll({
+			filters: query,
+			limit: options.limit ?? 50,
+			sort: { scheduledAt: 1 }
+		}, this.optsFromCtx(ctx))).data ?? [];
+		if (options.dryRun) return {
+			processed: pending.length,
+			succeeded: 0,
+			failed: 0,
+			settlements: pending,
+			errors: []
+		};
+		const out = {
+			processed: 0,
+			succeeded: 0,
+			failed: 0,
+			settlements: [],
+			errors: []
+		};
+		for (const settlement of pending) {
+			try {
+				SETTLEMENT_STATE_MACHINE.validate(settlement.status, SETTLEMENT_STATUS.PROCESSING, String(settlement._id));
+				await this.update(settlement._id, {
+					status: SETTLEMENT_STATUS.PROCESSING,
+					processedAt: /* @__PURE__ */ new Date()
+				}, this.optsFromCtx(ctx));
+				out.succeeded++;
+				out.settlements.push(settlement);
+				await this.dispatch(createEvent(REVENUE_EVENTS.SETTLEMENT_PROCESSING, {
+					settlement,
+					processedAt: /* @__PURE__ */ new Date()
+				}, ctx, {
+					resource: "settlement",
+					resourceId: settlement.publicId
+				}), ctx);
+			} catch (err) {
+				out.failed++;
+				out.errors.push({
+					settlementId: settlement._id,
+					error: err
+				});
+			}
+			out.processed++;
+		}
+		return out;
+	}
+	async complete(settlementId, details = {}, ctx = {}) {
+		const opts = this.optsFromCtx(ctx);
+		const settlement = await this.getById(settlementId, opts);
+		if (!settlement) throw new SettlementNotFoundError(settlementId);
+		SETTLEMENT_STATE_MACHINE.validate(settlement.status, SETTLEMENT_STATUS.COMPLETED, settlementId);
+		const updates = {
+			status: SETTLEMENT_STATUS.COMPLETED,
+			completedAt: /* @__PURE__ */ new Date(),
+			notes: details.notes,
+			metadata: {
+				...settlement.metadata,
+				...details.metadata
+			}
+		};
+		if (details.transferReference) updates.bankTransferDetails = {
+			...settlement.bankTransferDetails,
+			transferReference: details.transferReference,
+			transferredAt: details.transferredAt ?? /* @__PURE__ */ new Date()
+		};
+		if (details.transactionHash) updates.cryptoDetails = {
+			...settlement.cryptoDetails,
+			transactionHash: details.transactionHash,
+			transferredAt: details.transferredAt ?? /* @__PURE__ */ new Date()
+		};
+		const updated = await this.update(settlementId, updates, this.optsFromCtx(ctx, { throwOnNotFound: true }));
+		if (!updated) throw new SettlementNotFoundError(settlementId);
+		await this.deps.bridges.ledger?.onSettlementCompleted?.(updated, ctx);
+		await this.deps.bridges.notification?.onSettlementCompleted?.(updated, ctx);
+		await this.dispatch(createEvent(REVENUE_EVENTS.SETTLEMENT_COMPLETED, {
+			settlement: updated,
+			completedAt: /* @__PURE__ */ new Date()
+		}, ctx, {
+			resource: "settlement",
+			resourceId: updated?.publicId
+		}), ctx);
+		return updated;
+	}
+	async fail(settlementId, reason, options = {}, ctx = {}) {
+		const opts = this.optsFromCtx(ctx);
+		const settlement = await this.getById(settlementId, opts);
+		if (!settlement) throw new SettlementNotFoundError(settlementId);
+		if (options.retry) await this.update(settlementId, {
+			status: SETTLEMENT_STATUS.PENDING,
+			retryCount: (settlement.retryCount ?? 0) + 1,
+			failureReason: reason,
+			failureCode: options.code,
+			scheduledAt: new Date(Date.now() + 36e5)
+		}, opts);
+		else {
+			SETTLEMENT_STATE_MACHINE.validate(settlement.status, SETTLEMENT_STATUS.FAILED, settlementId);
+			await this.update(settlementId, {
+				status: SETTLEMENT_STATUS.FAILED,
+				failedAt: /* @__PURE__ */ new Date(),
+				failureReason: reason,
+				failureCode: options.code
+			}, opts);
+		}
+		const updated = await this.getById(settlementId, opts);
+		await this.dispatch(createEvent(REVENUE_EVENTS.SETTLEMENT_FAILED, {
+			settlement: updated,
+			reason,
+			code: options.code,
+			retry: options.retry
+		}, ctx, {
+			resource: "settlement",
+			resourceId: updated?.publicId
+		}), ctx);
+		return updated;
+	}
+};
+
+//#endregion
+export { SubscriptionRepository as n, TransactionRepository as r, SettlementRepository as t };