@happyvertical/smrt-sales 0.51.31 → 0.51.33

package/dist/chunks/{__smrt-register__-Bbvn3zZz.js.map → __smrt-register__-CSbufn1D.js.map}

@@ -1 +1 @@
-{"version":3,"file":"__smrt-register__-Bbvn3zZz.js","names":[],"sources":["../../src/__smrt-register__.ts"],"sourcesContent":["import { ObjectRegistry } from '@happyvertical/smrt-core';\n\nObjectRegistry.registerPackageManifest(\n  new URL('./manifest.json', import.meta.url),\n);\n"],"mappings":""}
+{"version":3,"file":"__smrt-register__-CSbufn1D.js","names":[],"sources":["../../src/__smrt-register__.ts"],"sourcesContent":["import { ObjectRegistry } from '@happyvertical/smrt-core';\n\nObjectRegistry.registerPackageManifest(\n  new URL('./manifest.json', import.meta.url),\n);\n"],"mappings":""}

package/dist/commissions/collections/CommissionAdjustmentCollection.d.ts

@@ -1,3 +1,16 @@
+/**
+ * CommissionAdjustmentCollection — collection manager for
+ * {@link CommissionAdjustment}.
+ *
+ * "Unsettled" means `payoutId` is empty (checked in memory so `''`/`NULL`
+ * storage differences don't matter). NOTE: the collection-level queries do
+ * NOT apply the parent-commission-status eligibility rule — that lives in
+ * `CommissionBalanceService` / `CommissionPayoutService`, which filter
+ * unsettled adjustments to those whose parent commission is
+ * earned/approved/payable/paid.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { CommissionAdjustment } from '../models/CommissionAdjustment.js';
 export declare class CommissionAdjustmentCollection extends SmrtCollection<CommissionAdjustment> {

package/dist/commissions/collections/CommissionAdjustmentOperationCollection.d.ts

@@ -1,3 +1,4 @@
+/** Database serialization primitive for adjustment operation UUIDs. */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { CommissionAdjustmentOperation } from '../models/CommissionAdjustmentOperation.js';
 export interface ClaimCommissionAdjustmentOperationInput {

package/dist/commissions/collections/CommissionCollection.d.ts

@@ -1,6 +1,17 @@
+/**
+ * CommissionCollection — collection manager for {@link Commission}.
+ *
+ * "Unsettled" throughout means `payoutId` is empty — the row has not been
+ * gathered into a {@link CommissionPayout} batch yet. The emptiness check is
+ * applied in memory (`!c.payoutId`) rather than as a `WHERE payout_id = ''`
+ * filter so the semantics hold whether an adapter stores the empty
+ * reference as `''` or `NULL`.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Commission } from '../models/Commission.js';
-import { CommissionStatus } from '../types.js';
+import type { CommissionStatus } from '../types.js';
 export declare class CommissionCollection extends SmrtCollection<Commission> {
     static readonly _itemClass: typeof Commission;
     /** All commissions for an earner, newest first. */

package/dist/commissions/collections/CommissionPayoutCollection.d.ts

@@ -1,6 +1,11 @@
+/**
+ * CommissionPayoutCollection — collection manager for
+ * {@link CommissionPayout}.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { CommissionPayout } from '../models/CommissionPayout.js';
-import { CommissionPayoutStatus } from '../types.js';
+import type { CommissionPayoutStatus } from '../types.js';
 export declare class CommissionPayoutCollection extends SmrtCollection<CommissionPayout> {
     static readonly _itemClass: typeof CommissionPayout;
     /** All payout batches for an earner, newest first. */

package/dist/commissions/collections/CommissionPlanCollection.d.ts

@@ -1,6 +1,14 @@
+/**
+ * CommissionPlanCollection — collection manager for {@link CommissionPlan}.
+ *
+ * Plans are versioned rows: amendments insert `(planKey, maxVersion + 1)`
+ * drafts via {@link createAmendment}; existing versions are never rewritten.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { CommissionPlan } from '../models/CommissionPlan.js';
-import { CommissionPlanComponent, CommissionPlanStatus } from '../types.js';
+import type { CommissionPlanComponent, CommissionPlanStatus } from '../types.js';
 /**
  * Fields an amendment may change relative to the version it copies.
  * `planKey` is fixed (it identifies the plan), `version` is computed, and

package/dist/commissions/collections/EarnerCollection.d.ts

@@ -1,6 +1,10 @@
+/**
+ * EarnerCollection — collection manager for {@link Earner}.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Earner } from '../models/Earner.js';
-import { EarnerStatus } from '../types.js';
+import type { EarnerStatus } from '../types.js';
 export declare class EarnerCollection extends SmrtCollection<Earner> {
     static readonly _itemClass: typeof Earner;
     /** Earners linked to a smrt-profiles Profile. */

package/dist/commissions/collections/EarnerSourceAttributionCollection.d.ts

@@ -1,3 +1,13 @@
+/**
+ * EarnerSourceAttributionCollection — collection manager for
+ * {@link EarnerSourceAttribution}.
+ *
+ * The queries here are the indexed primitives; the earner-resolving lookups
+ * (single + batched, active-earner filtered, ambiguity fail-closed) live on
+ * `EarnerAttributionService`.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { EarnerSourceAttribution } from '../models/EarnerSourceAttribution.js';
 export declare class EarnerSourceAttributionCollection extends SmrtCollection<EarnerSourceAttribution> {

package/dist/commissions/collections/EarningEventCollection.d.ts

@@ -1,6 +1,10 @@
+/**
+ * EarningEventCollection — collection manager for {@link EarningEvent}.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { EarningEvent } from '../models/EarningEvent.js';
-import { EarningEventOptions } from '../types.js';
+import type { EarningEventOptions } from '../types.js';
 export declare class EarningEventCollection extends SmrtCollection<EarningEvent> {
     static readonly _itemClass: typeof EarningEvent;
     /** Look up an event by its idempotency natural key. */

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

@@ -1,5 +1,31 @@
+/**
+ * Commission — one earning record for one earner, one plan component, one
+ * earning-event occurrence.
+ *
+ * Amounts are integer cents; `rate`/`shareFraction` are decimals in 0–1.
+ * Every row stores snapshot references (`planKey`/`planVersion` plus a
+ * generic polymorphic `termsSnapshotKind`/`termsSnapshotId` — the referrals
+ * module points the latter at its ReferralTermSnapshot) and a JSON
+ * `calculationTrace` sufficient to reproduce `amountCents`, so earnings stay
+ * auditable after plans are superseded.
+ *
+ * Lifecycle is a STRICT forward chain — `pending → earned → approved →
+ * payable → paid` — enforced at save time against the AUTHORITATIVE prior
+ * persisted status (re-read from the database, commerce pattern), so neither
+ * raw mass-assignment nor a `create({ id, _skipLoad: true })` upsert can skip
+ * steps or roll back. Use the transition methods ({@link markEarned} /
+ * {@link approve} / {@link markPayable} / {@link markPaid}); they mutate and
+ * stamp timestamps but DO NOT save — the caller saves (one explicit
+ * persistence point per mutation, matching commerce's markSent/markConfirmed
+ * convention).
+ *
+ * Commissions are audit rows: the generated surface has no update or delete.
+ * Corrections append {@link CommissionAdjustment} rows instead of editing.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { CommissionBasis, CommissionCalculationTrace, CommissionOptions, CommissionStatus } from '../types.js';
+import type { CommissionBasis, CommissionCalculationTrace, CommissionOptions, CommissionStatus } from '../types.js';
 export declare class Commission extends SmrtObject {
     /** Tenant ID for multi-tenant isolation (nullable → global rows). */
     tenantId: string | null;

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

@@ -1,5 +1,23 @@
+/**
+ * CommissionAdjustment — append-only correction against a Commission.
+ *
+ * Earned/paid Commissions are NEVER rewritten. A refund, credit,
+ * chargeback, dispute outcome, or manual correction appends one of these
+ * rows instead. `amountCents` is SIGNED — negative amounts claw earnings
+ * back; positive amounts credit extra.
+ *
+ * Immutability contract: once persisted, an adjustment's substance
+ * (`commissionId`, `earnerId`, `adjustmentKind`, `amountCents`, `currency`,
+ * `reason`, `createdByProfileId`, `metadata`, `tenantId`) is frozen — the
+ * save-time guard rejects any change via a WeakMap snapshot compare (the
+ * commerce LicenseSale pattern). The ONLY post-create mutation allowed is
+ * stamping/clearing `payoutId` when a settlement batch picks the row up.
+ * A wrong adjustment is corrected by appending a counter-adjustment.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { CommissionAdjustmentKind, CommissionAdjustmentOptions } from '../types.js';
+import type { CommissionAdjustmentKind, CommissionAdjustmentOptions } from '../types.js';
 export declare class CommissionAdjustment extends SmrtObject {
     /** Tenant ID for multi-tenant isolation (nullable → global rows). */
     tenantId: string | null;

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

@@ -1,4 +1,5 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/** Persisted serialization fence for idempotent CommissionAdjustment writes. */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 interface CommissionAdjustmentOperationOptions extends SmrtObjectOptions {
     tenantId?: string;
     adjustmentId?: string;

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

@@ -1,5 +1,39 @@
+/**
+ * CommissionPayout — settlement batch for one earner in one currency.
+ *
+ * A payout gathers an earner's payable unsettled Commissions plus the
+ * unsettled Adjustments of eligible commissions, stamps `payoutId` on those
+ * EXACT rows, and records the totals it settled
+ * (`totalAmountCents = commissionTotalCents + adjustmentTotalCents` —
+ * enforced at save time). Batches are minted by
+ * `CommissionPayoutService.createPayoutBatch`, idempotently via the
+ * `idempotencyKey` natural key.
+ *
+ * The model is named CommissionPayout (table `commission_payouts`) to avoid
+ * the global table-name collision with commerce `Payout` / legacy affiliates
+ * `Payout` (`payouts`).
+ *
+ * Generated surface is FULLY read-only — list/get on api, mcp, AND cli.
+ * Commerce Payout precedent ("a payout has no safe generated write"): the
+ * status drives an outgoing remittance and the totals are the integrity
+ * core, so the only legitimate writes are the service's creation path and
+ * the guarded transition helpers below. The CLI is an independently
+ * configured write surface — `cli: true` would regenerate the exact
+ * create/update vector closed on api/mcp, so it is locked to list/get too.
+ *
+ * Lifecycle: `pending → approved → processing → completed | failed`, with
+ * `failed` reachable from approved/processing and resettable to `pending`
+ * only via {@link resetFromFailed}, and `rejected` the terminal
+ * operator-decline exit from pending/approved (see {@link reject} — the
+ * membership release lives in
+ * `CommissionPayoutService.transitionPayoutForSource`). Transition helpers
+ * mutate and stamp but DO NOT save — the caller saves (same convention as
+ * Commission).
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { CommissionPayoutOptions, CommissionPayoutStatus, PayoutMethod } from '../types.js';
+import type { CommissionPayoutOptions, CommissionPayoutStatus, PayoutMethod } from '../types.js';
 export declare class CommissionPayout extends SmrtObject {
     /** Tenant ID for multi-tenant isolation (nullable → global payouts). */
     tenantId: string | null;

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

@@ -1,5 +1,23 @@
+/**
+ * CommissionPlan — versioned commission calculation terms.
+ *
+ * A plan is identified by its `(planKey, version)` natural key. Versions are
+ * ROWS, not edits: amending a plan inserts a `version + 1` draft (see
+ * `CommissionPlanCollection.createAmendment`) and the prior version is never
+ * rewritten. Once a row has been saved with status `active`, its calculation
+ * identity (`components`, `currency`, `planKey`, `version`, `effectiveFrom`)
+ * is frozen — re-saving with any of them changed throws (same
+ * WeakMap-serialize pattern as commerce's `LicenseSale` rights snapshot).
+ * Status transitions remain allowed on frozen rows.
+ *
+ * Generated write surface is deliberately narrow: `create` only (drafts),
+ * NO generated update route — amendments are new rows, and status moves go
+ * through the guarded transition methods / legal save-time edges.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { CommissionPlanComponent, CommissionPlanOptions, CommissionPlanStatus } from '../types.js';
+import { type CommissionPlanComponent, type CommissionPlanOptions, type 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

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

@@ -1,5 +1,17 @@
+/**
+ * Earner — neutral financial payout account.
+ *
+ * Replaces the financial half of legacy smrt-affiliates' `Partner`: it holds
+ * everything money-related about a party that earns commissions (payout
+ * method, threshold, schedule, currency, status) and NOTHING role-related.
+ * Role models (a CRM `SalesRepresentative`, a referrals `Referrer`, or any
+ * application-defined role) each hold their own `earnerId` pointing here, so
+ * one person acting in several roles still settles through a single account.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { EarnerOptions, EarnerStatus, PayoutMethod } from '../types.js';
+import type { EarnerOptions, EarnerStatus, PayoutMethod } from '../types.js';
 export declare class Earner extends SmrtObject {
     /**
      * Tenant ID for multi-tenant isolation. Nullable so global/operator-level

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

@@ -1,5 +1,64 @@
+/**
+ * EarnerSourceAttribution — indexed external attribution mapping for an
+ * {@link Earner}.
+ *
+ * Maps a generic external key `(sourceKind, sourceId)` — an ad-network
+ * property, a marketplace storefront, a partner account, any
+ * application-defined attribution surface — to the Earner credited for it.
+ * High-volume ingestion resolves earners through the indexed lookups on
+ * `EarnerSourceAttributionCollection` / `EarnerAttributionService` instead of
+ * scanning every active earner's JSON metadata.
+ *
+ * The kind space is the CONSUMER's to define. It may — but need not —
+ * coincide with the `(sourceKind, sourceId)` earning-source pairs recorded on
+ * EarningEvents and Commissions: an application can attribute earners by
+ * property while its earning events carry the network as their source.
+ *
+ * ## Uniqueness and tenancy
+ *
+ * Natural key `(tenant_id, source_kind, source_id)` (`conflictColumns`): one
+ * mapping per external key per tenant. A `create` for an existing key
+ * UPSERTS — it re-points the mapping to the new `earnerId` (idempotent
+ * registration; use `EarnerAttributionService.registerAttribution` to observe
+ * whether a call created or re-pointed). The adapters' null-aware upsert
+ * dedups NULL-tenant (global) keys too, but the unique INDEX itself treats
+ * NULLs as distinct, so duplicate global rows can still arrive outside the
+ * model layer (raw-SQL imports, pre-null-aware data) — the lookups treat
+ * more than one ACTIVE row for a key as ambiguous and fail closed instead
+ * of picking one.
+ *
+ * With an active tenant context, lookups resolve within that tenant only
+ * (global rows are invisible). Without tenant context (`optional` mode)
+ * lookups see every row, so operator-level resolution across tenants can
+ * surface an ambiguity that per-tenant resolution would not — tenant-scoped
+ * applications should resolve inside `withTenant()`.
+ *
+ * ## Migrating metadata-based associations
+ *
+ * Consumers that previously stashed the association in `Earner.metadata`
+ * migrate with a one-time loop — `registerAttribution` is the idempotent
+ * backfill primitive (re-running the loop upserts, never duplicates):
+ *
+ * ```typescript
+ * const service = await EarnerAttributionService.create({ db });
+ * for (const earner of await earners.list({})) {
+ *   const propertyIds = (earner.getMetadata().propertyIds ?? []) as string[];
+ *   for (const propertyId of propertyIds) {
+ *     await service.registerAttribution({
+ *       earnerId: earner.id!,
+ *       sourceKind: 'ad_network_property',
+ *       sourceId: propertyId,
+ *       tenantId: earner.tenantId,
+ *     });
+ *   }
+ * }
+ * // Verify via resolveActiveEarnersBySources(), then drop the metadata key.
+ * ```
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { EarnerSourceAttributionOptions, EarnerSourceAttributionStatus } from '../types.js';
+import type { EarnerSourceAttributionOptions, EarnerSourceAttributionStatus } from '../types.js';
 export declare class EarnerSourceAttribution extends SmrtObject {
     /** Tenant ID for multi-tenant isolation (nullable → global mappings). */
     tenantId: string | null;

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

@@ -1,5 +1,32 @@
+/**
+ * EarningEvent — immutable commercial-event evidence.
+ *
+ * An EarningEvent records that something commission-worthy happened: a
+ * conversion, an agreement execution, an invoice payment, collected revenue,
+ * recognized margin, a milestone — or any application-defined kind
+ * (`eventKind` is an open string; see `EARNING_EVENT_KINDS` for the
+ * recommended vocabulary). The source is a generic `(sourceKind, sourceId)`
+ * string pair — this module never assumes advertising, Referral, Lead, or
+ * Opportunity semantics.
+ *
+ * Immutability contract: events are evidence. The generated surface exposes
+ * `create`/`list`/`get` only (no update, no delete), and application code
+ * must treat persisted rows as append-only — commissions reference an
+ * event's amounts in their calculation traces, so rewriting an event would
+ * silently orphan the audit trail. Corrections are modelled as NEW events
+ * (e.g. a `refund`-kind event) or as `CommissionAdjustment` rows.
+ *
+ * Idempotent ingestion: `dedupeKey` is the natural key
+ * (`conflictColumns: ['dedupe_key']`). Callers embed tenant and source
+ * identity in the key — e.g.
+ * `` `${tenantId}:${sourceKind}:${sourceId}:${eventKind}:${occurrence}` `` —
+ * so a retried ingest resolves to the existing row (see
+ * `EarningEventCollection.getOrCreateByDedupeKey`).
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { EarningEventOptions } from '../types.js';
+import type { EarningEventOptions } from '../types.js';
 export declare class EarningEvent extends SmrtObject {
     /** Tenant ID for multi-tenant isolation (nullable → global events). */
     tenantId: string | null;

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

@@ -1,6 +1,7 @@
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
-import { CommissionAdjustment } from '../models/CommissionAdjustment.js';
-import { CommissionAdjustmentKind } from '../types.js';
+/** Tenant-safe, idempotent creation of immutable commission adjustments. */
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
+import type { CommissionAdjustment } from '../models/CommissionAdjustment.js';
+import { type CommissionAdjustmentKind } from '../types.js';
 /** One immutable operator correction intent. */
 export interface CreateCommissionAdjustmentInput {
     /** Stable caller-supplied UUID; retries MUST reuse it. */

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

@@ -1,7 +1,21 @@
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
+/**
+ * CommissionBalanceService — computed (never stored) per-earner balances.
+ *
+ * `payableCents` is the sum of unsettled `payable` commissions;
+ * `unsettledAdjustmentCents` is the signed sum of unsettled adjustments
+ * whose parent commission is earned/approved/payable/paid (adjustments
+ * against still-`pending` commissions wait for the earning to clear);
+ * `netPayableCents = payableCents + unsettledAdjustmentCents` and can go
+ * NEGATIVE when clawbacks against already-paid commissions exceed what is
+ * currently payable. The pending/earned/approved breakdowns feed portal
+ * views.
+ *
+ * @packageDocumentation
+ */
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
 import { CommissionAdjustmentCollection } from '../collections/CommissionAdjustmentCollection.js';
 import { CommissionCollection } from '../collections/CommissionCollection.js';
-import { EarnerBalance } from '../types.js';
+import { type EarnerBalance } from '../types.js';
 export declare class CommissionBalanceService {
     private readonly commissions;
     private readonly adjustments;

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

@@ -1,9 +1,21 @@
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
+/**
+ * CommissionCalculationService — turns one {@link EarningEvent} into
+ * Commission rows for one earner, driven by a set of plan components.
+ *
+ * The service deliberately takes COMPONENTS (plus `planKey`/`planVersion`
+ * snapshot refs), not a live plan: callers that calculate from frozen terms
+ * — e.g. the referrals module's term snapshots — pass the components they
+ * froze, so a later plan amendment can never leak into an already-agreed
+ * calculation.
+ *
+ * @packageDocumentation
+ */
+import type { 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';
+import type { Commission } from '../models/Commission.js';
+import type { EarningEvent } from '../models/EarningEvent.js';
+import type { CommissionPlanComponent } from '../types.js';
 /** Input for {@link CommissionCalculationService.calculateForEvent}. */
 export interface CommissionCalculationInput {
     /** The (persisted) earning event to calculate from. */

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

@@ -1,10 +1,35 @@
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
+/**
+ * CommissionPayoutService — mints and drives {@link CommissionPayout}
+ * settlement batches.
+ *
+ * The service is the ONLY sanctioned creation path for payouts (their
+ * generated surface is fully read-only): it gathers the exact payable
+ * unsettled Commissions and eligible unsettled Adjustments, refuses
+ * below-threshold / non-positive batches, stamps `payoutId` on the exact
+ * gathered rows, and later flips the batch's commissions to `paid` when the
+ * payout completes.
+ *
+ * Batch creation is deliberately non-transactional (conditional claims +
+ * disjoint scopes — see {@link createPayoutBatch}). Two surfaces layered on
+ * top serve per-source consumers:
+ *
+ * - {@link getSourcePayoutHistory} — the source-scoped, paginated,
+ *   membership-verified payout history (#1985), indexed by the derived
+ *   single-source stamp each batch/repair pass maintains.
+ * - {@link transitionPayoutForSource} — atomic source-authorized lifecycle
+ *   transitions (#1987): payout row locked, membership re-verified and
+ *   totals recomputed under the lock, transition + member writes committed
+ *   together on the same transaction database.
+ *
+ * @packageDocumentation
+ */
+import type { 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 { CommissionPayoutStatus, PayoutMethod } from '../types.js';
+import type { CommissionPayout } from '../models/CommissionPayout.js';
+import { type CommissionPayoutStatus, type PayoutMethod } from '../types.js';
 /** Collaborators for {@link CommissionPayoutService}. */
 export interface CommissionPayoutServiceDeps {
     earners: EarnerCollection;

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

@@ -1,6 +1,17 @@
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
+/**
+ * CommissionSettlementService — advances Commissions along the strict
+ * `pending → earned → approved → payable` chain (the final `payable → paid`
+ * step belongs to `CommissionPayoutService.completePayout`, which flips a
+ * batch's rows when the money actually moves).
+ *
+ * All methods persist the rows they advance (transition method + save per
+ * row) and return the updated instances.
+ *
+ * @packageDocumentation
+ */
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
 import { CommissionCollection } from '../collections/CommissionCollection.js';
-import { Commission } from '../models/Commission.js';
+import type { Commission } from '../models/Commission.js';
 export declare class CommissionSettlementService {
     private readonly commissions;
     constructor(commissions: CommissionCollection);

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

@@ -1,9 +1,27 @@
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
+/**
+ * EarnerAttributionService — registration and indexed resolution of
+ * {@link EarnerSourceAttribution} mappings.
+ *
+ * High-volume ingestion (e.g. billing events that must credit an earner per
+ * ad-network property) resolves earners here: one indexed attribution query
+ * plus one earner load per call, bounded by the REQUESTED keys — never a
+ * scan of all active earners. Resolution is fail-closed: a key that cannot
+ * be proven to map to exactly one active mapping and one active earner
+ * resolves to nothing, with a typed reason.
+ *
+ * Registration is the idempotent write path (and the documented
+ * metadata-migration backfill primitive — see the model doc): re-registering
+ * a key updates the existing mapping in place and reports the displaced
+ * earner instead of silently duplicating.
+ *
+ * @packageDocumentation
+ */
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
 import { EarnerCollection } from '../collections/EarnerCollection.js';
 import { EarnerSourceAttributionCollection } from '../collections/EarnerSourceAttributionCollection.js';
-import { Earner } from '../models/Earner.js';
-import { EarnerSourceAttribution } from '../models/EarnerSourceAttribution.js';
-import { EarnerSourceAttributionStatus } from '../types.js';
+import type { Earner } from '../models/Earner.js';
+import type { EarnerSourceAttribution } from '../models/EarnerSourceAttribution.js';
+import type { EarnerSourceAttributionStatus } from '../types.js';
 /** Collaborators for {@link EarnerAttributionService}. */
 export interface EarnerAttributionServiceDeps {
     earners: EarnerCollection;

package/dist/commissions/types.d.ts

@@ -1,4 +1,19 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * Shared types for the neutral commissions financial core.
+ *
+ * Statuses are string-literal unions derived from `as const` arrays (no TS
+ * enums) so downstream code can iterate the legal values and the types stay
+ * erasable. All monetary fields across the module are integer cents with a
+ * `*Cents` suffix; rates/fractions are decimals in the range 0–1.
+ *
+ * This module is the neutral financial core of `@happyvertical/smrt-sales`:
+ * it never imports from the `crm` or `referrals` modules and never assumes
+ * advertising, Referral, Lead, or Opportunity semantics. Earning sources are
+ * generic `(sourceKind, sourceId)` string pairs.
+ *
+ * @packageDocumentation
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
 /** Lifecycle of an {@link Earner} payout account. */
 export declare const EARNER_STATUSES: readonly ["pending", "active", "suspended"];
 export type EarnerStatus = (typeof EARNER_STATUSES)[number];

package/dist/commissions.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Subpath entry: `@happyvertical/smrt-sales/commissions`.
+ *
+ * Neutral commission financial core: Earners, versioned Commission Plans,
+ * earning events, Commissions, append-only adjustments, payable balances,
+ * and CommissionPayout batches. Commission sources are extensible and never
+ * assume advertising, Referral, Lead, or Opportunity semantics.
+ */
+import './__smrt-register__.js';
 export * from './commissions/index.js';
 //# sourceMappingURL=commissions.d.ts.map

package/dist/commissions.js

@@ -1,3 +1,3 @@
-import "./chunks/__smrt-register__-Bbvn3zZz.js";
+import "./chunks/__smrt-register__-CSbufn1D.js";
 import { A as EARNING_EVENT_KINDS, C as COMMISSION_ADJUSTMENT_KINDS, D as COMMISSION_STATUSES, E as COMMISSION_PLAN_STATUSES, F as Commission, I as CommissionAdjustmentOperationCollection, L as CommissionAdjustmentOperation, M as CommissionPayoutCollection, N as CommissionPayout, O as EARNER_SOURCE_ATTRIBUTION_STATUSES, P as CommissionCollection, R as CommissionAdjustmentCollection, S as ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES, T as COMMISSION_PAYOUT_STATUSES, _ as EarnerCollection, a as CommissionBalanceService, b as CommissionPlan, c as CommissionAdjustmentValidationError, d as centsToAmount, f as roundCents, g as EarnerSourceAttribution, h as EarnerSourceAttributionCollection, i as CommissionCalculationService, j as PAYOUT_METHODS, k as EARNER_STATUSES, l as amountToCents, m as EarningEvent, n as CommissionSettlementService, o as CommissionAdjustmentReplayConflictError, p as EarningEventCollection, r as CommissionPayoutService, s as CommissionAdjustmentService, t as EarnerAttributionService, u as calculateCommissionAmountCents, v as Earner, w as COMMISSION_BASES, x as validateCommissionPlanComponents, y as CommissionPlanCollection, z as CommissionAdjustment } from "./chunks/commissions-BlJpPXFC.js";
 export { ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES, COMMISSION_ADJUSTMENT_KINDS, COMMISSION_BASES, COMMISSION_PAYOUT_STATUSES, COMMISSION_PLAN_STATUSES, COMMISSION_STATUSES, Commission, CommissionAdjustment, CommissionAdjustmentCollection, CommissionAdjustmentOperation, CommissionAdjustmentOperationCollection, CommissionAdjustmentReplayConflictError, CommissionAdjustmentService, CommissionAdjustmentValidationError, CommissionBalanceService, CommissionCalculationService, CommissionCollection, CommissionPayout, CommissionPayoutCollection, CommissionPayoutService, CommissionPlan, CommissionPlanCollection, CommissionSettlementService, EARNER_SOURCE_ATTRIBUTION_STATUSES, EARNER_STATUSES, EARNING_EVENT_KINDS, Earner, EarnerAttributionService, EarnerCollection, EarnerSourceAttribution, EarnerSourceAttributionCollection, EarningEvent, EarningEventCollection, PAYOUT_METHODS, amountToCents, calculateCommissionAmountCents, centsToAmount, roundCents, validateCommissionPlanComponents };

package/dist/crm/collections/LeadCollection.d.ts

@@ -1,8 +1,13 @@
+/**
+ * LeadCollection — collection manager for Lead, including qualification into
+ * opportunities, audited duplicate merges, and merge-aware history reads.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Lead } from '../models/Lead.js';
-import { Opportunity } from '../models/Opportunity.js';
-import { SalesActivity } from '../models/SalesActivity.js';
-import { LeadStatus, MergeLeadsParams, MergeLeadsResult, QualifyLeadParams } from '../types.js';
+import type { Opportunity } from '../models/Opportunity.js';
+import type { SalesActivity } from '../models/SalesActivity.js';
+import type { LeadStatus, MergeLeadsParams, MergeLeadsResult, QualifyLeadParams } from '../types.js';
 export declare class LeadCollection extends SmrtCollection<Lead> {
     static readonly _itemClass: typeof Lead;
     private opportunityCollectionPromise;

package/dist/crm/collections/OpportunityCollection.d.ts

@@ -1,6 +1,11 @@
+/**
+ * OpportunityCollection — collection manager for Opportunity, including
+ * validated, audited stage movement.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Opportunity } from '../models/Opportunity.js';
-import { MoveToStageParams } from '../types.js';
+import type { MoveToStageParams } from '../types.js';
 export declare class OpportunityCollection extends SmrtCollection<Opportunity> {
     static readonly _itemClass: typeof Opportunity;
     private stageCollectionPromise;

package/dist/crm/collections/OpportunityConversionCollection.d.ts

@@ -1,6 +1,11 @@
+/**
+ * OpportunityConversionCollection — collection manager for
+ * OpportunityConversion, including the idempotent recorder.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { OpportunityConversion } from '../models/OpportunityConversion.js';
-import { RecordConversionParams, RecordConversionResult } from '../types.js';
+import type { RecordConversionParams, RecordConversionResult } from '../types.js';
 export declare class OpportunityConversionCollection extends SmrtCollection<OpportunityConversion> {
     static readonly _itemClass: typeof OpportunityConversion;
     private opportunityCollectionPromise;