@happyvertical/smrt-sales 0.39.2

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

@@ -0,0 +1,17 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { AttributionException } from '../models/AttributionException.js';
+export declare class AttributionExceptionCollection extends SmrtCollection<AttributionException> {
+    static readonly _itemClass: typeof AttributionException;
+    /** Every open exception, oldest first (the review queue). */
+    findOpen(): Promise<AttributionException[]>;
+    /**
+     * The open exception for one target within one program, or `null`.
+     * `AttributionService.resolve()` returns this instead of minting a
+     * duplicate when a conflict is already parked for review.
+     */
+    findOpenByTarget(targetKind: string, targetId: string, programId: string): Promise<AttributionException | null>;
+    /** Every exception (open and resolved) for one target, newest first. */
+    findByTarget(targetKind: string, targetId: string): Promise<AttributionException[]>;
+}
+export default AttributionExceptionCollection;
+//# sourceMappingURL=AttributionExceptionCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AttributionExceptionCollection.d.ts","sourceRoot":"","sources":["../../../src/referrals/collections/AttributionExceptionCollection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,qBAAa,8BAA+B,SAAQ,cAAc,CAAC,oBAAoB,CAAC;IACtF,MAAM,CAAC,QAAQ,CAAC,UAAU,8BAAwB;IAElD,6DAA6D;IACvD,QAAQ,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAOjD;;;;OAIG;IACG,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IASvC,wEAAwE;IAClE,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,oBAAoB,EAAE,CAAC;CAMnC;AAED,eAAe,8BAA8B,CAAC"}

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

@@ -0,0 +1,50 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { AttributionPolicy } from '../models/AttributionPolicy.js';
+import { 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,
+ * and `status` is always `draft` — a caller cannot mint a pre-activated
+ * amendment.
+ */
+export interface AttributionPolicyAmendmentChanges {
+    windowDays?: number;
+    creditMode?: AttributionCreditMode;
+    conflictBehavior?: AttributionConflictBehavior;
+    allowSelfReferral?: boolean;
+    allowExistingClients?: boolean;
+    eligibleServices?: string[];
+    eligibleCampaigns?: string[];
+    eligibleRegions?: string[];
+    effectiveFrom?: Date | null;
+    metadata?: Record<string, unknown>;
+}
+export declare class AttributionPolicyCollection extends SmrtCollection<AttributionPolicy> {
+    static readonly _itemClass: typeof AttributionPolicy;
+    /** Every version of a policy, newest version first. */
+    findByPolicyKey(policyKey: string): Promise<AttributionPolicy[]>;
+    /** Policies by status. */
+    findByStatus(status: AttributionPolicyStatus): Promise<AttributionPolicy[]>;
+    /**
+     * The highest ACTIVE version of a policy already IN EFFECT at `at`, or
+     * `null` when none is. This is what `AttributionService.resolve()` loads
+     * when the caller doesn't pin a version. A future-dated amendment can be
+     * activated ahead of its effective date without governing attributions
+     * resolved before it takes effect (`effectiveFrom: null` = effective
+     * immediately).
+     */
+    latestActiveByKey(policyKey: string, at?: Date, tenantId?: string | null): Promise<AttributionPolicy | null>;
+    /**
+     * Create an amendment: insert a new DRAFT row with
+     * `version = max(existing versions) + 1`, copying the latest existing
+     * version's fields and then applying `changes`. The source version is not
+     * touched — activate the draft (and supersede the prior active version)
+     * as a separate, explicit step.
+     *
+     * Throws when no version of `policyKey` exists (nothing to amend — use
+     * `create` for a brand-new policy).
+     */
+    createAmendment(policyKey: string, changes?: AttributionPolicyAmendmentChanges): Promise<AttributionPolicy>;
+}
+export default AttributionPolicyCollection;
+//# sourceMappingURL=AttributionPolicyCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AttributionPolicyCollection.d.ts","sourceRoot":"","sources":["../../../src/referrals/collections/AttributionPolicyCollection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EACV,2BAA2B,EAC3B,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,iCAAiC;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC,gBAAgB,CAAC,EAAE,2BAA2B,CAAC;IAC/C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,aAAa,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qBAAa,2BAA4B,SAAQ,cAAc,CAAC,iBAAiB,CAAC;IAChF,MAAM,CAAC,QAAQ,CAAC,UAAU,2BAAqB;IAE/C,uDAAuD;IACjD,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAOtE,0BAA0B;IACpB,YAAY,CAChB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAO/B;;;;;;;OAOG;IACG,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,EAAE,GAAE,IAAiB,EACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAsBpC;;;;;;;;;OASG;IACG,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,iBAAiB,CAAC;CA2C9B;AAED,eAAe,2BAA2B,CAAC"}

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

@@ -0,0 +1,48 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { ReferralAgreement } from '../models/ReferralAgreement.js';
+import { ReferralAgreementApprovalMode } from '../types.js';
+/**
+ * Fields an amendment may change relative to the version it copies.
+ * `referrerId`/`programId` are fixed (they identify the agreement),
+ * `version` is computed, and `status` is always `draft`.
+ */
+export interface ReferralAgreementAmendmentChanges {
+    commissionPlanKey?: string;
+    commissionPlanVersion?: number;
+    clearingDays?: number;
+    approvalMode?: ReferralAgreementApprovalMode;
+    effectiveFrom?: Date | null;
+    effectiveTo?: Date | null;
+    contractRef?: string;
+    executedArtifactUrl?: string;
+    executedArtifactHash?: string;
+    acceptanceEvidence?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export declare class ReferralAgreementCollection extends SmrtCollection<ReferralAgreement> {
+    static readonly _itemClass: typeof ReferralAgreement;
+    /** Every version of one referrer+program agreement, newest version first. */
+    findByReferrerAndProgram(referrerId: string, programId: string): Promise<ReferralAgreement[]>;
+    /**
+     * The agreement governing `(referrerId, programId)` at instant `at`
+     * (default now): status `active` AND effective window containing `at`
+     * (`effectiveFrom` null = always started; `effectiveTo` null =
+     * open-ended). When several active versions overlap — transitional states
+     * during amendment activation — the highest version wins. `null` when
+     * nothing governs.
+     */
+    activeFor(referrerId: string, programId: string, at?: Date): Promise<ReferralAgreement | null>;
+    /**
+     * Create an amendment: insert a new DRAFT row with
+     * `version = max(existing versions) + 1`, copying the latest existing
+     * version's fields and then applying `changes`. The source version is not
+     * touched — activate the draft (and supersede the prior active version)
+     * as a separate, explicit step.
+     *
+     * Throws when no version exists for the pair (nothing to amend — use
+     * `create` for a brand-new agreement).
+     */
+    createAmendment(referrerId: string, programId: string, changes?: ReferralAgreementAmendmentChanges): Promise<ReferralAgreement>;
+}
+export default ReferralAgreementCollection;
+//# sourceMappingURL=ReferralAgreementCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralAgreementCollection.d.ts","sourceRoot":"","sources":["../../../src/referrals/collections/ReferralAgreementCollection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,iCAAiC;IAChD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,6BAA6B,CAAC;IAC7C,aAAa,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC5B,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qBAAa,2BAA4B,SAAQ,cAAc,CAAC,iBAAiB,CAAC;IAChF,MAAM,CAAC,QAAQ,CAAC,UAAU,2BAAqB;IAE/C,6EAA6E;IACvE,wBAAwB,CAC5B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAO/B;;;;;;;OAOG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,EAAE,GAAE,IAAiB,GACpB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAQpC;;;;;;;;;OASG;IACG,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,iBAAiB,CAAC;CA4C9B;AAED,eAAe,2BAA2B,CAAC"}

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

@@ -0,0 +1,25 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { Referral } from '../models/Referral.js';
+export declare class ReferralCollection extends SmrtCollection<Referral> {
+    static readonly _itemClass: typeof Referral;
+    /** All referrals credited to a referrer, newest first. */
+    findByReferrer(referrerId: string): Promise<Referral[]>;
+    /** All referrals pointing at one qualifying target, newest first. */
+    findByTarget(targetKind: string, targetId: string): Promise<Referral[]>;
+    /**
+     * QUALIFIED referrals for one target — what
+     * `ReferralCommissionService.processEarningEvent` resolves when given a
+     * target instead of explicit referral ids.
+     */
+    findQualifiedByTarget(targetKind: string, targetId: string): Promise<Referral[]>;
+    /**
+     * Expire lapsed attributions: every `attributed` referral whose
+     * `expiresAt` is set and `<= now` transitions to `expired` and is saved.
+     * Referrals without an `expiresAt` never lapse.
+     *
+     * @returns The referrals expired by this sweep.
+     */
+    sweepExpired(now?: Date): Promise<Referral[]>;
+}
+export default ReferralCollection;
+//# sourceMappingURL=ReferralCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralCollection.d.ts","sourceRoot":"","sources":["../../../src/referrals/collections/ReferralCollection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,qBAAa,kBAAmB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IAC9D,MAAM,CAAC,QAAQ,CAAC,UAAU,kBAAY;IAEtC,0DAA0D;IACpD,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAO7D,qEAAqE;IAC/D,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,QAAQ,EAAE,CAAC;IAOtB;;;;OAIG;IACG,qBAAqB,CACzB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,QAAQ,EAAE,CAAC;IAOtB;;;;;;OAMG;IACG,YAAY,CAAC,GAAG,GAAE,IAAiB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CAiBhE;AAED,eAAe,kBAAkB,CAAC"}

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

@@ -0,0 +1,96 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { ReferralLink } from '../models/ReferralLink.js';
+import { ReferralTouch } from '../models/ReferralTouch.js';
+/** Length of generated share codes. */
+export declare const REFERRAL_CODE_LENGTH = 10;
+/** Alphabet generated codes draw from (lowercase alphanumeric). */
+export declare const REFERRAL_CODE_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+/** Attempts before {@link ReferralLinkCollection.createWithUniqueCode} gives up. */
+export declare const MAX_CODE_GENERATION_ATTEMPTS = 5;
+/**
+ * Generate a crypto-random share code: {@link REFERRAL_CODE_LENGTH}
+ * characters drawn uniformly from {@link REFERRAL_CODE_ALPHABET} via
+ * rejection-sampled `crypto.randomBytes` (no modulo bias).
+ */
+export declare function generateReferralCode(): string;
+/** Input for {@link ReferralLinkCollection.createWithUniqueCode}. */
+export interface CreateReferralLinkInput {
+    referrerId: string;
+    programId: string;
+    targetUrl?: string;
+    label?: string;
+    tenantId?: string | null;
+    /**
+     * Test seam / customization point: overrides the random code generator.
+     * Must return {@link REFERRAL_CODE_LENGTH} lowercase-alphanumeric
+     * characters; collisions with existing codes are retried up to
+     * {@link MAX_CODE_GENERATION_ATTEMPTS} times.
+     */
+    generateCode?: () => string;
+}
+/** Why {@link ReferralLinkCollection.recordClick} refused to record. */
+export type RecordClickRefusal = 'unknown_code' | 'link_disabled';
+/**
+ * Result of {@link ReferralLinkCollection.recordClick}. On success `link`
+ * and `touch` are both set and `refused` is absent. On refusal `touch` is
+ * `null`, `refused` names the reason, and `link` carries the (disabled) link
+ * for `'link_disabled'` / `null` for `'unknown_code'`.
+ */
+export interface RecordClickResult {
+    link: ReferralLink | null;
+    touch: ReferralTouch | null;
+    refused?: RecordClickRefusal;
+}
+/** Input for {@link ReferralLinkCollection.recordClick}. */
+export interface RecordClickInput {
+    code: string;
+    /** Extra evidence merged into the touch's evidence JSON (UA, IP hash, …). */
+    evidence?: Record<string, unknown>;
+    /** When the click occurred; defaults to now. */
+    occurredAt?: Date;
+    /**
+     * Prospect identity when the edge already knows it (e.g. a logged-in
+     * visitor or a pre-created lead). Without a subject pair the touch is
+     * anonymous and `AttributionService.resolve` cannot gather it by subject —
+     * the intake handler must then append a second, identified touch once the
+     * prospect materializes (same `occurredAt` preserves credit ordering).
+     */
+    subjectKind?: string;
+    subjectId?: string;
+}
+export declare class ReferralLinkCollection extends SmrtCollection<ReferralLink> {
+    static readonly _itemClass: typeof ReferralLink;
+    /** All links for a referrer, newest first. */
+    findByReferrer(referrerId: string): Promise<ReferralLink[]>;
+    /**
+     * Look up a link by its globally unique code (codes are minted lowercase;
+     * the lookup normalizes case so shared codes survive re-typing).
+     */
+    findByCode(code: string): Promise<ReferralLink | null>;
+    /**
+     * Create a link with a freshly minted, uniqueness-checked code.
+     *
+     * Codes come from `crypto.randomBytes` mapped to
+     * {@link REFERRAL_CODE_LENGTH} lowercase-alphanumeric characters. The
+     * check-then-insert loop retries on collision up to
+     * {@link MAX_CODE_GENERATION_ATTEMPTS} times, then throws — at 36^10
+     * possible codes repeated collisions mean the generator is broken (or a
+     * test seam returns a constant), not bad luck.
+     */
+    createWithUniqueCode(input: CreateReferralLinkInput): Promise<ReferralLink>;
+    /**
+     * Record a click on a share code: find the ACTIVE link, increment its
+     * {@link ReferralLink.clickCount}, and write an immutable ReferralTouch
+     * (kind `'click'`, evidence carrying the code/link/url plus any caller
+     * evidence). Returns `{ link, touch }` on success.
+     *
+     * Refusals return a typed result instead of throwing (clicks arrive from
+     * the edge — an unknown or disabled code is an expected outcome, not an
+     * exception): `refused: 'unknown_code'` (no such code; `link: null`) or
+     * `refused: 'link_disabled'` (link exists but is disabled; the link is
+     * returned, nothing is written).
+     */
+    recordClick(input: RecordClickInput): Promise<RecordClickResult>;
+}
+export default ReferralLinkCollection;
+//# sourceMappingURL=ReferralLinkCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralLinkCollection.d.ts","sourceRoot":"","sources":["../../../src/referrals/collections/ReferralLinkCollection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAuB,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAGhE,uCAAuC;AACvC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,yCAAyC,CAAC;AAE7E,oFAAoF;AACpF,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAe7C;AAED,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,wEAAwE;AACxE,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG,eAAe,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5B,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,gDAAgD;IAChD,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,sBAAuB,SAAQ,cAAc,CAAC,YAAY,CAAC;IACtE,MAAM,CAAC,QAAQ,CAAC,UAAU,sBAAgB;IAE1C,8CAA8C;IACxC,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAOjE;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAU5D;;;;;;;;;OASG;IACG,oBAAoB,CACxB,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,YAAY,CAAC;IA+BxB;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAuCvE;AAED,eAAe,sBAAsB,CAAC"}

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

@@ -0,0 +1,18 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { ReferralProgram } from '../models/ReferralProgram.js';
+import { ReferralProgramStatus } from '../types.js';
+export declare class ReferralProgramCollection extends SmrtCollection<ReferralProgram> {
+    static readonly _itemClass: typeof ReferralProgram;
+    /**
+     * Look up a program by its natural key within the ambient tenant scope
+     * (`(tenant_id, key)` is the conflict key, so under a tenant context the
+     * auto-filter narrows this to at most one row).
+     */
+    findByKey(key: string): Promise<ReferralProgram | null>;
+    /** Programs by status. */
+    findByStatus(status: ReferralProgramStatus): Promise<ReferralProgram[]>;
+    /** All active programs. */
+    findActive(): Promise<ReferralProgram[]>;
+}
+export default ReferralProgramCollection;
+//# sourceMappingURL=ReferralProgramCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralProgramCollection.d.ts","sourceRoot":"","sources":["../../../src/referrals/collections/ReferralProgramCollection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,qBAAa,yBAA0B,SAAQ,cAAc,CAAC,eAAe,CAAC;IAC5E,MAAM,CAAC,QAAQ,CAAC,UAAU,yBAAmB;IAE7C;;;;OAIG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAK7D,0BAA0B;IACpB,YAAY,CAChB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,eAAe,EAAE,CAAC;IAO7B,2BAA2B;IACrB,UAAU,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;CAG/C;AAED,eAAe,yBAAyB,CAAC"}

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

@@ -0,0 +1,13 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { ReferralTermSnapshot } from '../models/ReferralTermSnapshot.js';
+export declare class ReferralTermSnapshotCollection extends SmrtCollection<ReferralTermSnapshot> {
+    static readonly _itemClass: typeof ReferralTermSnapshot;
+    /**
+     * Every snapshot minted for one referral, newest first — index 0 is the
+     * currently governing snapshot only if the referral's `snapshotId` says
+     * so (requalification keeps old rows as history).
+     */
+    findByReferral(referralId: string): Promise<ReferralTermSnapshot[]>;
+}
+export default ReferralTermSnapshotCollection;
+//# sourceMappingURL=ReferralTermSnapshotCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralTermSnapshotCollection.d.ts","sourceRoot":"","sources":["../../../src/referrals/collections/ReferralTermSnapshotCollection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,qBAAa,8BAA+B,SAAQ,cAAc,CAAC,oBAAoB,CAAC;IACtF,MAAM,CAAC,QAAQ,CAAC,UAAU,8BAAwB;IAElD;;;;OAIG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;CAM1E;AAED,eAAe,8BAA8B,CAAC"}

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

@@ -0,0 +1,30 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { ReferralTouch } from '../models/ReferralTouch.js';
+/** Input for {@link ReferralTouchCollection.findByTargetWindow}. */
+export interface TouchWindowQuery {
+    subjectKind: string;
+    subjectId: string;
+    /** Restrict to one program's touches. */
+    programId: string;
+    /** Only touches occurring at or after this instant. */
+    since: Date;
+}
+export declare class ReferralTouchCollection extends SmrtCollection<ReferralTouch> {
+    static readonly _itemClass: typeof ReferralTouch;
+    /** All touches for a referrer, oldest first. */
+    findByReferrer(referrerId: string): Promise<ReferralTouch[]>;
+    /**
+     * Every touch recorded against one subject identity, oldest first —
+     * attribution's raw candidate stream.
+     */
+    findBySubject(subjectKind: string, subjectId: string): Promise<ReferralTouch[]>;
+    /**
+     * Touches for one subject within one program occurring at or after
+     * `since`, oldest first. The date bound is applied in memory after the
+     * indexed equality filters (sibling-module pattern — the semantics hold
+     * whether an adapter returns ISO strings or Dates).
+     */
+    findByTargetWindow(query: TouchWindowQuery): Promise<ReferralTouch[]>;
+}
+export default ReferralTouchCollection;
+//# sourceMappingURL=ReferralTouchCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralTouchCollection.d.ts","sourceRoot":"","sources":["../../../src/referrals/collections/ReferralTouchCollection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,KAAK,EAAE,IAAI,CAAC;CACb;AAED,qBAAa,uBAAwB,SAAQ,cAAc,CAAC,aAAa,CAAC;IACxE,MAAM,CAAC,QAAQ,CAAC,UAAU,uBAAiB;IAE3C,gDAAgD;IAC1C,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAOlE;;;OAGG;IACG,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,EAAE,CAAC;IAO3B;;;;;OAKG;IACG,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAa5E;AAED,eAAe,uBAAuB,CAAC"}

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

@@ -0,0 +1,17 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { Referrer } from '../models/Referrer.js';
+import { ReferrerStatus } from '../types.js';
+export declare class ReferrerCollection extends SmrtCollection<Referrer> {
+    static readonly _itemClass: typeof Referrer;
+    /**
+     * Find referrer roles held by a given profile (a profile may hold the
+     * role in several tenants/contexts).
+     */
+    findByProfile(profileId: string): Promise<Referrer[]>;
+    /** Referrers by status. */
+    findByStatus(status: ReferrerStatus): Promise<Referrer[]>;
+    /** All active referrers (eligible for new links/agreements). */
+    findActive(): Promise<Referrer[]>;
+}
+export default ReferrerCollection;
+//# sourceMappingURL=ReferrerCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferrerCollection.d.ts","sourceRoot":"","sources":["../../../src/referrals/collections/ReferrerCollection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,qBAAa,kBAAmB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IAC9D,MAAM,CAAC,QAAQ,CAAC,UAAU,kBAAY;IAEtC;;;OAGG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAO3D,2BAA2B;IACrB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAO/D,gEAAgE;IAC1D,UAAU,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;CAGxC;AAED,eAAe,kBAAkB,CAAC"}

package/dist/referrals/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Referrals module of `@happyvertical/smrt-sales`.
+ *
+ * Referrers, ReferralPrograms, versioned AttributionPolicies, share
+ * links/codes, immutable ReferralTouch evidence, Referrals with guarded
+ * lifecycles, the AttributionException review queue, versioned
+ * ReferralAgreements, immutable ReferralTermSnapshots, and the services
+ * that connect them: attribution, qualification, and the commission bridge.
+ *
+ * This module depends on `../commissions` (same package) for the neutral
+ * financial core and NEVER on `../crm` — qualifying targets are generic
+ * `(targetKind, targetId)` string pairs (see `packages/sales/AGENTS.md`).
+ *
+ * @packageDocumentation
+ */
+export { AttributionExceptionCollection } from './collections/AttributionExceptionCollection.js';
+export { type AttributionPolicyAmendmentChanges, AttributionPolicyCollection, } from './collections/AttributionPolicyCollection.js';
+export { type ReferralAgreementAmendmentChanges, ReferralAgreementCollection, } from './collections/ReferralAgreementCollection.js';
+export { ReferralCollection } from './collections/ReferralCollection.js';
+export { type CreateReferralLinkInput, generateReferralCode, MAX_CODE_GENERATION_ATTEMPTS, REFERRAL_CODE_ALPHABET, REFERRAL_CODE_LENGTH, type RecordClickInput, type RecordClickRefusal, type RecordClickResult, ReferralLinkCollection, } from './collections/ReferralLinkCollection.js';
+export { ReferralProgramCollection } from './collections/ReferralProgramCollection.js';
+export { ReferralTermSnapshotCollection } from './collections/ReferralTermSnapshotCollection.js';
+export { ReferralTouchCollection, type TouchWindowQuery, } from './collections/ReferralTouchCollection.js';
+export { ReferrerCollection } from './collections/ReferrerCollection.js';
+export { AttributionException } from './models/AttributionException.js';
+export { AttributionPolicy, validateAttributionPolicyTerms, } from './models/AttributionPolicy.js';
+export { Referral } from './models/Referral.js';
+export { ReferralAgreement } from './models/ReferralAgreement.js';
+export { assertHttpTargetUrl, ReferralLink } from './models/ReferralLink.js';
+export { ReferralProgram } from './models/ReferralProgram.js';
+export { ReferralTermSnapshot } from './models/ReferralTermSnapshot.js';
+export { ReferralTouch } from './models/ReferralTouch.js';
+export { Referrer } from './models/Referrer.js';
+export { type AttributionAward, type AttributionAwardResult, type AttributionRefusalReason, type AttributionResolution, AttributionService, type AttributionServiceDeps, type OverrideAttributionInput, QualifiedReferralOverrideError, type RecordManualAssignmentInput, type ResolveAttributionInput, type ResolveExceptionInput, } from './services/AttributionService.js';
+export { type ProcessEarningEventInput, type ProcessEarningEventResult, REFERRAL_TERMS_SNAPSHOT_KIND, type ReferralCommissionOutcome, ReferralCommissionService, type ReferralCommissionServiceDeps, type ReferralProcessingSkip, type ReferralProcessingSkipReason, } from './services/ReferralCommissionService.js';
+export { type QualificationRefusalReason, type QualifyReferralInput, type QualifyReferralResult, ReferralQualificationService, type ReferralQualificationServiceDeps, type RequalifyReferralInput, type RequalifyReferralResult, } from './services/ReferralQualificationService.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/referrals/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/referrals/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,8BAA8B,EAAE,MAAM,iDAAiD,CAAC;AACjG,OAAO,EACL,KAAK,iCAAiC,EACtC,2BAA2B,GAC5B,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,KAAK,iCAAiC,EACtC,2BAA2B,GAC5B,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,EACL,KAAK,uBAAuB,EAC5B,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,sBAAsB,GACvB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AACvF,OAAO,EAAE,8BAA8B,EAAE,MAAM,iDAAiD,CAAC;AACjG,OAAO,EACL,uBAAuB,EACvB,KAAK,gBAAgB,GACtB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAEzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EACL,iBAAiB,EACjB,8BAA8B,GAC/B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,kBAAkB,EAClB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,8BAA8B,EAC9B,KAAK,2BAA2B,EAChC,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,GAC3B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,4BAA4B,EAC5B,KAAK,yBAAyB,EAC9B,yBAAyB,EACzB,KAAK,6BAA6B,EAClC,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,GAClC,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,4BAA4B,EAC5B,KAAK,gCAAgC,EACrC,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,4CAA4C,CAAC;AAEpD,cAAc,YAAY,CAAC"}

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

@@ -0,0 +1,85 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { AttributionExceptionCandidate, AttributionExceptionOptions, AttributionExceptionStatus } from '../types.js';
+export declare class AttributionException extends SmrtObject {
+    /** Tenant ID for multi-tenant isolation (nullable → global rows). */
+    tenantId: string | null;
+    /** Target the conflicting attribution is about. Required. */
+    targetKind: string;
+    /** Identifier within the {@link targetKind} namespace. Required. */
+    targetId: string;
+    /** The ReferralProgram the contention belongs to. */
+    programId: string;
+    /** `open` (default, awaiting review) or `resolved`. */
+    status: AttributionExceptionStatus;
+    /**
+     * Why the exception was raised — recommended vocabulary: `'tie'`
+     * (exact-timestamp tie between distinct referrers),
+     * `'competing_touches'` (competing manual assignments), and
+     * `'policy_review'` (`conflictBehavior: 'review'` with multiple
+     * referrers). Open string.
+     */
+    conflictReason: string;
+    /**
+     * The competing touches as a JSON-string array of
+     * {@link AttributionExceptionCandidate}. Use
+     * {@link getCandidates}/{@link setCandidates}.
+     */
+    candidates: string;
+    /**
+     * How the exception was resolved — `'override'` (human award) or
+     * `'policy'` (policy re-run). Empty while open.
+     */
+    resolutionMode: string;
+    /** Why credit was awarded the way it was. REQUIRED to resolve. */
+    resolutionReason: string;
+    /**
+     * Who resolved the exception — cross-package string reference to a
+     * smrt-profiles Profile.
+     */
+    resolvedByProfileId: string;
+    /**
+     * Ids of the Referral rows the resolution created, as a JSON-string
+     * array. Use {@link getResolvedReferralIds}/{@link setResolvedReferralIds}.
+     */
+    resolvedReferralIds: string;
+    /** When the exception was resolved. */
+    resolvedAt: Date | null;
+    /**
+     * Free-form JSON object stored as a string (the attribution service
+     * stamps the policy pin here for later resolution). Use
+     * {@link getMetadata}/{@link setMetadata}.
+     */
+    metadata: string;
+    constructor(options?: AttributionExceptionOptions);
+    /** Re-coerce date fields after the framework reapplies raw option values. */
+    initialize(): Promise<this>;
+    /** Whether the exception still awaits review. */
+    isOpen(): boolean;
+    /** Parse {@link candidates}; returns `[]` on empty/invalid JSON. */
+    getCandidates(): AttributionExceptionCandidate[];
+    /** Serialize and store {@link candidates}. */
+    setCandidates(candidates: AttributionExceptionCandidate[]): void;
+    /** Parse {@link resolvedReferralIds}; returns `[]` on empty/invalid JSON. */
+    getResolvedReferralIds(): string[];
+    /** Serialize and store {@link resolvedReferralIds}. */
+    setResolvedReferralIds(ids: string[]): void;
+    /** Parse {@link metadata}; returns `{}` on malformed content. */
+    getMetadata(): Record<string, unknown>;
+    /** Serialize and store {@link metadata}. */
+    setMetadata(data: Record<string, unknown>): void;
+    /**
+     * Mark the exception resolved (mutates; the caller saves). Requires a
+     * non-empty reason — resolutions without a recorded rationale are
+     * rejected.
+     */
+    markResolved(input: {
+        mode: string;
+        reason: string;
+        resolvedByProfileId?: string;
+        referralIds: string[];
+        at?: Date;
+    }): void;
+    private static coerceDate;
+}
+export default AttributionException;
+//# sourceMappingURL=AttributionException.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AttributionException.d.ts","sourceRoot":"","sources":["../../../src/referrals/models/AttributionException.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAIL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,EAC3B,MAAM,aAAa,CAAC;AAErB,qBAQa,oBAAqB,SAAQ,UAAU;IAClD,qEAAqE;IAErE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,6DAA6D;IAE7D,UAAU,EAAE,MAAM,CAAM;IAExB,oEAAoE;IAEpE,QAAQ,EAAE,MAAM,CAAM;IAEtB,qDAAqD;IAErD,SAAS,EAAE,MAAM,CAAM;IAEvB,uDAAuD;IACvD,MAAM,EAAE,0BAA0B,CAAU;IAE5C;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,CAAM;IAE5B;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAQ;IAE1B;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAM;IAE5B,kEAAkE;IAClE,gBAAgB,EAAE,MAAM,CAAM;IAE9B;;;OAGG;IAEH,mBAAmB,EAAE,MAAM,CAAM;IAEjC;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAQ;IAEnC,uCAAuC;IACvC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE/B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAQ;gBAEZ,OAAO,GAAE,2BAAgC;IAuBrD,6EAA6E;IAC9D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM1C,iDAAiD;IACjD,MAAM,IAAI,OAAO;IAIjB,oEAAoE;IACpE,aAAa,IAAI,6BAA6B,EAAE;IAYhD,8CAA8C;IAC9C,aAAa,CAAC,UAAU,EAAE,6BAA6B,EAAE,GAAG,IAAI;IAIhE,6EAA6E;IAC7E,sBAAsB,IAAI,MAAM,EAAE;IAYlC,uDAAuD;IACvD,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAI3C,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;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,EAAE,CAAC,EAAE,IAAI,CAAC;KACX,GAAG,IAAI;IAmBR,OAAO,CAAC,MAAM,CAAC,UAAU;CAS1B;AAED,eAAe,oBAAoB,CAAC"}

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

@@ -0,0 +1,128 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { AttributionConflictBehavior, AttributionCreditMode, AttributionPolicyOptions, 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
+ * saves so no active policy can carry malformed terms.
+ */
+export declare function validateAttributionPolicyTerms(policy: AttributionPolicy): void;
+export declare class AttributionPolicy extends SmrtObject {
+    /** Tenant ID for multi-tenant isolation (nullable → global policies). */
+    tenantId: string | null;
+    /** Stable policy identity shared by every version of the policy. */
+    policyKey: string;
+    /** Monotonic version within `policyKey`. Amendments insert `max + 1`. */
+    version: number;
+    /**
+     * Lifecycle status — see {@link POLICY_STATUS_TRANSITIONS}. Mutate via
+     * {@link activate} / {@link supersede} / {@link retire} (or a legal
+     * single-step assignment; the save-time guard rejects illegal edges).
+     */
+    status: AttributionPolicyStatus;
+    /** When this version takes effect. Frozen once the policy activates. */
+    effectiveFrom: Date | null;
+    /**
+     * Attribution window in days: only touches occurring within `windowDays`
+     * of the resolution instant are credit candidates, and attributed
+     * referrals expire `windowDays` after attribution if never qualified.
+     */
+    windowDays: number;
+    /** How competing touches are credited. */
+    creditMode: AttributionCreditMode;
+    /** Whether multi-referrer contention auto-resolves or forces review. */
+    conflictBehavior: AttributionConflictBehavior;
+    /**
+     * Whether a touch whose referrer IS the prospect (matching
+     * `subjectProfileId`) may earn credit. Default false: self-referrals are
+     * dropped from candidate sets.
+     */
+    allowSelfReferral: boolean;
+    /**
+     * Whether referrals of already-existing clients are eligible. Default
+     * false: `AttributionService.resolve()` refuses outright when the caller
+     * flags the prospect as an existing client.
+     */
+    allowExistingClients: boolean;
+    /**
+     * Eligible service keys as a JSON-string array — empty array means ALL
+     * services are eligible. Interpretation belongs to the application layer
+     * that maps its offerings onto service keys; this module records and
+     * validates the list. Use {@link getEligibleServices}/{@link setEligibleServices}.
+     */
+    eligibleServices: string;
+    /** Eligible campaign keys (JSON-string array; empty = all eligible). */
+    eligibleCampaigns: string;
+    /** Eligible region codes (JSON-string array; empty = all eligible). */
+    eligibleRegions: string;
+    /** Additional metadata as a JSON string (not part of the frozen identity). */
+    metadata: string;
+    constructor(options?: AttributionPolicyOptions);
+    /**
+     * Re-coerce date fields after the framework reapplies raw option values,
+     * record the loaded status for the transition guard, and capture the
+     * frozen snapshot when the row arrived already non-draft (superseded and
+     * retired versions — history — can't be rewritten either).
+     */
+    initialize(): Promise<this>;
+    isDraft(): boolean;
+    isActive(): boolean;
+    /** Parse {@link eligibleServices}; returns `[]` on empty/invalid JSON. */
+    getEligibleServices(): string[];
+    /** Serialize and store {@link eligibleServices}. */
+    setEligibleServices(services: string[]): void;
+    /** Parse {@link eligibleCampaigns}; returns `[]` on empty/invalid JSON. */
+    getEligibleCampaigns(): string[];
+    /** Serialize and store {@link eligibleCampaigns}. */
+    setEligibleCampaigns(campaigns: string[]): void;
+    /** Parse {@link eligibleRegions}; returns `[]` on empty/invalid JSON. */
+    getEligibleRegions(): string[];
+    /** Serialize and store {@link eligibleRegions}. */
+    setEligibleRegions(regions: string[]): void;
+    /** Parse {@link metadata}; returns `{}` on empty/invalid JSON. */
+    getMetadata(): Record<string, unknown>;
+    /** Serialize and store {@link metadata}. */
+    setMetadata(data: Record<string, unknown>): void;
+    /**
+     * Transition `draft → active`. Validates the terms first so no active
+     * policy can carry malformed window/mode/eligibility values.
+     */
+    activate(): void;
+    /** Transition `active → superseded` (a newer version took over). */
+    supersede(): void;
+    /** Transition `draft | active → retired` (terminal). */
+    retire(): 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 (re-read
+     *    from the DB so a `create({ id: <existing>, _skipLoad: true })` upsert
+     *    can't sidestep the guard).
+     * 2. **Frozen policy identity** — once the row has been saved non-draft,
+     *    every policy-defining field must match the captured snapshot. Amend
+     *    by inserting a new version instead.
+     */
+    save(): Promise<this>;
+    /**
+     * Refuse a save whose `(tenantId, policyKey, version)` natural key
+     * already belongs to a DIFFERENT row — the frozen-identity guard is
+     * instance-local, so a fresh instance would otherwise upsert over the
+     * persisted policy (rewriting attribution rules and rotating the row
+     * id). Edit drafts by hydrating them; change terms with
+     * `AttributionPolicyCollection.createAmendment()`.
+     */
+    private assertNaturalKeyNotTaken;
+    /**
+     * Resolve the AUTHORITATIVE prior status from the database; fall back to
+     * the loaded-status WeakMap only when the DB is unavailable. `undefined`
+     * means no persisted row exists (genuinely new).
+     */
+    private resolvePriorStatus;
+    private assertStatusTransition;
+    private assertFrozenIdentityUnchanged;
+    private serializeFrozenSnapshot;
+    private static parseStringArray;
+    private static coerceDate;
+}
+export default AttributionPolicy;
+//# sourceMappingURL=AttributionPolicy.d.ts.map