@ak--47/dungeon-master 1.4.4 → 1.5.0

package/lib/hook-helpers/inject.js

@@ -97,3 +97,98 @@ export function injectBurst(events, templateEvent, count, anchorTime, spreadMs,
 	return created;
 }
 
+const DAY_MS = 86400000;
+
+/**
+ * Inject cloned events on days where the user had no activity for this event
+ * type. Increases distinct-day frequency without disturbing existing event
+ * ordering or inflating same-day counts.
+ *
+ * Designed for use in `everything` hooks to move users between frequency bins
+ * in Mixpanel's frequency distribution reports — which count DISTINCT DAYS
+ * (not total events). See `lib/verify/counting.js#countDistinctPeriods` and
+ * `mixpanel/analytics` `addiction_query.cpp` for the counting rule.
+ *
+ * Behavior:
+ *   1. Collect all existing distinct UTC days for `eventName`.
+ *   2. If the user already has >= `targetDays` distinct days, return unchanged.
+ *   3. Restrict candidate days to the user's active window (first event time
+ *      to last event time, by default).
+ *   4. Pick `targetDays - existing` random days that have no `eventName`
+ *      activity (uses seeded RNG).
+ *   5. Find a template event of `eventName`; if none exist for this user,
+ *      return unchanged (we honor schema-first: don't fabricate events).
+ *   6. Clone the template onto each picked day at a random hour within the
+ *      day. `insert_id` is stripped (Mixpanel re-deduplicates on import).
+ *   7. Append clones to the array. Caller's downstream sort handles ordering.
+ *
+ * @param {Object[]} events - Full user event array (from `everything` hook).
+ * @param {string} eventName - Event name to inject.
+ * @param {number} targetDays - Desired absolute count of distinct active days.
+ * @param {Object} [options]
+ * @param {('active')} [options.timeRange='active'] - 'active' = user's
+ *   first-to-last event window. Reserved for future range modes.
+ * @param {Object} [options.overrides] - Property overrides applied via spread
+ *   on top of the cloned template.
+ * @returns {Object[]} The (possibly mutated) events array. Same reference as
+ *   the input — convenient to return from an `everything` hook.
+ */
+export function injectOnNewDays(events, eventName, targetDays, options = {}) {
+	if (!Array.isArray(events) || !eventName || typeof targetDays !== 'number' || targetDays <= 0) return events;
+	const overrides = options.overrides || {};
+
+	// Collect timestamps for the named event + global window for the user.
+	const matches = [];
+	const allTimes = [];
+	let template = null;
+	for (const ev of events) {
+		if (!ev) continue;
+		const t = toMs(ev.time);
+		if (Number.isFinite(t)) allTimes.push(t);
+		if (ev.event === eventName && Number.isFinite(t)) {
+			matches.push(t);
+			template = template || ev;
+		}
+	}
+	if (!template) return events;
+	if (!allTimes.length) return events;
+
+	// Distinct UTC days that already have an event of `eventName`.
+	const existingDays = new Set();
+	for (const t of matches) existingDays.add(Math.floor(t / DAY_MS));
+	if (existingDays.size >= targetDays) return events;
+
+	const minMs = Math.min(...allTimes);
+	const maxMs = Math.max(...allTimes);
+	const firstDay = Math.floor(minMs / DAY_MS);
+	const lastDay = Math.floor(maxMs / DAY_MS);
+
+	const candidateDays = [];
+	for (let d = firstDay; d <= lastDay; d++) {
+		if (!existingDays.has(d)) candidateDays.push(d);
+	}
+	const need = targetDays - existingDays.size;
+	if (candidateDays.length === 0 || need <= 0) return events;
+
+	const chance = getChance();
+	// Use chance.pickset for a unique-without-replacement sample from the
+	// candidate day pool. If `need` exceeds candidates, fall back to all.
+	const pickCount = Math.min(need, candidateDays.length);
+	const picked = chance.pickset(candidateDays, pickCount);
+
+	for (const day of picked) {
+		// Pick a random ms within this UTC day. Clamp to active window.
+		const dayStart = day * DAY_MS;
+		const dayEnd = dayStart + DAY_MS - 1;
+		const lo = Math.max(dayStart, minMs);
+		const hi = Math.min(dayEnd, maxMs);
+		const newMs = lo >= hi ? lo : chance.integer({ min: lo, max: hi });
+		const clone = { ...template, ...overrides };
+		writeTime(clone, newMs);
+		delete clone.insert_id;
+		events.push(clone);
+	}
+
+	return events;
+}
+

package/lib/orchestrators/mixpanel-sender.js

@@ -63,6 +63,21 @@ export async function sendToMixpanel(context) {
 		workers: 35
 	};
 
+	const hasProgressCb = typeof config.onProgress === 'function';
+	function makeProgressCallback(total) {
+		if (!hasProgressCb) return undefined;
+		return (recordType, processed, requests, eps, bytesProcessed) => {
+			context.reportProgress({
+				phase: "import",
+				recordType,
+				processed,
+				total,
+				eps,
+				bytesProcessed
+			});
+		};
+	}
+
 	log(`\n${'─'.repeat(50)}`);
 	log(`  Importing data to Mixpanel (${region})`);
 	log(`${'─'.repeat(50)}\n`);
@@ -76,9 +91,11 @@ export async function sendToMixpanel(context) {
 			const files = eventData.getWrittenFiles();
 			if (files.length > 0) eventDataToImport = files;
 		}
+		const eventTotal = Array.isArray(eventDataToImport) ? eventDataToImport.length : 0;
 		const imported = await mp(creds, eventDataToImport, {
 			recordType: "event",
 			...commonOpts,
+			progressCallback: makeProgressCallback(eventTotal),
 		});
 		log(`  -> ${comma(imported.success)} events sent\n`);
 		importResults.events = imported;
@@ -93,9 +110,11 @@ export async function sendToMixpanel(context) {
 			const files = userProfilesData.getWrittenFiles();
 			if (files.length > 0) userProfilesToImport = files;
 		}
+		const userTotal = Array.isArray(userProfilesToImport) ? userProfilesToImport.length : 0;
 		const imported = await mp(creds, userProfilesToImport, {
 			recordType: "user",
 			...commonOpts,
+			progressCallback: makeProgressCallback(userTotal),
 		});
 		log(`  -> ${comma(imported.success)} user profiles sent\n`);
 		importResults.users = imported;
@@ -110,9 +129,11 @@ export async function sendToMixpanel(context) {
 			const files = adSpendData.getWrittenFiles();
 			if (files.length > 0) adSpendDataToImport = files;
 		}
+		const adTotal = Array.isArray(adSpendDataToImport) ? adSpendDataToImport.length : 0;
 		const imported = await mp(creds, adSpendDataToImport, {
 			recordType: "event",
 			...commonOpts,
+			progressCallback: makeProgressCallback(adTotal),
 		});
 		log(`  -> ${comma(imported.success)} ad spend events sent\n`);
 		importResults.adSpend = imported;
@@ -131,10 +152,12 @@ export async function sendToMixpanel(context) {
 				const files = groupEntity.getWrittenFiles();
 				if (files.length > 0) groupProfilesToImport = files;
 			}
+			const groupTotal = Array.isArray(groupProfilesToImport) ? groupProfilesToImport.length : 0;
 			const imported = await mp({ token, groupKey }, groupProfilesToImport, {
 				recordType: "group",
 				...commonOpts,
 				groupKey,
+				progressCallback: makeProgressCallback(groupTotal),
 			});
 			log(`  -> ${comma(imported.success)} ${groupKey} profiles sent\n`);
 			importResults.groups.push(imported);
@@ -150,9 +173,11 @@ export async function sendToMixpanel(context) {
 			const files = groupEventData.getWrittenFiles();
 			if (files.length > 0) groupEventDataToImport = files;
 		}
+		const groupEvTotal = Array.isArray(groupEventDataToImport) ? groupEventDataToImport.length : 0;
 		const imported = await mp(creds, groupEventDataToImport, {
 			recordType: "event",
 			...commonOpts,
+			progressCallback: makeProgressCallback(groupEvTotal),
 		});
 		log(`  -> ${comma(imported.success)} group events sent\n`);
 		importResults.groupEvents = imported;
@@ -197,6 +222,7 @@ export async function sendToMixpanel(context) {
 				}
 
 				try {
+					const scdTotal = Array.isArray(scdDataToImport) ? scdDataToImport.length : 0;
 					const imported = await mp(
 						{
 							token,
@@ -205,7 +231,7 @@ export async function sendToMixpanel(context) {
 							project: projectId
 						},
 						scdDataToImport,
-						options
+						{ ...options, progressCallback: makeProgressCallback(scdTotal) }
 					);
 					log(`  -> ${comma(imported.success)} ${scdKey} SCD entries sent\n`);
 					importResults[`${scdKey}_scd`] = imported;