@supalytics/cli 0.1.0

package/src/commands/login.ts

@@ -0,0 +1,83 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { addSite, CONFIG_FILE, getConfig, setDefaultSite } from "../config";
+import { mkdir } from "fs/promises";
+import { dirname } from "path";
+
+const API_BASE = process.env.SUPALYTICS_API_URL || "http://localhost:3000";
+
+interface VerifyResponse {
+  domain: string;
+}
+
+async function verifyApiKey(apiKey: string): Promise<VerifyResponse | null> {
+  try {
+    // Use a minimal analytics query to verify the key and get the domain
+    const response = await fetch(`${API_BASE}/v1/analytics`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        metrics: ["pageviews"],
+        date_range: "7d",
+        limit: 1,
+      }),
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const data = await response.json();
+    return { domain: data.meta.domain };
+  } catch {
+    return null;
+  }
+}
+
+export const loginCommand = new Command("login")
+  .description("Add a site by verifying its API key. Can be called multiple times to add multiple sites.")
+  .argument("<api-key>", "Your API key (starts with sly_)")
+  .option("--default", "Set this site as the default")
+  .action(async (apiKey: string, options: { default?: boolean }) => {
+    apiKey = apiKey.trim();
+
+    // Validate API key format
+    if (!apiKey.startsWith("sly_")) {
+      console.error(chalk.red("Error: Invalid API key format. Keys start with 'sly_'"));
+      process.exit(1);
+    }
+
+    // Verify API key with server
+    console.log(chalk.dim("Verifying API key..."));
+    const result = await verifyApiKey(apiKey);
+
+    if (!result) {
+      console.error(chalk.red("Error: Invalid API key or unable to verify"));
+      process.exit(1);
+    }
+
+    // Ensure config directory exists
+    await mkdir(dirname(CONFIG_FILE), { recursive: true });
+
+    // Add site to config
+    await addSite(result.domain, apiKey);
+
+    // Set as default if requested
+    if (options.default) {
+      await setDefaultSite(result.domain);
+    }
+
+    const config = await getConfig();
+    const isDefault = config.defaultSite === result.domain;
+    const siteCount = Object.keys(config.sites).length;
+
+    console.log(chalk.green(`✓ Added ${result.domain}`) + (isDefault ? chalk.dim(" (default)") : ""));
+    console.log(chalk.dim(`  ${siteCount} site${siteCount > 1 ? "s" : ""} configured`));
+
+    if (siteCount > 1 && !isDefault) {
+      console.log(chalk.dim(`  Use --default flag or 'supalytics default ${result.domain}' to set as default`));
+    }
+  });

package/src/commands/logout.ts

@@ -0,0 +1,15 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { CONFIG_FILE } from "../config";
+import { unlink } from "fs/promises";
+
+export const logoutCommand = new Command("logout")
+  .description("Remove stored credentials")
+  .action(async () => {
+    try {
+      await unlink(CONFIG_FILE);
+      console.log(chalk.green("✓ Logged out successfully"));
+    } catch {
+      console.log(chalk.dim("Already logged out"));
+    }
+  });

package/src/commands/pages.ts

@@ -0,0 +1,93 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { query, formatNumber } from "../api";
+import { getDefaultSite } from "../config";
+import { sparkBar, truncate, formatRevenue } from "../ui";
+
+export const pagesCommand = new Command("pages")
+  .description("Top pages by visitors")
+  .option("-s, --site <site>", "Site to query")
+  .option("-p, --period <period>", "Time period (7d, 30d, 90d, 12mo, all)", "30d")
+  .option("--start <date>", "Start date (YYYY-MM-DD)")
+  .option("--end <date>", "End date (YYYY-MM-DD)")
+  .option("-l, --limit <number>", "Number of results", "10")
+  .option("-f, --filter <filters...>", "Filters in format 'field:operator:value'")
+  .option("--no-revenue", "Exclude revenue metrics")
+  .option("--json", "Output as JSON")
+  .action(async (options) => {
+    const site = options.site || (await getDefaultSite());
+
+    if (!site) {
+      console.error(chalk.red("Error: No site specified. Use --site or set a default with `supalytics login --site`"));
+      process.exit(1);
+    }
+
+    const dateRange = options.start && options.end
+      ? [options.start, options.end] as [string, string]
+      : options.period;
+
+    const filters = options.filter
+      ? options.filter.map((f: string) => {
+          const parts = f.split(":");
+          if (parts.length < 3) {
+            console.error(chalk.red(`Invalid filter format: ${f}. Use 'field:operator:value'`));
+            process.exit(1);
+          }
+          const [field, operator, ...valueParts] = parts;
+          return [field, operator, valueParts.join(":")] as [string, string, string];
+        })
+      : undefined;
+
+    try {
+      const metrics = ["visitors"];
+      if (options.revenue !== false) {
+        metrics.push("revenue");
+      }
+
+      const response = await query(site, {
+        metrics,
+        dimensions: ["page"],
+        filters,
+        date_range: dateRange,
+        limit: parseInt(options.limit),
+        include_revenue: options.revenue !== false,
+      });
+
+      if (options.json) {
+        console.log(JSON.stringify(response, null, 2));
+        return;
+      }
+
+      const [startDate, endDate] = response.meta.date_range;
+
+      console.log();
+      console.log(chalk.bold("  📄 Top Pages"), chalk.dim(`${startDate} → ${endDate}`));
+      console.log();
+
+      if (response.data.length === 0) {
+        console.log(chalk.dim("     No data"));
+        console.log();
+        return;
+      }
+
+      const maxVisitors = Math.max(...response.data.map(r => r.metrics.visitors || 0), 1);
+
+      for (const result of response.data) {
+        const page = truncate(result.dimensions?.page || "/", 32);
+        const visitors = result.metrics.visitors || 0;
+        const bar = sparkBar(visitors, maxVisitors);
+
+        let line = `     ${page.padEnd(34)} ${bar} ${formatNumber(visitors).padStart(6)}`;
+
+        if (options.revenue !== false && result.metrics.revenue != null) {
+          line += `  ${formatRevenue(result.metrics.revenue)}`;
+        }
+
+        console.log(line);
+      }
+      console.log();
+    } catch (error) {
+      console.error(chalk.red(`Error: ${(error as Error).message}`));
+      process.exit(1);
+    }
+  });

package/src/commands/query.ts

@@ -0,0 +1,162 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { query, formatNumber, formatPercent, formatDuration } from "../api";
+import { getDefaultSite } from "../config";
+
+const queryDescription = `Flexible query with custom metrics and dimensions.
+
+Examples:
+  # Top pages with revenue
+  supalytics query -d page -m visitors,revenue
+
+  # Traffic by country and device
+  supalytics query -d country,device -m visitors
+
+  # Blog traffic from US
+  supalytics query -d page -f "page:contains:/blog" -f "country:is:US"
+
+  # Hourly breakdown for last 7 days
+  supalytics query -d hour -m visitors -p 7d
+
+  # UTM campaign performance
+  supalytics query -d utm_source,utm_campaign -m visitors,revenue
+
+  # Sort by revenue
+  supalytics query -d page --sort revenue:desc
+
+  # List all custom events
+  supalytics query -d event
+
+  # Top countries for visitors who signed up
+  supalytics query -d country -f "event:is:signup"
+
+  # Pages visited by premium users
+  supalytics query -d page -f "event_property:is:plan:premium"`;
+
+export const queryCommand = new Command("query")
+  .description(queryDescription)
+  .option("-s, --site <site>", "Site to query")
+  .option("-m, --metrics <metrics>", "Metrics: visitors, bounce_rate, avg_session_duration, revenue, conversions", "visitors")
+  .option("-d, --dimensions <dimensions>", "Dimensions: page, referrer, country, region, city, browser, os, device, date, hour, event, utm_* (max 2, event cannot combine)")
+  .option("-f, --filter <filters...>", "Filters: field:operator:value (e.g., 'page:contains:/blog', 'event:is:signup', 'event_property:is:plan:premium')")
+  .option("--sort <sort>", "Sort by field:order (e.g., 'revenue:desc', 'visitors:asc')")
+  .option("--timezone <tz>", "Timezone for date grouping (e.g., 'America/New_York')", "UTC")
+  .option("-p, --period <period>", "Time period: 7d, 14d, 30d, 90d, 12mo, all", "30d")
+  .option("--start <date>", "Start date (YYYY-MM-DD)")
+  .option("--end <date>", "End date (YYYY-MM-DD)")
+  .option("-l, --limit <number>", "Number of results (1-1000)", "10")
+  .option("--offset <number>", "Skip results for pagination", "0")
+  .option("--no-revenue", "Exclude revenue metrics")
+  .option("--json", "Output as JSON")
+  .action(async (options) => {
+    const site = options.site || (await getDefaultSite());
+
+    if (!site) {
+      console.error(chalk.red("Error: No site specified. Use --site or set a default with `supalytics login --site`"));
+      process.exit(1);
+    }
+
+    const dateRange = options.start && options.end
+      ? [options.start, options.end] as [string, string]
+      : options.period;
+
+    // Parse metrics
+    const metrics = options.metrics.split(",").map((m: string) => m.trim());
+
+    // Parse dimensions
+    const dimensions = options.dimensions
+      ? options.dimensions.split(",").map((d: string) => d.trim())
+      : undefined;
+
+    // Parse filters - NEW FORMAT: field:operator:value
+    const filters = options.filter
+      ? options.filter.map((f: string) => {
+          const parts = f.split(":");
+          if (parts.length < 3) {
+            console.error(chalk.red(`Invalid filter format: ${f}. Use 'field:operator:value'`));
+            process.exit(1);
+          }
+          const [field, operator, ...valueParts] = parts;
+          return [field, operator, valueParts.join(":")] as [string, string, string];
+        })
+      : undefined;
+
+    // Parse sort
+    const sort = options.sort
+      ? (() => {
+          const [field, order] = options.sort.split(":");
+          if (!field || !order || (order !== "asc" && order !== "desc")) {
+            console.error(chalk.red(`Invalid sort format: ${options.sort}. Use 'field:order' where order is 'asc' or 'desc'`));
+            process.exit(1);
+          }
+          return { field, order: order as "asc" | "desc" };
+        })()
+      : undefined;
+
+    try {
+      const response = await query(site, {
+        metrics,
+        dimensions,
+        filters,
+        sort,
+        timezone: options.timezone,
+        date_range: dateRange,
+        limit: parseInt(options.limit),
+        offset: parseInt(options.offset),
+        include_revenue: options.revenue !== false,
+      });
+
+      if (options.json) {
+        console.log(JSON.stringify(response, null, 2));
+        return;
+      }
+
+      const [startDate, endDate] = response.meta.date_range;
+
+      console.log();
+      console.log(chalk.bold("Query Results"), chalk.dim(`${startDate} → ${endDate}`));
+      console.log(chalk.dim(`  ${response.data.length} rows in ${response.meta.query_ms}ms`));
+      if (response.pagination.has_more) {
+        console.log(chalk.dim(`  More results available (offset: ${response.pagination.offset + response.pagination.limit})`));
+      }
+      console.log();
+
+      if (response.data.length === 0) {
+        console.log(chalk.dim("  No data"));
+        return;
+      }
+
+      // Display results
+      for (const result of response.data) {
+        const parts: string[] = [];
+
+        // Dimensions
+        if (result.dimensions) {
+          for (const [key, value] of Object.entries(result.dimensions)) {
+            parts.push(`${chalk.dim(key)}=${value}`);
+          }
+        }
+
+        // Metrics
+        for (const [key, value] of Object.entries(result.metrics)) {
+          let formatted: string;
+          if (key === "bounce_rate" || key === "conversion_rate") {
+            formatted = formatPercent(value);
+          } else if (key === "avg_session_duration") {
+            formatted = formatDuration(value);
+          } else if (key === "revenue") {
+            formatted = chalk.green("$" + (value / 100).toFixed(2));
+          } else {
+            formatted = formatNumber(value);
+          }
+          parts.push(`${chalk.dim(key)}=${formatted}`);
+        }
+
+        console.log(`  ${parts.join("  ")}`);
+      }
+      console.log();
+    } catch (error) {
+      console.error(chalk.red(`Error: ${(error as Error).message}`));
+      process.exit(1);
+    }
+  });

package/src/commands/realtime.ts

@@ -0,0 +1,110 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { getRealtime } from "../api";
+import { getDefaultSite } from "../config";
+import { sparkBar, truncate, logo } from "../ui";
+
+export const realtimeCommand = new Command("realtime")
+  .description("Live visitors on your site right now")
+  .option("-s, --site <site>", "Site to query")
+  .option("--json", "Output as JSON")
+  .option("-w, --watch", "Auto-refresh every 30 seconds")
+  .action(async (options) => {
+    const site = options.site || (await getDefaultSite());
+
+    if (!site) {
+      console.error(chalk.red("Error: No site specified. Use --site or set a default with `supalytics login --site`"));
+      process.exit(1);
+    }
+
+    const display = async () => {
+      try {
+        const response = await getRealtime(site);
+
+        if (options.json) {
+          console.log(JSON.stringify(response, null, 2));
+          return;
+        }
+
+        // Clear screen in watch mode
+        if (options.watch) {
+          console.clear();
+        }
+
+        const { data, meta } = response;
+        const time = new Date(meta.timestamp).toLocaleTimeString();
+        const maxVisitors = Math.max(
+          ...data.pages.map(p => p.visitors),
+          ...data.countries.map(c => c.visitors),
+          ...data.referrers.map(r => r.visitors),
+          1
+        );
+
+        // Logo
+        console.log(logo());
+
+        // Site info
+        console.log(chalk.bold(`  ${site}`));
+        console.log(chalk.dim(`  Updated ${time}`));
+        console.log();
+
+        // Big visitor count
+        const visitorCount = String(data.active_visitors);
+        console.log(`  ${chalk.green.bold(visitorCount)} ${chalk.dim("visitors right now")}`);
+        console.log();
+
+        // Top pages
+        if (data.pages.length > 0) {
+          console.log(chalk.dim("  PAGES"));
+          for (const p of data.pages.slice(0, 5)) {
+            const page = truncate(p.page, 36);
+            const bar = sparkBar(p.visitors, maxVisitors, 12);
+            console.log(`  ${page.padEnd(38)} ${bar} ${chalk.bold(String(p.visitors).padStart(3))}`);
+          }
+          console.log();
+        }
+
+        // Countries
+        if (data.countries.length > 0) {
+          console.log(chalk.dim("  COUNTRIES"));
+          for (const c of data.countries.slice(0, 5)) {
+            const bar = sparkBar(c.visitors, maxVisitors, 12);
+            console.log(`  ${c.country.padEnd(38)} ${bar} ${chalk.bold(String(c.visitors).padStart(3))}`);
+          }
+          console.log();
+        }
+
+        // Referrers
+        if (data.referrers.length > 0) {
+          console.log(chalk.dim("  REFERRERS"));
+          for (const r of data.referrers.slice(0, 5)) {
+            const ref = truncate(r.referrer || "Direct", 36);
+            const bar = sparkBar(r.visitors, maxVisitors, 12);
+            console.log(`  ${ref.padEnd(38)} ${bar} ${chalk.bold(String(r.visitors).padStart(3))}`);
+          }
+          console.log();
+        }
+
+        if (data.pages.length === 0 && data.countries.length === 0 && data.referrers.length === 0) {
+          console.log(chalk.dim("  No active visitors right now"));
+          console.log();
+        }
+
+        if (options.watch) {
+          console.log(chalk.dim("  ──────────────────────────────────────────────────────"));
+          console.log(chalk.dim("  Refreshing every 30s • Press Ctrl+C to exit"));
+        }
+      } catch (error) {
+        console.error(chalk.red(`Error: ${(error as Error).message}`));
+        if (!options.watch) {
+          process.exit(1);
+        }
+      }
+    };
+
+    await display();
+
+    if (options.watch) {
+      setInterval(display, 30000);
+    }
+  });

package/src/commands/referrers.ts

@@ -0,0 +1,95 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { query, formatNumber } from "../api";
+import { getDefaultSite } from "../config";
+import { sparkBar, truncate, formatRevenue } from "../ui";
+
+export const referrersCommand = new Command("referrers")
+  .description("Top referrers")
+  .option("-s, --site <site>", "Site to query")
+  .option("-p, --period <period>", "Time period (7d, 30d, 90d, 12mo, all)", "30d")
+  .option("--start <date>", "Start date (YYYY-MM-DD)")
+  .option("--end <date>", "End date (YYYY-MM-DD)")
+  .option("-l, --limit <number>", "Number of results", "10")
+  .option("-f, --filter <filters...>", "Filters in format 'field:operator:value'")
+  .option("--no-revenue", "Exclude revenue metrics")
+  .option("--json", "Output as JSON")
+  .action(async (options) => {
+    const site = options.site || (await getDefaultSite());
+
+    if (!site) {
+      console.error(chalk.red("Error: No site specified. Use --site or set a default with `supalytics login --site`"));
+      process.exit(1);
+    }
+
+    const dateRange = options.start && options.end
+      ? [options.start, options.end] as [string, string]
+      : options.period;
+
+    const filters = options.filter
+      ? options.filter.map((f: string) => {
+          const parts = f.split(":");
+          if (parts.length < 3) {
+            console.error(chalk.red(`Invalid filter format: ${f}. Use 'field:operator:value'`));
+            process.exit(1);
+          }
+          const [field, operator, ...valueParts] = parts;
+          return [field, operator, valueParts.join(":")] as [string, string, string];
+        })
+      : undefined;
+
+    try {
+      const metrics = ["visitors"];
+      if (options.revenue !== false) {
+        metrics.push("revenue");
+      }
+
+      const response = await query(site, {
+        metrics,
+        dimensions: ["referrer"],
+        filters,
+        date_range: dateRange,
+        limit: parseInt(options.limit),
+        include_revenue: options.revenue !== false,
+      });
+
+      if (options.json) {
+        console.log(JSON.stringify(response, null, 2));
+        return;
+      }
+
+      const [startDate, endDate] = response.meta.date_range;
+
+      console.log();
+      console.log(chalk.bold("  🔗 Referrers"), chalk.dim(`${startDate} → ${endDate}`));
+      console.log();
+
+      if (response.data.length === 0) {
+        console.log(chalk.dim("     No data"));
+        console.log();
+        return;
+      }
+
+      const maxVisitors = Math.max(...response.data.map(r => r.metrics.visitors || 0), 1);
+
+      for (const result of response.data) {
+        const referrer = result.dimensions?.referrer || "";
+        const displayRef = referrer === "" ? "Direct / None" : referrer;
+        const source = truncate(displayRef, 32);
+        const visitors = result.metrics.visitors || 0;
+        const bar = sparkBar(visitors, maxVisitors);
+
+        let line = `     ${source.padEnd(34)} ${bar} ${formatNumber(visitors).padStart(6)}`;
+
+        if (options.revenue !== false && result.metrics.revenue != null) {
+          line += `  ${formatRevenue(result.metrics.revenue)}`;
+        }
+
+        console.log(line);
+      }
+      console.log();
+    } catch (error) {
+      console.error(chalk.red(`Error: ${(error as Error).message}`));
+      process.exit(1);
+    }
+  });

package/src/commands/sites.ts

@@ -0,0 +1,65 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { getConfig, removeSite, setDefaultSite } from "../config";
+
+export const sitesCommand = new Command("sites")
+  .description("List all configured sites")
+  .action(async () => {
+    const config = await getConfig();
+    const sites = Object.keys(config.sites);
+
+    if (sites.length === 0) {
+      console.log(chalk.dim("No sites configured. Run `supalytics login <api-key>` to add a site."));
+      return;
+    }
+
+    console.log();
+    console.log(chalk.bold("Configured Sites"));
+    console.log();
+
+    for (const site of sites) {
+      const isDefault = config.defaultSite === site;
+      const apiKey = config.sites[site].apiKey;
+      const maskedKey = apiKey.slice(0, 8) + "..." + apiKey.slice(-4);
+
+      if (isDefault) {
+        console.log(`  ${chalk.green("●")} ${site} ${chalk.dim("(default)")} ${chalk.dim(maskedKey)}`);
+      } else {
+        console.log(`  ${chalk.dim("○")} ${site} ${chalk.dim(maskedKey)}`);
+      }
+    }
+    console.log();
+  });
+
+export const defaultCommand = new Command("default")
+  .description("Set the default site")
+  .argument("<domain>", "Domain to set as default")
+  .action(async (domain: string) => {
+    const success = await setDefaultSite(domain);
+
+    if (!success) {
+      const config = await getConfig();
+      const sites = Object.keys(config.sites);
+      console.error(chalk.red(`Error: Site '${domain}' not found.`));
+      if (sites.length > 0) {
+        console.log(chalk.dim(`Available sites: ${sites.join(", ")}`));
+      }
+      process.exit(1);
+    }
+
+    console.log(chalk.green(`✓ Default site set to ${domain}`));
+  });
+
+export const removeCommand = new Command("remove")
+  .description("Remove a site")
+  .argument("<domain>", "Domain to remove")
+  .action(async (domain: string) => {
+    const success = await removeSite(domain);
+
+    if (!success) {
+      console.error(chalk.red(`Error: Site '${domain}' not found.`));
+      process.exit(1);
+    }
+
+    console.log(chalk.green(`✓ Removed ${domain}`));
+  });