@happyvertical/smrt-sales 0.40.9 → 0.40.11

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

@@ -0,0 +1,29 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { ReferralClickOperation } from '../models/ReferralClickOperation.js';
+export interface ClaimReferralClickOperationInput {
+    operationId: string;
+    tenantId: string | null;
+    keyHash: string;
+    linkId: string;
+    touchId: string;
+    intentHash: string;
+    callerEvidenceHash: string;
+    requestedOccurredAt: string;
+}
+export interface ClaimReferralClickOperationResult {
+    operation: ReferralClickOperation | null;
+    claimed: boolean;
+}
+export declare class ReferralClickOperationCollection extends SmrtCollection<ReferralClickOperation> {
+    static readonly _itemClass: typeof ReferralClickOperation;
+    /** Tenant-filtered lookup; a foreign operation payload remains invisible. */
+    findByOperationId(operationId: string): Promise<ReferralClickOperation | null>;
+    /**
+     * Claim the deterministic operation UUID without changing a winner.
+     * Must run in the transaction that creates the touch and increments the
+     * link counter.
+     */
+    claim(input: ClaimReferralClickOperationInput): Promise<ClaimReferralClickOperationResult>;
+}
+export default ReferralClickOperationCollection;
+//# sourceMappingURL=ReferralClickOperationCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralClickOperationCollection.d.ts","sourceRoot":"","sources":["../../../src/referrals/collections/ReferralClickOperationCollection.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAE7E,MAAM,WAAW,gCAAgC;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,iCAAiC;IAChD,SAAS,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,gCAAiC,SAAQ,cAAc,CAAC,sBAAsB,CAAC;IAC1F,MAAM,CAAC,QAAQ,CAAC,UAAU,gCAA0B;IAEpD,6EAA6E;IACvE,iBAAiB,CACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAIzC;;;;OAIG;IACG,KAAK,CACT,KAAK,EAAE,gCAAgC,GACtC,OAAO,CAAC,iCAAiC,CAAC;CA0B9C;AAED,eAAe,gCAAgC,CAAC"}

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

@@ -7,6 +7,10 @@ export declare const REFERRAL_CODE_LENGTH = 10;
 export declare const REFERRAL_CODE_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
 /** Attempts before {@link ReferralLinkCollection.createWithUniqueCode} gives up. */
 export declare const MAX_CODE_GENERATION_ATTEMPTS = 5;
+/** Default UTF-8 byte ceiling for the exact persisted click evidence JSON. */
+export declare const DEFAULT_REFERRAL_CLICK_EVIDENCE_MAX_BYTES = 4096;
+/** Maximum UTF-8 size of a caller-supplied replay key. */
+export declare const MAX_REFERRAL_CLICK_IDEMPOTENCY_KEY_BYTES = 256;
 /**
  * Generate a crypto-random share code: {@link REFERRAL_CODE_LENGTH}
  * characters drawn uniformly from {@link REFERRAL_CODE_ALPHABET} via
@@ -40,12 +44,33 @@ export interface RecordClickResult {
     link: ReferralLink | null;
     touch: ReferralTouch | null;
     refused?: RecordClickRefusal;
+    /** Stable key used for a successful click (generated when omitted). */
+    idempotencyKey?: string;
+    /** `true` when this call returned the already-committed touch. */
+    replayed?: boolean;
 }
 /** Input for {@link ReferralLinkCollection.recordClick}. */
 export interface RecordClickInput {
     code: string;
-    /** Extra evidence merged into the touch's evidence JSON (UA, IP hash, …). */
+    /**
+     * Stable caller replay key. Retries must reuse the exact value. When
+     * omitted, Sales generates a unique one-shot UUID for backward
+     * compatibility and returns it in the successful result. Supplied keys
+     * must be well-formed Unicode and at most 256 UTF-8 bytes.
+     */
+    idempotencyKey?: string;
+    /**
+     * Extra evidence merged into the touch JSON (UA, IP hash, …). Sales owns
+     * and overwrites the reserved `code`, `linkId`, and `targetUrl` keys.
+     */
     evidence?: Record<string, unknown>;
+    /**
+     * Creation-time UTF-8 byte ceiling for the FINAL persisted JSON envelope,
+     * including Sales-owned `code`, `linkId`, and `targetUrl`. Defaults to
+     * {@link DEFAULT_REFERRAL_CLICK_EVIDENCE_MAX_BYTES}; an exact committed
+     * replay does not reapply a later invocation's ceiling.
+     */
+    maxEvidenceBytes?: number;
     /** When the click occurred; defaults to now. */
     occurredAt?: Date;
     /**
@@ -58,6 +83,22 @@ export interface RecordClickInput {
     subjectKind?: string;
     subjectId?: string;
 }
+export type ReferralClickReplayMismatchField = 'idempotencyKey' | 'tenantId' | 'code' | 'linkId' | 'targetUrl' | 'referrerId' | 'programId' | 'subjectKind' | 'subjectId' | 'occurredAt' | 'evidence' | 'intent';
+/** Typed fail-closed result for a replay key reused with another click. */
+export declare class ReferralClickReplayConflictError extends Error {
+    readonly idempotencyKey: string;
+    readonly mismatches: readonly ReferralClickReplayMismatchField[];
+    readonly code: "REFERRAL_CLICK_REPLAY_CONFLICT";
+    constructor(idempotencyKey: string, mismatches: readonly ReferralClickReplayMismatchField[]);
+}
+export type ReferralClickValidationReason = 'invalid_idempotency_key' | 'invalid_occurred_at' | 'invalid_evidence' | 'invalid_max_evidence_bytes' | 'evidence_too_large' | 'transaction_unavailable' | 'operation_link_missing' | 'operation_touch_missing' | 'link_update_conflict';
+/** Actionable validation/integrity error raised without a partial click. */
+export declare class ReferralClickValidationError extends Error {
+    readonly reason: ReferralClickValidationReason;
+    readonly details?: Readonly<Record<string, number | string>> | undefined;
+    readonly code: "REFERRAL_CLICK_VALIDATION_ERROR";
+    constructor(reason: ReferralClickValidationReason, message: string, details?: Readonly<Record<string, number | string>> | undefined);
+}
 export declare class ReferralLinkCollection extends SmrtCollection<ReferralLink> {
     static readonly _itemClass: typeof ReferralLink;
     /** All links for a referrer, newest first. */
@@ -79,10 +120,16 @@ export declare class ReferralLinkCollection extends SmrtCollection<ReferralLink>
      */
     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.
+     * Record a click on a share code. A private operation fence, immutable
+     * ReferralTouch, and {@link ReferralLink.clickCount} increment commit in
+     * one supported database transaction. An exact `idempotencyKey` replay
+     * returns the original touch without another increment; changed immutable
+     * intent raises {@link ReferralClickReplayConflictError}.
+     *
+     * Evidence is canonicalized, Sales-owned `code`/`linkId`/`targetUrl` fields
+     * are applied, and the UTF-8 bytes of that exact persisted JSON are checked
+     * before any write. The default bound is
+     * {@link DEFAULT_REFERRAL_CLICK_EVIDENCE_MAX_BYTES}.
      *
      * Refusals return a typed result instead of throwing (clicks arrive from
      * the edge — an unknown or disabled code is an expected outcome, not an
@@ -91,6 +138,10 @@ export declare class ReferralLinkCollection extends SmrtCollection<ReferralLink>
      * returned, nothing is written).
      */
     recordClick(input: RecordClickInput): Promise<RecordClickResult>;
+    /** Rebind public result models to the caller's database after commit. */
+    private rehydrateRecordClickResult;
+    private recordClickInTransaction;
+    private replayClick;
 }
 export default ReferralLinkCollection;
 //# sourceMappingURL=ReferralLinkCollection.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"ReferralLinkCollection.d.ts","sourceRoot":"","sources":["../../../src/referrals/collections/ReferralLinkCollection.ts"],"names":[],"mappings":"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"}

package/dist/referrals/index.d.ts

@@ -17,7 +17,7 @@ export { AttributionExceptionCollection } from './collections/AttributionExcepti
 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 { type CreateReferralLinkInput, DEFAULT_REFERRAL_CLICK_EVIDENCE_MAX_BYTES, generateReferralCode, MAX_CODE_GENERATION_ATTEMPTS, MAX_REFERRAL_CLICK_IDEMPOTENCY_KEY_BYTES, REFERRAL_CODE_ALPHABET, REFERRAL_CODE_LENGTH, type RecordClickInput, type RecordClickRefusal, type RecordClickResult, ReferralClickReplayConflictError, type ReferralClickReplayMismatchField, ReferralClickValidationError, type ReferralClickValidationReason, 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';

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

@@ -1 +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,mCAAmC,EACxC,8BAA8B,EAC9B,iCAAiC,EACjC,KAAK,qCAAqC,EAC1C,KAAK,sCAAsC,GAC5C,MAAM,iDAAiD,CAAC;AACzD,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"}
+{"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,yCAAyC,EACzC,oBAAoB,EACpB,4BAA4B,EAC5B,wCAAwC,EACxC,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,gCAAgC,EAChC,KAAK,gCAAgC,EACrC,4BAA4B,EAC5B,KAAK,6BAA6B,EAClC,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,mCAAmC,EACxC,8BAA8B,EAC9B,iCAAiC,EACjC,KAAK,qCAAqC,EAC1C,KAAK,sCAAsC,GAC5C,MAAM,iDAAiD,CAAC;AACzD,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/ReferralClickOperation.d.ts

@@ -0,0 +1,39 @@
+import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+interface ReferralClickOperationOptions extends SmrtObjectOptions {
+    tenantId?: string | null;
+    keyHash?: string;
+    linkId?: string;
+    touchId?: string;
+    intentHash?: string;
+    callerEvidenceHash?: string;
+    requestedOccurredAt?: string;
+}
+/**
+ * One globally unique caller replay key mapped to its immutable click touch.
+ *
+ * The deterministic primary UUID is derived from the caller key. The full
+ * SHA-256 hash is retained to fail closed even if two keys ever collide in the
+ * truncated UUID namespace. This is package-owned orchestration state: it has
+ * no generated API, MCP, or CLI surface.
+ */
+export declare class ReferralClickOperation extends SmrtObject {
+    /** Same tenant owner as the ReferralLink and ReferralTouch. */
+    tenantId: string | null;
+    /** Full SHA-256 of the exact caller replay key. */
+    keyHash: string;
+    /** Link whose counter this operation increments. */
+    linkId: string;
+    /** Immutable touch created by this operation in the same transaction. */
+    touchId: string;
+    /** Hash of the normalized link, attribution, timestamp, and evidence intent. */
+    intentHash: string;
+    /** Hash of caller evidence before Sales-owned envelope fields are applied. */
+    callerEvidenceHash: string;
+    /** ISO instant supplied by the caller, or empty when recordClick chose now. */
+    requestedOccurredAt: string;
+    constructor(options?: ReferralClickOperationOptions);
+    /** Keep the TEXT replay marker a string when adapters parse `*_at`. */
+    initialize(): Promise<this>;
+}
+export default ReferralClickOperation;
+//# sourceMappingURL=ReferralClickOperation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferralClickOperation.d.ts","sourceRoot":"","sources":["../../../src/referrals/models/ReferralClickOperation.ts"],"names":[],"mappings":"AAAA,qEAAqE;AAErE,OAAO,EAEL,UAAU,EACV,KAAK,iBAAiB,EAEvB,MAAM,0BAA0B,CAAC;AAGlC,UAAU,6BAA8B,SAAQ,iBAAiB;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,qBAEa,sBAAuB,SAAQ,UAAU;IACpD,+DAA+D;IAE/D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,mDAAmD;IAEnD,OAAO,EAAG,MAAM,CAAC;IAEjB,oDAAoD;IAEpD,MAAM,EAAG,MAAM,CAAC;IAEhB,yEAAyE;IAIzE,OAAO,EAAG,MAAM,CAAC;IAEjB,gFAAgF;IAEhF,UAAU,EAAG,MAAM,CAAC;IAEpB,8EAA8E;IAE9E,kBAAkB,EAAG,MAAM,CAAC;IAE5B,+EAA+E;IAE/E,mBAAmB,EAAG,MAAM,CAAC;gBAEjB,OAAO,GAAE,6BAAkC;IAavD,uEAAuE;IACxD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAM3C;AAED,eAAe,sBAAsB,CAAC"}

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

@@ -14,8 +14,9 @@ export declare function assertHttpTargetUrl(targetUrl: string): void;
  * 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
+ * `ReferralLinkCollection.recordClick()`, which atomically increments
+ * {@link clickCount} and writes one immutable, replay-keyed `ReferralTouch`
+ * evidence row after enforcing the final UTF-8 evidence bound; disabled links
  * refuse clicks.
  */
 export declare class ReferralLink extends SmrtObject {

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

@@ -1 +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"}
+{"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;;;;;;;;;;;;GAYG;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.js

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