@ak--47/dungeon-master 1.0.0

package/lib/generators/adspend.js

@@ -0,0 +1,132 @@
+/**
+ * Ad Spend generator module
+ * Creates realistic advertising spend events with UTM parameters and metrics
+ */
+
+/** @typedef {import('../../types').Context} Context */
+
+import dayjs from "dayjs";
+import * as u from "../utils/utils.js";
+
+/**
+ * Creates ad spend events for a given day and campaign configurations
+ * @param {Context} context - Context object containing config, defaults, etc.
+ * @param {string} day - ISO date string for the ad spend day
+ * @param {Array} campaigns - Array of campaign configurations (optional, uses context.campaigns if not provided)
+ * @returns {Promise<Array>} Array of ad spend event objects
+ */
+export async function makeAdSpend(context, day, campaigns = null) {
+    // Update operation counter
+    context.incrementOperations();
+
+    // Use campaigns from context if not provided
+    const campaignConfigs = campaigns || context.campaigns;
+
+    if (!campaignConfigs || campaignConfigs.length === 0) {
+        return [];
+    }
+
+    const chance = u.getChance();
+    const adSpendEvents = [];
+
+    for (const network of campaignConfigs) {
+        const networkCampaigns = network.utm_campaign;
+
+        for (const campaign of networkCampaigns) {
+            // Skip organic campaigns
+            if (campaign === "$organic") continue;
+
+            // Generate realistic ad spend metrics
+            const adSpendEvent = createAdSpendEvent(network, campaign, day, chance);
+            adSpendEvents.push(adSpendEvent);
+        }
+    }
+
+    return adSpendEvents;
+}
+
+/**
+ * Creates a single ad spend event with realistic metrics
+ * @param {Object} network - Network configuration object
+ * @param {string} campaign - Campaign name
+ * @param {string} day - ISO date string
+ * @param {Object} chance - Chance.js instance
+ * @returns {Object} Ad spend event object
+ */
+function createAdSpendEvent(network, campaign, day, chance) {
+    // Generate realistic cost
+    const cost = chance.floating({ min: 10, max: 250, fixed: 2 });
+
+    // Generate realistic CPC and CTR
+    const avgCPC = chance.floating({ min: 0.33, max: 2.00, fixed: 4 });
+    const avgCTR = chance.floating({ min: 0.05, max: 0.25, fixed: 4 });
+
+    // Calculate derived metrics
+    const clicks = Math.floor(cost / avgCPC);
+    const impressions = Math.floor(clicks / avgCTR);
+    const views = Math.floor(impressions * avgCTR);
+
+    // Generate UTM parameters
+    const utm_medium = u.choose(u.pickAWinner(network.utm_medium)());
+    const utm_content = u.choose(u.pickAWinner(network.utm_content)());
+    const utm_term = u.choose(u.pickAWinner(network.utm_term)());
+
+    // Create unique identifiers
+    const id = network.utm_source[0] + '-' + campaign;
+    const uid = u.quickHash(id);
+
+    return {
+        event: "$ad_spend",
+        time: day,
+        // source: 'dm4',
+        utm_campaign: campaign,
+        campaign_id: id,
+        insert_id: uid,
+        network: network.utm_source[0].toUpperCase(),
+        distinct_id: network.utm_source[0].toUpperCase(),
+        utm_source: network.utm_source[0],
+        utm_medium,
+        utm_content,
+        utm_term,
+        clicks,
+        views,
+        impressions,
+        cost,
+        date: dayjs(day).format("YYYY-MM-DD"),
+    };
+}
+
+/**
+ * Validates campaign configuration
+ * @param {Array} campaigns - Campaign configurations to validate
+ * @returns {boolean} True if valid, throws error if invalid
+ */
+export function validateCampaigns(campaigns) {
+    if (!Array.isArray(campaigns)) {
+        throw new Error("Campaigns must be an array");
+    }
+
+    for (const network of campaigns) {
+        if (!network.utm_source || !Array.isArray(network.utm_source)) {
+            throw new Error("Each campaign network must have utm_source array");
+        }
+
+        if (!network.utm_campaign || !Array.isArray(network.utm_campaign)) {
+            throw new Error("Each campaign network must have utm_campaign array");
+        }
+
+        if (!network.utm_medium || !Array.isArray(network.utm_medium)) {
+            throw new Error("Each campaign network must have utm_medium array");
+        }
+
+        if (!network.utm_content || !Array.isArray(network.utm_content)) {
+            throw new Error("Each campaign network must have utm_content array");
+        }
+
+        if (!network.utm_term || !Array.isArray(network.utm_term)) {
+            throw new Error("Each campaign network must have utm_term array");
+        }
+    }
+
+    return true;
+}

package/lib/generators/events.js

@@ -0,0 +1,271 @@
+/**
+ * Event generator module
+ * Creates individual Mixpanel events with realistic properties and timing
+ */
+
+/** @typedef {import('../../types').Dungeon} Config */
+/** @typedef {import('../../types').EventConfig} EventConfig */
+/** @typedef {import('../../types').ValueValid} ValueValid */
+/** @typedef {import('../../types').EventSchema} EventSchema */
+/** @typedef {import('../../types').Context} Context */
+
+import dayjs from "dayjs";
+import * as u from "../utils/utils.js";
+import { dataLogger as logger } from "../utils/logger.js";
+
+/**
+ * Creates a Mixpanel event with a flat shape
+ * @param {Context} context - Context object containing config, defaults, etc.
+ * @param {string} distinct_id - User identifier
+ * @param {number} earliestTime - Unix timestamp for earliest possible event time
+ * @param {Object} chosenEvent - Event configuration object
+ * @param {string[]} [anonymousIds] - Array of anonymous/device IDs
+ * @param {string[]} [sessionIds] - Array of session IDs
+ * @param {Object} [superProps] - Super properties to add to event
+ * @param {Array} [groupKeys] - Group key configurations
+ * @param {boolean} [isFirstEvent] - Whether this is the user's first event
+ * @param {boolean} [skipDefaults] - Whether to skip adding default properties
+ * @returns {Promise<Object>} Generated event object
+ */
+export async function makeEvent(
+    context, 
+    distinct_id, 
+    earliestTime, 
+    chosenEvent, 
+    anonymousIds = [], 
+    sessionIds = [], 
+    superProps = {}, 
+    groupKeys = [], 
+    isFirstEvent = false, 
+    skipDefaults = false
+) {
+    // Validate required parameters
+    if (!distinct_id) throw new Error("no distinct_id");
+    if (!earliestTime) throw new Error("no earliestTime");
+    if (!chosenEvent) throw new Error("no chosenEvent");
+
+    // Update context metrics
+    context.incrementOperations();
+    context.incrementEvents();
+
+    const { config, defaults } = context;
+    const chance = u.getChance();
+    
+    // Extract soup configuration for time distribution
+    // Dynamic peaks: enough to flatten DOW interference from chunk boundaries
+    const defaultPeaks = Math.max(5, (config.numDays || 30) * 2);
+    const { mean = 0, deviation = 2, peaks = defaultPeaks, dayOfWeekWeights, hourOfDayWeights } = /** @type {import('../../types').SoupConfig} */ (config.soup) || {};
+    
+    // Extract feature flags from config
+    const {
+        hasAndroidDevices = false,
+        hasBrowser = false,
+        hasCampaigns = false,
+        hasDesktopDevices = false,
+        hasIOSDevices = false,
+        hasLocation = false
+    } = config;
+
+    // Create base event template
+    const eventTemplate = {
+        event: chosenEvent.event,
+        // source: "dm4",
+        time: "",
+        insert_id: "",
+    };
+
+    let defaultProps = {};
+
+    // Add default properties based on configuration
+    if (hasLocation) {
+        defaultProps.location = u.pickRandom(defaults.locationsEvents());
+    }
+    
+    if (hasBrowser) {
+        defaultProps.browser = u.choose(defaults.browsers());
+    }
+
+    // Add campaigns with attribution likelihood
+    if (hasCampaigns && chance.bool({ likelihood: 25 })) {
+        defaultProps.campaigns = u.pickRandom(defaults.campaigns());
+    }
+    
+    // PERFORMANCE: Use pre-computed device pool instead of rebuilding every time
+    if (defaults.allDevices.length) {
+        defaultProps.device = u.pickRandom(defaults.allDevices);
+    }
+
+    // Set event time using TimeSoup for realistic distribution
+    if (earliestTime) {
+        let shiftedTimestamp;
+        if (isFirstEvent) {
+            shiftedTimestamp = earliestTime + context.TIME_SHIFT_SECONDS;
+        } else {
+            // TimeSoup returns unix seconds; shift and convert to ISO once
+            const soupTimestamp = u.TimeSoup(earliestTime, context.FIXED_NOW, peaks, deviation, mean, dayOfWeekWeights, hourOfDayWeights, context.TIME_SHIFT_SECONDS);
+            shiftedTimestamp = soupTimestamp + context.TIME_SHIFT_SECONDS;
+        }
+        // Drop events that would land in the future (Mixpanel rewrites these to "now", causing pile-ups)
+        if (shiftedTimestamp > context.MAX_TIME) {
+            eventTemplate._drop = true;
+        }
+        eventTemplate.time = dayjs.unix(Math.min(shiftedTimestamp, context.MAX_TIME)).toISOString();
+    }
+
+    // Add anonymous and session identifiers
+    if (anonymousIds.length) {
+        eventTemplate.device_id = u.pickRandom(anonymousIds);
+    }
+    
+    if (sessionIds.length) {
+        eventTemplate.session_id = u.pickRandom(sessionIds);
+    }
+
+    // Sometimes add user_id (for attribution modeling)
+    if (!isFirstEvent && chance.bool({ likelihood: 42 })) {
+        eventTemplate.user_id = distinct_id;
+    }
+
+    // Ensure we have either user_id or device_id
+    if (!eventTemplate.user_id && !eventTemplate.device_id) {
+        eventTemplate.user_id = distinct_id;
+    }
+
+    // PERFORMANCE: Process properties directly without creating intermediate object
+    // Add custom properties from event configuration
+    if (chosenEvent.properties) {
+        const eventKeys = Object.keys(chosenEvent.properties);
+        for (let i = 0; i < eventKeys.length; i++) {
+            const key = eventKeys[i];
+            try {
+                eventTemplate[key] = u.choose(chosenEvent.properties[key]);
+            } catch (e) {
+                logger.error({ err: e, key, event: chosenEvent.event }, `Error processing property ${key} in ${chosenEvent.event} event`);
+                // Continue processing other properties
+            }
+        }
+    }
+    
+    // Add super properties (override event properties if needed)
+    if (superProps) {
+        const superKeys = Object.keys(superProps);
+        for (let i = 0; i < superKeys.length; i++) {
+            const key = superKeys[i];
+            try {
+                eventTemplate[key] = u.choose(superProps[key]);
+            } catch (e) {
+                logger.error({ err: e, key }, `Error processing super property ${key}`);
+                // Continue processing other properties
+            }
+        }
+    }
+
+    // Add default properties if not skipped
+    if (!skipDefaults) {
+        addDefaultProperties(eventTemplate, defaultProps);
+    }
+
+    // Add group properties
+    addGroupProperties(eventTemplate, groupKeys);
+
+    // Generate unique insert_id
+	const distinctId = eventTemplate.user_id || eventTemplate.device_id || eventTemplate.distinct_id || distinct_id;
+	const tuple = `${eventTemplate.event}-${eventTemplate.time}-${distinctId}`;
+    eventTemplate.insert_id = u.quickHash(tuple);
+
+    // Call hook if configured (before returning the event)
+    const { hook } = config;
+    if (hook) {
+        const hookedEvent = await hook(eventTemplate, "event", { 
+            user: { distinct_id }, 
+            config 
+        });
+        // If hook returns a modified event, use it; otherwise use original
+        if (hookedEvent && typeof hookedEvent === 'object') {
+            return hookedEvent;
+        }
+    }
+
+    // Note: Time shift already applied above during timestamp calculation
+
+    return eventTemplate;
+}
+
+/**
+ * Adds default properties to an event template
+ * Handles complex nested property structures
+ * @param {Object} eventTemplate - Event object to modify
+ * @param {Object} defaultProps - Default properties to add
+ */
+function addDefaultProperties(eventTemplate, defaultProps) {
+    for (const key in defaultProps) {
+        if (Array.isArray(defaultProps[key])) {
+            const choice = u.choose(defaultProps[key]);
+            
+            if (typeof choice === "string") {
+                if (!eventTemplate[key]) eventTemplate[key] = choice;
+            }
+            else if (Array.isArray(choice)) {
+                for (const subChoice of choice) {
+                    if (!eventTemplate[key]) eventTemplate[key] = subChoice;
+                }
+            }
+            else if (typeof choice === "object") {
+                addNestedObjectProperties(eventTemplate, choice);
+            }
+        }
+        else if (typeof defaultProps[key] === "object") {
+            addNestedObjectProperties(eventTemplate, defaultProps[key]);
+        }
+        else {
+            if (!eventTemplate[key]) eventTemplate[key] = defaultProps[key];
+        }
+    }
+}
+
+/**
+ * Adds nested object properties to event template
+ * @param {Object} eventTemplate - Event object to modify
+ * @param {Object} obj - Object with properties to add
+ */
+function addNestedObjectProperties(eventTemplate, obj) {
+    for (const subKey in obj) {
+        if (typeof obj[subKey] === "string") {
+            if (!eventTemplate[subKey]) eventTemplate[subKey] = obj[subKey];
+        }
+        else if (Array.isArray(obj[subKey])) {
+            const subChoice = u.choose(obj[subKey]);
+            if (!eventTemplate[subKey]) eventTemplate[subKey] = subChoice;
+        }
+        else if (typeof obj[subKey] === "object") {
+            for (const subSubKey in obj[subKey]) {
+                if (!eventTemplate[subSubKey]) {
+                    eventTemplate[subSubKey] = obj[subKey][subSubKey];
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Adds group properties to event based on group key configuration
+ * @param {Object} eventTemplate - Event object to modify
+ * @param {Array} groupKeys - Array of group key configurations
+ */
+function addGroupProperties(eventTemplate, groupKeys) {
+    for (const groupPair of groupKeys) {
+        const groupKey = groupPair[0];
+        const groupCardinality = groupPair[1];
+        const groupEvents = groupPair[2] || [];
+
+        // Empty array for group events means all events get the group property
+        if (!groupEvents.length) {
+            eventTemplate[groupKey] = String(u.pick(u.weighNumRange(1, groupCardinality)));
+        }
+
+        // Only add group property if event is in the specified group events
+        if (groupEvents.includes(eventTemplate.event)) {
+            eventTemplate[groupKey] = String(u.pick(u.weighNumRange(1, groupCardinality)));
+        }
+    }
+}