@supalytics/cli 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# Supalytics CLI
+
+Command-line interface for [Supalytics](https://supalytics.co) web analytics.
+
+```
+░█▀▀░█░█░█▀█░█▀█░█░░░█░█░▀█▀░▀█▀░█▀▀░█▀▀
+░▀▀█░█░█░█▀▀░█▀█░█░░░░█░░░█░░░█░░█░░░▀▀█
+░▀▀▀░▀▀▀░▀░░░▀░▀░▀▀▀░░▀░░░▀░░▀▀▀░▀▀▀░▀▀▀
+```
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime
+
+## Installation
+
+```bash
+bun add -g @supalytics/cli
+```
+
+## Setup
+
+Get your API key from [supalytics.co/settings/api](https://supalytics.co/settings/api), then:
+
+```bash
+supalytics login <your-api-key>
+```
+
+## Usage
+
+### Quick Stats
+
+```bash
+supalytics stats              # Last 30 days (default)
+supalytics stats today
+supalytics stats yesterday
+supalytics stats week
+supalytics stats month
+supalytics stats 7d
+```
+
+### Realtime
+
+```bash
+supalytics realtime           # Current visitors
+supalytics realtime --watch   # Auto-refresh every 30s
+```
+
+### Breakdowns
+
+```bash
+supalytics pages              # Top pages
+supalytics referrers          # Top referrers
+supalytics countries          # Traffic by country
+```
+
+### Custom Queries
+
+```bash
+# Top pages with revenue
+supalytics query -d page -m visitors,revenue
+
+# Traffic by country and device
+supalytics query -d country,device -m visitors
+
+# Filter by country
+supalytics query -d page -f "country:is:US"
+
+# UTM campaign performance
+supalytics query -d utm_source,utm_campaign -m visitors,revenue
+```
+
+### Events
+
+```bash
+supalytics events                          # List all events
+supalytics events signup                   # Show properties for event
+supalytics events signup --property plan   # Breakdown by property
+```
+
+## Options
+
+All commands support:
+
+- `-s, --site <domain>` - Query a specific site
+- `--json` - Output raw JSON
+- `--no-revenue` - Exclude revenue metrics
+- `-f, --filter <filter>` - Filter data (format: `field:operator:value`)
+
+### Filters
+
+```bash
+-f "country:is:US"
+-f "page:contains:/blog"
+-f "device:is:mobile"
+-f "referrer:is:twitter.com"
+```
+
+## Multi-site Support
+
+```bash
+supalytics login <api-key>        # Add a site
+supalytics sites                  # List all sites
+supalytics default <domain>       # Set default site
+supalytics stats -s other.com     # Query specific site
+```
+
+## License
+
+Apache-2.0

package/bin/supalytics

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/index.ts";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@supalytics/cli",
+  "version": "0.1.0",
+  "description": "CLI for Supalytics web analytics",
+  "type": "module",
+  "bin": {
+    "supalytics": "./bin/supalytics"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts"
+  },
+  "keywords": [
+    "analytics",
+    "web-analytics",
+    "cli",
+    "supalytics",
+    "privacy"
+  ],
+  "author": "Supalytics",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yogesharc/supalytics-cli"
+  },
+  "homepage": "https://supalytics.co",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2"
+  }
+}

package/src/api.ts

@@ -0,0 +1,311 @@
+import { getApiKeyForSite, getSites } from "./config";
+
+const API_BASE = process.env.SUPALYTICS_API_URL || "https://api.supalytics.co";
+
+export interface QueryRequest {
+  metrics: string[];
+  date_range?: string | [string, string];
+  dimensions?: string[];
+  filters?: [string, string, string][]; // [field, operator, value]
+  sort?: { field: string; order: "asc" | "desc" };
+  timezone?: string;
+  limit?: number;
+  offset?: number;
+  include_revenue?: boolean;
+}
+
+export interface QueryResult {
+  dimensions: Record<string, string>;
+  metrics: Record<string, number>;
+}
+
+export interface QueryResponse {
+  data: QueryResult[];
+  meta: {
+    domain: string;
+    date_range: [string, string];
+    timezone: string;
+    query_ms: number;
+  };
+  pagination: {
+    limit: number;
+    offset: number;
+    has_more: boolean;
+  };
+  query: {
+    metrics: string[];
+    dimensions?: string[];
+    date_range: string | [string, string];
+    filters?: [string, string, string][];
+    sort?: { field: string; order: "asc" | "desc" };
+    timezone: string;
+  };
+}
+
+export interface ApiError {
+  error: string;
+  message?: string;
+}
+
+/**
+ * Query analytics data
+ */
+export async function query(
+  site: string,
+  request: QueryRequest
+): Promise<QueryResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    const sites = await getSites();
+    if (sites.length === 0) {
+      throw new Error(
+        "No sites configured. Run `supalytics login <api-key>` to add a site."
+      );
+    }
+    throw new Error(
+      `No API key found for '${site}'. Available sites: ${sites.join(", ")}`
+    );
+  }
+
+  const response = await fetch(`${API_BASE}/v1/query`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(request),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+export function formatNumber(num: number): string {
+  if (num >= 1_000_000) {
+    return (num / 1_000_000).toFixed(1) + "M";
+  }
+  if (num >= 1_000) {
+    return (num / 1_000).toFixed(1) + "K";
+  }
+  return num.toString();
+}
+
+export function formatDuration(seconds: number): string {
+  if (seconds < 60) {
+    return `${Math.round(seconds)}s`;
+  }
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.round(seconds % 60);
+  return `${mins}m ${secs}s`;
+}
+
+export function formatPercent(value: number): string {
+  return `${value.toFixed(1)}%`;
+}
+
+// Events API types
+export interface EventItem {
+  name: string;
+  count: number;
+  visitors: number;
+  has_properties: boolean;
+}
+
+export interface EventsResponse {
+  data: EventItem[];
+  meta: {
+    domain: string;
+    date_range: [string, string];
+    query_ms: number;
+  };
+}
+
+export interface PropertyKeysResponse {
+  data: string[];
+  meta: {
+    domain: string;
+    event: string;
+    date_range: [string, string];
+    query_ms: number;
+  };
+}
+
+export interface PropertyValue {
+  value: string;
+  count: number;
+  visitors: number;
+  revenue: number | null;
+}
+
+export interface PropertyBreakdownResponse {
+  data: PropertyValue[];
+  meta: {
+    domain: string;
+    event: string;
+    property: string;
+    date_range: [string, string];
+    query_ms: number;
+  };
+}
+
+/**
+ * List all events
+ */
+export async function listEvents(
+  site: string,
+  period: string = "30d",
+  limit: number = 100
+): Promise<EventsResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    const sites = await getSites();
+    if (sites.length === 0) {
+      throw new Error(
+        "No sites configured. Run `supalytics login <api-key>` to add a site."
+      );
+    }
+    throw new Error(
+      `No API key found for '${site}'. Available sites: ${sites.join(", ")}`
+    );
+  }
+
+  const params = new URLSearchParams({ period, limit: String(limit) });
+  const response = await fetch(`${API_BASE}/v1/events?${params}`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Get property keys for an event
+ */
+export async function getEventProperties(
+  site: string,
+  eventName: string,
+  period: string = "30d"
+): Promise<PropertyKeysResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`No API key found for '${site}'.`);
+  }
+
+  const params = new URLSearchParams({ period });
+  const response = await fetch(
+    `${API_BASE}/v1/events/${encodeURIComponent(eventName)}/properties?${params}`,
+    { headers: { Authorization: `Bearer ${apiKey}` } }
+  );
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Get property value breakdown
+ */
+export async function getPropertyBreakdown(
+  site: string,
+  eventName: string,
+  propertyKey: string,
+  period: string = "30d",
+  limit: number = 100,
+  includeRevenue: boolean = false
+): Promise<PropertyBreakdownResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`No API key found for '${site}'.`);
+  }
+
+  const params = new URLSearchParams({
+    period,
+    limit: String(limit),
+    include_revenue: String(includeRevenue),
+  });
+  const response = await fetch(
+    `${API_BASE}/v1/events/${encodeURIComponent(eventName)}/properties/${encodeURIComponent(propertyKey)}?${params}`,
+    { headers: { Authorization: `Bearer ${apiKey}` } }
+  );
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+// Realtime API types
+export interface RealtimePageItem {
+  page: string;
+  visitors: number;
+}
+
+export interface RealtimeCountryItem {
+  country: string;
+  visitors: number;
+}
+
+export interface RealtimeReferrerItem {
+  referrer: string;
+  visitors: number;
+}
+
+export interface RealtimeResponse {
+  data: {
+    active_visitors: number;
+    pages: RealtimePageItem[];
+    countries: RealtimeCountryItem[];
+    referrers: RealtimeReferrerItem[];
+  };
+  meta: {
+    domain: string;
+    timestamp: string;
+  };
+}
+
+/**
+ * Get realtime visitors
+ */
+export async function getRealtime(site: string): Promise<RealtimeResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    const sites = await getSites();
+    if (sites.length === 0) {
+      throw new Error(
+        "No sites configured. Run `supalytics login <api-key>` to add a site."
+      );
+    }
+    throw new Error(
+      `No API key found for '${site}'. Available sites: ${sites.join(", ")}`
+    );
+  }
+
+  const response = await fetch(`${API_BASE}/v1/realtime`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}

package/src/commands/countries.ts

@@ -0,0 +1,93 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { query, formatNumber } from "../api";
+import { getDefaultSite } from "../config";
+import { sparkBar, formatRevenue } from "../ui";
+
+export const countriesCommand = new Command("countries")
+  .description("Traffic by country")
+  .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: ["country"],
+        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("  🌍 Countries"), 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 country = result.dimensions?.country || "Unknown";
+        const visitors = result.metrics.visitors || 0;
+        const bar = sparkBar(visitors, maxVisitors);
+
+        let line = `     ${country.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/events.ts

@@ -0,0 +1,133 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { listEvents, getEventProperties, getPropertyBreakdown, formatNumber, PropertyKeysResponse } from "../api";
+import { getDefaultSite } from "../config";
+
+const eventsDescription = `List and explore custom events.
+
+Examples:
+  # List all events
+  supalytics events
+
+  # List properties for an event
+  supalytics events signup
+
+  # Get breakdown of a property
+  supalytics events signup --property plan
+
+  # With revenue
+  supalytics events signup --property plan --revenue`;
+
+function displayPropertyKeys(response: PropertyKeysResponse, event: string, json: boolean) {
+  if (json) {
+    console.log(JSON.stringify(response, null, 2));
+    return;
+  }
+
+  console.log();
+  console.log(chalk.bold(`Properties for "${event}"`));
+  console.log();
+
+  if (response.data.length === 0) {
+    console.log(chalk.dim("  No properties found"));
+    return;
+  }
+
+  for (const key of response.data) {
+    console.log(`  ${chalk.cyan(key)}`);
+  }
+  console.log();
+  console.log(chalk.dim(`  Use: supalytics events ${event} --property <key>`));
+  console.log();
+}
+
+export const eventsCommand = new Command("events")
+  .description(eventsDescription)
+  .argument("[event]", "Event name to explore")
+  .option("-s, --site <site>", "Site to query")
+  .option("-p, --period <period>", "Time period: 7d, 14d, 30d, 90d, 12mo, all", "30d")
+  .option("--property <key>", "Get breakdown for a specific property")
+  .option("-l, --limit <number>", "Number of results", "20")
+  .option("--revenue", "Include revenue in property breakdown")
+  .option("--json", "Output as JSON")
+  .action(async (event, 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);
+    }
+
+    try {
+      // If no event specified, list all events
+      if (!event) {
+        const response = await listEvents(site, options.period, parseInt(options.limit));
+
+        if (options.json) {
+          console.log(JSON.stringify(response, null, 2));
+          return;
+        }
+
+        const [startDate, endDate] = response.meta.date_range;
+        console.log();
+        console.log(chalk.bold("Events"), chalk.dim(`${startDate} → ${endDate}`));
+        console.log();
+
+        if (response.data.length === 0) {
+          console.log(chalk.dim("  No events found"));
+          return;
+        }
+
+        for (const e of response.data) {
+          const props = e.has_properties ? chalk.dim(" [has properties]") : "";
+          console.log(`  ${chalk.cyan(e.name)}  ${formatNumber(e.visitors)} visitors  ${formatNumber(e.count)} events${props}`);
+        }
+        console.log();
+        return;
+      }
+
+      // If --property flag, get breakdown
+      if (options.property) {
+        const response = await getPropertyBreakdown(
+          site,
+          event,
+          options.property,
+          options.period,
+          parseInt(options.limit),
+          options.revenue
+        );
+
+        if (options.json) {
+          console.log(JSON.stringify(response, null, 2));
+          return;
+        }
+
+        console.log();
+        console.log(chalk.bold(`${event}.${options.property}`), chalk.dim(`${response.meta.date_range[0]} → ${response.meta.date_range[1]}`));
+        console.log();
+
+        if (response.data.length === 0) {
+          console.log(chalk.dim("  No values found"));
+          return;
+        }
+
+        for (const v of response.data) {
+          let line = `  ${chalk.cyan(v.value)}  ${formatNumber(v.visitors)} visitors  ${formatNumber(v.count)} events`;
+          if (options.revenue && v.revenue !== null) {
+            line += `  ${chalk.green("$" + (v.revenue / 100).toFixed(2))}`;
+          }
+          console.log(line);
+        }
+        console.log();
+        return;
+      }
+
+      // If just event name, show properties
+      const response = await getEventProperties(site, event, options.period);
+      displayPropertyKeys(response, event, options.json);
+
+    } catch (error) {
+      console.error(chalk.red(`Error: ${(error as Error).message}`));
+      process.exit(1);
+    }
+  });