@ak--47/dungeon-master 1.3.1 → 1.4.0

package/lib/hook-helpers/cohort.js

@@ -0,0 +1,124 @@
+/**
+ * Hook helpers — cohort atoms.
+ *
+ * Pure functions used inside `everything` / `event` hooks to classify users into
+ * behavioral cohorts. None of these mutate the input. They derive a label from a
+ * user's events or profile and return it; the caller decides what to do with the
+ * label (typically: feed into a `mutate` or `inject` atom).
+ */
+
+import { toMs } from './_internal.js';
+
+/**
+ * Classify a user into a named bin based on the count of a specific event in their stream.
+ * Bin definitions use inclusive lower bound, exclusive upper bound (`[lo, hi)`).
+ *
+ * @example
+ * const tier = binUsersByEventCount(events, 'Complete Action Item', {
+ *   low:   [0, 5],
+ *   sweet: [5, 20],
+ *   over:  [20, Infinity],
+ * });
+ *
+ * @param {Array<{event:string,time?:string|number}>} events - User's event stream.
+ * @param {string} eventName - Event to count.
+ * @param {Record<string, [number, number]>} bins - Map of bin name → [lo, hi).
+ * @returns {string|null} Matching bin name, or null if no bin matches.
+ */
+export function binUsersByEventCount(events, eventName, bins) {
+	if (!events || !eventName || !bins) return null;
+	let count = 0;
+	for (const ev of events) {
+		if (ev && ev.event === eventName) count++;
+	}
+	for (const [name, range] of Object.entries(bins)) {
+		if (!Array.isArray(range) || range.length !== 2) continue;
+		const [lo, hi] = range;
+		if (count >= lo && count < hi) return name;
+	}
+	return null;
+}
+
+/**
+ * Like `binUsersByEventCount` but only counts events whose timestamp falls inside
+ * `[startTime, endTime]` (inclusive). Times can be unix milliseconds, unix seconds,
+ * ISO strings, or anything `Date.parse` accepts.
+ *
+ * @param {Array<{event:string,time:string|number}>} events
+ * @param {string} eventName
+ * @param {string|number} startTime
+ * @param {string|number} endTime
+ * @param {Record<string, [number, number]>} bins
+ * @returns {string|null}
+ */
+export function binUsersByEventInRange(events, eventName, startTime, endTime, bins) {
+	if (!events || !eventName || !bins) return null;
+	const startMs = toMs(startTime);
+	const endMs = toMs(endTime);
+	if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return null;
+	let count = 0;
+	for (const ev of events) {
+		if (!ev || ev.event !== eventName || ev.time === undefined) continue;
+		const t = toMs(ev.time);
+		if (Number.isFinite(t) && t >= startMs && t <= endMs) count++;
+	}
+	for (const [name, range] of Object.entries(bins)) {
+		if (!Array.isArray(range) || range.length !== 2) continue;
+		const [lo, hi] = range;
+		if (count >= lo && count < hi) return name;
+	}
+	return null;
+}
+
+/**
+ * Count events that occur strictly between the FIRST `eventA` and the FIRST `eventB`
+ * after it in the stream. Useful for "how many ${X} did the user do between landing
+ * and converting" measurements that hooks then condition on.
+ *
+ * @param {Array<{event:string,time:string|number}>} events
+ * @param {string} eventA
+ * @param {string} eventB
+ * @returns {number} Count, or 0 if either anchor is missing.
+ */
+export function countEventsBetween(events, eventA, eventB) {
+	if (!events || !eventA || !eventB) return 0;
+	const sorted = sortByTime(events);
+	const a = sorted.find(e => e && e.event === eventA);
+	if (!a) return 0;
+	const aIdx = sorted.indexOf(a);
+	const b = sorted.slice(aIdx + 1).find(e => e && e.event === eventB);
+	if (!b) return 0;
+	const aT = toMs(a.time);
+	const bT = toMs(b.time);
+	let n = 0;
+	for (const ev of sorted) {
+		if (!ev || ev.time === undefined) continue;
+		const t = toMs(ev.time);
+		if (Number.isFinite(t) && t > aT && t < bT) n++;
+	}
+	return n;
+}
+
+/**
+ * Profile-based cohort check. Returns true if `profile[segmentKey]` matches one of
+ * `segmentValues` (array) or equals the single value passed.
+ *
+ * @param {Object} profile
+ * @param {string} segmentKey
+ * @param {*|Array<*>} segmentValues
+ * @returns {boolean}
+ */
+export function userInProfileSegment(profile, segmentKey, segmentValues) {
+	if (!profile || !segmentKey) return false;
+	const v = profile[segmentKey];
+	if (Array.isArray(segmentValues)) return segmentValues.includes(v);
+	return v === segmentValues;
+}
+
+// ── internal helpers ──
+
+function sortByTime(events) {
+	const copy = events.slice();
+	copy.sort((a, b) => toMs(a && a.time) - toMs(b && b.time));
+	return copy;
+}

package/lib/hook-helpers/identity.js

@@ -0,0 +1,56 @@
+/**
+ * Hook helpers — identity atoms.
+ *
+ * Wraps the Phase 2 identity primitives so hook authors can re-derive pre-auth /
+ * post-auth / stitch info without having to grovel inside `meta`. The `everything`
+ * hook already exposes `meta.authTime` and `meta.isPreAuth(event)`; these helpers
+ * cover callers that operate on stored events outside that hook.
+ */
+
+/**
+ * Returns true if the event happened strictly before the user's stitch event.
+ * - `authTime === null | undefined` is interpreted as "user never authed" → every
+ *   event is pre-auth (matches the `everything` hook's behavior for born-in-dataset
+ *   users that never converted).
+ * - Pre-existing users (already authed before the dataset window) won't have
+ *   `authTime` populated by the engine; callers wanting "always false" semantics
+ *   should pass `0` or `-Infinity`.
+ *
+ * @param {{time: string|number}} event
+ * @param {number|null|undefined} authTime - Unix milliseconds.
+ * @returns {boolean}
+ */
+export function isPreAuthEvent(event, authTime) {
+	if (!event || event.time === undefined || event.time === null) return false;
+	if (authTime === null || authTime === undefined) return true;
+	const t = typeof event.time === 'number'
+		? (event.time > 1e12 ? event.time : event.time * 1000)
+		: Date.parse(event.time);
+	return Number.isFinite(t) ? t < authTime : false;
+}
+
+/**
+ * Partition `events` into pre-auth / post-auth / stitch buckets relative to
+ * `authTime`. The stitch is the first post-auth event whose record carries BOTH
+ * `user_id` and `device_id` (the engine stamps this exactly once per converted
+ * born-in-dataset user). When no such event exists, `stitch` is `null`.
+ *
+ * @param {Array<{event:string,time:string|number,user_id?:string,device_id?:string}>} events
+ * @param {number|null|undefined} authTime - Unix milliseconds.
+ * @returns {{ preAuth: Object[], postAuth: Object[], stitch: Object|null }}
+ */
+export function splitByAuth(events, authTime) {
+	const result = { preAuth: [], postAuth: [], stitch: null };
+	if (!events) return result;
+	for (const ev of events) {
+		if (isPreAuthEvent(ev, authTime)) {
+			result.preAuth.push(ev);
+		} else {
+			result.postAuth.push(ev);
+			if (!result.stitch && ev && ev.user_id && ev.device_id) {
+				result.stitch = ev;
+			}
+		}
+	}
+	return result;
+}

package/lib/hook-helpers/index.js

@@ -0,0 +1,44 @@
+/**
+ * @ak--47/dungeon-master/hook-helpers — Phase 3 atom barrel export.
+ *
+ * Atoms are pure-ish primitives that hooks compose to build trends. The five
+ * sub-modules (cohort, mutate, timing, inject, identity) cover the moves Mixpanel
+ * analyses need: classify users into bins, scale event counts and property values,
+ * adjust timings, splice in cloned events, and reason about pre-auth state.
+ *
+ * Each atom carries full JSDoc on its definition; see the individual files for
+ * the contract details. Patterns (Phase 4, lib/hook-patterns) are higher-level
+ * recipes built on top of these atoms.
+ */
+
+export {
+	binUsersByEventCount,
+	binUsersByEventInRange,
+	countEventsBetween,
+	userInProfileSegment,
+} from './cohort.js';
+
+export {
+	cloneEvent,
+	dropEventsWhere,
+	scaleEventCount,
+	scalePropertyValue,
+	shiftEventTime,
+} from './mutate.js';
+
+export {
+	scaleTimingBetween,
+	scaleFunnelTTC,
+	findFirstSequence,
+} from './timing.js';
+
+export {
+	injectAfterEvent,
+	injectBetween,
+	injectBurst,
+} from './inject.js';
+
+export {
+	isPreAuthEvent,
+	splitByAuth,
+} from './identity.js';

package/lib/hook-helpers/inject.js

@@ -0,0 +1,99 @@
+/**
+ * Hook helpers — injection atoms.
+ *
+ * Splice cloned events into a user's event stream. CRITICAL: per Phase 1 schema-first
+ * rules, `templateEvent` should be an existing event from the stream (not a
+ * fabricated one), so the injected event carries the dungeon's defined schema. Use
+ * `cloneEvent` from `mutate.js` if you want the override semantics explicit.
+ *
+ * Randomness uses the seeded `chance` instance from utils so dungeons stay reproducible.
+ */
+
+import { getChance } from '../utils/utils.js';
+import { toMs, writeTime } from './_internal.js';
+
+/**
+ * Splice a cloned event into `events` immediately after `sourceEvent`. Time is
+ * `sourceEvent.time + gapMs`; `overrides` are shallow-merged on top of `templateEvent`.
+ * If `sourceEvent` is not in `events` (caller passed a stale ref), the new event is
+ * pushed to the end instead. Returns the newly created event.
+ *
+ * @param {Array<Object>} events
+ * @param {{time: string|number}} sourceEvent
+ * @param {Object} templateEvent
+ * @param {number} gapMs
+ * @param {Object} [overrides]
+ * @returns {Object|null}
+ */
+export function injectAfterEvent(events, sourceEvent, templateEvent, gapMs, overrides = {}) {
+	if (!events || !sourceEvent || !templateEvent) return null;
+	const baseT = toMs(sourceEvent.time);
+	if (!Number.isFinite(baseT)) return null;
+	const newEv = { ...templateEvent, ...overrides };
+	writeTime(newEv, baseT + gapMs);
+	const idx = events.indexOf(sourceEvent);
+	if (idx >= 0) events.splice(idx + 1, 0, newEv);
+	else events.push(newEv);
+	return newEv;
+}
+
+/**
+ * Splice a cloned event between the first `eventA` and the first `eventB` after
+ * it (in time order), at the midpoint of the gap. Returns the new event, or null
+ * if either anchor is missing.
+ *
+ * @param {Array<{event:string,time:string|number}>} events
+ * @param {string} eventA
+ * @param {string} eventB
+ * @param {Object} templateEvent
+ * @param {Object} [overrides]
+ * @returns {Object|null}
+ */
+export function injectBetween(events, eventA, eventB, templateEvent, overrides = {}) {
+	if (!events || !eventA || !eventB || !templateEvent) return null;
+	const sorted = events.slice().sort((x, y) => toMs(x && x.time) - toMs(y && y.time));
+	const aIdx = sorted.findIndex(e => e && e.event === eventA);
+	if (aIdx < 0) return null;
+	const a = sorted[aIdx];
+	const b = sorted.slice(aIdx + 1).find(e => e && e.event === eventB);
+	if (!b) return null;
+	const aT = toMs(a.time);
+	const bT = toMs(b.time);
+	if (!Number.isFinite(aT) || !Number.isFinite(bT)) return null;
+	const newEv = { ...templateEvent, ...overrides };
+	writeTime(newEv, (aT + bT) / 2);
+	const bIdxOrig = events.indexOf(b);
+	if (bIdxOrig >= 0) events.splice(bIdxOrig, 0, newEv);
+	else events.push(newEv);
+	return newEv;
+}
+
+/**
+ * Inject `count` clones of `templateEvent` into `events`, distributed uniformly at
+ * random within `[anchorTime - spreadMs, anchorTime + spreadMs]`. Uses the seeded
+ * RNG. Returns the array of newly created events.
+ *
+ * @param {Array<Object>} events
+ * @param {Object} templateEvent
+ * @param {number} count
+ * @param {string|number} anchorTime
+ * @param {number} spreadMs
+ * @param {Object} [overrides]
+ * @returns {Object[]}
+ */
+export function injectBurst(events, templateEvent, count, anchorTime, spreadMs, overrides = {}) {
+	if (!events || !templateEvent || count <= 0 || typeof spreadMs !== 'number') return [];
+	const anchorMs = toMs(anchorTime);
+	if (!Number.isFinite(anchorMs)) return [];
+	const chance = getChance();
+	const created = [];
+	for (let i = 0; i < count; i++) {
+		const offset = chance.floating({ min: -spreadMs, max: spreadMs });
+		const newEv = { ...templateEvent, ...overrides };
+		writeTime(newEv, anchorMs + offset);
+		events.push(newEv);
+		created.push(newEv);
+	}
+	return created;
+}
+

package/lib/hook-helpers/mutate.js

@@ -0,0 +1,151 @@
+/**
+ * Hook helpers — mutation atoms.
+ *
+ * In-place mutation primitives that hooks call to scale, drop, or modify events.
+ * These are deliberately tiny and composable so patterns built on top stay readable.
+ *
+ * Randomness uses the seeded `chance` instance from `lib/utils/utils.js` — never
+ * `Math.random()` — so dungeon runs stay reproducible.
+ */
+
+import { toMs } from './_internal.js';
+
+import { getChance } from '../utils/utils.js';
+
+/**
+ * Returns a new event object built from `template` with `overrides` shallow-merged
+ * on top. Mandatory replacement fields (time, user_id, etc.) belong in `overrides`.
+ * The schema-first hook rule still applies: only properties that already exist in
+ * the dungeon's event config should be set in `overrides`.
+ *
+ * @template {Record<string, any>} T
+ * @param {T} template
+ * @param {Partial<T>} [overrides]
+ * @returns {T}
+ */
+export function cloneEvent(template, overrides = {}) {
+	if (!template) throw new Error('cloneEvent: template is required');
+	return /** @type {any} */ ({ ...template, ...overrides });
+}
+
+/**
+ * Drop events where `predicate(event, index)` is truthy. Mutates `events` in place.
+ *
+ * @param {Array<Object>} events
+ * @param {(event: Object, index: number) => boolean} predicate
+ * @returns {number} Number of events dropped.
+ */
+export function dropEventsWhere(events, predicate) {
+	if (!events || typeof predicate !== 'function') return 0;
+	let dropped = 0;
+	for (let i = events.length - 1; i >= 0; i--) {
+		if (predicate(events[i], i)) {
+			events.splice(i, 1);
+			dropped++;
+		}
+	}
+	return dropped;
+}
+
+/**
+ * Scale the count of events with name `eventName` in `events` by `factor`. Mutates
+ * `events` in place.
+ *
+ * - factor > 1: clones existing matches with small monotonic time offsets (1s steps)
+ *   so duplicates land just after their source. Returns positive integer = clones added.
+ * - factor < 1: drops matches at random using the seeded RNG. Returns negative
+ *   integer = -dropped.
+ * - factor === 1 or no matches: no-op, returns 0.
+ *
+ * Note: the `insert_id` of cloned events is removed so a downstream pass can
+ * regenerate it (otherwise Mixpanel will dedupe on import).
+ *
+ * @param {Array<{event:string,time:string|number,insert_id?:string}>} events
+ * @param {string} eventName
+ * @param {number} factor
+ * @returns {number}
+ */
+export function scaleEventCount(events, eventName, factor) {
+	if (!events || !eventName || typeof factor !== 'number' || factor === 1) return 0;
+	if (factor > 1) {
+		const matches = events.filter(e => e && e.event === eventName);
+		if (!matches.length) return 0;
+		const additionalNeeded = Math.round(matches.length * (factor - 1));
+		let added = 0;
+		for (let i = 0; i < additionalNeeded; i++) {
+			const src = matches[i % matches.length];
+			const baseMs = toMs(src.time);
+			const newTime = Number.isFinite(baseMs)
+				? new Date(baseMs + (i + 1) * 1000).toISOString()
+				: src.time;
+			const clone = { ...src, time: newTime };
+			delete clone.insert_id;
+			events.push(clone);
+			added++;
+		}
+		return added;
+	}
+	// factor < 1 → drop at random
+	const chance = getChance();
+	const dropProb = Math.max(0, Math.min(1, 1 - factor));
+	let dropped = 0;
+	for (let i = events.length - 1; i >= 0; i--) {
+		const ev = events[i];
+		if (ev && ev.event === eventName && chance.bool({ likelihood: dropProb * 100 })) {
+			events.splice(i, 1);
+			dropped++;
+		}
+	}
+	return -dropped;
+}
+
+/**
+ * For each event in `events` matching `predicate`, multiply the numeric value at
+ * `propertyName` by `factor`. Skips events where the property is missing or non-numeric.
+ *
+ * @param {Array<Object>} events
+ * @param {(event: Object) => boolean} predicate
+ * @param {string} propertyName
+ * @param {number} factor
+ * @returns {number} Number of events whose property was scaled.
+ */
+export function scalePropertyValue(events, predicate, propertyName, factor) {
+	if (!events || typeof predicate !== 'function' || !propertyName || typeof factor !== 'number') return 0;
+	let count = 0;
+	for (const ev of events) {
+		if (!ev || !predicate(ev)) continue;
+		const v = ev[propertyName];
+		if (typeof v === 'number') {
+			ev[propertyName] = v * factor;
+			count++;
+		}
+	}
+	return count;
+}
+
+/**
+ * Shift a single event's `time` by `deltaMs` milliseconds. Mutates the event in place.
+ * Accepts ISO string or numeric (unix ms / unix seconds) inputs and writes back in
+ * the original format.
+ *
+ * @param {{time: string|number}} event
+ * @param {number} deltaMs
+ * @returns {Object} The mutated event.
+ */
+export function shiftEventTime(event, deltaMs) {
+	if (!event || event.time === undefined || event.time === null) return event;
+	if (typeof event.time === 'string') {
+		const ms = Date.parse(event.time);
+		if (Number.isFinite(ms)) {
+			event.time = new Date(ms + deltaMs).toISOString();
+		}
+	} else if (typeof event.time === 'number') {
+		// Preserve scale (seconds vs ms).
+		if (event.time > 1e12) {
+			event.time = event.time + deltaMs;
+		} else {
+			event.time = event.time + deltaMs / 1000;
+		}
+	}
+	return event;
+}

package/lib/hook-helpers/timing.js

@@ -0,0 +1,99 @@
+/**
+ * Hook helpers — timing atoms.
+ *
+ * Adjust gaps between specific events (or the whole funnel TTC) and detect ordered
+ * sequences within a maximum gap. All times are normalized to unix milliseconds
+ * internally; ISO strings are written back when the source was a string.
+ */
+
+import { toMs, writeTime } from './_internal.js';
+
+/**
+ * Find the FIRST `eventA` in time order, then the FIRST `eventB` after it, then
+ * scale the time gap between them by `factor`. The B event is mutated to the new
+ * timestamp (the A event is unchanged). Returns true on success, false if either
+ * anchor is missing.
+ *
+ * @param {Array<{event:string,time:string|number}>} events
+ * @param {string} eventA
+ * @param {string} eventB
+ * @param {number} factor - 0.5 halves the gap, 2.0 doubles it.
+ * @returns {boolean}
+ */
+export function scaleTimingBetween(events, eventA, eventB, factor) {
+	if (!events || !eventA || !eventB || typeof factor !== 'number') return false;
+	const sorted = events.slice().sort((x, y) => toMs(x && x.time) - toMs(y && y.time));
+	const aIdx = sorted.findIndex(e => e && e.event === eventA);
+	if (aIdx < 0) return false;
+	const tail = sorted.slice(aIdx + 1);
+	const b = tail.find(e => e && e.event === eventB);
+	if (!b) return false;
+	const a = sorted[aIdx];
+	const aT = toMs(a.time);
+	const bT = toMs(b.time);
+	if (!Number.isFinite(aT) || !Number.isFinite(bT)) return false;
+	const newBT = aT + (bT - aT) * factor;
+	writeTime(b, newBT);
+	return true;
+}
+
+/**
+ * Scale the time-to-convert (TTC) of an entire funnel. Each event's offset from
+ * the funnel's first event is multiplied by `factor`. Mutates events in place.
+ *
+ * @param {Array<{event:string,time:string|number}>} funnelEvents
+ * @param {number} factor
+ * @returns {number} Count of events shifted (excludes the anchor).
+ */
+export function scaleFunnelTTC(funnelEvents, factor) {
+	if (!funnelEvents || !funnelEvents.length || typeof factor !== 'number') return 0;
+	const sorted = funnelEvents.slice().sort((x, y) => toMs(x && x.time) - toMs(y && y.time));
+	const baseT = toMs(sorted[0].time);
+	if (!Number.isFinite(baseT)) return 0;
+	let n = 0;
+	for (const ev of funnelEvents) {
+		if (ev === sorted[0]) continue;
+		const t = toMs(ev.time);
+		if (!Number.isFinite(t)) continue;
+		writeTime(ev, baseT + (t - baseT) * factor);
+		n++;
+	}
+	return n;
+}
+
+/**
+ * Detect the FIRST occurrence of an ordered sequence of event names within a
+ * maximum gap. Returns the matching events (in order) or `null` if no run satisfies
+ * the constraint. The gap is checked between *consecutive matched* events, not
+ * between any two events in the stream.
+ *
+ * @param {Array<{event:string,time:string|number}>} events
+ * @param {string[]} eventNames - Ordered sequence of event names to match.
+ * @param {number} maxGapMin - Maximum allowable gap between consecutive matched events, in minutes.
+ * @returns {Array<Object>|null}
+ */
+export function findFirstSequence(events, eventNames, maxGapMin) {
+	if (!events || !eventNames || !eventNames.length || typeof maxGapMin !== 'number') return null;
+	const sorted = events.slice().sort((x, y) => toMs(x && x.time) - toMs(y && y.time));
+	const maxGapMs = maxGapMin * 60 * 1000;
+	for (let i = 0; i < sorted.length; i++) {
+		const head = sorted[i];
+		if (!head || head.event !== eventNames[0]) continue;
+		const matched = [head];
+		let lastT = toMs(head.time);
+		let stepIdx = 1;
+		for (let j = i + 1; j < sorted.length && stepIdx < eventNames.length; j++) {
+			const cur = sorted[j];
+			if (!cur || cur.time === undefined) continue;
+			const t = toMs(cur.time);
+			if (!Number.isFinite(t) || t - lastT > maxGapMs) break;
+			if (cur.event === eventNames[stepIdx]) {
+				matched.push(cur);
+				lastT = t;
+				stepIdx++;
+			}
+		}
+		if (matched.length === eventNames.length) return matched;
+	}
+	return null;
+}

package/lib/hook-patterns/aggregate-per-user-by-bin.js

@@ -0,0 +1,38 @@
+/**
+ * Pattern: Aggregate per User, by cohort bin.
+ *
+ * Adjusts the average value of a numeric event property based on the user's
+ * cohort bin (derived from `count(cohortEvent)`). Used for "Avg Order Value by
+ * per-user count of Sessions" Insights views — engaged users skew avg up.
+ *
+ * Mechanism: classify, then `scalePropertyValue` with `deltas[bin]` as the
+ * multiplier. Property must already be defined on the event in the dungeon
+ * schema and carry numeric values.
+ */
+
+import { binUsersByEventCount } from '../hook-helpers/cohort.js';
+import { scalePropertyValue } from '../hook-helpers/mutate.js';
+
+/**
+ * @param {Array<Object>} events - User's event stream (mutated in place).
+ * @param {Object} _profile
+ * @param {Object} opts
+ * @param {string} opts.cohortEvent
+ * @param {Record<string, [number, number]>} opts.bins
+ * @param {string} opts.event - Event whose property is scaled.
+ * @param {string} opts.propertyName
+ * @param {Record<string, number>} opts.deltas - Bin name → multiplier (1 = no-op,
+ *   1.5 = 50% lift, 0.7 = 30% drop).
+ * @returns {{ bin: string|null, scaled: number }}
+ */
+export function applyAggregateByBin(events, _profile, { cohortEvent, bins, event, propertyName, deltas }) {
+	if (!events || !cohortEvent || !bins || !event || !propertyName || !deltas) {
+		return { bin: null, scaled: 0 };
+	}
+	const bin = binUsersByEventCount(events, cohortEvent, bins);
+	if (!bin) return { bin: null, scaled: 0 };
+	const factor = deltas[bin];
+	if (typeof factor !== 'number' || factor === 1) return { bin, scaled: 0 };
+	const scaled = scalePropertyValue(events, e => e && e.event === event, propertyName, factor);
+	return { bin, scaled };
+}

package/lib/hook-patterns/attributed-by-source.js

@@ -0,0 +1,72 @@
+/**
+ * Pattern: Attribute conversions by source.
+ *
+ * For each user, copy a property value from a "touch" event onto a downstream
+ * "conversion" event so Mixpanel's "Conversions by Source" attribution analysis
+ * shows the configured weighted distribution. The pattern doesn't invent the
+ * source distribution — it preserves whatever the touch events already carry —
+ * BUT it lets you bias the conversion completion rate per source via `weights`
+ * (probability of stamping = weight ÷ max(weight) ).
+ *
+ * Mechanism: walk the user's event stream; when a `downstreamEvent` event fires,
+ * look back at the most-recent (or first) `sourceEvent` and copy
+ * `sourceEvent[sourceProperty]` onto the downstream event. Skip stamping
+ * probabilistically per `weights[sourceValue]`.
+ *
+ * Identity & schema: the destination property must already exist on
+ * `downstreamEvent` in the dungeon schema (we OVERWRITE the value, not invent it).
+ */
+
+/**
+ * @param {Array<Object>} events - User's event stream (mutated in place).
+ * @param {Object} _profile
+ * @param {Object} opts
+ * @param {string} opts.sourceEvent - Event whose property we copy from.
+ * @param {string} opts.sourceProperty - Property on `sourceEvent` to copy.
+ * @param {string} opts.downstreamEvent - Event whose property we overwrite.
+ * @param {string} [opts.downstreamProperty] - Defaults to `sourceProperty`.
+ * @param {Record<string, number>} opts.weights - Source value → relative weight
+ *   (probability of stamping = weight / maxWeight; missing entries = 0).
+ * @param {'firstTouch'|'lastTouch'} [opts.model] - Default 'firstTouch'.
+ * @returns {{ stamped: number, skipped: number }}
+ */
+export function applyAttributedBySource(events, _profile, opts) {
+	const { sourceEvent, sourceProperty, downstreamEvent, downstreamProperty, weights, model = 'firstTouch' } = opts || {};
+	if (!events || !sourceEvent || !sourceProperty || !downstreamEvent || !weights) {
+		return { stamped: 0, skipped: 0 };
+	}
+	const destProp = downstreamProperty || sourceProperty;
+	const sorted = events.slice().sort((a, b) => Date.parse(a.time) - Date.parse(b.time));
+	const maxWeight = Math.max(...Object.values(weights), 0);
+	if (maxWeight <= 0) return { stamped: 0, skipped: 0 };
+
+	let stamped = 0;
+	let skipped = 0;
+	const touches = []; // accumulated source events in time order
+	for (const ev of sorted) {
+		if (!ev) continue;
+		if (ev.event === sourceEvent && ev[sourceProperty] !== undefined) {
+			touches.push(ev);
+			continue;
+		}
+		if (ev.event === downstreamEvent && touches.length) {
+			const touch = model === 'lastTouch' ? touches[touches.length - 1] : touches[0];
+			const val = touch[sourceProperty];
+			const w = weights[val] || 0;
+			const prob = w / maxWeight; // 0..1
+			// Deterministic per-user pseudo-RNG keyed on the downstream event's
+			// insert_id (or time fallback) — keeps verification reproducible.
+			const seed = ev.insert_id || ev.time || '';
+			const r = simpleHashFloat(String(seed));
+			if (r < prob) {
+				ev[destProp] = val;
+				stamped++;
+			} else {
+				skipped++;
+			}
+		}
+	}
+	return { stamped, skipped };
+}
+
+import { simpleHashFloat } from '../hook-helpers/_internal.js';