@classytic/revenue 2.0.1 → 2.1.3

package/dist/engine-types-Jctrbasz.d.mts

@@ -0,0 +1,1160 @@
+import { t as RevenueContext } from "./context-pjP1QeE3.mjs";
+import { t as RevenueBridges } from "./revenue-bridges-BtkWFsJu.mjs";
+import { u as TransactionKindValue } from "./bank-feed.enums-BadqNJTC.mjs";
+import { a as BankFeedProviderRegistry, d as PaymentProvider, o as FetchTransactionsParams, r as BankFeedProvider, t as ProviderRegistry } from "./registry-h8sasoLh.mjs";
+import { RepositoryPluginBundle, RevenueRepositories } from "./repositories/create-repositories.mjs";
+import { PluginType, Repository } from "@classytic/mongokit";
+import { TenantConfig } from "@classytic/repo-core/tenant";
+import mongoose, { Connection, Model, Schema } from "mongoose";
+import { DomainEvent, EventTransport } from "@classytic/primitives/events";
+import { OutboxStore } from "@classytic/primitives/outbox";
+import { BankImportReport, BankImportRowError, BankTransaction } from "@classytic/primitives/bank-transaction";
+import { ApprovalChain } from "@classytic/primitives/approval";
+
+//#region src/models/transaction.schema.d.ts
+/**
+ * Counterparty on a bank-feed entry. Untyped Mixed at the Mongoose level
+ * (banks populate different fields), but typed here so consumers and
+ * validators can introspect.
+ */
+interface TransactionCounterparty {
+  name?: string;
+  identifier?: string;
+  iban?: string;
+  accountNumber?: string;
+  bic?: string;
+  routingNumber?: string;
+}
+/**
+ * Polymorphic ledger journal-entry reference. String-typed (PACKAGE_RULES
+ * §7) so it works for ledger documents stored in another connection,
+ * Postgres ledgers, or external accounting systems (QBO Journal IDs).
+ */
+interface JournalEntryRef {
+  type: string;
+  id: string;
+}
+interface TransactionDocument {
+  _id: mongoose.Types.ObjectId;
+  publicId: string;
+  organizationId?: string;
+  customerId?: string | null;
+  /**
+   * Selects the state machine that governs this row's `status` field.
+   * Defaults to `'payment_flow'` so existing data reads identically.
+   * See `core/state-machines.ts:smFor()`.
+   */
+  kind: TransactionKindValue;
+  type: string;
+  flow: 'inflow' | 'outflow';
+  tags: string[];
+  amount: number;
+  currency: string;
+  fee: number;
+  tax: number;
+  net: number;
+  taxDetails?: {
+    type?: string;
+    rate?: number;
+    isInclusive?: boolean;
+  };
+  /**
+   * Multi-currency reconciliation (3.0). When the bank deposit clears
+   * in a currency different from the originating charge, store the
+   * other side here. Cross-currency `findMatchCandidates` reads these
+   * to compare same-currency-equivalent amounts.
+   */
+  fxRate?: number;
+  originalAmount?: number;
+  originalCurrency?: string;
+  method: string;
+  status: string;
+  /**
+   * Optional embedded approval chain — P7. Hosts that gate manual /
+   * non-gateway transactions on a maker-checker review attach a chain via
+   * `createChain()` from `@classytic/primitives/approval`; the host's
+   * approval action checks `isApproved(doc.approvals)` before flipping
+   * status to `succeeded`. Auto-gateway transactions (Stripe, SSLCommerz,
+   * etc.) bypass this entirely — synchronous gateway success is the gate.
+   *
+   * Use cases:
+   *   - Manual cash receipts (front desk → bookkeeper verify)
+   *   - Manual bank transfers (supplier-paid → finance verify)
+   *   - Cheque deposits (queued until cleared)
+   *   - **Refunds especially** — the audit-defining moment
+   */
+  approvals?: ApprovalChain;
+  gateway?: {
+    type: string;
+    sessionId?: string;
+    paymentIntentId?: string;
+    chargeId?: string;
+    metadata?: Record<string, unknown>;
+    verificationData?: Record<string, unknown>;
+  };
+  paymentDetails?: Record<string, unknown>;
+  commission?: {
+    rate: number;
+    grossAmount: number;
+    gatewayFeeRate: number;
+    gatewayFeeAmount: number;
+    netAmount: number;
+    status: string;
+  };
+  splits?: Array<{
+    type: string;
+    recipientId: string;
+    recipientType: string;
+    rate: number;
+    grossAmount: number;
+    gatewayFeeRate: number;
+    gatewayFeeAmount: number;
+    netAmount: number;
+    status: string;
+  }>;
+  hold?: {
+    status: string;
+    heldAmount: number;
+    releasedAmount: number;
+    reason: string;
+    heldAt: Date;
+    holdUntil?: Date;
+    releasedAt?: Date;
+    cancelledAt?: Date;
+    releases: Array<{
+      amount: number;
+      recipientId: string;
+      recipientType: string;
+      releasedAt: Date;
+      releasedBy?: string;
+      reason?: string;
+      metadata?: Record<string, unknown>;
+    }>;
+    metadata?: Record<string, unknown>;
+  };
+  /**
+   * Vendor-stable id from the upstream feed (FITID, NtryRef, qbo Id,
+   * Plaid transaction_id). Used to enforce idempotent re-import via the
+   * `(orgId, bankAccountId, externalId)` partial unique index.
+   *
+   * Distinct from `idempotencyKey` (host-chosen, request-scoped). See
+   * `@classytic/primitives/bank-transaction` and PACKAGE_RULES §8.
+   */
+  externalId?: string;
+  /** When the bank booked the entry. */
+  postedDate?: Date;
+  /** When funds clear / become available. */
+  valueDate?: Date;
+  /** Free-text bank description. */
+  description?: string;
+  counterparty?: TransactionCounterparty;
+  /** Check number, payment reference, end-to-end ID. */
+  reference?: string;
+  /** Running balance on the account after this entry, if the format provides it. */
+  balanceAfter?: number;
+  /** Bank's own category (rare in OFX, common in Plaid / Mint exports). */
+  vendorCategory?: string;
+  /**
+   * Polymorphic external ref to the bank account this row belongs to.
+   * String per PACKAGE_RULES §7 — accepts ObjectId hex, UUID, external
+   * IDs (Plaid `account_id`, QBO Account Id). Distinct from
+   * `customerId`; the `bankAccount` resource lives on the host side.
+   */
+  bankAccountId?: string;
+  /**
+   * Provenance — which feed produced this row. One of the values from
+   * `BANK_FEED_SOURCE` (`'ofx'`, `'plaid'`, `'qbo'`, …). Drives admin UI
+   * filtering and duplicate-detection rules.
+   */
+  source?: string;
+  /**
+   * Bidirectional link to the journal entry that posted this row to the
+   * GL. Stamped by `journalize()` after the host's LedgerBridge confirms
+   * the JE was created. Polymorphic — `type` names the foreign model
+   * (`'JournalEntry'`, `'QboJournalEntry'`, …).
+   */
+  journalEntryRef?: JournalEntryRef;
+  /**
+   * Operator-supplied mapping from bank line → GL accounts. Stored at
+   * match time so re-running the journalize step is deterministic.
+   */
+  matching?: {
+    debitAccount?: string;
+    creditAccount?: string;
+    notes?: string;
+    matchedAt?: Date;
+    matchedBy?: string;
+  };
+  sourceId?: string;
+  sourceModel?: string;
+  relatedTransactionId?: mongoose.Types.ObjectId;
+  refundedAmount?: number;
+  refundedAt?: Date;
+  failureReason?: string;
+  failedAt?: Date;
+  verifiedAt?: Date;
+  verifiedBy?: string;
+  webhook?: {
+    eventId: string;
+    eventType: string;
+    receivedAt: Date;
+    processedAt: Date;
+    data: Record<string, unknown>;
+  };
+  idempotencyKey?: string;
+  metadata?: Record<string, unknown>;
+  deletedAt?: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/models/subscription.schema.d.ts
+interface SubscriptionDocument {
+  _id: mongoose.Types.ObjectId;
+  publicId: string;
+  organizationId?: string;
+  customerId?: string | null;
+  planKey: string;
+  amount: number;
+  currency?: string;
+  status: string;
+  isActive: boolean;
+  transactionId?: mongoose.Types.ObjectId | null;
+  paymentIntentId?: string | null;
+  startDate?: Date;
+  endDate?: Date;
+  activatedAt?: Date;
+  pausedAt?: Date;
+  pauseReason?: string;
+  canceledAt?: Date;
+  cancelAt?: Date;
+  cancellationReason?: string;
+  /**
+   * Optional embedded approval chain — P7. Hosts that gate high-value
+   * subscription transitions on a maker-checker review attach a chain via
+   * `createChain()` from `@classytic/primitives/approval`; the host's
+   * approval action checks `isApproved(doc.approvals)` before applying
+   * the change. Routine renewals/auto-pause flows leave it undefined.
+   *
+   * Use cases:
+   *   - Cancel-with-refund (manager sign-off before issuing credit)
+   *   - Plan change with credit note (finance verifies proration)
+   *   - Manual reactivation after dunning failure
+   */
+  approvals?: ApprovalChain;
+  renewalTransactionId?: mongoose.Types.ObjectId;
+  renewalCount: number;
+  metadata?: Record<string, unknown>;
+  deletedAt?: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/models/settlement.schema.d.ts
+interface SettlementDocument {
+  _id: mongoose.Types.ObjectId;
+  publicId: string;
+  organizationId: string;
+  recipientId: string;
+  recipientType: string;
+  type: string;
+  status: string;
+  /**
+   * Optional embedded approval chain — P7. Hosts that gate payout release
+   * on a maker-checker review attach a chain via `createChain()` from
+   * `@classytic/primitives/approval`; the host's approval action checks
+   * `isApproved(doc.approvals)` before transitioning the settlement to
+   * `processed`/`completed`. Auto-disbursement flows leave it undefined.
+   *
+   * Use cases:
+   *   - Vendor payout sign-off (finance verifies before funds release)
+   *   - High-value mobile-wallet / crypto disbursement review
+   *   - Manual bank-transfer payouts to recipients
+   */
+  approvals?: ApprovalChain;
+  payoutMethod: string;
+  amount: number;
+  currency: string;
+  sourceTransactionIds: mongoose.Types.ObjectId[];
+  sourceSplitIds: string[];
+  bankTransferDetails?: Record<string, unknown>;
+  mobileWalletDetails?: Record<string, unknown>;
+  cryptoDetails?: Record<string, unknown>;
+  scheduledAt: Date;
+  processedAt?: Date;
+  completedAt?: Date;
+  failedAt?: Date;
+  cancelledAt?: Date;
+  failureReason?: string;
+  failureCode?: string;
+  retryCount: number;
+  notes?: string;
+  metadata?: Record<string, unknown>;
+  deletedAt?: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/models/create-models.d.ts
+interface RevenueModels {
+  Transaction: Model<TransactionDocument>;
+  Subscription?: Model<SubscriptionDocument>;
+  Settlement?: Model<SettlementDocument>;
+}
+interface RevenueSchemaOptions {
+  transaction?: {
+    extraFields?: Record<string, unknown>;
+    extraIndexes?: Array<{
+      fields: Record<string, 1 | -1>;
+      options?: Record<string, unknown>;
+    }>;
+  };
+  subscription?: {
+    extraFields?: Record<string, unknown>;
+    extraIndexes?: Array<{
+      fields: Record<string, 1 | -1>;
+      options?: Record<string, unknown>;
+    }>;
+  };
+  settlement?: {
+    extraFields?: Record<string, unknown>;
+    extraIndexes?: Array<{
+      fields: Record<string, 1 | -1>;
+      options?: Record<string, unknown>;
+    }>;
+  };
+}
+//#endregion
+//#region src/repositories/base.repository.d.ts
+/**
+ * Cross-cutting deps that every revenue repository needs.
+ *
+ * Subclasses extend this with their own bridges, providers, configs:
+ *
+ * ```ts
+ * export interface SettlementRepoDeps extends BaseRevenueRepoDeps {
+ *   bridges: RevenueBridges;
+ * }
+ * ```
+ */
+interface BaseRevenueRepoDeps {
+  /**
+   * Domain-event transport (in-process or arc-compatible). All four
+   * `revenue:*` event families (`payment.*`, `subscription.*`,
+   * `settlement.*`, `escrow.*`) flow through this single channel; hosts
+   * subscribe glob-style.
+   */
+  events: EventTransport;
+  /**
+   * Optional host-owned outbox (PACKAGE_RULES §5.5 + P8). When wired,
+   * every dispatched event is persisted via `outbox.save(event)` BEFORE
+   * `events.publish(event)` so a host relay (arc's EventOutbox, a Postgres
+   * LISTEN/NOTIFY pump, Kafka Connect, …) can replay on transport
+   * failure. When absent, events fire through `events.publish` only.
+   */
+  outbox?: OutboxStore | undefined;
+  /**
+   * Optional structured logger. Outbox/transport failures are logged
+   * here rather than thrown — a downstream subscriber error never
+   * cancels the upstream business write.
+   */
+  logger?: {
+    error(...args: unknown[]): void;
+  } | undefined;
+}
+/**
+ * Abstract base for `TransactionRepository`, `SubscriptionRepository`,
+ * `SettlementRepository`.
+ *
+ * Concrete subclasses MUST:
+ * - declare a `Deps` interface that extends {@link BaseRevenueRepoDeps}
+ * - call `super(model, plugins)` from the constructor
+ * - call `inject(deps)` once during engine boot
+ *
+ * Subclasses SHOULD use {@link optsFromCtx} for every mongokit call
+ * that takes an options bag, and {@link dispatch} for every event
+ * publish.
+ */
+declare abstract class RevenueRepositoryBase<TDoc, TDeps extends BaseRevenueRepoDeps> extends Repository<TDoc> {
+  /**
+   * Subclass-specific deps. `!` because the engine wires this once via
+   * `inject(deps)` immediately after construction; calling any domain
+   * verb before injection is a programming error and the runtime
+   * will fail-loud with `Cannot read properties of undefined`.
+   */
+  protected deps: TDeps;
+  constructor(model: Model<TDoc>, plugins?: PluginType[]);
+  /**
+   * Wire engine-managed deps. Called exactly once per repository
+   * instance during {@link createRevenue} bootstrap. Subclasses with
+   * extra steps (caching, prebuilding state machine maps) override and
+   * call `super.inject(deps)`.
+   */
+  inject(deps: TDeps): void;
+  /**
+   * Translate {@link RevenueContext} into a mongokit options bag.
+   *
+   * Forwards every canonical field mongokit's bundled plugins read —
+   * `organizationId` (multiTenant), `userId` / `user` (audit),
+   * `session` (transactions), `requestId` (observability) — plus
+   * the revenue-specific `_bypassTenant` flag for platform-admin
+   * cross-org reads.
+   *
+   * Pass `extra` for caller-specific options like `throwOnNotFound`,
+   * `lean`, `populate`, `select` — the spread is `extra`-first so
+   * ctx wins on a key collision (intentional: callers shouldn't
+   * be smuggling tenant fields through `extra`).
+   *
+   * @param ctx - The request-scoped revenue context.
+   * @param extra - Additional mongokit options merged in.
+   */
+  protected optsFromCtx(ctx?: RevenueContext, extra?: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Persist an event to the host outbox, then publish to the in-process
+   * transport. The two sides have asymmetric failure handling — see
+   * PACKAGE_RULES §P8.
+   *
+   * When `ctx.session` is set, the outbox `save` runs inside the same
+   * Mongoose transaction (true P8 session-bound write); when absent, the
+   * outbox row lands after commit — still durable via the host's relay,
+   * with only a small at-most-once window on process crash.
+   *
+   *   1. **`outbox.save` failures PROPAGATE.** If we can't durably record
+   *      the event, the caller's transaction MUST roll back so the
+   *      business doc and the event row land atomically (or neither
+   *      lands). Swallowing a save failure breaks the transactional-
+   *      outbox correctness argument — the parent doc would land while
+   *      the event vanishes.
+   *
+   *   2. **`events.publish` failures are SWALLOWED.** The host's outbox
+   *      relay re-publishes from the durable row on its next poll. Even
+   *      without an outbox, in-process subscribers shouldn't be able to
+   *      break the business operation — they're best-effort consumers.
+   *
+   * @param event - Pre-built domain event (use `createEvent(REVENUE_EVENTS.X, payload, ctx, meta)`).
+   * @param ctx - The same context that produced the business write.
+   */
+  protected dispatch(event: DomainEvent, ctx?: RevenueContext): Promise<void>;
+}
+//#endregion
+//#region src/repositories/transaction.repository.d.ts
+/**
+ * Deps for {@link TransactionRepository}. Extends {@link BaseRevenueRepoDeps}
+ * (events / outbox? / logger?) with provider/bridge/config wiring specific
+ * to the payment-flow + bank-feed lifecycles.
+ */
+interface TransactionRepoDeps extends BaseRevenueRepoDeps {
+  providers: ProviderRegistry;
+  /**
+   * Bank-feed provider registry (3.0). Optional — when omitted, the
+   * `drainSync` and `parseAndImport` verbs throw on use. The host typically
+   * wires Plaid / fin-io / a custom CSV provider here.
+   */
+  bankFeedProviders?: BankFeedProviderRegistry | undefined;
+  bridges: RevenueBridges;
+  commission?: CommissionConfig;
+  defaultCurrency: string;
+}
+declare class TransactionRepository extends RevenueRepositoryBase<TransactionDocument, TransactionRepoDeps> {
+  constructor(model: Model<TransactionDocument>, plugins?: PluginType[]);
+  /**
+   * Save an event to the host-owned outbox, session-bound when available.
+   *
+   * Called INSIDE a `withTransaction` body. The outbox row commits
+   * atomically with the business write (P8 true session-bound write) —
+   * if outbox.save fails, this method re-throws so `withTransaction`
+   * rolls the parent write back. Without propagation, the parent doc
+   * would commit while the event row vanishes, defeating the whole
+   * transactional-outbox correctness argument.
+   *
+   * Logging happens before the re-throw so the failure surfaces in
+   * observability without losing the original stack trace.
+   */
+  protected saveToOutbox(event: DomainEvent, session?: unknown): Promise<void>;
+  /**
+   * Publish an event to the in-process `EventTransport` after commit.
+   * Transport failure is logged and swallowed — the host relay re-delivers
+   * from the durable outbox row on the next poll, so in-process
+   * subscribers missing an event is recoverable. Best-effort by design.
+   */
+  protected publishToTransport(event: DomainEvent): Promise<void>;
+  /** Creates transaction + calls provider. Returns the created transaction doc. */
+  createPaymentIntent(params: {
+    data?: Record<string, unknown>;
+    planKey?: string;
+    monetizationType?: string;
+    amount: number;
+    currency?: string;
+    gateway: string;
+    paymentData?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /** Verifies payment via provider, updates status. Returns the updated doc. */
+  verify(paymentIntentId: string, options?: {
+    verifiedBy?: string;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * Creates refund transaction, updates original. Returns the refund transaction doc.
+   *
+   * The provider call happens OUTSIDE the transaction — it's a non-idempotent external
+   * side effect we can't roll back. The two Mongo writes (create refund + update original)
+   * run inside `withTransaction` so they commit atomically or both abort. Bridges and
+   * event emission run AFTER commit because they're independent side effects; rolling
+   * them back would not undo external state anyway.
+   *
+   * Powered by mongokit 3.6's module-level `withTransaction` helper. Automatically
+   * retries on `TransientTransactionError` / `UnknownTransactionCommitResult`.
+   */
+  refund(transactionId: string, amount?: number | null, options?: {
+    reason?: string;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /** Handles provider webhook. Returns the updated transaction doc (or null if not found). */
+  handleWebhook(providerName: string, payload: unknown, headers?: Record<string, string>, ctx?: RevenueContext): Promise<TransactionDocument | null>;
+  /** Places hold on verified transaction. Returns the updated doc. */
+  hold(transactionId: string, options?: {
+    amount?: number;
+    reason?: string;
+    holdUntil?: Date;
+    metadata?: Record<string, unknown>;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * Releases held funds. Returns the updated transaction doc.
+   *
+   * The hold update and the escrow_release transaction create happen inside
+   * `withTransaction` — a mid-flow crash can't leave the hold marked released
+   * without the corresponding outflow record (or vice versa).
+   */
+  release(transactionId: string, options: {
+    amount?: number;
+    recipientId: string;
+    recipientType: string;
+    reason?: string;
+    releasedBy?: string;
+    createTransaction?: boolean;
+    metadata?: Record<string, unknown>;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * Splits payment among recipients. Returns the updated transaction doc.
+   *
+   * N + 2 writes (one create per recipient, one update on the parent, one
+   * platform_revenue create) all commit atomically. Partial splits are the
+   * worst class of bug in a payments system — this is exactly what
+   * `withTransaction` is for.
+   */
+  split(transactionId: string, rules: Array<{
+    type: string;
+    recipientId: string;
+    recipientType: string;
+    rate: number;
+  }>, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * 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'`, …).
+   */
+  import(rows: BankTransaction[], opts: {
+    bankAccountId: string;
+    source: string;
+    method?: string;
+  }, ctx?: RevenueContext): Promise<BankImportReport>;
+  /**
+   * 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.
+   */
+  drainSync(providerName: string, params: FetchTransactionsParams & {
+    bankAccountId: string;
+  }, ctx?: RevenueContext): Promise<{
+    totalImported: number;
+    totalUpdated: number;
+    totalRemoved: number;
+    nextCursor?: string;
+    errors: BankImportRowError[];
+  }>;
+  /**
+   * 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.
+   */
+  parseAndImport(providerName: string, upload: {
+    buffer: Buffer | string | Uint8Array;
+    format?: string;
+    bankAccountId: string;
+  }, ctx?: RevenueContext): Promise<BankImportReport>;
+  /**
+   * 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.
+   */
+  createManual(data: {
+    amount: number;
+    currency: string;
+    flow: 'inflow' | 'outflow';
+    type: string;
+    description?: string;
+    counterparty?: TransactionDocument['counterparty'];
+    reference?: string;
+    postedDate?: Date;
+    valueDate?: Date;
+    bankAccountId?: string;
+    sourceId?: string;
+    sourceModel?: string;
+    metadata?: Record<string, unknown>;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * 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).
+   */
+  match(id: string, data: {
+    mapping: {
+      debitAccount?: string;
+      creditAccount?: string;
+      notes?: string;
+    };
+    relatedTransactionId?: string;
+    matchedBy?: string;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * 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).
+   */
+  unmatch(id: string, options?: {
+    unmatchedBy?: string;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * 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.
+   */
+  journalize(id: string, data: {
+    journalEntryRef: {
+      type: string;
+      id: string;
+    };
+    journalizedBy?: string;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * 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.
+   */
+  reject(id: string, data: {
+    reason: string;
+    rejectedBy?: string;
+  }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * 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).
+   */
+  removeByFeed(externalIds: string[], opts: {
+    bankAccountId: string;
+    source: string;
+  }, ctx?: RevenueContext): Promise<{
+    removed: number;
+    retainedJournalized: TransactionDocument[];
+  }>;
+  /**
+   * 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, …).
+   */
+  findMatchCandidates(filter: {
+    amount: number;
+    currency?: string;
+    postedDate: Date;
+    toleranceDays?: number;
+    amountTolerancePct?: number;
+    counterpartyName?: string;
+    kind?: TransactionKindValue;
+  }, ctx?: RevenueContext): Promise<TransactionDocument[]>;
+  /**
+   * 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).
+   */
+  getRunningBalance(bankAccountId: string, asOf?: Date, ctx?: RevenueContext): Promise<{
+    balance: number;
+    currency: string | null;
+    rowCount: number;
+    asOf: Date;
+  }>;
+}
+//#endregion
+//#region src/repositories/subscription.repository.d.ts
+/**
+ * Deps for {@link SubscriptionRepository}. Currently identical to
+ * {@link BaseRevenueRepoDeps} (events / outbox? / logger?). Kept as its
+ * own type alias so future subscription-specific deps (e.g. a billing
+ * engine handle) can land without touching every callsite — and so the
+ * `inject(deps)` signature reads as `SubscriptionRepoDeps` at the
+ * engine factory.
+ */
+type SubscriptionRepoDeps = BaseRevenueRepoDeps;
+/**
+ * SubscriptionRepository — data layer + domain verbs for the recurring-
+ * billing lifecycle.
+ *
+ * **CRUD inherited** from mongokit (via {@link RevenueRepositoryBase}):
+ * `getById`, `getByQuery`, `getAll`, `create`, `update`, `delete`,
+ * `findOneAndUpdate`, `count`, `exists`, `claim`, `cursor`, `updateMany`,
+ * `deleteMany`. All participate in `multiTenantPlugin` scope filtering
+ * when wired.
+ *
+ * **Domain verbs (state transitions):** `activate`, `cancel`, `pause`,
+ * `resume`. Each runs the state-machine guard (`SUBSCRIPTION_STATE_MACHINE`
+ * — invalid transitions throw, never silently no-op), persists the
+ * resulting writes through {@link RevenueRepositoryBase.optsFromCtx} so
+ * tenant scope is preserved end-to-end, then dispatches its
+ * `revenue:subscription.*` event via {@link RevenueRepositoryBase.dispatch}.
+ *
+ * **Multi-tenant correctness.** Every internal `getById`/`update` call
+ * threads `ctx.organizationId` through `optsFromCtx(ctx)`. Without this
+ * threading the inner read would either throw
+ * `Missing 'organizationId' in context` (when `multiTenantPlugin` is
+ * required) or — worse — return another tenant's subscription matching
+ * the same `_id` shape (when `required: false`). 2.1.0 had this bug; 2.1.1+
+ * is correct.
+ *
+ * @example Activate a pending sub
+ * ```ts
+ * const ctx = { organizationId: 'org_42', actorId: 'user_99' };
+ * const sub = await subRepo.create(
+ *   { customerId: 'cust_1', planKey: 'monthly', amount: 999, currency: 'USD',
+ *     status: SUBSCRIPTION_STATUS.PENDING, isActive: false },
+ *   ctx,
+ * );
+ * await subRepo.activate(String(sub._id), {}, ctx);
+ * ```
+ */
+declare class SubscriptionRepository extends RevenueRepositoryBase<SubscriptionDocument, SubscriptionRepoDeps> {
+  constructor(model: Model<SubscriptionDocument>, plugins?: PluginType[]);
+  activate(subscriptionId: string, options?: {
+    timestamp?: Date;
+  }, ctx?: RevenueContext): Promise<SubscriptionDocument>;
+  cancel(subscriptionId: string, options?: {
+    immediate?: boolean;
+    reason?: string;
+  }, ctx?: RevenueContext): Promise<SubscriptionDocument>;
+  pause(subscriptionId: string, options?: {
+    reason?: string;
+  }, ctx?: RevenueContext): Promise<SubscriptionDocument>;
+  resume(subscriptionId: string, options?: {
+    extendPeriod?: boolean;
+  }, ctx?: RevenueContext): Promise<SubscriptionDocument>;
+}
+//#endregion
+//#region src/repositories/settlement.repository.d.ts
+/**
+ * Deps for {@link SettlementRepository}. Adds the optional
+ * `RevenueBridges` (ledger / notification ports) on top of
+ * {@link BaseRevenueRepoDeps}.
+ */
+interface SettlementRepoDeps extends BaseRevenueRepoDeps {
+  bridges: RevenueBridges;
+}
+interface SettlementProcessingError {
+  settlementId: SettlementDocument['_id'];
+  error: unknown;
+}
+/**
+ * SettlementRepository — payouts to recipients (organizations, vendors,
+ * affiliates).
+ *
+ * **CRUD inherited** via {@link RevenueRepositoryBase}. **Domain verbs:**
+ * `schedule`, `processPending`, `complete`, `fail`. State machine:
+ * `pending → processing → completed | failed`; `failed` with
+ * `retry: true` resets to `pending` with a delayed `scheduledAt`.
+ *
+ * **Multi-tenant correctness.** Every read/write threads `ctx` through
+ * {@link RevenueRepositoryBase.optsFromCtx} so `multiTenantPlugin`
+ * scope filters apply. 2.1.0 had several `getById`/`update` calls that
+ * dropped ctx — fixed in 2.1.1+.
+ *
+ * Bridges (`ledger`, `notification`) fire on `complete()` so a host
+ * can pin double-entry book-keeping or push a "you got paid" email
+ * without the repo knowing about either subsystem.
+ */
+declare class SettlementRepository extends RevenueRepositoryBase<SettlementDocument, SettlementRepoDeps> {
+  constructor(model: Model<SettlementDocument>, plugins?: PluginType[]);
+  schedule(params: {
+    organizationId: string;
+    recipientId: string;
+    recipientType: string;
+    type: string;
+    amount: number;
+    currency: string;
+    payoutMethod: string;
+    sourceTransactionIds?: string[];
+    sourceSplitIds?: string[];
+    scheduledAt?: Date;
+    bankTransferDetails?: Record<string, unknown>;
+    mobileWalletDetails?: Record<string, unknown>;
+    cryptoDetails?: Record<string, unknown>;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+  }, ctx?: RevenueContext): Promise<SettlementDocument>;
+  processPending(options?: {
+    limit?: number;
+    organizationId?: string;
+    payoutMethod?: string;
+    dryRun?: boolean;
+  }, ctx?: RevenueContext): Promise<{
+    processed: number;
+    succeeded: number;
+    failed: number;
+    settlements: SettlementDocument[];
+    errors: SettlementProcessingError[];
+  }>;
+  complete(settlementId: string, details?: {
+    transferReference?: string;
+    transferredAt?: Date;
+    transactionHash?: string;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+  }, ctx?: RevenueContext): Promise<SettlementDocument>;
+  fail(settlementId: string, reason: string, options?: {
+    code?: string;
+    retry?: boolean;
+  }, ctx?: RevenueContext): Promise<SettlementDocument>;
+}
+//#endregion
+//#region src/engine/engine-types.d.ts
+interface CommissionConfig {
+  defaultRate: number;
+  gatewayFeeRate?: number | undefined;
+  categoryRates?: Record<string, number> | undefined;
+  gatewayRates?: Record<string, number> | undefined;
+}
+interface RetryConfig {
+  maxAttempts?: number | undefined;
+  baseDelay?: number | undefined;
+}
+/**
+ * Per-index opt-in for the bank-feed lifecycle. Each flag controls one
+ * MongoDB index on the `Transaction` collection. Defaults are tuned for
+ * "moderate use" — required indexes are on, dashboard indexes are on,
+ * heavy reconciliation indexes are off.
+ *
+ * Toggle these to match real usage. Index builds are non-trivial on a
+ * collection with millions of rows; turning unused ones off saves disk +
+ * write amplification.
+ */
+interface BankFeedIndexConfig {
+  /**
+   * `(orgId, bankAccountId, externalId)` partial unique index. Required
+   * for `import()` to enforce idempotent re-import — turning this off
+   * means a Plaid drain that retries can produce duplicate rows.
+   *
+   * Default: `true`. Disable only if you don't use `import()` /
+   * `drainSync()` / `parseAndImport()`.
+   */
+  idempotentImport?: boolean | undefined;
+  /**
+   * `(bankAccountId, postedDate -1)` partial — drives the treasurer
+   * dashboard ("show me last 30 days of transactions for account X").
+   * Cheap; on by default.
+   */
+  byAccount?: boolean | undefined;
+  /**
+   * `(kind, amount, postedDate)` and `(kind, amount, createdAt)` —
+   * back the cross-reference query in `findMatchCandidates`. Two
+   * compound indexes; turn on when you actively reconcile bank
+   * deposits to gateway charges.
+   *
+   * Default: `false`. Enable when running a recon dashboard.
+   */
+  matchCandidates?: boolean | undefined;
+}
+/**
+ * Bank-feed module configuration. Pass `true` for defaults, `false` to
+ * disable the module (skips the bulkWrite plugin + every bank-feed
+ * index), or an object to fine-tune indexes.
+ */
+interface BankFeedModuleConfig {
+  enabled?: boolean | undefined;
+  indexes?: BankFeedIndexConfig | undefined;
+}
+interface RevenueConfig {
+  connection: Connection;
+  defaultCurrency: string;
+  /**
+   * Event transport — structurally compatible with `@classytic/arc`'s
+   * `EventTransport`. Drop in any arc transport (Memory/Redis/Kafka) and it
+   * works without an adapter. When omitted, the engine uses
+   * `InProcessRevenueBus` (a ~50-line match of arc's `MemoryEventTransport`).
+   */
+  eventTransport?: EventTransport | undefined;
+  /**
+   * Host-owned transactional outbox store (PACKAGE_RULES §5.5 + P8).
+   * Structurally identical to `@classytic/arc`'s `OutboxStore` by design —
+   * primitives is the source of truth for the contract and arc mirrors it.
+   *
+   * **Host responsibility.** Revenue does NOT ship a durable store. Arc 2.10
+   * only ships `MemoryOutboxStore` (dev) + the `OutboxStore` interface — the
+   * host wires durability. The canonical production wiring uses arc's
+   * `repositoryAsOutboxStore` adapter over a mongokit `Repository`:
+   *
+   * ```ts
+   * import mongoose, { Schema } from 'mongoose';
+   * import {
+   *   Repository,
+   *   methodRegistryPlugin,
+   *   batchOperationsPlugin,
+   * } from '@classytic/mongokit';
+   * import { EventOutbox, repositoryAsOutboxStore } from '@classytic/arc/events';
+   * import { createRevenue } from '@classytic/revenue';
+   *
+   * // Arc owns the on-disk doc shape — strict:false forwards every field
+   * // (see arc's events.mdx "Why strict: false").
+   * const OutboxModel = mongoose.model(
+   *   'ArcOutbox',
+   *   new Schema({}, { strict: false, timestamps: false, _id: false }),
+   *   'event_outbox',
+   * );
+   *
+   * // Required plugins: the adapter calls `create` / `findAll` /
+   * // `findOneAndUpdate` (base Repository) + `deleteMany` (batchOperations).
+   * const outboxRepo = new Repository(OutboxModel, [
+   *   methodRegistryPlugin(),
+   *   batchOperationsPlugin(),
+   * ]);
+   * const outbox = repositoryAsOutboxStore(outboxRepo);
+   *
+   * const engine = await createRevenue({
+   *   connection: mongoose.connection,
+   *   defaultCurrency: 'USD',
+   *   outbox,                       // revenue's dispatch saves here
+   *   eventTransport: app.events,   // arc transport for in-process subscribers
+   *   // ...
+   * });
+   *
+   * // Relay + DLQ live in the host, not the package:
+   * const relay = new EventOutbox({ store: outbox, transport: app.events });
+   * setInterval(() => relay.relay(), 1_000);
+   * ```
+   *
+   * **Session-bound atomicity.** Revenue's transactional verbs (`refund`,
+   * `release`, `split`) open a mongokit `withTransaction` and pass the
+   * mongoose `ClientSession` into `outbox.save(event, { session })`, so the
+   * outbox row commits atomically with the business writes. Non-transactional
+   * verbs (`createPaymentIntent`, `verify`, `handleWebhook`, `hold`) forward
+   * `ctx.session` when the host is coordinating its own transaction — pass
+   * `{ session }` in `RevenueContext` to participate.
+   *
+   * **Non-arc hosts.** Any `OutboxStore` works — implement the three-method
+   * floor (`save` / `getPending` / `acknowledge`) over Postgres / Redis /
+   * Kafka / SQS. When omitted, events flow to `eventTransport` only
+   * (durability becomes transport-level, not at-least-once).
+   */
+  outbox?: OutboxStore | undefined;
+  modules?: {
+    subscription?: boolean | undefined;
+    escrow?: boolean | undefined;
+    settlement?: boolean | undefined;
+    commission?: CommissionConfig | boolean | undefined;
+    /**
+     * Bank-feed / accounting-feed module (3.0). Default: enabled (the
+     * schema fields are always present so the discriminator works
+     * uniformly). Disabling this suppresses the auto-wiring of
+     * `bankFeedProviders`, the bulk-write plugin, AND every bank-feed
+     * index — set to `false` for hosts that purely use the payment-
+     * flow lifecycle and want to omit those costs.
+     *
+     * Pass an object to fine-tune which bank-feed indexes are built.
+     * Examples:
+     *   `{ bankFeed: { indexes: { matchCandidates: true } } }`
+     *     — turn on cross-ref indexes for an active recon dashboard.
+     *   `{ bankFeed: { indexes: { idempotentImport: false, byAccount: false } } }`
+     *     — host doesn't use `import()` and doesn't need treasurer dashboards.
+     */
+    bankFeed?: boolean | BankFeedModuleConfig | undefined;
+  } | undefined;
+  providers?: Record<string, PaymentProvider> | undefined;
+  /**
+   * Bank-feed providers — Plaid, fin-io OFX/CAMT/MT940/CSV, QBO/Xero CDC
+   * adapters. Wired into `engine.bankFeedProviders` and consumed by
+   * `transactionRepository.drainSync()` and `parseAndImport()`.
+   *
+   * @example
+   * ```ts
+   * import { PlaidBankFeedProvider } from '@classytic/revenue-plaid';
+   * import { FinIoBankFeedProvider } from '@classytic/revenue-fin-io';
+   *
+   * const engine = await createRevenue({
+   *   ...,
+   *   bankFeedProviders: {
+   *     plaid: new PlaidBankFeedProvider({ clientId, secret }),
+   *     ofx:   new FinIoBankFeedProvider(),
+   *   },
+   * });
+   * ```
+   */
+  bankFeedProviders?: Record<string, BankFeedProvider> | undefined;
+  bridges?: RevenueBridges | undefined;
+  repositoryPlugins?: RepositoryPluginBundle | undefined;
+  schemaOptions?: RevenueSchemaOptions | undefined;
+  /**
+   * Tenant scope configuration. Delegates to `@classytic/primitives`'
+   * `TenantConfig`. Field names match mongokit's `MultiTenantOptions` so
+   * the resolved config forwards directly into `multiTenantPlugin(...)`.
+   *
+   * - `undefined` / `true` → default field strategy, ObjectId storage.
+   * - `false` → single-tenant (no plugin, field still present, not required).
+   * - `{ fieldType: 'string' }` → string orgIds (UUID/slug hosts).
+   * - `{ strategy: 'custom', resolve: ... }` → composite / derived scope.
+   *
+   * See PACKAGE_RULES.md §9.
+   */
+  scope?: TenantConfig | boolean | undefined;
+  commission?: CommissionConfig | undefined;
+  retry?: RetryConfig | undefined;
+  circuitBreaker?: boolean | undefined;
+  /**
+   * Set `false` to disable Mongoose auto-index on boot. Indexes are then
+   * managed explicitly via `engine.syncIndexes()` or a deploy-time script.
+   */
+  autoIndex?: boolean | Partial<Record<'Transaction' | 'Subscription' | 'Settlement', boolean>> | undefined;
+  /**
+   * Optional prefix prepended to every physical collection this package
+   * creates (see PACKAGE_RULES.md §20.1). Unset → default names
+   * (`revenue_transactions`, `revenue_subscriptions`, `revenue_settlements`).
+   * Model names and `ref:` populate are unaffected.
+   */
+  collectionPrefix?: string | undefined;
+  /**
+   * When true, existing Mongoose models with revenue's names are deleted
+   * from the connection before re-registering. Hot-reload / test fixtures
+   * only. Default `false` — collision throws `RevenueModelCollisionError`.
+   * Hosts that need two revenue engines should use two Mongoose connections
+   * (`mongoose.createConnection(...)`). See PACKAGE_RULES.md §21.
+   */
+  forceRecreate?: boolean | undefined;
+  logger?: {
+    info: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+  } | undefined;
+}
+/**
+ * RevenueEngine — no service facade.
+ *
+ * Repositories ARE the domain layer. CRUD is inherited from mongokit.
+ * Domain verbs (verify, refund, hold, activate, etc.) live on repositories.
+ * Arc's BaseController/adapter plugs into repositories directly.
+ *
+ * `events` is structurally compatible with `@classytic/arc`'s
+ * `EventTransport`. Hosts subscribe glob-style:
+ *
+ *     await revenue.events.subscribe('revenue:payment.*', handler);
+ *
+ * and the same transport can be wired into the outbox relay for durable
+ * delivery (see mongokit's `outbox-recipe.ts`). See PACKAGE_RULES §13.
+ */
+interface RevenueEngine {
+  config: Readonly<RevenueConfig>;
+  models: RevenueModels;
+  repositories: RevenueRepositories;
+  providers: ProviderRegistry;
+  /**
+   * Bank-feed providers registry (3.0). Populated when `bankFeed`
+   * module is enabled and `bankFeedProviders` config is non-empty.
+   * Used by `transactionRepository.drainSync()` and
+   * `parseAndImport()`. Hosts can `register` providers at runtime too
+   * (e.g. after the engine boots, to add a per-tenant Plaid client).
+   */
+  bankFeedProviders: BankFeedProviderRegistry;
+  events: EventTransport;
+  /** Explicitly build all schema-declared indexes. Non-destructive. */
+  syncIndexes(): Promise<void>;
+  destroy(): Promise<void>;
+}
+//#endregion
+export { RevenueConfig as a, SubscriptionRepository as c, RevenueSchemaOptions as d, SettlementDocument as f, RetryConfig as i, TransactionRepository as l, TransactionDocument as m, BankFeedModuleConfig as n, RevenueEngine as o, SubscriptionDocument as p, CommissionConfig as r, SettlementRepository as s, BankFeedIndexConfig as t, RevenueModels as u };