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

package/README.md

@@ -44,16 +44,16 @@ the main export accepts multiple input formats. use whatever fits your workflow:
 
 ```javascript
 // load a dungeon file from disk
-const result = await DUNGEON_MASTER('./dungeons/simple.js');
+const result = await DUNGEON_MASTER('./dungeons/technical/simple.js');
 
 // load a JSON dungeon (exported from the UI)
-const result = await DUNGEON_MASTER('./dungeons/simple-schema.json');
+const result = await DUNGEON_MASTER('./dungeons/technical/simple-schema.json');
 
 // run multiple dungeons
 const results = await DUNGEON_MASTER([
-  './dungeons/gaming.js',
-  './dungeons/media.js',
-  './dungeons/food-delivery.js'
+  './dungeons/vertical/gaming.js',
+  './dungeons/vertical/media.js',
+  './dungeons/vertical/food-delivery.js'
 ]);
 
 // pass raw javascript as a string
@@ -70,7 +70,7 @@ const result = await DUNGEON_MASTER(`
 `);
 
 // override any config when loading from files
-const result = await DUNGEON_MASTER('./dungeons/complex.js', {
+const result = await DUNGEON_MASTER('./dungeons/vertical/fintech.js', {
   numUsers: 100,       // shrink for testing
   writeToDisk: true,
   verbose: true
@@ -95,7 +95,7 @@ console.log(result.importResults);
 
 a dungeon is a javascript file that exports a configuration object. it defines your entire data model: events, funnels, user properties, group analytics, SCDs, and a hook function that engineers discoverable patterns into the data.
 
-see `dungeons/` for examples ranging from simple (5 events, no hooks) to complex (18 events, 8 funnels, 8 hooks with temporal windowing, closure state, and cross-table correlation).
+see `dungeons/vertical/` for customer-facing story dungeons (18 events, 8 hooks) and `dungeons/technical/` for feature-testing dungeons (mirrors, groups, scale, anonymous users).
 
 ```javascript
 // dungeons/my-app.js

package/dungeons/technical/ad-spend-schema.json

@@ -0,0 +1,128 @@
+{
+  "events": [
+    {
+      "event": "sign up",
+      "isFirstEvent": true,
+      "properties": {
+        "method": [
+          "email",
+          "google",
+          "facebook",
+          "github"
+        ]
+      }
+    },
+    {
+      "event": "page view",
+      "weight": 10,
+      "properties": {
+        "page": [
+          "/",
+          "/pricing",
+          "/features",
+          "/docs",
+          "/blog",
+          "/signup"
+        ]
+      }
+    },
+    {
+      "event": "purchase",
+      "weight": 2,
+      "properties": {
+        "amount": {
+          "$range": [
+            108,
+            392
+          ]
+        },
+        "currency": [
+          "USD",
+          "EUR",
+          "GBP"
+        ],
+        "item_count": {
+          "$range": [
+            2,
+            7
+          ]
+        }
+      }
+    },
+    {
+      "event": "ad click",
+      "weight": 6,
+      "properties": {
+        "partner": [
+          "google",
+          "facebook",
+          "linkedin",
+          "twitter",
+          "bing",
+          "tiktok"
+        ],
+        "ad_format": [
+          "banner",
+          "video",
+          "carousel",
+          "native",
+          "search"
+        ],
+        "placement": [
+          "feed",
+          "sidebar",
+          "header",
+          "interstitial"
+        ]
+      }
+    },
+    {
+      "event": "search",
+      "weight": 5,
+      "properties": {
+        "query_length": {
+          "$range": [
+            3,
+            28
+          ]
+        },
+        "results_count": {
+          "$range": [
+            21,
+            79
+          ]
+        }
+      }
+    },
+    {
+      "event": "share",
+      "weight": 3,
+      "properties": {
+        "platform": [
+          "twitter",
+          "facebook",
+          "linkedin",
+          "email"
+        ],
+        "content_type": [
+          "product",
+          "page",
+          "deal"
+        ]
+      }
+    }
+  ],
+  "userProps": {
+    "plan": [
+      "free",
+      "starter",
+      "pro",
+      "enterprise"
+    ],
+    "signup_source": [
+      "organic",
+      "paid",
+      "referral"
+    ]
+  }
+}

package/dungeons/technical/ad-spend.js

@@ -0,0 +1,116 @@
+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 { weighNumRange, date, integer, weighChoices } from "../../lib/utils/utils.js";
+
+/** @typedef {import("../../types").Dungeon} Config */
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * TECHNICAL TEST: Ad Spend & Campaign Attribution
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * Tests Mixpanel ad spend data generation and campaign attribution.
+ * - 1,000 users, 50K events, 90 days
+ * - hasAdSpend: true — generates cost, CPC, CTR, impressions, clicks
+ * - hasCampaigns: true — adds UTM parameters to events
+ * - hasBrowser: true — required for campaign tracking
+ * - 6 events: signup, page view, purchase, ad click, search, share
+ *
+ * No hooks. Focus is on verifying ad spend event structure
+ * and campaign attribution properties flow through correctly.
+ */
+
+/** @type {import('../../types').Dungeon} */
+const config = {
+	seed: "ad spend test",
+	name: "ad-spend",
+	numDays: 90,
+	numEvents: 50_000,
+	numUsers: 1_000,
+	format: 'json',
+	region: "US",
+	hasAnonIds: true,
+	hasSessionIds: true,
+	hasAdSpend: true,
+	hasLocation: false,
+	hasAndroidDevices: false,
+	hasIOSDevices: false,
+	hasDesktopDevices: true,
+	hasBrowser: true,
+	hasCampaigns: true,
+	isAnonymous: false,
+	alsoInferFunnels: false,
+	concurrency: 1,
+	writeToDisk: false,
+
+	events: [
+		{
+			event: "sign up",
+			weight: 1,
+			isFirstEvent: true,
+			properties: {
+				method: ["email", "google", "facebook", "github"],
+			}
+		},
+		{
+			event: "page view",
+			weight: 10,
+			properties: {
+				page: ["/", "/pricing", "/features", "/docs", "/blog", "/signup"],
+			}
+		},
+		{
+			event: "purchase",
+			weight: 2,
+			properties: {
+				amount: weighNumRange(10, 500, .25),
+				currency: ["USD", "EUR", "GBP"],
+				item_count: weighNumRange(1, 8),
+			}
+		},
+		{
+			event: "ad click",
+			weight: 6,
+			properties: {
+				partner: ["google", "facebook", "linkedin", "twitter", "bing", "tiktok"],
+				ad_format: ["banner", "video", "carousel", "native", "search"],
+				placement: ["feed", "sidebar", "header", "interstitial"],
+			}
+		},
+		{
+			event: "search",
+			weight: 5,
+			properties: {
+				query_length: weighNumRange(1, 30),
+				results_count: weighNumRange(0, 100, .25),
+			}
+		},
+		{
+			event: "share",
+			weight: 3,
+			properties: {
+				platform: ["twitter", "facebook", "linkedin", "email"],
+				content_type: ["product", "page", "deal"],
+			}
+		},
+	],
+	funnels: [],
+	superProps: {},
+	userProps: {
+		plan: ["free", "starter", "pro", "enterprise"],
+		signup_source: ["organic", "organic", "organic", "paid", "paid", "referral"],
+	},
+	scdProps: {},
+	mirrorProps: {},
+	groupKeys: [],
+	groupProps: {},
+	lookupTables: [],
+	hook: function (record, type, meta) {
+		return record;
+	}
+};
+
+export default config;

package/dungeons/technical/anonymous-users-schema.json

@@ -0,0 +1,92 @@
+{
+  "events": [
+    {
+      "event": "page view",
+      "weight": 10,
+      "properties": {
+        "page": [
+          "/",
+          "/features",
+          "/pricing",
+          "/docs",
+          "/blog"
+        ],
+        "referrer": [
+          "direct",
+          "google",
+          "twitter",
+          "linkedin"
+        ]
+      }
+    },
+    {
+      "event": "signup",
+      "isFirstEvent": true,
+      "properties": {
+        "method": [
+          "email",
+          "google",
+          "github",
+          "sso"
+        ]
+      }
+    },
+    {
+      "event": "feature used",
+      "weight": 7,
+      "properties": {
+        "feature": [
+          "dashboard",
+          "reports",
+          "settings",
+          "export",
+          "import",
+          "search"
+        ]
+      }
+    },
+    {
+      "event": "purchase",
+      "weight": 2,
+      "properties": {
+        "amount": {
+          "$range": [
+            114,
+            397
+          ]
+        },
+        "plan": [
+          "monthly",
+          "annual"
+        ]
+      }
+    },
+    {
+      "event": "button click",
+      "weight": 8,
+      "properties": {
+        "button": [
+          "cta",
+          "nav",
+          "menu",
+          "submit",
+          "cancel",
+          "back"
+        ],
+        "location": [
+          "header",
+          "body",
+          "footer",
+          "sidebar"
+        ]
+      }
+    }
+  ],
+  "userProps": {
+    "plan": [
+      "free",
+      "pro",
+      "enterprise"
+    ]
+  }
+}

package/dungeons/technical/anonymous-users.js

@@ -0,0 +1,102 @@
+/**
+ * Anonymous Users — tests anonymous user mode, anonIds, and identity merge.
+ *
+ * Exercises: isAnonymous mode, hasAnonIds for anonymous-to-identified
+ * user flows, long 180-day timespan for tail behavior.
+ *
+ * - 1000 users, 50K events, 180 days
+ * - isAnonymous: true, hasAnonIds: true
+ * - Simple events with signup as isFirstEvent (identity resolution point)
+ * - No hooks, minimal config
+ */
+
+import Chance from 'chance';
+let chance = new Chance();
+import { weighNumRange, weighChoices } from "../../lib/utils/utils.js";
+
+/** @typedef {import("../../types").Dungeon} Config */
+/** @type {import('../../types').Dungeon} */
+const config = {
+	token: "",
+	seed: "anonymous-users",
+	numDays: 180,
+	numEvents: 50_000,
+	numUsers: 1_000,
+	format: "json",
+	region: "US",
+	isAnonymous: true,
+	hasAnonIds: true,
+	hasSessionIds: true,
+	hasAdSpend: false,
+	hasLocation: false,
+	hasAndroidDevices: true,
+	hasIOSDevices: true,
+	hasDesktopDevices: true,
+	hasBrowser: true,
+	hasCampaigns: false,
+	alsoInferFunnels: false,
+	concurrency: 1,
+	writeToDisk: false,
+
+	events: [
+		{
+			event: "page view",
+			weight: 10,
+			properties: {
+				page: ["/", "/", "/features", "/pricing", "/docs", "/blog"],
+				referrer: weighChoices(["direct", "direct", "direct", "google", "google", "twitter", "linkedin"]),
+			}
+		},
+		{
+			event: "signup",
+			weight: 1,
+			isFirstEvent: true,
+			properties: {
+				method: ["email", "google", "github", "sso"],
+			}
+		},
+		{
+			event: "feature used",
+			weight: 7,
+			properties: {
+				feature: ["dashboard", "reports", "settings", "export", "import", "search"],
+			}
+		},
+		{
+			event: "purchase",
+			weight: 2,
+			properties: {
+				amount: weighNumRange(10, 500, .25),
+				plan: ["monthly", "annual"],
+			}
+		},
+		{
+			event: "button click",
+			weight: 8,
+			properties: {
+				button: ["cta", "nav", "menu", "submit", "cancel", "back"],
+				location: ["header", "body", "footer", "sidebar"],
+			}
+		},
+	],
+
+	funnels: [],
+
+	superProps: {},
+
+	userProps: {
+		plan: weighChoices(["free", "free", "free", "pro", "pro", "enterprise"]),
+	},
+
+	scdProps: {},
+	mirrorProps: {},
+	groupKeys: [],
+	groupProps: {},
+	lookupTables: [],
+
+	hook: function (record, type, meta) {
+		return record;
+	}
+};
+
+export default config;

package/dungeons/technical/array-of-object-lookup-schema.json

@@ -0,0 +1,191 @@
+{
+  "events": [
+    {
+      "event": "checkout",
+      "weight": 2,
+      "properties": {
+        "currency": [
+          "USD",
+          "CAD",
+          "EUR",
+          "BTC",
+          "ETH",
+          "JPY"
+        ],
+        "coupon": [
+          "none",
+          "10%OFF",
+          "20%OFF",
+          "30%OFF",
+          "40%OFF",
+          "50%OFF"
+        ],
+        "cart": {
+          "$type": "object[]",
+          "$keys": [
+            "product_id",
+            "product_url"
+          ]
+        },
+        "discount_applied": [
+          false
+        ],
+        "discount_percent": [
+          0
+        ],
+        "user_segment": [
+          "regular"
+        ]
+      }
+    },
+    {
+      "event": "add to cart",
+      "weight": 4,
+      "properties": {
+        "item": {
+          "$type": "object[]",
+          "$keys": [
+            "product_id",
+            "product_url"
+          ]
+        },
+        "user_segment": [
+          "regular"
+        ]
+      }
+    },
+    {
+      "event": "view item",
+      "weight": 8,
+      "properties": {
+        "item": {
+          "$type": "object[]",
+          "$keys": [
+            "product_id",
+            "product_url"
+          ]
+        },
+        "user_segment": [
+          "regular"
+        ]
+      }
+    },
+    {
+      "event": "save item",
+      "weight": 5,
+      "properties": {
+        "item": {
+          "$type": "object[]",
+          "$keys": [
+            "product_id",
+            "product_url"
+          ]
+        },
+        "save_context": [
+          "weekday_intent"
+        ],
+        "user_segment": [
+          "regular"
+        ]
+      }
+    }
+  ],
+  "superProps": {
+    "theme": [
+      "light",
+      "dark",
+      "custom"
+    ]
+  },
+  "userProps": {
+    "spiritAnimal": [
+      "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"
+    ]
+  }
+}