visitrack 1.0.0

package/README.md

@@ -0,0 +1,51 @@
+# visitrack
+
+Read your [VisitTrack](https://visitrack.app) analytics from the terminal.
+
+A thin wrapper over the public REST API — every command maps to one
+`GET /api/v1/<resource>`, so it can never report something the API
+wouldn't. No dependencies, single file.
+
+## Use it
+
+From a checkout, with nothing to install:
+
+```bash
+export VISITRACK_API_KEY=vt_...   # Settings → API / MCP → New API key
+
+node cli/visitrack.mjs stats
+node cli/visitrack.mjs pages --days 7
+node cli/visitrack.mjs referrers --csv > referrers.csv
+```
+
+For a plain `visitrack` on your PATH, install this folder globally:
+
+```bash
+npm install -g ./cli
+
+visitrack stats
+```
+
+It is not published to the npm registry yet, so `npx visitrack` does not
+work — publishing it is planned, and the docs switch to that form when it
+happens.
+
+## Commands
+
+`site` · `stats` · `timeseries` · `pages` · `referrers` · `countries` ·
+`devices` · `revenue` · `goals` · `live`
+
+## Options
+
+| Flag | What it does |
+|---|---|
+| `--days N` | How far back to report on (1–365, default 30) |
+| `--from ISO --to ISO` | An explicit range instead of `--days` |
+| `--granularity G` | `day` \| `hour` \| `minute` (timeseries only) |
+| `--json` | Raw JSON, for piping into `jq` |
+| `--csv` | CSV, for row-shaped resources |
+| `--key KEY` | API key, if you'd rather not use the env var |
+| `--host URL` | API origin (default `https://visitrack.app`) |
+
+A key is scoped to one site, and is read-only — nothing the CLI can do
+changes or deletes anything.

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "visitrack",
+  "version": "1.0.0",
+  "description": "Read your VisitTrack analytics from the terminal.",
+  "type": "module",
+  "bin": { "visitrack": "./visitrack.mjs" },
+  "files": ["visitrack.mjs", "README.md"],
+  "engines": { "node": ">=18" },
+  "license": "MIT"
+}

package/visitrack.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// VisitTrack CLI — the third piece of the "API, CLI & exports" the pricing
+// page has always promised. Deliberately a thin wrapper over the public
+// REST API rather than its own data path: every command below maps to one
+// GET /api/v1/<resource>, so the CLI can never report something the API
+// wouldn't, and a new API resource shows up here by adding one line.
+//
+// Zero dependencies, single file, Node built-ins only — it runs straight
+// from a checkout (`node cli/visitrack.mjs stats`) with no build step.
+
+const DEFAULT_HOST = "https://visitrack.app";
+
+const RESOURCES = {
+  site: "Details of the site this key belongs to",
+  stats: "Visitors, pageviews, bounce rate, session time, online now",
+  timeseries: "Visitors and pageviews per bucket",
+  pages: "Most-viewed pages",
+  referrers: "Traffic sources with their channel",
+  countries: "Visitors by country",
+  devices: "Visitors by device type",
+  revenue: "Attributed revenue plus breakdowns",
+  goals: "Goals with completions and conversion rates",
+  live: "Visitors active in the last 5 minutes",
+  funnels: "Funnels with per-step visitor counts and drop-off",
+  visitor: "One visitor's full event timeline (needs --visitor-id or --external-id)",
+};
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const flags = {};
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (!arg.startsWith("--")) continue;
+    const [name, inline] = arg.slice(2).split("=");
+    if (inline !== undefined) {
+      flags[name] = inline;
+    } else if (rest[i + 1] && !rest[i + 1].startsWith("--")) {
+      flags[name] = rest[++i];
+    } else {
+      flags[name] = true;
+    }
+  }
+  return { command, flags };
+}
+
+function usage() {
+  const width = Math.max(...Object.keys(RESOURCES).map((r) => r.length));
+  return `visitrack — read your analytics from the terminal
+
+Usage
+  node cli/visitrack.mjs <command> [options]
+  visitrack <command> [options]            (after npm install -g ./cli)
+
+Commands
+${Object.entries(RESOURCES)
+  .map(([name, summary]) => `  ${name.padEnd(width)}  ${summary}`)
+  .join("\n")}
+
+Options
+  --days N            How far back to report on (1-365, default 30)
+  --from ISO --to ISO An explicit range instead of --days
+  --granularity G     day | hour | minute (timeseries only)
+  --visitor-id ID     Look up one visitor by our id (visitor only)
+  --external-id ID    Look up one visitor by your own user id (visitor only)
+  --json              Print the raw JSON response
+  --csv               Print CSV (row-shaped resources only)
+  --key KEY           API key; defaults to $VISITRACK_API_KEY
+  --host URL          API origin (default ${DEFAULT_HOST})
+
+Getting a key
+  Dashboard -> Settings -> API / MCP -> New API key, then:
+    export VISITRACK_API_KEY=vt_...
+
+Examples
+  node cli/visitrack.mjs stats
+  node cli/visitrack.mjs pages --days 7
+  node cli/visitrack.mjs referrers --csv > referrers.csv
+  node cli/visitrack.mjs timeseries --granularity hour --days 2
+  node cli/visitrack.mjs funnels
+  node cli/visitrack.mjs visitor --external-id user_482`;
+}
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+/** Aligned columns, so output stays readable without a table dependency. */
+function renderTable(rows) {
+  if (rows.length === 0) return "(nothing to show)";
+  const columns = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+  const cell = (row, column) => {
+    const value = row[column];
+    if (value === null || value === undefined) return "";
+    return typeof value === "object" ? JSON.stringify(value) : String(value);
+  };
+  const widths = columns.map((column) =>
+    Math.max(column.length, ...rows.map((row) => cell(row, column).length)),
+  );
+  const line = (cells) => cells.map((text, i) => text.padEnd(widths[i])).join("  ").trimEnd();
+
+  return [
+    line(columns),
+    line(widths.map((width) => "-".repeat(width))),
+    ...rows.map((row) => line(columns.map((column) => cell(row, column)))),
+  ].join("\n");
+}
+
+/** Scalar resources (stats, site) read better as label/value pairs. */
+function renderObject(data) {
+  const entries = Object.entries(data).filter(([, value]) => typeof value !== "object" || value === null);
+  const width = Math.max(...entries.map(([key]) => key.length));
+  return entries.map(([key, value]) => `${key.padEnd(width)}  ${value ?? ""}`).join("\n");
+}
+
+function firstArray(data) {
+  if (Array.isArray(data)) return data;
+  return Object.values(data ?? {}).find(Array.isArray) ?? null;
+}
+
+async function main() {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+
+  if (!command || command === "help" || flags.help) {
+    process.stdout.write(`${usage()}\n`);
+    return;
+  }
+  if (!(command in RESOURCES)) {
+    fail(`Unknown command '${command}'.\n\n${usage()}`);
+  }
+
+  const key = flags.key ?? process.env.VISITRACK_API_KEY;
+  if (!key || key === true) {
+    fail("No API key. Pass --key, or set VISITRACK_API_KEY.\nCreate one in Settings -> API / MCP.");
+  }
+
+  const host = (flags.host === true ? null : flags.host) ?? process.env.VISITRACK_HOST ?? DEFAULT_HOST;
+  const url = new URL(`/api/v1/${command}`, host);
+  for (const name of ["days", "from", "to", "granularity"]) {
+    if (flags[name] !== undefined && flags[name] !== true) url.searchParams.set(name, String(flags[name]));
+  }
+  // Flag names read like CLI options (kebab-case); the API's query params
+  // match the resource's own field names (camelCase) — translate here so
+  // the REST endpoint never has to know about the CLI's spelling.
+  if (flags["visitor-id"] !== undefined && flags["visitor-id"] !== true) {
+    url.searchParams.set("visitorId", String(flags["visitor-id"]));
+  }
+  if (flags["external-id"] !== undefined && flags["external-id"] !== true) {
+    url.searchParams.set("externalId", String(flags["external-id"]));
+  }
+  if (flags.csv) url.searchParams.set("format", "csv");
+
+  let response;
+  try {
+    response = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
+  } catch (error) {
+    fail(`Couldn't reach ${host}: ${error.message}`);
+  }
+
+  if (response.status === 401) fail("That API key was rejected. Check it, or create a new one in Settings -> API / MCP.");
+  if (response.status === 429) {
+    fail(`Rate limited — 120 requests a minute per key. Retry in ${response.headers.get("retry-after") ?? "a moment"}s.`);
+  }
+  if (!response.ok) {
+    let detail = "";
+    try {
+      detail = (await response.json()).error ?? "";
+    } catch {
+      /* non-JSON error body */
+    }
+    fail(`Request failed (${response.status})${detail ? `: ${detail}` : ""}`);
+  }
+
+  if (flags.csv) {
+    process.stdout.write(await response.text());
+    return;
+  }
+
+  const body = await response.json();
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(body, null, 2)}\n`);
+    return;
+  }
+
+  const rows = firstArray(body.data);
+  process.stdout.write(`${rows ? renderTable(rows) : renderObject(body.data)}\n`);
+}
+
+main().catch((error) => fail(error.message));