make-mp-data 3.0.4 → 3.0.5

package/README.md

@@ -87,6 +87,52 @@ 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
 
+## ⏱️ 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).
+
+### Presets
+
+Use a preset string for quick configuration:
+
+```javascript
+const config = {
+  soup: "growth",    // default — gradual uptrend with weekly cycle
+  // ...
+};
+```
+
+| Preset | Pattern | Use Case |
+|--------|---------|----------|
+| `"steady"` | Flat, minimal variation | Enterprise B2B, utility apps |
+| `"growth"` | Gradual uptrend + weekly cycle | General purpose (default) |
+| `"spiky"` | Dramatic peaks and valleys | Gaming, social media, viral products |
+| `"seasonal"` | 3-4 major waves | E-commerce, education |
+| `"global"` | Flat DOW + flat HOD | Global SaaS, infrastructure tools |
+| `"churny"` | Flat, no growth trend | Declining products (pair with churn hooks) |
+| `"chaotic"` | Wild variation | Anomaly detection, incident response |
+
+### Custom Configuration
+
+Override specific parameters or use a preset as a base:
+
+```javascript
+// Preset + overrides
+soup: { preset: "spiky", deviation: 5 }
+
+// Fully custom
+soup: {
+  peaks: 200,
+  deviation: 2,
+  mean: 0,
+  dayOfWeekWeights: [0.637, 1.0, 0.999, 0.998, 0.966, 0.802, 0.528],  // [Sun..Sat]
+  hourOfDayWeights: [/* 24 values, index 0 = midnight UTC */],
+}
+
+// Disable cyclical patterns entirely
+soup: { dayOfWeekWeights: null, hourOfDayWeights: null }
+```
+
 ## 🎯 Hooks — Engineering Trends in Data
 
 Hooks let you engineer deliberate, discoverable patterns into your generated data — things like "premium users convert 2x better" or "there was a service outage during days 40-47." A hook is a single transform function on your dungeon config:

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

@@ -0,0 +1,327 @@
+{
+  "schema": {
+    "seed": "test array of objects lookup",
+    "name": "array-of-object-lookup",
+    "numDays": 60,
+    "numEvents": 100000,
+    "numUsers": 1000,
+    "format": "json",
+    "region": "US",
+    "hasAnonIds": true,
+    "hasSessionIds": true,
+    "hasAdSpend": false,
+    "hasLocation": true,
+    "hasAndroidDevices": false,
+    "hasIOSDevices": false,
+    "hasDesktopDevices": true,
+    "hasBrowser": true,
+    "hasCampaigns": false,
+    "isAnonymous": false,
+    "alsoInferFunnels": true,
+    "concurrency": 1,
+    "batchSize": 250000,
+    "writeToDisk": false,
+    "events": [
+      {
+        "event": "checkout",
+        "weight": 2,
+        "properties": {
+          "currency": [
+            "USD",
+            "CAD",
+            "EUR",
+            "BTC",
+            "ETH",
+            "JPY"
+          ],
+          "coupon": {
+            "functionName": "arrow",
+            "body": "function generateWeightedArray() {\n\t\tconst weightedArray = [];\n\n\t\t// Add each value to the array the number of times specified by its weight\n\t\tweightedItems.forEach(({ value, weight }) => {\n\t\t\tif (!weight) weight = 1;\n\t\t\tfor (let i = 0; i < weight; i++) {\n\t\t\t\tweightedArray.push(value);\n\t\t\t}\n\t\t});\n\n\t\treturn weightedArray;\n\t}"
+          },
+          "cart": {
+            "functionName": "arrow",
+            "body": "function () {\n\t\tconst categories = [\"electronics\", \"books\", \"clothing\", \"home\", \"garden\", \"toys\", \"sports\", \"automotive\", \"beauty\", \"health\", \"grocery\", \"jewelry\", \"shoes\", \"tools\", \"office supplies\"];\n\t\tconst descriptors = [\"brand new\", \"open box\", \"refurbished\", \"used\", \"like new\", \"vintage\", \"antique\", \"collectible\"];\n\t\tconst suffix = [\"item\", \"product\", \"good\", \"merchandise\", \"thing\", \"object\", \"widget\", \"gadget\", \"device\", \"apparatus\", \"contraption\", \"instrument\", \"tool\", \"implement\", \"utensil\", \"appliance\", \"machine\", \"equipment\", \"gear\", \"kit\", \"set\", \"package\"];\n\t\tconst assetPreview = ['.png', '.jpg', '.jpeg', '.heic', '.mp4', '.mov', '.avi'];\n\t\tconst data = [];\n\t\tconst numOfItems = integer(1, maxItems);\n\n\t\tfor (var i = 0; i < numOfItems; i++) {\n\t\t\tconst category = chance.pickone(categories);\n\t\t\tconst descriptor = chance.pickone(descriptors);\n\t\t\tconst suffixWord = chance.pickone(suffix);\n\t\t\tconst slug = `${descriptor.replace(/\\s+/g, '-').toLowerCase()}-${suffixWord.replace(/\\s+/g, '-').toLowerCase()}`;\n\t\t\tconst asset = chance.pickone(assetPreview);\n\n\t\t\t// const product_id = chance.guid();\n\t\t\tconst price = integer(1, 100);\n\t\t\tconst quantity = integer(1, 5);\n\t\t\tconst product_id = integer(1, 1_000);\n\n\t\t\tconst item = {\n\t\t\t\tproduct_id: product_id,\n\t\t\t\tproduct_url: `https://example.com/assets/${product_id}`,\n\t\t\t\t// sku: integer(11111, 99999),\n\t\t\t\t// amount: price,\n\t\t\t\t// quantity: quantity,\n\t\t\t\t// total_value: price * quantity,\n\t\t\t\t// featured: chance.pickone([true, false, false]),\n\t\t\t\t// category: category,\n\t\t\t\t// descriptor: descriptor,\n\t\t\t\t// slug: slug,\n\t\t\t\t\n\t\t\t\t// assetType: asset\n\n\t\t\t};\n\n\t\t\tdata.push(item);\n\t\t}\n\n\t\treturn () => [data];\n\t}"
+          }
+        }
+      },
+      {
+        "event": "add to cart",
+        "weight": 4,
+        "properties": {
+          "item": {
+            "functionName": "arrow",
+            "body": "function () {\n\t\tconst categories = [\"electronics\", \"books\", \"clothing\", \"home\", \"garden\", \"toys\", \"sports\", \"automotive\", \"beauty\", \"health\", \"grocery\", \"jewelry\", \"shoes\", \"tools\", \"office supplies\"];\n\t\tconst descriptors = [\"brand new\", \"open box\", \"refurbished\", \"used\", \"like new\", \"vintage\", \"antique\", \"collectible\"];\n\t\tconst suffix = [\"item\", \"product\", \"good\", \"merchandise\", \"thing\", \"object\", \"widget\", \"gadget\", \"device\", \"apparatus\", \"contraption\", \"instrument\", \"tool\", \"implement\", \"utensil\", \"appliance\", \"machine\", \"equipment\", \"gear\", \"kit\", \"set\", \"package\"];\n\t\tconst assetPreview = ['.png', '.jpg', '.jpeg', '.heic', '.mp4', '.mov', '.avi'];\n\t\tconst data = [];\n\t\tconst numOfItems = integer(1, maxItems);\n\n\t\tfor (var i = 0; i < numOfItems; i++) {\n\t\t\tconst category = chance.pickone(categories);\n\t\t\tconst descriptor = chance.pickone(descriptors);\n\t\t\tconst suffixWord = chance.pickone(suffix);\n\t\t\tconst slug = `${descriptor.replace(/\\s+/g, '-').toLowerCase()}-${suffixWord.replace(/\\s+/g, '-').toLowerCase()}`;\n\t\t\tconst asset = chance.pickone(assetPreview);\n\n\t\t\t// const product_id = chance.guid();\n\t\t\tconst price = integer(1, 100);\n\t\t\tconst quantity = integer(1, 5);\n\t\t\tconst product_id = integer(1, 1_000);\n\n\t\t\tconst item = {\n\t\t\t\tproduct_id: product_id,\n\t\t\t\tproduct_url: `https://example.com/assets/${product_id}`,\n\t\t\t\t// sku: integer(11111, 99999),\n\t\t\t\t// amount: price,\n\t\t\t\t// quantity: quantity,\n\t\t\t\t// total_value: price * quantity,\n\t\t\t\t// featured: chance.pickone([true, false, false]),\n\t\t\t\t// category: category,\n\t\t\t\t// descriptor: descriptor,\n\t\t\t\t// slug: slug,\n\t\t\t\t\n\t\t\t\t// assetType: asset\n\n\t\t\t};\n\n\t\t\tdata.push(item);\n\t\t}\n\n\t\treturn () => [data];\n\t}"
+          }
+        }
+      },
+      {
+        "event": "view item",
+        "weight": 8,
+        "properties": {
+          "item": {
+            "functionName": "arrow",
+            "body": "function () {\n\t\tconst categories = [\"electronics\", \"books\", \"clothing\", \"home\", \"garden\", \"toys\", \"sports\", \"automotive\", \"beauty\", \"health\", \"grocery\", \"jewelry\", \"shoes\", \"tools\", \"office supplies\"];\n\t\tconst descriptors = [\"brand new\", \"open box\", \"refurbished\", \"used\", \"like new\", \"vintage\", \"antique\", \"collectible\"];\n\t\tconst suffix = [\"item\", \"product\", \"good\", \"merchandise\", \"thing\", \"object\", \"widget\", \"gadget\", \"device\", \"apparatus\", \"contraption\", \"instrument\", \"tool\", \"implement\", \"utensil\", \"appliance\", \"machine\", \"equipment\", \"gear\", \"kit\", \"set\", \"package\"];\n\t\tconst assetPreview = ['.png', '.jpg', '.jpeg', '.heic', '.mp4', '.mov', '.avi'];\n\t\tconst data = [];\n\t\tconst numOfItems = integer(1, maxItems);\n\n\t\tfor (var i = 0; i < numOfItems; i++) {\n\t\t\tconst category = chance.pickone(categories);\n\t\t\tconst descriptor = chance.pickone(descriptors);\n\t\t\tconst suffixWord = chance.pickone(suffix);\n\t\t\tconst slug = `${descriptor.replace(/\\s+/g, '-').toLowerCase()}-${suffixWord.replace(/\\s+/g, '-').toLowerCase()}`;\n\t\t\tconst asset = chance.pickone(assetPreview);\n\n\t\t\t// const product_id = chance.guid();\n\t\t\tconst price = integer(1, 100);\n\t\t\tconst quantity = integer(1, 5);\n\t\t\tconst product_id = integer(1, 1_000);\n\n\t\t\tconst item = {\n\t\t\t\tproduct_id: product_id,\n\t\t\t\tproduct_url: `https://example.com/assets/${product_id}`,\n\t\t\t\t// sku: integer(11111, 99999),\n\t\t\t\t// amount: price,\n\t\t\t\t// quantity: quantity,\n\t\t\t\t// total_value: price * quantity,\n\t\t\t\t// featured: chance.pickone([true, false, false]),\n\t\t\t\t// category: category,\n\t\t\t\t// descriptor: descriptor,\n\t\t\t\t// slug: slug,\n\t\t\t\t\n\t\t\t\t// assetType: asset\n\n\t\t\t};\n\n\t\t\tdata.push(item);\n\t\t}\n\n\t\treturn () => [data];\n\t}"
+          }
+        }
+      },
+      {
+        "event": "save item",
+        "weight": 5,
+        "properties": {
+          "item": {
+            "functionName": "arrow",
+            "body": "function () {\n\t\tconst categories = [\"electronics\", \"books\", \"clothing\", \"home\", \"garden\", \"toys\", \"sports\", \"automotive\", \"beauty\", \"health\", \"grocery\", \"jewelry\", \"shoes\", \"tools\", \"office supplies\"];\n\t\tconst descriptors = [\"brand new\", \"open box\", \"refurbished\", \"used\", \"like new\", \"vintage\", \"antique\", \"collectible\"];\n\t\tconst suffix = [\"item\", \"product\", \"good\", \"merchandise\", \"thing\", \"object\", \"widget\", \"gadget\", \"device\", \"apparatus\", \"contraption\", \"instrument\", \"tool\", \"implement\", \"utensil\", \"appliance\", \"machine\", \"equipment\", \"gear\", \"kit\", \"set\", \"package\"];\n\t\tconst assetPreview = ['.png', '.jpg', '.jpeg', '.heic', '.mp4', '.mov', '.avi'];\n\t\tconst data = [];\n\t\tconst numOfItems = integer(1, maxItems);\n\n\t\tfor (var i = 0; i < numOfItems; i++) {\n\t\t\tconst category = chance.pickone(categories);\n\t\t\tconst descriptor = chance.pickone(descriptors);\n\t\t\tconst suffixWord = chance.pickone(suffix);\n\t\t\tconst slug = `${descriptor.replace(/\\s+/g, '-').toLowerCase()}-${suffixWord.replace(/\\s+/g, '-').toLowerCase()}`;\n\t\t\tconst asset = chance.pickone(assetPreview);\n\n\t\t\t// const product_id = chance.guid();\n\t\t\tconst price = integer(1, 100);\n\t\t\tconst quantity = integer(1, 5);\n\t\t\tconst product_id = integer(1, 1_000);\n\n\t\t\tconst item = {\n\t\t\t\tproduct_id: product_id,\n\t\t\t\tproduct_url: `https://example.com/assets/${product_id}`,\n\t\t\t\t// sku: integer(11111, 99999),\n\t\t\t\t// amount: price,\n\t\t\t\t// quantity: quantity,\n\t\t\t\t// total_value: price * quantity,\n\t\t\t\t// featured: chance.pickone([true, false, false]),\n\t\t\t\t// category: category,\n\t\t\t\t// descriptor: descriptor,\n\t\t\t\t// slug: slug,\n\t\t\t\t\n\t\t\t\t// assetType: asset\n\n\t\t\t};\n\n\t\t\tdata.push(item);\n\t\t}\n\n\t\treturn () => [data];\n\t}"
+          }
+        }
+      }
+    ],
+    "funnels": [],
+    "superProps": {
+      "theme": {
+        "functionName": "arrow",
+        "body": "function () {\n\t\tconst weighted = [];\n\t\tfor (let i = 0; i < 10; i++) {\n\t\t\tconst rand = chance.d10(); // Random number between 1 and 10\n\n\t\t\t// 35% chance to favor the most chosen index\n\t\t\tif (chance.bool({ likelihood: 35 })) {\n\t\t\t\t// 50% chance to slightly alter the index\n\t\t\t\tif (chance.bool({ likelihood: 50 })) {\n\t\t\t\t\tweighted.push(items[mostChosenIndex]);\n\t\t\t\t} else {\n\t\t\t\t\tconst addOrSubtract = chance.bool({ likelihood: 50 }) ? -rand : rand;\n\t\t\t\t\tlet newIndex = mostChosenIndex + addOrSubtract;\n\n\t\t\t\t\t// Ensure newIndex is within bounds\n\t\t\t\t\tif (newIndex < 0) newIndex = 0;\n\t\t\t\t\tif (newIndex >= items.length) newIndex = items.length - 1;\n\t\t\t\t\tweighted.push(items[newIndex]);\n\t\t\t\t}\n\t\t\t}\n\t\t\t// 25% chance to favor the second most chosen index\n\t\t\telse if (chance.bool({ likelihood: 25 })) {\n\t\t\t\tweighted.push(items[secondMostChosenIndex]);\n\t\t\t}\n\t\t\t// 15% chance to favor the third most chosen index\n\t\t\telse if (chance.bool({ likelihood: 15 })) {\n\t\t\t\tweighted.push(items[thirdMostChosenIndex]);\n\t\t\t}\n\t\t\t// Otherwise, pick a random item from the list\n\t\t\telse {\n\t\t\t\tweighted.push(chance.pickone(items));\n\t\t\t}\n\t\t}\n\t\treturn weighted;\n\t}"
+      }
+    },
+    "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"
+      ]
+    },
+    "scdProps": {},
+    "mirrorProps": {},
+    "groupKeys": [],
+    "groupProps": {},
+    "lookupTables": [
+      {
+        "key": "product_id",
+        "entries": 1000,
+        "attributes": {
+          "amount": [
+            259,
+            247,
+            271,
+            269,
+            209,
+            305,
+            706,
+            344,
+            350,
+            327,
+            259,
+            225,
+            269,
+            267,
+            256,
+            705,
+            196,
+            588,
+            775,
+            235,
+            737,
+            341,
+            268,
+            409,
+            233,
+            246,
+            239,
+            737,
+            701,
+            741,
+            227,
+            230,
+            693,
+            719,
+            277,
+            706,
+            292,
+            274,
+            596,
+            263,
+            250,
+            279,
+            275,
+            799,
+            236,
+            267,
+            221,
+            230,
+            730,
+            789
+          ],
+          "quantity": [
+            4,
+            5,
+            7,
+            4,
+            8,
+            6,
+            3,
+            3,
+            4,
+            6,
+            3,
+            3,
+            8,
+            3,
+            3,
+            8,
+            3,
+            8,
+            7,
+            4,
+            8,
+            4,
+            4,
+            4,
+            4,
+            3,
+            5,
+            4,
+            3,
+            3,
+            3,
+            7,
+            3,
+            3,
+            4,
+            4,
+            6,
+            4,
+            7,
+            7,
+            4,
+            3,
+            3,
+            3,
+            3,
+            4,
+            8,
+            3,
+            3,
+            3
+          ],
+          "featured": {
+            "functionName": "arrow",
+            "body": "function flip(likelihood = 50) {\n\treturn chance.bool({ likelihood });\n}"
+          },
+          "category": [
+            "electronics",
+            "books",
+            "clothing",
+            "home",
+            "garden",
+            "toys",
+            "sports",
+            "automotive",
+            "beauty",
+            "health",
+            "grocery",
+            "jewelry",
+            "shoes",
+            "tools",
+            "office supplies"
+          ],
+          "descriptor": [
+            "brand new",
+            "open box",
+            "refurbished",
+            "used",
+            "like new",
+            "vintage",
+            "antique",
+            "collectible"
+          ]
+        }
+      }
+    ]
+  },
+  "hooks": "function (record, type, meta) {\n\n\t\tconst NOW = dayjs();\n\n\t\tif (type === \"event\") {\n\t\t\t// Pattern 1: Checkouts with coupons get a discount_applied flag and adjusted total\n\t\t\tif (record.event === \"checkout\" && record.coupon && record.coupon !== \"none\") {\n\t\t\t\trecord.discount_applied = true;\n\t\t\t\tconst pctMatch = record.coupon.match(/(\\d+)%/);\n\t\t\t\tif (pctMatch) {\n\t\t\t\t\trecord.discount_percent = parseInt(pctMatch[1]);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Pattern 2: \"save item\" events on weekends are tagged as wishlist behavior\n\t\t\tif (record.event === \"save item\") {\n\t\t\t\tconst dow = dayjs(record.time).day();\n\t\t\t\tif (dow === 0 || dow === 6) {\n\t\t\t\t\trecord.save_context = \"weekend_browse\";\n\t\t\t\t} else {\n\t\t\t\t\trecord.save_context = \"weekday_intent\";\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif (type === \"everything\") {\n\t\t\t// Pattern 3: Users who view 5+ items but never checkout are tagged as window shoppers\n\t\t\tconst views = record.filter(e => e.event === \"view item\").length;\n\t\t\tconst checkouts = record.filter(e => e.event === \"checkout\").length;\n\t\t\tif (views >= 5 && checkouts === 0) {\n\t\t\t\tfor (const e of record) {\n\t\t\t\t\te.user_segment = \"window_shopper\";\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn record;\n\t}",
+  "timestamp": "2026-04-10T01:39:06.554Z",
+  "version": "4.0"
+}

package/dungeons/array-of-object-lookup.js

@@ -1,11 +1,3 @@
-/**
- * This is the default configuration file for the data generator in SIMPLE mode
- * notice how the config object is structured, and see it's type definition in ./types.d.ts
- * feel free to modify this file to customize the data you generate
- * see helper functions in utils.js for more ways to generate data
- */
-
-
 import Chance from 'chance';
 let chance = new Chance();
 import dayjs from "dayjs";
@@ -17,6 +9,34 @@ import { pickAWinner, weighNumRange, date, integer, weighChoices } from "../lib/
 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"];
 
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * DATASET OVERVIEW
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * Array-of-Object Lookup Test — tests nested product arrays in events.
+ * - 1,000 users over 60 days, ~100K events
+ * - Events: checkout (cart array), add to cart, view/save item (single item)
+ * - Lookup table: 1,000 products with price, category, descriptor
+ * - Tests Mixpanel's array-of-objects property handling
+ *
+ * ═══════════════════════════════════════════════════════════════
+ * ANALYTICS HOOKS (3 patterns)
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * 1. COUPON DISCOUNT TAGGING (event hook)
+ *    Checkout events with coupons get discount_applied: true and
+ *    discount_percent extracted from the coupon string.
+ *
+ * 2. WEEKEND BROWSE vs WEEKDAY INTENT (event hook)
+ *    Save item events on weekends tagged save_context: "weekend_browse",
+ *    weekdays tagged "weekday_intent".
+ *
+ * 3. WINDOW SHOPPERS (everything hook)
+ *    Users with 5+ view item events but 0 checkouts get all their
+ *    events tagged user_segment: "window_shopper".
+ */
+
 /** @type {import('../types.js').Dungeon} */
 const config = {
 	// token: "",