@happyvertical/smrt-sales 0.39.2

package/dist/commissions/models/CommissionPlan.d.ts

@@ -0,0 +1,117 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { CommissionPlanComponent, CommissionPlanOptions, CommissionPlanStatus } from '../types.js';
+/**
+ * Validate a components array. Throws a descriptive error on the first
+ * violation. Exported for reuse by the calculation service's input guards
+ * and by referral-terms builders that assemble component arrays.
+ *
+ * Rules:
+ * - component keys are non-empty and unique within the plan
+ * - `trigger` is a non-empty string (`'*'` matches every event kind)
+ * - `basis` is one of {@link COMMISSION_BASES}
+ * - basis `fixed` requires an integer `fixedAmountCents`
+ * - every other basis requires `rate` in `[0, 1]`
+ * - basis `custom` additionally requires a non-empty `customBasisKey`
+ * - `recurrence.kind` (when present) is `one_time` or `recurring`;
+ *   `maxOccurrences` / `windowMonths` (when present) are positive integers
+ */
+export declare function validateCommissionPlanComponents(components: CommissionPlanComponent[]): void;
+export declare class CommissionPlan extends SmrtObject {
+    /** Tenant ID for multi-tenant isolation (nullable → global plans). */
+    tenantId: string | null;
+    /** Stable plan identity shared by every version of the plan. */
+    planKey: string;
+    /** Monotonic version within `planKey`. Amendments insert `max + 1`. */
+    version: number;
+    /** Human-readable plan name. */
+    name: string;
+    /** Longer human-readable description of the terms. */
+    description: string;
+    /**
+     * Lifecycle status — see {@link PLAN_STATUS_TRANSITIONS}. Mutate via
+     * {@link activate} / {@link supersede} / {@link retire} (or a legal
+     * single-step assignment; the save-time guard rejects illegal edges).
+     */
+    status: CommissionPlanStatus;
+    /** When this version takes effect. Frozen once the plan activates. */
+    effectiveFrom: Date | null;
+    /** ISO 4217 currency the plan's terms are denominated in. */
+    currency: string;
+    /**
+     * Calculation components as a JSON-string array — see
+     * {@link CommissionPlanComponent}. Use {@link getComponents} /
+     * {@link setComponents} (the setter validates).
+     */
+    components: string;
+    /** Additional metadata as a JSON string. */
+    metadata: string;
+    constructor(options?: CommissionPlanOptions);
+    /**
+     * Re-coerce date fields after the framework reapplies raw option values,
+     * record the loaded status for the transition guard, and capture the
+     * frozen snapshot when the row arrived already activated. The snapshot is
+     * captured for every non-draft status (not just `active`) so a superseded
+     * or retired version — history — can't be rewritten either.
+     */
+    initialize(): Promise<this>;
+    isDraft(): boolean;
+    isActive(): boolean;
+    /** Parse {@link components}; returns `[]` on empty/invalid JSON. */
+    getComponents(): CommissionPlanComponent[];
+    /**
+     * Validate and store the components array. Throws on invalid components —
+     * see {@link validateCommissionPlanComponents} for the rules.
+     */
+    setComponents(components: CommissionPlanComponent[]): void;
+    /** Parse {@link metadata}; returns `{}` on empty/invalid JSON. */
+    getMetadata(): Record<string, unknown>;
+    /** Serialize and store {@link metadata}. */
+    setMetadata(data: Record<string, unknown>): void;
+    /**
+     * Transition `draft → active`. Validates components first so no active
+     * plan can carry malformed terms.
+     */
+    activate(): void;
+    /** Transition `active → superseded` (a newer version took over). */
+    supersede(): void;
+    /** Transition `draft | active → retired` (terminal). */
+    retire(): void;
+    /**
+     * Save with two guards:
+     *
+     * 1. **Status transition** — the about-to-be-written status must be a
+     *    legal edge from the authoritative prior persisted status (re-read
+     *    from the DB so a `create({ id: <existing>, _skipLoad: true })` upsert
+     *    can't sidestep the guard — commerce pattern).
+     * 2. **Frozen calculation identity** — once the row has been saved
+     *    non-draft, `components` / `currency` / `planKey` / `version` /
+     *    `effectiveFrom` must match the captured snapshot. Amend by inserting
+     *    a new version instead.
+     *
+     * Activating saves also re-validate components, so an `active` row always
+     * carries well-formed terms regardless of which write path set them.
+     */
+    save(): Promise<this>;
+    /**
+     * Refuse a save whose `(tenantId, planKey, version)` natural key already
+     * belongs to a DIFFERENT row. The frozen-identity guard above is
+     * instance-local (WeakMap), so a FRESH instance carrying an existing
+     * natural key would otherwise sail through and the conflict-column
+     * upsert would rewrite the persisted terms (and rotate the row id).
+     * Edit drafts by hydrating them; change terms with
+     * `CommissionPlanCollection.createAmendment()`.
+     */
+    private assertNaturalKeyNotTaken;
+    /**
+     * Resolve the AUTHORITATIVE prior status from the database; fall back to
+     * the loaded-status WeakMap only when the DB is unavailable. `undefined`
+     * means no persisted row exists (genuinely new).
+     */
+    private resolvePriorStatus;
+    private assertStatusTransition;
+    private assertFrozenIdentityUnchanged;
+    private serializeFrozenSnapshot;
+    private static coerceDate;
+}
+export default CommissionPlan;
+//# sourceMappingURL=CommissionPlan.d.ts.map

package/dist/commissions/models/CommissionPlan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommissionPlan.d.ts","sourceRoot":"","sources":["../../../src/commissions/models/CommissionPlan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAS,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAC1B,MAAM,aAAa,CAAC;AAmCrB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,uBAAuB,EAAE,GACpC,IAAI,CA6EN;AAED,qBAgBa,cAAe,SAAQ,UAAU;IAC5C,sEAAsE;IAEtE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,gEAAgE;IAEhE,OAAO,EAAE,MAAM,CAAM;IAErB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAK;IAEpB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAM;IAElB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAM;IAEzB;;;;OAIG;IACH,MAAM,EAAE,oBAAoB,CAAW;IAEvC,sEAAsE;IACtE,aAAa,EAAE,IAAI,GAAG,IAAI,CAAQ;IAElC,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAS;IAEzB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAQ;IAE1B,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,qBAA0B;IAgB/C;;;;;;OAMG;IACY,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAc1C,OAAO,IAAI,OAAO;IAIlB,QAAQ,IAAI,OAAO;IAMnB,oEAAoE;IACpE,aAAa,IAAI,uBAAuB,EAAE;IAU1C;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,uBAAuB,EAAE,GAAG,IAAI;IAK1D,kEAAkE;IAClE,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYtC,4CAA4C;IAC5C,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMhD;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAUhB,oEAAoE;IACpE,SAAS,IAAI,IAAI;IASjB,wDAAwD;IACxD,MAAM,IAAI,IAAI;IAWd;;;;;;;;;;;;;;OAcG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBpC;;;;;;;;OAQG;YACW,wBAAwB;IAgCtC;;;;OAIG;YACW,kBAAkB;IAgBhC,OAAO,CAAC,sBAAsB;IAe9B,OAAO,CAAC,6BAA6B;IAerC,OAAO,CAAC,uBAAuB;IAa/B,OAAO,CAAC,MAAM,CAAC,UAAU;CAS1B;AAED,eAAe,cAAc,CAAC"}

package/dist/commissions/models/Earner.d.ts

@@ -0,0 +1,49 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { EarnerOptions, EarnerStatus, PayoutMethod } from '../types.js';
+export declare class Earner extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation. Nullable so global/operator-level
+     * earners remain possible; unlike legacy affiliates, sales earners are
+     * tenant-owned by default.
+     */
+    tenantId: string | null;
+    /**
+     * Identity link to a smrt-profiles Profile (cross-package string
+     * reference — never a DDL foreign key).
+     */
+    profileId: string;
+    /** Human-readable display name for portals and operator views. */
+    displayName: string;
+    /** Account lifecycle: `pending` (default) → `active` / `suspended`. */
+    status: EarnerStatus;
+    /** Preferred payout delivery method. */
+    payoutMethod: PayoutMethod;
+    /**
+     * Minimum unsettled balance (integer cents) before a payout batch is
+     * created. Default $50.00 = 5000 cents.
+     */
+    payoutThresholdCents: number;
+    /**
+     * Payout cadence key. Open string so applications can define their own
+     * schedules (`manual`, `monthly`, `weekly`, `net_30`, …); `manual` means
+     * an operator triggers batches explicitly.
+     */
+    payoutScheduleKey: string;
+    /** ISO 4217 currency all of this earner's balances settle in. */
+    currency: string;
+    /**
+     * Additional metadata as a JSON string (tax info, payout-rail details,
+     * …). Use {@link getMetadata}/{@link setMetadata}.
+     */
+    metadata: string;
+    constructor(options?: EarnerOptions);
+    isActive(): boolean;
+    isPending(): boolean;
+    isSuspended(): boolean;
+    /** Parse {@link metadata}; returns `{}` on empty/invalid JSON. */
+    getMetadata(): Record<string, unknown>;
+    /** Serialize and store {@link metadata}. */
+    setMetadata(data: Record<string, unknown>): void;
+}
+export default Earner;
+//# sourceMappingURL=Earner.d.ts.map

package/dist/commissions/models/Earner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Earner.d.ts","sourceRoot":"","sources":["../../../src/commissions/models/Earner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAmB,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAE7E,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7E,qBAMa,MAAO,SAAQ,UAAU;IACpC;;;;OAIG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;;OAGG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAM;IAEzB,uEAAuE;IACvE,MAAM,EAAE,YAAY,CAAa;IAEjC,wCAAwC;IACxC,YAAY,EAAE,YAAY,CAAmB;IAE7C;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAQ;IAEpC;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAY;IAErC,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAS;IAEzB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,aAAkB;IAiBvC,QAAQ,IAAI,OAAO;IAInB,SAAS,IAAI,OAAO;IAIpB,WAAW,IAAI,OAAO;IAItB,kEAAkE;IAClE,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYtC,4CAA4C;IAC5C,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAGjD;AAED,eAAe,MAAM,CAAC"}

package/dist/commissions/models/EarningEvent.d.ts

@@ -0,0 +1,89 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { EarningEventOptions } from '../types.js';
+export declare class EarningEvent extends SmrtObject {
+    /** Tenant ID for multi-tenant isolation (nullable → global events). */
+    tenantId: string | null;
+    /**
+     * What kind of commercial event this is. Open string — see
+     * `EARNING_EVENT_KINDS` for the recommended vocabulary. Plan components
+     * match on this via their `trigger`.
+     */
+    eventKind: string;
+    /** When the commercial event occurred (not when it was ingested). */
+    occurredAt: Date;
+    /**
+     * Generic earning-source discriminator (`referral`, `opportunity`,
+     * `subscription`, `ad_event`, …). Free-form; this module attaches no
+     * semantics to it.
+     */
+    sourceKind: string;
+    /** Id of the source record named by {@link sourceKind}. */
+    sourceId: string;
+    /** Gross amount of the event in integer cents. */
+    grossAmountCents: number;
+    /**
+     * Net amount in integer cents, when the ingesting system defines one.
+     * `null` means "net is not defined for this event" — `net`-basis
+     * components then SKIP rather than falling back to gross (net is never
+     * derived).
+     */
+    netAmountCents: number | null;
+    /**
+     * Recognized margin in integer cents, when defined. `null` skips
+     * `margin`-basis components — margin is never derived.
+     */
+    marginCents: number | null;
+    /** ISO 4217 currency of the event's amounts. */
+    currency: string;
+    /**
+     * JSON map of `basisKey → integer cents` for `custom`-basis plan
+     * components. Use {@link getCustomBases}/{@link setCustomBases}.
+     */
+    customBases: string;
+    /**
+     * Idempotency natural key. Required. Callers embed tenant/source identity
+     * (see the class doc) — the framework does not synthesize it.
+     */
+    dedupeKey: string;
+    /** Additional metadata as a JSON string. */
+    metadata: string;
+    constructor(options?: EarningEventOptions);
+    /**
+     * Re-coerce {@link occurredAt} after the framework reapplies raw option /
+     * hydrated row values (SQLite hands back ISO strings), and capture the
+     * persisted state for the immutability guard when this instance hydrated
+     * an existing row.
+     */
+    initialize(): Promise<this>;
+    /**
+     * Save with the evidence-immutability guard. EarningEvents are immutable
+     * commercial evidence; three write vectors are closed:
+     *
+     * - a HYDRATED persisted row must serialize identically to its captured
+     *   state (no-op re-saves pass, any change throws);
+     * - an instance carrying an existing id WITHOUT having hydrated it
+     *   (`create({ id, _skipLoad: true })`) is rejected outright;
+     * - a NEW instance whose `dedupeKey` already belongs to another row is
+     *   refused outright: the natural-key upsert would not only rewrite the
+     *   evidence values but ROTATE the row's id (orphaning any Commission
+     *   whose `earningEventId` points at it). Idempotent ingestion goes
+     *   through `EarningEventCollection.getOrCreateByDedupeKey()`, which
+     *   finds first and never upserts.
+     */
+    save(): Promise<this>;
+    private serializeState;
+    /**
+     * Parse {@link customBases} into a `basisKey → cents` map; non-numeric
+     * values are dropped. Returns `{}` on empty/invalid JSON.
+     */
+    getCustomBases(): Record<string, number>;
+    /** Serialize and store {@link customBases}. */
+    setCustomBases(bases: Record<string, number>): void;
+    /** Parse {@link metadata}; returns `{}` on empty/invalid JSON. */
+    getMetadata(): Record<string, unknown>;
+    /** Serialize and store {@link metadata}. */
+    setMetadata(data: Record<string, unknown>): void;
+    private static coerceDate;
+}
+export default EarningEvent;
+//# sourceMappingURL=EarningEvent.d.ts.map

package/dist/commissions/models/EarningEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EarningEvent.d.ts","sourceRoot":"","sources":["../../../src/commissions/models/EarningEvent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAS,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAEnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AASvD,qBAYa,YAAa,SAAQ,UAAU;IAC1C,uEAAuE;IAEvE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;;;OAIG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB,qEAAqE;IACrE,UAAU,EAAE,IAAI,CAAc;IAE9B;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAM;IAExB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAM;IAEtB,kDAAkD;IAClD,gBAAgB,EAAE,MAAM,CAAK;IAE7B;;;;;OAKG;IAEH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAQ;IAErC;;;OAGG;IAEH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;IAElC,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAS;IAEzB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAQ;IAE3B;;;OAGG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,mBAAwB;IAsB7C;;;;;OAKG;IACY,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAS1C;;;;;;;;;;;;;;OAcG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkDpC,OAAO,CAAC,cAAc;IAkBtB;;;OAGG;IACH,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAqBxC,+CAA+C;IAC/C,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAInD,kEAAkE;IAClE,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYtC,4CAA4C;IAC5C,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhD,OAAO,CAAC,MAAM,CAAC,UAAU;CAS1B;AAED,eAAe,YAAY,CAAC"}

package/dist/commissions/models/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Model barrel for the commissions module.
+ * @packageDocumentation
+ */
+export { Commission } from './Commission.js';
+export { CommissionAdjustment } from './CommissionAdjustment.js';
+export { CommissionPayout } from './CommissionPayout.js';
+export { CommissionPlan, validateCommissionPlanComponents, } from './CommissionPlan.js';
+export { Earner } from './Earner.js';
+export { EarningEvent } from './EarningEvent.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/commissions/models/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commissions/models/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EACL,cAAc,EACd,gCAAgC,GACjC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/commissions/money.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Integer-cents money helpers for the commissions module.
+ *
+ * Every monetary field in this module is stored as integer cents (`*Cents`
+ * suffix). Rounding happens exactly once per calculation step via
+ * {@link roundCents} using half-away-from-zero semantics, and every
+ * Commission persists a `calculationTrace` naming that rounding mode so
+ * amounts stay reproducible.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Round to the nearest integer cent, half away from zero.
+ *
+ * `Math.round` alone rounds -2.5 to -2 (half toward +∞); financial
+ * conventions want symmetric behaviour, so the sign is factored out first:
+ * `Math.sign(v) * Math.round(Math.abs(v))` → `roundCents(2.5) === 3` and
+ * `roundCents(-2.5) === -3`.
+ */
+export declare function roundCents(value: number): number;
+/** Convert integer cents to a decimal major-unit amount (`/ 100`). */
+export declare function centsToAmount(cents: number): number;
+/**
+ * Convert a decimal major-unit amount to integer cents, rounding half away
+ * from zero (`roundCents(amount * 100)`).
+ */
+export declare function amountToCents(amount: number): number;
+/**
+ * Calculate a commission amount in integer cents:
+ * `roundCents(baseCents * rate * (shareFraction ?? 1))`.
+ *
+ * Rounding is applied once, on the final product, so split siblings each
+ * round independently and their sum can differ from the unsplit amount by at
+ * most one cent per sibling — the calculation trace records the inputs so any
+ * such drift is auditable.
+ *
+ * @param baseCents - Base amount in integer cents
+ * @param rate - Commission rate (0–1)
+ * @param shareFraction - Optional split share (0–1); defaults to 1
+ */
+export declare function calculateCommissionAmountCents(baseCents: number, rate: number, shareFraction?: number): number;
+//# sourceMappingURL=money.d.ts.map

package/dist/commissions/money.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../../src/commissions/money.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAER"}

package/dist/commissions/services/CommissionBalanceService.d.ts

@@ -0,0 +1,14 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { CommissionAdjustmentCollection } from '../collections/CommissionAdjustmentCollection.js';
+import { CommissionCollection } from '../collections/CommissionCollection.js';
+import { EarnerBalance } from '../types.js';
+export declare class CommissionBalanceService {
+    private readonly commissions;
+    private readonly adjustments;
+    constructor(commissions: CommissionCollection, adjustments: CommissionAdjustmentCollection);
+    static create(classOptions?: SmrtClassOptions): Promise<CommissionBalanceService>;
+    /** Compute the {@link EarnerBalance} for one earner in one currency. */
+    getBalance(earnerId: string, currency: string): Promise<EarnerBalance>;
+}
+export default CommissionBalanceService;
+//# sourceMappingURL=CommissionBalanceService.d.ts.map

package/dist/commissions/services/CommissionBalanceService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommissionBalanceService.d.ts","sourceRoot":"","sources":["../../../src/commissions/services/CommissionBalanceService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,8BAA8B,EAAE,MAAM,kDAAkD,CAAC;AAClG,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAE9E,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAErB,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,WAAW,EAAE,oBAAoB,EACjC,WAAW,EAAE,8BAA8B;WAGjD,MAAM,CACjB,YAAY,GAAE,gBAAqB,GAClC,OAAO,CAAC,wBAAwB,CAAC;IAOpC,wEAAwE;IAClE,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAkD7E;AAED,eAAe,wBAAwB,CAAC"}

package/dist/commissions/services/CommissionCalculationService.d.ts

@@ -0,0 +1,142 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { CommissionCollection } from '../collections/CommissionCollection.js';
+import { EarnerCollection } from '../collections/EarnerCollection.js';
+import { Commission } from '../models/Commission.js';
+import { EarningEvent } from '../models/EarningEvent.js';
+import { CommissionPlanComponent } from '../types.js';
+/** Input for {@link CommissionCalculationService.calculateForEvent}. */
+export interface CommissionCalculationInput {
+    /** The (persisted) earning event to calculate from. */
+    event: EarningEvent;
+    /** Snapshot reference recorded on every created Commission. */
+    planKey: string;
+    /** Snapshot reference recorded on every created Commission. */
+    planVersion: number;
+    /** The calculation terms to apply (typically from a frozen snapshot). */
+    components: CommissionPlanComponent[];
+    /** The earner the commissions belong to. */
+    earnerId: string;
+    /**
+     * Split share (0–1) this earner receives; defaults to 1. Callers running
+     * a split invoke the service once per earner with the shares and a shared
+     * `splitGroupId`.
+     */
+    shareFraction?: number;
+    /** Groups the sibling commissions of one split. */
+    splitGroupId?: string;
+    /** Generic polymorphic terms-snapshot reference (kind). */
+    termsSnapshotKind?: string;
+    /** Generic polymorphic terms-snapshot reference (id). */
+    termsSnapshotId?: string;
+    /**
+     * Clearing window in days: created commissions get
+     * `clearingEndsAt = event.occurredAt + clearingDays`. Omitted → no
+     * clearing (`clearingEndsAt: null`, immediately sweepable).
+     */
+    clearingDays?: number;
+    /**
+     * Currency the plan/terms are denominated in. When provided and different
+     * from `event.currency`, every matching component skips with reason
+     * `'currency_mismatch'` (this module performs no FX). Omitted → the event
+     * currency is taken as authoritative and no mismatch is possible.
+     */
+    currency?: string;
+    /**
+     * Resolves how many occurrences of a component this earner has already
+     * consumed under these terms (commissions from PRIOR events — the current
+     * event must not be counted). Drives `one_time` / `maxOccurrences` limits
+     * and the `occurrenceIndex` in the dedupe key and trace. Omitted →
+     * occurrence count `0`, i.e. recurrence limits are NOT enforced.
+     */
+    occurrenceCountResolver?: (componentKey: string) => Promise<number>;
+    /**
+     * Anchor for `windowMonths` recurrence checks (e.g. an agreement's
+     * effective date). Omitted → window checks are skipped.
+     */
+    anchorAt?: Date;
+}
+/** One component the calculation declined, and why. */
+export interface CommissionComponentSkip {
+    componentKey: string;
+    /**
+     * `'net_basis_undefined'` | `'margin_basis_undefined'` |
+     * `'fixed_amount_missing'` | `'rate_missing'` | `'custom_basis_missing'`
+     * | `'currency_mismatch'` | `'occurrence_limit_reached'` |
+     * `'outside_recurrence_window'`
+     */
+    reason: string;
+}
+/** Result of {@link CommissionCalculationService.calculateForEvent}. */
+export interface CommissionCalculationResult {
+    /** Commissions newly created by THIS call. */
+    created: Commission[];
+    /** Components that produced nothing, with reasons. */
+    skipped: CommissionComponentSkip[];
+    /**
+     * Idempotent replays: commissions that already existed for this
+     * (event, terms, component, earner) tuple. Never re-created, never
+     * mutated, and never in `created`.
+     */
+    existing: Commission[];
+}
+export declare class CommissionCalculationService {
+    private readonly commissions;
+    /**
+     * Optional earner lookup for the tenant-lane guard. When provided,
+     * `calculateForEvent` refuses an earner from a different tenant lane
+     * than the event (a cross-tenant `earnerId` would create a commission
+     * payable to another tenant's account). `static create()` always wires
+     * it; direct constructors may omit it for narrow test fixtures.
+     */
+    private readonly earners?;
+    constructor(commissions: CommissionCollection, 
+    /**
+     * Optional earner lookup for the tenant-lane guard. When provided,
+     * `calculateForEvent` refuses an earner from a different tenant lane
+     * than the event (a cross-tenant `earnerId` would create a commission
+     * payable to another tenant's account). `static create()` always wires
+     * it; direct constructors may omit it for narrow test fixtures.
+     */
+    earners?: EarnerCollection | undefined);
+    static create(classOptions?: SmrtClassOptions): Promise<CommissionCalculationService>;
+    /**
+     * Calculate commissions for one event × one earner × a component set.
+     *
+     * For each component whose `trigger` matches `event.eventKind` (or `'*'`
+     * — non-matching components are silently filtered, not "skipped"):
+     *
+     * 1. **Idempotency** — if a Commission already exists for this
+     *    (event, terms, component, earner) tuple, it is returned in
+     *    `existing` and nothing else runs for the component.
+     * 2. **Currency** — `input.currency` (when given) must equal the event's;
+     *    otherwise skip `'currency_mismatch'`.
+     * 3. **Recurrence** — `one_time` components skip
+     *    `'occurrence_limit_reached'` once the resolver reports ≥ 1 prior
+     *    occurrence; `recurring` components honor `maxOccurrences` and
+     *    `windowMonths` (events after `anchorAt + windowMonths` skip
+     *    `'outside_recurrence_window'`).
+     * 4. **Basis** — gross → `grossAmountCents`; net → `netAmountCents`
+     *    (skip `'net_basis_undefined'` when null — net is explicit, NEVER
+     *    derived from gross); margin → `marginCents` (skip
+     *    `'margin_basis_undefined'` when null); fixed → `fixedAmountCents`;
+     *    custom → `getCustomBases()[customBasisKey]` (skip
+     *    `'custom_basis_missing'`).
+     * 5. **Amount** — `roundCents(base * rate * shareFraction)`; for `fixed`,
+     *    `roundCents(fixedAmountCents * shareFraction)` with `rate` recorded
+     *    as `0`. Rounding happens exactly once, on the final product.
+     *
+     * Every created Commission is persisted `pending`, carries the event's
+     * tenant/currency/source, a complete {@link CommissionCalculationTrace},
+     * `clearingEndsAt` when `clearingDays` was given, and the dedupe key
+     * `` `${event.dedupeKey}:${termsSnapshotId || planKey + '@' + planVersion}:${componentKey}:${earnerId}:${occurrenceIndex}` ``.
+     */
+    calculateForEvent(input: CommissionCalculationInput): Promise<CommissionCalculationResult>;
+    /**
+     * Calendar-month addition (UTC). JS `setUTCMonth` semantics: day-of-month
+     * overflow rolls into the next month (Jan 31 + 1 month → Mar 2/3), which
+     * is acceptable for coarse recurrence windows.
+     */
+    private static addMonths;
+}
+export default CommissionCalculationService;
+//# sourceMappingURL=CommissionCalculationService.d.ts.map

package/dist/commissions/services/CommissionCalculationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommissionCalculationService.d.ts","sourceRoot":"","sources":["../../../src/commissions/services/CommissionCalculationService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,KAAK,EAEV,uBAAuB,EACxB,MAAM,aAAa,CAAC;AAIrB,wEAAwE;AACxE,MAAM,WAAW,0BAA0B;IACzC,uDAAuD;IACvD,KAAK,EAAE,YAAY,CAAC;IACpB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,UAAU,EAAE,uBAAuB,EAAE,CAAC;IACtC,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpE;;;OAGG;IACH,QAAQ,CAAC,EAAE,IAAI,CAAC;CACjB;AAED,uDAAuD;AACvD,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wEAAwE;AACxE,MAAM,WAAW,2BAA2B;IAC1C,8CAA8C;IAC9C,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,sDAAsD;IACtD,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC;;;;OAIG;IACH,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,qBAAa,4BAA4B;IAErC,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBARR,WAAW,EAAE,oBAAoB;IAClD;;;;;;OAMG;IACc,OAAO,CAAC,EAAE,gBAAgB,YAAA;WAGhC,MAAM,CACjB,YAAY,GAAE,gBAAqB,GAClC,OAAO,CAAC,4BAA4B,CAAC;IAOxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,iBAAiB,CACrB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,2BAA2B,CAAC;IAoSvC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;CAKzB;AAED,eAAe,4BAA4B,CAAC"}

package/dist/commissions/services/CommissionPayoutService.d.ts

@@ -0,0 +1,134 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { CommissionAdjustmentCollection } from '../collections/CommissionAdjustmentCollection.js';
+import { CommissionCollection } from '../collections/CommissionCollection.js';
+import { CommissionPayoutCollection } from '../collections/CommissionPayoutCollection.js';
+import { EarnerCollection } from '../collections/EarnerCollection.js';
+import { CommissionPayout } from '../models/CommissionPayout.js';
+import { PayoutMethod } from '../types.js';
+/** Collaborators for {@link CommissionPayoutService}. */
+export interface CommissionPayoutServiceDeps {
+    earners: EarnerCollection;
+    commissions: CommissionCollection;
+    adjustments: CommissionAdjustmentCollection;
+    payouts: CommissionPayoutCollection;
+}
+/** Input for {@link CommissionPayoutService.createPayoutBatch}. */
+export interface CreatePayoutBatchInput {
+    earnerId: string;
+    currency: string;
+    /** Informational period bounds recorded on the payout. */
+    periodStart?: Date;
+    periodEnd?: Date;
+    /**
+     * Idempotency natural key. Defaults to
+     * `` `${earnerId}:${currency}:${periodEnd ISO date}` `` where the date is
+     * the `YYYY-MM-DD` of `periodEnd` (falling back to `now`). Callers running
+     * more than one batch per earner/currency/day must supply their own key.
+     */
+    idempotencyKey?: string;
+    /** Overrides the earner's `payoutThresholdCents`. */
+    minimumThresholdCents?: number;
+    /** Overrides the earner's `payoutMethod`. */
+    payoutMethod?: PayoutMethod;
+    /** Clock override for deterministic tests. */
+    now?: Date;
+}
+/** Result of {@link CommissionPayoutService.createPayoutBatch}. */
+export interface CreatePayoutBatchResult {
+    /** The created (or, on an idempotent replay, existing) payout — `null` on refusal. */
+    payout: CommissionPayout | null;
+    /** `true` only when THIS call minted the payout. */
+    created: boolean;
+    /** Why no payout was created, when refused. */
+    reason?: 'below_threshold' | 'nothing_payable';
+    /** Ids of the commissions THIS call stamped onto the payout. */
+    settledCommissionIds: string[];
+    /** Ids of the adjustments THIS call stamped onto the payout. */
+    settledAdjustmentIds: string[];
+}
+export declare class CommissionPayoutService {
+    private readonly deps;
+    constructor(deps: CommissionPayoutServiceDeps);
+    static create(classOptions?: SmrtClassOptions): Promise<CommissionPayoutService>;
+    /**
+     * Create a settlement batch for one earner in one currency.
+     *
+     * Flow:
+     * 1. **Idempotency + repair** — an existing payout with the (defaulted)
+     *    key is returned as `{ payout, created: false }`. A clean replay
+     *    touches nothing (new payable work is never swept into an existing
+     *    batch). A PENDING payout whose stored totals disagree with the rows
+     *    stamped with its id — the signature of an interrupted claim pass —
+     *    is repaired: the claim pass re-runs and the totals are reconciled
+     *    from the verified membership. Past `pending` the batch is frozen.
+     * 2. **Gather** — payable unsettled commissions for the earner/currency,
+     *    plus unsettled adjustments whose parent commission is
+     *    earned/approved/payable/paid (same eligibility as the balance
+     *    service, so the batch settles exactly what the balance reports).
+     * 3. **Refuse** — `netTotal <= 0` → `'nothing_payable'`;
+     *    `netTotal < threshold` (earner default, overridable) →
+     *    `'below_threshold'`. Nothing is minted or stamped on refusal.
+     * 4. **Mint, claim, reconcile** — create the `pending` payout, then
+     *    CLAIM the gathered rows through the collections' conditional
+     *    `claimForPayout` (rows grabbed by another batch in the interim are
+     *    skipped, never double-claimed), and finally store totals computed
+     *    from the rows that were VERIFIABLY claimed — the payout's totals
+     *    are always reproducible from its member rows.
+     *
+     * Concurrency: claims are conditional with post-save verification, which
+     * narrows but does not eliminate races between batches with different
+     * keys (the collection layer exposes no cross-row transaction — the same
+     * stance as commerce/ledgers compensation). Settlement runs are expected
+     * to be single-writer per earner; totals are correct-by-construction from
+     * claimed rows either way.
+     */
+    createPayoutBatch(input: CreatePayoutBatchInput): Promise<CreatePayoutBatchResult>;
+    /**
+     * Whether a payout's stored totals are reproducible from the rows
+     * actually stamped with its id — the invariant an interrupted claim pass
+     * breaks. Clean replays short-circuit on this; repair runs only when it
+     * fails.
+     */
+    private membershipConsistent;
+    /**
+     * Claim pass + totals reconciliation for a PENDING payout.
+     *
+     * The claim set is the union of rows already stamped with this payout
+     * (an interrupted earlier pass) and the currently gathered eligible
+     * rows. Claims go through the collections' conditional `claimForPayout`
+     * (rows owned by another batch are skipped); totals are then recomputed
+     * from the claimed rows and saved when they drift from what the payout
+     * carries. In the pathological all-rows-raced-away case the payout keeps
+     * zero totals and a note — auditable, never double-paid.
+     */
+    private claimAndReconcile;
+    /**
+     * Complete a payout: flip the batch's settled commissions
+     * `payable → paid` FIRST, then `payout.complete(paymentReference)`
+     * (requires status `processing`). Ordering matters for recoverability —
+     * if a member save fails mid-loop the payout is still `processing`, so a
+     * retry finishes the remaining members (already-paid ones are skipped)
+     * and then finalizes; the terminal transition never strands `payable`
+     * members behind a `completed` payout. Adjustments carry no status —
+     * stamping `payoutId` at batch time already settled them.
+     */
+    completePayout(payoutId: string, paymentReference: string, now?: Date): Promise<CommissionPayout>;
+    /**
+     * Fail a payout (`approved | processing → failed`). The batch's rows stay
+     * stamped — after `resetFromFailed()` the SAME payout retries the SAME
+     * rows; releasing the rows to a different batch would double-pay them if
+     * the failed remittance later settled.
+     */
+    failPayout(payoutId: string, reason: string): Promise<CommissionPayout>;
+    /**
+     * Unsettled adjustments for the earner/currency whose parent commission
+     * is earned/approved/payable/paid — the same eligibility rule the balance
+     * service applies, so batches settle exactly what balances report.
+     */
+    private findEligibleUnsettledAdjustments;
+    private requirePayout;
+    /** `${earnerId}:${currency}:${YYYY-MM-DD of periodEnd}` — see the input doc. */
+    private static defaultIdempotencyKey;
+}
+export default CommissionPayoutService;
+//# sourceMappingURL=CommissionPayoutService.d.ts.map

package/dist/commissions/services/CommissionPayoutService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommissionPayoutService.d.ts","sourceRoot":"","sources":["../../../src/commissions/services/CommissionPayoutService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,8BAA8B,EAAE,MAAM,kDAAkD,CAAC;AAClG,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,8CAA8C,CAAC;AAC1F,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAErB,yDAAyD;AACzD,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,gBAAgB,CAAC;IAC1B,WAAW,EAAE,oBAAoB,CAAC;IAClC,WAAW,EAAE,8BAA8B,CAAC;IAC5C,OAAO,EAAE,0BAA0B,CAAC;CACrC;AAED,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,6CAA6C;IAC7C,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,8CAA8C;IAC9C,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,mEAAmE;AACnE,MAAM,WAAW,uBAAuB;IACtC,sFAAsF;IACtF,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,CAAC;IAC/C,gEAAgE;IAChE,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,gEAAgE;IAChE,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,qBAAa,uBAAuB;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,2BAA2B;WAEjD,MAAM,CACjB,YAAY,GAAE,gBAAqB,GAClC,OAAO,CAAC,uBAAuB,CAAC;IASnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,iBAAiB,CACrB,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,uBAAuB,CAAC;IAqHnC;;;;;OAKG;YACW,oBAAoB;IAsBlC;;;;;;;;;;OAUG;YACW,iBAAiB;IA8E/B;;;;;;;;;OASG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,EACxB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC,gBAAgB,CAAC;IA0B5B;;;;;OAKG;IACG,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,CAAC;IAO5B;;;;OAIG;YACW,gCAAgC;YA6BhC,aAAa;IAU3B,gFAAgF;IAChF,OAAO,CAAC,MAAM,CAAC,qBAAqB;CAOrC;AAED,eAAe,uBAAuB,CAAC"}