@classytic/revenue 2.0.1 → 2.1.3

package/CHANGELOG.md

@@ -3,6 +3,72 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.1] — multi-tenant scope correctness across all repos
+
+**Fix.** `SubscriptionRepository` and `SettlementRepository` lifecycle verbs
+were calling internal `getById` / `update` / `getAll` without threading
+`ctx.organizationId` into the mongokit options bag. The moment a host
+enabled `multiTenantPlugin` (the recommended default — see PACKAGE_RULES
+§9), every verb threw `Missing 'organizationId' in context for 'getById'`
+mid-flow and the lifecycle was unusable.
+
+Affected verbs (all now threaded correctly):
+
+- `SubscriptionRepository.{activate,cancel,pause,resume}` — every internal
+  `getById` and `update` now forwards `ctx`.
+- `SettlementRepository.{schedule,processPending,complete,fail}` — every
+  internal `getById`, `getAll`, `update` now forwards `ctx`.
+
+**Refactor.** Introduces `RevenueRepositoryBase<TDoc, TDeps>` (abstract;
+internal — not exported) consolidating the two cross-cutting concerns
+that were previously hand-rolled in three places:
+
+- `protected optsFromCtx(ctx, extra?)` — thin adapter over mongokit's
+  canonical `repoOptionsFromCtx` extractor, plus revenue's `_bypassTenant`
+  flag for platform-admin cross-org reads. **Adding a new canonical context
+  field is now a single edit in `repo-options.ts` upstream, not three.**
+- `protected dispatch(event, ctx)` — outbox-save (session-bound when
+  `ctx.session` is present) → transport-publish, with isolated try/catch
+  on each step (PACKAGE_RULES P8 / §5.5).
+
+`TransactionRepository`, `SubscriptionRepository`, `SettlementRepository`
+all extend the base. `BaseRevenueRepoDeps` (the shared `events` / `outbox`
+/ `logger` trio) is now the canonical superset every per-repo `Deps`
+interface extends.
+
+### Added
+
+- **`tests/scenarios/subscription-tenancy.scenario.test.ts`** — 6 tests
+  proving each lifecycle verb works under `scope: { enabled, required }`,
+  cross-tenant access is rejected with `SubscriptionNotFoundError`, and
+  `multiTenantPlugin` is wired (canary: omitting ctx throws
+  `Missing organizationId`).
+- **`tests/scenarios/settlement-tenancy.scenario.test.ts`** — 5 tests for
+  the same matrix on settlements: schedule, processPending, complete, fail,
+  cross-tenant rejection.
+
+### Internal
+
+- `RevenueRepositoryBase` is unexported on purpose — kept private to
+  the package. Adding a new repo means subclassing it; consumers stay
+  on the existing engine factory surface (`createRevenue(...)`).
+- No public API change. Engine factory, repo method signatures, and
+  exported types are all byte-stable.
+
+### Migration
+
+None — this is a behavioural fix. If you were running 2.1.0 with
+`scope: false` as a workaround for the lifecycle bugs, you can now turn
+scope back on. Recommended config:
+
+```ts
+await createRevenue({
+  connection: mongoose.connection,
+  scope: { enabled: true, fieldType: 'objectId', required: true },
+  // ...
+});
+```
+
 ## [2.0.0] — major rewrite
 
 Payment lifecycle engine refactored around unified transactions, an

package/README.md

@@ -53,25 +53,48 @@ const refundTxn = await revenue.repositories.transaction.refund(
 ```
 createRevenue(config) --> RevenueEngine
   |
-  |-- repositories.transaction       extends mongokit Repository
-  |     getAll, getById, getByQuery, create, update, delete, count  (inherited)
+  |-- repositories.transaction      extends RevenueRepositoryBase
+  |     CRUD inherited (mongokit Repository)
   |     createPaymentIntent, verify, refund, handleWebhook          (domain verbs)
   |     hold, release, split                                        (escrow verbs)
+  |     import, match, unmatch, journalize, reject, removeByFeed    (bank-feed verbs)
   |
-  |-- repositories.subscription      extends mongokit Repository
-  |     getAll, getById, create, update, delete, count              (inherited)
+  |-- repositories.subscription     extends RevenueRepositoryBase
+  |     CRUD inherited
   |     activate, cancel, pause, resume                             (domain verbs)
   |
-  |-- repositories.settlement        extends mongokit Repository
-  |     getAll, getById, create, update, delete, count              (inherited)
+  |-- repositories.settlement       extends RevenueRepositoryBase
+  |     CRUD inherited
   |     schedule, processPending, complete, fail                    (domain verbs)
   |
-  |-- providers                      ProviderRegistry
-  |-- events                         RevenueEventTransport (Arc-compatible)
-  |-- models                         Mongoose models (for Arc adapter)
+  |-- providers                     ProviderRegistry
+  |-- events                        RevenueEventTransport (Arc-compatible)
+  |-- models                        Mongoose models (for Arc adapter)
+
+
+      RevenueRepositoryBase (internal)
+        |
+        |-- extends mongokit Repository<TDoc>
+        |-- protected optsFromCtx(ctx, extra?)   threads RevenueContext into mongokit
+        |                                        options bag (uses repoOptionsFromCtx;
+        |                                        forwards organizationId, userId,
+        |                                        session, requestId + _bypassTenant)
+        |-- protected dispatch(event, ctx)       outbox.save (session-bound) →
+        |                                        events.publish (PACKAGE_RULES P8)
+        \-- protected deps: BaseRevenueRepoDeps  events / outbox? / logger?
 ```
 
-Repositories extend mongokit `Repository`. CRUD + pagination + query is inherited. Domain verbs contain real business logic (state machine transitions, provider calls, event emission). No service layer. No proxy methods.
+**Three repos. One scope-threading helper. One dispatch helper.** Every
+domain verb routes its mongokit calls through `optsFromCtx(ctx)` so
+multi-tenant scope, audit attribution, and transaction sessions land
+on every read/write without per-method boilerplate. Every domain event
+goes through `dispatch(event, ctx)` so outbox and transport semantics
+stay consistent across the package.
+
+CRUD, pagination, querying, and policy hooks come from
+[`@classytic/mongokit`](https://www.npmjs.com/package/@classytic/mongokit).
+Domain verbs contain real business logic (state machine transitions,
+provider calls, event emission). No service layer. No proxy methods.
 
 ## RevenueConfig
 

package/dist/bank-feed-BlQeq2rK.mjs

@@ -0,0 +1,133 @@
+import { l as ProviderNotFoundError } from "./errors-LYYg9wcs.mjs";
+
+//#region src/providers/base.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.
+*/
+var PaymentProvider = class {
+	config;
+	name;
+	_defaultCurrency = "USD";
+	constructor(config = {}) {
+		this.config = config;
+		this.name = "base";
+		if (config.defaultCurrency && typeof config.defaultCurrency === "string") this._defaultCurrency = config.defaultCurrency;
+	}
+	get defaultCurrency() {
+		return this._defaultCurrency;
+	}
+	setDefaultCurrency(currency) {
+		this._defaultCurrency = currency;
+	}
+	/**
+	* Default: accept all signatures (manual / dev provider). Real
+	* gateways MUST override with HMAC / timing-safe verification.
+	*/
+	verifyWebhookSignature(_payload, _signature) {
+		return true;
+	}
+	getCapabilities() {
+		return {
+			supportsWebhooks: false,
+			supportsRefunds: false,
+			supportsPartialRefunds: false,
+			requiresManualVerification: true
+		};
+	}
+};
+
+//#endregion
+//#region src/providers/registry.ts
+var ProviderRegistry = class {
+	providers = /* @__PURE__ */ new Map();
+	register(name, provider) {
+		this.providers.set(name, provider);
+	}
+	get(name) {
+		const provider = this.providers.get(name);
+		if (!provider) throw new ProviderNotFoundError(name);
+		return provider;
+	}
+	has(name) {
+		return this.providers.has(name);
+	}
+	list() {
+		return Array.from(this.providers.keys());
+	}
+	setDefaultCurrency(currency) {
+		for (const provider of this.providers.values()) provider.setDefaultCurrency(currency);
+	}
+};
+function createProviderRegistry(providers = {}, defaultCurrency) {
+	const registry = new ProviderRegistry();
+	for (const [name, provider] of Object.entries(providers)) {
+		if (defaultCurrency) provider.setDefaultCurrency(defaultCurrency);
+		registry.register(name, provider);
+	}
+	return registry;
+}
+
+//#endregion
+//#region src/providers/bank-feed.ts
+/**
+* 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.
+*/
+var BankFeedProvider = class {
+	config;
+	name;
+	constructor(name, config = {}) {
+		this.name = name;
+		this.config = config;
+	}
+	/**
+	* 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.
+	*/
+	async *drain(params = {}) {
+		if (!this.fetchTransactions) throw new Error(`Provider ${this.name} does not support fetchTransactions()`);
+		let cursor = params.cursor;
+		const MAX_PAGES = 1e4;
+		for (let i = 0; i < MAX_PAGES; i++) {
+			const result = await this.fetchTransactions({
+				...params,
+				cursor
+			});
+			yield result;
+			const tooLittle = result.transactions.length === 0 && (result.removed?.length ?? 0) === 0;
+			if (result.hasMore === false || tooLittle) return;
+			if (!result.nextCursor || result.nextCursor === cursor) return;
+			cursor = result.nextCursor;
+		}
+	}
+};
+var BankFeedProviderRegistry = class {
+	providers = /* @__PURE__ */ new Map();
+	register(name, provider) {
+		this.providers.set(name, provider);
+	}
+	get(name) {
+		const provider = this.providers.get(name);
+		if (!provider) throw new ProviderNotFoundError(name);
+		return provider;
+	}
+	has(name) {
+		return this.providers.has(name);
+	}
+	list() {
+		return Array.from(this.providers.keys());
+	}
+};
+function createBankFeedProviderRegistry(providers = {}) {
+	const registry = new BankFeedProviderRegistry();
+	for (const [name, provider] of Object.entries(providers)) registry.register(name, provider);
+	return registry;
+}
+
+//#endregion
+export { createProviderRegistry as a, ProviderRegistry as i, BankFeedProviderRegistry as n, PaymentProvider as o, createBankFeedProviderRegistry as r, BankFeedProvider as t };

package/dist/bank-feed.enums-BadqNJTC.d.mts

@@ -0,0 +1,118 @@
+//#region src/enums/transaction.enums.d.ts
+declare const TRANSACTION_FLOW: {
+  readonly INFLOW: "inflow";
+  readonly OUTFLOW: "outflow";
+};
+type TransactionFlow = typeof TRANSACTION_FLOW;
+type TransactionFlowValue = TransactionFlow[keyof TransactionFlow];
+declare const TRANSACTION_FLOW_VALUES: TransactionFlowValue[];
+declare const TRANSACTION_STATUS: {
+  readonly PENDING: "pending";
+  readonly PAYMENT_INITIATED: "payment_initiated";
+  readonly PROCESSING: "processing";
+  readonly REQUIRES_ACTION: "requires_action";
+  readonly VERIFIED: "verified";
+  readonly COMPLETED: "completed";
+  readonly FAILED: "failed";
+  readonly CANCELLED: "cancelled";
+  readonly EXPIRED: "expired";
+  readonly REFUNDED: "refunded";
+  readonly PARTIALLY_REFUNDED: "partially_refunded";
+  readonly IMPORTED: "imported";
+  readonly MATCHED: "matched";
+  readonly JOURNALIZED: "journalized";
+  readonly REJECTED: "rejected";
+};
+type TransactionStatus = typeof TRANSACTION_STATUS;
+type TransactionStatusValue = TransactionStatus[keyof TransactionStatus];
+declare const TRANSACTION_STATUS_VALUES: TransactionStatusValue[];
+declare const LIBRARY_CATEGORIES: {
+  readonly SUBSCRIPTION: "subscription";
+  readonly PURCHASE: "purchase";
+};
+type LibraryCategories = typeof LIBRARY_CATEGORIES;
+type LibraryCategoryValue = LibraryCategories[keyof LibraryCategories];
+declare const LIBRARY_CATEGORY_VALUES: LibraryCategoryValue[];
+declare function isLibraryCategory(value: unknown): value is LibraryCategoryValue;
+declare function isTransactionFlow(value: unknown): value is TransactionFlowValue;
+declare function isTransactionStatus(value: unknown): value is TransactionStatusValue;
+//#endregion
+//#region src/enums/bank-feed.enums.d.ts
+declare const TRANSACTION_KIND: {
+  /**
+   * Payment-gateway flow — the original revenue lifecycle. Stripe / SSL /
+   * Bkash / manual all share this graph.
+   *   pending → payment_initiated → processing → requires_action → verified
+   *   → completed → refunded | partially_refunded
+   */
+  readonly PAYMENT_FLOW: "payment_flow";
+  /**
+   * Bank / accounting feed — OFX upload, Plaid sync, QBO/Xero CDC.
+   *   imported → matched → journalized   (happy path)
+   *   imported → rejected                 (operator skip)
+   *   matched  → imported                 (un-match)
+   */
+  readonly BANK_FEED: "bank_feed";
+  /**
+   * Hand-keyed entry — treasurer logs a cash deposit, owner injects
+   * capital. Cleaner two-step lifecycle than payment_flow.
+   *   pending → matched → journalized | rejected
+   */
+  readonly MANUAL: "manual";
+};
+type TransactionKind = typeof TRANSACTION_KIND;
+type TransactionKindValue = TransactionKind[keyof TransactionKind];
+declare const TRANSACTION_KIND_VALUES: TransactionKindValue[];
+declare function isTransactionKind(value: unknown): value is TransactionKindValue;
+declare const BANK_FEED_STATUS: {
+  readonly IMPORTED: "imported";
+  readonly MATCHED: "matched";
+  readonly JOURNALIZED: "journalized";
+  readonly REJECTED: "rejected";
+};
+type BankFeedStatusValue = (typeof BANK_FEED_STATUS)[keyof typeof BANK_FEED_STATUS];
+declare const BANK_FEED_STATUS_VALUES: BankFeedStatusValue[];
+declare function isBankFeedStatus(value: unknown): value is BankFeedStatusValue;
+declare const BANK_FEED_SOURCE: {
+  readonly OFX: "ofx";
+  readonly CAMT053: "camt.053";
+  readonly MT940: "mt940";
+  readonly CSV: "csv";
+  readonly IIF: "iif";
+  readonly QBO: "qbo";
+  readonly XERO: "xero";
+  readonly PLAID: "plaid";
+  readonly MANUAL: "manual";
+};
+type BankFeedSourceValue = (typeof BANK_FEED_SOURCE)[keyof typeof BANK_FEED_SOURCE];
+declare const BANK_FEED_SOURCE_VALUES: BankFeedSourceValue[];
+declare function isBankFeedSource(value: unknown): value is BankFeedSourceValue;
+/**
+ * Initial status for a freshly created row of a given kind. Centralized so
+ * the schema, repo verbs, and validators agree.
+ *
+ * - `payment_flow` → `pending` — provider may flip to verified instantly
+ *   for zero-amount rows (see `createPaymentIntent`).
+ * - `bank_feed`    → `imported` — bulk upsert from a feed/upload.
+ * - `manual`       → `pending`  — treasurer reviews then `match()`es.
+ */
+declare function initialStatusFor(kind: TransactionKindValue): TransactionStatusValue;
+/**
+ * True iff `status` is a legal value for a transaction of the given
+ * `kind`. Use at API boundaries (admin status filters, list-page query
+ * params, JSON imports) to reject `?kind=payment_flow&status=imported`
+ * before it reaches the repository.
+ *
+ * @example
+ * if (!isStatusValidForKind(req.query.status, req.query.kind)) {
+ *   throw new ValidationError('status invalid for kind');
+ * }
+ */
+declare function isStatusValidForKind(status: unknown, kind: TransactionKindValue): boolean;
+/**
+ * The set of status values legal for a given kind. Useful for building
+ * dropdown options or `$in` filters at the API layer.
+ */
+declare function statusesForKind(kind: TransactionKindValue): readonly string[];
+//#endregion
+export { isTransactionFlow as A, TRANSACTION_STATUS as C, TransactionStatus as D, TransactionFlowValue as E, TransactionStatusValue as O, TRANSACTION_FLOW_VALUES as S, TransactionFlow as T, LIBRARY_CATEGORIES as _, BankFeedSourceValue as a, LibraryCategoryValue as b, TRANSACTION_KIND_VALUES as c, initialStatusFor as d, isBankFeedSource as f, statusesForKind as g, isTransactionKind as h, BANK_FEED_STATUS_VALUES as i, isTransactionStatus as j, isLibraryCategory as k, TransactionKind as l, isStatusValidForKind as m, BANK_FEED_SOURCE_VALUES as n, BankFeedStatusValue as o, isBankFeedStatus as p, BANK_FEED_STATUS as r, TRANSACTION_KIND as s, BANK_FEED_SOURCE as t, TransactionKindValue as u, LIBRARY_CATEGORY_VALUES as v, TRANSACTION_STATUS_VALUES as w, TRANSACTION_FLOW as x, LibraryCategories as y };

package/dist/bank-feed.enums-kYTLTTbe.mjs

@@ -0,0 +1,165 @@
+//#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",
+	IMPORTED: "imported",
+	MATCHED: "matched",
+	JOURNALIZED: "journalized",
+	REJECTED: "rejected"
+};
+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/bank-feed.enums.ts
+/**
+* Bank-feed lifecycle enums.
+*
+* Revenue 3.0 generalizes the Transaction model from "payment-gateway-only"
+* to a unified cashflow ledger. The `kind` discriminator selects which
+* state machine governs the row (see `core/state-machines.ts`); these
+* enums own the bank-feed and manual lifecycles plus the canonical
+* `TransactionKind` literals every consumer should branch on.
+*
+* Why a discriminator instead of a separate model — same collection wins
+* the unified-audit-ledger query ("everything that touched cash this
+* quarter"), keeps soft-delete + retention policies single-sourced, and
+* lets `relatedTransactionId` cross-link a Stripe charge to its Plaid
+* deposit without a polymorphic ref. See PACKAGE_RULES §30 / §35.
+*/
+const TRANSACTION_KIND = {
+	PAYMENT_FLOW: "payment_flow",
+	BANK_FEED: "bank_feed",
+	MANUAL: "manual"
+};
+const TRANSACTION_KIND_VALUES = Object.values(TRANSACTION_KIND);
+const transactionKindSet = new Set(TRANSACTION_KIND_VALUES);
+function isTransactionKind(value) {
+	return typeof value === "string" && transactionKindSet.has(value);
+}
+const BANK_FEED_STATUS = {
+	IMPORTED: "imported",
+	MATCHED: "matched",
+	JOURNALIZED: "journalized",
+	REJECTED: "rejected"
+};
+const BANK_FEED_STATUS_VALUES = Object.values(BANK_FEED_STATUS);
+const bankFeedStatusSet = new Set(BANK_FEED_STATUS_VALUES);
+function isBankFeedStatus(value) {
+	return typeof value === "string" && bankFeedStatusSet.has(value);
+}
+const BANK_FEED_SOURCE = {
+	OFX: "ofx",
+	CAMT053: "camt.053",
+	MT940: "mt940",
+	CSV: "csv",
+	IIF: "iif",
+	QBO: "qbo",
+	XERO: "xero",
+	PLAID: "plaid",
+	MANUAL: "manual"
+};
+const BANK_FEED_SOURCE_VALUES = Object.values(BANK_FEED_SOURCE);
+const bankFeedSourceSet = new Set(BANK_FEED_SOURCE_VALUES);
+function isBankFeedSource(value) {
+	return typeof value === "string" && bankFeedSourceSet.has(value);
+}
+/**
+* Initial status for a freshly created row of a given kind. Centralized so
+* the schema, repo verbs, and validators agree.
+*
+* - `payment_flow` → `pending` — provider may flip to verified instantly
+*   for zero-amount rows (see `createPaymentIntent`).
+* - `bank_feed`    → `imported` — bulk upsert from a feed/upload.
+* - `manual`       → `pending`  — treasurer reviews then `match()`es.
+*/
+function initialStatusFor(kind) {
+	switch (kind) {
+		case TRANSACTION_KIND.BANK_FEED: return BANK_FEED_STATUS.IMPORTED;
+		case TRANSACTION_KIND.MANUAL: return TRANSACTION_STATUS.PENDING;
+		case TRANSACTION_KIND.PAYMENT_FLOW:
+		default: return TRANSACTION_STATUS.PENDING;
+	}
+}
+const STATUSES_BY_KIND = {
+	[TRANSACTION_KIND.PAYMENT_FLOW]: new Set([
+		TRANSACTION_STATUS.PENDING,
+		TRANSACTION_STATUS.PAYMENT_INITIATED,
+		TRANSACTION_STATUS.PROCESSING,
+		TRANSACTION_STATUS.REQUIRES_ACTION,
+		TRANSACTION_STATUS.VERIFIED,
+		TRANSACTION_STATUS.COMPLETED,
+		TRANSACTION_STATUS.FAILED,
+		TRANSACTION_STATUS.CANCELLED,
+		TRANSACTION_STATUS.EXPIRED,
+		TRANSACTION_STATUS.REFUNDED,
+		TRANSACTION_STATUS.PARTIALLY_REFUNDED
+	]),
+	[TRANSACTION_KIND.BANK_FEED]: new Set([
+		TRANSACTION_STATUS.IMPORTED,
+		TRANSACTION_STATUS.MATCHED,
+		TRANSACTION_STATUS.JOURNALIZED,
+		TRANSACTION_STATUS.REJECTED
+	]),
+	[TRANSACTION_KIND.MANUAL]: new Set([
+		TRANSACTION_STATUS.PENDING,
+		TRANSACTION_STATUS.MATCHED,
+		TRANSACTION_STATUS.JOURNALIZED,
+		TRANSACTION_STATUS.REJECTED
+	])
+};
+/**
+* True iff `status` is a legal value for a transaction of the given
+* `kind`. Use at API boundaries (admin status filters, list-page query
+* params, JSON imports) to reject `?kind=payment_flow&status=imported`
+* before it reaches the repository.
+*
+* @example
+* if (!isStatusValidForKind(req.query.status, req.query.kind)) {
+*   throw new ValidationError('status invalid for kind');
+* }
+*/
+function isStatusValidForKind(status, kind) {
+	if (typeof status !== "string") return false;
+	return STATUSES_BY_KIND[kind].has(status);
+}
+/**
+* The set of status values legal for a given kind. Useful for building
+* dropdown options or `$in` filters at the API layer.
+*/
+function statusesForKind(kind) {
+	return [...STATUSES_BY_KIND[kind]];
+}
+
+//#endregion
+export { TRANSACTION_STATUS as _, TRANSACTION_KIND as a, isTransactionFlow as b, isBankFeedSource as c, isTransactionKind as d, statusesForKind as f, TRANSACTION_FLOW_VALUES as g, TRANSACTION_FLOW as h, BANK_FEED_STATUS_VALUES as i, isBankFeedStatus as l, LIBRARY_CATEGORY_VALUES as m, BANK_FEED_SOURCE_VALUES as n, TRANSACTION_KIND_VALUES as o, LIBRARY_CATEGORIES as p, BANK_FEED_STATUS as r, initialStatusFor as s, BANK_FEED_SOURCE as t, isStatusValidForKind as u, TRANSACTION_STATUS_VALUES as v, isTransactionStatus as x, isLibraryCategory as y };

package/dist/bridges/index.d.mts

@@ -1,2 +1,2 @@
-import { a as CurrencyBridge, c as LedgerBridge, i as CustomerBridge, n as SourceBridge, o as NotificationBridge, r as AnalyticsBridge, s as TaxBridge, t as RevenueBridges } from "../revenue-bridges-sdlrR85c.mjs";
+import { a as CurrencyBridge, c as LedgerBridge, i as CustomerBridge, n as SourceBridge, o as NotificationBridge, r as AnalyticsBridge, s as TaxBridge, t as RevenueBridges } from "../revenue-bridges-BtkWFsJu.mjs";
 export { type AnalyticsBridge, type CurrencyBridge, type CustomerBridge, type LedgerBridge, type NotificationBridge, type RevenueBridges, type SourceBridge, type TaxBridge };

package/dist/core/state-machines.d.mts

@@ -1,4 +1,5 @@
-import { C as SubscriptionStatusValue, F as SplitStatusValue, K as SettlementStatusValue, f as TransactionStatusValue, it as HoldStatusValue } from "../transaction.enums-u4MshXcL.mjs";
+import { U as HoldStatusValue, b as SplitStatusValue, c as SubscriptionStatusValue, j as SettlementStatusValue } from "../subscription.enums-k24kLpF7.mjs";
+import { O as TransactionStatusValue, u as TransactionKindValue } from "../bank-feed.enums-BadqNJTC.mjs";
 
 //#region src/core/state-machines.d.ts
 /**
@@ -49,5 +50,27 @@ declare const SUBSCRIPTION_STATE_MACHINE: StateMachine<SubscriptionStatusValue>;
 declare const SETTLEMENT_STATE_MACHINE: StateMachine<SettlementStatusValue>;
 declare const HOLD_STATE_MACHINE: StateMachine<HoldStatusValue>;
 declare const SPLIT_STATE_MACHINE: StateMachine<SplitStatusValue>;
+declare const PAYMENT_FLOW_STATE_MACHINE: StateMachine<TransactionStatusValue>;
+declare const BANK_FEED_STATE_MACHINE: StateMachine<TransactionStatusValue>;
+declare const MANUAL_STATE_MACHINE: StateMachine<TransactionStatusValue>;
+/**
+ * Select the state machine that governs a transaction row, given its
+ * `kind`. Repo verbs call this at the start of every state transition
+ * so the same `from → to` rules apply on both the in-memory check
+ * (state machine) and the atomic CAS (mongokit `claim()` with the
+ * `where: { kind }` predicate).
+ *
+ * @example
+ * ```ts
+ * const machine = smFor(transaction.kind);
+ * machine.validate(transaction.status, 'matched', String(transaction._id));
+ * await this.claim(id, {
+ *   from: ['imported', 'matched'],
+ *   to: 'matched',
+ *   where: { kind: transaction.kind },
+ * }, patch, opts);
+ * ```
+ */
+declare function smFor(kind: TransactionKindValue): StateMachine<TransactionStatusValue>;
 //#endregion
-export { HOLD_STATE_MACHINE, SETTLEMENT_STATE_MACHINE, SPLIT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, StateChangeEvent, StateMachine, TRANSACTION_STATE_MACHINE };
+export { BANK_FEED_STATE_MACHINE, HOLD_STATE_MACHINE, MANUAL_STATE_MACHINE, PAYMENT_FLOW_STATE_MACHINE, SETTLEMENT_STATE_MACHINE, SPLIT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, StateChangeEvent, StateMachine, TRANSACTION_STATE_MACHINE, smFor };

package/dist/core/state-machines.mjs

@@ -1,5 +1,6 @@
-import { F as TRANSACTION_STATUS, g as SETTLEMENT_STATUS, l as SPLIT_STATUS, r as SUBSCRIPTION_STATUS, w as HOLD_STATUS } from "../subscription.enums-tfoAgsTv.mjs";
-import { r as InvalidStateTransitionError } from "../errors-DHa8JVQ-.mjs";
+import { _ as TRANSACTION_STATUS, a as TRANSACTION_KIND } from "../bank-feed.enums-kYTLTTbe.mjs";
+import { g as SETTLEMENT_STATUS, l as SPLIT_STATUS, r as SUBSCRIPTION_STATUS, w as HOLD_STATUS } from "../subscription.enums-95othr0i.mjs";
+import { a as InvalidStateTransitionError } from "../errors-LYYg9wcs.mjs";
 import { defineStateMachine } from "@classytic/primitives/state-machine";
 
 //#region src/core/state-machines.ts
@@ -148,6 +149,45 @@ const SPLIT_STATE_MACHINE = new StateMachine(new Map([
 	[SPLIT_STATUS.WAIVED, /* @__PURE__ */ new Set([])],
 	[SPLIT_STATUS.CANCELLED, /* @__PURE__ */ new Set([])]
 ]), "split");
+const PAYMENT_FLOW_STATE_MACHINE = TRANSACTION_STATE_MACHINE;
+const BANK_FEED_STATE_MACHINE = new StateMachine(new Map([
+	[TRANSACTION_STATUS.IMPORTED, new Set([TRANSACTION_STATUS.MATCHED, TRANSACTION_STATUS.REJECTED])],
+	[TRANSACTION_STATUS.MATCHED, new Set([TRANSACTION_STATUS.IMPORTED, TRANSACTION_STATUS.JOURNALIZED])],
+	[TRANSACTION_STATUS.JOURNALIZED, /* @__PURE__ */ new Set([])],
+	[TRANSACTION_STATUS.REJECTED, /* @__PURE__ */ new Set([])]
+]), "transaction.bank_feed");
+const MANUAL_STATE_MACHINE = new StateMachine(new Map([
+	[TRANSACTION_STATUS.PENDING, new Set([TRANSACTION_STATUS.MATCHED, TRANSACTION_STATUS.REJECTED])],
+	[TRANSACTION_STATUS.MATCHED, new Set([TRANSACTION_STATUS.JOURNALIZED])],
+	[TRANSACTION_STATUS.JOURNALIZED, /* @__PURE__ */ new Set([])],
+	[TRANSACTION_STATUS.REJECTED, /* @__PURE__ */ new Set([])]
+]), "transaction.manual");
+/**
+* Select the state machine that governs a transaction row, given its
+* `kind`. Repo verbs call this at the start of every state transition
+* so the same `from → to` rules apply on both the in-memory check
+* (state machine) and the atomic CAS (mongokit `claim()` with the
+* `where: { kind }` predicate).
+*
+* @example
+* ```ts
+* const machine = smFor(transaction.kind);
+* machine.validate(transaction.status, 'matched', String(transaction._id));
+* await this.claim(id, {
+*   from: ['imported', 'matched'],
+*   to: 'matched',
+*   where: { kind: transaction.kind },
+* }, patch, opts);
+* ```
+*/
+function smFor(kind) {
+	switch (kind) {
+		case TRANSACTION_KIND.BANK_FEED: return BANK_FEED_STATE_MACHINE;
+		case TRANSACTION_KIND.MANUAL: return MANUAL_STATE_MACHINE;
+		case TRANSACTION_KIND.PAYMENT_FLOW:
+		default: return PAYMENT_FLOW_STATE_MACHINE;
+	}
+}
 
 //#endregion
-export { HOLD_STATE_MACHINE, SETTLEMENT_STATE_MACHINE, SPLIT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, StateMachine, TRANSACTION_STATE_MACHINE };
+export { 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 };