@happyvertical/smrt-sales 0.40.9 → 0.40.10

package/dist/chunks/{__smrt-register__-D08SaNJE.js.map → __smrt-register__-CZE4Gm8_.js.map}

@@ -1 +1 @@
-{"version":3,"file":"__smrt-register__-D08SaNJE.js","names":[],"sources":["../../src/__smrt-register__.ts"],"sourcesContent":["import { ObjectRegistry } from '@happyvertical/smrt-core';\n\nObjectRegistry.registerPackageManifest(\n  new URL('./manifest.json', import.meta.url),\n);\n"],"mappings":""}
+{"version":3,"file":"__smrt-register__-CZE4Gm8_.js","names":[],"sources":["../../src/__smrt-register__.ts"],"sourcesContent":["import { ObjectRegistry } from '@happyvertical/smrt-core';\n\nObjectRegistry.registerPackageManifest(\n  new URL('./manifest.json', import.meta.url),\n);\n"],"mappings":""}

package/dist/chunks/{referrals-BXqD65KR.js → referrals-CJUOZxpa.js}

@@ -1,14 +1,14 @@
 import { P as CommissionCollection, i as CommissionCalculationService, y as CommissionPlanCollection } from "./commissions-CelWwvjZ.js";
 import { SmrtCollection, SmrtObject, crossPackageRef, field, foreignKey, smrt } from "@happyvertical/smrt-core";
 import { TenantScoped, requireTenantId, tenantId } from "@happyvertical/smrt-tenancy";
-import { randomBytes, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 //#region src/referrals/models/AttributionException.ts
-var __defProp$8 = Object.defineProperty;
-var __getOwnPropDesc$8 = Object.getOwnPropertyDescriptor;
-var __decorateClass$8 = (decorators, target, key, kind) => {
-	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$8(target, key) : target;
+var __defProp$9 = Object.defineProperty;
+var __getOwnPropDesc$9 = Object.getOwnPropertyDescriptor;
+var __decorateClass$9 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$9(target, key) : target;
 	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-	if (kind && result) __defProp$8(target, key, result);
+	if (kind && result) __defProp$9(target, key, result);
 	return result;
 };
 var AttributionException = class extends SmrtObject {
@@ -146,12 +146,12 @@ var AttributionException = class extends SmrtObject {
 		return null;
 	}
 };
-__decorateClass$8([tenantId({ nullable: true })], AttributionException.prototype, "tenantId", 2);
-__decorateClass$8([field({ required: true })], AttributionException.prototype, "targetKind", 2);
-__decorateClass$8([field({ required: true })], AttributionException.prototype, "targetId", 2);
-__decorateClass$8([foreignKey("ReferralProgram")], AttributionException.prototype, "programId", 2);
-__decorateClass$8([crossPackageRef("@happyvertical/smrt-profiles:Profile")], AttributionException.prototype, "resolvedByProfileId", 2);
-AttributionException = __decorateClass$8([TenantScoped({ mode: "optional" }), smrt({
+__decorateClass$9([tenantId({ nullable: true })], AttributionException.prototype, "tenantId", 2);
+__decorateClass$9([field({ required: true })], AttributionException.prototype, "targetKind", 2);
+__decorateClass$9([field({ required: true })], AttributionException.prototype, "targetId", 2);
+__decorateClass$9([foreignKey("ReferralProgram")], AttributionException.prototype, "programId", 2);
+__decorateClass$9([crossPackageRef("@happyvertical/smrt-profiles:Profile")], AttributionException.prototype, "resolvedByProfileId", 2);
+AttributionException = __decorateClass$9([TenantScoped({ mode: "optional" }), smrt({
 	api: { include: ["list", "get"] },
 	mcp: { include: ["list", "get"] },
 	cli: false
@@ -247,12 +247,12 @@ var REFERRAL_AGREEMENT_STATUSES = [
 var REFERRAL_AGREEMENT_APPROVAL_MODES = ["manual", "auto"];
 //#endregion
 //#region src/referrals/models/AttributionPolicy.ts
-var __defProp$7 = Object.defineProperty;
-var __getOwnPropDesc$7 = Object.getOwnPropertyDescriptor;
-var __decorateClass$7 = (decorators, target, key, kind) => {
-	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$7(target, key) : target;
+var __defProp$8 = Object.defineProperty;
+var __getOwnPropDesc$8 = Object.getOwnPropertyDescriptor;
+var __decorateClass$8 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$8(target, key) : target;
 	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-	if (kind && result) __defProp$7(target, key, result);
+	if (kind && result) __defProp$8(target, key, result);
 	return result;
 };
 var POLICY_STATUS_TRANSITIONS = {
@@ -519,9 +519,9 @@ var AttributionPolicy = class extends SmrtObject {
 		return null;
 	}
 };
-__decorateClass$7([tenantId({ nullable: true })], AttributionPolicy.prototype, "tenantId", 2);
-__decorateClass$7([field({ required: true })], AttributionPolicy.prototype, "policyKey", 2);
-AttributionPolicy = __decorateClass$7([TenantScoped({ mode: "optional" }), smrt({
+__decorateClass$8([tenantId({ nullable: true })], AttributionPolicy.prototype, "tenantId", 2);
+__decorateClass$8([field({ required: true })], AttributionPolicy.prototype, "policyKey", 2);
+AttributionPolicy = __decorateClass$8([TenantScoped({ mode: "optional" }), smrt({
 	conflictColumns: [
 		"tenant_id",
 		"policy_key",
@@ -605,12 +605,12 @@ var AttributionPolicyCollection = class extends SmrtCollection {
 };
 //#endregion
 //#region src/referrals/models/ReferralAgreement.ts
-var __defProp$6 = Object.defineProperty;
-var __getOwnPropDesc$6 = Object.getOwnPropertyDescriptor;
-var __decorateClass$6 = (decorators, target, key, kind) => {
-	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$6(target, key) : target;
+var __defProp$7 = Object.defineProperty;
+var __getOwnPropDesc$7 = Object.getOwnPropertyDescriptor;
+var __decorateClass$7 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$7(target, key) : target;
 	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-	if (kind && result) __defProp$6(target, key, result);
+	if (kind && result) __defProp$7(target, key, result);
 	return result;
 };
 var AGREEMENT_STATUS_TRANSITIONS = {
@@ -847,12 +847,12 @@ var ReferralAgreement = class extends SmrtObject {
 		return null;
 	}
 };
-__decorateClass$6([tenantId({ nullable: true })], ReferralAgreement.prototype, "tenantId", 2);
-__decorateClass$6([foreignKey("Referrer", { required: true })], ReferralAgreement.prototype, "referrerId", 2);
-__decorateClass$6([foreignKey("ReferralProgram", { required: true })], ReferralAgreement.prototype, "programId", 2);
-__decorateClass$6([foreignKey("AgreementExecution")], ReferralAgreement.prototype, "executionId", 2);
-__decorateClass$6([foreignKey("ExecutedAgreement")], ReferralAgreement.prototype, "executedAgreementId", 2);
-ReferralAgreement = __decorateClass$6([TenantScoped({ mode: "optional" }), smrt({
+__decorateClass$7([tenantId({ nullable: true })], ReferralAgreement.prototype, "tenantId", 2);
+__decorateClass$7([foreignKey("Referrer", { required: true })], ReferralAgreement.prototype, "referrerId", 2);
+__decorateClass$7([foreignKey("ReferralProgram", { required: true })], ReferralAgreement.prototype, "programId", 2);
+__decorateClass$7([foreignKey("AgreementExecution")], ReferralAgreement.prototype, "executionId", 2);
+__decorateClass$7([foreignKey("ExecutedAgreement")], ReferralAgreement.prototype, "executedAgreementId", 2);
+ReferralAgreement = __decorateClass$7([TenantScoped({ mode: "optional" }), smrt({
 	conflictColumns: [
 		"referrer_id",
 		"program_id",
@@ -931,12 +931,12 @@ var ReferralAgreementCollection = class extends SmrtCollection {
 };
 //#endregion
 //#region src/referrals/models/Referral.ts
-var __defProp$5 = Object.defineProperty;
-var __getOwnPropDesc$5 = Object.getOwnPropertyDescriptor;
-var __decorateClass$5 = (decorators, target, key, kind) => {
-	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$5(target, key) : target;
+var __defProp$6 = Object.defineProperty;
+var __getOwnPropDesc$6 = Object.getOwnPropertyDescriptor;
+var __decorateClass$6 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$6(target, key) : target;
 	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-	if (kind && result) __defProp$5(target, key, result);
+	if (kind && result) __defProp$6(target, key, result);
 	return result;
 };
 var REFERRAL_STATUS_TRANSITIONS = {
@@ -1143,11 +1143,11 @@ var Referral = class extends SmrtObject {
 		return null;
 	}
 };
-__decorateClass$5([tenantId({ nullable: true })], Referral.prototype, "tenantId", 2);
-__decorateClass$5([foreignKey("Referrer", { required: true })], Referral.prototype, "referrerId", 2);
-__decorateClass$5([foreignKey("ReferralProgram", { required: true })], Referral.prototype, "programId", 2);
-__decorateClass$5([foreignKey("ReferralTouch")], Referral.prototype, "primaryTouchId", 2);
-Referral = __decorateClass$5([TenantScoped({ mode: "optional" }), smrt({
+__decorateClass$6([tenantId({ nullable: true })], Referral.prototype, "tenantId", 2);
+__decorateClass$6([foreignKey("Referrer", { required: true })], Referral.prototype, "referrerId", 2);
+__decorateClass$6([foreignKey("ReferralProgram", { required: true })], Referral.prototype, "programId", 2);
+__decorateClass$6([foreignKey("ReferralTouch")], Referral.prototype, "primaryTouchId", 2);
+Referral = __decorateClass$6([TenantScoped({ mode: "optional" }), smrt({
 	api: { include: [
 		"list",
 		"get",
@@ -1217,12 +1217,12 @@ var ReferralCollection = class extends SmrtCollection {
 };
 //#endregion
 //#region src/referrals/models/ReferralLink.ts
-var __defProp$4 = Object.defineProperty;
-var __getOwnPropDesc$4 = Object.getOwnPropertyDescriptor;
-var __decorateClass$4 = (decorators, target, key, kind) => {
-	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$4(target, key) : target;
+var __defProp$5 = Object.defineProperty;
+var __getOwnPropDesc$5 = Object.getOwnPropertyDescriptor;
+var __decorateClass$5 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$5(target, key) : target;
 	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-	if (kind && result) __defProp$4(target, key, result);
+	if (kind && result) __defProp$5(target, key, result);
 	return result;
 };
 function assertHttpTargetUrl(targetUrl) {
@@ -1308,11 +1308,11 @@ var ReferralLink = class extends SmrtObject {
 		return await super.save();
 	}
 };
-__decorateClass$4([tenantId({ nullable: true })], ReferralLink.prototype, "tenantId", 2);
-__decorateClass$4([foreignKey("Referrer", { required: true })], ReferralLink.prototype, "referrerId", 2);
-__decorateClass$4([foreignKey("ReferralProgram", { required: true })], ReferralLink.prototype, "programId", 2);
-__decorateClass$4([field({ required: true })], ReferralLink.prototype, "code", 2);
-ReferralLink = __decorateClass$4([TenantScoped({ mode: "optional" }), smrt({
+__decorateClass$5([tenantId({ nullable: true })], ReferralLink.prototype, "tenantId", 2);
+__decorateClass$5([foreignKey("Referrer", { required: true })], ReferralLink.prototype, "referrerId", 2);
+__decorateClass$5([foreignKey("ReferralProgram", { required: true })], ReferralLink.prototype, "programId", 2);
+__decorateClass$5([field({ required: true })], ReferralLink.prototype, "code", 2);
+ReferralLink = __decorateClass$5([TenantScoped({ mode: "optional" }), smrt({
 	conflictColumns: ["code"],
 	api: { include: [
 		"list",
@@ -1328,6 +1328,113 @@ ReferralLink = __decorateClass$4([TenantScoped({ mode: "optional" }), smrt({
 	cli: true
 })], ReferralLink);
 //#endregion
+//#region src/referrals/models/ReferralClickOperation.ts
+var __defProp$4 = Object.defineProperty;
+var __getOwnPropDesc$4 = Object.getOwnPropertyDescriptor;
+var __decorateClass$4 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$4(target, key) : target;
+	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+	if (kind && result) __defProp$4(target, key, result);
+	return result;
+};
+var ReferralClickOperation = class extends SmrtObject {
+	tenantId = null;
+	keyHash;
+	linkId;
+	touchId;
+	intentHash;
+	callerEvidenceHash;
+	requestedOccurredAt;
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.keyHash !== void 0) this.keyHash = options.keyHash;
+		if (options.linkId !== void 0) this.linkId = options.linkId;
+		if (options.touchId !== void 0) this.touchId = options.touchId;
+		if (options.intentHash !== void 0) this.intentHash = options.intentHash;
+		if (options.callerEvidenceHash !== void 0) this.callerEvidenceHash = options.callerEvidenceHash;
+		if (options.requestedOccurredAt !== void 0) this.requestedOccurredAt = options.requestedOccurredAt;
+	}
+	/** Keep the TEXT replay marker a string when adapters parse `*_at`. */
+	async initialize() {
+		await super.initialize();
+		const value = this.requestedOccurredAt;
+		if (value instanceof Date) this.requestedOccurredAt = value.toISOString();
+		return this;
+	}
+};
+__decorateClass$4([tenantId({ nullable: true })], ReferralClickOperation.prototype, "tenantId", 2);
+__decorateClass$4([field({
+	required: true,
+	readonly: true
+})], ReferralClickOperation.prototype, "keyHash", 2);
+__decorateClass$4([field({
+	sqlType: "UUID",
+	required: true,
+	readonly: true,
+	indexed: true
+})], ReferralClickOperation.prototype, "linkId", 2);
+__decorateClass$4([field({
+	sqlType: "UUID",
+	required: true,
+	readonly: true,
+	indexed: true
+})], ReferralClickOperation.prototype, "touchId", 2);
+__decorateClass$4([field({
+	required: true,
+	readonly: true
+})], ReferralClickOperation.prototype, "intentHash", 2);
+__decorateClass$4([field({
+	required: true,
+	readonly: true
+})], ReferralClickOperation.prototype, "callerEvidenceHash", 2);
+__decorateClass$4([field({
+	required: true,
+	readonly: true
+})], ReferralClickOperation.prototype, "requestedOccurredAt", 2);
+ReferralClickOperation = __decorateClass$4([TenantScoped({ mode: "optional" }), smrt({
+	api: false,
+	mcp: false,
+	cli: false
+})], ReferralClickOperation);
+//#endregion
+//#region src/referrals/collections/ReferralClickOperationCollection.ts
+var ReferralClickOperationCollection = class extends SmrtCollection {
+	static _itemClass = ReferralClickOperation;
+	/** Tenant-filtered lookup; a foreign operation payload remains invisible. */
+	async findByOperationId(operationId) {
+		return await this.get({ id: operationId }, { cache: false });
+	}
+	/**
+	* Claim the deterministic operation UUID without changing a winner.
+	* Must run in the transaction that creates the touch and increments the
+	* link counter.
+	*/
+	async claim(input) {
+		const inserted = await this.query(`INSERT INTO ${this.tableName} (
+         id, slug, context, tenant_id, key_hash, link_id, touch_id,
+         intent_hash, caller_evidence_hash, requested_occurred_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT (id) DO NOTHING
+       RETURNING id`, [
+			input.operationId,
+			input.operationId,
+			"",
+			input.tenantId,
+			input.keyHash,
+			input.linkId,
+			input.touchId,
+			input.intentHash,
+			input.callerEvidenceHash,
+			input.requestedOccurredAt
+		], { allowRawOnTenantScoped: true });
+		return {
+			operation: await this.findByOperationId(input.operationId),
+			claimed: inserted.length === 1
+		};
+	}
+};
+//#endregion
 //#region src/referrals/models/ReferralTouch.ts
 var __defProp$3 = Object.defineProperty;
 var __getOwnPropDesc$3 = Object.getOwnPropertyDescriptor;
@@ -1487,6 +1594,8 @@ var ReferralTouchCollection = class extends SmrtCollection {
 var REFERRAL_CODE_LENGTH = 10;
 var REFERRAL_CODE_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
 var MAX_CODE_GENERATION_ATTEMPTS = 5;
+var DEFAULT_REFERRAL_CLICK_EVIDENCE_MAX_BYTES = 4096;
+var MAX_REFERRAL_CLICK_IDEMPOTENCY_KEY_BYTES = 256;
 function generateReferralCode() {
 	const alphabetSize = 36;
 	const rejectionBound = 256 - 256 % alphabetSize;
@@ -1501,7 +1610,29 @@ function generateReferralCode() {
 	}
 	return code;
 }
-var ReferralLinkCollection = class extends SmrtCollection {
+var ReferralClickReplayConflictError = class extends Error {
+	constructor(idempotencyKey, mismatches) {
+		super(`Referral click idempotency key '${idempotencyKey}' was already used with different ${mismatches.length === 1 ? "intent field" : "intent fields"}: ` + mismatches.join(", "));
+		this.idempotencyKey = idempotencyKey;
+		this.mismatches = mismatches;
+		this.name = "ReferralClickReplayConflictError";
+	}
+	idempotencyKey;
+	mismatches;
+	code = "REFERRAL_CLICK_REPLAY_CONFLICT";
+};
+var ReferralClickValidationError = class extends Error {
+	constructor(reason, message, details) {
+		super(message);
+		this.reason = reason;
+		this.details = details;
+		this.name = "ReferralClickValidationError";
+	}
+	reason;
+	details;
+	code = "REFERRAL_CLICK_VALIDATION_ERROR";
+};
+var ReferralLinkCollection = class ReferralLinkCollection extends SmrtCollection {
 	static _itemClass = ReferralLink;
 	/** All links for a referrer, newest first. */
 	async findByReferrer(referrerId) {
@@ -1552,10 +1683,16 @@ var ReferralLinkCollection = class extends SmrtCollection {
 		throw new Error(`ReferralLinkCollection.createWithUniqueCode: could not mint a unique code after 5 attempts \u2014 the code generator is returning colliding codes`);
 	}
 	/**
-	* 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
@@ -1564,7 +1701,41 @@ var ReferralLinkCollection = class extends SmrtCollection {
 	* returned, nothing is written).
 	*/
 	async recordClick(input) {
-		const link = await this.findByCode(input.code);
+		const request = canonicalizeClickRequest(input);
+		const db = this.db;
+		if (typeof db.transaction !== "function") throw new ReferralClickValidationError("transaction_unavailable", "Referral click recording requires a transaction-capable database adapter");
+		const transactionResult = await db.transaction(async (tx) => {
+			const deps = {
+				links: await ReferralLinkCollection.create({ db: tx }),
+				touches: await ReferralTouchCollection.create({ db: tx }),
+				operations: await ReferralClickOperationCollection.create({ db: tx })
+			};
+			return await this.recordClickInTransaction(deps, request);
+		});
+		return await this.rehydrateRecordClickResult(transactionResult);
+	}
+	/** Rebind public result models to the caller's database after commit. */
+	async rehydrateRecordClickResult(result) {
+		let link = null;
+		if (result.link?.id) {
+			link = await this.get({ id: result.link.id }, { cache: false });
+			if (!link) throw new ReferralClickValidationError("operation_link_missing", "Committed referral click result has no visible link");
+		}
+		let touch = null;
+		if (result.touch?.id) {
+			touch = await (await ReferralTouchCollection.create({ db: this.db })).get({ id: result.touch.id }, { cache: false });
+			if (!touch) throw new ReferralClickValidationError("operation_touch_missing", "Committed referral click result has no visible touch");
+		}
+		return {
+			...result,
+			link,
+			touch
+		};
+	}
+	async recordClickInTransaction(deps, request) {
+		const existingOperation = await deps.operations.findByOperationId(request.operationId);
+		if (existingOperation) return await this.replayClick(deps, existingOperation, request);
+		const link = await deps.links.findByCode(request.normalizedCode);
 		if (!link) return {
 			link: null,
 			touch: null,
@@ -1575,31 +1746,215 @@ var ReferralLinkCollection = class extends SmrtCollection {
 			touch: null,
 			refused: "link_disabled"
 		};
-		const occurredAt = input.occurredAt ?? /* @__PURE__ */ new Date();
-		const touch = await (await ReferralTouchCollection.create({ db: this.db })).create({
+		if (!link.id) throw new ReferralClickValidationError("link_update_conflict", "Referral click link is missing its persisted identifier");
+		const intent = buildClickIntent(link, request);
+		assertEvidenceBound(intent.finalEvidence, request.maxEvidenceBytes);
+		const touchId = randomUUID();
+		const claimed = await deps.operations.claim({
+			operationId: request.operationId,
 			tenantId: link.tenantId,
-			linkId: link.id ?? "",
+			keyHash: request.keyHash,
+			linkId: link.id,
+			touchId,
+			intentHash: intent.intentHash,
+			callerEvidenceHash: request.callerEvidenceHash,
+			requestedOccurredAt: request.requestedOccurredAt
+		});
+		if (!claimed.operation) throw new ReferralClickReplayConflictError(request.idempotencyKey, ["tenantId"]);
+		if (!claimed.claimed) return await this.replayClick(deps, claimed.operation, request);
+		const touch = await deps.touches.create({
+			id: touchId,
+			tenantId: link.tenantId,
+			linkId: link.id,
 			code: link.code,
 			referrerId: link.referrerId,
 			programId: link.programId,
 			kind: "click",
-			subjectKind: input.subjectKind ?? "",
-			subjectId: input.subjectId ?? "",
-			occurredAt,
-			evidence: JSON.stringify({
-				...input.evidence ?? {},
-				code: link.code,
-				linkId: link.id ?? "",
-				targetUrl: link.targetUrl
-			})
+			subjectKind: request.subjectKind,
+			subjectId: request.subjectId,
+			occurredAt: request.occurredAt ?? /* @__PURE__ */ new Date(),
+			evidence: intent.finalEvidence
 		});
-		await this.db.execute`UPDATE referral_links SET click_count = click_count + 1 WHERE id = ${link.id ?? ""}`;
+		if ((await deps.links.query(`UPDATE ${deps.links.tableName}
+       SET click_count = click_count + 1
+       WHERE id = ?
+         AND status = 'active'
+         AND COALESCE(CAST(tenant_id AS TEXT), '') = ?
+       RETURNING id`, [link.id, link.tenantId ?? ""], { allowRawOnTenantScoped: true })).length !== 1) throw new ReferralClickValidationError("link_update_conflict", "Referral link changed or was disabled while its click was being recorded; the transaction was rolled back");
+		const fresh = await deps.links.get({ id: link.id }, { cache: false });
+		if (!fresh || !sameClickLinkSnapshot(link, fresh)) throw new ReferralClickValidationError("link_update_conflict", "Referral link attribution changed while its click was being recorded; the transaction was rolled back");
 		return {
-			link: await this.get({ id: link.id }) ?? link,
-			touch
+			link: fresh,
+			touch,
+			idempotencyKey: request.idempotencyKey,
+			replayed: false
+		};
+	}
+	async replayClick(deps, operation, request) {
+		if (operation.keyHash !== request.keyHash) throw new ReferralClickReplayConflictError(request.idempotencyKey, ["idempotencyKey"]);
+		const link = await deps.links.get({ id: operation.linkId }, { cache: false });
+		if (!link) throw new ReferralClickValidationError("operation_link_missing", `Referral click operation '${request.idempotencyKey}' has no visible link`);
+		const touch = await deps.touches.get({ id: operation.touchId }, { cache: false });
+		if (!touch) throw new ReferralClickValidationError("operation_touch_missing", `Referral click operation '${request.idempotencyKey}' has no visible touch`);
+		const mismatches = collectReplayMismatches(operation, link, touch, request);
+		if (mismatches.length > 0) throw new ReferralClickReplayConflictError(request.idempotencyKey, mismatches);
+		return {
+			link,
+			touch,
+			idempotencyKey: request.idempotencyKey,
+			replayed: true
 		};
 	}
 };
+function canonicalizeClickRequest(input) {
+	const idempotencyKey = input.idempotencyKey ?? randomUUID();
+	if (typeof idempotencyKey !== "string" || idempotencyKey.length === 0 || idempotencyKey.trim() !== idempotencyKey || !isWellFormedUnicode(idempotencyKey) || utf8ByteLength(idempotencyKey) > 256) throw new ReferralClickValidationError("invalid_idempotency_key", `Referral click idempotencyKey must be non-empty, unpadded, well-formed Unicode, and at most 256 UTF-8 bytes`);
+	const maxEvidenceBytes = input.maxEvidenceBytes ?? 4096;
+	if (!Number.isSafeInteger(maxEvidenceBytes) || maxEvidenceBytes <= 0) throw new ReferralClickValidationError("invalid_max_evidence_bytes", "Referral click maxEvidenceBytes must be a positive safe integer");
+	let requestedOccurredAt = "";
+	let occurredAt = null;
+	if (input.occurredAt !== void 0) {
+		if (!(input.occurredAt instanceof Date) || Number.isNaN(input.occurredAt.getTime())) throw new ReferralClickValidationError("invalid_occurred_at", "Referral click occurredAt must be a valid Date");
+		occurredAt = new Date(input.occurredAt.getTime());
+		requestedOccurredAt = occurredAt.toISOString();
+	}
+	const callerEvidence = canonicalizeCallerEvidence(input.evidence ?? {});
+	const callerEvidenceJson = stableJson(callerEvidence);
+	const keyDigest = createHash("sha256").update(idempotencyKey, "utf8").digest();
+	return {
+		idempotencyKey,
+		operationId: uuidFromDigest(keyDigest),
+		keyHash: keyDigest.toString("hex"),
+		normalizedCode: String(input.code ?? "").trim().toLowerCase(),
+		callerEvidence,
+		callerEvidenceHash: hashText(callerEvidenceJson),
+		requestedOccurredAt,
+		occurredAt,
+		subjectKind: input.subjectKind ?? "",
+		subjectId: input.subjectId ?? "",
+		maxEvidenceBytes
+	};
+}
+function canonicalizeCallerEvidence(evidence) {
+	try {
+		const serialized = JSON.stringify(evidence);
+		if (serialized === void 0) throw new TypeError("evidence is undefined");
+		const parsed = JSON.parse(serialized);
+		if (!isPlainObject(parsed)) throw new TypeError("evidence must be a JSON object");
+		return JSON.parse(stableJson(parsed));
+	} catch (error) {
+		throw new ReferralClickValidationError("invalid_evidence", `Referral click evidence must be a JSON-serializable object: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function buildClickIntent(link, request) {
+	const finalEvidence = stableJson(Object.assign(/* @__PURE__ */ Object.create(null), request.callerEvidence, {
+		code: link.code,
+		linkId: link.id ?? "",
+		targetUrl: link.targetUrl
+	}));
+	return {
+		finalEvidence,
+		intentHash: hashText(stableJson({
+			tenantId: link.tenantId,
+			linkId: link.id ?? "",
+			code: link.code,
+			targetUrl: link.targetUrl,
+			referrerId: link.referrerId,
+			programId: link.programId,
+			subjectKind: request.subjectKind,
+			subjectId: request.subjectId,
+			requestedOccurredAt: request.requestedOccurredAt,
+			callerEvidenceHash: request.callerEvidenceHash,
+			finalEvidence
+		}))
+	};
+}
+function collectReplayMismatches(operation, link, touch, request) {
+	const mismatches = /* @__PURE__ */ new Set();
+	if (request.normalizedCode !== touch.code) mismatches.add("code");
+	if (operation.linkId !== link.id || touch.linkId !== link.id || operation.touchId !== touch.id) mismatches.add("linkId");
+	if (operation.tenantId !== touch.tenantId) mismatches.add("tenantId");
+	if (touch.subjectKind !== request.subjectKind) mismatches.add("subjectKind");
+	if (touch.subjectId !== request.subjectId) mismatches.add("subjectId");
+	if (normalizePersistedInstant(operation.requestedOccurredAt) !== request.requestedOccurredAt) mismatches.add("occurredAt");
+	if (operation.callerEvidenceHash !== request.callerEvidenceHash) mismatches.add("evidence");
+	const persisted = touch.getEvidence();
+	if (persisted.code !== touch.code) mismatches.add("code");
+	if (persisted.linkId !== touch.linkId) mismatches.add("linkId");
+	if (operation.intentHash !== hashPersistedClickIntent(operation, touch, persisted.targetUrl) && mismatches.size === 0) mismatches.add("intent");
+	return [...mismatches];
+}
+function hashPersistedClickIntent(operation, touch, targetUrl) {
+	return hashText(stableJson({
+		tenantId: touch.tenantId,
+		linkId: touch.linkId,
+		code: touch.code,
+		targetUrl,
+		referrerId: touch.referrerId,
+		programId: touch.programId,
+		subjectKind: touch.subjectKind,
+		subjectId: touch.subjectId,
+		requestedOccurredAt: normalizePersistedInstant(operation.requestedOccurredAt),
+		callerEvidenceHash: operation.callerEvidenceHash,
+		finalEvidence: touch.evidence
+	}));
+}
+function assertEvidenceBound(evidence, maxBytes) {
+	const actualBytes = utf8ByteLength(evidence);
+	if (actualBytes > maxBytes) throw new ReferralClickValidationError("evidence_too_large", `Referral click final evidence is ${actualBytes} UTF-8 bytes and exceeds the ${maxBytes}-byte limit`, {
+		actualBytes,
+		maxBytes
+	});
+}
+function sameClickLinkSnapshot(left, right) {
+	return left.id === right.id && left.tenantId === right.tenantId && left.code === right.code && left.targetUrl === right.targetUrl && left.referrerId === right.referrerId && left.programId === right.programId;
+}
+function hashText(value) {
+	return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function normalizePersistedInstant(value) {
+	if (value instanceof Date) return value.toISOString();
+	return typeof value === "string" ? value : String(value ?? "");
+}
+function uuidFromDigest(digest) {
+	const bytes = Buffer.from(digest.subarray(0, 16));
+	bytes[6] = bytes[6] & 15 | 80;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = bytes.toString("hex");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function utf8ByteLength(value) {
+	return Buffer.byteLength(value, "utf8");
+}
+function isWellFormedUnicode(value) {
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code >= 55296 && code <= 56319) {
+			if (index + 1 >= value.length) return false;
+			const next = value.charCodeAt(index + 1);
+			if (next < 56320 || next > 57343) return false;
+			index += 1;
+		} else if (code >= 56320 && code <= 57343) return false;
+	}
+	return true;
+}
+function stableJson(value) {
+	return JSON.stringify(sortJsonValue(value));
+}
+function sortJsonValue(value) {
+	if (Array.isArray(value)) return value.map(sortJsonValue);
+	if (isPlainObject(value)) {
+		const sorted = /* @__PURE__ */ Object.create(null);
+		for (const key of Object.keys(value).sort()) sorted[key] = sortJsonValue(value[key]);
+		return sorted;
+	}
+	return value;
+}
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
 //#endregion
 //#region src/referrals/models/ReferralProgram.ts
 var __defProp$2 = Object.defineProperty;
@@ -2998,6 +3353,6 @@ var ReferralQualificationService = class ReferralQualificationService {
 	}
 };
 //#endregion
-export { ATTRIBUTION_CONFLICT_BEHAVIORS as A, REFERRAL_TOUCH_KINDS as B, ReferralCollection as C, AttributionPolicyCollection as D, ReferralAgreement as E, REFERRAL_AGREEMENT_APPROVAL_MODES as F, AttributionExceptionCollection as H, REFERRAL_AGREEMENT_STATUSES as I, REFERRAL_LINK_STATUSES as L, ATTRIBUTION_EXCEPTION_STATUSES as M, ATTRIBUTION_POLICY_STATUSES as N, AttributionPolicy as O, ATTRIBUTION_RESOLUTION_MODES as P, REFERRAL_PROGRAM_STATUSES as R, assertHttpTargetUrl as S, ReferralAgreementCollection as T, AttributionException as U, REFERRER_STATUSES as V, ReferralLinkCollection as _, ReferralAgreementExecutionService as a, ReferralTouch as b, ReferrerCollection as c, ReferralTermSnapshot as d, ReferralProgramCollection as f, REFERRAL_CODE_LENGTH as g, REFERRAL_CODE_ALPHABET as h, REFERRAL_AGREEMENT_SOURCE_KIND as i, ATTRIBUTION_CREDIT_MODES as j, validateAttributionPolicyTerms as k, Referrer as l, MAX_CODE_GENERATION_ATTEMPTS as m, REFERRAL_TERMS_SNAPSHOT_KIND as n, AttributionService as o, ReferralProgram as p, ReferralCommissionService as r, QualifiedReferralOverrideError as s, ReferralQualificationService as t, ReferralTermSnapshotCollection as u, generateReferralCode as v, Referral as w, ReferralLink as x, ReferralTouchCollection as y, REFERRAL_STATUSES as z };
+export { ReferralAgreement as A, REFERRAL_AGREEMENT_STATUSES as B, ReferralTouchCollection as C, ReferralCollection as D, assertHttpTargetUrl as E, ATTRIBUTION_CREDIT_MODES as F, REFERRER_STATUSES as G, REFERRAL_PROGRAM_STATUSES as H, ATTRIBUTION_EXCEPTION_STATUSES as I, AttributionExceptionCollection as K, ATTRIBUTION_POLICY_STATUSES as L, AttributionPolicy as M, validateAttributionPolicyTerms as N, Referral as O, ATTRIBUTION_CONFLICT_BEHAVIORS as P, ATTRIBUTION_RESOLUTION_MODES as R, generateReferralCode as S, ReferralLink as T, REFERRAL_STATUSES as U, REFERRAL_LINK_STATUSES as V, REFERRAL_TOUCH_KINDS as W, REFERRAL_CODE_ALPHABET as _, ReferralAgreementExecutionService as a, ReferralClickValidationError as b, ReferrerCollection as c, ReferralTermSnapshot as d, ReferralProgramCollection as f, MAX_REFERRAL_CLICK_IDEMPOTENCY_KEY_BYTES as g, MAX_CODE_GENERATION_ATTEMPTS as h, REFERRAL_AGREEMENT_SOURCE_KIND as i, AttributionPolicyCollection as j, ReferralAgreementCollection as k, Referrer as l, DEFAULT_REFERRAL_CLICK_EVIDENCE_MAX_BYTES as m, REFERRAL_TERMS_SNAPSHOT_KIND as n, AttributionService as o, ReferralProgram as p, AttributionException as q, ReferralCommissionService as r, QualifiedReferralOverrideError as s, ReferralQualificationService as t, ReferralTermSnapshotCollection as u, REFERRAL_CODE_LENGTH as v, ReferralTouch as w, ReferralLinkCollection as x, ReferralClickReplayConflictError as y, REFERRAL_AGREEMENT_APPROVAL_MODES as z };
 
-//# sourceMappingURL=referrals-BXqD65KR.js.map
+//# sourceMappingURL=referrals-CJUOZxpa.js.map