@gurulu/cli 0.4.4 → 0.4.5

package/dist/commands/audiences.d.ts

@@ -15,5 +15,9 @@ export interface AudiencesArgs {
     rules?: string;
     yes?: boolean;
     dryRun?: boolean;
+    format?: 'csv' | 'json' | string;
+    output?: string;
+    preview?: boolean;
+    limit?: number;
 }
 export declare function audiencesCommand(args: AudiencesArgs): Promise<void>;

package/dist/commands/audiences.js

@@ -5,6 +5,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.audiencesCommand = audiencesCommand;
+const node_fs_1 = require("node:fs");
 const api_client_1 = require("../api-client");
 const ui_1 = require("../utils/ui");
 const confirm_1 = require("../utils/confirm");
@@ -23,9 +24,11 @@ async function audiencesCommand(args) {
             return updateCmd(args);
         case 'delete':
             return deleteCmd(args);
+        case 'export':
+            return exportCmd(args);
         default:
             (0, ui_1.error)(`Unknown audiences action: ${action}`);
-            (0, ui_1.info)('Usage: gurulu audiences [list|show|create|update|delete]');
+            (0, ui_1.info)('Usage: gurulu audiences [list|show|create|update|delete|export]');
             process.exit(1);
     }
 }
@@ -205,3 +208,36 @@ async function deleteCmd(args) {
     });
     (0, ui_1.success)(`Deleted audience ${id}`);
 }
+/**
+ * AU5 (audit-2026-04-29-audience.md) — `gurulu audiences export <name-or-id>`.
+ * Streams the current audience membership as CSV (default) or JSON. With
+ * `--output <path>` we write to disk; otherwise the body goes to stdout.
+ */
+async function exportCmd(args) {
+    const target = args.target;
+    if (!target) {
+        (0, ui_1.error)('Usage: gurulu audiences export <name-or-id> [--format csv|json] [--output file]');
+        process.exit(1);
+    }
+    const id = await resolveId(target, args.profile);
+    const format = (args.format || 'csv').toLowerCase();
+    if (format !== 'csv' && format !== 'json') {
+        (0, ui_1.error)('--format must be csv or json');
+        process.exit(1);
+    }
+    const path = `/api/cli/audiences/${encodeURIComponent(id)}/export?format=${format}&destination=download`;
+    const res = await (0, api_client_1.cliApi)(path, { profile: args.profile });
+    const body = await res.text();
+    if (!res.ok) {
+        (0, ui_1.error)(`Export failed (HTTP ${res.status}): ${body.slice(0, 200)}`);
+        process.exit(1);
+    }
+    if (args.output) {
+        (0, node_fs_1.writeFileSync)(args.output, body, 'utf8');
+        (0, ui_1.success)(`Wrote ${body.length} bytes to ${args.output}`);
+        return;
+    }
+    process.stdout.write(body);
+    if (!body.endsWith('\n'))
+        process.stdout.write('\n');
+}

package/dist/commands/events.js

@@ -184,7 +184,13 @@ async function defineCmd(args) {
             process.exit(1);
         }
     }
-    const eventName = args.eventName.startsWith('$') ? args.eventName : `$${args.eventName}`;
+    // Use the user-provided name verbatim. The CLI used to force a `$` prefix
+    // because Gurulu's built-ins use one (`$page_view`, `$session_start`), but
+    // built-ins are inconsistent (`click`, `engaged_session` have none) and
+    // mutating the customer's chosen name silently broke schema lookups + made
+    // the generated SDK snippets reference a name that no longer matched the
+    // ingest payload.
+    const eventName = args.eventName;
     const body = {
         siteId: args.site,
         eventName,
@@ -207,10 +213,14 @@ async function verifyCmd(args) {
         (0, ui_1.error)('--site is required.');
         process.exit(1);
     }
+    // Accept both `--event` (verify-original) and `--event-name` (used by
+    // every other events subcommand). Removes the surprising flag-name
+    // inconsistency without breaking existing scripts.
+    const filterEvent = args.event || args.eventName;
     const qs = new URLSearchParams();
     qs.set('siteId', args.site);
-    if (args.event)
-        qs.set('eventName', args.event);
+    if (filterEvent)
+        qs.set('eventName', filterEvent);
     const path = `/api/cli/events/health?${qs.toString()}`;
     const data = await (0, api_client_1.cliApiJson)(path, { profile: args.profile });
     if (args.json) {
@@ -220,7 +230,7 @@ async function verifyCmd(args) {
     console.log((0, ui_1.bold)('\nEvent Health Report'));
     console.log(`Site: ${args.site}`);
     console.log('');
-    if (Array.isArray(data.events)) {
+    if (Array.isArray(data.events) && data.events.length > 0) {
         for (const ev of data.events) {
             const statusIcon = ev.status === 'active'
                 ? (0, ui_1.green)('●')
@@ -237,6 +247,17 @@ async function verifyCmd(args) {
         console.log(`Total events (24h): ${data.total_events}`);
         console.log(`Unique event types: ${data.unique_types ?? 'N/A'}`);
     }
+    else {
+        // Empty: no telemetry yet for the requested filter / definition. Without
+        // this branch the report printed only its header — users couldn't tell
+        // success from "no data found".
+        if (filterEvent) {
+            (0, ui_1.info)(`No telemetry yet for "${filterEvent}". Track it from your app and run verify again.`);
+        }
+        else {
+            (0, ui_1.info)('No telemetry data found for this site in the last 24h.');
+        }
+    }
     console.log('');
 }
 /* ── templates: list vertical event template catalogs ───────────── */

package/dist/commands/heatmap.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sprint J-Heat HM10 — `gurulu heatmap ...` subcommands.
+ *
+ * Read-only surface backed by `/api/cli/heatmap/list` and
+ * `/api/cli/heatmap/get`. Lets agents and operators inspect heatmap
+ * snapshots without opening the dashboard.
+ *
+ *   gurulu heatmap list   --site <id|name>           [--range 7d|30d] [--json]
+ *   gurulu heatmap export --site <id|name> --page <pageUrl>
+ *                                                    [--type click|scroll]
+ *                                                    [--range 7d|30d]
+ *                                                    [--viewport mobile|tablet|desktop]
+ *                                                    [--page-id <hash>]
+ *                                                    [--json]
+ */
+export interface HeatmapArgs {
+    action?: string;
+    site?: string;
+    page?: string;
+    pageId?: string;
+    type?: string;
+    range?: string;
+    viewport?: string;
+    json?: boolean;
+    profile?: string;
+}
+export declare function heatmapCommand(args: HeatmapArgs): Promise<void>;

package/dist/commands/heatmap.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Sprint J-Heat HM10 — `gurulu heatmap ...` subcommands.
+ *
+ * Read-only surface backed by `/api/cli/heatmap/list` and
+ * `/api/cli/heatmap/get`. Lets agents and operators inspect heatmap
+ * snapshots without opening the dashboard.
+ *
+ *   gurulu heatmap list   --site <id|name>           [--range 7d|30d] [--json]
+ *   gurulu heatmap export --site <id|name> --page <pageUrl>
+ *                                                    [--type click|scroll]
+ *                                                    [--range 7d|30d]
+ *                                                    [--viewport mobile|tablet|desktop]
+ *                                                    [--page-id <hash>]
+ *                                                    [--json]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.heatmapCommand = heatmapCommand;
+const api_client_1 = require("../api-client");
+const ui_1 = require("../utils/ui");
+async function resolveSiteId(target, profile) {
+    if (!target)
+        throw new Error('--site is required');
+    const body = await (0, api_client_1.cliApiJson)('/api/cli/sites', { profile });
+    const sites = body.sites || [];
+    const byId = sites.find((s) => s.id === target);
+    if (byId)
+        return byId.id;
+    const byName = sites.find((s) => s.name === target);
+    if (byName)
+        return byName.id;
+    const byDomain = sites.find((s) => s.domain === target);
+    if (byDomain)
+        return byDomain.id;
+    const prefix = sites.find((s) => s.id.startsWith(target));
+    if (prefix)
+        return prefix.id;
+    throw new Error(`Site '${target}' not found.`);
+}
+async function heatmapCommand(args) {
+    const action = args.action || 'list';
+    switch (action) {
+        case 'list':
+            return listCmd(args);
+        case 'export':
+            return exportCmd(args);
+        default:
+            (0, ui_1.error)(`Unknown heatmap action: ${action}`);
+            (0, ui_1.info)('Usage: gurulu heatmap [list|export]');
+            process.exit(1);
+    }
+}
+async function listCmd(args) {
+    if (!args.site) {
+        (0, ui_1.error)('--site is required.');
+        process.exit(1);
+    }
+    const siteId = await resolveSiteId(args.site, args.profile);
+    const range = args.range === '30d' ? '30d' : '7d';
+    const body = await (0, api_client_1.cliApiJson)(`/api/cli/heatmap/list?siteId=${encodeURIComponent(siteId)}&range=${range}`, {
+        profile: args.profile,
+    });
+    if (args.json) {
+        process.stdout.write(JSON.stringify(body, null, 2) + '\n');
+        return;
+    }
+    const pages = body.pages || [];
+    if (pages.length === 0) {
+        (0, ui_1.info)(`No heatmap data for site '${body.siteName}' (range=${range}).`);
+        return;
+    }
+    process.stdout.write(['CLICKS', 'VISITORS', 'M/T/D', 'LAST SEEN', 'PAGE URL'].join('\t') + '\n');
+    for (const p of pages) {
+        const mtd = `${p.viewportBuckets.mobile}/${p.viewportBuckets.tablet}/${p.viewportBuckets.desktop}`;
+        process.stdout.write([
+            String(p.clickCount),
+            String(p.visitors),
+            mtd,
+            String(p.lastSeen).slice(0, 19),
+            p.pageUrl,
+        ].join('\t') + '\n');
+    }
+}
+async function exportCmd(args) {
+    if (!args.site) {
+        (0, ui_1.error)('--site is required.');
+        process.exit(1);
+    }
+    if (!args.page) {
+        (0, ui_1.error)('--page <pageUrl> is required.');
+        process.exit(1);
+    }
+    const siteId = await resolveSiteId(args.site, args.profile);
+    const range = args.range === '30d' ? '30d' : '7d';
+    const type = args.type === 'scroll' ? 'scroll' : 'click';
+    const qp = new URLSearchParams({
+        siteId,
+        pageUrl: args.page,
+        range,
+        type,
+    });
+    if (args.pageId)
+        qp.set('pageId', args.pageId);
+    if (args.viewport)
+        qp.set('viewportBucket', args.viewport);
+    const body = await (0, api_client_1.cliApiJson)(`/api/cli/heatmap/get?${qp.toString()}`, {
+        profile: args.profile,
+    });
+    // Export commands always emit machine-readable output by default; the
+    // `--json` flag is accepted for symmetry with the rest of the CLI.
+    process.stdout.write(JSON.stringify(body, null, args.json ? 2 : 0) + '\n');
+}

package/dist/index.js

@@ -34,6 +34,8 @@ const audit_1 = require("./commands/audit");
 // Goals & Funnels CRUD
 const goals_1 = require("./commands/goals");
 const funnels_1 = require("./commands/funnels");
+// Sprint J-Heat HM10 — heatmap read surface
+const heatmap_1 = require("./commands/heatmap");
 // Gurulu Chat — NL → SQL analytics
 const chat_1 = require("./commands/chat");
 // Error tracking — source map upload
@@ -323,8 +325,11 @@ const secrets_1 = require("./commands/secrets");
     });
 })
     // ── Phase 19.5 W2 — read-surface subcommands ─────────────────────────
-    .command('audiences <action> [target]', 'Manage audiences (list, show, create, update, delete)', (y) => y
-    .positional('action', { type: 'string', describe: 'list | show | create | update | delete' })
+    .command('audiences <action> [target]', 'Manage audiences (list, show, create, update, delete, export)', (y) => y
+    .positional('action', {
+    type: 'string',
+    describe: 'list | show | create | update | delete | export',
+})
     .positional('target', { type: 'string', describe: 'Audience name or id' })
     .option('site', { type: 'string', describe: 'Site ID' })
     .option('id', { type: 'string', describe: 'Audience ID (for update/delete)' })
@@ -334,6 +339,15 @@ const secrets_1 = require("./commands/secrets");
     .option('from-file', { type: 'string', describe: 'Load payload from JSON file' })
     .option('dry-run', { type: 'boolean', describe: 'Show what would be done' })
     .option('yes', { type: 'boolean', alias: 'y', describe: 'Skip confirmation' })
+    // AU5 — export options
+    .option('format', {
+    type: 'string',
+    describe: 'Export format: csv | json (default csv)',
+})
+    .option('output', {
+    type: 'string',
+    describe: 'Write export body to this file (default stdout)',
+})
     .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, audiences_1.audiencesCommand)({
     action: args.action,
     target: args.target,
@@ -345,6 +359,8 @@ const secrets_1 = require("./commands/secrets");
     fromFile: args['from-file'],
     dryRun: args['dry-run'],
     yes: args.yes,
+    format: args.format,
+    output: args.output,
     json: args.json,
     profile: args.profile,
 }))
@@ -400,6 +416,10 @@ const secrets_1 = require("./commands/secrets");
 }))
     .command('insights <action>', 'View daily insights (today, history, weekly)', (y) => y
     .positional('action', { type: 'string', describe: 'today | history | weekly' })
+    // `--site` is accepted but ignored: insights are computed at tenant
+    // scope (across all sites). Accept it so the flag is consistent with
+    // the rest of the CLI and doesn't reject scripts that pass it.
+    .option('site', { type: 'string', describe: 'Site ID (accepted for consistency, currently tenant-scoped)' })
     .option('days', { type: 'number', describe: 'History window in days (1..30)' })
     .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, insights_1.insightsCommand)({
     action: args.action,
@@ -494,6 +514,40 @@ const secrets_1 = require("./commands/secrets");
     yes: args.yes,
     json: args.json,
     profile: args.profile,
+}))
+    .command('heatmap <action>', 'Inspect click + scroll heatmaps (list, export)', (y) => y
+    .positional('action', { type: 'string', describe: 'list | export' })
+    .option('site', { type: 'string', describe: 'Site name or id' })
+    .option('page', { type: 'string', describe: 'Page URL (for export)' })
+    .option('page-id', {
+    type: 'string',
+    describe: 'Virtual-page id (HM6, optional)',
+})
+    .option('type', {
+    type: 'string',
+    choices: ['click', 'scroll'],
+    describe: 'Heatmap type for export (default click)',
+})
+    .option('range', {
+    type: 'string',
+    choices: ['7d', '30d'],
+    describe: 'Lookback window (default 7d)',
+})
+    .option('viewport', {
+    type: 'string',
+    choices: ['mobile', 'tablet', 'desktop'],
+    describe: 'Filter to a viewport bucket (HM9)',
+})
+    .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, heatmap_1.heatmapCommand)({
+    action: args.action,
+    site: args.site,
+    page: args.page,
+    pageId: args['page-id'],
+    type: args.type,
+    range: args.range,
+    viewport: args.viewport,
+    json: args.json,
+    profile: args.profile,
 }))
     .command('identity <action> [sub]', 'Identity state + writes (decay stats | transfers list | cdc-sources list | identify | alias | merge | bulk)', (y) => y
     .positional('action', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gurulu/cli",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Gurulu.io CLI — setup analytics in seconds",
   "bin": {
     "gurulu": "bin/gurulu.js"