@agent-analytics/cli 0.1.7 → 0.1.9

package/README.md

@@ -8,35 +8,40 @@ Web analytics your AI agent can read. Drop a JS snippet on your site, query the
 # 1. Get your API key from https://api.agentanalytics.sh (sign in with GitHub)
 
 # 2. Save your key
-npx agent-analytics login --token aak_your_key
+npx @agent-analytics/cli login --token aak_your_key
 
 # 3. Create a project
-npx agent-analytics create my-site --domain https://mysite.com
+npx @agent-analytics/cli create my-site --domain https://mysite.com
 
 # 4. Check your stats
-npx agent-analytics stats my-site
+npx @agent-analytics/cli stats my-site
 ```
 
 ## Commands
 
 ```bash
 # Auth
-npx agent-analytics login --token <key>    # Save your API key
-npx agent-analytics whoami                  # Show current account
+npx @agent-analytics/cli login --token <key>    # Save your API key
+npx @agent-analytics/cli whoami                  # Show current account
 
 # Projects
-npx agent-analytics create <name> --domain <url>    # Create a project
-npx agent-analytics projects                        # List your projects
-npx agent-analytics delete <id>                     # Delete a project
+npx @agent-analytics/cli create <name> --domain <url>    # Create a project
+npx @agent-analytics/cli projects                        # List your projects
+npx @agent-analytics/cli delete <id>                     # Delete a project
 
 # Analytics
-npx agent-analytics stats <name>              # Stats (last 7 days)
-npx agent-analytics stats <name> --days 30    # Stats (last 30 days)
-npx agent-analytics events <name>             # Recent events
-npx agent-analytics properties-received <name>  # Property keys per event
+npx @agent-analytics/cli stats <name>              # Stats (last 7 days)
+npx @agent-analytics/cli stats <name> --days 30    # Stats (last 30 days)
+npx @agent-analytics/cli events <name>             # Recent events
+npx @agent-analytics/cli properties-received <name>  # Property keys per event
+npx @agent-analytics/cli insights <name>           # Period-over-period comparison (--period 7d)
+npx @agent-analytics/cli breakdown <name> --property path  # Top values for a property
+npx @agent-analytics/cli pages <name>              # Landing page performance (--type entry|exit|both)
+npx @agent-analytics/cli sessions-dist <name>      # Session duration histogram
+npx @agent-analytics/cli heatmap <name>            # Peak hours & busiest days
 
 # Security
-npx agent-analytics revoke-key     # Revoke and regenerate API key
+npx @agent-analytics/cli revoke-key     # Revoke and regenerate API key
 ```
 
 ## For AI Agents

package/bin/cli.mjs

@@ -4,17 +4,22 @@
  * agent-analytics CLI
  * 
  * Usage:
- *   npx agent-analytics login --token <key>  — Save your API key
- *   npx agent-analytics create <name>         — Create a project and get your snippet
- *   npx agent-analytics projects             — List your projects
- *   npx agent-analytics stats <name>         — Get stats for a project
- *   npx agent-analytics events <name>        — Get recent events
- *   npx agent-analytics properties-received <name> — Show property keys per event
- *   npx agent-analytics init <name>          — Alias for create
- *   npx agent-analytics delete <id>          — Delete a project
- *   npx agent-analytics revoke-key           — Revoke and regenerate API key
- *   npx agent-analytics delete-account       — Delete your account (opens dashboard)
- *   npx agent-analytics whoami               — Show current account
+ *   npx @agent-analytics/cli login --token <key>  — Save your API key
+ *   npx @agent-analytics/cli create <name>         — Create a project and get your snippet
+ *   npx @agent-analytics/cli projects             — List your projects
+ *   npx @agent-analytics/cli stats <name>         — Get stats for a project
+ *   npx @agent-analytics/cli events <name>        — Get recent events
+ *   npx @agent-analytics/cli properties-received <name> — Show property keys per event
+ *   npx @agent-analytics/cli insights <name>      — Period-over-period comparison
+ *   npx @agent-analytics/cli breakdown <name>     — Property value distribution
+ *   npx @agent-analytics/cli pages <name>         — Entry/exit page stats
+ *   npx @agent-analytics/cli sessions-dist <name> — Session duration distribution
+ *   npx @agent-analytics/cli heatmap <name>       — Peak hours & busiest days
+ *   npx @agent-analytics/cli init <name>          — Alias for create
+ *   npx @agent-analytics/cli delete <id>          — Delete a project
+ *   npx @agent-analytics/cli revoke-key           — Revoke and regenerate API key
+ *   npx @agent-analytics/cli delete-account       — Delete your account (opens dashboard)
+ *   npx @agent-analytics/cli whoami               — Show current account
  */
 
 import { AgentAnalyticsAPI } from '../lib/api.mjs';
@@ -37,7 +42,7 @@ function heading(msg) { log(`\n${BOLD}${msg}${RESET}`); }
 function requireKey() {
   const key = getApiKey();
   if (!key) {
-    error('Not logged in. Run: npx agent-analytics login');
+    error('Not logged in. Run: npx @agent-analytics/cli login');
   }
   return new AgentAnalyticsAPI(key, getBaseUrl());
 }
@@ -49,7 +54,7 @@ async function cmdLogin(token) {
     heading('Agent Analytics — Login');
     log('');
     log('Pass your API key from the dashboard:');
-    log(`  ${CYAN}npx agent-analytics login --token aak_your_key_here${RESET}`);
+    log(`  ${CYAN}npx @agent-analytics/cli login --token aak_your_key_here${RESET}`);
     log('');
     log('Or set it as an environment variable:');
     log(`  ${CYAN}export AGENT_ANALYTICS_API_KEY=aak_your_key_here${RESET}`);
@@ -71,15 +76,15 @@ async function cmdLogin(token) {
 
     success(`Logged in as ${BOLD}${account.github_login || account.email}${RESET}`);
     log(`${DIM}API key saved to ~/.config/agent-analytics/config.json${RESET}`);
-    log(`\nNext: ${CYAN}npx agent-analytics create my-site${RESET}`);
+    log(`\nNext: ${CYAN}npx @agent-analytics/cli create my-site${RESET}`);
   } catch (err) {
     error(`Invalid API key: ${err.message}`);
   }
 }
 
 async function cmdCreate(name, domain) {
-  if (!name) error('Usage: npx agent-analytics create <project-name> --domain https://mysite.com');
-  if (!domain) error('Usage: npx agent-analytics create <project-name> --domain https://mysite.com\n\nThe domain is required so we can restrict tracking to your site.');
+  if (!name) error('Usage: npx @agent-analytics/cli create <project-name> --domain https://mysite.com');
+  if (!domain) error('Usage: npx @agent-analytics/cli create <project-name> --domain https://mysite.com\n\nThe domain is required so we can restrict tracking to your site.');
 
   const api = requireKey();
 
@@ -115,7 +120,7 @@ async function cmdProjects() {
 
     if (!projects || projects.length === 0) {
       log('No projects yet. Create one:');
-      log(`  ${CYAN}npx agent-analytics create my-site${RESET}`);
+      log(`  ${CYAN}npx @agent-analytics/cli create my-site${RESET}`);
       return;
     }
 
@@ -135,7 +140,7 @@ async function cmdProjects() {
 }
 
 async function cmdStats(project, days = 7) {
-  if (!project) error('Usage: npx agent-analytics stats <project-name> [--days N]');
+  if (!project) error('Usage: npx @agent-analytics/cli stats <project-name> [--days N]');
 
   const api = requireKey();
 
@@ -192,7 +197,7 @@ async function cmdStats(project, days = 7) {
 }
 
 async function cmdEvents(project, opts = {}) {
-  if (!project) error('Usage: npx agent-analytics events <project-name> [--days N] [--limit N]');
+  if (!project) error('Usage: npx @agent-analytics/cli events <project-name> [--days N] [--limit N]');
 
   const api = requireKey();
 
@@ -221,7 +226,7 @@ async function cmdEvents(project, opts = {}) {
 }
 
 async function cmdPropertiesReceived(project, opts = {}) {
-  if (!project) error('Usage: npx agent-analytics properties-received <project-name> [--since DATE] [--sample N]');
+  if (!project) error('Usage: npx @agent-analytics/cli properties-received <project-name> [--since DATE] [--sample N]');
 
   const api = requireKey();
 
@@ -257,8 +262,153 @@ async function cmdPropertiesReceived(project, opts = {}) {
   }
 }
 
+async function cmdInsights(project, period = '7d') {
+  if (!project) error('Usage: npx @agent-analytics/cli insights <project-name> [--period 7d]');
+
+  const api = requireKey();
+
+  try {
+    const data = await api.getInsights(project, { period });
+
+    heading(`Insights: ${project} (${period} vs previous)`);
+    log('');
+
+    const m = data.metrics;
+    for (const [key, metric] of Object.entries(m)) {
+      const label = key.replace(/_/g, ' ');
+      const arrow = metric.change > 0 ? `${GREEN}↑` : metric.change < 0 ? `${RED}↓` : `${DIM}—`;
+      const pct = metric.change_pct !== null ? ` (${metric.change_pct > 0 ? '+' : ''}${metric.change_pct}%)` : '';
+      log(`  ${BOLD}${label}:${RESET}  ${metric.current} ${arrow}${pct}${RESET}  ${DIM}was ${metric.previous}${RESET}`);
+    }
+
+    log('');
+    log(`  ${BOLD}Trend:${RESET} ${data.trend}`);
+    log('');
+  } catch (err) {
+    error(`Failed to get insights: ${err.message}`);
+  }
+}
+
+async function cmdBreakdown(project, property, opts = {}) {
+  if (!project || !property) error('Usage: npx @agent-analytics/cli breakdown <project-name> --property <key> [--event page_view] [--limit 20]');
+
+  const api = requireKey();
+
+  try {
+    const data = await api.getBreakdown(project, { property, ...opts });
+
+    heading(`Breakdown: ${project} — ${property}${data.event ? ` (${data.event})` : ''}`);
+    log('');
+
+    if (!data.values || data.values.length === 0) {
+      log('  No data found.');
+      return;
+    }
+
+    for (const v of data.values) {
+      log(`  ${BOLD}${v.value}${RESET}  ${v.count} events  ${DIM}(${v.unique_users} users)${RESET}`);
+    }
+    log(`\n${DIM}${data.total_with_property} of ${data.total_events} events have this property${RESET}`);
+    log('');
+  } catch (err) {
+    error(`Failed to get breakdown: ${err.message}`);
+  }
+}
+
+async function cmdPages(project, type = 'entry', opts = {}) {
+  if (!project) error('Usage: npx @agent-analytics/cli pages <project-name> [--type entry|exit|both] [--limit 20]');
+
+  const api = requireKey();
+
+  try {
+    const data = await api.getPages(project, { type, ...opts });
+
+    heading(`Pages: ${project} (${type})`);
+    log('');
+
+    const pages = data.entry_pages || data.exit_pages || [];
+    if (pages.length === 0) {
+      log('  No page data found.');
+      return;
+    }
+
+    for (const p of pages) {
+      const bounceStr = `${Math.round(p.bounce_rate * 100)}% bounce`;
+      const durStr = `${Math.round(p.avg_duration / 1000)}s avg`;
+      log(`  ${BOLD}${p.page}${RESET}  ${p.sessions} sessions  ${DIM}${bounceStr}  ${durStr}  ${p.avg_events} events/session${RESET}`);
+    }
+
+    if (data.exit_pages && data.entry_pages) {
+      log('');
+      heading('Exit pages:');
+      for (const p of data.exit_pages) {
+        log(`  ${BOLD}${p.page}${RESET}  ${p.sessions} sessions`);
+      }
+    }
+    log('');
+  } catch (err) {
+    error(`Failed to get pages: ${err.message}`);
+  }
+}
+
+async function cmdSessionsDist(project) {
+  if (!project) error('Usage: npx @agent-analytics/cli sessions-dist <project-name>');
+
+  const api = requireKey();
+
+  try {
+    const data = await api.getSessionDistribution(project);
+
+    heading(`Session Distribution: ${project}`);
+    log('');
+
+    if (!data.distribution || data.distribution.length === 0) {
+      log('  No session data found.');
+      return;
+    }
+
+    for (const b of data.distribution) {
+      const bar = '█'.repeat(Math.min(Math.ceil(b.pct / 2), 40));
+      log(`  ${b.bucket.padEnd(7)}  ${GREEN}${bar}${RESET}  ${b.sessions} (${b.pct}%)`);
+    }
+
+    log('');
+    log(`  ${BOLD}Median:${RESET} ${data.median_bucket}  ${BOLD}Engaged:${RESET} ${data.engaged_pct}% (sessions ≥30s)`);
+    log('');
+  } catch (err) {
+    error(`Failed to get session distribution: ${err.message}`);
+  }
+}
+
+async function cmdHeatmap(project) {
+  if (!project) error('Usage: npx @agent-analytics/cli heatmap <project-name>');
+
+  const api = requireKey();
+
+  try {
+    const data = await api.getHeatmap(project);
+
+    heading(`Heatmap: ${project}`);
+    log('');
+
+    if (!data.heatmap || data.heatmap.length === 0) {
+      log('  No heatmap data found.');
+      return;
+    }
+
+    if (data.peak) {
+      log(`  ${BOLD}Peak:${RESET} ${data.peak.day_name} at ${data.peak.hour}:00 (${data.peak.events} events, ${data.peak.users} users)`);
+    }
+    log(`  ${BOLD}Busiest day:${RESET} ${data.busiest_day}`);
+    log(`  ${BOLD}Busiest hour:${RESET} ${data.busiest_hour}:00`);
+    log('');
+  } catch (err) {
+    error(`Failed to get heatmap: ${err.message}`);
+  }
+}
+
 async function cmdDelete(id) {
-  if (!id) error('Usage: npx agent-analytics delete <project-id>');
+  if (!id) error('Usage: npx @agent-analytics/cli delete <project-id>');
 
   const api = requireKey();
 
@@ -320,7 +470,7 @@ function showHelp() {
 ${BOLD}agent-analytics${RESET} — Web analytics your AI agent can read
 
 ${BOLD}USAGE${RESET}
-  npx agent-analytics <command> [options]
+  npx @agent-analytics/cli <command> [options]
 
 ${BOLD}COMMANDS${RESET}
   ${CYAN}login${RESET} --token <key> Save your API key
@@ -331,16 +481,25 @@ ${BOLD}COMMANDS${RESET}
   ${CYAN}stats${RESET} <name>       Get stats for a project
   ${CYAN}events${RESET} <name>      Get recent events
   ${CYAN}properties-received${RESET} <name>  Show property keys per event
+  ${CYAN}insights${RESET} <name>    Period-over-period comparison
+  ${CYAN}breakdown${RESET} <name>   Property value distribution
+  ${CYAN}pages${RESET} <name>       Entry/exit page performance
+  ${CYAN}sessions-dist${RESET} <name>  Session duration distribution
+  ${CYAN}heatmap${RESET} <name>     Peak hours & busiest days
   ${CYAN}whoami${RESET}             Show current account
   ${CYAN}revoke-key${RESET}         Revoke and regenerate API key
   ${CYAN}delete-account${RESET}     Delete your account (opens dashboard)
 
 ${BOLD}OPTIONS${RESET}
   --days <N>         Days of data (default: 7)
-  --limit <N>        Max events to return (default: 100)
+  --limit <N>        Max events/rows to return (default: 100)
   --domain <url>     Your site domain (required for create)
   --since <date>     ISO date for properties-received (default: 7 days)
   --sample <N>       Max events to sample (default: 5000)
+  --period <P>       Period for insights: 1d, 7d, 14d, 30d, 90d (default: 7d)
+  --property <key>   Property key for breakdown (required)
+  --event <name>     Filter by event name (breakdown only)
+  --type <T>         Page type: entry, exit, both (default: entry)
 
 ${BOLD}ENVIRONMENT${RESET}
   AGENT_ANALYTICS_API_KEY    API key (overrides config file)
@@ -348,13 +507,13 @@ ${BOLD}ENVIRONMENT${RESET}
 
 ${BOLD}EXAMPLES${RESET}
   ${DIM}# First time: save your API key (from app.agentanalytics.sh)${RESET}
-  npx agent-analytics login --token aak_your_key
+  npx @agent-analytics/cli login --token aak_your_key
 
   ${DIM}# Create a project${RESET}
-  npx agent-analytics create my-site --domain https://mysite.com
+  npx @agent-analytics/cli create my-site --domain https://mysite.com
 
   ${DIM}# Check how your site is doing${RESET}
-  npx agent-analytics stats my-site --days 30
+  npx @agent-analytics/cli stats my-site --days 30
 
   ${DIM}# Your agent can also use the API directly${RESET}
   curl "https://api.agentanalytics.sh/stats?project=my-site&days=7" \\
@@ -388,20 +547,40 @@ try {
       await cmdProjects();
       break;
     case 'stats':
-      await cmdStats(args[1], parseInt(getArg('--days') || '7'));
+      await cmdStats(args[1], parseInt(getArg('--days') || '7', 10));
       break;
     case 'events':
       await cmdEvents(args[1], {
-        days: parseInt(getArg('--days') || '7'),
-        limit: parseInt(getArg('--limit') || '100'),
+        days: parseInt(getArg('--days') || '7', 10),
+        limit: parseInt(getArg('--limit') || '100', 10),
       });
       break;
     case 'properties-received':
       await cmdPropertiesReceived(args[1], {
         since: getArg('--since'),
-        sample: getArg('--sample') ? parseInt(getArg('--sample')) : undefined,
+        sample: getArg('--sample') ? parseInt(getArg('--sample'), 10) : undefined,
       });
       break;
+    case 'insights':
+      await cmdInsights(args[1], getArg('--period') || '7d');
+      break;
+    case 'breakdown':
+      await cmdBreakdown(args[1], getArg('--property'), {
+        event: getArg('--event'),
+        limit: getArg('--limit') ? parseInt(getArg('--limit'), 10) : undefined,
+      });
+      break;
+    case 'pages':
+      await cmdPages(args[1], getArg('--type') || 'entry', {
+        limit: getArg('--limit') ? parseInt(getArg('--limit'), 10) : undefined,
+      });
+      break;
+    case 'sessions-dist':
+      await cmdSessionsDist(args[1]);
+      break;
+    case 'heatmap':
+      await cmdHeatmap(args[1]);
+      break;
     case 'delete':
       await cmdDelete(args[1]);
       break;
@@ -421,7 +600,7 @@ try {
       showHelp();
       break;
     default:
-      error(`Unknown command: ${command}. Run: npx agent-analytics help`);
+      error(`Unknown command: ${command}. Run: npx @agent-analytics/cli help`);
   }
 } catch (err) {
   error(err.message);

package/lib/api.mjs

@@ -87,4 +87,36 @@ export class AgentAnalyticsAPI {
     if (sample) qs += `&sample=${sample}`;
     return this.request('GET', `/properties/received?${qs}`);
   }
+
+  // Analytics
+  async getBreakdown(project, { property, event, since, limit = 20 } = {}) {
+    let qs = `project=${encodeURIComponent(project)}&property=${encodeURIComponent(property)}`;
+    if (event) qs += `&event=${encodeURIComponent(event)}`;
+    if (since) qs += `&since=${encodeURIComponent(since)}`;
+    if (limit) qs += `&limit=${limit}`;
+    return this.request('GET', `/breakdown?${qs}`);
+  }
+
+  async getInsights(project, { period = '7d' } = {}) {
+    return this.request('GET', `/insights?project=${encodeURIComponent(project)}&period=${period}`);
+  }
+
+  async getPages(project, { type = 'entry', since, limit = 20 } = {}) {
+    let qs = `project=${encodeURIComponent(project)}&type=${type}`;
+    if (since) qs += `&since=${encodeURIComponent(since)}`;
+    if (limit) qs += `&limit=${limit}`;
+    return this.request('GET', `/pages?${qs}`);
+  }
+
+  async getSessionDistribution(project, { since } = {}) {
+    let qs = `project=${encodeURIComponent(project)}`;
+    if (since) qs += `&since=${encodeURIComponent(since)}`;
+    return this.request('GET', `/sessions/distribution?${qs}`);
+  }
+
+  async getHeatmap(project, { since } = {}) {
+    let qs = `project=${encodeURIComponent(project)}`;
+    if (since) qs += `&since=${encodeURIComponent(since)}`;
+    return this.request('GET', `/heatmap?${qs}`);
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-analytics/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Web analytics your AI agent can read. CLI for managing projects and querying stats.",
   "bin": {
     "agent-analytics": "./bin/cli.mjs"