primitive-admin 1.0.37 → 1.0.39

package/dist/src/commands/analytics.js

@@ -1,49 +1,220 @@
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
-import { error, info, keyValue, formatTable, formatId, formatDate, formatNumber, formatPercent, formatDuration, json, divider, heading, } from "../lib/output.js";
+import { error, info, formatTable, formatId, formatDate, formatNumber, formatPercent, formatDuration, json, heading, keyValue, dim, } from "../lib/output.js";
+/** Format a value that is already a percentage (e.g. 33.3 → "33.3%") */
+function formatPctRaw(value) {
+    if (value === undefined || value === null)
+        return "-";
+    return `${value.toFixed(1)}%`;
+}
 export function registerAnalyticsCommands(program) {
     const analytics = program
         .command("analytics")
         .description("View usage analytics, user activity, and integration metrics")
         .addHelpText("after", `
+Commands:
+  overview                   DAU / WAU / MAU and growth accounting
+  daily-active               Daily active users time series
+  rolling-active             Rolling active users (28 points)
+  cohort-retention           Weekly cohort retention matrix
+  top-users                  Most active users
+  user-search                Search users by email or ULID
+  user-detail                Detailed activity for a single user
+  user-snapshot              Latest context snapshot for a user
+  events                     Paginated event feed
+  events-grouped             Events grouped by a dimension
+  integrations               Integration usage metrics
+  workflows                  Top workflows by runs
+  prompts                    Top prompts by executions
+
 Examples:
   $ primitive analytics overview
-  $ primitive analytics top-users --window-days 7 --limit 20
-  $ primitive analytics integrations
+  $ primitive analytics daily-active --window-days 14
+  $ primitive analytics top-users --limit 20
+  $ primitive analytics user-search --query user@example.com
+  $ primitive analytics user-detail <user-ulid>
+  $ primitive analytics events --window-days 7 --page 0
+  $ primitive analytics events-grouped --group-by feature
+  $ primitive analytics cohort-retention
+  $ primitive analytics workflows --limit 5
+  $ primitive analytics prompts --window-days 14
 `);
-    // Overview
+    // ── Overview (DAU / WAU / MAU / Growth) ──────────────────────────
     analytics
         .command("overview")
-        .description("Get analytics overview for an app")
+        .description("Show DAU, WAU, MAU, and growth accounting")
         .argument("[app-id]", "App ID (uses current app if not specified)")
         .option("--app <app-id>", "App ID")
-        .option("--window-days <n>", "Time window in days", "30")
+        .option("--window-days <n>", "Growth window in days", "28")
         .option("--json", "Output as JSON")
         .action(async (appId, options) => {
         const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         try {
-            const result = await client.getAnalyticsOverview(resolvedAppId, {
+            const [dau, wau, mau, growth] = await Promise.all([
+                client.getAnalyticsOverviewDau(resolvedAppId),
+                client.getAnalyticsOverviewWau(resolvedAppId),
+                client.getAnalyticsOverviewMau(resolvedAppId),
+                client.getAnalyticsOverviewGrowth(resolvedAppId, {
+                    windowDays: parseInt(options.windowDays),
+                }),
+            ]);
+            if (options.json) {
+                json({ dau, wau, mau, growth });
+                return;
+            }
+            heading("Active Users");
+            console.log();
+            const formatDelta = (d) => d > 0 ? `+${(d * 100).toFixed(1)}%` : d === 0 ? "0%" : `${(d * 100).toFixed(1)}%`;
+            console.log(formatTable([
+                { metric: "DAU", value: dau.value, previous: dau.previous, delta: formatDelta(dau.deltaPct) },
+                { metric: "WAU", value: wau.value, previous: wau.previous, delta: formatDelta(wau.deltaPct) },
+                { metric: "MAU", value: mau.value, previous: mau.previous, delta: formatDelta(mau.deltaPct) },
+            ], [
+                { header: "METRIC", key: "metric" },
+                { header: "CURRENT", key: "value", align: "right", format: formatNumber },
+                { header: "PREVIOUS", key: "previous", align: "right", format: formatNumber },
+                { header: "CHANGE", key: "delta", align: "right" },
+            ]));
+            console.log();
+            heading(`Growth Accounting (${growth.window_days} days)`);
+            console.log();
+            keyValue("Current active", String(growth.current_active));
+            keyValue("Previous active", String(growth.previous_active));
+            keyValue("New users", String(growth.new_users));
+            keyValue("Retained", String(growth.retained_users));
+            keyValue("Reactivated", String(growth.reactivated_users));
+            keyValue("Churned", String(growth.churned_users));
+            keyValue("Delta", formatDelta(growth.deltaPct));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Daily Active ─────────────────────────────────────────────────
+    analytics
+        .command("daily-active")
+        .description("Daily active users time series")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", "Time window in days (7-90)", "28")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsDailyActive(resolvedAppId, {
                 windowDays: parseInt(options.windowDays),
             });
             if (options.json) {
                 json(result);
                 return;
             }
-            heading(`Analytics Overview (${result.windowDays} days)`);
+            heading(`Daily Active Users (${result.window_days} days)`);
             console.log();
-            keyValue("Daily Active Users (DAU)", formatNumber(result.totals.dau));
-            keyValue("Weekly Active Users (WAU)", formatNumber(result.totals.wau));
-            keyValue("Monthly Active Users (MAU)", formatNumber(result.totals.mau));
-            keyValue("Total Events", formatNumber(result.totals.totalEvents));
-            if (result.series && result.series.length > 0) {
-                divider();
-                info("Activity Series:");
-                console.log(formatTable(result.series.slice(-10), [
-                    { header: "DATE", key: "bucketStart", format: (v) => v.slice(0, 10) },
-                    { header: "USERS", key: "activeUsers", align: "right" },
-                    { header: "EVENTS", key: "totalEvents", align: "right" },
-                ]));
+            if (!result.rows || result.rows.length === 0) {
+                info("No data found.");
+                return;
+            }
+            console.log(formatTable(result.rows, [
+                { header: "DATE", key: "day_label" },
+                { header: "ACTIVE USERS", key: "active_users", align: "right", format: formatNumber },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Rolling Active ───────────────────────────────────────────────
+    analytics
+        .command("rolling-active")
+        .description("Rolling active users (28 data points)")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", "Rolling window size in days (1-28)", "7")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsRollingActive(resolvedAppId, {
+                windowDays: parseInt(options.windowDays),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading(`Rolling Active Users (${result.window_days}-day window)`);
+            console.log();
+            if (!result.rows || result.rows.length === 0) {
+                info("No data found.");
+                return;
+            }
+            console.log(formatTable(result.rows, [
+                { header: "DATE", key: "day_label" },
+                { header: "ACTIVE USERS", key: "active_users", align: "right", format: formatNumber },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Cohort Retention ─────────────────────────────────────────────
+    analytics
+        .command("cohort-retention")
+        .description("Weekly cohort retention matrix")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsCohortRetention(resolvedAppId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading("Cohort Retention");
+            console.log();
+            if (!result.rows || result.rows.length === 0) {
+                info("No cohort data found.");
+                return;
+            }
+            // Build week headers
+            const weekHeaders = result.weeks.map((w) => `W${w}`);
+            // Build table rows with retention percentages
+            const tableRows = result.rows.map((row) => {
+                const entry = {
+                    cohort: row.signup_week_label,
+                    size: row.cohort_size,
+                };
+                row.retention.forEach((r, i) => {
+                    entry[`w${result.weeks[i]}`] =
+                        r !== null ? `${r.toFixed(0)}%` : "-";
+                });
+                return entry;
+            });
+            const columns = [
+                { header: "COHORT", key: "cohort" },
+                { header: "SIZE", key: "size", align: "right", format: formatNumber },
+                ...weekHeaders.map((h, i) => ({
+                    header: h,
+                    key: `w${result.weeks[i]}`,
+                    align: "right",
+                })),
+            ];
+            console.log(formatTable(tableRows, columns));
+            // Print averages row
+            if (result.averages) {
+                const avgStr = result.averages
+                    .map((a) => a !== null ? `${a.toFixed(0)}%` : "-")
+                    .join("  ");
+                console.log();
+                dim(`Averages: ${avgStr}`);
             }
         }
         catch (err) {
@@ -51,7 +222,7 @@ Examples:
             process.exit(1);
         }
     });
-    // Top users
+    // ── Top Users ────────────────────────────────────────────────────
     analytics
         .command("top-users")
         .description("Get top users by activity")
@@ -80,6 +251,7 @@ Examples:
             }
             console.log(formatTable(result.results, [
                 { header: "USER", key: "userUlid", format: formatId },
+                { header: "EMAIL", key: "email" },
                 { header: "EVENTS", key: "eventCount", align: "right" },
                 { header: "FIRST SEEN", key: "firstSeen", format: formatDate },
                 { header: "LAST SEEN", key: "lastSeen", format: formatDate },
@@ -90,53 +262,93 @@ Examples:
             process.exit(1);
         }
     });
-    // User details
+    // ── User Search ──────────────────────────────────────────────────
     analytics
-        .command("user")
-        .description("Get analytics for a specific user")
+        .command("user-search")
+        .description("Search users by email or ULID")
         .argument("[app-id]", "App ID (uses current app if not specified)")
-        .argument("<user-ulid>", "User ULID")
         .option("--app <app-id>", "App ID")
-        .option("--window-days <n>", "Time window in days", "30")
+        .requiredOption("--query <q>", "Email or ULID to search for")
+        .option("--limit <n>", "Max results", "25")
         .option("--json", "Output as JSON")
-        .action(async (appIdOrUserUlid, userUlidOrUndefined, options) => {
-        let resolvedAppId;
-        let userUlid;
-        if (userUlidOrUndefined) {
-            resolvedAppId = resolveAppId(appIdOrUserUlid, options);
-            userUlid = userUlidOrUndefined;
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsUserSearch(resolvedAppId, {
+                q: options.query,
+                limit: parseInt(options.limit),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading(`User Search: "${result.query}"`);
+            console.log();
+            if (!result.results || result.results.length === 0) {
+                info("No users found.");
+                return;
+            }
+            console.log(formatTable(result.results, [
+                { header: "USER", key: "userUlid", format: formatId },
+                { header: "EMAIL", key: "email" },
+                { header: "NAME", key: "name" },
+                { header: "EVENTS", key: "eventCount", align: "right" },
+                { header: "LAST SEEN", key: "lastSeen", format: formatDate },
+            ]));
         }
-        else {
-            resolvedAppId = resolveAppId(undefined, options);
-            userUlid = appIdOrUserUlid;
+        catch (err) {
+            error(err.message);
+            process.exit(1);
         }
+    });
+    // ── User Detail ──────────────────────────────────────────────────
+    analytics
+        .command("user-detail")
+        .description("Detailed activity for a single user")
+        .argument("<user-ulid>", "User ULID")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (userUlid, appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         try {
-            const result = await client.getAnalyticsUserTimeline(resolvedAppId, userUlid, {
-                windowDays: parseInt(options.windowDays),
-            });
+            const result = await client.getAnalyticsUserDetail(resolvedAppId, userUlid);
             if (options.json) {
                 json(result);
                 return;
             }
-            heading(`User Activity (${result.windowDays} days)`);
-            keyValue("User", userUlid);
+            heading("User Detail");
             console.log();
-            if (result.breakdown && result.breakdown.length > 0) {
-                info("Activity Breakdown:");
-                console.log(formatTable(result.breakdown.slice(0, 15), [
+            keyValue("ULID", result.user.user_ulid);
+            if (result.user.email)
+                keyValue("Email", result.user.email);
+            if (result.user.name)
+                keyValue("Name", result.user.name);
+            console.log();
+            keyValue("First seen", result.stats.first_seen ? formatDate(result.stats.first_seen) : "-");
+            keyValue("Last active", result.stats.last_active ? formatDate(result.stats.last_active) : "-");
+            keyValue("Total events", String(result.stats.total_events));
+            keyValue("Days active", String(result.stats.days_active));
+            if (result.events_by_action?.length > 0) {
+                console.log();
+                heading("Events by Action");
+                console.log();
+                console.log(formatTable(result.events_by_action, [
                     { header: "ACTION", key: "action" },
-                    { header: "FEATURE", key: "feature" },
-                    { header: "ROUTE", key: "route" },
-                    { header: "EVENTS", key: "events", align: "right" },
+                    { header: "COUNT", key: "event_count", align: "right", format: formatNumber },
+                    { header: "LAST OCCURRED", key: "last_occurred", format: formatDate },
                 ]));
             }
-            if (result.timeline && result.timeline.length > 0) {
-                divider();
-                info("Recent Timeline:");
-                console.log(formatTable(result.timeline.slice(-10), [
-                    { header: "TIME", key: "bucketStart", format: formatDate },
-                    { header: "EVENTS", key: "events", align: "right" },
+            if (result.events_by_feature?.length > 0) {
+                console.log();
+                heading("Events by Feature");
+                console.log();
+                console.log(formatTable(result.events_by_feature, [
+                    { header: "FEATURE", key: "feature" },
+                    { header: "COUNT", key: "event_count", align: "right", format: formatNumber },
+                    { header: "PCT", key: "pct", align: "right", format: formatPctRaw },
                 ]));
             }
         }
@@ -145,7 +357,123 @@ Examples:
             process.exit(1);
         }
     });
-    // Integration metrics
+    // ── User Snapshot ────────────────────────────────────────────────
+    analytics
+        .command("user-snapshot")
+        .description("Latest context snapshot for a user")
+        .argument("<user-ulid>", "User ULID")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (userUlid, appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsUserSnapshot(resolvedAppId, userUlid);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading("User Snapshot");
+            console.log();
+            if (!result.snapshot) {
+                info("No snapshot found for this user.");
+                return;
+            }
+            keyValue("Timestamp", formatDate(result.snapshot.timestamp));
+            console.log();
+            console.log(JSON.stringify(result.snapshot.values, null, 2));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Events Feed ──────────────────────────────────────────────────
+    analytics
+        .command("events")
+        .description("Paginated event feed")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", "Time window in days", "7")
+        .option("--page <n>", "Page number (0-based)", "0")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsEvents(resolvedAppId, {
+                windowDays: parseInt(options.windowDays),
+                page: parseInt(options.page),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading(`Events (page ${result.page}, ${result.total_rows} total)`);
+            console.log();
+            if (!result.rows || result.rows.length === 0) {
+                info("No events found.");
+                return;
+            }
+            console.log(formatTable(result.rows, [
+                { header: "TIME", key: "timestamp", format: formatDate },
+                { header: "USER", key: "user_ulid", format: formatId },
+                { header: "ACTION", key: "action" },
+                { header: "FEATURE", key: "feature" },
+                { header: "ROUTE", key: "route" },
+                { header: "COUNTRY", key: "country" },
+            ]));
+            const totalPages = Math.ceil(result.total_rows / result.page_size);
+            if (result.page + 1 < totalPages) {
+                console.log();
+                dim(`Page ${result.page + 1} of ${totalPages}. Use --page ${result.page + 1} for the next page.`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Events Grouped ───────────────────────────────────────────────
+    analytics
+        .command("events-grouped")
+        .description("Events grouped by a dimension")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--group-by <dim>", "Dimension: action, feature, route, country, deviceType, plan, day", "action")
+        .option("--window-days <n>", "Time window in days", "7")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsEventsGrouped(resolvedAppId, {
+                groupBy: options.groupBy,
+                windowDays: parseInt(options.windowDays),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading(`Events by ${result.group_by}`);
+            console.log();
+            if (!result.rows || result.rows.length === 0) {
+                info("No events found.");
+                return;
+            }
+            console.log(formatTable(result.rows, [
+                { header: result.group_by.toUpperCase(), key: "group_value" },
+                { header: "EVENTS", key: "events", align: "right", format: formatNumber },
+                { header: "UNIQUE USERS", key: "unique_users", align: "right", format: formatNumber },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Integration Metrics ──────────────────────────────────────────
     analytics
         .command("integrations")
         .description("Get integration usage metrics")
@@ -174,8 +502,89 @@ Examples:
                 { header: "INTEGRATION", key: "integrationKey" },
                 { header: "CALLS", key: "invocations", align: "right", format: formatNumber },
                 { header: "ERROR RATE", key: "errorRate", align: "right", format: formatPercent },
-                { header: "AVG LATENCY", key: "avgDurationMs", align: "right", format: formatDuration },
-                { header: "P95 LATENCY", key: "p95DurationMs", align: "right", format: formatDuration },
+                { header: "MEDIAN", key: "medianDurationMs", align: "right", format: formatDuration },
+                { header: "P95", key: "p95DurationMs", align: "right", format: formatDuration },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Top Workflows ────────────────────────────────────────────────
+    analytics
+        .command("workflows")
+        .description("Top workflows by runs")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", "Time window in days", "30")
+        .option("--limit <n>", "Number of workflows to show", "10")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsTopWorkflows(resolvedAppId, {
+                windowDays: parseInt(options.windowDays),
+                limit: parseInt(options.limit),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading(`Top Workflows (${result.windowDays} days)`);
+            console.log();
+            if (!result.workflows || result.workflows.length === 0) {
+                info("No workflow data found.");
+                return;
+            }
+            console.log(formatTable(result.workflows, [
+                { header: "WORKFLOW", key: "workflowKey" },
+                { header: "RUNS", key: "runs", align: "right", format: formatNumber },
+                { header: "SUCCESS", key: "successRate", align: "right", format: formatPercent },
+                { header: "MEDIAN", key: "medianDurationMs", align: "right", format: formatDuration },
+                { header: "P95", key: "p95", align: "right", format: formatDuration },
+                { header: "TOKENS", key: "totalTokens", align: "right", format: formatNumber },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Top Prompts ──────────────────────────────────────────────────
+    analytics
+        .command("prompts")
+        .description("Top prompts by executions")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", "Time window in days", "30")
+        .option("--limit <n>", "Number of prompts to show", "10")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsTopPrompts(resolvedAppId, {
+                windowDays: parseInt(options.windowDays),
+                limit: parseInt(options.limit),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading(`Top Prompts (${result.windowDays} days)`);
+            console.log();
+            if (!result.prompts || result.prompts.length === 0) {
+                info("No prompt data found.");
+                return;
+            }
+            console.log(formatTable(result.prompts, [
+                { header: "PROMPT", key: "promptKey" },
+                { header: "RUNS", key: "executions", align: "right", format: formatNumber },
+                { header: "MEDIAN", key: "medianDurationMs", align: "right", format: formatDuration },
+                { header: "P95", key: "p95DurationMs", align: "right", format: formatDuration },
+                { header: "TOKENS", key: "totalTokens", align: "right", format: formatNumber },
             ]));
         }
         catch (err) {