@classytic/revenue 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -3,6 +3,101 @@
 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.2.0] - 2026-05-26
+
+### Added — auth/capture + dispute event coverage
+
+Seven new event constants on `REVENUE_EVENTS` aligning with the
+`@classytic/primitives@0.7.1` payment event catalogue:
+`PAYMENT_AUTHORIZED`, `PAYMENT_CAPTURED`, `PAYMENT_AUTH_VOIDED`,
+`PAYMENT_DISPUTED`, `PAYMENT_DISPUTE_WON`, `PAYMENT_DISPUTE_LOST`,
+`PAYMENT_SETTLED`. Catalog payload schemas updated to match.
+
+### Added — `RevenueError.httpStatus`
+
+`RevenueError` carries an optional `httpStatus` field so Arc / Express
+hosts can map errors to response codes without per-error switch
+statements. Defaults to 500 in the host mapper when unset.
+
+### Added — `MethodKindLockedError` (409)
+
+New error thrown by `TransactionRepository.backfillMethodKind` when the
+existing doc is not backfill-eligible (methodKind already specific OR
+status no longer `pending`). 409 because the request is well-formed but
+conflicts with current resource state.
+
+### Changed — peer bump: `@classytic/primitives` `>=0.7.1`
+
+Catalogue now imports `PAYMENT_METHOD_KIND` from
+`@classytic/primitives/payment-method-kind`. Hosts must bump primitives
+to `>=0.7.1`.
+
+## [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

@@ -48,30 +48,61 @@ const refundTxn = await revenue.repositories.transaction.refund(
 // refundTxn.type → 'refund', refundTxn.flow → 'outflow', refundTxn.amount → 5000
 ```
 
+## Hosted-checkout `methodKind` backfill
+
+Every transaction carries a `methodKind: PaymentMethodKind` (`card`, `bank_transfer`, `wallet`, `cash`, `cheque`, `cryptocurrency`, `manual`, `other`). For hosted-checkout flows where the customer picks their method on the gateway's UI (Stripe Checkout, PayPal redirect, Razorpay Checkout), create the PaymentIntent with `methodKind: 'other'` — then call `transactionRepository.backfillMethodKind(transactionId, kind)` from your verification webhook handler once you know the actual choice. The backfill is an atomic CAS — allowed only when the doc still has `methodKind === 'other'` AND `status === 'pending'`; any other transition throws `MethodKindLockedError` (HTTP 409). For the Stripe case, `@classytic/revenue-stripe` exposes `stripePaymentIntentToKind(intent)` so the host doesn't write the mapping table itself.
+
+## Bank-feed `import()` requires `methodKind`
+
+`TransactionRepository.import()` (and the higher-level `drainSync` / `parseAndImport`) require an explicit `opts.methodKind` — no silent default. Pass `'bank_transfer'` for Plaid/OFX/CAMT/MT940 drains, `'card'` for a Stripe-balance import, `'wallet'` for PayPal exports, `'cryptocurrency'` for exchange CSVs. This forces every feed integration to be intentional about how its rows show up in downstream analytics and accounting reports.
+
 ## Architecture
 
 ```
 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-DJtLvz_7.mjs → bank-feed-ClxNob_I.mjs}

@@ -1,4 +1,4 @@
-import { l as ProviderNotFoundError } from "./errors-Dt46UZL_.mjs";
+import { u as ProviderNotFoundError } from "./errors-Bt5NRVMq.mjs";
 
 //#region src/providers/base.ts
 /**

package/dist/core/state-machines.mjs

@@ -1,6 +1,6 @@
 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-DoIr56O6.mjs";
-import { a as InvalidStateTransitionError } from "../errors-Dt46UZL_.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-Bt5NRVMq.mjs";
 import { defineStateMachine } from "@classytic/primitives/state-machine";
 
 //#region src/core/state-machines.ts

package/dist/{engine-types-txFXOiQS.d.mts → engine-types-ChFPg3kw.d.mts}

@@ -6,7 +6,8 @@ import { RepositoryPluginBundle, RevenueRepositories } from "./repositories/crea
 import { PluginType, Repository } from "@classytic/mongokit";
 import { TenantConfig } from "@classytic/repo-core/tenant";
 import mongoose, { Connection, Model, Schema } from "mongoose";
-import { EventTransport } from "@classytic/primitives/events";
+import { PaymentMethodKind } from "@classytic/primitives/payment-method-kind";
+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";
@@ -68,6 +69,7 @@ interface TransactionDocument {
   originalAmount?: number;
   originalCurrency?: string;
   method: string;
+  methodKind: PaymentMethodKind;
   status: string;
   /**
    * Optional embedded approval chain — P7. Hosts that gate manual /
@@ -325,17 +327,125 @@ interface RevenueSchemaOptions {
   };
 }
 //#endregion
-//#region src/repositories/transaction.repository.d.ts
-interface TransactionRepoDeps {
+//#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 store (PACKAGE_RULES §5.5 + P8). When present,
-   * every domain event is persisted via `outbox.save(event)` before the
-   * in-process `events.publish(event)` so the host's relay (arc's EventOutbox,
-   * a Postgres LISTEN/NOTIFY pump, Kafka Connect, …) can replay on transport
+   * 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
@@ -346,47 +456,30 @@ interface TransactionRepoDeps {
   bridges: RevenueBridges;
   commission?: CommissionConfig;
   defaultCurrency: string;
-  logger?: {
-    error(...args: unknown[]): void;
-  } | undefined;
 }
-declare class TransactionRepository extends Repository<TransactionDocument> {
-  private deps;
+declare class TransactionRepository extends RevenueRepositoryBase<TransactionDocument, TransactionRepoDeps> {
   constructor(model: Model<TransactionDocument>, plugins?: PluginType[]);
-  inject(deps: TransactionRepoDeps): void;
-  /**
-   * Thread `ctx.organizationId` (and future ctx fields) into mongokit
-   * options so the `multiTenantPlugin` can auto-scope filters, queries,
-   * and inserts. Merges any caller-supplied extras. Centralizing this
-   * here means every domain verb participates in scope isolation without
-   * per-call boilerplate.
-   */
-  private optsFromCtx;
   /**
    * Save an event to the host-owned outbox, session-bound when available.
    *
-   * When `session` is passed, the outbox row commits atomically with the
-   * business write (P8 true session-bound write). When absent, the save
-   * happens after commit — still durable via the host's relay, but with a
-   * small at-most-once window on process crash.
+   * 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.
    *
-   * Isolated try/catch: an outbox failure never throws out of this helper;
-   * the caller still issues a transport.publish.
+   * Logging happens before the re-throw so the failure surfaces in
+   * observability without losing the original stack trace.
    */
-  private saveToOutbox;
+  protected saveToOutbox(event: DomainEvent, session?: unknown): Promise<void>;
   /**
    * Publish an event to the in-process `EventTransport` after commit.
-   * Transport failure is logged — the host relay will still redeliver from
-   * the outbox, so in-process subscribers missing an event is recoverable.
-   */
-  private publishToTransport;
-  /**
-   * Non-transactional dispatch (used by verbs that don't open their own
-   * `withTransaction` block): outbox.save (session-bound when ctx provides
-   * one) → transport.publish. Matches arc's EventOutbox + MemoryEventTransport
-   * wiring bit-for-bit.
+   * 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.
    */
-  private dispatch;
+  protected publishToTransport(event: DomainEvent): Promise<void>;
   /** Creates transaction + calls provider. Returns the created transaction doc. */
   createPaymentIntent(params: {
     data?: Record<string, unknown>;
@@ -395,6 +488,7 @@ declare class TransactionRepository extends Repository<TransactionDocument> {
     amount: number;
     currency?: string;
     gateway: string;
+    methodKind: PaymentMethodKind;
     paymentData?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
     idempotencyKey?: string;
@@ -487,6 +581,7 @@ declare class TransactionRepository extends Repository<TransactionDocument> {
   import(rows: BankTransaction[], opts: {
     bankAccountId: string;
     source: string;
+    methodKind: PaymentMethodKind;
     method?: string;
   }, ctx?: RevenueContext): Promise<BankImportReport>;
   /**
@@ -507,6 +602,7 @@ declare class TransactionRepository extends Repository<TransactionDocument> {
    */
   drainSync(providerName: string, params: FetchTransactionsParams & {
     bankAccountId: string;
+    methodKind: PaymentMethodKind;
   }, ctx?: RevenueContext): Promise<{
     totalImported: number;
     totalUpdated: number;
@@ -526,6 +622,7 @@ declare class TransactionRepository extends Repository<TransactionDocument> {
     buffer: Buffer | string | Uint8Array;
     format?: string;
     bankAccountId: string;
+    methodKind: PaymentMethodKind;
   }, ctx?: RevenueContext): Promise<BankImportReport>;
   /**
    * Hand-keyed entry — treasurer logs a cash deposit, owner injects
@@ -539,6 +636,7 @@ declare class TransactionRepository extends Repository<TransactionDocument> {
     currency: string;
     flow: 'inflow' | 'outflow';
     type: string;
+    methodKind: PaymentMethodKind;
     description?: string;
     counterparty?: TransactionDocument['counterparty'];
     reference?: string;
@@ -549,6 +647,37 @@ declare class TransactionRepository extends Repository<TransactionDocument> {
     sourceModel?: string;
     metadata?: Record<string, unknown>;
   }, ctx?: RevenueContext): Promise<TransactionDocument>;
+  /**
+   * Backfill the `methodKind` on a Transaction created with kind
+   * unknown — the canonical use case is hosted-checkout (Stripe
+   * Checkout, PayPal redirect, Razorpay Checkout) where the customer
+   * picks their payment method on the gateway's UI, AFTER the host has
+   * already created the PaymentIntent + Transaction with
+   * `methodKind: 'other'`.
+   *
+   * Call this from your verification / webhook handler once you know
+   * the customer's actual choice — e.g. inside
+   * `payment_intent.succeeded`:
+   *
+   * ```ts
+   * await transactionRepository.backfillMethodKind(
+   *   tx._id,
+   *   stripePaymentIntentToKind(event.data.object),
+   *   ctx,
+   * );
+   * ```
+   *
+   * **Guard rule.** Atomic CAS — succeeds only when the doc has
+   * `methodKind === 'other'` AND `status === 'pending'`. Any other
+   * combination throws `MethodKindLockedError` (HTTP 409): once a
+   * transaction has a specific kind (or has settled past pending),
+   * silently overwriting it would corrupt downstream analytics and
+   * accounting reports.
+   *
+   * Emits `revenue:transaction.updated` with `changedFields:
+   * ['methodKind']` so subscribers can re-bucket the row.
+   */
+  backfillMethodKind(transactionId: string, methodKind: PaymentMethodKind, ctx?: RevenueContext): Promise<TransactionDocument>;
   /**
    * Match a bank-feed / manual transaction to GL accounts, optionally
    * cross-linking to an upstream payment-flow transaction.
@@ -677,33 +806,53 @@ declare class TransactionRepository extends Repository<TransactionDocument> {
 }
 //#endregion
 //#region src/repositories/subscription.repository.d.ts
-interface SubscriptionRepoDeps {
-  events: EventTransport;
-  /** Host-owned outbox (PACKAGE_RULES §5.5 + P8). See TransactionRepoDeps. */
-  outbox?: OutboxStore | undefined;
-  logger?: {
-    error(...args: unknown[]): void;
-  } | undefined;
-}
 /**
- * SubscriptionRepository — data layer + domain verbs.
+ * 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.
  *
- * CRUD inherited from mongokit. Domain verbs: activate, cancel, pause, resume.
+ * **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}.
  *
- * Events: each domain verb calls `this.deps.events.publish(createEvent(...))`
- * with a fully-qualified `REVENUE_EVENTS.*` name. Hosts can subscribe glob-style
- * via `revenue.events.subscribe('revenue:subscription.*', handler)` — the
- * injected transport is arc-compatible (PACKAGE_RULES §13–§14).
+ * **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 Repository<SubscriptionDocument> {
-  private deps;
+declare class SubscriptionRepository extends RevenueRepositoryBase<SubscriptionDocument, SubscriptionRepoDeps> {
   constructor(model: Model<SubscriptionDocument>, plugins?: PluginType[]);
-  inject(deps: SubscriptionRepoDeps): void;
-  /**
-   * Host-owned outbox save → in-process transport publish (PACKAGE_RULES P8).
-   * Session-bound when `ctx.session` is present (atomic outbox row write).
-   */
-  private dispatch;
   activate(subscriptionId: string, options?: {
     timestamp?: Date;
   }, ctx?: RevenueContext): Promise<SubscriptionDocument>;
@@ -720,37 +869,38 @@ declare class SubscriptionRepository extends Repository<SubscriptionDocument> {
 }
 //#endregion
 //#region src/repositories/settlement.repository.d.ts
-interface SettlementRepoDeps {
-  events: EventTransport;
-  /** Host-owned outbox (PACKAGE_RULES §5.5 + P8). See TransactionRepoDeps. */
-  outbox?: OutboxStore | undefined;
+/**
+ * Deps for {@link SettlementRepository}. Adds the optional
+ * `RevenueBridges` (ledger / notification ports) on top of
+ * {@link BaseRevenueRepoDeps}.
+ */
+interface SettlementRepoDeps extends BaseRevenueRepoDeps {
   bridges: RevenueBridges;
-  logger?: {
-    error(...args: unknown[]): void;
-  } | undefined;
 }
 interface SettlementProcessingError {
   settlementId: SettlementDocument['_id'];
   error: unknown;
 }
 /**
- * SettlementRepository — data layer + domain verbs.
+ * 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`.
  *
- * CRUD inherited from mongokit. Domain verbs: schedule, processPending, complete, fail.
+ * **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+.
  *
- * Events are published via the injected `events` transport (arc-compatible).
- * Hosts subscribe glob-style via `revenue.events.subscribe('revenue:settlement.*', h)`.
- * See PACKAGE_RULES §13–§14.
+ * 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 Repository<SettlementDocument> {
-  private deps;
+declare class SettlementRepository extends RevenueRepositoryBase<SettlementDocument, SettlementRepoDeps> {
   constructor(model: Model<SettlementDocument>, plugins?: PluginType[]);
-  inject(deps: SettlementRepoDeps): void;
-  /**
-   * Host-owned outbox save → in-process transport publish (PACKAGE_RULES P8).
-   * Session-bound when `ctx.session` is present (atomic outbox row write).
-   */
-  private dispatch;
   schedule(params: {
     organizationId: string;
     recipientId: string;

package/dist/enums/index.mjs

@@ -1,5 +1,5 @@
 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 { 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-DoIr56O6.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 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";
 
 export { BANK_FEED_SOURCE, BANK_FEED_SOURCE_VALUES, BANK_FEED_STATUS, BANK_FEED_STATUS_VALUES, HOLD_REASON, HOLD_REASON_VALUES, HOLD_STATUS, HOLD_STATUS_VALUES, LIBRARY_CATEGORIES, LIBRARY_CATEGORY_VALUES, MONETIZATION_TYPES, MONETIZATION_TYPE_VALUES, PAYMENT_GATEWAY_TYPE, PAYMENT_GATEWAY_TYPE_VALUES, PAYMENT_STATUS, PAYMENT_STATUS_VALUES, PAYOUT_METHOD, PAYOUT_METHOD_VALUES, PLAN_KEYS, PLAN_KEY_VALUES, RELEASE_REASON, RELEASE_REASON_VALUES, SETTLEMENT_STATUS, SETTLEMENT_STATUS_VALUES, SETTLEMENT_TYPE, SETTLEMENT_TYPE_VALUES, SPLIT_STATUS, SPLIT_STATUS_VALUES, SPLIT_TYPE, SPLIT_TYPE_VALUES, SUBSCRIPTION_STATUS, SUBSCRIPTION_STATUS_VALUES, TRANSACTION_FLOW, TRANSACTION_FLOW_VALUES, TRANSACTION_KIND, TRANSACTION_KIND_VALUES, TRANSACTION_STATUS, TRANSACTION_STATUS_VALUES, initialStatusFor, isBankFeedSource, isBankFeedStatus, isHoldReason, isHoldStatus, isLibraryCategory, isMonetizationType, isPaymentGatewayType, isPaymentStatus, isPayoutMethod, isPlanKey, isReleaseReason, isSettlementStatus, isSettlementType, isSplitStatus, isSplitType, isStatusValidForKind, isSubscriptionStatus, isTransactionFlow, isTransactionKind, isTransactionStatus, statusesForKind };