trackrev 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# trackrev
+
+Your [TrackRev](https://trackrev.io) link analytics, in the terminal — performance per channel,
+per link, the raw click stream, and any single visitor's full journey.
+
+Zero dependencies. Node 20 or newer.
+
+## Install
+
+```bash
+npx trackrev channels
+```
+
+Or keep it around:
+
+```bash
+npm install -g trackrev
+```
+
+## Authenticate
+
+Create a **secret** key under Settings → Developers, then:
+
+```bash
+export TRACKREV_KEY=lk_live_...
+```
+
+Set `TRACKREV_API_URL` to point at a different API base (self-hosted, staging).
+
+## Commands
+
+### `channels` — performance per traffic source
+
+```bash
+trackrev channels                # last 30 days
+trackrev channels --days 7
+trackrev channels --ltv          # add all-time lifetime value per channel
+```
+
+```
+channel     clicks  visitors  conversions   revenue
+youtube      1,204       980        12.50  2,410.50
+newsletter     310       287         9.00  1,890.00
+```
+
+`conversions` is a decimal because attribution splits credit — one sale touched by two channels
+counts 0.5 on each.
+
+### `links` — performance per short link
+
+```bash
+trackrev links --limit 20
+trackrev links --from 2026-01-01 --to 2026-02-01
+```
+
+### `clicks` — the raw click stream
+
+Newest first, bots excluded, cursor-paginated.
+
+```bash
+trackrev clicks                        # most recent 100
+trackrev clicks --limit 500            # one page, max size
+trackrev clicks --all                  # follow the cursor to the end
+trackrev clicks --link <link-id>       # one link only
+trackrev clicks --bots                 # include bot traffic
+```
+
+`--all` stops after 200 pages and says so on stderr, so a runaway cursor can't loop forever.
+
+### `journey` — one visitor's timeline
+
+```bash
+trackrev journey 3f1b8c22-9d4e-4a71-b8c0-2e6f5a91d7e4
+```
+
+Every click, identify event and order in order. The visitor id is the `visitor_id` column from
+`trackrev clicks`.
+
+## Window
+
+`channels` and `links` accept:
+
+| flag | meaning |
+| --- | --- |
+| `--days N` | last N days (default 30, max 365) |
+| `--from ISO` | explicit start, e.g. `2026-01-01` |
+| `--to ISO` | explicit end (defaults to now) |
+
+`--from`/`--to` win over `--days`.
+
+## Output
+
+The same data comes out three ways, so the command works both as something you read and as
+something you pipe:
+
+```bash
+trackrev channels                    # aligned table (a terminal)
+trackrev channels > channels.tsv     # tab-separated, raw values (a pipe or file)
+trackrev channels --json | jq .      # the API's own JSON body
+```
+
+Piped output is deliberately unformatted — `2410.5`, not `2,410.50` — so `cut` and `awk` see real
+numbers:
+
+```bash
+trackrev channels | cut -f1,5
+trackrev links --limit 10 | column -t
+trackrev clicks --all --json | jq '.clicks[] | select(.country == "BD")'
+```
+
+Warnings, errors and the `journey` caption always go to **stderr**, never into your pipe.
+
+## Exit codes
+
+| code | meaning |
+| --- | --- |
+| `0` | success |
+| `1` | no API key, auth failure, plan gate, network error, API error |
+| `2` | usage error — unknown flag or command, bad `--limit`, missing visitor id |
+

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "trackrev",
+  "version": "0.1.0",
+  "description": "Your TrackRev link analytics, in the terminal — channels, links and the raw click stream.",
+  "type": "module",
+  "bin": {
+    "trackrev": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "trackrev",
+    "analytics",
+    "attribution",
+    "link-tracking",
+    "cli"
+  ],
+  "homepage": "https://trackrev.io",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/index.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+// trackrev — your link analytics, in the terminal.
+//
+//   trackrev channels --days 7
+//   trackrev clicks --all --json > clicks.json
+import { parseArgs } from "node:util";
+import { createRequire } from "node:module";
+
+const { version } = createRequire(import.meta.url)("../package.json");
+const BASE = process.env.TRACKREV_API_URL ?? "https://app.trackrev.io/api/v1";
+const KEY = process.env.TRACKREV_KEY;
+
+const EXIT_FAIL = 1;
+const EXIT_USAGE = 2;
+const MAX_PAGES = 200;
+
+const HELP = `trackrev — your link analytics, in the terminal
+
+Usage
+  trackrev channels [--ltv]             performance per channel
+  trackrev links    [--limit N]         performance per link
+  trackrev clicks   [--all] [--link ID] the raw click stream
+  trackrev journey  <visitor-id>        one visitor's full timeline
+
+Window (channels, links)
+  --days N        last N days (default 30)
+  --from ISO      explicit start, e.g. 2026-01-01
+  --to ISO        explicit end (defaults to now)
+
+Options
+  --ltv           channels: add all-time lifetime value per channel
+  --limit N       links: rows to return; clicks: page size (max 500)
+  --all           clicks: follow the cursor to the end of the stream
+  --link ID       clicks: restrict to one link
+  --bots          clicks: include bot traffic (excluded by default)
+  --json          print raw JSON instead of a table
+  --version       print the version
+  --help          show this message
+
+Output
+  A table when you are watching, tab-separated when piped or redirected,
+  JSON with --json. Warnings and errors always go to stderr.
+
+Environment
+  TRACKREV_KEY       secret API key, from Settings → Developers
+  TRACKREV_API_URL   override the API base URL
+`;
+
+/* ── plumbing ───────────────────────────────────────────────────────────── */
+
+/** Anything that is not data goes to stderr, so it never lands in a pipe. */
+function warn(message) {
+  console.error(message);
+}
+
+/** Print to stderr and quit with a failure code. */
+function die(message, code = EXIT_FAIL) {
+  console.error(message);
+  process.exit(code);
+}
+
+/** GET a path under the API base, returning the parsed JSON body. */
+async function api(path) {
+  if (!KEY) die("No API key. Set TRACKREV_KEY to a secret key from Settings → Developers.");
+
+  let res;
+  try {
+    res = await fetch(BASE + path, { headers: { Authorization: `Bearer ${KEY}` } });
+  } catch {
+    return die(`Could not reach ${BASE} — is the server running?`);
+  }
+
+  if (!res.ok) {
+    const body = await res.json().catch(() => null);
+    const message = body?.error?.message ?? res.statusText;
+    if (res.status === 401) die(`${message}. Check TRACKREV_KEY.`);
+    if (res.status === 402) die(`${message}\nUpgrade at https://www.trackrev.io/pricing`);
+    if (res.status === 404) die(message);
+    die(`API error ${res.status}: ${message}`);
+  }
+  return res.json();
+}
+
+/* ── arguments ──────────────────────────────────────────────────────────── */
+
+// parseArgs throws on an unknown flag. Left uncaught that is a stack trace in
+// the user's face; caught, it is a one-line usage error.
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: {
+      days:    { type: "string",  default: "30" },
+      from:    { type: "string" },
+      to:      { type: "string" },
+      limit:   { type: "string" },
+      link:    { type: "string" },
+      ltv:     { type: "boolean", default: false },
+      all:     { type: "boolean", default: false },
+      bots:    { type: "boolean", default: false },
+      json:    { type: "boolean", default: false },
+      version: { type: "boolean", default: false },
+      help:    { type: "boolean", default: false },
+    },
+  });
+} catch (err) {
+  console.error(`${err.message}\n\nRun: trackrev --help`);
+  process.exit(EXIT_USAGE);
+}
+const { positionals, values } = parsed;
+const command = positionals[0];
+
+if (values.version) {
+  console.log(version);
+  process.exit(0);
+}
+if (values.help || !command) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+/**
+ * The reporting window as query params. `--from`/`--to` win over `--days`:
+ * the server ignores `days` once either bound is present, so sending all three
+ * would only be noise in the request log.
+ */
+function windowParams() {
+  const params = new URLSearchParams();
+  if (values.from) params.set("from", values.from);
+  if (values.to) params.set("to", values.to);
+  if (!values.from && !values.to) params.set("days", values.days);
+  return params;
+}
+
+/** Parse a numeric flag, failing with a usage error rather than sending NaN. */
+function intFlag(name, rawValue, { min = 1, max }) {
+  const n = Number(rawValue);
+  if (!Number.isInteger(n) || n < min || n > max) {
+    die(`--${name} must be a whole number between ${min} and ${max}.`, EXIT_USAGE);
+  }
+  return n;
+}
+
+/* ── output ─────────────────────────────────────────────────────────────── */
+
+const TTY = process.stdout.isTTY;
+
+/** Raw value for a pipe: no padding, no separators, empty cell for null. */
+function rawCell(value) {
+  return value === null || value === undefined ? "" : String(value);
+}
+
+/**
+ * Human value for a table. `fixed` is the column's decimal places, so a money
+ * column stays uniform (9 → 9.00) instead of following each individual value.
+ */
+function pretty(value, fixed = 0) {
+  if (value === null || value === undefined || value === "") return "—";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return "—";
+    return value.toLocaleString("en-US", {
+      minimumFractionDigits: fixed,
+      maximumFractionDigits: fixed,
+    });
+  }
+  return String(value);
+}
+
+/**
+ * Render rows three ways:
+ *   --json      the API's own body, untouched, for jq
+ *   a terminal  an aligned table
+ *   a pipe      tab-separated raw values, ready for cut/awk
+ */
+function emit(columns, rows, body) {
+  if (values.json) {
+    console.log(JSON.stringify(body, null, 2));
+    return;
+  }
+  if (rows.length === 0) {
+    warn("No rows for this window.");
+    return;
+  }
+
+  const header = columns.map((c) => c.header);
+  const cells = rows.map((row) => columns.map((c) => c.value(row)));
+
+  if (!TTY) {
+    console.log(header.join("\t"));
+    for (const line of cells) console.log(line.map(rawCell).join("\t"));
+    return;
+  }
+
+  const table = [header, ...cells.map((line) => line.map((v, i) => pretty(v, columns[i].fixed)))];
+  const widths = header.map((_, i) => Math.max(...table.map((line) => line[i].length)));
+  for (const line of table) {
+    console.log(
+      line
+        .map((v, i) => (columns[i].align === "right" ? v.padStart(widths[i]) : v.padEnd(widths[i])))
+        .join("  ")
+        .trimEnd(),
+    );
+  }
+}
+
+/* ── commands ───────────────────────────────────────────────────────────── */
+
+async function channels() {
+  const params = windowParams();
+  if (values.ltv) params.set("ltv", "1");
+  const body = await api(`/channels?${params}`);
+
+  const columns = [
+    { header: "channel",     value: (r) => r.channel },
+    { header: "clicks",      value: (r) => Number(r.clicks),      align: "right" },
+    { header: "visitors",    value: (r) => Number(r.visitors),    align: "right" },
+    { header: "conversions", value: (r) => Number(r.conversions), align: "right", fixed: 2 },
+    { header: "revenue",     value: (r) => Number(r.revenue),     align: "right", fixed: 2 },
+  ];
+  if (values.ltv) {
+    columns.push({ header: "ltv", value: (r) => Number(r.ltv), align: "right", fixed: 2 });
+  }
+
+  emit(columns, body.channels, body);
+}
+
+async function links() {
+  const params = windowParams();
+  if (values.limit !== undefined) {
+    params.set("limit", String(intFlag("limit", values.limit, { max: 500 })));
+  }
+  const body = await api(`/links?${params}`);
+
+  emit(
+    [
+      { header: "slug",        value: (r) => r.slug },
+      { header: "channel",     value: (r) => r.channel },
+      { header: "clicks",      value: (r) => Number(r.clicks),      align: "right" },
+      { header: "visitors",    value: (r) => Number(r.visitors),    align: "right" },
+      { header: "conversions", value: (r) => Number(r.conversions), align: "right", fixed: 2 },
+      { header: "revenue",     value: (r) => Number(r.revenue),     align: "right", fixed: 2 },
+      { header: "destination", value: (r) => r.destination },
+    ],
+    body.links,
+    body,
+  );
+}
+
+async function clicks() {
+  const pageSize = values.limit === undefined ? 100 : intFlag("limit", values.limit, { max: 500 });
+  const stream = [];
+  let before = null;
+  let pages = 0;
+
+  do {
+    const params = new URLSearchParams({ limit: String(pageSize) });
+    if (before) params.set("before", before);
+    if (values.link) params.set("link_id", values.link);
+    if (values.bots) params.set("bots", "include");
+
+    const page = await api(`/clicks?${params}`);
+    stream.push(...page.clicks);
+    before = page.next_cursor;
+
+    if (++pages >= MAX_PAGES && before) {
+      warn(`Stopped after ${MAX_PAGES} pages (${stream.length} clicks). Narrow it with --link.`);
+      break;
+    }
+  } while (values.all && before);
+
+  const columns = [
+    { header: "ts",      value: (r) => r.ts },
+    { header: "channel", value: (r) => r.channel },
+    { header: "country", value: (r) => r.country },
+    { header: "device",  value: (r) => r.device },
+    { header: "browser", value: (r) => r.browser },
+    { header: "visitor", value: (r) => r.visitor_id },
+  ];
+  if (values.bots) columns.push({ header: "bot", value: (r) => (r.is_bot ? "yes" : "") });
+
+  emit(columns, stream, { clicks: stream });
+}
+
+async function journey() {
+  const id = positionals[1];
+  if (!id) die("Usage: trackrev journey <visitor-id>", EXIT_USAGE);
+
+  const body = await api(`/visitors/${encodeURIComponent(id)}/journey`);
+  const who = body.visitor;
+  // Identity goes to stderr: it is a caption, not a row, so a pipe stays clean.
+  if (!values.json) warn(`visitor ${who.id}${who.email ? ` · ${who.email}` : ""}`);
+
+  emit(
+    [
+      { header: "ts",      value: (r) => r.ts },
+      { header: "kind",    value: (r) => r.kind },
+      { header: "label",   value: (r) => r.label },
+      { header: "channel", value: (r) => r.channel },
+      { header: "link",    value: (r) => r.link_slug },
+      { header: "amount",  value: (r) => (r.amount == null ? null : Number(r.amount)), align: "right", fixed: 2 },
+      { header: "detail",  value: (r) => r.detail },
+    ],
+    body.journey,
+    body,
+  );
+}
+
+/* ── dispatch ───────────────────────────────────────────────────────────── */
+
+const COMMANDS = { channels, links, clicks, journey };
+const run = COMMANDS[command];
+if (!run) {
+  console.error(`Unknown command "${command}".\n\nRun: trackrev --help`);
+  process.exit(EXIT_USAGE);
+}
+
+try {
+  await run();
+} catch (err) {
+  die(err?.message ?? String(err));
+}