make-mp-data 2.1.11 → 3.0.1

package/lib/templates/hooks-instructions.txt

@@ -12,6 +12,28 @@ The user has already generated a dungeon schema with these events, properties, a
 
 --------------
 
+CRITICAL - EXACT PROPERTY AND VALUE NAMES:
+
+You MUST use the EXACT event names, property names, and property values from the schema above. These are CASE-SENSITIVE and must match EXACTLY.
+
+DO NOT:
+- Invent new event names
+- Invent new property names
+- Invent new property values
+- Change the case of any names (e.g., "user_id" ≠ "User_ID" ≠ "userId")
+- Use similar but different names (e.g., "status" ≠ "application status")
+
+DO:
+- Copy event names exactly as they appear in the schema
+- Copy property names exactly as they appear in the schema
+- Copy property values exactly as they appear in the schema (for arrays)
+- Reference only properties that actually exist in the schema
+- Respect underscores, hyphens, spaces, and capitalization
+
+If the user asks you to reference a property that doesn't exist in the schema, ask them to add it to the schema first OR work with the closest matching property that does exist.
+
+--------------
+
 YOUR TASK:
 
 Based on the user's description of desired trends or patterns, generate a single JavaScript hook function that implements those statistical relationships.
@@ -38,6 +60,36 @@ HOOK TYPES (type parameter):
 - "ad-spend": Hook into ad spend events.
 - "everything": Runs once per user after all their events are generated. `record` is the full event stream array, and `meta` contains user profile and metadata. This is the most powerful hook for creating complex correlations.
 
+COMPOSING MULTIPLE HOOK TYPES:
+
+IMPORTANT: Your hook function can handle MULTIPLE hook types in the SAME function. The examples below show individual patterns, but you should COMBINE and COMPOSE multiple hook types together when the user's requirements call for it.
+
+For example, a single hook function can:
+- Modify event properties (event type)
+- Alter funnel conversion rates (funnel-pre type)
+- Filter or modify the full event stream (everything type)
+- All in the same function!
+
+Pattern for multi-type hooks:
+
+if (type === "event") {
+    // Handle individual event modifications
+}
+
+if (type === "funnel-pre") {
+    // Handle funnel configuration changes
+}
+
+if (type === "everything") {
+    // Handle full user event stream modifications
+}
+
+return record;
+
+Think of the examples below as BUILDING BLOCKS that you can mix and match. If the user asks for "users who do X are more likely to do Y AND their funnels convert better AND they churn less", you should compose event-level, funnel-level, and everything-level logic into ONE cohesive hook function.
+
+The examples are NOT rigid templates - they're patterns to learn from and combine creatively.
+
 AVAILABLE HELPERS:
 
 You have access to these utilities within the hook:
@@ -52,13 +104,17 @@ You have access to these utilities within the hook:
 
 CRITICAL RULES:
 
-1. Your ONLY output is the hook function body (the code inside the function, NOT including the "hook: function (record, type, meta) {" wrapper).
+1. Output Format: You MUST output a COMPLETE JavaScript function with the exact signature: function(record, type, meta) { ... }
+   - INCLUDE the function declaration: function(record, type, meta) {
+   - INCLUDE all your hook logic in the body
+   - INCLUDE the closing brace: }
+   - The function MUST always return record at the end
 
 2. Generate VALID JavaScript code that will execute without errors.
 
 3. The code should implement the statistical trends described by the user.
 
-4. Use the actual event names and property names from the schema provided above.
+4. CRITICAL: Use ONLY the EXACT event names, property names, and values from the schema. Case-sensitive. No variations. No invented names. Copy them exactly.
 
 5. Always return `record` at the end.
 
@@ -390,6 +446,203 @@ if (type === "event") {
 }
 return record;
 
+=== SCD HOOKS (Slowly Changing Dimensions) ===
+
+Example 9: Modifying events based on user's SCD state at that time
+
+// SCDs track how user properties change over time (e.g., plan upgrades, role changes)
+// This hook modifies user behavior during different SCD periods
+
+if (type === "everything") {
+    // Assuming the schema has an SCD for "subscription_plan" with values ["free", "basic", "pro", "enterprise"]
+    // We'll modify user behavior based on their plan at the time of each event
+
+    const UPGRADE_DATE = dayjs().subtract(15, 'days');
+    const ENTERPRISE_DATE = dayjs().subtract(5, 'days');
+
+    record.forEach((event) => {
+        const EVENT_TIME = dayjs(event.time);
+
+        // Determine user's plan at this point in time
+        let currentPlan = "free"; // default
+        if (EVENT_TIME.isAfter(UPGRADE_DATE)) {
+            currentPlan = "basic";
+        }
+        if (EVENT_TIME.isAfter(ENTERPRISE_DATE)) {
+            currentPlan = "enterprise";
+        }
+
+        // Modify event behavior based on plan
+        if (currentPlan === "enterprise") {
+            // Enterprise users use advanced features more
+            if (event.event === "feature_used" && event["feature_name"]) {
+                if (chance.bool({ likelihood: 70 })) {
+                    event["feature_name"] = "advanced_analytics";
+                    event["usage_duration"] = u.integer(300, 600); // longer sessions
+                }
+            }
+            // They also generate more API calls
+            if (event.event === "api_call") {
+                event["rate_limit"] = "unlimited";
+                event["response_time"] = u.integer(50, 150); // faster response
+            }
+        } else if (currentPlan === "basic") {
+            // Basic users have moderate usage
+            if (event.event === "feature_used") {
+                event["usage_duration"] = u.integer(60, 300);
+            }
+            if (event.event === "api_call") {
+                event["rate_limit"] = "1000/hour";
+                event["response_time"] = u.integer(100, 300);
+            }
+        } else {
+            // Free users have limited behavior
+            if (event.event === "feature_used") {
+                event["usage_duration"] = u.integer(30, 120); // shorter sessions
+                if (chance.bool({ likelihood: 30 })) {
+                    // Sometimes hit paywalls
+                    event["hit_paywall"] = true;
+                }
+            }
+            if (event.event === "api_call") {
+                event["rate_limit"] = "100/hour";
+                event["response_time"] = u.integer(200, 500);
+                if (chance.bool({ likelihood: 20 })) {
+                    event["error"] = "rate_limit_exceeded";
+                }
+            }
+        }
+    });
+}
+return record;
+
+Example 10: SCD-driven churn patterns
+
+// Users who downgrade their plan are more likely to churn
+
+if (type === "everything") {
+    const DOWNGRADE_DATE = dayjs().subtract(20, 'days');
+    const CHURN_DATE = dayjs().subtract(10, 'days');
+
+    // Check if user downgraded (would be tracked in SCD)
+    let userDowngraded = false;
+
+    record.forEach((event, idx) => {
+        const EVENT_TIME = dayjs(event.time);
+
+        // Simulate checking SCD history
+        if (EVENT_TIME.isAfter(DOWNGRADE_DATE) && EVENT_TIME.isBefore(CHURN_DATE)) {
+            userDowngraded = true;
+        }
+
+        if (userDowngraded && EVENT_TIME.isAfter(CHURN_DATE)) {
+            // Downgraded users have 60% chance to stop using the product
+            if (chance.bool({ likelihood: 60 })) {
+                // Remove this event (user churned)
+                record.splice(idx, 1);
+            }
+        }
+    });
+
+    // If user downgraded, reduce overall event frequency
+    if (userDowngraded) {
+        record = record.filter((event, idx) => {
+            const EVENT_TIME = dayjs(event.time);
+            if (EVENT_TIME.isAfter(DOWNGRADE_DATE)) {
+                // Keep only 30% of events after downgrade
+                return chance.bool({ likelihood: 30 });
+            }
+            return true;
+        });
+    }
+}
+return record;
+
+=== MULTI-TYPE COMPOSITION EXAMPLE ===
+
+Example 11: Complete multi-type hook for product launch impact
+
+// This example shows how to compose multiple hook types for a comprehensive trend:
+// A new feature launch that affects individual events, funnel conversion, and overall usage
+
+const FEATURE_LAUNCH = dayjs().subtract(21, 'days');
+const FEATURE_IMPROVEMENT = dayjs().subtract(7, 'days');
+
+// Handle individual events
+if (type === "event") {
+    const EVENT_TIME = dayjs(record.time);
+
+    // After feature launch, usage patterns change
+    if (EVENT_TIME.isAfter(FEATURE_LAUNCH)) {
+        // New feature attracts more engagement
+        if (record.event === "page_view" && record["page_name"] === "dashboard") {
+            if (chance.bool({ likelihood: 40 })) {
+                record["page_name"] = "new_feature";
+                record["engagement_score"] = u.integer(70, 100);
+            }
+        }
+
+        // But initially has bugs
+        if (EVENT_TIME.isBefore(FEATURE_IMPROVEMENT)) {
+            if (record.event === "error" && record["error_type"]) {
+                if (chance.bool({ likelihood: 30 })) {
+                    record["error_type"] = "feature_bug";
+                    record["severity"] = "high";
+                }
+            }
+        }
+    }
+}
+
+// Handle funnel conversion changes
+if (type === "funnel-pre") {
+    const funnelTime = dayjs.unix(meta.firstEventTime);
+
+    // Feature launch improves conversion for certain funnels
+    if (funnelTime.isAfter(FEATURE_LAUNCH)) {
+        if (record.sequence && record.sequence.includes("signup")) {
+            // New feature attracts more signups
+            record.conversionRate *= 1.3;
+
+            // After improvements, conversion gets even better
+            if (funnelTime.isAfter(FEATURE_IMPROVEMENT)) {
+                record.conversionRate *= 1.2;
+            }
+        }
+    }
+}
+
+// Handle overall user stream modifications
+if (type === "everything") {
+    const firstEventTime = record[0] ? dayjs(record[0].time) : dayjs();
+
+    // Users who joined after feature launch are more engaged
+    if (firstEventTime.isAfter(FEATURE_LAUNCH)) {
+        // These users generate 50% more events
+        const additionalEvents = Math.floor(record.length * 0.5);
+
+        for (let i = 0; i < additionalEvents; i++) {
+            if (record.length > 0 && chance.bool({ likelihood: 70 })) {
+                // Clone and modify random events
+                const sourceEvent = record[u.integer(0, record.length - 1)];
+                const newEvent = v.clone(sourceEvent);
+
+                // Adjust time and properties
+                newEvent.time = dayjs(sourceEvent.time).add(u.integer(1, 60), 'minutes').toISOString();
+                newEvent["feature_related"] = true;
+
+                // Add to stream
+                record.push(newEvent);
+            }
+        }
+
+        // Sort events by time after additions
+        record.sort((a, b) => new Date(a.time) - new Date(b.time));
+    }
+}
+
+return record;
+
 === KEY PATTERNS FOR ENGINEERING TRENDS ===
 
 1. **Time-Based Changes**: Define key dates (product launches, feature changes, bugs fixed) and modify behavior before/after
@@ -425,10 +678,44 @@ return record;
 
 YOUR OUTPUT:
 
-Generate ONLY the hook function body (the code between the curly braces). Do not include:
-- The "hook: function (record, type, meta) {" wrapper
-- The closing "}" of the function
-- Any explanations or comments outside the code
-- Any markdown formatting
+You MUST output a COMPLETE JavaScript function that can be directly stored and executed.
+
+REQUIRED FORMAT:
+```
+function(record, type, meta) {
+    // Your hook implementation here
+    // Can handle multiple types in one function
+    // Must always return record at the end
+    return record;
+}
+```
+
+OUTPUT REQUIREMENTS:
+✅ MUST include the function declaration: function(record, type, meta) {
+✅ MUST include all hook logic in the function body
+✅ MUST include the closing brace: }
+✅ MUST return record at the end (even if modified or filtered)
+❌ DO NOT include markdown formatting or backticks
+❌ DO NOT include explanations outside the function
+❌ DO NOT include anything except the JavaScript function
+
+Example of CORRECT output:
+```
+function(record, type, meta) {
+    if (type === "event") {
+        // Modify individual events
+        if (record.event === "purchase") {
+            record.amount *= 1.1;
+        }
+    }
+
+    if (type === "everything") {
+        // Modify full event stream
+        record = record.filter(e => e.event !== "test");
+    }
+
+    return record;
+}
+```
 
-Your output should be pure JavaScript code that can be directly inserted into a hook function.
+Your entire output should be exactly one JavaScript function that starts with function(record, type, meta) { and ends with }