@classytic/revenue 2.0.1 → 2.1.3

package/dist/index.mjs

@@ -1,23 +1,29 @@
-import { n as createEvent, t as REVENUE_EVENTS } from "./event-constants-CEMitnIV.mjs";
-import { A as isReleaseReason, C as HOLD_REASON_VALUES, D as RELEASE_REASON_VALUES, E as RELEASE_REASON, F as TRANSACTION_STATUS, I as TRANSACTION_STATUS_VALUES, L as isLibraryCategory, M as LIBRARY_CATEGORY_VALUES, N as TRANSACTION_FLOW, O as isHoldReason, P as TRANSACTION_FLOW_VALUES, R as isTransactionFlow, S as HOLD_REASON, T as HOLD_STATUS_VALUES, _ as SETTLEMENT_STATUS_VALUES, a as isPlanKey, b as isSettlementStatus, c as PAYOUT_METHOD_VALUES, d as SPLIT_TYPE, f as SPLIT_TYPE_VALUES, g as SETTLEMENT_STATUS, h as isSplitType, i as SUBSCRIPTION_STATUS_VALUES, j as LIBRARY_CATEGORIES, k as isHoldStatus, l as SPLIT_STATUS, m as isSplitStatus, n as PLAN_KEY_VALUES, o as isSubscriptionStatus, p as isPayoutMethod, r as SUBSCRIPTION_STATUS, s as PAYOUT_METHOD, t as PLAN_KEYS, u as SPLIT_STATUS_VALUES, v as SETTLEMENT_TYPE, w as HOLD_STATUS, x as isSettlementType, y as SETTLEMENT_TYPE_VALUES, z as isTransactionStatus } from "./subscription.enums-tfoAgsTv.mjs";
-import { a as PaymentVerificationError, c as RefundNotSupportedError, d as SubscriptionNotFoundError, f as TransactionNotFoundError, i as PaymentIntentCreationError, l as RevenueError, n as ConfigurationError, o as ProviderCapabilityError, p as ValidationError, r as InvalidStateTransitionError, s as ProviderNotFoundError, t as AlreadyVerifiedError, u as SettlementNotFoundError } from "./errors-DHa8JVQ-.mjs";
-import { HOLD_STATE_MACHINE, SETTLEMENT_STATE_MACHINE, SPLIT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, StateMachine, TRANSACTION_STATE_MACHINE } from "./core/state-machines.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-BAfY-a9P.mjs";
-import { n as SubscriptionRepository, r as TransactionRepository, t as SettlementRepository } from "./settlement.repository-DHIPx5S4.mjs";
+import { _ as TRANSACTION_STATUS, a as TRANSACTION_KIND, b as isTransactionFlow, c as isBankFeedSource, d as isTransactionKind, f as statusesForKind, g as TRANSACTION_FLOW_VALUES, h as TRANSACTION_FLOW, i as BANK_FEED_STATUS_VALUES, l as isBankFeedStatus, m as LIBRARY_CATEGORY_VALUES, n as BANK_FEED_SOURCE_VALUES, o as TRANSACTION_KIND_VALUES, p as LIBRARY_CATEGORIES, r as BANK_FEED_STATUS, s as initialStatusFor, t as BANK_FEED_SOURCE, u as isStatusValidForKind, v as TRANSACTION_STATUS_VALUES, x as isTransactionStatus, y as isLibraryCategory } from "./bank-feed.enums-kYTLTTbe.mjs";
+import { n as SubscriptionRepository, r as TransactionRepository, t as SettlementRepository } from "./settlement.repository-BAdc9qGl.mjs";
+import { n as createEvent, t as REVENUE_EVENTS } from "./event-constants-Dn1TKahe.mjs";
+import { A as isReleaseReason, C as HOLD_REASON_VALUES, D as RELEASE_REASON_VALUES, E as RELEASE_REASON, O as isHoldReason, S as HOLD_REASON, T as HOLD_STATUS_VALUES, _ as SETTLEMENT_STATUS_VALUES, a as isPlanKey, b as isSettlementStatus, c as PAYOUT_METHOD_VALUES, d as SPLIT_TYPE, f as SPLIT_TYPE_VALUES, g as SETTLEMENT_STATUS, h as isSplitType, i as SUBSCRIPTION_STATUS_VALUES, k as isHoldStatus, l as SPLIT_STATUS, m as isSplitStatus, n as PLAN_KEY_VALUES, o as isSubscriptionStatus, p as isPayoutMethod, r as SUBSCRIPTION_STATUS, s as PAYOUT_METHOD, t as PLAN_KEYS, u as SPLIT_STATUS_VALUES, v as SETTLEMENT_TYPE, w as HOLD_STATUS, x as isSettlementType, y as SETTLEMENT_TYPE_VALUES } from "./subscription.enums-95othr0i.mjs";
+import { a as InvalidStateTransitionError, c as ProviderCapabilityError, d as RevenueError, f as SettlementNotFoundError, g as WrongTransactionKindError, h as ValidationError, i as ConfigurationError, l as ProviderNotFoundError, m as TransactionNotFoundError, n as BankFeedImportError, o as PaymentIntentCreationError, p as SubscriptionNotFoundError, r as BankFeedProviderNotFoundError, s as PaymentVerificationError, t as AlreadyVerifiedError, u as RefundNotSupportedError } from "./errors-LYYg9wcs.mjs";
+import { BANK_FEED_STATE_MACHINE, HOLD_STATE_MACHINE, MANUAL_STATE_MACHINE, PAYMENT_FLOW_STATE_MACHINE, SETTLEMENT_STATE_MACHINE, SPLIT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, StateMachine, TRANSACTION_STATE_MACHINE, smFor } from "./core/state-machines.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-CNfQj92L.mjs";
 import { createRevenueRepositories } from "./repositories/create-repositories.mjs";
-import { a as PaymentResult, i as PaymentProvider, n as createProviderRegistry, o as RefundResult, r as PaymentIntent, s as WebhookEvent, t as ProviderRegistry } from "./registry-DhFMsSn5.mjs";
-import { D as InProcessRevenueBus, E as revenueEventDefinitions } from "./revenue-event-catalog-LqxPnsU_.mjs";
-import { a as PAYMENT_GATEWAY_TYPE_VALUES, c as isPaymentGatewayType, i as PAYMENT_GATEWAY_TYPE, l as isPaymentStatus, n as MONETIZATION_TYPE_VALUES, o as PAYMENT_STATUS, r as isMonetizationType, s as PAYMENT_STATUS_VALUES, t as MONETIZATION_TYPES } from "./monetization.enums-BtiU3t8o.mjs";
-import { _ as transactionListFilterSchema, a as paymentVerifySchema, c as settlementCreateSchema, d as subscriptionBaseSchema, f as subscriptionCreateSchema, g as transactionCreateSchema, h as transactionBaseSchema, i as paymentIntentSchema, l as settlementListFilterSchema, m as subscriptionUpdateSchema, n as escrowReleaseSchema, o as refundSchema, p as subscriptionListFilterSchema, r as splitRuleSchema, s as settlementBaseSchema, t as escrowHoldSchema, u as settlementUpdateSchema, v as transactionUpdateSchema } from "./escrow.schema-BBv9oVEW.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 createProviderRegistry, i as ProviderRegistry, n as BankFeedProviderRegistry, o as PaymentProvider, r as createBankFeedProviderRegistry, t as BankFeedProvider } from "./bank-feed-BlQeq2rK.mjs";
+import { M as revenueEventDefinitions, N as InProcessRevenueBus } from "./revenue-event-catalog-BvjNVnPd.mjs";
+import { a as PAYMENT_GATEWAY_TYPE_VALUES, c as isPaymentGatewayType, i as PAYMENT_GATEWAY_TYPE, l as isPaymentStatus, n as MONETIZATION_TYPE_VALUES, o as PAYMENT_STATUS, r as isMonetizationType, s as PAYMENT_STATUS_VALUES, t as MONETIZATION_TYPES } from "./monetization.enums-B9HBOecd.mjs";
+import { _ as transactionListFilterSchema, a as paymentVerifySchema, c as settlementCreateSchema, d as subscriptionBaseSchema, f as subscriptionCreateSchema, g as transactionCreateSchema, h as transactionBaseSchema, i as paymentIntentSchema, l as settlementListFilterSchema, m as subscriptionUpdateSchema, n as escrowReleaseSchema, o as refundSchema, p as subscriptionListFilterSchema, r as splitRuleSchema, s as settlementBaseSchema, t as escrowHoldSchema, u as settlementUpdateSchema, v as transactionUpdateSchema } from "./escrow.schema-C-b41z_G.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";
 import { PluginManager } from "./plugins/plugin.interface.mjs";
-import { customIdPlugin, multiTenantPlugin, prefixedId, softDeletePlugin } from "@classytic/mongokit";
-import { resolveTenantConfig } from "@classytic/primitives/tenant";
+import { batchOperationsPlugin, customIdPlugin, methodRegistryPlugin, multiTenantPlugin, prefixedId, softDeletePlugin } from "@classytic/mongokit";
+import { resolveTenantConfig } from "@classytic/repo-core/tenant";
 import mongoose, { Schema } from "mongoose";
 import { InvalidOutboxEventError, OutboxOwnershipError } from "@classytic/primitives/outbox";
 import { err, isErr, isOk, ok } from "@classytic/primitives/result";
 
 //#region src/models/transaction.schema.ts
+const NO_BANK_FEED_INDEXES = {
+	idempotentImport: false,
+	byAccount: false,
+	matchCandidates: false
+};
 function buildTransactionSchema(config) {
 	const fields = {
 		publicId: { type: String },
@@ -25,6 +31,13 @@ function buildTransactionSchema(config) {
 			type: String,
 			default: null
 		},
+		kind: {
+			type: String,
+			enum: TRANSACTION_KIND_VALUES,
+			default: TRANSACTION_KIND.PAYMENT_FLOW,
+			required: true,
+			index: true
+		},
 		type: {
 			type: String,
 			required: true
@@ -56,6 +69,9 @@ function buildTransactionSchema(config) {
 			default: 0
 		},
 		taxDetails: { type: Schema.Types.Mixed },
+		fxRate: { type: Number },
+		originalAmount: { type: Number },
+		originalCurrency: { type: String },
 		method: {
 			type: String,
 			required: true
@@ -64,11 +80,27 @@ function buildTransactionSchema(config) {
 			type: String,
 			default: "pending"
 		},
+		approvals: {
+			type: Schema.Types.Mixed,
+			default: null
+		},
 		gateway: { type: Schema.Types.Mixed },
 		paymentDetails: { type: Schema.Types.Mixed },
 		commission: { type: Schema.Types.Mixed },
 		splits: [{ type: Schema.Types.Mixed }],
 		hold: { type: Schema.Types.Mixed },
+		externalId: { type: String },
+		postedDate: { type: Date },
+		valueDate: { type: Date },
+		description: { type: String },
+		counterparty: { type: Schema.Types.Mixed },
+		reference: { type: String },
+		balanceAfter: { type: Number },
+		vendorCategory: { type: String },
+		bankAccountId: { type: String },
+		source: { type: String },
+		journalEntryRef: { type: Schema.Types.Mixed },
+		matching: { type: Schema.Types.Mixed },
 		sourceId: { type: String },
 		sourceModel: { type: String },
 		relatedTransactionId: {
@@ -103,6 +135,32 @@ function buildTransactionSchema(config) {
 		sourceId: 1,
 		sourceModel: 1
 	});
+	schema.index({
+		kind: 1,
+		status: 1,
+		createdAt: -1
+	});
+	schema.index({ relatedTransactionId: 1 }, { sparse: true });
+	const bfi = config.bankFeedIndexes ?? NO_BANK_FEED_INDEXES;
+	if (bfi.byAccount) schema.index({
+		bankAccountId: 1,
+		postedDate: -1
+	}, {
+		partialFilterExpression: { bankAccountId: { $type: "string" } },
+		name: "bank_feed_by_account"
+	});
+	if (bfi.matchCandidates) {
+		schema.index({
+			kind: 1,
+			amount: 1,
+			postedDate: -1
+		}, { name: "match_candidates_by_amount_date" });
+		schema.index({
+			kind: 1,
+			amount: 1,
+			createdAt: -1
+		}, { name: "match_candidates_by_amount_createdat" });
+	}
 	if (config.extraIndexes) for (const idx of config.extraIndexes) schema.index(idx.fields, idx.options);
 	return schema;
 }
@@ -151,6 +209,10 @@ function buildSubscriptionSchema(config) {
 		canceledAt: { type: Date },
 		cancelAt: { type: Date },
 		cancellationReason: { type: String },
+		approvals: {
+			type: Schema.Types.Mixed,
+			default: null
+		},
 		renewalTransactionId: {
 			type: Schema.Types.ObjectId,
 			ref: txnRef
@@ -207,6 +269,10 @@ function buildSettlementSchema(config) {
 			type: String,
 			default: "pending"
 		},
+		approvals: {
+			type: Schema.Types.Mixed,
+			default: null
+		},
 		payoutMethod: {
 			type: String,
 			required: true
@@ -282,7 +348,7 @@ function buildSettlementSchema(config) {
 * The field storage type follows `scope.fieldType` (`'objectId'` →
 * `Schema.Types.ObjectId` + `ref`, `'string'` → `String`). No hardcoding
 * here — callers must pass a `ResolvedTenantConfig` from
-* `@classytic/primitives/tenant` via `resolveTenantConfig(...)`.
+* `@classytic/repo-core/tenant` via `resolveTenantConfig(...)`.
 */
 function injectTenantField(schema, scope) {
 	schema.add({ [scope.tenantField]: {
@@ -325,7 +391,7 @@ var RevenueModelCollisionError = class extends Error {
 	}
 };
 function createRevenueModels(options) {
-	const { connection, scope, schemaOptions = {}, modules = {}, collectionPrefix, forceRecreate } = options;
+	const { connection, scope, schemaOptions = {}, modules = {}, collectionPrefix, forceRecreate, bankFeedIndexes } = options;
 	const prefix = collectionPrefix ?? "";
 	if (forceRecreate) {
 		for (const name of REVENUE_MODEL_NAMES) if (connection.models[name]) connection.deleteModel(name);
@@ -333,7 +399,8 @@ function createRevenueModels(options) {
 	const txnSchema = buildTransactionSchema({
 		scoped: scope.enabled,
 		extraFields: schemaOptions.transaction?.extraFields,
-		extraIndexes: schemaOptions.transaction?.extraIndexes
+		extraIndexes: schemaOptions.transaction?.extraIndexes,
+		...bankFeedIndexes ? { bankFeedIndexes } : {}
 	});
 	injectTenantField(txnSchema, scope);
 	txnSchema.index({ "gateway.sessionId": 1 }, { sparse: true });
@@ -349,6 +416,23 @@ function createRevenueModels(options) {
 			publicId: { $type: "string" }
 		}
 	});
+	if (bankFeedIndexes?.idempotentImport) if (scope.enabled && scope.strategy === "field") txnSchema.index({
+		[scope.tenantField]: 1,
+		bankAccountId: 1,
+		externalId: 1
+	}, {
+		unique: true,
+		partialFilterExpression: { externalId: { $type: "string" } },
+		name: "bank_feed_idempotent_import"
+	});
+	else txnSchema.index({
+		bankAccountId: 1,
+		externalId: 1
+	}, {
+		unique: true,
+		partialFilterExpression: { externalId: { $type: "string" } },
+		name: "bank_feed_idempotent_import"
+	});
 	const models = { Transaction: connection.model("Transaction", txnSchema, prefix + DEFAULT_COLLECTIONS.Transaction) };
 	if (modules.subscription !== false) {
 		const subSchema = buildSubscriptionSchema({
@@ -388,10 +472,23 @@ function createRevenueModels(options) {
 * See PACKAGE_RULES §13–§14.
 */
 async function createRevenue(config) {
+	const bankFeedRaw = config.modules?.bankFeed;
+	const bankFeedEnabled = bankFeedRaw === false ? false : typeof bankFeedRaw === "object" && bankFeedRaw !== null ? bankFeedRaw.enabled !== false : true;
+	const userIndexCfg = typeof bankFeedRaw === "object" && bankFeedRaw !== null ? bankFeedRaw.indexes : void 0;
+	const bankFeedIndexes = bankFeedEnabled ? {
+		idempotentImport: userIndexCfg?.idempotentImport ?? true,
+		byAccount: userIndexCfg?.byAccount ?? true,
+		matchCandidates: userIndexCfg?.matchCandidates ?? false
+	} : {
+		idempotentImport: false,
+		byAccount: false,
+		matchCandidates: false
+	};
 	const modules = {
 		subscription: config.modules?.subscription !== false,
 		escrow: config.modules?.escrow ?? false,
-		settlement: config.modules?.settlement ?? false
+		settlement: config.modules?.settlement ?? false,
+		bankFeed: bankFeedEnabled
 	};
 	const scope = resolveTenantConfig(config.scope);
 	const events = config.eventTransport ?? new InProcessRevenueBus({ logger: config.logger });
@@ -400,6 +497,7 @@ async function createRevenue(config) {
 		scope,
 		schemaOptions: config.schemaOptions,
 		modules,
+		bankFeedIndexes,
 		...config.collectionPrefix !== void 0 ? { collectionPrefix: config.collectionPrefix } : {},
 		...config.forceRecreate !== void 0 ? { forceRecreate: config.forceRecreate } : {}
 	});
@@ -424,16 +522,18 @@ async function createRevenue(config) {
 		return plugins;
 	};
 	const repositories = createRevenueRepositories(models, {
-		transaction: buildPlugins("txn"),
+		transaction: buildPlugins("txn", modules.bankFeed ? [methodRegistryPlugin(), batchOperationsPlugin()] : []),
 		subscription: buildPlugins("sub"),
 		settlement: buildPlugins("stl")
 	}, config.repositoryPlugins);
 	const providers = createProviderRegistry(config.providers ?? {}, config.defaultCurrency);
+	const bankFeedProviders = createBankFeedProviderRegistry(config.bankFeedProviders ?? {});
 	const commission = typeof config.modules?.commission === "object" ? config.modules.commission : config.commission;
 	repositories.transaction.inject({
 		events,
 		outbox: config.outbox,
 		providers,
+		bankFeedProviders,
 		bridges: config.bridges ?? {},
 		commission,
 		defaultCurrency: config.defaultCurrency,
@@ -460,6 +560,7 @@ async function createRevenue(config) {
 		models,
 		repositories,
 		providers,
+		bankFeedProviders,
 		events,
 		async syncIndexes() {
 			await Promise.all(Object.values(models).filter(Boolean).map((m) => m.createIndexes()));
@@ -471,4 +572,26 @@ async function createRevenue(config) {
 }
 
 //#endregion
-export { AlreadyVerifiedError, CURRENCIES, ConfigurationError, CurrencyMismatchError, HOLD_REASON, HOLD_REASON_VALUES, HOLD_STATE_MACHINE, HOLD_STATUS, HOLD_STATUS_VALUES, InProcessRevenueBus, InvalidOutboxEventError, InvalidStateTransitionError, LIBRARY_CATEGORIES, LIBRARY_CATEGORY_VALUES, MINOR_UNIT_FACTOR, MONETIZATION_TYPES, MONETIZATION_TYPE_VALUES, OutboxOwnershipError, PAYMENT_GATEWAY_TYPE, PAYMENT_GATEWAY_TYPE_VALUES, PAYMENT_STATUS, PAYMENT_STATUS_VALUES, PAYOUT_METHOD, PAYOUT_METHOD_VALUES, PLAN_KEYS, PLAN_KEY_VALUES, PaymentIntent, PaymentIntentCreationError, PaymentProvider, PaymentResult, PaymentVerificationError, PluginManager, ProviderCapabilityError, ProviderNotFoundError, ProviderRegistry, RELEASE_REASON, RELEASE_REASON_VALUES, REVENUE_EVENTS, RefundNotSupportedError, RefundResult, RevenueError, SETTLEMENT_STATE_MACHINE, SETTLEMENT_STATUS, SETTLEMENT_STATUS_VALUES, SETTLEMENT_TYPE, SETTLEMENT_TYPE_VALUES, SPLIT_STATE_MACHINE, SPLIT_STATUS, SPLIT_STATUS_VALUES, SPLIT_TYPE, SPLIT_TYPE_VALUES, SUBSCRIPTION_STATE_MACHINE, SUBSCRIPTION_STATUS, SUBSCRIPTION_STATUS_VALUES, SettlementNotFoundError, SettlementRepository, StateMachine, SubscriptionNotFoundError, SubscriptionRepository, TRANSACTION_FLOW, TRANSACTION_FLOW_VALUES, TRANSACTION_STATE_MACHINE, TRANSACTION_STATUS, TRANSACTION_STATUS_VALUES, TransactionNotFoundError, TransactionRepository, ValidationError, WebhookEvent, absMoney, addMoney, appendAuditEvent, calculateCommission, calculateOrganizationPayout, calculateSplits, calculateTax, compareMoney, createEvent, createProviderRegistry, createRevenue, equalsMoney, err, escrowHoldSchema, escrowReleaseSchema, fromMajor, fromSmallestUnit, getAuditTrail, getLastStateChange, getTaxType, isCurrencyCode, isErr, isHoldReason, isHoldStatus, isLibraryCategory, isMonetizationType, isMoney, isNegativeMoney, isOk, isPaymentGatewayType, isPaymentStatus, isPayoutMethod, isPlanKey, isPositiveMoney, isReleaseReason, isSettlementStatus, isSettlementType, isSplitStatus, isSplitType, isSubscriptionStatus, isTransactionFlow, isTransactionStatus, isZeroMoney, minorUnitFactor, money, multiplyMoney, negateMoney, ok, paymentIntentSchema, paymentVerifySchema, refundSchema, revenueEventDefinitions, reverseCommission, reverseTax, settlementBaseSchema, settlementCreateSchema, settlementListFilterSchema, settlementUpdateSchema, splitRuleSchema, subscriptionBaseSchema, subscriptionCreateSchema, subscriptionListFilterSchema, subscriptionUpdateSchema, subtractMoney, sumMoney, toCurrencyCode, toMajor, toSmallestUnit, transactionBaseSchema, transactionCreateSchema, transactionListFilterSchema, transactionUpdateSchema, validateTaxCalculation };
+//#region src/events/outbox-store.ts
+var MemoryOutboxStore = class {
+	events = [];
+	async save(event, _options) {
+		this.events.push({ event });
+	}
+	async getPending(limit) {
+		return this.events.filter((e) => !e.acknowledgedAt).slice(0, limit).map((e) => e.event);
+	}
+	async acknowledge(eventId, _options) {
+		const entry = this.events.find((e) => e.event.meta.id === eventId);
+		if (entry) entry.acknowledgedAt = /* @__PURE__ */ new Date();
+	}
+	async purge(olderThanMs) {
+		const cutoff = Date.now() - olderThanMs;
+		const before = this.events.length;
+		this.events = this.events.filter((e) => !e.acknowledgedAt || e.acknowledgedAt.getTime() >= cutoff);
+		return before - this.events.length;
+	}
+};
+
+//#endregion
+export { AlreadyVerifiedError, BANK_FEED_SOURCE, BANK_FEED_SOURCE_VALUES, BANK_FEED_STATE_MACHINE, BANK_FEED_STATUS, BANK_FEED_STATUS_VALUES, BankFeedImportError, BankFeedProvider, BankFeedProviderNotFoundError, BankFeedProviderRegistry, CURRENCIES, ConfigurationError, CurrencyMismatchError, HOLD_REASON, HOLD_REASON_VALUES, HOLD_STATE_MACHINE, HOLD_STATUS, HOLD_STATUS_VALUES, InProcessRevenueBus, InvalidOutboxEventError, InvalidStateTransitionError, LIBRARY_CATEGORIES, LIBRARY_CATEGORY_VALUES, MANUAL_STATE_MACHINE, MINOR_UNIT_FACTOR, MONETIZATION_TYPES, MONETIZATION_TYPE_VALUES, MemoryOutboxStore, OutboxOwnershipError, PAYMENT_FLOW_STATE_MACHINE, PAYMENT_GATEWAY_TYPE, PAYMENT_GATEWAY_TYPE_VALUES, PAYMENT_STATUS, PAYMENT_STATUS_VALUES, PAYOUT_METHOD, PAYOUT_METHOD_VALUES, PLAN_KEYS, PLAN_KEY_VALUES, PaymentIntentCreationError, PaymentProvider, PaymentVerificationError, PluginManager, ProviderCapabilityError, ProviderNotFoundError, ProviderRegistry, RELEASE_REASON, RELEASE_REASON_VALUES, REVENUE_EVENTS, RefundNotSupportedError, RevenueError, SETTLEMENT_STATE_MACHINE, SETTLEMENT_STATUS, SETTLEMENT_STATUS_VALUES, SETTLEMENT_TYPE, SETTLEMENT_TYPE_VALUES, SPLIT_STATE_MACHINE, SPLIT_STATUS, SPLIT_STATUS_VALUES, SPLIT_TYPE, SPLIT_TYPE_VALUES, SUBSCRIPTION_STATE_MACHINE, SUBSCRIPTION_STATUS, SUBSCRIPTION_STATUS_VALUES, SettlementNotFoundError, SettlementRepository, StateMachine, SubscriptionNotFoundError, SubscriptionRepository, TRANSACTION_FLOW, TRANSACTION_FLOW_VALUES, TRANSACTION_KIND, TRANSACTION_KIND_VALUES, TRANSACTION_STATE_MACHINE, TRANSACTION_STATUS, TRANSACTION_STATUS_VALUES, TransactionNotFoundError, TransactionRepository, ValidationError, WrongTransactionKindError, absMoney, addMoney, appendAuditEvent, calculateCommission, calculateOrganizationPayout, calculateSplits, calculateTax, compareMoney, createBankFeedProviderRegistry, createEvent, createProviderRegistry, createRevenue, equalsMoney, err, escrowHoldSchema, escrowReleaseSchema, fromMajor, fromSmallestUnit, getAuditTrail, getLastStateChange, getTaxType, initialStatusFor, isBankFeedSource, isBankFeedStatus, isCurrencyCode, isErr, isHoldReason, isHoldStatus, isLibraryCategory, isMonetizationType, isMoney, isNegativeMoney, isOk, isPaymentGatewayType, isPaymentStatus, isPayoutMethod, isPlanKey, isPositiveMoney, isReleaseReason, isSettlementStatus, isSettlementType, isSplitStatus, isSplitType, isStatusValidForKind, isSubscriptionStatus, isTransactionFlow, isTransactionKind, isTransactionStatus, isZeroMoney, minorUnitFactor, money, multiplyMoney, negateMoney, ok, paymentIntentSchema, paymentVerifySchema, refundSchema, revenueEventDefinitions, reverseCommission, reverseTax, settlementBaseSchema, settlementCreateSchema, settlementListFilterSchema, settlementUpdateSchema, smFor, splitRuleSchema, statusesForKind, subscriptionBaseSchema, subscriptionCreateSchema, subscriptionListFilterSchema, subscriptionUpdateSchema, subtractMoney, sumMoney, toCurrencyCode, toMajor, toSmallestUnit, transactionBaseSchema, transactionCreateSchema, transactionListFilterSchema, transactionUpdateSchema, validateTaxCalculation };

package/dist/providers/index.d.mts

@@ -1,2 +1,2 @@
-import { a as PaymentIntentData, c as PaymentResultData, d as RefundResultData, f as WebhookEvent, i as PaymentIntent, l as ProviderCapabilities, n as createProviderRegistry, o as PaymentProvider, p as WebhookEventData, r as CreateIntentParams, s as PaymentResult, t as ProviderRegistry, u as RefundResult } from "../registry-SvIGPAx_.mjs";
-export { type CreateIntentParams, PaymentIntent, type PaymentIntentData, PaymentProvider, PaymentResult, type PaymentResultData, type ProviderCapabilities, ProviderRegistry, RefundResult, type RefundResultData, WebhookEvent, type WebhookEventData, createProviderRegistry };
+import { a as BankFeedProviderRegistry, c as ParseUploadParams, d as PaymentProvider, i as BankFeedProviderCapabilities, l as ParseUploadResult, n as createProviderRegistry, o as FetchTransactionsParams, r as BankFeedProvider, s as FetchTransactionsResult, t as ProviderRegistry, u as createBankFeedProviderRegistry } from "../registry-h8sasoLh.mjs";
+export { BankFeedProvider, type BankFeedProviderCapabilities, BankFeedProviderRegistry, type FetchTransactionsParams, type FetchTransactionsResult, type ParseUploadParams, type ParseUploadResult, PaymentProvider, ProviderRegistry, createBankFeedProviderRegistry, createProviderRegistry };

package/dist/providers/index.mjs

@@ -1,3 +1,3 @@
-import { a as PaymentResult, i as PaymentProvider, n as createProviderRegistry, o as RefundResult, r as PaymentIntent, s as WebhookEvent, t as ProviderRegistry } from "../registry-DhFMsSn5.mjs";
+import { a as createProviderRegistry, i as ProviderRegistry, n as BankFeedProviderRegistry, o as PaymentProvider, r as createBankFeedProviderRegistry, t as BankFeedProvider } from "../bank-feed-BlQeq2rK.mjs";
 
-export { PaymentIntent, PaymentProvider, PaymentResult, ProviderRegistry, RefundResult, WebhookEvent, createProviderRegistry };
+export { BankFeedProvider, BankFeedProviderRegistry, PaymentProvider, ProviderRegistry, createBankFeedProviderRegistry, createProviderRegistry };

package/dist/registry-h8sasoLh.d.mts

@@ -0,0 +1,145 @@
+import { a as BankFeedSourceValue } from "./bank-feed.enums-BadqNJTC.mjs";
+import { CreateIntentParams, PaymentIntent, PaymentResult, ProviderCapabilities, RefundResult, WebhookEvent } from "@classytic/primitives/payment-gateway";
+import { BankStatement, BankTransaction } from "@classytic/primitives/bank-transaction";
+
+//#region src/providers/base.d.ts
+/**
+ * Abstract `PaymentProvider` — the contract revenue's repositories
+ * consume. Provider implementations may extend this for the default
+ * config plumbing, or just satisfy the structural shape.
+ */
+declare abstract class PaymentProvider {
+  readonly config: Record<string, unknown>;
+  readonly name: string;
+  private _defaultCurrency;
+  constructor(config?: Record<string, unknown>);
+  get defaultCurrency(): string;
+  setDefaultCurrency(currency: string): void;
+  abstract createIntent(params: CreateIntentParams): Promise<PaymentIntent>;
+  abstract verifyPayment(intentId: string): Promise<PaymentResult>;
+  abstract getStatus(intentId: string): Promise<PaymentResult>;
+  abstract refund(paymentId: string, amount?: number | null, options?: {
+    reason?: string;
+  }): Promise<RefundResult>;
+  abstract handleWebhook(payload: unknown, headers?: Record<string, string>): Promise<WebhookEvent>;
+  /**
+   * Default: accept all signatures (manual / dev provider). Real
+   * gateways MUST override with HMAC / timing-safe verification.
+   */
+  verifyWebhookSignature(_payload: unknown, _signature: string): boolean;
+  getCapabilities(): ProviderCapabilities;
+}
+//#endregion
+//#region src/providers/bank-feed.d.ts
+interface BankFeedProviderCapabilities {
+  /** Supports continuous sync (Plaid, QBO CDC, Xero CDC). */
+  supportsSync: boolean;
+  /** Supports file upload parsing (OFX, CAMT.053, MT940, CSV, IIF). */
+  supportsUpload: boolean;
+  /** Provider may report retracted entries (Plaid `removed[]`, OFX correction). */
+  supportsRemovals: boolean;
+  /** Cursor-resumable — `fetchTransactions` returns a `nextCursor`. */
+  cursorBased: boolean;
+  /** Multi-account in a single sync call. */
+  multiAccount: boolean;
+}
+interface FetchTransactionsParams {
+  /** Resumption token from a previous call (Plaid cursor, QBO `LastUpdatedTime`, …). */
+  cursor?: string | undefined;
+  /** Account scope. May be undefined for providers that fetch all accounts. */
+  bankAccountId?: string | undefined;
+  /** Optional date floor — supplements cursor-based drains. */
+  from?: Date | undefined;
+  /** Optional date ceiling. */
+  to?: Date | undefined;
+  /** Provider-specific knobs. */
+  options?: Record<string, unknown> | undefined;
+}
+interface FetchTransactionsResult {
+  /** Newly added or updated rows. */
+  transactions: BankTransaction[];
+  /** Vendor-stable IDs of rows the upstream feed has retracted. */
+  removed?: Array<{
+    externalId: string;
+    bankAccountId?: string;
+  }>;
+  /** Resumption cursor for the next call. */
+  nextCursor?: string;
+  /** True when more pages are available — driver may stop calling when false. */
+  hasMore?: boolean;
+  /** Provider raw response for audit. Optional. */
+  raw?: unknown;
+}
+interface ParseUploadParams {
+  /** Raw upload bytes / string. */
+  buffer: Buffer | string | Uint8Array;
+  /** Format hint — providers MAY auto-detect when absent. */
+  format?: BankFeedSourceValue;
+  /** Account scope to stamp on every parsed row (when the file omits it). */
+  bankAccountId?: string;
+  /** Format-specific quirks (e.g. `'chase' | 'boa' | 'lenient'`). */
+  options?: Record<string, unknown>;
+}
+interface ParseUploadResult {
+  /** Statement-level metadata (account, period, balances). */
+  statements: BankStatement[];
+  /** Flat list of all rows across all statements — convenience for `import()`. */
+  transactions: BankTransaction[];
+  /** Per-row parse errors that didn't abort the file. */
+  warnings: Array<{
+    line?: number;
+    reason: string;
+  }>;
+}
+/**
+ * Bank-feed provider — implement one method or both depending on the
+ * upstream's capabilities. Mirrors the optional-method pattern that
+ * works well across PaymentProvider's gateway plurality.
+ */
+declare abstract class BankFeedProvider {
+  readonly config: Record<string, unknown>;
+  readonly name: string;
+  constructor(name: string, config?: Record<string, unknown>);
+  /**
+   * Fetch a batch of transactions. Cursor-based providers (Plaid)
+   * return `nextCursor` for the next call; date-range providers
+   * (older QBO Reports API) ignore cursor and use `from` / `to`.
+   * Throws if the provider does not support sync.
+   */
+  fetchTransactions?(_params: FetchTransactionsParams): Promise<FetchTransactionsResult>;
+  /**
+   * Parse a file upload (OFX / CAMT.053 / MT940 / CSV / IIF). The
+   * canonical implementation delegates to `@classytic/fin-io`. Throws
+   * if the provider does not support uploads.
+   */
+  parseUpload?(_params: ParseUploadParams): Promise<ParseUploadResult>;
+  /**
+   * Async drain — yields one batch per call until the upstream is
+   * caught up. Default implementation pulls `fetchTransactions` in a
+   * loop; providers can override for more efficient pagination
+   * (e.g. SSE / long-poll) or to interleave `removed[]` correctly.
+   */
+  drain(params?: FetchTransactionsParams): AsyncGenerator<FetchTransactionsResult>;
+  abstract getCapabilities(): BankFeedProviderCapabilities;
+}
+declare class BankFeedProviderRegistry {
+  private providers;
+  register(name: string, provider: BankFeedProvider): void;
+  get(name: string): BankFeedProvider;
+  has(name: string): boolean;
+  list(): string[];
+}
+declare function createBankFeedProviderRegistry(providers?: Record<string, BankFeedProvider>): BankFeedProviderRegistry;
+//#endregion
+//#region src/providers/registry.d.ts
+declare class ProviderRegistry {
+  private providers;
+  register(name: string, provider: PaymentProvider): void;
+  get(name: string): PaymentProvider;
+  has(name: string): boolean;
+  list(): string[];
+  setDefaultCurrency(currency: string): void;
+}
+declare function createProviderRegistry(providers?: Record<string, PaymentProvider>, defaultCurrency?: string): ProviderRegistry;
+//#endregion
+export { BankFeedProviderRegistry as a, ParseUploadParams as c, PaymentProvider as d, BankFeedProviderCapabilities as i, ParseUploadResult as l, createProviderRegistry as n, FetchTransactionsParams as o, BankFeedProvider as r, FetchTransactionsResult as s, ProviderRegistry as t, createBankFeedProviderRegistry as u };

package/dist/repositories/create-repositories.d.mts

@@ -1,4 +1,4 @@
-import { a as SettlementRepository, c as RevenueModels, o as SubscriptionRepository, s as TransactionRepository } from "../engine-types-CcjIb4Fy.mjs";
+import { c as SubscriptionRepository, l as TransactionRepository, s as SettlementRepository, u as RevenueModels } from "../engine-types-Jctrbasz.mjs";
 import { PluginType } from "@classytic/mongokit";
 
 //#region src/repositories/create-repositories.d.ts

package/dist/repositories/create-repositories.mjs

@@ -1,4 +1,4 @@
-import { n as SubscriptionRepository, r as TransactionRepository, t as SettlementRepository } from "../settlement.repository-DHIPx5S4.mjs";
+import { n as SubscriptionRepository, r as TransactionRepository, t as SettlementRepository } from "../settlement.repository-BAdc9qGl.mjs";
 
 //#region src/repositories/create-repositories.ts
 function createRevenueRepositories(models, builtInPlugins, hostPlugins = {}) {

package/dist/{revenue-bridges-sdlrR85c.d.mts → revenue-bridges-BtkWFsJu.d.mts}

@@ -1,10 +1,116 @@
-import { t as RevenueContext } from "./context-DRqSeTPM.mjs";
+import { t as RevenueContext } from "./context-pjP1QeE3.mjs";
 
 //#region src/bridges/ledger.bridge.d.ts
+/**
+ * LedgerBridge — host-implemented contract for posting revenue events
+ * into a general-ledger / accounting system.
+ *
+ * Revenue does NOT import any ledger package directly (PACKAGE_RULES §23).
+ * The host wires this bridge once at engine creation time; revenue's repo
+ * verbs call the relevant hook after each state transition. Every method
+ * is optional — features degrade gracefully when omitted.
+ *
+ * Two phases of hooks:
+ *
+ *   1. **Payment-flow hooks** (`onPaymentVerified`, `onRefundProcessed`,
+ *      `onSettlementCompleted`) — the original Stripe-style integration.
+ *      Fired when a gateway transaction reaches a terminal accounting
+ *      moment.
+ *
+ *   2. **Bank-feed hooks** (`onTransactionImported`, `onTransactionMatched`,
+ *      `onTransactionJournalized`, `onTransactionRejected`,
+ *      `onTransactionUnmatched`, `onTransactionRemovedByFeed`) — added
+ *      in 3.0. Fired during the bank-feed lifecycle so the host can post
+ *      JEs at match time, recall them on un-match, and chain
+ *      `journalize()` after a successful JE post.
+ *
+ * The canonical wiring for `onTransactionMatched` is:
+ *
+ * ```ts
+ * const ledgerBridge: LedgerBridge = {
+ *   async onTransactionMatched(txn, mapping, ctx) {
+ *     const report = await wireImport({
+ *       source: [{ txn, mapping }],
+ *       mapper: bankToJournalEntryMapper(mapping),
+ *       journalEntries: ledger.repositories.journalEntry,
+ *       context: { organizationId: ctx.organizationId },
+ *     }).run();
+ *     if (report.ok && report.entries[0]) {
+ *       await revenue.repositories.transaction.journalize(
+ *         String(txn._id),
+ *         { journalEntryRef: { type: 'JournalEntry', id: report.entries[0].id } },
+ *         ctx,
+ *       );
+ *     }
+ *   },
+ * };
+ * ```
+ */
 interface LedgerBridge {
+  /** Fired when a gateway transaction reaches `verified` status. */
   onPaymentVerified?(transaction: Record<string, unknown>, ctx: RevenueContext): Promise<void>;
+  /** Fired after a refund posts (the new outflow row + the updated original). */
   onRefundProcessed?(original: Record<string, unknown>, refund: Record<string, unknown>, ctx: RevenueContext): Promise<void>;
+  /** Fired when a settlement record reaches `completed`. */
   onSettlementCompleted?(settlement: Record<string, unknown>, ctx: RevenueContext): Promise<void>;
+  /**
+   * Fired once per row inserted by `import()`. Use this for live preview
+   * dashboards or downstream materialized views — most production hosts
+   * leave this unimplemented and act on the per-batch `events.publish`
+   * stream instead.
+   */
+  onTransactionImported?(transaction: Record<string, unknown>, ctx: RevenueContext): Promise<void>;
+  /**
+   * Fired after `match()` succeeds. The host's typical implementation
+   * posts a journal entry via the host's ledger package (e.g. arc's
+   * `wireImport` over `@classytic/ledger`'s `journalEntry` repository),
+   * then calls `revenue.repositories.transaction.journalize(id, …)` so
+   * the row transitions `matched → journalized`.
+   */
+  onTransactionMatched?(transaction: Record<string, unknown>, mapping: {
+    debitAccount?: string;
+    creditAccount?: string;
+    notes?: string;
+  }, ctx: RevenueContext): Promise<void>;
+  /**
+   * Fired after `unmatch()` succeeds. Hosts can void / reverse the
+   * journal entry created at match time. Pass the prior
+   * `journalEntryRef` so reversal is keyed correctly.
+   */
+  onTransactionUnmatched?(transaction: Record<string, unknown>, priorJournalEntryRef: {
+    type: string;
+    id: string;
+  } | undefined, ctx: RevenueContext): Promise<void>;
+  /**
+   * Fired after `journalize()` stamps `journalEntryRef` on the row.
+   * Most hosts are passive on this hook (the JE was created in
+   * `onTransactionMatched`); useful for audit logs and analytics.
+   */
+  onTransactionJournalized?(transaction: Record<string, unknown>, journalEntryRef: {
+    type: string;
+    id: string;
+  }, ctx: RevenueContext): Promise<void>;
+  /**
+   * Fired after `reject()` — operator skip on a duplicate / non-cash
+   * import. Hosts typically log for audit.
+   *
+   * **JE reversal contract.** `reject()` is legal from `'matched'` as
+   * well as `'imported'`. If your `onTransactionMatched` posted a JE
+   * synchronously (the typical bridge implementation), the JE must be
+   * reversed here — revenue itself never calls into ledger and has no
+   * way to know one exists. Idempotency is the bridge's responsibility:
+   * a reject on a never-journalized row should be a no-op for ledger,
+   * a reject after journalize should void the JE keyed off
+   * `transaction.matching` or whatever the host stamped at match time.
+   */
+  onTransactionRejected?(transaction: Record<string, unknown>, reason: string, ctx: RevenueContext): Promise<void>;
+  /**
+   * Fired when the upstream feed retracts a row (Plaid `removed[]`,
+   * OFX correction, QBO CDC delete). The transaction is soft-deleted
+   * before this hook runs. If a JE was already posted, the host
+   * should reverse it.
+   */
+  onTransactionRemovedByFeed?(transaction: Record<string, unknown>, ctx: RevenueContext): Promise<void>;
 }
 //#endregion
 //#region src/bridges/tax.bridge.d.ts