@happyvertical/smrt-sales 0.39.2

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

@@ -0,0 +1 @@
+{"version":3,"file":"AttributionPolicy.d.ts","sourceRoot":"","sources":["../../../src/referrals/models/AttributionPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAS,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EAGL,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC7B,MAAM,aAAa,CAAC;AAkCrB;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,iBAAiB,GACxB,IAAI,CAsCN;AAED,qBAca,iBAAkB,SAAQ,UAAU;IAC/C,yEAAyE;IAEzE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,oEAAoE;IAEpE,SAAS,EAAE,MAAM,CAAM;IAEvB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAK;IAEpB;;;;OAIG;IACH,MAAM,EAAE,uBAAuB,CAAW;IAE1C,wEAAwE;IACxE,aAAa,EAAE,IAAI,GAAG,IAAI,CAAQ;IAElC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAM;IAExB,0CAA0C;IAC1C,UAAU,EAAE,qBAAqB,CAAiB;IAElD,wEAAwE;IACxE,gBAAgB,EAAE,2BAA2B,CAAU;IAEvD;;;;OAIG;IACH,iBAAiB,EAAE,OAAO,CAAS;IAEnC;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,CAAS;IAEtC;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,CAAQ;IAEhC,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAQ;IAEjC,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAQ;IAE/B,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,wBAA6B;IAyBlD;;;;;OAKG;IACY,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAc1C,OAAO,IAAI,OAAO;IAIlB,QAAQ,IAAI,OAAO;IAMnB,0EAA0E;IAC1E,mBAAmB,IAAI,MAAM,EAAE;IAI/B,oDAAoD;IACpD,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI;IAI7C,2EAA2E;IAC3E,oBAAoB,IAAI,MAAM,EAAE;IAIhC,qDAAqD;IACrD,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI;IAI/C,yEAAyE;IACzE,kBAAkB,IAAI,MAAM,EAAE;IAI9B,mDAAmD;IACnD,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAI3C,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;;;;;;;;;;OAUG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBpC;;;;;;;OAOG;YACW,wBAAwB;IAiCtC;;;;OAIG;YACW,kBAAkB;IAgBhC,OAAO,CAAC,sBAAsB;IAe9B,OAAO,CAAC,6BAA6B;IAerC,OAAO,CAAC,uBAAuB;IAqB/B,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAY/B,OAAO,CAAC,MAAM,CAAC,UAAU;CAS1B;AAED,eAAe,iBAAiB,CAAC"}

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

@@ -0,0 +1,112 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { ReferralOptions, ReferralStatus } from '../types.js';
+export declare class Referral extends SmrtObject {
+    /** Tenant ID for multi-tenant isolation (nullable → global referrals). */
+    tenantId: string | null;
+    /** The Referrer credited with the introduction. Required. */
+    referrerId: string;
+    /** The ReferralProgram the referral belongs to. Required. */
+    programId: string;
+    /** AttributionPolicy key resolved at attribution ('' until attributed). */
+    policyKey: string;
+    /** AttributionPolicy version resolved at attribution (0 until attributed). */
+    policyVersion: number;
+    /**
+     * Lifecycle status — see the module transition map. Mutate via the
+     * transition methods; the save-time guard rejects illegal edges.
+     */
+    status: ReferralStatus;
+    /**
+     * Generic qualifying target: what the introduction became/points at —
+     * `('lead', <id>)`, `('opportunity', <id>)`, `('client', <id>)`,
+     * `('subscription', <id>)`, … This module attaches no semantics to it.
+     */
+    targetKind: string;
+    /** Identifier within the {@link targetKind} namespace. */
+    targetId: string;
+    /**
+     * Credit share (0–1) this referral carries. `1.0` for sole attribution;
+     * split attribution creates sibling Referrals whose fractions sum to 1.0
+     * sharing one {@link splitGroupId}. Flows into Commission
+     * `shareFraction` at earning time.
+     */
+    creditFraction: number;
+    /** Groups the sibling referrals of one split. Empty for unsplit rows. */
+    splitGroupId: string;
+    /** The winning ReferralTouch behind the attribution ('' for touchless awards). */
+    primaryTouchId: string;
+    /** When the referral was attributed. */
+    attributedAt: Date | null;
+    /** When the referral was qualified. */
+    qualifiedAt: Date | null;
+    /**
+     * When an attributed-but-unqualified referral lapses. Stamped at
+     * attribution (`attributedAt + policy.windowDays`); enforced by
+     * `ReferralCollection.sweepExpired()`.
+     */
+    expiresAt: Date | null;
+    /**
+     * The ReferralTermSnapshot frozen at qualification ('' until qualified).
+     * Requalification repoints this at a NEW snapshot; old snapshots remain
+     * as history.
+     *
+     * Deliberately a PLAIN string reference (not `@foreignKey`): the
+     * snapshot's own `referralId` FK carries the relationship, and declaring
+     * both directions would put a cycle in the model graph (breaking the
+     * registry's topological initialization order). Services fetch the
+     * snapshot by id explicitly.
+     */
+    snapshotId: string;
+    /**
+     * Free-form JSON object stored as a string. Use
+     * {@link getMetadata}/{@link setMetadata} instead of parsing manually.
+     */
+    metadata: string;
+    constructor(options?: ReferralOptions);
+    /**
+     * Re-coerce date fields after the framework reapplies raw option values
+     * and record the loaded status for the save-time transition guard.
+     */
+    initialize(): Promise<this>;
+    isAttributed(): boolean;
+    isQualified(): boolean;
+    /** Whether the referral sits in a terminal status. */
+    isTerminal(): boolean;
+    /** Parse {@link metadata}; returns `{}` on malformed content. */
+    getMetadata(): Record<string, unknown>;
+    /** Serialize and store {@link metadata}. */
+    setMetadata(data: Record<string, unknown>): void;
+    /** Transition `pending → under_review` (conflict parked for humans). */
+    markUnderReview(): void;
+    /**
+     * Transition `pending | under_review → attributed` and stamp
+     * {@link attributedAt}.
+     */
+    markAttributed(at?: Date): void;
+    /** Transition `attributed → qualified` and stamp {@link qualifiedAt}. */
+    markQualified(at?: Date): void;
+    /**
+     * Transition to `disqualified` (terminal). Legal from every non-terminal
+     * status — including `qualified` (the rare clawback path).
+     */
+    disqualify(): void;
+    /** Transition `pending | attributed → expired` (terminal). */
+    markExpired(): void;
+    /**
+     * Validate the status transition before persisting, then save. A forged
+     * `status` (e.g. un-expiring a referral or skipping straight to
+     * qualified) is rejected regardless of how the instance was constructed.
+     */
+    save(): Promise<this>;
+    /**
+     * Resolve the AUTHORITATIVE prior status from the database; fall back to
+     * the loaded-status WeakMap only when the DB is unavailable (commerce
+     * pattern — an upsert via `create({ id, _skipLoad: true })` can't
+     * sidestep the guard).
+     */
+    private resolvePriorStatus;
+    private assertStatusTransition;
+    private static coerceDate;
+}
+export default Referral;
+//# sourceMappingURL=Referral.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Referral.d.ts","sourceRoot":"","sources":["../../../src/referrals/models/Referral.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAExE,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAuBnE,qBAQa,QAAS,SAAQ,UAAU;IACtC,0EAA0E;IAE1E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,6DAA6D;IAE7D,UAAU,EAAE,MAAM,CAAM;IAExB,6DAA6D;IAE7D,SAAS,EAAE,MAAM,CAAM;IAEvB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAM;IAEvB,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAK;IAE1B;;;OAGG;IACH,MAAM,EAAE,cAAc,CAAa;IAEnC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAM;IAExB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAM;IAEtB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAO;IAE7B,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAM;IAE1B,kFAAkF;IAElF,cAAc,EAAE,MAAM,CAAM;IAE5B,wCAAwC;IACxC,YAAY,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEjC,uCAAuC;IACvC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEhC;;;;OAIG;IACH,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE9B;;;;;;;;;;OAUG;IACH,UAAU,EAAE,MAAM,CAAM;IAExB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,eAAoB;IA2BzC;;;OAGG;IACY,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAa1C,YAAY,IAAI,OAAO;IAIvB,WAAW,IAAI,OAAO;IAItB,sDAAsD;IACtD,UAAU,IAAI,OAAO;IAMrB,iEAAiE;IACjE,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYtC,4CAA4C;IAC5C,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMhD,wEAAwE;IACxE,eAAe,IAAI,IAAI;IASvB;;;OAGG;IACH,cAAc,CAAC,EAAE,GAAE,IAAiB,GAAG,IAAI;IAU3C,yEAAyE;IACzE,aAAa,CAAC,EAAE,GAAE,IAAiB,GAAG,IAAI;IAU1C;;;OAGG;IACH,UAAU,IAAI,IAAI;IASlB,8DAA8D;IAC9D,WAAW,IAAI,IAAI;IAWnB;;;;OAIG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQpC;;;;;OAKG;YACW,kBAAkB;IAchC,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,MAAM,CAAC,UAAU;CAS1B;AAED,eAAe,QAAQ,CAAC"}

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

@@ -0,0 +1,125 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { ReferralAgreementApprovalMode, ReferralAgreementOptions, ReferralAgreementStatus } from '../types.js';
+export declare class ReferralAgreement extends SmrtObject {
+    /** Tenant ID for multi-tenant isolation (nullable → global agreements). */
+    tenantId: string | null;
+    /** The Referrer bound by this agreement. Required. */
+    referrerId: string;
+    /** The ReferralProgram the agreement applies to. Required. */
+    programId: string;
+    /** Monotonic version within `(referrerId, programId)`. */
+    version: number;
+    /**
+     * Lifecycle status — see the module transition map. Mutate via
+     * {@link activate} / {@link supersede} / {@link terminate}.
+     */
+    status: ReferralAgreementStatus;
+    /** Start of the effective window (`null` = effective immediately). */
+    effectiveFrom: Date | null;
+    /**
+     * End of the effective window (`null` = open-ended). Deliberately NOT
+     * frozen: end-dating an active agreement is a legitimate operation.
+     */
+    effectiveTo: Date | null;
+    /**
+     * The commissions-module CommissionPlan key these terms bind. Required to
+     * activate.
+     */
+    commissionPlanKey: string;
+    /**
+     * Pinned plan version. `0` (default) means "resolve the latest ACTIVE
+     * version at qualification time and pin it in the ReferralTermSnapshot";
+     * `> 0` pins a specific version now.
+     */
+    commissionPlanVersion: number;
+    /**
+     * Clearing window in days applied to commissions earned under these
+     * terms (refund/chargeback holdback). Frozen into every snapshot.
+     */
+    clearingDays: number;
+    /** How earned commissions are approved downstream. */
+    approvalMode: ReferralAgreementApprovalMode;
+    /**
+     * Optional cross-package string reference to a smrt-commerce Contract
+     * representing the executed legal agreement.
+     */
+    contractRef: string;
+    /** URL of the executed agreement artifact (e-signature PDF, …). */
+    executedArtifactUrl: string;
+    /** Content hash of the executed artifact for tamper evidence. */
+    executedArtifactHash: string;
+    /**
+     * Acceptance evidence as a JSON object string (click-through record, IP,
+     * timestamp, signer, …). Use
+     * {@link getAcceptanceEvidence}/{@link setAcceptanceEvidence}.
+     */
+    acceptanceEvidence: string;
+    /**
+     * Free-form JSON object stored as a string. Use
+     * {@link getMetadata}/{@link setMetadata} instead of parsing manually.
+     */
+    metadata: string;
+    constructor(options?: ReferralAgreementOptions);
+    /**
+     * Re-coerce date fields after the framework reapplies raw option values,
+     * record the loaded status for the transition guard, and capture the
+     * frozen terms snapshot when the row arrived already non-draft
+     * (superseded / terminated history can't be rewritten either).
+     */
+    initialize(): Promise<this>;
+    isDraft(): boolean;
+    isActive(): boolean;
+    /**
+     * Whether the effective window contains `at` (`effectiveFrom` null =
+     * always started; `effectiveTo` null = open-ended). Status is NOT part of
+     * this check — combine with {@link isActive}.
+     */
+    isEffectiveAt(at: Date): boolean;
+    /** Parse {@link acceptanceEvidence}; returns `{}` on malformed content. */
+    getAcceptanceEvidence(): Record<string, unknown>;
+    /** Serialize and store {@link acceptanceEvidence}. */
+    setAcceptanceEvidence(evidence: Record<string, unknown>): void;
+    /** Parse {@link metadata}; returns `{}` on malformed content. */
+    getMetadata(): Record<string, unknown>;
+    /** Serialize and store {@link metadata}. */
+    setMetadata(data: Record<string, unknown>): void;
+    /**
+     * Transition `draft → active`. Requires a non-empty
+     * {@link commissionPlanKey} — an agreement without bound terms cannot
+     * govern qualification.
+     */
+    activate(): void;
+    /** Transition `active → superseded` (a newer version took over). */
+    supersede(): void;
+    /** Transition `draft | active → terminated` (terminal). */
+    terminate(): void;
+    /**
+     * Save with two guards (CommissionPlan pattern):
+     *
+     * 1. **Status transition** — the about-to-be-written status must be a
+     *    legal edge from the authoritative prior persisted status.
+     * 2. **Frozen terms** — once the row has been saved non-draft, the terms
+     *    fields must match the captured snapshot. Amend by inserting a new
+     *    version instead.
+     *
+     * Activating saves also re-require {@link commissionPlanKey}.
+     */
+    save(): Promise<this>;
+    /**
+     * Refuse a save whose `(referrerId, programId, version)` natural key
+     * already belongs to a DIFFERENT row — the frozen-terms guard is
+     * instance-local, so a fresh instance would otherwise upsert over the
+     * persisted agreement (replacing legally frozen referral terms without
+     * an amendment, and rotating the row id). Edit drafts by hydrating
+     * them; change terms with
+     * `ReferralAgreementCollection.createAmendment()`.
+     */
+    private assertNaturalKeyNotTaken;
+    private resolvePriorStatus;
+    private assertStatusTransition;
+    private assertFrozenTermsUnchanged;
+    private serializeFrozenTerms;
+    private static coerceDate;
+}
+export default ReferralAgreement;
+//# sourceMappingURL=ReferralAgreement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralAgreement.d.ts","sourceRoot":"","sources":["../../../src/referrals/models/ReferralAgreement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAGL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,6BAA6B,EAC7B,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,aAAa,CAAC;AA0BrB,qBAWa,iBAAkB,SAAQ,UAAU;IAC/C,2EAA2E;IAE3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,sDAAsD;IAEtD,UAAU,EAAE,MAAM,CAAM;IAExB,8DAA8D;IAE9D,SAAS,EAAE,MAAM,CAAM;IAEvB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAK;IAEpB;;;OAGG;IACH,MAAM,EAAE,uBAAuB,CAAW;IAE1C,sEAAsE;IACtE,aAAa,EAAE,IAAI,GAAG,IAAI,CAAQ;IAElC;;;OAGG;IACH,WAAW,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEhC;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAM;IAE/B;;;;OAIG;IACH,qBAAqB,EAAE,MAAM,CAAK;IAElC;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAK;IAEzB,sDAAsD;IACtD,YAAY,EAAE,6BAA6B,CAAY;IAEvD;;;OAGG;IAEH,WAAW,EAAE,MAAM,CAAM;IAEzB,mEAAmE;IACnE,mBAAmB,EAAE,MAAM,CAAM;IAEjC,iEAAiE;IACjE,oBAAoB,EAAE,MAAM,CAAM;IAElC;;;;OAIG;IACH,kBAAkB,EAAE,MAAM,CAAQ;IAElC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,wBAA6B;IA8BlD;;;;;OAKG;IACY,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAe1C,OAAO,IAAI,OAAO;IAIlB,QAAQ,IAAI,OAAO;IAInB;;;;OAIG;IACH,aAAa,CAAC,EAAE,EAAE,IAAI,GAAG,OAAO;IAYhC,2EAA2E;IAC3E,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYhD,sDAAsD;IACtD,qBAAqB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI9D,iEAAiE;IACjE,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYtC,4CAA4C;IAC5C,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMhD;;;;OAIG;IACH,QAAQ,IAAI,IAAI;IAchB,oEAAoE;IACpE,SAAS,IAAI,IAAI;IASjB,2DAA2D;IAC3D,SAAS,IAAI,IAAI;IAWjB;;;;;;;;;;OAUG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBpC;;;;;;;;OAQG;YACW,wBAAwB;YA8BxB,kBAAkB;IAgBhC,OAAO,CAAC,sBAAsB;IAe9B,OAAO,CAAC,0BAA0B;IAclC,OAAO,CAAC,oBAAoB;IAgB5B,OAAO,CAAC,MAAM,CAAC,UAAU;CAS1B;AAED,eAAe,iBAAiB,CAAC"}

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

@@ -0,0 +1,71 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { 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
+ * write path can persist a malformed target.
+ */
+export declare function assertHttpTargetUrl(targetUrl: string): void;
+/**
+ * A ReferralLink is the shareable artifact a Referrer distributes: a
+ * globally unique `code` (natural key `['code']` — codes resolve without
+ * knowing the tenant/program) plus an optional destination `targetUrl`.
+ *
+ * Codes are minted by `ReferralLinkCollection.createWithUniqueCode()` —
+ * crypto-random, 10 lowercase-alphanumeric characters, collision-checked
+ * with a capped retry loop. Click traffic lands through
+ * `ReferralLinkCollection.recordClick()`, which increments {@link clickCount}
+ * and writes an immutable `ReferralTouch` evidence row; disabled links
+ * refuse clicks.
+ */
+export declare class ReferralLink extends SmrtObject {
+    /** Tenant ID for multi-tenant isolation (nullable → global links). */
+    tenantId: string | null;
+    /** The Referrer this link credits. Required. */
+    referrerId: string;
+    /** The ReferralProgram this link belongs to. Required. */
+    programId: string;
+    /**
+     * Globally unique share code (10 lowercase-alphanumeric characters when
+     * minted by `createWithUniqueCode`). Natural key.
+     */
+    code: string;
+    /**
+     * Optional destination URL the shared link forwards to. Must be an
+     * absolute http/https URL when non-empty (validated at save time).
+     */
+    targetUrl: string;
+    /** Human-readable label for the referrer's own bookkeeping. */
+    label: string;
+    /** `active` (default) accepts clicks; `disabled` refuses them. */
+    status: ReferralLinkStatus;
+    /** Number of recorded clicks (incremented by `recordClick`). */
+    clickCount: number;
+    /**
+     * Free-form JSON object stored as a string. Use
+     * {@link getMetadata}/{@link setMetadata} instead of parsing manually.
+     */
+    metadata: string;
+    constructor(options?: ReferralLinkOptions);
+    /** Whether the link currently accepts clicks. */
+    isActive(): boolean;
+    /** Parse the metadata JSON string; returns `{}` on malformed content. */
+    getMetadata(): Record<string, unknown>;
+    /** Serialize and store the metadata object. */
+    setMetadata(metadata: Record<string, unknown>): void;
+    /**
+     * Save with two guards:
+     *
+     * - a non-empty {@link targetUrl} must be an absolute http/https URL
+     *   regardless of which write path set it;
+     * - the {@link code} must not belong to a DIFFERENT persisted link. Codes
+     *   are the upsert natural key and they are public — without this check a
+     *   generated-surface `create` carrying an existing code would silently
+     *   UPSERT over that link (rewriting its referrer/program/target: a
+     *   referral-code hijack). Mint codes through
+     *   `ReferralLinkCollection.createWithUniqueCode()`.
+     */
+    save(): Promise<this>;
+}
+export default ReferralLink;
+//# sourceMappingURL=ReferralLink.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralLink.d.ts","sourceRoot":"","sources":["../../../src/referrals/models/ReferralLink.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAqB,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAE/E,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE3E;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAc3D;AAED;;;;;;;;;;;GAWG;AACH,qBASa,YAAa,SAAQ,UAAU;IAC1C,sEAAsE;IAEtE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,gDAAgD;IAEhD,UAAU,EAAE,MAAM,CAAM;IAExB,0DAA0D;IAE1D,SAAS,EAAE,MAAM,CAAM;IAEvB;;;OAGG;IAEH,IAAI,EAAE,MAAM,CAAM;IAElB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAM;IAEvB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAM;IAEnB,kEAAkE;IAClE,MAAM,EAAE,kBAAkB,CAAY;IAEtC,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAK;IAEvB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,mBAAwB;IAa7C,iDAAiD;IACjD,QAAQ,IAAI,OAAO;IAInB,yEAAyE;IACzE,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYtC,+CAA+C;IAC/C,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIpD;;;;;;;;;;;OAWG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA2BrC;AAED,eAAe,YAAY,CAAC"}

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

@@ -0,0 +1,57 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { ReferralProgramOptions, ReferralProgramStatus } from '../types.js';
+/**
+ * A ReferralProgram anchors links, touches, referrals, agreements, and
+ * exceptions, and carries the program-level DEFAULTS:
+ *
+ * - `defaultAttributionPolicyKey` — which versioned AttributionPolicy
+ *   `AttributionService.resolve()` loads when the caller doesn't override.
+ * - `defaultCommissionPlanKey` — the suggested commissions plan for new
+ *   ReferralAgreements (the agreement's own `commissionPlanKey` is what
+ *   actually binds terms).
+ *
+ * Both defaults are KEYS, not pinned versions: the active version is
+ * resolved at attribution/qualification time and pinned on the Referral /
+ * ReferralTermSnapshot, so program rows stay stable across policy and plan
+ * amendments.
+ *
+ * Natural key `(tenant_id, key)` — each tenant names its programs once.
+ */
+export declare class ReferralProgram extends SmrtObject {
+    /** Tenant ID for multi-tenant isolation (nullable → global programs). */
+    tenantId: string | null;
+    /** Stable program key within the tenant (natural-key component). */
+    key: string;
+    /** Human-readable program name. */
+    name: string;
+    /**
+     * Program lifecycle: `draft` (default) → `active` → `paused` /
+     * `archived`. Applications gate intake on `active`; this module records
+     * the status without enforcing transition edges.
+     */
+    status: ReferralProgramStatus;
+    /**
+     * Default commissions-plan key suggested to new ReferralAgreements.
+     * Empty means the program has no default — agreements must name a plan.
+     */
+    defaultCommissionPlanKey: string;
+    /**
+     * Default AttributionPolicy key `AttributionService.resolve()` uses when
+     * the caller passes no `policyKey` override.
+     */
+    defaultAttributionPolicyKey: string;
+    /**
+     * Free-form JSON object stored as a string. Use
+     * {@link getMetadata}/{@link setMetadata} instead of parsing manually.
+     */
+    metadata: string;
+    constructor(options?: ReferralProgramOptions);
+    /** Whether the program is accepting new referral activity. */
+    isActive(): boolean;
+    /** Parse the metadata JSON string; returns `{}` on malformed content. */
+    getMetadata(): Record<string, unknown>;
+    /** Serialize and store the metadata object. */
+    setMetadata(metadata: Record<string, unknown>): void;
+}
+export default ReferralProgram;
+//# sourceMappingURL=ReferralProgram.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralProgram.d.ts","sourceRoot":"","sources":["../../../src/referrals/models/ReferralProgram.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAS,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAEnE,OAAO,KAAK,EACV,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAOa,eAAgB,SAAQ,UAAU;IAC7C,yEAAyE;IAEzE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,oEAAoE;IAEpE,GAAG,EAAE,MAAM,CAAM;IAEjB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAM;IAElB;;;;OAIG;IACH,MAAM,EAAE,qBAAqB,CAAW;IAExC;;;OAGG;IACH,wBAAwB,EAAE,MAAM,CAAM;IAEtC;;;OAGG;IACH,2BAA2B,EAAE,MAAM,CAAM;IAEzC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,sBAA2B;IAahD,8DAA8D;IAC9D,QAAQ,IAAI,OAAO;IAInB,yEAAyE;IACzE,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYtC,+CAA+C;IAC/C,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAGrD;AAED,eAAe,eAAe,CAAC"}

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

@@ -0,0 +1,61 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { CommissionPlanComponent } from '../../commissions/index.js';
+import { ReferralAgreementApprovalMode, ReferralTermSnapshotOptions } from '../types.js';
+export declare class ReferralTermSnapshot extends SmrtObject {
+    /** Tenant ID for multi-tenant isolation (nullable → global rows). */
+    tenantId: string | null;
+    /** The Referral this snapshot governs. Required. */
+    referralId: string;
+    /** Id of the ReferralAgreement the terms came from. */
+    agreementId: string;
+    /** Version of the agreement at qualification time. */
+    agreementVersion: number;
+    /** CommissionPlan key the components were copied from. */
+    planKey: string;
+    /**
+     * CommissionPlan version PINNED at qualification — when the agreement
+     * left the version unpinned (`0`), this records the latest-active version
+     * that was resolved.
+     */
+    planVersion: number;
+    /** AttributionPolicy key stamped on the referral at attribution. */
+    policyKey: string;
+    /** AttributionPolicy version stamped on the referral at attribution. */
+    policyVersion: number;
+    /**
+     * FROZEN copy of the plan's components JSON — THE calculation inputs.
+     * Use {@link getComponents} for the typed array.
+     */
+    components: string;
+    /** ISO 4217 currency the frozen terms are denominated in. */
+    currency: string;
+    /** Clearing window (days) copied from the agreement. */
+    clearingDays: number;
+    /** Approval mode copied from the agreement. */
+    approvalMode: ReferralAgreementApprovalMode;
+    /** Additional metadata as a JSON string (immutable like every field). */
+    metadata: string;
+    constructor(options?: ReferralTermSnapshotOptions);
+    /** Capture the persisted state so the save guard can reject mutations. */
+    initialize(): Promise<this>;
+    /**
+     * Parse {@link components} into the typed plan-component array the
+     * calculation service consumes; returns `[]` on empty/invalid JSON.
+     */
+    getComponents(): CommissionPlanComponent[];
+    /** Parse {@link metadata}; returns `{}` on malformed content. */
+    getMetadata(): Record<string, unknown>;
+    /**
+     * Save with the full-immutability guard:
+     *
+     * - A hydrated persisted row must serialize IDENTICALLY to its captured
+     *   state — any field change throws (no-op re-saves pass).
+     * - An instance carrying an existing row's id WITHOUT having hydrated it
+     *   (e.g. `create({ id, _skipLoad: true })`) is rejected outright — blind
+     *   overwrites can't sidestep the comparison.
+     */
+    save(): Promise<this>;
+    private serializeState;
+}
+export default ReferralTermSnapshot;
+//# sourceMappingURL=ReferralTermSnapshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralTermSnapshot.d.ts","sourceRoot":"","sources":["../../../src/referrals/models/ReferralTermSnapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAExE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,KAAK,EACV,6BAA6B,EAC7B,2BAA2B,EAC5B,MAAM,aAAa,CAAC;AAUrB,qBAQa,oBAAqB,SAAQ,UAAU;IAClD,qEAAqE;IAErE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,oDAAoD;IAEpD,UAAU,EAAE,MAAM,CAAM;IAExB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAM;IAEzB,sDAAsD;IACtD,gBAAgB,EAAE,MAAM,CAAK;IAE7B,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAM;IAErB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAK;IAExB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAM;IAEvB,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAK;IAE1B;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAQ;IAE1B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAS;IAEzB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAK;IAEzB,+CAA+C;IAC/C,YAAY,EAAE,6BAA6B,CAAY;IAEvD,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,2BAAgC;IAuBrD,0EAA0E;IAC3D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ1C;;;OAGG;IACH,aAAa,IAAI,uBAAuB,EAAE;IAU1C,iEAAiE;IACjE,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYtC;;;;;;;;OAQG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBpC,OAAO,CAAC,cAAc;CAkBvB;AAED,eAAe,oBAAoB,CAAC"}

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

@@ -0,0 +1,55 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { ReferralTouchKind, ReferralTouchOptions } from '../types.js';
+export declare class ReferralTouch extends SmrtObject {
+    /** Tenant ID for multi-tenant isolation (nullable → global touches). */
+    tenantId: string | null;
+    /** The ReferralLink that produced this touch (empty for touchpoints
+     * without a link, e.g. manual assignments). */
+    linkId: string;
+    /** The share code involved, when the touch came through a code/link. */
+    code: string;
+    /** The Referrer this touch credits. Required. */
+    referrerId: string;
+    /** The ReferralProgram the touch belongs to. */
+    programId: string;
+    /** What kind of interaction this evidence records. */
+    kind: ReferralTouchKind;
+    /**
+     * Prospect identity when known — a generic `(subjectKind, subjectId)`
+     * pair (e.g. `('lead', <id>)`, `('email', 'a@b.test')`). Attribution
+     * matches touches to a resolution's subject and/or target through these.
+     */
+    subjectKind: string;
+    /** Identifier within the {@link subjectKind} namespace. */
+    subjectId: string;
+    /** When the interaction occurred (not when it was ingested). */
+    occurredAt: Date;
+    /**
+     * Evidence payload as a JSON object string (the code/link/url for clicks,
+     * actor + reason for manual assignments, …). Use
+     * {@link getEvidence}/{@link setEvidence}.
+     */
+    evidence: string;
+    /**
+     * Free-form JSON object stored as a string. Use
+     * {@link getMetadata}/{@link setMetadata} instead of parsing manually.
+     */
+    metadata: string;
+    constructor(options?: ReferralTouchOptions);
+    /**
+     * Re-coerce {@link occurredAt} after the framework reapplies raw option /
+     * hydrated row values (SQLite hands back ISO strings).
+     */
+    initialize(): Promise<this>;
+    /** Parse {@link evidence}; returns `{}` on empty/invalid JSON. */
+    getEvidence(): Record<string, unknown>;
+    /** Serialize and store {@link evidence}. */
+    setEvidence(evidence: Record<string, unknown>): void;
+    /** Parse {@link metadata}; returns `{}` on malformed content. */
+    getMetadata(): Record<string, unknown>;
+    /** Serialize and store {@link metadata}. */
+    setMetadata(data: Record<string, unknown>): void;
+    private static coerceDate;
+}
+export default ReferralTouch;
+//# sourceMappingURL=ReferralTouch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralTouch.d.ts","sourceRoot":"","sources":["../../../src/referrals/models/ReferralTouch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAExE,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE3E,qBASa,aAAc,SAAQ,UAAU;IAC3C,wEAAwE;IAExE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;mDAC+C;IAE/C,MAAM,EAAE,MAAM,CAAM;IAEpB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAM;IAElB,iDAAiD;IAEjD,UAAU,EAAE,MAAM,CAAM;IAExB,gDAAgD;IAEhD,SAAS,EAAE,MAAM,CAAM;IAEvB,sDAAsD;IACtD,IAAI,EAAE,iBAAiB,CAAW;IAElC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAM;IAEzB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAM;IAEvB,gEAAgE;IAChE,UAAU,EAAE,IAAI,CAAc;IAE9B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAQ;IAExB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,oBAAyB;IAkB9C;;;OAGG;IACY,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM1C,kEAAkE;IAClE,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYtC,4CAA4C;IAC5C,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIpD,iEAAiE;IACjE,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,aAAa,CAAC"}

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

@@ -0,0 +1,69 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { 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
+ * `referrerId`).
+ *
+ * Roles and money stay separate (see `packages/sales/AGENTS.md` "Roles vs.
+ * money"): a referrer connects to payouts only through the optional
+ * `earnerId` pointing at the commissions module's neutral `Earner`. A
+ * referral cannot produce Commissions until its referrer carries an
+ * `earnerId` — `ReferralCommissionService` skips such referrals with reason
+ * `'referrer_missing_earner'`.
+ *
+ * @example
+ * ```typescript
+ * const referrers = await ReferrerCollection.create({ db });
+ * const referrer = await referrers.create({
+ *   profileId: 'profile-uuid',
+ *   displayName: 'Jordan Partner',
+ *   status: 'active',
+ * });
+ * const active = await referrers.findActive();
+ * ```
+ */
+export declare class Referrer extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation. Nullable to support both
+     * tenant-scoped and global (operator-level) referrers.
+     */
+    tenantId: string | null;
+    /**
+     * Identity of the person/organization acting as a referrer —
+     * cross-package string reference to a smrt-profiles Profile.
+     */
+    profileId: string;
+    /**
+     * Optional link to the commissions module's `Earner` (the neutral payout
+     * identity). String-form same-package FK: the Earner class lives in
+     * `src/commissions` and is intentionally NOT imported here — the string
+     * form registers the relationship without a module dependency, keeping the
+     * `referrals → commissions` boundary reference-only at the model layer.
+     * Empty when the referrer is not commission-compensated (yet).
+     */
+    earnerId: string;
+    /** Human-readable display name for portals and operator views. */
+    displayName: string;
+    /**
+     * Role lifecycle: `pending` (default, awaiting approval) → `active` /
+     * `suspended`. Only active referrers should receive new links/agreements.
+     */
+    status: ReferrerStatus;
+    /**
+     * Free-form JSON object stored as a string. Use
+     * {@link getMetadata}/{@link setMetadata} instead of parsing manually.
+     */
+    metadata: string;
+    constructor(options?: ReferrerOptions);
+    /** Whether the referrer may receive new links/agreements. */
+    isActive(): boolean;
+    isPending(): boolean;
+    isSuspended(): boolean;
+    /** Parse the metadata JSON string; returns `{}` on malformed content. */
+    getMetadata(): Record<string, unknown>;
+    /** Serialize and store the metadata object. */
+    setMetadata(metadata: Record<string, unknown>): void;
+}
+export default Referrer;
+//# sourceMappingURL=Referrer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Referrer.d.ts","sourceRoot":"","sources":["../../../src/referrals/models/Referrer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAMa,QAAS,SAAQ,UAAU;IACtC;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;;OAGG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;;;;;;OAOG;IAEH,QAAQ,EAAE,MAAM,CAAM;IAEtB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAM;IAEzB;;;OAGG;IACH,MAAM,EAAE,cAAc,CAAa;IAEnC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,eAAoB;IAWzC,6DAA6D;IAC7D,QAAQ,IAAI,OAAO;IAInB,SAAS,IAAI,OAAO;IAIpB,WAAW,IAAI,OAAO;IAItB,yEAAyE;IACzE,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYtC,+CAA+C;IAC/C,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAGrD;AAED,eAAe,QAAQ,CAAC"}