@happyvertical/smrt-sales 0.51.32 → 0.51.34

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

@@ -1,7 +1,12 @@
+/**
+ * PipelineDefinitionCollection — collection manager for PipelineDefinition,
+ * including the idempotent default-pipeline seeder.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { PipelineDefinition } from '../models/PipelineDefinition.js';
-import { PipelineStage } from '../models/PipelineStage.js';
-import { EnsureDefaultPipelineParams, EnsureDefaultPipelineResult } from '../types.js';
+import type { PipelineStage } from '../models/PipelineStage.js';
+import { type EnsureDefaultPipelineParams, type EnsureDefaultPipelineResult } from '../types.js';
 export declare class PipelineDefinitionCollection extends SmrtCollection<PipelineDefinition> {
     static readonly _itemClass: typeof PipelineDefinition;
     private stageCollectionPromise;

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

@@ -1,3 +1,7 @@
+/**
+ * PipelineStageCollection — collection manager for PipelineStage.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { PipelineStage } from '../models/PipelineStage.js';
 export declare class PipelineStageCollection extends SmrtCollection<PipelineStage> {

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

@@ -1,6 +1,10 @@
+/**
+ * SalesActivityCollection — collection manager for the SalesActivity trail.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { SalesActivity } from '../models/SalesActivity.js';
-import { SalesActivitySubjectKind } from '../types.js';
+import type { SalesActivitySubjectKind } from '../types.js';
 export declare class SalesActivityCollection extends SmrtCollection<SalesActivity> {
     static readonly _itemClass: typeof SalesActivity;
     /**

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

@@ -1,3 +1,7 @@
+/**
+ * SalesRepresentativeCollection — collection manager for SalesRepresentative.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { SalesRepresentative } from '../models/SalesRepresentative.js';
 export declare class SalesRepresentativeCollection extends SmrtCollection<SalesRepresentative> {

package/dist/crm/models/Lead.d.ts

@@ -1,5 +1,9 @@
+/**
+ * Lead — identified prospect with guarded lifecycle and audited merge support.
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { LeadOptions, LeadStatus } from '../types.js';
+import type { LeadOptions, LeadStatus } from '../types.js';
 /**
  * Lead is an identified prospect: a person/organization that showed intent
  * but has not yet been qualified into an Opportunity.

package/dist/crm/models/Opportunity.d.ts

@@ -1,5 +1,9 @@
+/**
+ * Opportunity — a qualified engagement moving through a pipeline.
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { OpportunityOptions, OpportunityStatus } from '../types.js';
+import type { OpportunityOptions, OpportunityStatus } from '../types.js';
 /**
  * Opportunity is a qualified engagement: a deal with an expected value moving
  * through the stages of a PipelineDefinition.

package/dist/crm/models/OpportunityConversion.d.ts

@@ -1,5 +1,9 @@
+/**
+ * OpportunityConversion — idempotent link from a won deal to a downstream record.
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { OpportunityConversionOptions } from '../types.js';
+import type { OpportunityConversionOptions } from '../types.js';
 /**
  * OpportunityConversion records that a WON opportunity materialized into a
  * downstream record — a client, project, contract, subscription, or any

package/dist/crm/models/PipelineDefinition.d.ts

@@ -1,5 +1,9 @@
+/**
+ * PipelineDefinition — a named, tenant-scoped sales pipeline.
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { PipelineDefinitionOptions, PipelineStatus } from '../types.js';
+import type { PipelineDefinitionOptions, PipelineStatus } from '../types.js';
 /**
  * PipelineDefinition names an ordered set of {@link PipelineStage | stages}
  * that opportunities move through. Pipelines are configuration rows, not

package/dist/crm/models/PipelineStage.d.ts

@@ -1,5 +1,9 @@
+/**
+ * PipelineStage — one ordered step of a PipelineDefinition.
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { PipelineStageOptions } from '../types.js';
+import type { PipelineStageOptions } from '../types.js';
 /**
  * PipelineStage is a configurable step within a pipeline. Stages carry the
  * default win `probability` an opportunity adopts on entry and the terminal

package/dist/crm/models/SalesActivity.d.ts

@@ -1,5 +1,9 @@
+/**
+ * SalesActivity — the activity, next-action, and audit trail for CRM subjects.
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { SalesActivityOptions, SalesActivitySubjectKind } from '../types.js';
+import type { SalesActivityOptions, SalesActivitySubjectKind } from '../types.js';
 /**
  * Permit one monotonic `completedAt` stamp on a hydrated task.
  *

package/dist/crm/models/SalesRepresentative.d.ts

@@ -1,5 +1,9 @@
+/**
+ * SalesRepresentative — the sales-rep role model.
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { SalesRepresentativeOptions, SalesRepresentativeStatus } from '../types.js';
+import type { SalesRepresentativeOptions, SalesRepresentativeStatus } from '../types.js';
 /**
  * SalesRepresentative is a ROLE model: it links an identity (smrt-profiles
  * Profile) to sales ownership (Leads/Opportunities reference `ownerRepId`).

package/dist/crm/services/LeadWorkflowService.d.ts

@@ -1,8 +1,18 @@
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
-import { Lead } from '../models/Lead.js';
-import { SalesActivity } from '../models/SalesActivity.js';
-import { SalesRepresentative } from '../models/SalesRepresentative.js';
-import { LeadStatus } from '../types.js';
+/**
+ * Tenant-safe, audited follow-up workflow for CRM Leads.
+ *
+ * The service is intentionally the narrow mutation seam for the generic
+ * pre-qualification loop. It does not create opportunities, conversions, or
+ * downstream records; those lifecycles remain owned by their existing CRM
+ * collections and by the consuming application respectively.
+ *
+ * @packageDocumentation
+ */
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
+import type { Lead } from '../models/Lead.js';
+import { type SalesActivity } from '../models/SalesActivity.js';
+import type { SalesRepresentative } from '../models/SalesRepresentative.js';
+import type { LeadStatus } from '../types.js';
 /** Human follow-up kinds accepted by {@link LeadWorkflowService.recordActivity}. */
 export declare const LEAD_HUMAN_ACTIVITY_KINDS: readonly ["note", "call", "email", "meeting"];
 export type LeadHumanActivityKind = (typeof LEAD_HUMAN_ACTIVITY_KINDS)[number];

package/dist/crm/types.d.ts

@@ -1,8 +1,19 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
-import { Lead } from './models/Lead.js';
-import { OpportunityConversion } from './models/OpportunityConversion.js';
-import { PipelineDefinition } from './models/PipelineDefinition.js';
-import { PipelineStage } from './models/PipelineStage.js';
+/**
+ * Shared types, status unions, and operation contracts for the CRM module.
+ *
+ * Statuses are string-literal unions derived from `as const` arrays so both
+ * the runtime list (for validation/UI pickers) and the compile-time union stay
+ * in lockstep. All monetary fields across the module are integer cents
+ * (`*Cents`, INTEGER columns); rates/probabilities are decimals in `0`–`1`
+ * (DECIMAL columns). See `packages/sales/AGENTS.md`.
+ *
+ * @packageDocumentation
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import type { Lead } from './models/Lead.js';
+import type { OpportunityConversion } from './models/OpportunityConversion.js';
+import type { PipelineDefinition } from './models/PipelineDefinition.js';
+import type { PipelineStage } from './models/PipelineStage.js';
 /** Lifecycle statuses for a {@link SalesRepresentativeOptions | SalesRepresentative} role. */
 export declare const SALES_REPRESENTATIVE_STATUSES: readonly ["active", "inactive", "suspended"];
 export type SalesRepresentativeStatus = (typeof SALES_REPRESENTATIVE_STATUSES)[number];

package/dist/crm.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Subpath entry: `@happyvertical/smrt-sales/crm`.
+ *
+ * Leads, Opportunities, configurable Pipelines, tenant-safe follow-up,
+ * sales activity, ownership, and idempotent conversion links — without
+ * referral or commission behavior in the CRM state machine.
+ */
+import './__smrt-register__.js';
 export * from './crm/index.js';
 //# sourceMappingURL=crm.d.ts.map

package/dist/crm.js

@@ -1,3 +1,3 @@
-import "./chunks/__smrt-register__-D4oQpwQY.js";
+import "./chunks/__smrt-register__-CJkQS7rB.js";
 import { C as SalesActivity, D as Lead, E as Opportunity, S as SalesActivityCollection, T as PipelineStage, _ as SALES_ACTIVITY_KINDS, a as projectLeadWorkQueue, b as PipelineDefinition, c as OpportunityConversionCollection, d as PipelineDefinitionCollection, f as DEFAULT_PIPELINE_KEY, g as PIPELINE_STATUSES, h as OPPORTUNITY_STATUSES, i as MAX_LEAD_WORKFLOW_TEXT_LENGTH, l as OpportunityConversion, m as LEAD_STATUSES, n as LeadWorkflowService, o as SalesRepresentativeCollection, p as DEFAULT_PIPELINE_STAGES, r as LeadWorkflowValidationError, s as SalesRepresentative, t as LEAD_HUMAN_ACTIVITY_KINDS, u as LeadCollection, v as SALES_ACTIVITY_SUBJECT_KINDS, w as PipelineStageCollection, x as OpportunityCollection, y as SALES_REPRESENTATIVE_STATUSES } from "./chunks/crm-C2bD25yv.js";
 export { DEFAULT_PIPELINE_KEY, DEFAULT_PIPELINE_STAGES, LEAD_HUMAN_ACTIVITY_KINDS, LEAD_STATUSES, Lead, LeadCollection, LeadWorkflowService, LeadWorkflowValidationError, MAX_LEAD_WORKFLOW_TEXT_LENGTH, OPPORTUNITY_STATUSES, Opportunity, OpportunityCollection, OpportunityConversion, OpportunityConversionCollection, PIPELINE_STATUSES, PipelineDefinition, PipelineDefinitionCollection, PipelineStage, PipelineStageCollection, SALES_ACTIVITY_KINDS, SALES_ACTIVITY_SUBJECT_KINDS, SALES_REPRESENTATIVE_STATUSES, SalesActivity, SalesActivityCollection, SalesRepresentative, SalesRepresentativeCollection, projectLeadWorkQueue };

package/dist/index.d.ts

@@ -1,3 +1,29 @@
+/**
+ * @happyvertical/smrt-sales
+ *
+ * Modular sales for the SMRT framework, shipped as one installable package
+ * with distinct modules:
+ *
+ * - `agreements` (`@happyvertical/smrt-sales/agreements`): provider-neutral
+ *   e-signature lifecycle, verified events, and immutable executed evidence.
+ * - `crm` (`@happyvertical/smrt-sales/crm`): Leads, Opportunities,
+ *   configurable Pipelines, tenant-safe Lead follow-up, sales activity,
+ *   ownership, and idempotent conversion links.
+ * - `referrals` (`@happyvertical/smrt-sales/referrals`): Referrers, Referral
+ *   Programs, links/codes, attribution evidence, versioned attribution
+ *   policies, referral agreements, and qualification term snapshots.
+ * - `commissions` (`@happyvertical/smrt-sales/commissions`): neutral Earners,
+ *   versioned Commission Plans, earning events, Commissions, append-only
+ *   adjustments, payable balances, and CommissionPayout batches.
+ * - `svelte` (`@happyvertical/smrt-sales/svelte`): reusable dashboard and
+ *   Referrer/operator portal components.
+ *
+ * The root export re-exports every module for convenience; the subpath
+ * exports keep consumers' bundles scoped to what they use.
+ *
+ * @packageDocumentation
+ */
+import './__smrt-register__.js';
 export * from './agreements/index.js';
 export * from './commissions/index.js';
 export * from './crm/index.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-import "./chunks/__smrt-register__-D4oQpwQY.js";
+import "./chunks/__smrt-register__-CJkQS7rB.js";
 import { a as AgreementExecutionEvent, c as AGREEMENT_EXECUTION_STATUSES, d as sanitizeSignerIntent, i as AgreementExecutionEventCollection, l as coerceAgreementDate, n as ExecutedAgreementCollection, o as AgreementExecutionCollection, r as ExecutedAgreement, s as AgreementExecution, t as AgreementExecutionService, u as sanitizeSignerEvidence } from "./chunks/agreements-CxHyIbZB.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";
 import { C as SalesActivity, D as Lead, E as Opportunity, S as SalesActivityCollection, T as PipelineStage, _ as SALES_ACTIVITY_KINDS, a as projectLeadWorkQueue, b as PipelineDefinition, c as OpportunityConversionCollection, d as PipelineDefinitionCollection, f as DEFAULT_PIPELINE_KEY, g as PIPELINE_STATUSES, h as OPPORTUNITY_STATUSES, i as MAX_LEAD_WORKFLOW_TEXT_LENGTH, l as OpportunityConversion, m as LEAD_STATUSES, n as LeadWorkflowService, o as SalesRepresentativeCollection, p as DEFAULT_PIPELINE_STAGES, r as LeadWorkflowValidationError, s as SalesRepresentative, t as LEAD_HUMAN_ACTIVITY_KINDS, u as LeadCollection, v as SALES_ACTIVITY_SUBJECT_KINDS, w as PipelineStageCollection, x as OpportunityCollection, y as SALES_REPRESENTATIVE_STATUSES } from "./chunks/crm-C2bD25yv.js";

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-sales",
-  "packageVersion": "0.51.32",
+  "packageVersion": "0.51.34",
   "objects": {
     "@happyvertical/smrt-sales:AgreementExecutionCollection": {
       "name": "agreementexecutioncollection",

package/dist/referrals/collections/AttributionExceptionCollection.d.ts

@@ -1,3 +1,8 @@
+/**
+ * AttributionExceptionCollection — collection manager for
+ * {@link AttributionException}.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { AttributionException } from '../models/AttributionException.js';
 export declare class AttributionExceptionCollection extends SmrtCollection<AttributionException> {

package/dist/referrals/collections/AttributionPolicyCollection.d.ts

@@ -1,6 +1,16 @@
+/**
+ * AttributionPolicyCollection — collection manager for
+ * {@link AttributionPolicy}.
+ *
+ * Policies are versioned rows: amendments insert `(policyKey, maxVersion +
+ * 1)` drafts via {@link createAmendment}; existing versions are never
+ * rewritten (CommissionPlan pattern).
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { AttributionPolicy } from '../models/AttributionPolicy.js';
-import { AttributionConflictBehavior, AttributionCreditMode, AttributionPolicyStatus } from '../types.js';
+import type { AttributionConflictBehavior, AttributionCreditMode, AttributionPolicyStatus } from '../types.js';
 /**
  * Fields an amendment may change relative to the version it copies.
  * `policyKey` is fixed (it identifies the policy), `version` is computed,

package/dist/referrals/collections/ReferralAgreementCollection.d.ts

@@ -1,6 +1,16 @@
+/**
+ * ReferralAgreementCollection — collection manager for
+ * {@link ReferralAgreement}.
+ *
+ * Agreements are versioned rows: amendments insert
+ * `(referrerId, programId, maxVersion + 1)` drafts via
+ * {@link createAmendment}; existing versions are never rewritten.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { ReferralAgreement } from '../models/ReferralAgreement.js';
-import { ReferralAgreementApprovalMode } from '../types.js';
+import type { ReferralAgreementApprovalMode } from '../types.js';
 /**
  * Fields an amendment may change relative to the version it copies.
  * `referrerId`/`programId` are fixed (they identify the agreement),

package/dist/referrals/collections/ReferralClickOperationCollection.d.ts

@@ -1,3 +1,4 @@
+/** Database serialization primitive for referral-click replay keys. */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { ReferralClickOperation } from '../models/ReferralClickOperation.js';
 export interface ClaimReferralClickOperationInput {

package/dist/referrals/collections/ReferralCollection.d.ts

@@ -1,3 +1,7 @@
+/**
+ * ReferralCollection — collection manager for {@link Referral}.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Referral } from '../models/Referral.js';
 export declare class ReferralCollection extends SmrtCollection<Referral> {

package/dist/referrals/collections/ReferralLinkCollection.d.ts

@@ -1,7 +1,14 @@
+/**
+ * ReferralLinkCollection — collection manager for {@link ReferralLink}:
+ * crypto-random code minting with collision retry, code lookup, and click
+ * recording (link counter + immutable ReferralTouch evidence).
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
-import { DatabaseInterface } from '@happyvertical/sql';
+import type { DatabaseInterface } from '@happyvertical/sql';
 import { ReferralLink } from '../models/ReferralLink.js';
-import { ReferralTouch } from '../models/ReferralTouch.js';
+import type { ReferralTouch } from '../models/ReferralTouch.js';
 /** Length of generated share codes. */
 export declare const REFERRAL_CODE_LENGTH = 10;
 /** Alphabet generated codes draw from (lowercase alphanumeric). */

package/dist/referrals/collections/ReferralProgramCollection.d.ts

@@ -1,6 +1,10 @@
+/**
+ * ReferralProgramCollection — collection manager for {@link ReferralProgram}.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { ReferralProgram } from '../models/ReferralProgram.js';
-import { ReferralProgramStatus } from '../types.js';
+import type { ReferralProgramStatus } from '../types.js';
 export declare class ReferralProgramCollection extends SmrtCollection<ReferralProgram> {
     static readonly _itemClass: typeof ReferralProgram;
     /**

package/dist/referrals/collections/ReferralTermSnapshotCollection.d.ts

@@ -1,3 +1,11 @@
+/**
+ * ReferralTermSnapshotCollection — collection manager for
+ * {@link ReferralTermSnapshot}.
+ *
+ * Snapshots are immutable history: this collection only creates and reads.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { ReferralTermSnapshot } from '../models/ReferralTermSnapshot.js';
 export declare class ReferralTermSnapshotCollection extends SmrtCollection<ReferralTermSnapshot> {

package/dist/referrals/collections/ReferralTouchCollection.d.ts

@@ -1,3 +1,10 @@
+/**
+ * ReferralTouchCollection — collection manager for {@link ReferralTouch}.
+ *
+ * Touches are immutable evidence: this collection only creates and reads.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { ReferralTouch } from '../models/ReferralTouch.js';
 /** Input for {@link ReferralTouchCollection.findByTargetWindow}. */

package/dist/referrals/collections/ReferrerCollection.d.ts

@@ -1,6 +1,10 @@
+/**
+ * ReferrerCollection — collection manager for {@link Referrer}.
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Referrer } from '../models/Referrer.js';
-import { ReferrerStatus } from '../types.js';
+import type { ReferrerStatus } from '../types.js';
 export declare class ReferrerCollection extends SmrtCollection<Referrer> {
     static readonly _itemClass: typeof Referrer;
     /**

package/dist/referrals/models/AttributionException.d.ts

@@ -1,5 +1,24 @@
+/**
+ * AttributionException — the conflict-review queue and override audit trail.
+ *
+ * When attribution cannot conclude automatically (exact-timestamp ties,
+ * competing manual assignments, or a policy whose `conflictBehavior` is
+ * `review`), `AttributionService.resolve()` creates an OPEN exception
+ * carrying the candidate touches and creates NO referral rows. A human (or
+ * policy re-run) resolves it via `AttributionService.resolveException()`,
+ * which requires a `resolutionReason`, creates the awarded referral(s), and
+ * stamps the resolution audit fields here. `AttributionService.override()`
+ * writes an already-RESOLVED exception row as the audit record of a
+ * re-attribution.
+ *
+ * The generated surface is read-only (`list`/`get`): exceptions are minted
+ * and resolved exclusively by the attribution service so the audit fields
+ * stay trustworthy.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { AttributionExceptionCandidate, AttributionExceptionOptions, AttributionExceptionStatus } from '../types.js';
+import type { AttributionExceptionCandidate, AttributionExceptionOptions, AttributionExceptionStatus } from '../types.js';
 export declare class AttributionException extends SmrtObject {
     /** Tenant ID for multi-tenant isolation (nullable → global rows). */
     tenantId: string | null;

package/dist/referrals/models/AttributionPolicy.d.ts

@@ -1,5 +1,24 @@
+/**
+ * AttributionPolicy — versioned attribution terms.
+ *
+ * A policy is identified by its `(policyKey, version)` natural key. Versions
+ * are ROWS, not edits: amending a policy inserts a `version + 1` draft (see
+ * `AttributionPolicyCollection.createAmendment`) and the prior version is
+ * never rewritten. Once a row has been saved non-draft, its policy-defining
+ * identity (window, credit mode, conflict behavior, eligibility flags and
+ * lists, key/version, effectiveFrom) is frozen — re-saving with any of them
+ * changed throws (same WeakMap-serialize pattern as commerce `LicenseSale`
+ * and this package's `CommissionPlan`). Status transitions remain allowed on
+ * frozen rows.
+ *
+ * Generated write surface is deliberately narrow: `create` only (drafts) —
+ * 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 { AttributionConflictBehavior, AttributionCreditMode, AttributionPolicyOptions, AttributionPolicyStatus } from '../types.js';
+import { type AttributionConflictBehavior, type AttributionCreditMode, type AttributionPolicyOptions, type AttributionPolicyStatus } from '../types.js';
 /**
  * Validate a policy's terms. Throws a descriptive error on the first
  * violation. Called by {@link AttributionPolicy.activate} and by activating

package/dist/referrals/models/Referral.d.ts

@@ -1,5 +1,29 @@
+/**
+ * Referral — the introduction record.
+ *
+ * A Referral says "this referrer introduced this target under this program"
+ * — the target is a GENERIC `(targetKind, targetId)` pair (lead,
+ * opportunity, client, project, subscription, …) so the referrals module
+ * never depends on CRM or any downstream domain.
+ *
+ * Lifecycle (save-time guarded against the AUTHORITATIVE prior persisted
+ * status — commerce pattern):
+ *
+ * - `pending → attributed | under_review | disqualified | expired`
+ * - `under_review → attributed | disqualified`
+ * - `attributed → qualified | disqualified | expired`
+ * - `qualified → disqualified` (rare clawback path)
+ * - `disqualified` / `expired` are terminal.
+ *
+ * Transition methods ({@link markAttributed} / {@link markUnderReview} /
+ * {@link markQualified} / {@link disqualify} / {@link markExpired}) mutate
+ * and stamp timestamps but DO NOT save — the caller saves (one explicit
+ * persistence point per mutation, matching the sibling modules).
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { ReferralOptions, ReferralStatus } from '../types.js';
+import type { ReferralOptions, ReferralStatus } from '../types.js';
 export declare class Referral extends SmrtObject {
     /** Tenant ID for multi-tenant isolation (nullable → global referrals). */
     tenantId: string | null;

package/dist/referrals/models/ReferralAgreement.d.ts

@@ -1,5 +1,29 @@
+/**
+ * ReferralAgreement — versioned per-Referrer terms binding.
+ *
+ * An agreement binds one Referrer to one ReferralProgram under specific
+ * commission terms: which CommissionPlan key (optionally pinned to a
+ * version), the clearing window, and the approval mode. Natural key
+ * `(referrerId, programId, version)` — amendments insert `version + 1`
+ * drafts (see `ReferralAgreementCollection.createAmendment`); prior versions
+ * are never rewritten.
+ *
+ * Lifecycle: `draft → active | terminated`; `active → superseded |
+ * terminated`; `superseded` / `terminated` are terminal. Activation requires
+ * bound commercial terms and an immutable {@link executedAgreementId}.
+ *
+ * Immutability: once a row has been saved non-draft, its TERMS
+ * (`referrerId`, `programId`, `version`, `commissionPlanKey`,
+ * `commissionPlanVersion`, `clearingDays`, `approvalMode`, `effectiveFrom`)
+ * are frozen via the WeakMap-serialize guard (commerce `LicenseSale`
+ * pattern). Status transitions stay allowed and `effectiveTo` stays mutable
+ * so an operator can end-date an agreement. Signed artifacts and signer/audit
+ * evidence live only on immutable `ExecutedAgreement` records.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { ReferralAgreementApprovalMode, ReferralAgreementOptions, ReferralAgreementStatus } from '../types.js';
+import type { ReferralAgreementApprovalMode, ReferralAgreementOptions, ReferralAgreementStatus } from '../types.js';
 export declare class ReferralAgreement extends SmrtObject {
     /** Tenant ID for multi-tenant isolation (nullable → global agreements). */
     tenantId: string | null;

package/dist/referrals/models/ReferralClickOperation.d.ts

@@ -1,4 +1,5 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/** Private idempotency fence for atomic referral-click recording. */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 interface ReferralClickOperationOptions extends SmrtObjectOptions {
     tenantId?: string | null;
     keyHash?: string;

package/dist/referrals/models/ReferralLink.d.ts

@@ -1,5 +1,9 @@
+/**
+ * ReferralLink — shareable link/code per Referrer + Program.
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { ReferralLinkOptions, ReferralLinkStatus } from '../types.js';
+import type { ReferralLinkOptions, ReferralLinkStatus } from '../types.js';
 /**
  * Assert that a target URL is an absolute http/https URL. Exported for the
  * collection's create path; the model also enforces it at save time so no

package/dist/referrals/models/ReferralProgram.d.ts

@@ -1,5 +1,9 @@
+/**
+ * ReferralProgram — program-level defaults for referral intake.
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { ReferralProgramOptions, ReferralProgramStatus } from '../types.js';
+import type { ReferralProgramOptions, ReferralProgramStatus } from '../types.js';
 /**
  * A ReferralProgram anchors links, touches, referrals, agreements, and
  * exceptions, and carries the program-level DEFAULTS:

package/dist/referrals/models/ReferralTermSnapshot.d.ts

@@ -1,6 +1,26 @@
+/**
+ * ReferralTermSnapshot — the terms frozen at qualification.
+ *
+ * When a Referral qualifies, `ReferralQualificationService` copies
+ * EVERYTHING later earnings depend on into one immutable row: the resolved
+ * agreement/plan/policy version references plus the CALCULATION INPUTS
+ * themselves (`components`, `currency`, `clearingDays`, `approvalMode`).
+ * `ReferralCommissionService` calculates exclusively from this row — never
+ * from a live plan — so a plan amendment after qualification can NEVER
+ * change what an already-qualified referral earns. Reproducibility over
+ * convenience.
+ *
+ * FULLY immutable post-create: a save guard rejects ANY field change to a
+ * persisted row (and blind writes onto an existing id from a non-hydrated
+ * instance). Amended terms mean a NEW snapshot via
+ * `ReferralQualificationService.requalify()` — the old row stands as
+ * history, still referenced by any Commission it produced.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { CommissionPlanComponent } from '../../commissions/index.js';
-import { ReferralAgreementApprovalMode, ReferralTermSnapshotOptions } from '../types.js';
+import type { CommissionPlanComponent } from '../../commissions/index.js';
+import type { ReferralAgreementApprovalMode, ReferralTermSnapshotOptions } from '../types.js';
 export declare class ReferralTermSnapshot extends SmrtObject {
     /** Tenant ID for multi-tenant isolation (nullable → global rows). */
     tenantId: string | null;

package/dist/referrals/models/ReferralTouch.d.ts

@@ -1,5 +1,24 @@
+/**
+ * ReferralTouch — immutable attribution evidence.
+ *
+ * A touch records that a prospect interacted with a referral artifact: a
+ * link click, a code entry, a partner-submitted introduction, or an
+ * operator's manual assignment. Touches are the CANDIDATE SET attribution
+ * resolves over — `AttributionService.resolve()` gathers eligible touches
+ * within the policy window and credits per the policy's mode.
+ *
+ * Immutability contract (same as the commissions module's `EarningEvent`):
+ * touches are evidence. The generated surface exposes `create`/`list`/`get`
+ * only (no update, no delete), and application code must treat persisted
+ * rows as append-only — Referrals point at their winning touch via
+ * `primaryTouchId` and AttributionExceptions embed candidate touches, so
+ * rewriting a touch would orphan the audit trail. Corrections are modelled
+ * as NEW touches (e.g. a `manual_assignment`).
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { ReferralTouchKind, ReferralTouchOptions } from '../types.js';
+import type { ReferralTouchKind, ReferralTouchOptions } from '../types.js';
 export declare class ReferralTouch extends SmrtObject {
     /** Tenant ID for multi-tenant isolation (nullable → global touches). */
     tenantId: string | null;

package/dist/referrals/models/Referrer.d.ts

@@ -1,5 +1,9 @@
+/**
+ * Referrer — the referral role model.
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { ReferrerOptions, ReferrerStatus } from '../types.js';
+import type { ReferrerOptions, ReferrerStatus } from '../types.js';
 /**
  * Referrer is a ROLE model: it links an identity (smrt-profiles Profile) to
  * referral activity (ReferralLinks, ReferralTouches, and Referrals reference