@ak--47/dungeon-master 1.2.0 → 1.2.1

package/dungeons/vertical/rpg.js

@@ -1,14 +1,21 @@
+// ── TWEAK THESE ──
+const SEED = "harness-gaming";
+const num_days = 100;
+const num_users = 5_000;
+const avg_events_per_user = 120;
+let token = "your-mixpanel-token";
+
+// ── env overrides ──
+if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
+
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc.js";
 import "dotenv/config";
 import * as u from "../../lib/utils/utils.js";
 import * as v from "ak-tools";
 
-const SEED = "harness-gaming";
 dayjs.extend(utc);
 const chance = u.initChance(SEED);
-const num_users = 5_000;
-const days = 100;
 
 /** @typedef  {import("../../types").Dungeon} Config */
 
@@ -164,10 +171,10 @@ const itemIds = v.range(1, 301).map(n => `item_${v.uid(7)}`);
 
 /** @type {Config} */
 const config = {
-	token: "",
+	token,
 	seed: SEED,
-	numDays: days,
-	numEvents: num_users * 120,
+	numDays: num_days,
+	numEvents: num_users * avg_events_per_user,
 	numUsers: num_users,
 	hasAnonIds: false,
 	hasSessionIds: true,
@@ -519,7 +526,7 @@ const config = {
 	],
 
 	superProps: {
-		platform: [
+		Platform: [
 			"PC",
 			"Mac",
 			"PlayStation",
@@ -562,6 +569,20 @@ const config = {
 			"Ranger",
 			"Paladin"
 		],
+		Platform: [
+			"PC",
+			"Mac",
+			"PlayStation",
+			"Xbox",
+			"Switch"
+		],
+		graphics_quality: [
+			"Low",
+			"Medium",
+			"High",
+			"Ultra"
+		],
+		subscription_tier: ["Free", "Free", "Free", "Premium", "Elite"],
 	},
 
 	groupKeys: [
@@ -595,7 +616,7 @@ const config = {
 	 */
 	hook: function (record, type, meta) {
 		const NOW = dayjs();
-		const DATASET_START = NOW.subtract(days, 'days');
+		const DATASET_START = NOW.subtract(num_days, 'days');
 		const CURSED_WEEK_START = DATASET_START.add(40, 'days');
 		const CURSED_WEEK_END = DATASET_START.add(47, 'days');
 		const LEGENDARY_WEAPON_RELEASE = DATASET_START.add(45, 'days');
@@ -642,6 +663,15 @@ const config = {
 		// Hook #3, #4, #5, #6, #1: EVERYTHING - Complex behavioral patterns
 		if (type === "everything") {
 			const userEvents = record;
+			const profile = meta.profile;
+
+			// Stamp superProps from profile for consistency
+			userEvents.forEach(e => {
+				e.Platform = profile.Platform;
+				e.graphics_quality = profile.graphics_quality;
+				e.subscription_tier = profile.subscription_tier;
+			});
+
 			const firstEventTime = userEvents.length > 0 ? dayjs(userEvents[0].time) : null;
 
 			// Track user behaviors

package/dungeons/vertical/sass.js

@@ -1,14 +1,21 @@
+// ── TWEAK THESE ──
+const SEED = "harness-sass";
+const num_days = 100;
+const num_users = 5_000;
+const avg_events_per_user = 120;
+let token = "your-mixpanel-token";
+
+// ── env overrides ──
+if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
+
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc.js";
 import "dotenv/config";
 import * as u from "../../lib/utils/utils.js";
 import * as v from "ak-tools";
 
-const SEED = "harness-sass";
 dayjs.extend(utc);
 const chance = u.initChance(SEED);
-const num_users = 5_000;
-const days = 100;
 
 /** @typedef  {import("../../types").Dungeon} Config */
 
@@ -248,10 +255,10 @@ const failedDeployUsers = new Map();
 
 /** @type {Config} */
 const config = {
-	token: "",
+	token,
 	seed: SEED,
-	numDays: days,
-	numEvents: num_users * 120,
+	numDays: num_days,
+	numEvents: num_users * avg_events_per_user,
 	numUsers: num_users,
 	hasAnonIds: false,
 	hasSessionIds: true,
@@ -547,6 +554,8 @@ const config = {
 		annual_contract_value: [0],
 		customer_success_manager: [false],
 		customer_health_score: u.weighNumRange(1, 100),
+		plan_tier: ["free", "free", "team", "team", "business", "enterprise"],
+		cloud_provider: ["aws", "gcp", "azure", "multi_cloud"],
 	},
 
 	groupKeys: [
@@ -580,7 +589,7 @@ const config = {
 	 */
 	hook: function (record, type, meta) {
 		const NOW = dayjs();
-		const DATASET_START = NOW.subtract(days, "days");
+		const DATASET_START = NOW.subtract(num_days, "days");
 
 		// ─────────────────────────────────────────────────────────────
 		// Hook #1: END-OF-QUARTER SPIKE (event)
@@ -698,6 +707,14 @@ const config = {
 		// ─────────────────────────────────────────────────────────────
 		if (type === "everything") {
 			const userEvents = record;
+			const profile = meta.profile;
+
+			// Stamp superProps from profile for consistency
+			userEvents.forEach(e => {
+				e.plan_tier = profile.plan_tier;
+				e.cloud_provider = profile.cloud_provider;
+			});
+
 			if (userEvents && userEvents.length > 0) {
 				const firstEvent = userEvents[0];
 				const idHash = String(firstEvent.user_id || firstEvent.device_id).split("").reduce((acc, char) => acc + char.charCodeAt(0), 0);

package/dungeons/vertical/social.js

@@ -1,14 +1,21 @@
+// ── TWEAK THESE ──
+const SEED = "harness-social";
+const num_days = 100;
+const num_users = 5_000;
+const avg_events_per_user = 120;
+let token = "your-mixpanel-token";
+
+// ── env overrides ──
+if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
+
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc.js";
 import "dotenv/config";
 import * as u from "../../lib/utils/utils.js";
 import * as v from "ak-tools";
 
-const SEED = "harness-social";
 dayjs.extend(utc);
 const chance = u.initChance(SEED);
-const num_users = 5_000;
-const days = 100;
 
 /** @typedef  {import("../../types").Dungeon} Config */
 
@@ -162,10 +169,10 @@ const postIds = v.range(1, 1001).map(n => `post_${v.uid(8)}`);
 
 /** @type {Config} */
 const config = {
-	token: "",
+	token,
 	seed: SEED,
-	numDays: days,
-	numEvents: num_users * 120,
+	numDays: num_days,
+	numEvents: num_users * avg_events_per_user,
 	numUsers: num_users,
 	hasAnonIds: false,
 	hasSessionIds: true,
@@ -445,6 +452,8 @@ const config = {
 	},
 
 	userProps: {
+		app_version: ["4.0", "4.1", "4.2", "4.3", "5.0"],
+		account_type: ["personal", "creator", "business"],
 		"follower_count": u.weighNumRange(0, 10000, 0.2, 50),
 		"following_count": u.weighNumRange(0, 5000, 0.3, 100),
 		"bio_length": u.weighNumRange(0, 160),
@@ -469,7 +478,7 @@ const config = {
 
 	hook: function (record, type, meta) {
 		const NOW = dayjs();
-		const DATASET_START = NOW.subtract(days, 'days');
+		const DATASET_START = NOW.subtract(num_days, 'days');
 		const ALGORITHM_CHANGE_DAY = DATASET_START.add(45, 'days');
 		const REENGAGEMENT_START = DATASET_START.add(30, 'days');
 
@@ -529,6 +538,13 @@ const config = {
 			const userEvents = record;
 			if (!userEvents || userEvents.length === 0) return record;
 
+			// Stamp superProps from profile for consistency
+			const profile = meta.profile;
+			userEvents.forEach(e => {
+				e.app_version = profile.app_version;
+				e.account_type = profile.account_type;
+			});
+
 			// Tracking variables for user patterns
 			let postCreatedCount = 0;
 			let followReceivedCount = 0;

package/dungeons/vertical/travel-schema.json

@@ -530,7 +530,7 @@
     }
   ],
   "superProps": {
-    "platform": [
+    "Platform": [
       "ios",
       "android",
       "web"

package/dungeons/vertical/travel.js

@@ -1,16 +1,23 @@
+// ── TWEAK THESE ──
+const SEED = "dm4-travel";
+const num_days = 100;
+const num_users = 5_000;
+const avg_events_per_user = 120;
+let token = "your-mixpanel-token";
+
+// ── env overrides ──
+if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
+
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc.js";
 import "dotenv/config";
 import * as u from "../../lib/utils/utils.js";
 import * as v from "ak-tools";
 
-const SEED = "dm4-travel";
 dayjs.extend(utc);
 const chance = u.initChance(SEED);
-const num_users = 5_000;
-const days = 100;
 const NOW = dayjs();
-const DATASET_START = NOW.subtract(days, "days");
+const DATASET_START = NOW.subtract(num_days, "days");
 
 /** @typedef  {import("../../types").Dungeon} Config */
 
@@ -164,10 +171,10 @@ const destinationCities = ["New York", "London", "Paris", "Tokyo", "Barcelona",
  * with consistent, high-frequency booking patterns.
  *
  * ───────────────────────────────────────────────────────────────
- * 8. REPEAT DESTINATION CLUSTERING (funnel-pre hook)
+ * 8. REPEAT DESTINATION CLUSTERING (everything hook — event filtering)
  * ───────────────────────────────────────────────────────────────
- * PATTERN: Business travelers convert 1.3x better through the
- * search-to-book funnel (repeat bookings are habitual).
+ * PATTERN: Non-business/luxury users have ~25% of "booking completed"
+ * events dropped, simulating lower funnel conversion for casual segments.
  *
  * HOW TO FIND IT IN MIXPANEL:
  *   Report 1: Conversion by Segment
@@ -197,10 +204,10 @@ const destinationCities = ["New York", "London", "Paris", "Tokyo", "Barcelona",
 
 /** @type {Config} */
 const config = {
-	token: "",
+	token,
 	seed: SEED,
-	numDays: days,
-	numEvents: num_users * 120,
+	numDays: num_days,
+	numEvents: num_users * avg_events_per_user,
 	numUsers: num_users,
 	hasAnonIds: false,
 	hasSessionIds: true,
@@ -445,7 +452,7 @@ const config = {
 
 	// ── SuperProps ──────────────────────────────────────────
 	superProps: {
-		platform: ["ios", "android", "web", "web"],
+		Platform: ["ios", "android", "web", "web"],
 		membership_tier: ["standard", "standard", "standard", "gold", "platinum"],
 	},
 
@@ -456,6 +463,8 @@ const config = {
 		company_name: ["none"],
 		preferred_destination: chance.pickone.bind(chance, destinationCities),
 		avg_budget_per_night: u.weighNumRange(50, 400, 0.4, 150),
+		Platform: ["ios", "android", "web", "web"],
+		membership_tier: ["standard", "standard", "standard", "gold", "platinum"],
 	},
 
 	// ── Personas ──────────────────────────────────
@@ -632,14 +641,10 @@ const config = {
 		}
 
 		// ── HOOK 8: REPEAT DESTINATION CLUSTERING (funnel-pre) ─
+		// conversionRate modifications moved to everything hook (event filtering)
+		// to avoid dilution by organic events
 		if (type === "funnel-pre") {
-			if (meta && meta.profile) {
-				if (meta.profile.customer_segment === "business_traveler") {
-					record.conversionRate = Math.min(record.conversionRate * 1.3, 90);
-				} else if (meta.profile.customer_segment === "luxury_seeker") {
-					record.conversionRate = Math.min(record.conversionRate * 1.15, 85);
-				}
-			}
+			// prop-setting only; no conversionRate changes
 		}
 
 		// ── HOOK 1: WEEKEND LEISURE SURGE (event) ────────────
@@ -672,6 +677,33 @@ const config = {
 			const events = record;
 			if (!events.length) return record;
 
+			const profile = meta.profile;
+
+			// ─── Stamp superProps from profile (consistent per user) ───
+			const stampPlatform = profile && profile.Platform ? profile.Platform : undefined;
+			const stampTier = profile && profile.membership_tier ? profile.membership_tier : undefined;
+			if (stampPlatform || stampTier) {
+				events.forEach(e => {
+					if (stampPlatform) e.Platform = stampPlatform;
+					if (stampTier) e.membership_tier = stampTier;
+				});
+			}
+
+			// ─── Bug 2 fix: Repeat destination clustering conversion filtering ───
+			// Drop ~25% of "booking completed" events for users who are NOT
+			// business_traveler or luxury_seeker to simulate their lower funnel
+			// conversion (was conversionRate * 1.3 / 1.15 in funnel-pre)
+			const segment = profile && profile.customer_segment;
+			if (segment !== "business_traveler" && segment !== "luxury_seeker") {
+				for (let i = events.length - 1; i >= 0; i--) {
+					if (events[i].event === "booking completed") {
+						if (chance.bool({ likelihood: 25 })) {
+							events.splice(i, 1);
+						}
+					}
+				}
+			}
+
 			// ── HOOK 3: LOYALTY TIER UPGRADE PATH ────────────
 			let bookingCount = 0;
 			events.forEach(e => { if (e.event === "booking completed") bookingCount++; });
@@ -694,7 +726,6 @@ const config = {
 			}
 
 			// ── HOOK 5: UPSELL SUCCESS BY SEGMENT ────────────
-			const profile = meta.profile;
 			if (profile && profile.customer_segment === "luxury_seeker") {
 				const templateUpgrade = events.find(e => e.event === "room upgrade selected");
 				if (templateUpgrade) {

package/index.js

@@ -109,6 +109,9 @@ async function DUNGEON_MASTER(input, overrides = {}) {
 			const textConfig = await loadFromText(value);
 			return await runDungeon({ ...textConfig, ...overrides });
 		}
+
+		default:
+			throw new Error(`Unexpected input type: ${type}`);
 	}
 }
 

package/lib/core/config-validator.js

@@ -24,7 +24,6 @@ const FIXED_NOW = dayjs('2024-02-02').unix();
 function inferFunnels(events) {
 	const createdFunnels = [];
 	const firstEvents = events.filter((e) => e.isFirstEvent).map((e) => e.event);
-	const strictEvents = events.filter((e) => e.isStrictEvent).map((e) => e.event);
 	const usageEvents = events
 		.filter((e) => !e.isFirstEvent && !e.isStrictEvent)
 		.map((e) => e.event);
@@ -106,6 +105,7 @@ export function validateDungeonConfig(config) {
 		lookupTables = [],
 		hasAnonIds = false,
 		hasSessionIds = false,
+		sessionTimeout = 30,
 		format = "csv",
 		token = null,
 		region = "US",
@@ -140,6 +140,14 @@ export function validateDungeonConfig(config) {
 		concurrency = 1;
 	}
 
+	// Throw if token is the placeholder and nothing will be written to disk
+	if (token === "your-mixpanel-token" && !writeToDisk) {
+		throw new Error(
+			"No Mixpanel token set and writeToDisk is false — nothing useful will happen.\n" +
+			"Either set process.env.MP_TOKEN, change the token in the dungeon file, or set writeToDisk to true."
+		);
+	}
+
 	// Auto-enable batch mode for large datasets to prevent OOM
 	if (numEvents >= 2_000_000 && config.batchSize === undefined) {
 		batchSize = 1_000_000;
@@ -148,7 +156,9 @@ export function validateDungeonConfig(config) {
 
 	// Ensure defaults for deep objects
 	if (!config.superProps) config.superProps = superProps;
-	if (!config.userProps || Object.keys(config?.userProps || {})) config.userProps = userProps;
+	if (!config.userProps || Object.keys(config.userProps).length === 0) {
+		userProps = { spiritAnimal: chance.animal.bind(chance) };
+	}
 
 	// Setting up "TIME"
 	if (epochStart && !numDays) numDays = dayjs.unix(epochEnd).diff(dayjs.unix(epochStart), "day");
@@ -356,6 +366,7 @@ export function validateDungeonConfig(config) {
 		lookupTables,
 		hasAnonIds,
 		hasSessionIds,
+		sessionTimeout: (typeof sessionTimeout === 'number' && sessionTimeout > 0) ? sessionTimeout : 30,
 		format,
 		token,
 		region,

package/lib/generators/events.js

@@ -116,14 +116,12 @@ export async function makeEvent(
         eventTemplate.time = dayjs.unix(Math.min(shiftedTimestamp, context.MAX_TIME)).toISOString();
     }
 
-    // Add anonymous and session identifiers
+    // Add anonymous identifiers
     if (anonymousIds.length) {
         eventTemplate.device_id = u.pickRandom(anonymousIds);
     }
-    
-    if (sessionIds.length) {
-        eventTemplate.session_id = u.pickRandom(sessionIds);
-    }
+
+    // Session IDs are assigned post-hoc in user-loop.js based on temporal gaps
 
     // Sometimes add user_id (for attribution modeling)
     if (!isFirstEvent && chance.bool({ likelihood: 42 })) {

package/lib/orchestrators/user-loop.js

@@ -359,6 +359,8 @@ export async function userLoop(context) {
 
 			// ALL SUBSEQUENT EVENTS (funnels for converted users, standalone for all)
 			let userChurned = false;
+			const sessionTimeout = config.sessionTimeout || 30;
+
 			while (numEventsPreformed < numEventsThisUserWillPreform && !cancelled) {
 				let newEvents;
 				if (usageFunnels.length && userConverted) {
@@ -448,6 +450,24 @@ export async function userLoop(context) {
 				}
 			}
 
+			// Session clustering: redistribute events into temporal bursts, then assign session IDs
+			if (hasSessionIds && usersEvents.length > 0) {
+				const soupCfg = /** @type {import('../../types').SoupConfig} */ (config.soup) || {};
+				const defaultPeaks = Math.max(5, (config.numDays || 30) * 2);
+				const { mean: soupMean = 0, deviation: soupDev = 2, peaks: soupPeaks = defaultPeaks,
+					dayOfWeekWeights: soupDOW, hourOfDayWeights: soupHOD } = soupCfg;
+
+				u.bunchIntoSessions(usersEvents, sessionTimeout, {
+					earliestTime: userFirstEventTime,
+					latestTime: context.FIXED_NOW,
+					peaks: soupPeaks, deviation: soupDev, mean: soupMean,
+					dayOfWeekWeights: soupDOW, hourOfDayWeights: soupHOD,
+					timeShiftSeconds: context.TIME_SHIFT_SECONDS,
+					maxTime: context.MAX_TIME
+				});
+				u.assignSessionIds(usersEvents, sessionTimeout);
+			}
+
 			// Hook for processing all user events (hooks override everything)
 			if (config.hook) {
 				const newEvents = await config.hook(usersEvents, "everything", {

package/lib/utils/utils.js

@@ -1314,15 +1314,7 @@ function person(userId, bornDaysAgo = 30, isAnonymous = false, hasAvatar = false
 
 	if (!hasAnonIds) delete user.anonymousIds;
 
-	//session Ids
-	if (hasSessionIds) {
-		const sessionSize = integer(5, 30);
-		for (let i = 0; i < sessionSize; i++) {
-			const sessionId = [uid(5), uid(5), uid(5), uid(5)].join("-");
-			user.sessionIds.push(sessionId);
-		}
-	}
-
+	// Session IDs are now assigned post-hoc in user-loop.js based on temporal gaps
 	if (!hasSessionIds) delete user.sessionIds;
 
 	return user;
@@ -1436,6 +1428,131 @@ function deepClone(thing, opts) {
 };
 
 
+/**
+ * Generates a session ID in the standard format
+ * @returns {string} Session ID like "xxxxx-xxxxx-xxxxx-xxxxx"
+ */
+function generateSessionId() {
+	return [uid(5), uid(5), uid(5), uid(5)].join("-");
+}
+
+/**
+ * Redistributes events into temporal clusters (sessions).
+ *
+ * Algorithm:
+ * 1. Sort events by time
+ * 2. Determine number of sessions (total events / avg events per session)
+ * 3. Generate session anchor times using TimeSoup
+ * 4. Assign events round-robin to sessions
+ * 5. Within each session, retime events with tight spacing (5-300s apart)
+ * 6. Regenerate insert_ids for retimed events
+ * 7. Re-sort by time
+ *
+ * Mutates events in place. Does NOT assign session_id (call assignSessionIds after).
+ *
+ * @param {Object[]} events - Array of event objects with .time (ISO string)
+ * @param {number} timeoutMinutes - Session timeout in minutes (used to determine intra-session spacing)
+ * @param {Object} soupParams - Parameters for TimeSoup anchor generation
+ */
+function bunchIntoSessions(events, timeoutMinutes, soupParams) {
+	if (events.length < 2) return;
+
+	const chance = getChance();
+	const { earliestTime, latestTime, peaks, deviation, mean,
+		dayOfWeekWeights, hourOfDayWeights, timeShiftSeconds, maxTime } = soupParams;
+
+	// Sort by time first
+	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
+
+	// Determine number of sessions: target 3-8 events per session
+	const eventsPerSession = chance.integer({ min: 3, max: 8 });
+	const numSessions = Math.max(1, Math.ceil(events.length / eventsPerSession));
+
+	// Generate session anchor times using TimeSoup
+	const anchors = [];
+	for (let i = 0; i < numSessions; i++) {
+		const soupTime = TimeSoup(earliestTime, latestTime, peaks, deviation, mean,
+			dayOfWeekWeights, hourOfDayWeights, timeShiftSeconds);
+		anchors.push(soupTime + timeShiftSeconds); // shifted to present time
+	}
+	anchors.sort((a, b) => a - b);
+
+	// Distribute events across sessions round-robin (preserving original order → temporal order)
+	const sessionBuckets = anchors.map(() => []);
+	for (let i = 0; i < events.length; i++) {
+		const bucketIndex = Math.min(i % numSessions, numSessions - 1);
+		sessionBuckets[bucketIndex].push(events[i]);
+	}
+
+	// Retime events within each session
+	let writeIndex = 0;
+	for (let s = 0; s < numSessions; s++) {
+		const bucket = sessionBuckets[s];
+		if (bucket.length === 0) continue;
+
+		let currentTime = anchors[s];
+		for (let e = 0; e < bucket.length; e++) {
+			const ev = bucket[e];
+			const clampedTime = Math.min(currentTime, maxTime);
+
+			ev.time = dayjs.unix(clampedTime).toISOString();
+			// Regenerate insert_id to match new time
+			const distinctId = ev.user_id || ev.device_id || ev.distinct_id || '';
+			ev.insert_id = quickHash(`${ev.event}-${ev.time}-${distinctId}`);
+
+			if (currentTime > maxTime) {
+				ev._drop = true;
+			}
+
+			// Advance time within session: 5-300 seconds (5s to 5min)
+			currentTime += chance.integer({ min: 5, max: 300 });
+		}
+	}
+
+	// Re-sort by time
+	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
+}
+
+/**
+ * Assigns session IDs to a chronologically sorted array of events.
+ * A new session starts when:
+ *   - Gap between consecutive events exceeds timeoutMinutes
+ *   - Session duration exceeds 24 hours
+ *
+ * Events MUST be sorted by time before calling this function.
+ * Mutates events in place (adds session_id property).
+ *
+ * @param {Object[]} events - Sorted array of event objects with .time (ISO string)
+ * @param {number} timeoutMinutes - Session timeout in minutes (default 30)
+ * @returns {Object[]} Same array, with session_id added to each event
+ */
+function assignSessionIds(events, timeoutMinutes = 30) {
+	if (!events.length) return events;
+
+	const timeoutMs = timeoutMinutes * 60 * 1000;
+	const maxSessionMs = 24 * 60 * 60 * 1000;
+
+	let currentSessionId = generateSessionId();
+	let sessionStartMs = new Date(events[0].time).getTime();
+	let lastEventMs = sessionStartMs;
+
+	for (const event of events) {
+		const eventMs = new Date(event.time).getTime();
+		const gapFromLast = eventMs - lastEventMs;
+		const sessionDuration = eventMs - sessionStartMs;
+
+		if (gapFromLast > timeoutMs || sessionDuration > maxSessionMs) {
+			currentSessionId = generateSessionId();
+			sessionStartMs = eventMs;
+		}
+
+		event.session_id = currentSessionId;
+		lastEventMs = eventMs;
+	}
+
+	return events;
+}
+
 export {
 	pick,
 	date,
@@ -1486,4 +1603,7 @@ export {
 	wrapFunc,
 	bytesHuman,
 	formatDuration,
+	generateSessionId,
+	assignSessionIds,
+	bunchIntoSessions,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.2.0",
+	"version": "1.2.1",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",

package/types.d.ts

@@ -72,8 +72,10 @@ export interface Dungeon {
     verbose?: boolean;
     /** If true, users get anonymous device IDs in addition to distinct_id. */
     hasAnonIds?: boolean;
-    /** If true, users get session IDs attached to events. */
+    /** If true, users get session IDs attached to events based on temporal clustering. */
     hasSessionIds?: boolean;
+    /** Session timeout in minutes. Events with gaps exceeding this start a new session. Default: 30. Only used when hasSessionIds is true. */
+    sessionTimeout?: number;
     /** If true, auto-generates funnels from the events array in addition to any explicit funnels. */
     alsoInferFunnels?: boolean;
     /** Restrict all location data to a single country (e.g., "US", "GB"). */
@@ -231,8 +233,8 @@ export interface hookArrayOptions<T> {
  * an enriched array is an array that has a hookPush method that can be used to transform-then-push items into the array
  */
 export interface HookedArray<T> extends Array<T> {
-    hookPush: (item: T | T[], ...meta: any[]) => any;
-    flush: () => void;
+    hookPush: (item: T | T[], ...meta: any[]) => Promise<any>;
+    flush: () => Promise<void>;
     getWriteDir: () => string;
     getWritePath: () => string;
     [key: string]: any;