@classytic/revenue 2.0.1 → 2.1.0

package/dist/{settlement.repository-DHIPx5S4.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, g as SETTLEMENT_STATUS, r as SUBSCRIPTION_STATUS, w as HOLD_STATUS } from "./subscription.enums-tfoAgsTv.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 };

package/dist/{subscription.enums-tfoAgsTv.mjs → subscription.enums-DoIr56O6.mjs}

@@ -1,42 +1,3 @@
-//#region src/enums/transaction.enums.ts
-const TRANSACTION_FLOW = {
-	INFLOW: "inflow",
-	OUTFLOW: "outflow"
-};
-const TRANSACTION_FLOW_VALUES = Object.values(TRANSACTION_FLOW);
-const TRANSACTION_STATUS = {
-	PENDING: "pending",
-	PAYMENT_INITIATED: "payment_initiated",
-	PROCESSING: "processing",
-	REQUIRES_ACTION: "requires_action",
-	VERIFIED: "verified",
-	COMPLETED: "completed",
-	FAILED: "failed",
-	CANCELLED: "cancelled",
-	EXPIRED: "expired",
-	REFUNDED: "refunded",
-	PARTIALLY_REFUNDED: "partially_refunded"
-};
-const TRANSACTION_STATUS_VALUES = Object.values(TRANSACTION_STATUS);
-const LIBRARY_CATEGORIES = {
-	SUBSCRIPTION: "subscription",
-	PURCHASE: "purchase"
-};
-const LIBRARY_CATEGORY_VALUES = Object.values(LIBRARY_CATEGORIES);
-const transactionFlowSet = new Set(TRANSACTION_FLOW_VALUES);
-const transactionStatusSet = new Set(TRANSACTION_STATUS_VALUES);
-const libraryCategorySet = new Set(LIBRARY_CATEGORY_VALUES);
-function isLibraryCategory(value) {
-	return typeof value === "string" && libraryCategorySet.has(value);
-}
-function isTransactionFlow(value) {
-	return typeof value === "string" && transactionFlowSet.has(value);
-}
-function isTransactionStatus(value) {
-	return typeof value === "string" && transactionStatusSet.has(value);
-}
-
-//#endregion
 //#region src/enums/escrow.enums.ts
 const HOLD_STATUS = {
 	PENDING: "pending",
@@ -169,4 +130,4 @@ function isPlanKey(value) {
 }
 
 //#endregion
-export { isReleaseReason as A, HOLD_REASON_VALUES as C, RELEASE_REASON_VALUES as D, RELEASE_REASON as E, TRANSACTION_STATUS as F, TRANSACTION_STATUS_VALUES as I, isLibraryCategory as L, LIBRARY_CATEGORY_VALUES as M, TRANSACTION_FLOW as N, isHoldReason as O, TRANSACTION_FLOW_VALUES as P, isTransactionFlow as R, HOLD_REASON as S, HOLD_STATUS_VALUES as T, SETTLEMENT_STATUS_VALUES as _, isPlanKey as a, isSettlementStatus as b, PAYOUT_METHOD_VALUES as c, SPLIT_TYPE as d, SPLIT_TYPE_VALUES as f, SETTLEMENT_STATUS as g, isSplitType as h, SUBSCRIPTION_STATUS_VALUES as i, LIBRARY_CATEGORIES as j, isHoldStatus as k, SPLIT_STATUS as l, isSplitStatus as m, PLAN_KEY_VALUES as n, isSubscriptionStatus as o, isPayoutMethod as p, SUBSCRIPTION_STATUS as r, PAYOUT_METHOD as s, PLAN_KEYS as t, SPLIT_STATUS_VALUES as u, SETTLEMENT_TYPE as v, HOLD_STATUS as w, isSettlementType as x, SETTLEMENT_TYPE_VALUES as y, isTransactionStatus as z };
+export { isReleaseReason as A, HOLD_REASON_VALUES as C, RELEASE_REASON_VALUES as D, RELEASE_REASON as E, isHoldReason as O, HOLD_REASON as S, HOLD_STATUS_VALUES as T, SETTLEMENT_STATUS_VALUES as _, isPlanKey as a, isSettlementStatus as b, PAYOUT_METHOD_VALUES as c, SPLIT_TYPE as d, SPLIT_TYPE_VALUES as f, SETTLEMENT_STATUS as g, isSplitType as h, SUBSCRIPTION_STATUS_VALUES as i, isHoldStatus as k, SPLIT_STATUS as l, isSplitStatus as m, PLAN_KEY_VALUES as n, isSubscriptionStatus as o, isPayoutMethod as p, SUBSCRIPTION_STATUS as r, PAYOUT_METHOD as s, PLAN_KEYS as t, SPLIT_STATUS_VALUES as u, SETTLEMENT_TYPE as v, HOLD_STATUS as w, isSettlementType as x, SETTLEMENT_TYPE_VALUES as y };