@happyvertical/smrt-sales 0.57.9 → 0.57.11

package/dist/chunks/{commissions-Cip6QZ9Q.js → commissions-D5x24d4o.js}

@@ -1048,6 +1048,80 @@ var CommissionPayoutCollection = class extends SmrtCollection {
 	}
 };
 //#endregion
+//#region src/commissions/types.ts
+var EARNER_STATUSES = [
+	"pending",
+	"active",
+	"suspended"
+];
+var EARNER_SOURCE_ATTRIBUTION_STATUSES = ["active", "inactive"];
+var EARNER_KINDS = [
+	"person",
+	"organisation",
+	"treasury"
+];
+var PAYOUT_METHODS = [
+	"bank_transfer",
+	"check",
+	"paypal",
+	"credit",
+	"other",
+	"stripe_connect",
+	"crypto"
+];
+var PAYOUT_METHODS_REQUIRING_DESTINATION = ["stripe_connect", "crypto"];
+var COMMISSION_PLAN_STATUSES = [
+	"draft",
+	"active",
+	"superseded",
+	"retired"
+];
+var COMMISSION_STATUSES = [
+	"pending",
+	"earned",
+	"approved",
+	"payable",
+	"paid"
+];
+var COMMISSION_BASES = [
+	"fixed",
+	"gross",
+	"net",
+	"margin",
+	"custom"
+];
+var COMMISSION_ADJUSTMENT_KINDS = [
+	"refund",
+	"credit",
+	"chargeback",
+	"dispute",
+	"correction"
+];
+var COMMISSION_PAYOUT_STATUSES = [
+	"pending",
+	"approved",
+	"processing",
+	"completed",
+	"failed",
+	"rejected"
+];
+var EARNING_EVENT_KINDS = [
+	"conversion",
+	"agreement_execution",
+	"invoice_payment",
+	"collected_revenue",
+	"recognized_margin",
+	"milestone"
+];
+var ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES = [
+	"earned",
+	"approved",
+	"payable",
+	"paid"
+];
+var WATERFALL_POOL_RESIDUAL_RULES = ["remainder_sink", "largest_remainder"];
+var WATERFALL_POOL_ZERO_WEIGHT_RULES = ["remainder_sink", "equal"];
+//#endregion
 //#region src/commissions/services/WaterfallCalculationService.ts
 var WaterfallRecipientResolverRegistry = class {
 	resolvers = /* @__PURE__ */ new Map();
@@ -1060,6 +1134,54 @@ var WaterfallRecipientResolverRegistry = class {
 		return this.resolvers.get(descriptor.kind)?.(descriptor, event) ?? null;
 	}
 };
+async function prepareWaterfallPools(plan, event, options = {}) {
+	validateWaterfallPlan(plan);
+	const period = normalizePeriod(options.metricPeriod);
+	const facts = event.facts ?? {};
+	const pools = /* @__PURE__ */ Object.create(null);
+	for (const step of plan.steps) {
+		if (!step.pool || !conditionsMatch(step.conditions, facts)) continue;
+		const resolved = options.resolver?.resolve(step.recipient, event) ?? null;
+		if (!resolved) {
+			pools[step.key] = null;
+			continue;
+		}
+		const pool = freezeRecipient(resolved);
+		if (!options.poolMembers) throw new Error(`Waterfall pool step '${step.key}' requires a poolMembers resolver`);
+		const members = sortMembers((await options.poolMembers(pool, event)).map((member) => freezeRecipient(assertRecipient(member, `pool '${step.key}' member`))), step.key);
+		const metric = step.pool.metric ?? null;
+		let weights = members.map(() => 1);
+		if (metric !== null) {
+			if (!options.metricProvider) throw new Error(`Waterfall pool step '${step.key}' requires a metricProvider for metric '${metric}'`);
+			const values = await options.metricProvider.getMetricValues({
+				metric,
+				pool,
+				members,
+				period,
+				event
+			});
+			weights = weightsFromMetricValues(step.key, members, values);
+		}
+		pools[step.key] = {
+			pool,
+			metric,
+			period: metric === null ? null : period,
+			members: members.map((recipient, index) => ({
+				recipient,
+				weight: weights[index]
+			}))
+		};
+	}
+	return pools;
+}
+async function calculateWaterfallWithPools(plan, event, options = {}) {
+	if (options.frozenInputs || options.pools) return calculateWaterfall(plan, event, options);
+	const pools = await prepareWaterfallPools(plan, event, options);
+	return calculateWaterfall(plan, event, {
+		...options,
+		pools
+	});
+}
 function calculateWaterfall(plan, event, options = {}) {
 	validateWaterfallPlan(plan);
 	const planFingerprint = fingerprintPlan(plan);
@@ -1085,6 +1207,11 @@ function calculateWaterfall(plan, event, options = {}) {
 		remainderSink: options.frozenInputs ? freezeRecipient(options.frozenInputs.remainderSink) : resolveSink(plan, calculationEvent, options),
 		applicationFeeSettledCents: options.frozenInputs?.applicationFeeSettledCents ?? event.applicationFeeSettledCents ?? 0
 	};
+	if (plan.steps.some((step) => step.pool)) {
+		const poolsByStep = /* @__PURE__ */ Object.create(null);
+		for (const [key, snapshot] of Object.entries(options.frozenInputs?.poolsByStep ?? {})) poolsByStep[key] = normalizePoolSnapshot(snapshot, key);
+		frozenInputs.poolsByStep = poolsByStep;
+	}
 	assertWholeNonNegative(frozenInputs.applicationFeeSettledCents, "applicationFeeSettledCents");
 	let remainingCents = calculationEvent.grossAmountCents;
 	let redirectedToSinkCents = 0;
@@ -1108,6 +1235,38 @@ function calculateWaterfall(plan, event, options = {}) {
 		const baseCents = resolveBase(step, calculationEvent, remainingCents);
 		const amountCents = resolveAmount(step, baseCents);
 		if (amountCents > remainingCents) throw new Error(`Waterfall step '${step.key}' allocates ${amountCents} cents but only ${remainingCents} cents remain`);
+		if (step.pool) {
+			const { recipient: recipient2, snapshot } = resolvePoolStep(step, calculationEvent, options, frozenInputs);
+			remainingCents -= amountCents;
+			if (!recipient2 || !snapshot) {
+				redirectedToSinkCents += amountCents;
+				steps.push({
+					key: step.key,
+					baseCents,
+					amountCents,
+					recipient: null,
+					redirectedToSinkCents: amountCents,
+					applicationFeeOffsetCents: 0,
+					payableCents: 0
+				});
+				continue;
+			}
+			const pool = allocatePool(amountCents, step.pool, snapshot);
+			const memberCents = amountCents - pool.toSinkCents;
+			totalRecipientAllocatedCents += memberCents;
+			redirectedToSinkCents += pool.toSinkCents;
+			steps.push({
+				key: step.key,
+				baseCents,
+				amountCents,
+				recipient: recipient2,
+				redirectedToSinkCents: pool.toSinkCents,
+				applicationFeeOffsetCents: 0,
+				payableCents: memberCents,
+				pool: pool.trace
+			});
+			continue;
+		}
 		const recipient = resolveStepRecipient(step, calculationEvent, options, frozenInputs);
 		let applicationFeeOffsetCents = 0;
 		if (recipient && descriptorMatches(plan.applicationFeeOffsetRecipient, step.recipient)) {
@@ -1166,6 +1325,176 @@ function resolveStepRecipient(step, event, options, frozen) {
 	});
 	return frozenRecipient;
 }
+function resolvePoolStep(step, event, options, frozen) {
+	const poolsByStep = frozen.poolsByStep;
+	if (Object.hasOwn(frozen.recipientByStep, step.key)) {
+		const recipient2 = frozen.recipientByStep[step.key];
+		if (!recipient2) return {
+			recipient: null,
+			snapshot: null
+		};
+		const snapshot2 = Object.hasOwn(poolsByStep, step.key) ? poolsByStep[step.key] : void 0;
+		if (!snapshot2) throw new Error(`Waterfall frozen inputs lack the pool snapshot for step '${step.key}'`);
+		if (!isDeepStrictEqual(snapshot2.pool, recipient2)) throw new Error(`Waterfall frozen pool snapshot for step '${step.key}' does not match its frozen recipient`);
+		assertSnapshotMetric(step, snapshot2);
+		return {
+			recipient: freezeRecipient(recipient2),
+			snapshot: snapshot2
+		};
+	}
+	if (!options.pools || !Object.hasOwn(options.pools, step.key)) throw new Error(`Waterfall pool step '${step.key}' requires prepared pool inputs; use prepareWaterfallPools() or calculateWaterfallWithPools()`);
+	const prepared = options.pools[step.key];
+	const snapshot = prepared ? normalizePoolSnapshot(prepared, step.key) : null;
+	if (snapshot) assertSnapshotMetric(step, snapshot);
+	const current = options.resolver?.resolve(step.recipient, event) ?? null;
+	if (!isDeepStrictEqual(current ? freezeRecipient(current) : null, snapshot ? snapshot.pool : null)) throw new Error(`Waterfall prepared pool for step '${step.key}' does not match the pool its recipient descriptor resolves to`);
+	const recipient = snapshot ? freezeRecipient(snapshot.pool) : null;
+	Object.defineProperty(frozen.recipientByStep, step.key, {
+		value: recipient,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+	if (snapshot) poolsByStep[step.key] = snapshot;
+	return {
+		recipient,
+		snapshot
+	};
+}
+function assertSnapshotMetric(step, snapshot) {
+	const expected = step.pool?.metric ?? null;
+	if (snapshot.metric !== expected) throw new Error(`Waterfall pool snapshot for step '${step.key}' uses metric ${JSON.stringify(snapshot.metric)} but the plan step declares ${JSON.stringify(expected)}`);
+}
+function allocatePool(amountCents, spec, snapshot) {
+	const residualRule = spec.residual ?? "remainder_sink";
+	const members = snapshot.members;
+	const totalWeight = members.reduce((sum, member) => sum + member.weight, 0);
+	const base = {
+		metric: snapshot.metric,
+		period: snapshot.period ? { ...snapshot.period } : null,
+		totalWeight,
+		residualRule
+	};
+	const useEqual = members.length > 0 && totalWeight === 0 && (spec.zeroWeight ?? "remainder_sink") === "equal";
+	if (members.length === 0 || totalWeight === 0 && !useEqual) return {
+		toSinkCents: amountCents,
+		trace: {
+			...base,
+			distribution: "remainder_sink",
+			residualToSinkCents: 0,
+			members: members.map((member) => ({
+				recipient: freezeRecipient(member.recipient),
+				weight: member.weight,
+				shareFraction: 0,
+				amountCents: 0
+			}))
+		}
+	};
+	const effective = members.map((member) => BigInt(useEqual ? 1 : member.weight));
+	const total = effective.reduce((sum, weight) => sum + weight, 0n);
+	const amount = BigInt(amountCents);
+	const floors = effective.map((weight) => amount * weight / total);
+	const remainders = effective.map((weight) => amount * weight % total);
+	let residual = Number(amount - floors.reduce((sum, cents2) => sum + cents2, 0n));
+	const cents = floors.map(Number);
+	let residualToSinkCents = residual;
+	if (residualRule === "largest_remainder") {
+		const order = members.map((_, index) => index).sort((a, b) => compareBigInt(remainders[b], remainders[a]) || compareBigInt(effective[b], effective[a]) || compareCodeUnits(members[a].recipient.kind, members[b].recipient.kind) || compareCodeUnits(members[a].recipient.id, members[b].recipient.id));
+		for (const index of order) {
+			if (residual === 0) break;
+			cents[index] += 1;
+			residual -= 1;
+		}
+		residualToSinkCents = 0;
+	}
+	const memberTraces = members.map((member, index) => ({
+		recipient: freezeRecipient(member.recipient),
+		weight: member.weight,
+		shareFraction: Number(effective[index]) / Number(total),
+		amountCents: cents[index]
+	}));
+	return {
+		toSinkCents: residualToSinkCents,
+		trace: {
+			...base,
+			distribution: useEqual || snapshot.metric === null ? "equal" : "weighted",
+			residualToSinkCents,
+			members: memberTraces
+		}
+	};
+}
+function compareBigInt(a, b) {
+	return a === b ? 0 : a < b ? -1 : 1;
+}
+function compareCodeUnits(a, b) {
+	return a === b ? 0 : a < b ? -1 : 1;
+}
+function assertRecipient(value, label) {
+	const recipient = value;
+	if (!recipient || typeof recipient !== "object" || typeof recipient.kind !== "string" || !recipient.kind || typeof recipient.id !== "string" || !recipient.id) throw new Error(`Waterfall ${label} must have non-empty kind and id`);
+	return recipient;
+}
+function sortMembers(members, stepKey) {
+	const sorted = [...members].sort((a, b) => compareCodeUnits(a.kind, b.kind) || compareCodeUnits(a.id, b.id));
+	for (let index = 1; index < sorted.length; index++) if (sorted[index].kind === sorted[index - 1].kind && sorted[index].id === sorted[index - 1].id) throw new Error(`Waterfall pool step '${stepKey}' lists member ${sorted[index].kind}:${sorted[index].id} more than once`);
+	return sorted;
+}
+function weightsFromMetricValues(stepKey, members, values) {
+	if (!Array.isArray(values)) throw new Error(`Waterfall pool step '${stepKey}' metric provider must return an array`);
+	const indexByMember = /* @__PURE__ */ new Map();
+	for (const [index, member] of members.entries()) indexByMember.set(JSON.stringify([member.kind, member.id]), index);
+	const weights = members.map(() => 0);
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of values) {
+		const index = indexByMember.get(JSON.stringify([entry?.kind, entry?.id]));
+		if (index === void 0) throw new Error(`Waterfall pool step '${stepKey}' metric value names a non-member`);
+		if (seen.has(index)) throw new Error(`Waterfall pool step '${stepKey}' metric value repeats a member`);
+		seen.add(index);
+		assertWeight(entry.value, stepKey);
+		weights[index] = entry.value;
+	}
+	return weights;
+}
+function assertWeight(value, stepKey) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`Waterfall pool step '${stepKey}' weights must be non-negative safe integers`);
+}
+function normalizePoolSnapshot(snapshot, stepKey) {
+	if (!snapshot || typeof snapshot !== "object" || !Array.isArray(snapshot.members)) throw new Error(`Waterfall pool snapshot for step '${stepKey}' must list members`);
+	if (snapshot.metric !== null && (typeof snapshot.metric !== "string" || !snapshot.metric)) throw new Error(`Waterfall pool snapshot for step '${stepKey}' has an invalid metric`);
+	const members = sortMembers(snapshot.members.map((member) => {
+		assertWeight(member?.weight, stepKey);
+		return {
+			...freezeRecipient(assertRecipient(member.recipient, `pool '${stepKey}' member`)),
+			weight: member.weight
+		};
+	}), stepKey);
+	if (snapshot.metric === null && members.some((member) => member.weight !== 1)) throw new Error(`Waterfall pool snapshot for step '${stepKey}' uses equal weights, so every weight must be 1`);
+	let total = 0;
+	for (const member of members) {
+		total += member.weight;
+		if (!Number.isSafeInteger(total)) throw new Error(`Waterfall pool step '${stepKey}' total weight exceeds the safe integer range`);
+	}
+	return {
+		pool: freezeRecipient(assertRecipient(snapshot.pool, `pool '${stepKey}'`)),
+		metric: snapshot.metric,
+		period: snapshot.period ? normalizePeriod(snapshot.period) : null,
+		members: members.map(({ weight, ...recipient }) => ({
+			recipient,
+			weight
+		}))
+	};
+}
+function normalizePeriod(period) {
+	if (!period) return null;
+	const start = new Date(period.start);
+	const end = new Date(period.end);
+	if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) throw new Error("Waterfall metric period must use valid dates");
+	if (end <= start) throw new Error("Waterfall metric period end must be later than start");
+	return {
+		start: start.toISOString(),
+		end: end.toISOString()
+	};
+}
 function freezeRecipient(recipient) {
 	return {
 		kind: recipient.kind,
@@ -1235,6 +1564,7 @@ function validateWaterfallPlan(plan) {
 			"prototype"
 		].includes(step.key)) throw new Error(`Waterfall step '${step.key}' uses a reserved key`);
 		if (!step.recipient?.kind) throw new Error(`Waterfall step '${step.key}' requires a recipient descriptor`);
+		if (step.pool !== void 0) validatePoolSpec(plan, step);
 		if (step.base === "custom" && !step.customBaseKey) throw new Error(`Waterfall step '${step.key}' requires customBaseKey for custom base`);
 		if (![
 			"gross",
@@ -1263,6 +1593,20 @@ function validateWaterfallPlan(plan) {
 	if (!plan.remainderSink?.kind) throw new Error("Waterfall plan requires a remainderSink descriptor");
 	if (plan.applicationFeeOffsetRecipient && !plan.applicationFeeOffsetRecipient.kind) throw new Error("Waterfall application fee offset requires a recipient descriptor");
 }
+function validatePoolSpec(plan, step) {
+	const pool = step.pool;
+	if (!pool || typeof pool !== "object" || Array.isArray(pool) || Object.getPrototypeOf(pool) !== Object.prototype) throw new Error(`Waterfall step '${step.key}' pool must be an object`);
+	const spec = pool;
+	for (const key of Object.keys(spec)) if (![
+		"metric",
+		"residual",
+		"zeroWeight"
+	].includes(key)) throw new Error(`Waterfall step '${step.key}' pool has an unknown option '${key}'`);
+	if (spec.metric !== void 0 && (typeof spec.metric !== "string" || !spec.metric)) throw new Error(`Waterfall step '${step.key}' pool metric must be a non-empty string`);
+	if (spec.residual !== void 0 && !WATERFALL_POOL_RESIDUAL_RULES.includes(spec.residual)) throw new Error(`Waterfall step '${step.key}' pool residual is invalid`);
+	if (spec.zeroWeight !== void 0 && !WATERFALL_POOL_ZERO_WEIGHT_RULES.includes(spec.zeroWeight)) throw new Error(`Waterfall step '${step.key}' pool zeroWeight is invalid`);
+	if (descriptorMatches(plan.applicationFeeOffsetRecipient, step.recipient)) throw new Error(`Waterfall pool step '${step.key}' cannot be the application fee offset recipient`);
+}
 function validateEvent(plan, event) {
 	if (plan.currency !== event.currency) throw new Error("Waterfall plan and event currency must match; no FX is performed");
 	assertWholeNonNegative(event.grossAmountCents, "grossAmountCents");
@@ -1271,70 +1615,6 @@ function assertWholeNonNegative(value, label) {
 	if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${label} must be a non-negative safe integer cents value`);
 }
 //#endregion
-//#region src/commissions/types.ts
-var EARNER_STATUSES = [
-	"pending",
-	"active",
-	"suspended"
-];
-var EARNER_SOURCE_ATTRIBUTION_STATUSES = ["active", "inactive"];
-var PAYOUT_METHODS = [
-	"bank_transfer",
-	"check",
-	"paypal",
-	"credit",
-	"other"
-];
-var COMMISSION_PLAN_STATUSES = [
-	"draft",
-	"active",
-	"superseded",
-	"retired"
-];
-var COMMISSION_STATUSES = [
-	"pending",
-	"earned",
-	"approved",
-	"payable",
-	"paid"
-];
-var COMMISSION_BASES = [
-	"fixed",
-	"gross",
-	"net",
-	"margin",
-	"custom"
-];
-var COMMISSION_ADJUSTMENT_KINDS = [
-	"refund",
-	"credit",
-	"chargeback",
-	"dispute",
-	"correction"
-];
-var COMMISSION_PAYOUT_STATUSES = [
-	"pending",
-	"approved",
-	"processing",
-	"completed",
-	"failed",
-	"rejected"
-];
-var EARNING_EVENT_KINDS = [
-	"conversion",
-	"agreement_execution",
-	"invoice_payment",
-	"collected_revenue",
-	"recognized_margin",
-	"milestone"
-];
-var ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES = [
-	"earned",
-	"approved",
-	"payable",
-	"paid"
-];
-//#endregion
 //#region src/commissions/models/CommissionPlan.ts
 var __defProp$3 = Object.defineProperty;
 var __getOwnPropDesc$3 = Object.getOwnPropertyDescriptor;
@@ -1822,8 +2102,39 @@ var __decorateClass$2 = (decorators, target, key, kind) => {
 	return result;
 };
 var __publicField$2 = (obj, key, value) => __defNormalProp$2(obj, typeof key !== "symbol" ? key + "" : key, value);
+function validatePayoutDestination(destination) {
+	const value = destination;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Earner payoutDestination must be an object");
+	const requireText = (key) => {
+		if (typeof value[key] !== "string" || !value[key].trim()) throw new Error(`Earner payoutDestination.${key} is required`);
+	};
+	let allowed;
+	if (value.method === "stripe_connect") {
+		allowed = ["method", "connectedAccountId"];
+		requireText("connectedAccountId");
+		if (!/^acct_[A-Za-z0-9]+$/.test(value.connectedAccountId)) throw new Error("Earner payoutDestination.connectedAccountId must be a Stripe connected account id ('acct_…')");
+	} else if (value.method === "crypto") {
+		allowed = [
+			"method",
+			"network",
+			"asset",
+			"address",
+			"memo"
+		];
+		requireText("network");
+		requireText("asset");
+		requireText("address");
+		if (value.memo !== void 0 && typeof value.memo !== "string") throw new Error("Earner payoutDestination.memo must be a string");
+	} else throw new Error(`Earner payoutDestination.method must be one of ${PAYOUT_METHODS_REQUIRING_DESTINATION.join(", ")}`);
+	for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Earner payoutDestination has an unexpected field '${key}'`);
+}
 var Earner = class extends SmrtObject {
 	tenantId = null;
+	/**
+	* Party kind: `person` (default), `organisation`, or `treasury`.
+	* Organisation and treasury earners need no person Profile.
+	*/
+	kind = "person";
 	profileId = "";
 	/** Human-readable display name for portals and operator views. */
 	displayName = "";
@@ -1832,6 +2143,13 @@ var Earner = class extends SmrtObject {
 	/** Preferred payout delivery method. */
 	payoutMethod = "bank_transfer";
 	/**
+	* Typed payout-rail descriptor as a JSON string (`{}` when none). Required
+	* for an active earner whose method is `stripe_connect` or `crypto`, and
+	* its `method` must match {@link payoutMethod}. Use
+	* {@link getPayoutDestination}/{@link setPayoutDestination}.
+	*/
+	payoutDestination = "{}";
+	/**
 	* Minimum unsettled balance (integer cents) before a payout batch is
 	* created. Default $50.00 = 5000 cents.
 	*/
@@ -1852,10 +2170,12 @@ var Earner = class extends SmrtObject {
 	constructor(options = {}) {
 		super(options);
 		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.kind !== void 0) this.kind = options.kind;
 		if (options.profileId !== void 0) this.profileId = options.profileId;
 		if (options.displayName !== void 0) this.displayName = options.displayName;
 		if (options.status !== void 0) this.status = options.status;
 		if (options.payoutMethod !== void 0) this.payoutMethod = options.payoutMethod;
+		if (options.payoutDestination !== void 0) this.payoutDestination = options.payoutDestination;
 		if (options.payoutThresholdCents !== void 0) this.payoutThresholdCents = options.payoutThresholdCents;
 		if (options.payoutScheduleKey !== void 0) this.payoutScheduleKey = options.payoutScheduleKey;
 		if (options.currency !== void 0) this.currency = options.currency;
@@ -1884,6 +2204,60 @@ var Earner = class extends SmrtObject {
 	setMetadata(data) {
 		this.metadata = JSON.stringify(data ?? {});
 	}
+	isOrganisation() {
+		return this.kind === "organisation";
+	}
+	isTreasury() {
+		return this.kind === "treasury";
+	}
+	/** Parse {@link payoutDestination}; `null` when none or unparseable. */
+	getPayoutDestination() {
+		try {
+			const parsed = JSON.parse(this.payoutDestination || "{}");
+			return parsed && typeof parsed === "object" && !Array.isArray(parsed) && Object.keys(parsed).length > 0 ? parsed : null;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Validate and store a payout destination, and set {@link payoutMethod}
+	* to its method. `null` clears it (the method is left unchanged).
+	*/
+	setPayoutDestination(destination) {
+		if (destination === null) {
+			this.payoutDestination = "{}";
+			return;
+		}
+		validatePayoutDestination(destination);
+		this.payoutDestination = JSON.stringify(destination);
+		this.payoutMethod = destination.method;
+	}
+	/**
+	* Save with field guards: `kind` and `payoutMethod` must be known values,
+	* a stored destination must be valid and match `payoutMethod`, and an
+	* active Stripe Connect / crypto earner must have a destination.
+	*/
+	async save() {
+		this.assertPayoutTerms();
+		return await super.save();
+	}
+	assertPayoutTerms() {
+		const label = `Earner ${this.id ?? "<new>"}`;
+		if (!EARNER_KINDS.includes(this.kind)) throw new Error(`${label}: unknown kind '${this.kind}'`);
+		if (!PAYOUT_METHODS.includes(this.payoutMethod)) throw new Error(`${label}: unknown payoutMethod '${this.payoutMethod}'`);
+		let parsed;
+		try {
+			parsed = JSON.parse(this.payoutDestination || "{}");
+		} catch {
+			throw new Error(`${label}: payoutDestination must be valid JSON`);
+		}
+		const hasDestination = !!parsed && typeof parsed === "object" && !Array.isArray(parsed) && Object.keys(parsed).length > 0;
+		if (hasDestination) {
+			validatePayoutDestination(parsed);
+			if (parsed.method !== this.payoutMethod) throw new Error(`${label}: payoutDestination method '${parsed.method}' does not match payoutMethod '${this.payoutMethod}'`);
+		} else if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${label}: payoutDestination must be a JSON object`);
+		if (this.status === "active" && !hasDestination && PAYOUT_METHODS_REQUIRING_DESTINATION.includes(this.payoutMethod)) throw new Error(`${label}: an active ${this.payoutMethod} earner requires a payoutDestination`);
+	}
 };
 __publicField$2(Earner, "__smrtPackage__", "@happyvertical/smrt-sales");
 __decorateClass$2([tenantId({ nullable: true })], Earner.prototype, "tenantId", 2);
@@ -2927,6 +3301,8 @@ var CommissionPayoutService = class CommissionPayoutService {
 				settledAdjustmentIds: []
 			};
 		}
+		const payoutMethod = input.payoutMethod ?? earner.payoutMethod;
+		if (PAYOUT_METHODS_REQUIRING_DESTINATION.includes(payoutMethod) && earner.getPayoutDestination()?.method !== payoutMethod) throw new Error(`CommissionPayoutService: earner '${input.earnerId}' has no ${payoutMethod} payoutDestination`);
 		const commissions = await this.gatherBatchCommissions(input);
 		const eligibleAdjustments = await this.findEligibleUnsettledAdjustments(input.earnerId, input.currency, CommissionPayoutService.adjustmentParentPredicate(input));
 		const commissionTotalCents = commissions.reduce((sum, c) => sum + c.amountCents, 0);
@@ -2952,7 +3328,7 @@ var CommissionPayoutService = class CommissionPayoutService {
 			currency: input.currency,
 			periodStart: input.periodStart ?? null,
 			periodEnd: input.periodEnd ?? null,
-			payoutMethod: input.payoutMethod ?? earner.payoutMethod,
+			payoutMethod,
 			status: "pending",
 			commissionTotalCents,
 			adjustmentTotalCents,
@@ -3960,6 +4336,6 @@ var EarnerAttributionService = class EarnerAttributionService {
 	}
 };
 //#endregion
-export { EARNING_EVENT_KINDS as A, CommissionAdjustmentOperation as B, COMMISSION_ADJUSTMENT_KINDS as C, COMMISSION_STATUSES as D, COMMISSION_PLAN_STATUSES as E, CommissionPayoutCollection as F, CommissionAdjustment as H, CommissionPayout as I, CommissionCollection as L, WaterfallRecipientResolverRegistry as M, calculateWaterfall as N, EARNER_SOURCE_ATTRIBUTION_STATUSES as O, validateWaterfallPlan as P, Commission as R, ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES as S, COMMISSION_PAYOUT_STATUSES as T, CommissionAdjustmentCollection as V, EarnerCollection as _, CommissionBalanceService as a, CommissionPlan as b, CommissionAdjustmentValidationError as c, centsToAmount as d, roundCents as f, EarnerSourceAttribution as g, EarnerSourceAttributionCollection as h, CommissionCalculationService as i, PAYOUT_METHODS as j, EARNER_STATUSES as k, amountToCents as l, EarningEvent as m, CommissionSettlementService as n, CommissionAdjustmentReplayConflictError as o, EarningEventCollection as p, CommissionPayoutService as r, CommissionAdjustmentService as s, EarnerAttributionService as t, calculateCommissionAmountCents as u, Earner as v, COMMISSION_BASES as w, validateCommissionPlanComponents as x, CommissionPlanCollection as y, CommissionAdjustmentOperationCollection as z };
+export { COMMISSION_BASES as A, WATERFALL_POOL_RESIDUAL_RULES as B, WaterfallRecipientResolverRegistry as C, validateWaterfallPlan as D, prepareWaterfallPools as E, EARNER_SOURCE_ATTRIBUTION_STATUSES as F, Commission as G, CommissionPayoutCollection as H, EARNER_STATUSES as I, CommissionAdjustmentCollection as J, CommissionAdjustmentOperationCollection as K, EARNING_EVENT_KINDS as L, COMMISSION_PLAN_STATUSES as M, COMMISSION_STATUSES as N, ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES as O, EARNER_KINDS as P, PAYOUT_METHODS as R, validateCommissionPlanComponents as S, calculateWaterfallWithPools as T, CommissionPayout as U, WATERFALL_POOL_ZERO_WEIGHT_RULES as V, CommissionCollection as W, CommissionAdjustment as Y, EarnerCollection as _, CommissionBalanceService as a, CommissionPlanCollection as b, CommissionAdjustmentValidationError as c, centsToAmount as d, roundCents as f, EarnerSourceAttribution as g, EarnerSourceAttributionCollection as h, CommissionCalculationService as i, COMMISSION_PAYOUT_STATUSES as j, COMMISSION_ADJUSTMENT_KINDS as k, amountToCents as l, EarningEvent as m, CommissionSettlementService as n, CommissionAdjustmentReplayConflictError as o, EarningEventCollection as p, CommissionAdjustmentOperation as q, CommissionPayoutService as r, CommissionAdjustmentService as s, EarnerAttributionService as t, calculateCommissionAmountCents as u, Earner as v, calculateWaterfall as w, CommissionPlan as x, validatePayoutDestination as y, PAYOUT_METHODS_REQUIRING_DESTINATION as z };
 
-//# sourceMappingURL=commissions-Cip6QZ9Q.js.map
+//# sourceMappingURL=commissions-D5x24d4o.js.map