trackrev 0.1.0 → 0.2.0

package/src/commands/webhooks.js

@@ -0,0 +1,79 @@
+// Outbound webhook endpoints. The signing secret is shown once at creation.
+import { die, warn, EXIT } from "../lib/api.js";
+import { emit } from "../lib/output.js";
+import { confirm } from "../lib/prompt.js";
+
+const COLUMNS = [
+  { header: "url",     value: (r) => r.url },
+  { header: "events",  value: (r) => (r.events ?? []).join(",") },
+  { header: "active",  value: (r) => r.active },
+  { header: "status",  value: (r) => r.last_status },
+  { header: "lastfire",value: (r) => (r.last_at ?? "").slice(0, 16).replace("T", " ") || null },
+  { header: "id",      value: (r) => r.id },
+];
+
+export async function list({ flags, api }) {
+  const body = await api.get("/webhooks");
+  emit(COLUMNS, body.webhooks, body, {
+    json: flags.json,
+    empty: "No endpoints. Create one with: trackrev webhooks create",
+  });
+}
+
+export async function events({ flags, api }) {
+  const body = await api.get("/webhooks/events");
+  emit(
+    [
+      { header: "event", value: (r) => r.value },
+      { header: "fires when", value: (r) => r.label },
+    ],
+    body.events,
+    body,
+    { json: flags.json },
+  );
+}
+
+export async function create({ flags, api }) {
+  if (!flags.url) die("--url is required (https only).", EXIT.USAGE);
+  if (!flags.event || flags.event.length === 0) {
+    die("Pass at least one --event. See: trackrev webhooks events", EXIT.USAGE);
+  }
+  const body = await api.post("/webhooks", { url: flags.url, events: flags.event });
+
+  if (flags.json) {
+    console.log(JSON.stringify(body, null, 2));
+    return;
+  }
+  warn(`Created ${body.webhook.url} for ${body.webhook.events.join(", ")}.`);
+  warn("Signing secret (shown once):");
+  console.log(body.secret);
+}
+
+export async function update({ args, flags, api }) {
+  const [id] = args;
+  const patch = {};
+  if (flags.url !== undefined) patch.url = flags.url;
+  if (flags.event && flags.event.length) patch.events = flags.event;
+  if (flags.pause) patch.active = false;
+  if (flags.resume) patch.active = true;
+  if (flags.pause && flags.resume) die("Pass --pause or --resume, not both.", EXIT.USAGE);
+  if (Object.keys(patch).length === 0) {
+    die("Nothing to change. Run: trackrev webhooks update --help", EXIT.USAGE);
+  }
+
+  const hook = await api.patch(`/webhooks/${encodeURIComponent(id)}`, patch);
+  emit(COLUMNS, [hook], hook, { json: flags.json });
+}
+
+export async function remove({ args, flags, api }) {
+  const [id] = args;
+  const hook = await api.get(`/webhooks/${encodeURIComponent(id)}`);
+  const ok = await confirm(`Delete the endpoint ${hook.url}? Deliveries stop immediately.`, {
+    yes: flags.yes,
+  });
+  if (!ok) die("Cancelled.", EXIT.USAGE);
+
+  const res = await api.del(`/webhooks/${encodeURIComponent(hook.id)}`);
+  if (flags.json) console.log(JSON.stringify(res, null, 2));
+  else warn(`Deleted ${hook.url}.`);
+}

package/src/index.js

@@ -1,321 +1,70 @@
 #!/usr/bin/env node
-// trackrev — your link analytics, in the terminal.
+// trackrev — TrackRev in the terminal.
 //
 //   trackrev channels --days 7
+//   trackrev links create --url https://acme.com/launch --name Launch --channel youtube
 //   trackrev clicks --all --json > clicks.json
 import { parseArgs } from "node:util";
-import { createRequire } from "node:module";
+import { VERSION, resolve, optionsFor, helpText, helpFor, usageOf } from "./registry.js";
+import { resolveAuth } from "./lib/config.js";
+import { createApi, die, EXIT } from "./lib/api.js";
 
-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 argv = process.argv.slice(2);
 
-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;
+// Pass 1 — lenient. We don't know the command yet, so parse with the union of
+// every flag (so `--days 7` consumes its value instead of leaking "7" into the
+// positionals) and tolerate anything unknown.
+let first;
 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 },
-    },
-  });
+  first = parseArgs({ args: argv, allowPositionals: true, strict: false, options: optionsFor(null) });
 } catch (err) {
-  console.error(`${err.message}\n\nRun: trackrev --help`);
-  process.exit(EXIT_USAGE);
+  die(`${err.message}\n\nRun: trackrev --help`, 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);
+if (first.values.version) {
+  console.log(VERSION);
   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(),
-    );
-  }
+const [noun, maybeVerb] = first.positionals;
+if (!noun) {
+  console.log(helpText());
+  process.exit(0);
 }
 
-/* ── 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);
+const match = resolve(noun, maybeVerb);
+if (!match) {
+  die(`Unknown command "${[noun, maybeVerb].filter(Boolean).join(" ")}".\n\nRun: trackrev --help`, EXIT.USAGE);
 }
+const { command, consumed } = match;
 
-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,
-  );
+if (first.values.help) {
+  console.log(helpFor(command));
+  process.exit(0);
 }
 
-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 });
+// Pass 2 — strict, with exactly this command's flags. An unknown flag is a
+// one-line usage error, not a stack trace.
+let parsed;
+try {
+  parsed = parseArgs({ args: argv, allowPositionals: true, strict: true, options: optionsFor(command) });
+} catch (err) {
+  die(`${err.message}\n\nRun: trackrev ${usageOf(command)} --help`, EXIT.USAGE);
 }
+const flags = parsed.values;
+const args = parsed.positionals.slice(consumed);
 
-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,
-  );
+if (args.length < command.args.length) {
+  die(`Usage: trackrev ${usageOf(command)} ${command.args.map((a) => `<${a}>`).join(" ")}`, EXIT.USAGE);
 }
 
-/* ── 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);
-}
+const auth = resolveAuth(flags.profile);
+const api = createApi(auth);
+const mod = await import(`./commands/${command.module}.js`);
+const handler = mod[command.handler];
 
 try {
-  await run();
+  await handler({ args, flags, api, auth, command });
 } catch (err) {
-  die(err?.message ?? String(err));
-}
+  die(err && err.message ? err.message : String(err));
+}

package/src/lib/api.js

@@ -0,0 +1,87 @@
+import { VERSION } from "../registry.js";
+
+export const EXIT = { OK: 0, FAIL: 1, USAGE: 2, PLAN: 3 };
+
+/** Anything that is not data goes to stderr, so it never lands in a pipe. */
+export function warn(message) {
+  console.error(message);
+}
+
+/** Print to stderr and quit with a failure code. */
+export function die(message, code = EXIT.FAIL) {
+  console.error(message);
+  process.exit(code);
+}
+
+/**
+ * A tiny client over /api/v1. Every non-2xx becomes a one-line error and an
+ * exit code a script can branch on: 401 → 1, 402 → 3, 400 → 2, the rest → 1.
+ */
+/**
+ * The secret key rides in every request, so refuse to send it in cleartext.
+ * http is allowed only for localhost, where there is no network to sniff.
+ * Carried over from the September 2026 hardening of the single-file CLI.
+ */
+function assertSecureBase(apiUrl) {
+  let u = null;
+  try {
+    u = new URL(apiUrl);
+  } catch {
+    /* handled below */
+  }
+  const local = u && (u.hostname === "localhost" || u.hostname === "127.0.0.1");
+  if (!u || (u.protocol !== "https:" && !local)) {
+    die(
+      "TRACKREV_API_URL must be an https:// URL (http is only allowed for localhost).",
+      EXIT.USAGE,
+    );
+  }
+}
+
+export function createApi({ key, apiUrl, source }) {
+  assertSecureBase(apiUrl);
+
+  async function request(method, path, body) {
+    if (!key) {
+      die("No API key. Run `trackrev login`, or set TRACKREV_KEY to a secret key from Settings → Developers.");
+    }
+    const headers = {
+      Authorization: `Bearer ${key}`,
+      "User-Agent": `trackrev-cli/${VERSION}`,
+    };
+    let payload;
+    if (body !== undefined) {
+      const isText = typeof body === "string";
+      headers["Content-Type"] = isText ? "text/csv" : "application/json";
+      payload = isText ? body : JSON.stringify(body);
+    }
+
+    let res;
+    try {
+      res = await fetch(apiUrl + path, { method, headers, body: payload });
+    } catch {
+      return die(`Could not reach ${apiUrl} — is the server running?`);
+    }
+
+    const type = res.headers.get("content-type") || "";
+    const parsed = type.includes("json") ? await res.json().catch(() => null) : await res.text();
+
+    if (!res.ok) {
+      const message = (parsed && parsed.error && parsed.error.message) || res.statusText;
+      if (res.status === 401) die(`${message}. The key came from ${source}.`);
+      if (res.status === 402) die(`${message}\nUpgrade at https://www.trackrev.io/pricing`, EXIT.PLAN);
+      if (res.status === 400) die(message, EXIT.USAGE);
+      if (res.status === 404 || res.status === 409) die(message);
+      die(`API error ${res.status}: ${message}`);
+    }
+    return parsed;
+  }
+
+  return {
+    get: (path) => request("GET", path),
+    post: (path, body) => request("POST", path, body),
+    patch: (path, body) => request("PATCH", path, body),
+    put: (path, body) => request("PUT", path, body),
+    del: (path) => request("DELETE", path),
+  };
+}

package/src/lib/config.js

@@ -0,0 +1,52 @@
+// Saved logins. One file, several named profiles, one marked current:
+//   { "current": "default", "profiles": { "default": { "key": "lk_…", "apiUrl": "…" } } }
+// Written 0600 — it holds a secret key.
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_API = "https://app.trackrev.io/api/v1";
+
+export function configPath() {
+  const root = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(root, "trackrev", "config.json");
+}
+
+export function readConfig() {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+    return { current: parsed.current || "default", profiles: parsed.profiles || {} };
+  } catch {
+    return { current: "default", profiles: {} };
+  }
+}
+
+export function writeConfig(cfg) {
+  const p = configPath();
+  mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
+  writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(p, 0o600);
+}
+
+export function deleteConfig() {
+  rmSync(configPath(), { force: true });
+}
+
+/**
+ * Resolve credentials. Highest precedence first:
+ *   1. TRACKREV_KEY / TRACKREV_API_URL in the environment (CI, one-offs)
+ *   2. --profile NAME
+ *   3. the profile `trackrev login` marked current
+ */
+export function resolveAuth(profileFlag) {
+  const cfg = readConfig();
+  const name = profileFlag || cfg.current || "default";
+  const profile = cfg.profiles[name] || {};
+  const envKey = process.env.TRACKREV_KEY;
+  return {
+    profile: name,
+    key: envKey || profile.key || null,
+    apiUrl: process.env.TRACKREV_API_URL || profile.apiUrl || DEFAULT_API,
+    source: envKey ? "the environment" : profile.key ? `profile "${name}"` : "nowhere",
+  };
+}

package/src/lib/output.js

@@ -0,0 +1,72 @@
+// Three renderings of the same rows:
+//   --json      the API's own body, untouched, for jq
+//   a terminal  an aligned table
+//   a pipe      tab-separated raw values, ready for cut/awk
+import { warn } from "./api.js";
+
+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 === "boolean") return value ? "yes" : "";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return "—";
+    return value.toLocaleString("en-US", {
+      minimumFractionDigits: fixed,
+      maximumFractionDigits: fixed,
+    });
+  }
+  return String(value);
+}
+
+export function emit(columns, rows, body, { json, empty = "No rows." } = {}) {
+  if (json) {
+    console.log(JSON.stringify(body, null, 2));
+    return;
+  }
+  if (rows.length === 0) {
+    warn(empty);
+    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(),
+    );
+  }
+}
+
+/** A single record as aligned `key  value` lines (TTY) or key/value TSV (pipe). */
+export function emitRecord(pairs, body, { json } = {}) {
+  if (json) {
+    console.log(JSON.stringify(body, null, 2));
+    return;
+  }
+  const w = TTY ? Math.max(...pairs.map(([k]) => k.length)) : 0;
+  for (const [k, v] of pairs) {
+    console.log(TTY ? `${k.padEnd(w)}  ${pretty(v)}` : [k, rawCell(v)].join("\t"));
+  }
+}