@happyvertical/smrt-sales 0.51.32 → 0.51.33

package/dist/referrals/services/AttributionService.d.ts

@@ -1,13 +1,21 @@
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
+/**
+ * AttributionService — turns ReferralTouch evidence into attributed
+ * Referral rows (or AttributionExceptions when the policy cannot conclude),
+ * and owns the audited manual paths: assignments, exception resolution, and
+ * re-attribution overrides.
+ *
+ * @packageDocumentation
+ */
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
 import { AttributionExceptionCollection } from '../collections/AttributionExceptionCollection.js';
 import { AttributionPolicyCollection } from '../collections/AttributionPolicyCollection.js';
 import { ReferralCollection } from '../collections/ReferralCollection.js';
 import { ReferralProgramCollection } from '../collections/ReferralProgramCollection.js';
 import { ReferralTouchCollection } from '../collections/ReferralTouchCollection.js';
 import { ReferrerCollection } from '../collections/ReferrerCollection.js';
-import { AttributionException } from '../models/AttributionException.js';
-import { Referral } from '../models/Referral.js';
-import { ReferralTouch } from '../models/ReferralTouch.js';
+import type { AttributionException } from '../models/AttributionException.js';
+import type { Referral } from '../models/Referral.js';
+import type { ReferralTouch } from '../models/ReferralTouch.js';
 /**
  * Thrown by {@link AttributionService.override} when the target already has
  * a QUALIFIED referral: qualified credit is governed by its term snapshot

package/dist/referrals/services/ReferralAgreementExecutionService.d.ts

@@ -1,10 +1,11 @@
-import { SignatureDocument, SignatureSignerInput } from '@happyvertical/signatures';
-import { AgreementExecutionCollection } from '../../agreements/collections/AgreementExecutionCollection.js';
-import { ExecutedAgreementCollection } from '../../agreements/collections/ExecutedAgreementCollection.js';
-import { AgreementExecutionService } from '../../agreements/services/AgreementExecutionService.js';
-import { AgreementExecutionResult } from '../../agreements/types.js';
+/** ReferralAgreement binding for the provider-neutral execution service. */
+import type { SignatureDocument, SignatureSignerInput } from '@happyvertical/signatures';
+import type { AgreementExecutionCollection } from '../../agreements/collections/AgreementExecutionCollection.js';
+import type { ExecutedAgreementCollection } from '../../agreements/collections/ExecutedAgreementCollection.js';
+import type { AgreementExecutionService } from '../../agreements/services/AgreementExecutionService.js';
+import type { AgreementExecutionResult } from '../../agreements/types.js';
 import { ReferralAgreementCollection } from '../collections/ReferralAgreementCollection.js';
-import { ReferralAgreement } from '../models/ReferralAgreement.js';
+import type { ReferralAgreement } from '../models/ReferralAgreement.js';
 export declare const REFERRAL_AGREEMENT_SOURCE_KIND = "referral_agreement";
 export interface ReferralAgreementExecutionServiceDeps {
     agreements: ReferralAgreementCollection;

package/dist/referrals/services/ReferralCommissionService.d.ts

@@ -1,5 +1,18 @@
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
-import { Commission, CommissionCalculationService, CommissionCollection, CommissionComponentSkip, EarningEvent } from '../../commissions/index.js';
+/**
+ * ReferralCommissionService — the bridge from qualified Referrals to the
+ * commissions financial core (#1932).
+ *
+ * Given an EarningEvent (e.g. an invoice payment), the service finds the
+ * qualified referrals it should pay, loads each one's FROZEN
+ * ReferralTermSnapshot, resolves the referrer's Earner, and hands the
+ * snapshot's components to `CommissionCalculationService.calculateForEvent`.
+ * Calculation NEVER touches a live plan — reproducibility comes from the
+ * snapshot, idempotency from the calculation service's dedupe keys.
+ *
+ * @packageDocumentation
+ */
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { type Commission, CommissionCalculationService, CommissionCollection, type CommissionComponentSkip, type EarningEvent } from '../../commissions/index.js';
 import { ReferralCollection } from '../collections/ReferralCollection.js';
 import { ReferralTermSnapshotCollection } from '../collections/ReferralTermSnapshotCollection.js';
 import { ReferrerCollection } from '../collections/ReferrerCollection.js';

package/dist/referrals/services/ReferralQualificationService.d.ts

@@ -1,12 +1,27 @@
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
+/**
+ * ReferralQualificationService — turns an attributed Referral into a
+ * QUALIFIED one by freezing the governing terms into an immutable
+ * ReferralTermSnapshot.
+ *
+ * Qualification is the moment terms bind: the active ReferralAgreement is
+ * resolved, the CommissionPlan version is pinned (the agreement's explicit
+ * pin, or the latest active version when unpinned), and the plan's
+ * components are COPIED into the snapshot. Everything the commission bridge
+ * later needs comes from that frozen row — plan amendments after
+ * qualification change nothing unless {@link requalify} is explicitly
+ * invoked.
+ *
+ * @packageDocumentation
+ */
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
 import { CommissionPlanCollection } from '../../commissions/index.js';
 import { AttributionPolicyCollection } from '../collections/AttributionPolicyCollection.js';
 import { ReferralAgreementCollection } from '../collections/ReferralAgreementCollection.js';
 import { ReferralCollection } from '../collections/ReferralCollection.js';
 import { ReferralTermSnapshotCollection } from '../collections/ReferralTermSnapshotCollection.js';
 import { ReferrerCollection } from '../collections/ReferrerCollection.js';
-import { Referral } from '../models/Referral.js';
-import { ReferralTermSnapshot } from '../models/ReferralTermSnapshot.js';
+import type { Referral } from '../models/Referral.js';
+import type { ReferralTermSnapshot } from '../models/ReferralTermSnapshot.js';
 /** Collaborators for {@link ReferralQualificationService}. */
 export interface ReferralQualificationServiceDeps {
     referrals: ReferralCollection;

package/dist/referrals/types.d.ts

@@ -1,4 +1,21 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * Shared types, status unions, and contracts for the referrals module.
+ *
+ * Statuses are string-literal unions derived from `as const` arrays (no TS
+ * enums) so the runtime lists (validation, UI pickers) and the compile-time
+ * unions stay in lockstep. All monetary fields across the module are integer
+ * cents with a `*Cents` suffix; rates/fractions are decimals in `0`–`1`.
+ *
+ * The referrals module depends on the `commissions` module (same package)
+ * for the neutral financial core — Earners, CommissionPlans, EarningEvents,
+ * Commissions — and NEVER on `crm`. Qualifying targets are generic
+ * `(targetKind, targetId)` string pairs so a referral can point at a lead,
+ * opportunity, client, project, subscription, or any application-defined
+ * record without this module knowing its semantics.
+ *
+ * @packageDocumentation
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
 /** Lifecycle of a {@link ReferrerOptions | Referrer} role. */
 export declare const REFERRER_STATUSES: readonly ["pending", "active", "suspended"];
 export type ReferrerStatus = (typeof REFERRER_STATUSES)[number];

package/dist/referrals.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Subpath entry: `@happyvertical/smrt-sales/referrals`.
+ *
+ * Referrers, Referral Programs, links/codes, attribution evidence, versioned
+ * attribution policies, referral agreements, and qualification term
+ * snapshots. Referral lifecycle stays independent of the CRM state machine
+ * while supporting generic qualifying-target links.
+ */
+import './__smrt-register__.js';
 export * from './referrals/index.js';
 //# sourceMappingURL=referrals.d.ts.map

package/dist/referrals.js

@@ -1,3 +1,3 @@
-import "./chunks/__smrt-register__-D4oQpwQY.js";
+import "./chunks/__smrt-register__-CSbufn1D.js";
 import { A as ReferralClickOperation, B as ATTRIBUTION_RESOLUTION_MODES, C as ReferralTouchCollection, D as ReferralCollection, E as assertHttpTargetUrl, F as validateAttributionPolicyTerms, G as REFERRAL_STATUSES, H as REFERRAL_AGREEMENT_STATUSES, I as ATTRIBUTION_CONFLICT_BEHAVIORS, J as AttributionExceptionCollection, K as REFERRAL_TOUCH_KINDS, L as ATTRIBUTION_CREDIT_MODES, M as ReferralAgreement, N as AttributionPolicyCollection, O as Referral, P as AttributionPolicy, R as ATTRIBUTION_EXCEPTION_STATUSES, S as generateReferralCode, T as ReferralLink, U as REFERRAL_LINK_STATUSES, V as REFERRAL_AGREEMENT_APPROVAL_MODES, W as REFERRAL_PROGRAM_STATUSES, Y as AttributionException, _ as REFERRAL_CODE_ALPHABET, a as ReferralAgreementExecutionService, b as ReferralClickValidationError, c as ReferrerCollection, d as ReferralTermSnapshot, f as ReferralProgramCollection, g as MAX_REFERRAL_CLICK_IDEMPOTENCY_KEY_BYTES, h as MAX_CODE_GENERATION_ATTEMPTS, i as REFERRAL_AGREEMENT_SOURCE_KIND, j as ReferralAgreementCollection, k as ReferralClickOperationCollection, l as Referrer, m as DEFAULT_REFERRAL_CLICK_EVIDENCE_MAX_BYTES, n as REFERRAL_TERMS_SNAPSHOT_KIND, o as AttributionService, p as ReferralProgram, q as REFERRER_STATUSES, r as ReferralCommissionService, s as QualifiedReferralOverrideError, t as ReferralQualificationService, u as ReferralTermSnapshotCollection, v as REFERRAL_CODE_LENGTH, w as ReferralTouch, x as ReferralLinkCollection, y as ReferralClickReplayConflictError, z as ATTRIBUTION_POLICY_STATUSES } from "./chunks/referrals-BsGHbnpW.js";
 export { ATTRIBUTION_CONFLICT_BEHAVIORS, ATTRIBUTION_CREDIT_MODES, ATTRIBUTION_EXCEPTION_STATUSES, ATTRIBUTION_POLICY_STATUSES, ATTRIBUTION_RESOLUTION_MODES, AttributionException, AttributionExceptionCollection, AttributionPolicy, AttributionPolicyCollection, AttributionService, DEFAULT_REFERRAL_CLICK_EVIDENCE_MAX_BYTES, MAX_CODE_GENERATION_ATTEMPTS, MAX_REFERRAL_CLICK_IDEMPOTENCY_KEY_BYTES, QualifiedReferralOverrideError, REFERRAL_AGREEMENT_APPROVAL_MODES, REFERRAL_AGREEMENT_SOURCE_KIND, REFERRAL_AGREEMENT_STATUSES, REFERRAL_CODE_ALPHABET, REFERRAL_CODE_LENGTH, REFERRAL_LINK_STATUSES, REFERRAL_PROGRAM_STATUSES, REFERRAL_STATUSES, REFERRAL_TERMS_SNAPSHOT_KIND, REFERRAL_TOUCH_KINDS, REFERRER_STATUSES, Referral, ReferralAgreement, ReferralAgreementCollection, ReferralAgreementExecutionService, ReferralClickOperation, ReferralClickOperationCollection, ReferralClickReplayConflictError, ReferralClickValidationError, ReferralCollection, ReferralCommissionService, ReferralLink, ReferralLinkCollection, ReferralProgram, ReferralProgramCollection, ReferralQualificationService, ReferralTermSnapshot, ReferralTermSnapshotCollection, ReferralTouch, ReferralTouchCollection, Referrer, ReferrerCollection, assertHttpTargetUrl, generateReferralCode, validateAttributionPolicyTerms };

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-sales",
-  "packageVersion": "0.51.32",
+  "packageVersion": "0.51.33",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "38d72e5494cdc577041f9c852bb27759f54a954f5dd64d1c6cbd594486f64b13",
-    "packageJson": "c65b4bece2974aae1947d359f30b9c7b2259792273a95905bdd4082c06931f8c",
+    "manifest": "9f899fd0aad94ae477c4c69b4774e15b94f41ed40b85b371d656d8ee565cbf46",
+    "packageJson": "7216b3803b898f046ca63ba05530c3a28c1b1338fdcd1f3b8e0cbeee6d644536",
     "agents": "70ca45be28b73fa742d3ebebe4c7cc25b524ba3684757d7066056f707efc3b22",
     "moduleDoc:agents/agreements.md": "eb6ff147a0f60ee627d3337e8e9394d06fda955b4a4fff228537a9bd2803f886",
     "moduleDoc:agents/commissions.md": "e047024aafe5edcf072c1a6b7ea253c24cb15f2fa1beb2edd13651e735921f73",
@@ -39,7 +39,7 @@
     "@types/node": "24.13.6",
     "svelte": "^5.57.1",
     "svelte-check": "^4.7.6",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
   },

package/dist/test-fixtures.d.ts

@@ -0,0 +1,6 @@
+import type { DatabaseInterface } from '@happyvertical/sql';
+/** Create the real execution/evidence parents referenced by agreement fixtures. */
+export declare function seedAgreementEvidence(db: DatabaseInterface, executionId: string, executedAgreementId: string): Promise<void>;
+export declare function seedCommissionPayout(db: DatabaseInterface, earnerId: string, payoutId: string): Promise<void>;
+export declare function seedEarningEvent(db: DatabaseInterface, eventId: string): Promise<void>;
+//# sourceMappingURL=test-fixtures.d.ts.map

package/dist/test-fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-fixtures.d.ts","sourceRoot":"","sources":["../src/test-fixtures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAM5D,mFAAmF;AACnF,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,iBAAiB,EACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/dist/test-setup.d.ts

@@ -0,0 +1,2 @@
+import './index.js';
+//# sourceMappingURL=test-setup.d.ts.map

package/dist/test-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.d.ts","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":"AAEA,OAAO,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-sales",
-  "version": "0.51.32",
+  "version": "0.51.33",
   "smrtJsdoc": "strict",
   "description": "Modular sales for the SMRT framework: agreement execution, CRM, referral intake, neutral commissions, and reusable Svelte surfaces",
   "type": "module",
@@ -43,23 +43,23 @@
   },
   "dependencies": {
     "@happyvertical/signatures": "^0.94.1",
-    "@happyvertical/smrt-assets": "0.51.32",
-    "@happyvertical/smrt-core": "0.51.32",
-    "@happyvertical/smrt-tenancy": "0.51.32",
-    "@happyvertical/smrt-ui": "0.51.32",
+    "@happyvertical/smrt-assets": "0.51.33",
+    "@happyvertical/smrt-core": "0.51.33",
+    "@happyvertical/smrt-tenancy": "0.51.33",
+    "@happyvertical/smrt-ui": "0.51.33",
     "@happyvertical/sql": "^0.94.1"
   },
   "peerDependencies": {
     "svelte": "^5.57.1"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.51.32",
+    "@happyvertical/smrt-vitest": "0.51.33",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@types/node": "24.13.6",
     "svelte": "^5.57.1",
     "svelte-check": "^4.7.6",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
   },