@classytic/revenue 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -3,6 +3,47 @@
 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.6.0]
+
+### Added — generalized settlement rollups (`summary` + `breakdownByRecipient`)
+
+`recipientBalance` only rolled up ONE recipient, forcing hosts to hand-roll raw
+aggregations for platform-wide / per-recipient / cross-org views. Two reusable
+primitives now cover all of them (the `recipientBalance` status+due bucketing,
+generalized — one tenant-scoped `aggregatePipeline`, never a raw `Model.aggregate`):
+
+- **`summary(filter = {}, ctx)` → `SettlementSummary`** — the money-state
+  (`held / available / processing / paidOut / pending / failed / lifetime /
+  currency`) for an ARBITRARY filter: a recipient, an org, or the whole platform
+  (pass `_bypassTenant` in ctx). Backs platform reconciliation + cross-org
+  earnings.
+- **`breakdownByRecipient(filter = {}, ctx)` → `RecipientBreakdown[]`** — one
+  rollup per distinct `(recipientId, recipientType)` (plus first-seen `role`),
+  for a "who is owed what" platform view.
+
+`recipientBalance` is now a thin wrapper over `summary({ recipientId, … })`.
+Exported types: `SettlementSummary`, `RecipientBreakdown`. No migration; no
+breaking change to `recipientBalance`'s shape.
+
+## [2.5.0]
+
+### Added — `SettlementRepository.recipientBalance()` (the seller/creator "wallet")
+
+`recipientBalance(recipientId, { recipientType?, currency? }, ctx)` returns a
+recipient's payout balance bucketed by settlement status —
+`{ pending, held, available, processing, paidOut, failed, lifetime, currency }`
+in minor units. `pending` splits into `held` (escrowed — `scheduledAt` in the
+future) and `available` (cleared — due now), so a marketplace can show "in
+clearance" vs "ready to pay". One tenant-scoped `aggregatePipeline` over the
+`{ recipientId, status }` index, so hosts stop hand-rolling a raw
+`Model.aggregate` (which bypasses multi-tenant scope).
+
+### Added — `processPending({ recipientId })` filter
+
+`processPending` now accepts an optional `recipientId` so a host can pay out a
+single seller/participant (gating each via their own KYC/eligibility check)
+instead of only by organization.
+
 ## [2.4.0] - 2026-06-14
 
 ### Added — `settled` bank-feed/manual status + `settle()` / `unsettle()` verbs

package/dist/{audit-DRKuLBFO.d.mts → audit-BkDdPSed.d.mts}

@@ -60,6 +60,7 @@ interface SplitInfo {
 }
 declare function calculateSplits(amount: number, rules: SplitRule[], gatewayFeeRate?: number): SplitInfo[];
 declare function calculateOrganizationPayout(amount: number, splits: SplitInfo[]): number;
+declare function reverseSplits(originalSplits: SplitInfo[], originalAmount: number, refundAmount: number): SplitInfo[];
 //#endregion
 //#region src/shared/formatters/money.d.ts
 /**
@@ -86,4 +87,4 @@ declare function getLastStateChange(doc: {
   metadata?: Record<string, unknown>;
 }): StateChangeEvent | undefined;
 //#endregion
-export { SplitInfo as A, validateTaxCalculation as B, multiplyMoney as C, toCurrencyCode as D, sumMoney as E, TaxConfig as F, calculateCommission as H, TaxType as I, calculateTax as L, calculateOrganizationPayout as M, calculateSplits as N, toMajor$1 as O, TaxCalculation as P, getTaxType as R, money$1 as S, subtractMoney as T, reverseCommission as U, CommissionInfo as V, isMoney as _, CurrencyCode as a, isZeroMoney as b, Money as c, addMoney as d, compareMoney as f, isCurrencyCode as g, fromSmallestUnit as h, CURRENCIES as i, SplitRule as j, toSmallestUnit as k, MoneyValue as l, fromMajor$1 as m, getAuditTrail as n, CurrencyMismatchError as o, equalsMoney as p, getLastStateChange as r, MINOR_UNIT_FACTOR as s, appendAuditEvent as t, absMoney as u, isNegativeMoney as v, negateMoney as w, minorUnitFactor as x, isPositiveMoney as y, reverseTax as z };
+export { SplitInfo as A, reverseTax as B, multiplyMoney as C, toCurrencyCode as D, sumMoney as E, TaxCalculation as F, CommissionInfo as H, TaxConfig as I, TaxType as L, calculateOrganizationPayout as M, calculateSplits as N, toMajor$1 as O, reverseSplits as P, calculateTax as R, money$1 as S, subtractMoney as T, calculateCommission as U, validateTaxCalculation as V, reverseCommission as W, isMoney as _, CurrencyCode as a, isZeroMoney as b, Money as c, addMoney as d, compareMoney as f, isCurrencyCode as g, fromSmallestUnit as h, CURRENCIES as i, SplitRule as j, toSmallestUnit as k, MoneyValue as l, fromMajor$1 as m, getAuditTrail as n, CurrencyMismatchError as o, equalsMoney as p, getLastStateChange as r, MINOR_UNIT_FACTOR as s, appendAuditEvent as t, absMoney as u, isNegativeMoney as v, negateMoney as w, minorUnitFactor as x, isPositiveMoney as y, getTaxType as z };

package/dist/{engine-types-BU8kkttr.d.mts → engine-types-D6ijamqA.d.mts}

@@ -922,6 +922,42 @@ interface SettlementProcessingError {
   settlementId: SettlementDocument['_id'];
   error: unknown;
 }
+/**
+ * A recipient's payout balance — the amounts the platform has scheduled,
+ * is processing, has paid, or failed to pay, in minor units. The "wallet"
+ * view a marketplace shows a seller/creator. Derived from settlement status;
+ * tenant-scoped.
+ */
+interface RecipientBalance {
+  recipientId: string;
+  currency: string | null;
+  /** Scheduled, awaiting payout (status: pending) = held + available. */
+  pending: number;
+  /** Pending but still in the clearance window (`scheduledAt` in the future) — escrowed, not yet payable. */
+  held: number;
+  /** Pending and due (`scheduledAt <= now`) — cleared, ready to pay out. */
+  available: number;
+  /** Payout in flight (status: processing). */
+  processing: number;
+  /** Paid out, lifetime (status: completed). */
+  paidOut: number;
+  /** Failed payouts (status: failed). */
+  failed: number;
+  /** pending + processing + paidOut — the total the platform has committed to this recipient. */
+  lifetime: number;
+}
+/**
+ * Settlement money-state for an arbitrary filter (a recipient, an org, or the
+ * whole platform) — the same status+due rollup as {@link RecipientBalance} but
+ * not tied to a single recipient. The reusable shape behind `summary`.
+ */
+type SettlementSummary = Omit<RecipientBalance, 'recipientId'>;
+/** One row of {@link SettlementRepository.breakdownByRecipient}. */
+interface RecipientBreakdown extends RecipientBalance {
+  recipientType: string;
+  /** First-seen settlement role (creator_earning | co_instructor | referrer | …). */
+  role: string | null;
+}
 /**
  * SettlementRepository — payouts to recipients (organizations, vendors,
  * affiliates).
@@ -962,7 +998,8 @@ declare class SettlementRepository extends RevenueRepositoryBase<SettlementDocum
   processPending(options?: {
     limit?: number;
     organizationId?: string;
-    payoutMethod?: string;
+    payoutMethod?: string; /** Restrict the sweep to a single recipient — pay one seller/participant. */
+    recipientId?: string;
     dryRun?: boolean;
   }, ctx?: RevenueContext): Promise<{
     processed: number;
@@ -982,6 +1019,26 @@ declare class SettlementRepository extends RevenueRepositoryBase<SettlementDocum
     code?: string;
     retry?: boolean;
   }, ctx?: RevenueContext): Promise<SettlementDocument>;
+  /**
+   * Settlement money-state for an ARBITRARY filter — a recipient, an org, or
+   * the whole platform (pass `_bypassTenant` in ctx to span every org). One
+   * tenant-scoped `aggregatePipeline` (the `{ recipientId, status }` index backs
+   * the `$match`), never a raw `Model.aggregate`. The reusable rollup behind
+   * `recipientBalance`, platform reconciliation, and cross-org earnings.
+   */
+  summary(filter?: Record<string, unknown>, ctx?: RevenueContext): Promise<SettlementSummary>;
+  /**
+   * Per-recipient settlement rollup — one {@link RecipientBreakdown} per
+   * distinct (recipientId, recipientType) matching `filter`. The reusable list
+   * behind a platform "who is owed what" view; pass `_bypassTenant` to span all
+   * orgs.
+   */
+  breakdownByRecipient(filter?: Record<string, unknown>, ctx?: RevenueContext): Promise<RecipientBreakdown[]>;
+  /** One recipient's wallet — a thin `summary` over `{ recipientId, … }`. */
+  recipientBalance(recipientId: string, options?: {
+    recipientType?: string;
+    currency?: string;
+  }, ctx?: RevenueContext): Promise<RecipientBalance>;
 }
 //#endregion
 //#region src/engine/engine-types.d.ts
@@ -1236,4 +1293,4 @@ interface RevenueEngine {
   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 };
+export { TransactionDocument as _, RevenueConfig as a, RecipientBreakdown as c, SubscriptionRepository as d, TransactionRepository as f, SubscriptionDocument as g, SettlementDocument as h, RetryConfig as i, SettlementRepository as l, RevenueSchemaOptions as m, BankFeedModuleConfig as n, RevenueEngine as o, RevenueModels as p, CommissionConfig as r, RecipientBalance as s, BankFeedIndexConfig as t, SettlementSummary as u };

package/dist/{escrow.schema-Cklvlywy.d.mts → escrow.schema-DSx7EywJ.d.mts}

@@ -110,29 +110,10 @@ declare const transactionBaseSchema: z.ZodObject<{
   metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 declare const transactionCreateSchema: z.ZodObject<{
-  organizationId: z.ZodOptional<z.ZodString>;
-  customerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  status: z.ZodDefault<z.ZodString>;
   type: z.ZodString;
-  flow: z.ZodEnum<{
-    inflow: "inflow";
-    outflow: "outflow";
-  }>;
-  tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
   amount: z.ZodNumber;
   currency: z.ZodString;
-  fee: z.ZodDefault<z.ZodNumber>;
-  tax: z.ZodDefault<z.ZodNumber>;
-  net: z.ZodDefault<z.ZodNumber>;
-  taxDetails: z.ZodOptional<z.ZodObject<{
-    type: z.ZodOptional<z.ZodEnum<{
-      sales_tax: "sales_tax";
-      vat: "vat";
-      none: "none";
-    }>>;
-    rate: z.ZodOptional<z.ZodNumber>;
-    isInclusive: z.ZodOptional<z.ZodBoolean>;
-  }, z.core.$strip>>;
-  method: z.ZodString;
   methodKind: z.ZodEnum<{
     manual: "manual";
     bank_transfer: "bank_transfer";
@@ -148,8 +129,39 @@ declare const transactionCreateSchema: z.ZodObject<{
     cheque: "cheque";
     other: "other";
   }>;
-  status: z.ZodDefault<z.ZodString>;
   metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  customerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  splits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    type: z.ZodString;
+    recipientId: z.ZodString;
+    recipientType: z.ZodString;
+    rate: z.ZodNumber;
+    grossAmount: z.ZodNumber;
+    gatewayFeeRate: z.ZodNumber;
+    gatewayFeeAmount: z.ZodNumber;
+    netAmount: z.ZodNumber;
+    status: z.ZodString;
+  }, z.core.$strip>>>;
+  relatedTransactionId: z.ZodOptional<z.ZodString>;
+  organizationId: z.ZodOptional<z.ZodString>;
+  flow: z.ZodEnum<{
+    inflow: "inflow";
+    outflow: "outflow";
+  }>;
+  tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  fee: z.ZodDefault<z.ZodNumber>;
+  tax: z.ZodDefault<z.ZodNumber>;
+  net: z.ZodDefault<z.ZodNumber>;
+  taxDetails: z.ZodOptional<z.ZodObject<{
+    type: z.ZodOptional<z.ZodEnum<{
+      sales_tax: "sales_tax";
+      vat: "vat";
+      none: "none";
+    }>>;
+    rate: z.ZodOptional<z.ZodNumber>;
+    isInclusive: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>>;
+  method: z.ZodString;
   gateway: z.ZodOptional<z.ZodObject<{
     type: z.ZodString;
     sessionId: z.ZodOptional<z.ZodString>;
@@ -167,17 +179,6 @@ declare const transactionCreateSchema: z.ZodObject<{
     netAmount: z.ZodNumber;
     status: z.ZodString;
   }, z.core.$strip>>;
-  splits: z.ZodOptional<z.ZodArray<z.ZodObject<{
-    type: z.ZodString;
-    recipientId: z.ZodString;
-    recipientType: z.ZodString;
-    rate: z.ZodNumber;
-    grossAmount: z.ZodNumber;
-    gatewayFeeRate: z.ZodNumber;
-    gatewayFeeAmount: z.ZodNumber;
-    netAmount: z.ZodNumber;
-    status: z.ZodString;
-  }, z.core.$strip>>>;
   hold: z.ZodOptional<z.ZodObject<{
     status: z.ZodString;
     heldAmount: z.ZodNumber;
@@ -200,7 +201,6 @@ declare const transactionCreateSchema: z.ZodObject<{
   }, z.core.$strip>>;
   sourceId: z.ZodOptional<z.ZodString>;
   sourceModel: z.ZodOptional<z.ZodString>;
-  relatedTransactionId: z.ZodOptional<z.ZodString>;
   idempotencyKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const transactionUpdateSchema: z.ZodObject<{
@@ -360,12 +360,12 @@ declare const subscriptionBaseSchema: z.ZodObject<{
   metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 declare const subscriptionCreateSchema: z.ZodObject<{
-  organizationId: z.ZodOptional<z.ZodString>;
-  customerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   amount: z.ZodNumber;
   currency: z.ZodOptional<z.ZodString>;
-  paymentIntentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  customerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  organizationId: z.ZodOptional<z.ZodString>;
+  paymentIntentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   planKey: z.ZodString;
   transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   startDate: z.ZodOptional<z.ZodCoercedDate<unknown>>;
@@ -478,7 +478,6 @@ declare const settlementBaseSchema: z.ZodObject<{
   metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 declare const settlementCreateSchema: z.ZodObject<{
-  organizationId: z.ZodString;
   type: z.ZodEnum<{
     split_payout: "split_payout";
     platform_withdrawal: "platform_withdrawal";
@@ -504,6 +503,9 @@ declare const settlementCreateSchema: z.ZodObject<{
     crypto: "crypto";
     check: "check";
   }>;
+  scheduledAt: z.ZodDefault<z.ZodCoercedDate<unknown>>;
+  notes: z.ZodOptional<z.ZodString>;
+  organizationId: z.ZodString;
   sourceTransactionIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
   sourceSplitIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
   bankTransferDetails: z.ZodOptional<z.ZodObject<{
@@ -529,8 +531,6 @@ declare const settlementCreateSchema: z.ZodObject<{
     transactionHash: z.ZodOptional<z.ZodString>;
     transferredAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
   }, z.core.$strip>>;
-  scheduledAt: z.ZodDefault<z.ZodCoercedDate<unknown>>;
-  notes: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const settlementUpdateSchema: z.ZodObject<{
   publicId: z.ZodOptional<z.ZodOptional<z.ZodString>>;

package/dist/index.d.mts

@@ -6,10 +6,10 @@ import { BANK_FEED_STATE_MACHINE, HOLD_STATE_MACHINE, MANUAL_STATE_MACHINE, PAYM
 import { a as isMonetizationType, c as PAYMENT_STATUS, d as PaymentGatewayTypeValue, f as PaymentStatus, h as isPaymentStatus, i as MonetizationTypes, l as PAYMENT_STATUS_VALUES, m as isPaymentGatewayType, n as MONETIZATION_TYPE_VALUES, o as PAYMENT_GATEWAY_TYPE, p as PaymentStatusValue, r as MonetizationTypeValue, s as PAYMENT_GATEWAY_TYPE_VALUES, t as MONETIZATION_TYPES, u as PaymentGatewayType } from "./monetization.enums-DzAI4sT7.mjs";
 import { D as RevenueEventSchema, E as RevenueEventPayloadOf, T as RevenueEventDefinition, _t as InProcessRevenueBusOptions, ft as revenueEventDefinitions, gt as InProcessRevenueBus, ht as createEvent, mt as RevenueEventName, pt as REVENUE_EVENTS } from "./revenue-event-catalog-BU_KYN2-.mjs";
 import { a as BankFeedProviderRegistry, c as ParseUploadParams, d as PaymentProvider, i as BankFeedProviderCapabilities, l as ParseUploadResult, n as createProviderRegistry, o as FetchTransactionsParams, r as BankFeedProvider, s as FetchTransactionsResult, t as ProviderRegistry, u as createBankFeedProviderRegistry } from "./registry-DSG7x-Cl.mjs";
-import { a as RevenueConfig, c as SubscriptionRepository, d as RevenueSchemaOptions, f as SettlementDocument, i as RetryConfig, l as TransactionRepository, m as TransactionDocument, n as BankFeedModuleConfig, o as RevenueEngine, p as SubscriptionDocument, r as CommissionConfig, s as SettlementRepository, t as BankFeedIndexConfig, u as RevenueModels } from "./engine-types-BU8kkttr.mjs";
+import { _ as TransactionDocument, a as RevenueConfig, c as RecipientBreakdown, d as SubscriptionRepository, f as TransactionRepository, g as SubscriptionDocument, h as SettlementDocument, i as RetryConfig, l as SettlementRepository, m as RevenueSchemaOptions, n as BankFeedModuleConfig, o as RevenueEngine, p as RevenueModels, r as CommissionConfig, s as RecipientBalance, t as BankFeedIndexConfig, u as SettlementSummary } from "./engine-types-D6ijamqA.mjs";
 import { RepositoryPluginBundle, RevenueRepositories } from "./repositories/create-repositories.mjs";
-import { A as transactionBaseSchema, C as subscriptionBaseSchema, D as TransactionCreateInput, E as subscriptionUpdateSchema, M as transactionListFilterSchema, N as transactionUpdateSchema, O as TransactionListFilter, S as SubscriptionUpdateInput, T as subscriptionListFilterSchema, _ as settlementCreateSchema, a as escrowReleaseSchema, b as SubscriptionCreateInput, c as PaymentVerifyInput, d as paymentVerifySchema, f as refundSchema, g as settlementBaseSchema, h as SettlementUpdateInput, i as escrowHoldSchema, j as transactionCreateSchema, k as TransactionUpdateInput, l as RefundInput, m as SettlementListFilter, n as EscrowReleaseInput, o as splitRuleSchema, p as SettlementCreateInput, r as SplitRuleInput, s as PaymentIntentInput, t as EscrowHoldInput, u as paymentIntentSchema, v as settlementListFilterSchema, w as subscriptionCreateSchema, x as SubscriptionListFilter, y as settlementUpdateSchema } from "./escrow.schema-Cklvlywy.mjs";
-import { A as SplitInfo, B as validateTaxCalculation, C as multiplyMoney, D as toCurrencyCode, E as sumMoney, F as TaxConfig, H as calculateCommission, I as TaxType, L as calculateTax, M as calculateOrganizationPayout, N as calculateSplits, O as toMajor, P as TaxCalculation, R as getTaxType, S as money, T as subtractMoney, U as reverseCommission, V as CommissionInfo, _ as isMoney, a as CurrencyCode, b as isZeroMoney, c as Money, d as addMoney, f as compareMoney, g as isCurrencyCode, h as fromSmallestUnit, i as CURRENCIES, j as SplitRule, k as toSmallestUnit, l as MoneyValue, m as fromMajor, n as getAuditTrail, o as CurrencyMismatchError, p as equalsMoney, r as getLastStateChange, s as MINOR_UNIT_FACTOR, t as appendAuditEvent, u as absMoney, v as isNegativeMoney, w as negateMoney, x as minorUnitFactor, y as isPositiveMoney, z as reverseTax } from "./audit-DRKuLBFO.mjs";
+import { A as transactionBaseSchema, C as subscriptionBaseSchema, D as TransactionCreateInput, E as subscriptionUpdateSchema, M as transactionListFilterSchema, N as transactionUpdateSchema, O as TransactionListFilter, S as SubscriptionUpdateInput, T as subscriptionListFilterSchema, _ as settlementCreateSchema, a as escrowReleaseSchema, b as SubscriptionCreateInput, c as PaymentVerifyInput, d as paymentVerifySchema, f as refundSchema, g as settlementBaseSchema, h as SettlementUpdateInput, i as escrowHoldSchema, j as transactionCreateSchema, k as TransactionUpdateInput, l as RefundInput, m as SettlementListFilter, n as EscrowReleaseInput, o as splitRuleSchema, p as SettlementCreateInput, r as SplitRuleInput, s as PaymentIntentInput, t as EscrowHoldInput, u as paymentIntentSchema, v as settlementListFilterSchema, w as subscriptionCreateSchema, x as SubscriptionListFilter, y as settlementUpdateSchema } from "./escrow.schema-DSx7EywJ.mjs";
+import { A as SplitInfo, B as reverseTax, C as multiplyMoney, D as toCurrencyCode, E as sumMoney, F as TaxCalculation, H as CommissionInfo, I as TaxConfig, L as TaxType, M as calculateOrganizationPayout, N as calculateSplits, O as toMajor, R as calculateTax, S as money, T as subtractMoney, U as calculateCommission, V as validateTaxCalculation, W as reverseCommission, _ as isMoney, a as CurrencyCode, b as isZeroMoney, c as Money, d as addMoney, f as compareMoney, g as isCurrencyCode, h as fromSmallestUnit, i as CURRENCIES, j as SplitRule, k as toSmallestUnit, l as MoneyValue, m as fromMajor, n as getAuditTrail, o as CurrencyMismatchError, p as equalsMoney, r as getLastStateChange, s as MINOR_UNIT_FACTOR, t as appendAuditEvent, u as absMoney, v as isNegativeMoney, w as negateMoney, x as minorUnitFactor, y as isPositiveMoney, z as getTaxType } from "./audit-BkDdPSed.mjs";
 import { HookHandler, PluginContext, PluginManager, RevenuePluginDefinition } from "./plugins/plugin.interface.mjs";
 import { DomainEvent, DomainEvent as DomainEvent$1, EventHandler, EventTransport } from "@classytic/primitives/events";
 import { InvalidOutboxEventError, OutboxAcknowledgeOptions, OutboxAcknowledgeOptions as OutboxAcknowledgeOptions$1, OutboxClaimOptions, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStore, OutboxStore as OutboxStore$1, OutboxWriteOptions, OutboxWriteOptions as OutboxWriteOptions$1 } from "@classytic/primitives/outbox";
@@ -115,4 +115,4 @@ declare class BankFeedProviderNotFoundError extends RevenueError {
   constructor(providerName: string);
 }
 //#endregion
-export { AlreadyVerifiedError, type AnalyticsBridge, BANK_FEED_SOURCE, BANK_FEED_SOURCE_VALUES, BANK_FEED_STATE_MACHINE, BANK_FEED_STATUS, BANK_FEED_STATUS_VALUES, BankFeedImportError, type BankFeedIndexConfig, type BankFeedModuleConfig, BankFeedProvider, type BankFeedProviderCapabilities, BankFeedProviderNotFoundError, BankFeedProviderRegistry, BankFeedSourceValue, BankFeedStatusValue, CURRENCIES, type CommissionConfig, type CommissionInfo, ConfigurationError, type CurrencyBridge, type CurrencyCode, CurrencyMismatchError, type CustomerBridge, type DomainEvent, EscrowHoldInput, EscrowReleaseInput, type EventHandler, type EventTransport, type FetchTransactionsParams, type FetchTransactionsResult, HOLD_REASON, HOLD_REASON_VALUES, HOLD_STATE_MACHINE, HOLD_STATUS, HOLD_STATUS_VALUES, HoldReason, HoldReasonValue, HoldStatus, HoldStatusValue, type HookHandler, InProcessRevenueBus, type InProcessRevenueBusOptions, InvalidOutboxEventError, InvalidStateTransitionError, LIBRARY_CATEGORIES, LIBRARY_CATEGORY_VALUES, type LedgerBridge, LibraryCategories, LibraryCategoryValue, MANUAL_STATE_MACHINE, MINOR_UNIT_FACTOR, MONETIZATION_TYPES, MONETIZATION_TYPE_VALUES, MemoryOutboxStore, MethodKindLockedError, MonetizationTypeValue, MonetizationTypes, type Money, type MoneyValue, type NotificationBridge, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, type OutboxFailureContext, type OutboxFailureDecision, type OutboxFailurePolicy, OutboxOwnershipError, type OutboxStore, type OutboxWriteOptions, PAYMENT_FLOW_STATE_MACHINE, PAYMENT_GATEWAY_TYPE, PAYMENT_GATEWAY_TYPE_VALUES, PAYMENT_STATUS, PAYMENT_STATUS_VALUES, PAYOUT_METHOD, PAYOUT_METHOD_VALUES, PLAN_KEYS, PLAN_KEY_VALUES, type ParseUploadParams, type ParseUploadResult, PaymentGatewayType, PaymentGatewayTypeValue, PaymentIntentCreationError, PaymentIntentInput, PaymentProvider, PaymentStatus, PaymentStatusValue, PaymentVerificationError, PaymentVerifyInput, PayoutMethod, PayoutMethodValue, PlanKeyValue, PlanKeys, type PluginContext, PluginManager, ProviderCapabilityError, ProviderNotFoundError, ProviderRegistry, RELEASE_REASON, RELEASE_REASON_VALUES, REVENUE_EVENTS, RefundInput, RefundNotSupportedError, ReleaseReason, ReleaseReasonValue, type RepositoryPluginBundle, type Result, type RetryConfig, type RevenueBridges, type RevenueConfig, type RevenueContext, type RevenueEngine, RevenueError, type RevenueEventDefinition, type RevenueEventName, type RevenueEventPayloadOf, type RevenueEventSchema, type RevenueModels, type RevenuePluginDefinition, type RevenueRepositories, type RevenueSchemaOptions, SETTLEMENT_STATE_MACHINE, SETTLEMENT_STATUS, SETTLEMENT_STATUS_VALUES, SETTLEMENT_TYPE, SETTLEMENT_TYPE_VALUES, SPLIT_STATE_MACHINE, SPLIT_STATUS, SPLIT_STATUS_VALUES, SPLIT_TYPE, SPLIT_TYPE_VALUES, SUBSCRIPTION_STATE_MACHINE, SUBSCRIPTION_STATUS, SUBSCRIPTION_STATUS_VALUES, SettlementCreateInput, type SettlementDocument, SettlementListFilter, SettlementNotFoundError, SettlementRepository, SettlementStatus, SettlementStatusValue, SettlementType, SettlementTypeValue, SettlementUpdateInput, type SplitInfo, type SplitRule, SplitRuleInput, SplitStatus, SplitStatusValue, SplitType, SplitTypeValue, type StateChangeEvent, StateMachine, SubscriptionCreateInput, type SubscriptionDocument, SubscriptionListFilter, SubscriptionNotFoundError, SubscriptionRepository, SubscriptionStatus, SubscriptionStatusValue, SubscriptionUpdateInput, TRANSACTION_FLOW, TRANSACTION_FLOW_VALUES, TRANSACTION_KIND, TRANSACTION_KIND_VALUES, TRANSACTION_STATE_MACHINE, TRANSACTION_STATUS, TRANSACTION_STATUS_VALUES, type TaxBridge, type TaxCalculation, type TaxConfig, type TaxType, TransactionCreateInput, type TransactionDocument, TransactionFlow, TransactionFlowValue, TransactionKind, TransactionKindValue, TransactionListFilter, TransactionNotFoundError, TransactionRepository, TransactionStatus, TransactionStatusValue, TransactionUpdateInput, ValidationError, WrongTransactionKindError, absMoney, addMoney, appendAuditEvent, calculateCommission, calculateOrganizationPayout, calculateSplits, calculateTax, compareMoney, createBankFeedProviderRegistry, createEvent, createProviderRegistry, createRevenue, equalsMoney, err, escrowHoldSchema, escrowReleaseSchema, fromMajor, fromSmallestUnit, getAuditTrail, getLastStateChange, getTaxType, initialStatusFor, isBankFeedSource, isBankFeedStatus, isCurrencyCode, isErr, isHoldReason, isHoldStatus, isLibraryCategory, isMonetizationType, isMoney, isNegativeMoney, isOk, isPaymentGatewayType, isPaymentStatus, isPayoutMethod, isPlanKey, isPositiveMoney, isReleaseReason, isSettlementStatus, isSettlementType, isSplitStatus, isSplitType, isStatusValidForKind, isSubscriptionStatus, isTransactionFlow, isTransactionKind, isTransactionStatus, isZeroMoney, minorUnitFactor, money, multiplyMoney, negateMoney, ok, paymentIntentSchema, paymentVerifySchema, refundSchema, revenueEventDefinitions, reverseCommission, reverseTax, settlementBaseSchema, settlementCreateSchema, settlementListFilterSchema, settlementUpdateSchema, smFor, splitRuleSchema, statusesForKind, subscriptionBaseSchema, subscriptionCreateSchema, subscriptionListFilterSchema, subscriptionUpdateSchema, subtractMoney, sumMoney, toCurrencyCode, toMajor, toSmallestUnit, transactionBaseSchema, transactionCreateSchema, transactionListFilterSchema, transactionUpdateSchema, validateTaxCalculation };
+export { AlreadyVerifiedError, type AnalyticsBridge, BANK_FEED_SOURCE, BANK_FEED_SOURCE_VALUES, BANK_FEED_STATE_MACHINE, BANK_FEED_STATUS, BANK_FEED_STATUS_VALUES, BankFeedImportError, type BankFeedIndexConfig, type BankFeedModuleConfig, BankFeedProvider, type BankFeedProviderCapabilities, BankFeedProviderNotFoundError, BankFeedProviderRegistry, BankFeedSourceValue, BankFeedStatusValue, CURRENCIES, type CommissionConfig, type CommissionInfo, ConfigurationError, type CurrencyBridge, type CurrencyCode, CurrencyMismatchError, type CustomerBridge, type DomainEvent, EscrowHoldInput, EscrowReleaseInput, type EventHandler, type EventTransport, type FetchTransactionsParams, type FetchTransactionsResult, HOLD_REASON, HOLD_REASON_VALUES, HOLD_STATE_MACHINE, HOLD_STATUS, HOLD_STATUS_VALUES, HoldReason, HoldReasonValue, HoldStatus, HoldStatusValue, type HookHandler, InProcessRevenueBus, type InProcessRevenueBusOptions, InvalidOutboxEventError, InvalidStateTransitionError, LIBRARY_CATEGORIES, LIBRARY_CATEGORY_VALUES, type LedgerBridge, LibraryCategories, LibraryCategoryValue, MANUAL_STATE_MACHINE, MINOR_UNIT_FACTOR, MONETIZATION_TYPES, MONETIZATION_TYPE_VALUES, MemoryOutboxStore, MethodKindLockedError, MonetizationTypeValue, MonetizationTypes, type Money, type MoneyValue, type NotificationBridge, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, type OutboxFailureContext, type OutboxFailureDecision, type OutboxFailurePolicy, OutboxOwnershipError, type OutboxStore, type OutboxWriteOptions, PAYMENT_FLOW_STATE_MACHINE, PAYMENT_GATEWAY_TYPE, PAYMENT_GATEWAY_TYPE_VALUES, PAYMENT_STATUS, PAYMENT_STATUS_VALUES, PAYOUT_METHOD, PAYOUT_METHOD_VALUES, PLAN_KEYS, PLAN_KEY_VALUES, type ParseUploadParams, type ParseUploadResult, PaymentGatewayType, PaymentGatewayTypeValue, PaymentIntentCreationError, PaymentIntentInput, PaymentProvider, PaymentStatus, PaymentStatusValue, PaymentVerificationError, PaymentVerifyInput, PayoutMethod, PayoutMethodValue, PlanKeyValue, PlanKeys, type PluginContext, PluginManager, ProviderCapabilityError, ProviderNotFoundError, ProviderRegistry, RELEASE_REASON, RELEASE_REASON_VALUES, REVENUE_EVENTS, type RecipientBalance, type RecipientBreakdown, RefundInput, RefundNotSupportedError, ReleaseReason, ReleaseReasonValue, type RepositoryPluginBundle, type Result, type RetryConfig, type RevenueBridges, type RevenueConfig, type RevenueContext, type RevenueEngine, RevenueError, type RevenueEventDefinition, type RevenueEventName, type RevenueEventPayloadOf, type RevenueEventSchema, type RevenueModels, type RevenuePluginDefinition, type RevenueRepositories, type RevenueSchemaOptions, SETTLEMENT_STATE_MACHINE, SETTLEMENT_STATUS, SETTLEMENT_STATUS_VALUES, SETTLEMENT_TYPE, SETTLEMENT_TYPE_VALUES, SPLIT_STATE_MACHINE, SPLIT_STATUS, SPLIT_STATUS_VALUES, SPLIT_TYPE, SPLIT_TYPE_VALUES, SUBSCRIPTION_STATE_MACHINE, SUBSCRIPTION_STATUS, SUBSCRIPTION_STATUS_VALUES, SettlementCreateInput, type SettlementDocument, SettlementListFilter, SettlementNotFoundError, SettlementRepository, SettlementStatus, SettlementStatusValue, type SettlementSummary, SettlementType, SettlementTypeValue, SettlementUpdateInput, type SplitInfo, type SplitRule, SplitRuleInput, SplitStatus, SplitStatusValue, SplitType, SplitTypeValue, type StateChangeEvent, StateMachine, SubscriptionCreateInput, type SubscriptionDocument, SubscriptionListFilter, SubscriptionNotFoundError, SubscriptionRepository, SubscriptionStatus, SubscriptionStatusValue, SubscriptionUpdateInput, TRANSACTION_FLOW, TRANSACTION_FLOW_VALUES, TRANSACTION_KIND, TRANSACTION_KIND_VALUES, TRANSACTION_STATE_MACHINE, TRANSACTION_STATUS, TRANSACTION_STATUS_VALUES, type TaxBridge, type TaxCalculation, type TaxConfig, type TaxType, TransactionCreateInput, type TransactionDocument, TransactionFlow, TransactionFlowValue, TransactionKind, TransactionKindValue, TransactionListFilter, TransactionNotFoundError, TransactionRepository, TransactionStatus, TransactionStatusValue, TransactionUpdateInput, ValidationError, WrongTransactionKindError, absMoney, addMoney, appendAuditEvent, calculateCommission, calculateOrganizationPayout, calculateSplits, calculateTax, compareMoney, createBankFeedProviderRegistry, createEvent, createProviderRegistry, createRevenue, equalsMoney, err, escrowHoldSchema, escrowReleaseSchema, fromMajor, fromSmallestUnit, getAuditTrail, getLastStateChange, getTaxType, initialStatusFor, isBankFeedSource, isBankFeedStatus, isCurrencyCode, isErr, isHoldReason, isHoldStatus, isLibraryCategory, isMonetizationType, isMoney, isNegativeMoney, isOk, isPaymentGatewayType, isPaymentStatus, isPayoutMethod, isPlanKey, isPositiveMoney, isReleaseReason, isSettlementStatus, isSettlementType, isSplitStatus, isSplitType, isStatusValidForKind, isSubscriptionStatus, isTransactionFlow, isTransactionKind, isTransactionStatus, isZeroMoney, minorUnitFactor, money, multiplyMoney, negateMoney, ok, paymentIntentSchema, paymentVerifySchema, refundSchema, revenueEventDefinitions, reverseCommission, reverseTax, settlementBaseSchema, settlementCreateSchema, settlementListFilterSchema, settlementUpdateSchema, smFor, splitRuleSchema, statusesForKind, subscriptionBaseSchema, subscriptionCreateSchema, subscriptionListFilterSchema, subscriptionUpdateSchema, subtractMoney, sumMoney, toCurrencyCode, toMajor, toSmallestUnit, transactionBaseSchema, transactionCreateSchema, transactionListFilterSchema, transactionUpdateSchema, validateTaxCalculation };

package/dist/index.mjs

@@ -1,10 +1,10 @@
 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-ByS3mjX0.mjs";
-import { n as SubscriptionRepository, r as TransactionRepository, t as SettlementRepository } from "./settlement.repository-DtLSBDIk.mjs";
+import { n as SubscriptionRepository, r as TransactionRepository, t as SettlementRepository } from "./settlement.repository-oypYDjKq.mjs";
 import { n as createEvent, t as REVENUE_EVENTS } from "./event-constants-DM_-A57b.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 { _ as WrongTransactionKindError, a as InvalidStateTransitionError, c as PaymentVerificationError, d as RefundNotSupportedError, f as RevenueError, g as ValidationError, h as TransactionNotFoundError, i as ConfigurationError, l as ProviderCapabilityError, m as SubscriptionNotFoundError, n as BankFeedImportError, o as MethodKindLockedError, p as SettlementNotFoundError, r as BankFeedProviderNotFoundError, s as PaymentIntentCreationError, t as AlreadyVerifiedError, u as ProviderNotFoundError } from "./errors-Bt5NRVMq.mjs";
 import { BANK_FEED_STATE_MACHINE, HOLD_STATE_MACHINE, MANUAL_STATE_MACHINE, PAYMENT_FLOW_STATE_MACHINE, SETTLEMENT_STATE_MACHINE, SPLIT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, StateMachine, TRANSACTION_STATE_MACHINE, smFor } from "./core/state-machines.mjs";
-import { a as reverseTax, c as reverseCommission, i as getTaxType, n as calculateSplits, o as validateTaxCalculation, r as calculateTax, s as calculateCommission, t as calculateOrganizationPayout } from "./splits-CNfQj92L.mjs";
+import { a as getTaxType, c as calculateCommission, i as calculateTax, l as reverseCommission, n as calculateSplits, o as reverseTax, s as validateTaxCalculation, t as calculateOrganizationPayout } from "./splits-CEdZN6OT.mjs";
 import { createRevenueRepositories } from "./repositories/create-repositories.mjs";
 import { a as createProviderRegistry, i as ProviderRegistry, n as BankFeedProviderRegistry, o as PaymentProvider, r as createBankFeedProviderRegistry, t as BankFeedProvider } from "./bank-feed-ClxNob_I.mjs";
 import { M as revenueEventDefinitions, N as InProcessRevenueBus } from "./revenue-event-catalog-B9aZmNpL.mjs";

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

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

package/dist/repositories/create-repositories.mjs

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

package/dist/{settlement.repository-DtLSBDIk.mjs → settlement.repository-oypYDjKq.mjs}

@@ -3,7 +3,7 @@ import { n as createEvent, t as REVENUE_EVENTS } from "./event-constants-DM_-A57
 import { g as SETTLEMENT_STATUS, r as SUBSCRIPTION_STATUS, w as HOLD_STATUS } from "./subscription.enums-95othr0i.mjs";
 import { _ as WrongTransactionKindError, g as ValidationError, h as TransactionNotFoundError, m as SubscriptionNotFoundError, n as BankFeedImportError, o as MethodKindLockedError, p as SettlementNotFoundError } from "./errors-Bt5NRVMq.mjs";
 import { SETTLEMENT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, TRANSACTION_STATE_MACHINE, smFor } from "./core/state-machines.mjs";
-import { a as reverseTax, c as reverseCommission, n as calculateSplits, s as calculateCommission, t as calculateOrganizationPayout } from "./splits-CNfQj92L.mjs";
+import { c as calculateCommission, l as reverseCommission, n as calculateSplits, o as reverseTax, t as calculateOrganizationPayout } from "./splits-CEdZN6OT.mjs";
 import { Repository, repoOptionsFromCtx, withTransaction } from "@classytic/mongokit";
 
 //#region src/repositories/base.repository.ts
@@ -1402,6 +1402,38 @@ var SubscriptionRepository = class extends RevenueRepositoryBase {
 
 //#endregion
 //#region src/repositories/settlement.repository.ts
+function emptySettlementSummary() {
+	return {
+		currency: null,
+		pending: 0,
+		held: 0,
+		available: 0,
+		processing: 0,
+		paidOut: 0,
+		failed: 0,
+		lifetime: 0
+	};
+}
+/** Bucket one aggregated (status, due, total) row into a running summary. */
+function foldSettlementStatus(s, status, due, total) {
+	switch (status) {
+		case SETTLEMENT_STATUS.PENDING:
+			s.pending += total;
+			if (due) s.available += total;
+			else s.held += total;
+			break;
+		case SETTLEMENT_STATUS.PROCESSING:
+			s.processing += total;
+			break;
+		case SETTLEMENT_STATUS.COMPLETED:
+			s.paidOut += total;
+			break;
+		case SETTLEMENT_STATUS.FAILED:
+			s.failed += total;
+			break;
+		default: break;
+	}
+}
 /**
 * SettlementRepository — payouts to recipients (organizations, vendors,
 * affiliates).
@@ -1447,6 +1479,7 @@ var SettlementRepository = class extends RevenueRepositoryBase {
 		};
 		if (options.organizationId) query.organizationId = options.organizationId;
 		if (options.payoutMethod) query.payoutMethod = options.payoutMethod;
+		if (options.recipientId) query.recipientId = options.recipientId;
 		const pending = (await this.getAll({
 			filters: query,
 			limit: options.limit ?? 50,
@@ -1562,6 +1595,82 @@ var SettlementRepository = class extends RevenueRepositoryBase {
 		}), ctx);
 		return updated;
 	}
+	/**
+	* Settlement money-state for an ARBITRARY filter — a recipient, an org, or
+	* the whole platform (pass `_bypassTenant` in ctx to span every org). One
+	* tenant-scoped `aggregatePipeline` (the `{ recipientId, status }` index backs
+	* the `$match`), never a raw `Model.aggregate`. The reusable rollup behind
+	* `recipientBalance`, platform reconciliation, and cross-org earnings.
+	*/
+	async summary(filter = {}, ctx = {}) {
+		const now = /* @__PURE__ */ new Date();
+		const rows = await this.aggregatePipeline([{ $match: filter }, { $group: {
+			_id: {
+				status: "$status",
+				due: { $lte: ["$scheduledAt", now] }
+			},
+			total: { $sum: "$amount" },
+			currency: { $first: "$currency" }
+		} }], this.optsFromCtx(ctx));
+		const out = emptySettlementSummary();
+		for (const row of rows) {
+			foldSettlementStatus(out, row._id.status, row._id.due, row.total);
+			if (row.currency && !out.currency) out.currency = row.currency;
+		}
+		out.lifetime = out.pending + out.processing + out.paidOut;
+		return out;
+	}
+	/**
+	* Per-recipient settlement rollup — one {@link RecipientBreakdown} per
+	* distinct (recipientId, recipientType) matching `filter`. The reusable list
+	* behind a platform "who is owed what" view; pass `_bypassTenant` to span all
+	* orgs.
+	*/
+	async breakdownByRecipient(filter = {}, ctx = {}) {
+		const now = /* @__PURE__ */ new Date();
+		const rows = await this.aggregatePipeline([{ $match: filter }, { $group: {
+			_id: {
+				recipientId: "$recipientId",
+				recipientType: "$recipientType",
+				status: "$status",
+				due: { $lte: ["$scheduledAt", now] }
+			},
+			total: { $sum: "$amount" },
+			currency: { $first: "$currency" },
+			role: { $first: "$metadata.role" }
+		} }], this.optsFromCtx(ctx));
+		const byKey = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			const key = `${row._id.recipientType}:${row._id.recipientId}`;
+			let r = byKey.get(key);
+			if (!r) {
+				r = {
+					recipientId: row._id.recipientId,
+					recipientType: row._id.recipientType,
+					role: row.role ?? null,
+					...emptySettlementSummary()
+				};
+				byKey.set(key, r);
+			}
+			foldSettlementStatus(r, row._id.status, row._id.due, row.total);
+			if (row.role && !r.role) r.role = row.role;
+			if (row.currency && !r.currency) r.currency = row.currency;
+		}
+		for (const r of byKey.values()) r.lifetime = r.pending + r.processing + r.paidOut;
+		return [...byKey.values()];
+	}
+	/** One recipient's wallet — a thin `summary` over `{ recipientId, … }`. */
+	async recipientBalance(recipientId, options = {}, ctx = {}) {
+		const filter = { recipientId };
+		if (options.recipientType !== void 0) filter.recipientType = options.recipientType;
+		if (options.currency !== void 0) filter.currency = options.currency;
+		const s = await this.summary(filter, ctx);
+		return {
+			recipientId,
+			...s,
+			currency: options.currency ?? s.currency
+		};
+	}
 };
 
 //#endregion

package/dist/shared/index.d.mts

@@ -1,2 +1,2 @@
-import { A as SplitInfo, B as validateTaxCalculation, C as multiplyMoney, D as toCurrencyCode, E as sumMoney, F as TaxConfig, H as calculateCommission, I as TaxType, L as calculateTax, M as calculateOrganizationPayout, N as calculateSplits, O as toMajor, P as TaxCalculation, R as getTaxType, S as money, T as subtractMoney, U as reverseCommission, V as CommissionInfo, _ as isMoney, a as CurrencyCode, b as isZeroMoney, c as Money, d as addMoney, f as compareMoney, g as isCurrencyCode, h as fromSmallestUnit, i as CURRENCIES, j as SplitRule, k as toSmallestUnit, l as MoneyValue, m as fromMajor, n as getAuditTrail, o as CurrencyMismatchError, p as equalsMoney, r as getLastStateChange, s as MINOR_UNIT_FACTOR, t as appendAuditEvent, u as absMoney, v as isNegativeMoney, w as negateMoney, x as minorUnitFactor, y as isPositiveMoney, z as reverseTax } from "../audit-DRKuLBFO.mjs";
-export { CURRENCIES, CommissionInfo, type CurrencyCode, CurrencyMismatchError, MINOR_UNIT_FACTOR, type Money, type MoneyValue, SplitInfo, SplitRule, TaxCalculation, TaxConfig, TaxType, absMoney, addMoney, appendAuditEvent, calculateCommission, calculateOrganizationPayout, calculateSplits, calculateTax, compareMoney, equalsMoney, fromMajor, fromSmallestUnit, getAuditTrail, getLastStateChange, getTaxType, isCurrencyCode, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, minorUnitFactor, money, multiplyMoney, negateMoney, reverseCommission, reverseTax, subtractMoney, sumMoney, toCurrencyCode, toMajor, toSmallestUnit, validateTaxCalculation };
+import { A as SplitInfo, B as reverseTax, C as multiplyMoney, D as toCurrencyCode, E as sumMoney, F as TaxCalculation, H as CommissionInfo, I as TaxConfig, L as TaxType, M as calculateOrganizationPayout, N as calculateSplits, O as toMajor, P as reverseSplits, R as calculateTax, S as money, T as subtractMoney, U as calculateCommission, V as validateTaxCalculation, W as reverseCommission, _ as isMoney, a as CurrencyCode, b as isZeroMoney, c as Money, d as addMoney, f as compareMoney, g as isCurrencyCode, h as fromSmallestUnit, i as CURRENCIES, j as SplitRule, k as toSmallestUnit, l as MoneyValue, m as fromMajor, n as getAuditTrail, o as CurrencyMismatchError, p as equalsMoney, r as getLastStateChange, s as MINOR_UNIT_FACTOR, t as appendAuditEvent, u as absMoney, v as isNegativeMoney, w as negateMoney, x as minorUnitFactor, y as isPositiveMoney, z as getTaxType } from "../audit-BkDdPSed.mjs";
+export { CURRENCIES, CommissionInfo, type CurrencyCode, CurrencyMismatchError, MINOR_UNIT_FACTOR, type Money, type MoneyValue, SplitInfo, SplitRule, TaxCalculation, TaxConfig, TaxType, absMoney, addMoney, appendAuditEvent, calculateCommission, calculateOrganizationPayout, calculateSplits, calculateTax, compareMoney, equalsMoney, fromMajor, fromSmallestUnit, getAuditTrail, getLastStateChange, getTaxType, isCurrencyCode, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, minorUnitFactor, money, multiplyMoney, negateMoney, reverseCommission, reverseSplits, reverseTax, subtractMoney, sumMoney, toCurrencyCode, toMajor, toSmallestUnit, validateTaxCalculation };

package/dist/shared/index.mjs

@@ -1,4 +1,4 @@
-import { a as reverseTax, c as reverseCommission, i as getTaxType, n as calculateSplits, o as validateTaxCalculation, r as calculateTax, s as calculateCommission, t as calculateOrganizationPayout } from "../splits-CNfQj92L.mjs";
+import { a as getTaxType, c as calculateCommission, i as calculateTax, l as reverseCommission, n as calculateSplits, o as reverseTax, r as reverseSplits, s as validateTaxCalculation, t as calculateOrganizationPayout } from "../splits-CEdZN6OT.mjs";
 import { C as sumMoney, E as toSmallestUnit, S as subtractMoney, T as toMajor, _ as isZeroMoney, a as CurrencyMismatchError, b as multiplyMoney, c as addMoney, d as fromMajor, f as fromSmallestUnit, g as isPositiveMoney, h as isNegativeMoney, i as CURRENCIES, l as compareMoney, m as isMoney, n as getAuditTrail, o as MINOR_UNIT_FACTOR, p as isCurrencyCode, r as getLastStateChange, s as absMoney, t as appendAuditEvent, u as equalsMoney, v as minorUnitFactor, w as toCurrencyCode, x as negateMoney, y as money } from "../audit-Ba2XB2C4.mjs";
 
-export { CURRENCIES, CurrencyMismatchError, MINOR_UNIT_FACTOR, absMoney, addMoney, appendAuditEvent, calculateCommission, calculateOrganizationPayout, calculateSplits, calculateTax, compareMoney, equalsMoney, fromMajor, fromSmallestUnit, getAuditTrail, getLastStateChange, getTaxType, isCurrencyCode, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, minorUnitFactor, money, multiplyMoney, negateMoney, reverseCommission, reverseTax, subtractMoney, sumMoney, toCurrencyCode, toMajor, toSmallestUnit, validateTaxCalculation };
+export { CURRENCIES, CurrencyMismatchError, MINOR_UNIT_FACTOR, absMoney, addMoney, appendAuditEvent, calculateCommission, calculateOrganizationPayout, calculateSplits, calculateTax, compareMoney, equalsMoney, fromMajor, fromSmallestUnit, getAuditTrail, getLastStateChange, getTaxType, isCurrencyCode, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, minorUnitFactor, money, multiplyMoney, negateMoney, reverseCommission, reverseSplits, reverseTax, subtractMoney, sumMoney, toCurrencyCode, toMajor, toSmallestUnit, validateTaxCalculation };

package/dist/{splits-CNfQj92L.mjs → splits-CEdZN6OT.mjs}

@@ -1,3 +1,5 @@
+import { g as ValidationError } from "./errors-Bt5NRVMq.mjs";
+
 //#region src/shared/calculators/commission.ts
 function calculateCommission(amount, commissionRate, gatewayFeeRate = 0) {
 	if (!commissionRate || commissionRate <= 0) return null;
@@ -17,9 +19,9 @@ function calculateCommission(amount, commissionRate, gatewayFeeRate = 0) {
 }
 function reverseCommission(originalCommission, originalAmount, refundAmount) {
 	if (!originalCommission?.netAmount) return null;
-	if (!originalAmount || originalAmount <= 0) throw new Error("Original amount must be greater than 0");
-	if (refundAmount < 0) throw new Error("Refund amount cannot be negative");
-	if (refundAmount > originalAmount) throw new Error("Refund amount exceeds original amount");
+	if (!originalAmount || originalAmount <= 0) throw new ValidationError("Original amount must be greater than 0");
+	if (refundAmount < 0) throw new ValidationError("Refund amount cannot be negative");
+	if (refundAmount > originalAmount) throw new ValidationError("Refund amount exceeds original amount");
 	const refundRatio = refundAmount / originalAmount;
 	return {
 		rate: originalCommission.rate,
@@ -74,9 +76,9 @@ function reverseTax(originalTax, originalAmount, refundAmount) {
 		totalAmount: refundAmount,
 		pricesIncludeTax: false
 	};
-	if (!originalAmount || originalAmount <= 0) throw new Error("Original amount must be greater than 0");
-	if (refundAmount < 0) throw new Error("Refund amount cannot be negative");
-	if (refundAmount > originalAmount) throw new Error("Refund amount exceeds original amount");
+	if (!originalAmount || originalAmount <= 0) throw new ValidationError("Original amount must be greater than 0");
+	if (refundAmount < 0) throw new ValidationError("Refund amount cannot be negative");
+	if (refundAmount > originalAmount) throw new ValidationError("Refund amount exceeds original amount");
 	const refundRatio = refundAmount / originalAmount;
 	const reversedType = originalTax.type ? originalTax.type === "collected" ? "paid" : originalTax.type === "paid" ? "collected" : "exempt" : void 0;
 	return {
@@ -118,6 +120,19 @@ function calculateSplits(amount, rules, gatewayFeeRate = 0) {
 function calculateOrganizationPayout(amount, splits) {
 	return amount - splits.reduce((sum, s) => sum + s.grossAmount, 0);
 }
+function reverseSplits(originalSplits, originalAmount, refundAmount) {
+	if (!originalAmount || originalAmount <= 0) throw new ValidationError("Original amount must be greater than 0");
+	if (refundAmount < 0) throw new ValidationError("Refund amount cannot be negative");
+	if (refundAmount > originalAmount) throw new ValidationError("Refund amount exceeds original amount");
+	const refundRatio = refundAmount / originalAmount;
+	return originalSplits.map((s) => ({
+		...s,
+		grossAmount: Math.round(s.grossAmount * refundRatio),
+		gatewayFeeAmount: Math.round(s.gatewayFeeAmount * refundRatio),
+		netAmount: Math.round(s.netAmount * refundRatio),
+		status: "waived"
+	}));
+}
 
 //#endregion
-export { reverseTax as a, reverseCommission as c, getTaxType as i, calculateSplits as n, validateTaxCalculation as o, calculateTax as r, calculateCommission as s, calculateOrganizationPayout as t };
+export { getTaxType as a, calculateCommission as c, calculateTax as i, reverseCommission as l, calculateSplits as n, reverseTax as o, reverseSplits as r, validateTaxCalculation as s, calculateOrganizationPayout as t };

package/dist/validators/index.d.mts

@@ -1,4 +1,4 @@
-import { A as transactionBaseSchema, C as subscriptionBaseSchema, D as TransactionCreateInput, E as subscriptionUpdateSchema, M as transactionListFilterSchema, N as transactionUpdateSchema, O as TransactionListFilter, S as SubscriptionUpdateInput, T as subscriptionListFilterSchema, _ as settlementCreateSchema, a as escrowReleaseSchema, b as SubscriptionCreateInput, c as PaymentVerifyInput, d as paymentVerifySchema, f as refundSchema, g as settlementBaseSchema, h as SettlementUpdateInput, i as escrowHoldSchema, j as transactionCreateSchema, k as TransactionUpdateInput, l as RefundInput, m as SettlementListFilter, n as EscrowReleaseInput, o as splitRuleSchema, p as SettlementCreateInput, r as SplitRuleInput, s as PaymentIntentInput, t as EscrowHoldInput, u as paymentIntentSchema, v as settlementListFilterSchema, w as subscriptionCreateSchema, x as SubscriptionListFilter, y as settlementUpdateSchema } from "../escrow.schema-Cklvlywy.mjs";
+import { A as transactionBaseSchema, C as subscriptionBaseSchema, D as TransactionCreateInput, E as subscriptionUpdateSchema, M as transactionListFilterSchema, N as transactionUpdateSchema, O as TransactionListFilter, S as SubscriptionUpdateInput, T as subscriptionListFilterSchema, _ as settlementCreateSchema, a as escrowReleaseSchema, b as SubscriptionCreateInput, c as PaymentVerifyInput, d as paymentVerifySchema, f as refundSchema, g as settlementBaseSchema, h as SettlementUpdateInput, i as escrowHoldSchema, j as transactionCreateSchema, k as TransactionUpdateInput, l as RefundInput, m as SettlementListFilter, n as EscrowReleaseInput, o as splitRuleSchema, p as SettlementCreateInput, r as SplitRuleInput, s as PaymentIntentInput, t as EscrowHoldInput, u as paymentIntentSchema, v as settlementListFilterSchema, w as subscriptionCreateSchema, x as SubscriptionListFilter, y as settlementUpdateSchema } from "../escrow.schema-DSx7EywJ.mjs";
 import { z } from "zod";
 
 //#region src/validators/bank-feed.schema.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/revenue",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Payment lifecycle engine — transactions, subscriptions, escrow, settlements, commissions. MongoKit-powered, Arc-compatible, framework-agnostic.",
   "type": "module",
   "sideEffects": false,