@classytic/revenue 2.0.0 → 2.1.0

package/dist/{settlement.repository-Cy3mMWGH.mjs → settlement.repository-Ba2U17zY.mjs}

@@ -1,20 +1,12 @@
-import { n as createEvent, t as REVENUE_EVENTS } from "./event-constants-CEMitnIV.mjs";
-import { F as TRANSACTION_STATUS, u as SETTLEMENT_STATUS, v as SUBSCRIPTION_STATUS, w as HOLD_STATUS } from "./split.enums-CQE3ekH1.mjs";
-import { d as SubscriptionNotFoundError, f as TransactionNotFoundError, p as ValidationError, u as SettlementNotFoundError } from "./errors-DHa8JVQ-.mjs";
-import { SETTLEMENT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, TRANSACTION_STATE_MACHINE } from "./core/state-machines.mjs";
-import { a as reverseTax, c as reverseCommission, n as calculateSplits, s as calculateCommission, t as calculateOrganizationPayout } from "./splits-BAfY-a9P.mjs";
+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-CTiDNWzc.mjs";
+import { g as SETTLEMENT_STATUS, r as SUBSCRIPTION_STATUS, w as HOLD_STATUS } from "./subscription.enums-DoIr56O6.mjs";
+import { f as SettlementNotFoundError, g as WrongTransactionKindError, h as ValidationError, m as TransactionNotFoundError, n as BankFeedImportError, p as SubscriptionNotFoundError } from "./errors-Dt46UZL_.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-D8XkNWgX.mjs";
 import { Repository, withTransaction } from "@classytic/mongokit";
 
 //#region src/repositories/transaction.repository.ts
-/**
-* TransactionRepository — extends mongokit Repository.
-*
-* CRUD inherited: getAll, getById, getByQuery, create, update, delete, count, exists.
-* Domain verbs: createPaymentIntent, verify, refund, handleWebhook, hold, release, split.
-*
-* All domain verbs return raw mongokit docs — no custom envelopes.
-* Composite results (refund creates a new doc) are stored in metadata on the primary doc.
-*/
 var TransactionRepository = class extends Repository {
 	deps;
 	constructor(model, plugins = []) {
@@ -91,8 +83,10 @@ var TransactionRepository = class extends Repository {
 		let gatewayData = { type: params.gateway };
 		if (params.amount > 0) {
 			const intent = await provider.createIntent({
-				amount: params.amount,
-				currency,
+				amount: {
+					amount: params.amount,
+					currency
+				},
 				metadata: params.metadata,
 				...params.paymentData
 			});
@@ -457,7 +451,555 @@ var TransactionRepository = class extends Repository {
 		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 query = {
+			kind: targetKind,
+			status: { $in: targetKind === TRANSACTION_KIND.PAYMENT_FLOW ? [TRANSACTION_STATUS.VERIFIED, TRANSACTION_STATUS.COMPLETED] : [TRANSACTION_STATUS.IMPORTED, TRANSACTION_STATUS.MATCHED] },
+			amount: {
+				$gte: minAmount,
+				$lte: maxAmount
+			},
+			$or: [{ postedDate: {
+				$gte: start,
+				$lte: end
+			} }, { createdAt: {
+				$gte: start,
+				$lte: end
+			} }]
+		};
+		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
@@ -656,7 +1198,7 @@ var SettlementRepository = class extends Repository {
 			filters: query,
 			limit: options.limit ?? 50,
 			sort: { scheduledAt: 1 }
-		})).docs ?? [];
+		})).data ?? [];
 		if (options.dryRun) return {
 			processed: pending.length,
 			succeeded: 0,

package/dist/shared/index.d.mts

@@ -1,2 +1,2 @@
-import { A as SplitInfo, B as validateTaxCalculation, C as multiplyMoney, D as toCurrencyCode, E as sumMoney, F as TaxConfig, H as calculateCommission, I as TaxType, L as calculateTax, M as calculateOrganizationPayout, N as calculateSplits, O as toMajor, P as TaxCalculation, R as getTaxType, S as money, T as subtractMoney, U as reverseCommission, V as CommissionInfo, _ as isMoney, a as CurrencyCode, b as isZeroMoney, c as Money, d as addMoney, f as compareMoney, g as isCurrencyCode, h as fromSmallestUnit, i as CURRENCIES, j as SplitRule, k as toSmallestUnit, l as MoneyValue, m as fromMajor, n as getAuditTrail, o as CurrencyMismatchError, p as equalsMoney, r as getLastStateChange, s as MINOR_UNIT_FACTOR, t as appendAuditEvent, u as absMoney, v as isNegativeMoney, w as negateMoney, x as minorUnitFactor, y as isPositiveMoney, z as reverseTax } from "../audit-DZ0eTr9g.mjs";
+import { A as SplitInfo, B as validateTaxCalculation, C as multiplyMoney, D as toCurrencyCode, E as sumMoney, F as TaxConfig, H as calculateCommission, I as TaxType, L as calculateTax, M as calculateOrganizationPayout, N as calculateSplits, O as toMajor, P as TaxCalculation, R as getTaxType, S as money, T as subtractMoney, U as reverseCommission, V as CommissionInfo, _ as isMoney, a as CurrencyCode, b as isZeroMoney, c as Money, d as addMoney, f as compareMoney, g as isCurrencyCode, h as fromSmallestUnit, i as CURRENCIES, j as SplitRule, k as toSmallestUnit, l as MoneyValue, m as fromMajor, n as getAuditTrail, o as CurrencyMismatchError, p as equalsMoney, r as getLastStateChange, s as MINOR_UNIT_FACTOR, t as appendAuditEvent, u as absMoney, v as isNegativeMoney, w as negateMoney, x as minorUnitFactor, y as isPositiveMoney, z as reverseTax } from "../audit-DRKuLBFO.mjs";
 export { CURRENCIES, CommissionInfo, type CurrencyCode, CurrencyMismatchError, MINOR_UNIT_FACTOR, type Money, type MoneyValue, SplitInfo, SplitRule, TaxCalculation, TaxConfig, TaxType, absMoney, addMoney, appendAuditEvent, calculateCommission, calculateOrganizationPayout, calculateSplits, calculateTax, compareMoney, equalsMoney, fromMajor, fromSmallestUnit, getAuditTrail, getLastStateChange, getTaxType, isCurrencyCode, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, minorUnitFactor, money, multiplyMoney, negateMoney, reverseCommission, reverseTax, subtractMoney, sumMoney, toCurrencyCode, toMajor, toSmallestUnit, validateTaxCalculation };

package/dist/shared/index.mjs

@@ -1,4 +1,4 @@
-import { a as reverseTax, c as reverseCommission, i as getTaxType, n as calculateSplits, o as validateTaxCalculation, r as calculateTax, s as calculateCommission, t as calculateOrganizationPayout } from "../splits-BAfY-a9P.mjs";
-import { C as sumMoney, E as toSmallestUnit, S as subtractMoney, T as toMajor, _ as isZeroMoney, a as CurrencyMismatchError, b as multiplyMoney, c as addMoney, d as fromMajor, f as fromSmallestUnit, g as isPositiveMoney, h as isNegativeMoney, i as CURRENCIES, l as compareMoney, m as isMoney, n as getAuditTrail, o as MINOR_UNIT_FACTOR, p as isCurrencyCode, r as getLastStateChange, s as absMoney, t as appendAuditEvent, u as equalsMoney, v as minorUnitFactor, w as toCurrencyCode, x as negateMoney, y as money } from "../audit-B39B0Sdq.mjs";
+import { a as reverseTax, c as reverseCommission, i as getTaxType, n as calculateSplits, o as validateTaxCalculation, r as calculateTax, s as calculateCommission, t as calculateOrganizationPayout } from "../splits-D8XkNWgX.mjs";
+import { C as sumMoney, E as toSmallestUnit, S as subtractMoney, T as toMajor, _ as isZeroMoney, a as CurrencyMismatchError, b as multiplyMoney, c as addMoney, d as fromMajor, f as fromSmallestUnit, g as isPositiveMoney, h as isNegativeMoney, i as CURRENCIES, l as compareMoney, m as isMoney, n as getAuditTrail, o as MINOR_UNIT_FACTOR, p as isCurrencyCode, r as getLastStateChange, s as absMoney, t as appendAuditEvent, u as equalsMoney, v as minorUnitFactor, w as toCurrencyCode, x as negateMoney, y as money } from "../audit-Ba2XB2C4.mjs";
 
 export { CURRENCIES, CurrencyMismatchError, MINOR_UNIT_FACTOR, absMoney, addMoney, appendAuditEvent, calculateCommission, calculateOrganizationPayout, calculateSplits, calculateTax, compareMoney, equalsMoney, fromMajor, fromSmallestUnit, getAuditTrail, getLastStateChange, getTaxType, isCurrencyCode, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, minorUnitFactor, money, multiplyMoney, negateMoney, reverseCommission, reverseTax, subtractMoney, sumMoney, toCurrencyCode, toMajor, toSmallestUnit, validateTaxCalculation };