make-mp-data 3.0.6 → 3.1.0

package/README.md

@@ -13,6 +13,30 @@ under the hood, `make-mp-data` is modeling data adherent to match [Mixpanel's da
 
 ## 🚀 Quick Start
 
+### Canonical Usage (v3.1.0+)
+
+Two paths are guaranteed to "just work":
+
+**1. As a CLI — send data to Mixpanel with one flag:**
+
+```bash
+npx make-mp-data --token YOUR_PROJECT_TOKEN
+```
+
+**2. As an ES module — bare `await` call:**
+
+```javascript
+import makeMpData from 'make-mp-data';
+
+// Zero-config: generates events + users, returns them in memory
+const result = await makeMpData({});
+
+// Canonical "just send it": pass a token, data ships to Mixpanel
+await makeMpData({ token: 'YOUR_PROJECT_TOKEN' });
+```
+
+Both paths return a `Result` object with `eventData`, `userProfilesData`, `importResults`, `files`, `eventCount`, `userCount`, and timing info.
+
 ### Basic Usage
 
 Generate events and users, and write them to CSV files:
@@ -87,6 +111,16 @@ Here's a breakdown of the CLI options you can use with `make-mp-data`:
 - `--complex`: create a complex set models including groups, SCD, and lookup tables.
 - `--simple`: create a simple dataset including events, and users
 
+### Custom Dungeon Configs
+
+Pass a path to your own dungeon `.js` file. CLI flags override values from the dungeon — your file provides defaults, the CLI tunes them:
+
+```bash
+npx make-mp-data ./my-dungeon.js --numUsers 500 --token YOUR_TOKEN
+```
+
+CLI flag defaults (like `region`, `concurrency`) **do not** clobber explicit values in your dungeon — only flags you actually pass take effect.
+
 ## ⏱️ TimeSoup — Realistic Time Distributions
 
 TimeSoup controls how events are distributed across time. Out of the box, it produces realistic day-of-week and hour-of-day patterns derived from real Mixpanel data (weekday-heavy, Saturday valley, morning peak).

package/dungeons/capstone/capstone-ic3.js

@@ -0,0 +1,291 @@
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * DATASET OVERVIEW
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * IC3 Capstone — e-commerce dataset for Mixpanel certification.
+ * - 25,000 users over 180 days, ~5M events
+ * - Events: checkout (array-of-object cart), add to cart, view/save items
+ * - Nested product arrays with product_id lookups
+ * - Location, browser, session tracking enabled
+ *
+ * ═══════════════════════════════════════════════════════════════
+ * ANALYTICS HOOKS (1 pattern)
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * 1. EVENT DUPLICATION (everything hook)
+ *    Every user gets ~3-7 random events duplicated, simulating
+ *    real-world duplicate event ingestion that students must
+ *    identify and handle in their analysis.
+ */
+
+import Chance from 'chance';
+let chance = new Chance();
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+dayjs.extend(utc);
+import { uid, comma } from 'ak-tools';
+import { pickAWinner, weighNumRange, date, integer, weighChoices } from "../brain/utils/utils.js";
+
+const videoCategories = ["funny", "educational", "inspirational", "music", "news", "sports", "cooking", "DIY", "travel", "gaming"];
+const spiritAnimals = ["duck", "dog", "otter", "penguin", "cat", "elephant", "lion", "cheetah", "giraffe", "zebra", "rhino", "hippo", "whale", "dolphin", "shark", "octopus", "squid", "jellyfish", "starfish", "seahorse", "crab", "lobster", "shrimp", "clam", "snail", "slug", "butterfly", "moth", "bee", "wasp", "ant", "beetle", "ladybug", "caterpillar", "centipede", "millipede", "scorpion", "spider", "tarantula", "tick", "mite", "mosquito", "fly", "dragonfly", "damselfly", "grasshopper", "cricket", "locust", "mantis", "cockroach", "termite", "praying mantis", "walking stick", "stick bug", "leaf insect", "lacewing", "aphid", "cicada", "thrips", "psyllid", "scale insect", "whitefly", "mealybug", "planthopper", "leafhopper", "treehopper", "flea", "louse", "bedbug", "flea beetle", "weevil", "longhorn beetle", "leaf beetle", "tiger beetle", "ground beetle", "lady beetle", "firefly", "click beetle", "rove beetle", "scarab beetle", "dung beetle", "stag beetle", "rhinoceros beetle", "hercules beetle", "goliath beetle", "jewel beetle", "tortoise beetle"];
+
+/** @type {import('../types.js').Dungeon} */
+const config = {
+	token: "",
+	seed: "IC3 baby!",
+	name: "ic3-capstone",
+	numDays: 180, //how many days worth1 of data
+	numEvents: 5_000_000, //how many events
+	numUsers: 25_000, //how many users
+	format: 'json', //csv or json
+	region: "US",
+	hasAnonIds: true, //if true, anonymousIds are created for each user
+	hasSessionIds: true, //if true, hasSessionIds are created for each user
+	hasAdSpend: false,
+	makeChart: false,
+	hasLocation: true,
+	hasAndroidDevices: false,
+	hasIOSDevices: false,
+	hasDesktopDevices: true,
+	hasBrowser: true,
+	hasCampaigns: false,
+	isAnonymous: false,
+	alsoInferFunnels: false,
+	concurrency: 1,
+	batchSize: 250_000,
+	writeToDisk: true,
+	events: [
+		{
+			event: "checkout",
+			weight: 2,
+			properties: {
+				currency: pickAWinner(["USD", "CAD", "EUR", "BTC", "ETH", "JPY"], 0),
+				coupon: weighChoices(["none", "none", "none", "none", "10%OFF", "20%OFF", "10%OFF", "20%OFF", "30%OFF", "40%OFF", "50%OFF"]),
+				cart: makeProducts()
+			}
+		},
+		{
+			event: "add to cart",
+			weight: 4,
+			properties: {
+				item: makeProducts(1),
+			}
+		},
+		{
+			event: "view item",
+			weight: 8,
+			properties: {
+				item: makeProducts(1)
+			}
+		},
+		{
+			event: "save item",
+			weight: 5,
+			properties: {
+				item: makeProducts(1),
+			}
+		},
+		{
+			event: "page view",
+			weight: 10,
+			properties: {
+				page: ["/", "/help", "/account", "/watch", "/listen", "/product", "/people", "/peace"],
+			}
+		},
+		{
+			event: "watch video",
+			weight: 8,
+			properties: {
+				watchTimeSec: weighNumRange(10, 600, .25),
+			}
+		},
+		{
+			event: "like video",
+			weight: 6,
+			properties: {
+
+			}
+		},
+		{
+			event: "dislike video",
+			weight: 4,
+			properties: {
+
+			}
+		},
+		{
+			event: "sign up",
+			weight: 1,
+			isFirstEvent: true,
+			properties: {
+				signupMethod: pickAWinner(["email", "google", "facebook", "twitter", "linkedin", "github"]),
+				referral: weighChoices(["none", "none", "none", "friend", "ad", "ad", "ad", "friend", "friend", "friend", "friend"]),
+			}
+		},
+
+	],
+	funnels: [
+		{
+			sequence: ["page view", "view item", "save item", "page view", "sign up"],
+			conversionRate: 50,
+			order: "first-and-last-fixed",
+			weight: 1,
+			isFirstFunnel: true,
+			timeToConvert: 2,
+			experiment: false,
+			name: "Signup Flow"
+
+		},
+		{
+			sequence: ["watch video", "like video", "watch video", "like video"],
+			name: "Video Likes",
+			conversionRate: 60,
+			props: {
+				videoCategory: videoCategories,
+				quality: ["2160p", "1440p", "1080p", "720p", "480p", "360p", "240p"],
+				format: ["mp4", "avi", "mov", "mpg"],
+				uploader_id: chance.guid.bind(chance)
+			}
+		},
+		{
+			name: "Video Dislikes",
+			sequence: ["watch video", "dislike video", "watch video", "dislike video"],
+			conversionRate: 20,
+			props: {
+				videoCategory: videoCategories,
+				quality: ["2160p", "1440p", "1080p", "720p", "480p", "360p", "240p"],
+				format: ["mp4", "avi", "mov", "mpg"],
+				uploader_id: chance.guid.bind(chance)
+			}
+		},
+		{
+			name: "eCommerce Purchase",
+			sequence: ["view item", "view item", "add to cart", "view item", "add to cart", "checkout"],
+			conversionRate: 15,
+			requireRepeats: true,
+			weight: 10,
+			order: "last-fixed",
+		}
+
+	],
+	superProps: {
+		theme: pickAWinner(["light", "dark", "custom", "light", "dark"]),
+	},
+	/*
+	user properties work the same as event properties
+	each key should be an array or function reference
+	*/
+	userProps: {
+		title: chance.profession.bind(chance),
+		luckyNumber: weighNumRange(1, 500, .3),
+		spiritAnimal: spiritAnimals
+	},
+	scdProps: {},
+	mirrorProps: {},
+	/*
+	for group analytics keys, we need an array of arrays [[],[],[]]
+	each pair represents a group_key and the number of profiles for that key
+	*/
+	groupKeys: [],
+	groupProps: {},
+	lookupTables: [{
+		key: "luckyNumber",
+		entries: 500,
+		attributes: {
+			present: ["happy", "sad", "angry", "confused", "excited", "bored", "curious", "anxious", "relaxed", "stressed"],
+			past: ["joyful", "melancholy", "furious", "puzzled", "thrilled", "weary", "inquiring", "nervous", "calm", "tense"],
+			future: ["hopeful", "dreadful", "optimistic", "skeptical", "eager", "lethargic", "inquiring", "apprehensive", "confident", "uneasy"],
+			weather: ["sunny", "rainy", "cloudy", "stormy", "snowy", "windy", "foggy", "humid", "dry", "chilly"],
+			temperature: weighNumRange(-10, 100)
+			
+		}
+
+	}],
+	hook: function (record, type, meta) {
+
+		const NOW = dayjs();
+
+
+		if (type === "event") {
+			
+		}
+
+		if (type === "everything") {
+			// every users has ~5 duplicate events
+			let numDupes = integer(3, 7);
+			if (record.length < numDupes) numDupes = record.length - 1;
+			// pick random events to duplicate
+			const dupesIndexes = [];
+			while (dupesIndexes.length < numDupes) {
+				const idx = integer(0, record.length - 1);
+				if (!dupesIndexes.includes(idx)) {
+					dupesIndexes.push(idx);
+				}
+			}
+
+			// duplicate those events
+			dupesIndexes.forEach(idx => {
+				const eventToDup = record[idx];
+				const newEvent = { ...eventToDup };				
+				record.push(newEvent);
+			});
+
+
+		}
+
+
+
+		return record;
+	}
+};
+
+function makeProducts(maxItems = 5) {
+	return function () {
+		const categories = ["electronics", "books", "clothing", "home", "garden", "toys", "sports", "automotive", "beauty", "health", "grocery", "jewelry", "shoes", "tools", "office supplies"];
+		const descriptors = ["brand new", "open box", "refurbished", "used", "like new", "vintage", "antique", "collectible"];
+		const suffix = ["item", "product", "good", "merchandise", "thing", "object", "widget", "gadget", "device", "apparatus", "contraption", "instrument", "tool", "implement", "utensil", "appliance", "machine", "equipment", "gear", "kit", "set", "package"];
+		const assetPreview = ['.png', '.jpg', '.jpeg', '.heic', '.mp4', '.mov', '.avi'];
+		const data = [];
+		const numOfItems = integer(1, maxItems);
+
+		for (var i = 0; i < numOfItems; i++) {
+			const category = chance.pickone(categories);
+			const descriptor = chance.pickone(descriptors);
+			const suffixWord = chance.pickone(suffix);
+			const slug = `${descriptor.replace(/\s+/g, '-').toLowerCase()}-${suffixWord.replace(/\s+/g, '-').toLowerCase()}`;
+			const asset = chance.pickone(assetPreview);
+
+			// const product_id = chance.guid();
+			const price = integer(1, 100);
+			const quantity = integer(1, 5);
+
+			const item = {
+				// product_id: product_id,
+				// sku: integer(11111, 99999),
+				amount: price,
+				quantity: quantity,
+				total_value: price * quantity,
+				featured: chance.pickone([true, false, false]),
+				category: category,
+				descriptor: descriptor,
+				slug: slug,
+				assetPreview: `https://example.com/assets/${slug}${asset}`,
+				assetType: asset
+
+			};
+
+			data.push(item);
+		}
+
+		return () => [data];
+	};
+};
+
+
+function flip(likelihood = 50) {
+	return chance.bool({ likelihood });
+}
+
+
+export default config;