@happyvertical/smrt-sales 0.40.0 → 0.40.2

package/dist/chunks/{referrals-CzkrPeKv.js → referrals-cYYg4YZw.js}

@@ -1,6 +1,6 @@
 import { g as CommissionPlanCollection, i as CommissionCalculationService, j as CommissionCollection } from "./commissions-pI_MmBxN.js";
 import { SmrtCollection, SmrtObject, crossPackageRef, field, foreignKey, smrt } from "@happyvertical/smrt-core";
-import { TenantScoped, tenantId } from "@happyvertical/smrt-tenancy";
+import { TenantScoped, requireTenantId, tenantId } from "@happyvertical/smrt-tenancy";
 import { randomBytes, randomUUID } from "node:crypto";
 //#region src/referrals/models/AttributionException.ts
 var __defProp$8 = Object.defineProperty;
@@ -657,17 +657,8 @@ var ReferralAgreement = class extends SmrtObject {
 	clearingDays = 0;
 	/** How earned commissions are approved downstream. */
 	approvalMode = "manual";
-	contractRef = "";
-	/** URL of the executed agreement artifact (e-signature PDF, …). */
-	executedArtifactUrl = "";
-	/** Content hash of the executed artifact for tamper evidence. */
-	executedArtifactHash = "";
-	/**
-	* Acceptance evidence as a JSON object string (click-through record, IP,
-	* timestamp, signer, …). Use
-	* {@link getAcceptanceEvidence}/{@link setAcceptanceEvidence}.
-	*/
-	acceptanceEvidence = "{}";
+	executionId = "";
+	executedAgreementId = "";
 	/**
 	* Free-form JSON object stored as a string. Use
 	* {@link getMetadata}/{@link setMetadata} instead of parsing manually.
@@ -686,10 +677,8 @@ var ReferralAgreement = class extends SmrtObject {
 		if (options.commissionPlanVersion !== void 0) this.commissionPlanVersion = options.commissionPlanVersion;
 		if (options.clearingDays !== void 0) this.clearingDays = options.clearingDays;
 		if (options.approvalMode !== void 0) this.approvalMode = options.approvalMode;
-		if (options.contractRef !== void 0) this.contractRef = options.contractRef;
-		if (options.executedArtifactUrl !== void 0) this.executedArtifactUrl = options.executedArtifactUrl;
-		if (options.executedArtifactHash !== void 0) this.executedArtifactHash = options.executedArtifactHash;
-		if (options.acceptanceEvidence !== void 0) this.acceptanceEvidence = options.acceptanceEvidence;
+		if (options.executionId !== void 0) this.executionId = options.executionId;
+		if (options.executedAgreementId !== void 0) this.executedAgreementId = options.executedAgreementId;
 		if (options.metadata !== void 0) this.metadata = options.metadata;
 	}
 	/**
@@ -702,7 +691,7 @@ var ReferralAgreement = class extends SmrtObject {
 		await super.initialize();
 		this.effectiveFrom = ReferralAgreement.coerceDate(this.effectiveFrom);
 		this.effectiveTo = ReferralAgreement.coerceDate(this.effectiveTo);
-		if (await this.isSaved()) {
+		if (this.isPersisted) {
 			loadedAgreementStatus.set(this, this.status);
 			if (this.status !== "draft") frozenAgreementSnapshot.set(this, this.serializeFrozenTerms());
 		}
@@ -724,20 +713,6 @@ var ReferralAgreement = class extends SmrtObject {
 		if (this.effectiveTo && at.getTime() > this.effectiveTo.getTime()) return false;
 		return true;
 	}
-	/** Parse {@link acceptanceEvidence}; returns `{}` on malformed content. */
-	getAcceptanceEvidence() {
-		if (!this.acceptanceEvidence) return {};
-		try {
-			const parsed = JSON.parse(this.acceptanceEvidence);
-			return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
-		} catch {
-			return {};
-		}
-	}
-	/** Serialize and store {@link acceptanceEvidence}. */
-	setAcceptanceEvidence(evidence) {
-		this.acceptanceEvidence = JSON.stringify(evidence ?? {});
-	}
 	/** Parse {@link metadata}; returns `{}` on malformed content. */
 	getMetadata() {
 		if (!this.metadata) return {};
@@ -760,8 +735,24 @@ var ReferralAgreement = class extends SmrtObject {
 	activate() {
 		if (this.status !== "draft") throw new Error(`ReferralAgreement ${this.referrerId}/${this.programId}@${this.version}: cannot activate from status '${this.status}'`);
 		if (!this.commissionPlanKey) throw new Error(`ReferralAgreement ${this.referrerId}/${this.programId}@${this.version}: commissionPlanKey is required to activate`);
+		if (!this.executionId || !this.executedAgreementId) throw new Error(`ReferralAgreement ${this.referrerId}/${this.programId}@${this.version}: AgreementExecution and immutable ExecutedAgreement evidence are required to activate`);
 		this.status = "active";
 	}
+	/** Bind the provider workflow to an unsigned draft. */
+	bindExecution(executionId) {
+		if (this.status !== "draft") throw new Error("Only draft ReferralAgreements can bind an execution");
+		if (!executionId) throw new Error("executionId is required");
+		if (this.executionId && this.executionId !== executionId) throw new Error("ReferralAgreement is already bound to another execution");
+		this.executionId = executionId;
+	}
+	/** Bind immutable completed evidence to an unsigned draft. */
+	bindExecutedAgreement(executedAgreementId) {
+		if (this.status !== "draft") throw new Error("Only draft ReferralAgreements can bind executed evidence");
+		if (!this.executionId) throw new Error("Bind the AgreementExecution before its executed evidence");
+		if (!executedAgreementId) throw new Error("executedAgreementId is required");
+		if (this.executedAgreementId && this.executedAgreementId !== executedAgreementId) throw new Error("ReferralAgreement is already bound to different executed evidence");
+		this.executedAgreementId = executedAgreementId;
+	}
 	/** Transition `active → superseded` (a newer version took over). */
 	supersede() {
 		if (this.status !== "active") throw new Error(`ReferralAgreement ${this.referrerId}/${this.programId}@${this.version}: cannot supersede from status '${this.status}'`);
@@ -788,7 +779,10 @@ var ReferralAgreement = class extends SmrtObject {
 		this.assertStatusTransition(prior);
 		this.assertFrozenTermsUnchanged();
 		await this.assertNaturalKeyNotTaken();
-		if (this.status === "active" && !this.commissionPlanKey) throw new Error(`ReferralAgreement ${this.referrerId}/${this.programId}@${this.version}: commissionPlanKey is required while active`);
+		if (this.status === "active") {
+			if (!this.commissionPlanKey) throw new Error(`ReferralAgreement ${this.referrerId}/${this.programId}@${this.version}: commissionPlanKey is required while active`);
+			if (!this.executionId || !this.executedAgreementId) throw new Error(`ReferralAgreement ${this.referrerId}/${this.programId}@${this.version}: AgreementExecution and ExecutedAgreement evidence are required while active`);
+		}
 		const result = await super.save();
 		loadedAgreementStatus.set(this, this.status);
 		if (this.status !== "draft" && !frozenAgreementSnapshot.has(this)) frozenAgreementSnapshot.set(this, this.serializeFrozenTerms());
@@ -838,7 +832,9 @@ var ReferralAgreement = class extends SmrtObject {
 			commissionPlanVersion: this.commissionPlanVersion,
 			clearingDays: this.clearingDays,
 			approvalMode: this.approvalMode,
-			effectiveFrom: this.effectiveFrom ? this.effectiveFrom.toISOString() : null
+			effectiveFrom: this.effectiveFrom ? this.effectiveFrom.toISOString() : null,
+			executionId: this.executionId,
+			executedAgreementId: this.executedAgreementId
 		});
 	}
 	static coerceDate(value) {
@@ -854,7 +850,8 @@ var ReferralAgreement = class extends SmrtObject {
 __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([crossPackageRef("@happyvertical/smrt-commerce:Contract")], ReferralAgreement.prototype, "contractRef", 2);
+__decorateClass$6([foreignKey("AgreementExecution")], ReferralAgreement.prototype, "executionId", 2);
+__decorateClass$6([foreignKey("ExecutedAgreement")], ReferralAgreement.prototype, "executedAgreementId", 2);
 ReferralAgreement = __decorateClass$6([TenantScoped({ mode: "optional" }), smrt({
 	conflictColumns: [
 		"referrer_id",
@@ -926,10 +923,8 @@ var ReferralAgreementCollection = class extends SmrtCollection {
 			approvalMode: changes.approvalMode ?? latest.approvalMode,
 			effectiveFrom: changes.effectiveFrom !== void 0 ? changes.effectiveFrom : latest.effectiveFrom,
 			effectiveTo: changes.effectiveTo !== void 0 ? changes.effectiveTo : latest.effectiveTo,
-			contractRef: changes.contractRef ?? latest.contractRef,
-			executedArtifactUrl: changes.executedArtifactUrl ?? latest.executedArtifactUrl,
-			executedArtifactHash: changes.executedArtifactHash ?? latest.executedArtifactHash,
-			acceptanceEvidence: changes.acceptanceEvidence !== void 0 ? JSON.stringify(changes.acceptanceEvidence) : latest.acceptanceEvidence,
+			executionId: "",
+			executedAgreementId: "",
 			metadata: changes.metadata !== void 0 ? JSON.stringify(changes.metadata) : latest.metadata
 		});
 	}
@@ -2516,6 +2511,134 @@ var AttributionService = class AttributionService {
 	}
 };
 //#endregion
+//#region src/referrals/services/ReferralAgreementExecutionService.ts
+var REFERRAL_AGREEMENT_SOURCE_KIND = "referral_agreement";
+var ReferralAgreementExecutionService = class {
+	constructor(deps) {
+		this.deps = deps;
+		this.now = deps.now ?? (() => /* @__PURE__ */ new Date());
+	}
+	deps;
+	now;
+	async requestSignature(input) {
+		this.assertTenant(input.tenantId);
+		const agreement = await this.requireAgreement(input.agreementId);
+		this.assertAgreementTenant(agreement, input.tenantId);
+		if (!agreement.id || agreement.status !== "draft") throw new Error("Only a persisted draft ReferralAgreement can be sent");
+		if (agreement.executedAgreementId) throw new Error("ReferralAgreement already has immutable executed evidence");
+		const prior = await this.findPriorActive(agreement);
+		const idempotencyKey = `${input.tenantId}:${REFERRAL_AGREEMENT_SOURCE_KIND}:${agreement.id}:v${agreement.version}`;
+		let result;
+		try {
+			result = await this.deps.executionService.createExecution({
+				tenantId: input.tenantId,
+				idempotencyKey,
+				sourceKind: REFERRAL_AGREEMENT_SOURCE_KIND,
+				sourceId: agreement.id,
+				sourceVersion: agreement.version,
+				title: input.title ?? `Referral Agreement v${agreement.version}`,
+				document: input.document,
+				signers: input.signers,
+				...input.message ? { message: input.message } : {},
+				...input.signingOrder !== void 0 ? { signingOrder: input.signingOrder } : {},
+				...input.expiresInDays !== void 0 ? { expiresInDays: input.expiresInDays } : {},
+				...input.providerAccountRef ? { providerAccountRef: input.providerAccountRef } : {},
+				...input.credentialRef ? { credentialRef: input.credentialRef } : {},
+				effectiveFrom: agreement.effectiveFrom,
+				effectiveTo: agreement.effectiveTo,
+				supersedesExecutedAgreementId: prior?.executedAgreementId ?? "",
+				metadata: {
+					referralAgreementId: agreement.id,
+					referralAgreementVersion: String(agreement.version),
+					referrerId: agreement.referrerId,
+					programId: agreement.programId
+				},
+				...input.signal ? { signal: input.signal } : {}
+			});
+		} catch (error) {
+			const persisted = await this.deps.executions.findByIdempotencyKey(idempotencyKey);
+			if (persisted?.id) {
+				agreement.bindExecution(persisted.id);
+				await agreement.save();
+			}
+			throw error;
+		}
+		agreement.bindExecution(result.executionId);
+		await agreement.save();
+		return result;
+	}
+	/**
+	* Bind completed immutable evidence, activate the signed version, and end
+	* the prior active version only when the new effective date has arrived.
+	*/
+	async applyExecutedAgreement(input) {
+		this.assertTenant(input.tenantId);
+		const loaded = await this.requireAgreement(input.agreementId);
+		this.assertAgreementTenant(loaded, input.tenantId);
+		if (!loaded.executionId) throw new Error("ReferralAgreement has no AgreementExecution");
+		const executed = input.executedAgreementId ? await this.deps.executedAgreements.get({ id: input.executedAgreementId }) : await this.deps.executedAgreements.findByExecution(loaded.executionId);
+		if (!executed?.id) throw new Error("Completed immutable ExecutedAgreement evidence was not found");
+		const executedId = executed.id;
+		if (executed.executionId !== loaded.executionId || executed.sourceKind !== "referral_agreement" || executed.sourceId !== loaded.id || executed.sourceVersion !== loaded.version || executed.tenantId !== input.tenantId) throw new Error("ExecutedAgreement does not belong to this ReferralAgreement version");
+		const at = input.at ?? this.now();
+		const agreementId = await this.runTransaction(async (agreements) => {
+			const agreement = await agreements.get({ id: input.agreementId });
+			if (!agreement) throw new Error("ReferralAgreement disappeared");
+			if (agreement.status === "active" && agreement.executedAgreementId === executedId) return agreement.id;
+			if (agreement.status !== "draft") throw new Error(`ReferralAgreement cannot accept executed evidence from status '${agreement.status}'`);
+			agreement.bindExecutedAgreement(executedId);
+			agreement.effectiveFrom ??= executed.effectiveFrom;
+			agreement.activate();
+			await agreement.save();
+			if (!agreement.effectiveFrom || agreement.effectiveFrom <= at) await this.supersedePriors(agreements, agreement, at);
+			return agreement.id;
+		});
+		return await this.requireAgreement(agreementId);
+	}
+	/** Scheduled/reconciliation hook for future-dated signed amendments. */
+	async supersedePriorIfEffective(input) {
+		this.assertTenant(input.tenantId);
+		const at = input.at ?? this.now();
+		const agreementId = await this.runTransaction(async (agreements) => {
+			const agreement = await agreements.get({ id: input.agreementId });
+			if (agreement?.status !== "active") throw new Error("Signed active ReferralAgreement was not found");
+			this.assertAgreementTenant(agreement, input.tenantId);
+			if (agreement.effectiveFrom && agreement.effectiveFrom > at) return agreement.id;
+			await this.supersedePriors(agreements, agreement, at);
+			return agreement.id;
+		});
+		return await this.requireAgreement(agreementId);
+	}
+	async supersedePriors(agreements, agreement, at) {
+		const priors = (await agreements.findByReferrerAndProgram(agreement.referrerId, agreement.programId)).filter((candidate) => candidate.id !== agreement.id && candidate.status === "active" && candidate.version < agreement.version);
+		for (const prior of priors) {
+			const supersededAt = agreement.effectiveFrom ?? at;
+			if (!prior.effectiveTo || prior.effectiveTo > supersededAt) prior.effectiveTo = supersededAt;
+			prior.supersede();
+			await prior.save();
+		}
+	}
+	async findPriorActive(agreement) {
+		return (await this.deps.agreements.findByReferrerAndProgram(agreement.referrerId, agreement.programId)).find((candidate) => candidate.id !== agreement.id && candidate.status === "active" && candidate.version < agreement.version) ?? null;
+	}
+	async requireAgreement(id) {
+		const agreement = await this.deps.agreements.get({ id });
+		if (!agreement) throw new Error(`ReferralAgreement '${id}' was not found`);
+		return agreement;
+	}
+	async runTransaction(fn) {
+		const db = this.deps.agreements.db;
+		if (typeof db.transaction !== "function") return await fn(this.deps.agreements);
+		return await db.transaction(async (tx) => fn(await ReferralAgreementCollection.create({ db: tx })));
+	}
+	assertTenant(tenantId) {
+		if (requireTenantId() !== tenantId) throw new Error("ReferralAgreement execution tenant mismatch");
+	}
+	assertAgreementTenant(agreement, tenantId) {
+		if (agreement.tenantId !== tenantId) throw new Error("ReferralAgreement does not belong to the active tenant");
+	}
+};
+//#endregion
 //#region src/referrals/services/ReferralCommissionService.ts
 var REFERRAL_TERMS_SNAPSHOT_KIND = "referral_term_snapshot";
 var ReferralCommissionService = class ReferralCommissionService {
@@ -2875,6 +2998,6 @@ var ReferralQualificationService = class ReferralQualificationService {
 	}
 };
 //#endregion
-export { ATTRIBUTION_EXCEPTION_STATUSES as A, AttributionExceptionCollection as B, ReferralAgreementCollection as C, validateAttributionPolicyTerms as D, AttributionPolicy as E, REFERRAL_LINK_STATUSES as F, REFERRAL_PROGRAM_STATUSES as I, REFERRAL_STATUSES as L, ATTRIBUTION_RESOLUTION_MODES as M, REFERRAL_AGREEMENT_APPROVAL_MODES as N, ATTRIBUTION_CONFLICT_BEHAVIORS as O, REFERRAL_AGREEMENT_STATUSES as P, REFERRAL_TOUCH_KINDS as R, Referral as S, AttributionPolicyCollection as T, AttributionException as V, ReferralTouchCollection as _, QualifiedReferralOverrideError as a, assertHttpTargetUrl as b, ReferralTermSnapshotCollection as c, ReferralProgram as d, MAX_CODE_GENERATION_ATTEMPTS as f, generateReferralCode as g, ReferralLinkCollection as h, AttributionService as i, ATTRIBUTION_POLICY_STATUSES as j, ATTRIBUTION_CREDIT_MODES as k, ReferralTermSnapshot as l, REFERRAL_CODE_LENGTH as m, REFERRAL_TERMS_SNAPSHOT_KIND as n, ReferrerCollection as o, REFERRAL_CODE_ALPHABET as p, ReferralCommissionService as r, Referrer as s, ReferralQualificationService as t, ReferralProgramCollection as u, ReferralTouch as v, ReferralAgreement as w, ReferralCollection as x, ReferralLink as y, REFERRER_STATUSES as z };
+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 };
 
-//# sourceMappingURL=referrals-CzkrPeKv.js.map
+//# sourceMappingURL=referrals-cYYg4YZw.js.map