trackrev 0.2.0 → 0.3.0

package/README.md

@@ -1,18 +1,27 @@
 # trackrev
 
-[TrackRev](https://trackrev.io) in your terminal — create and manage tracking links, pull
-performance per channel and per link, walk the raw click stream, and replay any visitor's
-journey from first click to paid conversion.
+[TrackRev](https://trackrev.io) for Node and the terminal — create and manage tracking links,
+pull performance per channel and per link, walk the raw click stream, replay any visitor's
+journey from first click to paid conversion, and run a referral program end to end.
 
-Zero dependencies. Node 20 or newer.
+One package, two ways in: `import { TrackRev } from "trackrev"` in your app, or the `trackrev`
+command in your shell. Zero dependencies. Node 20 or newer.
 
 ## Install
 
+In your project, for the SDK:
+
+```bash
+npm install trackrev
+```
+
+Globally, for the CLI:
+
 ```bash
 npm install -g trackrev
 ```
 
-Or run it once without installing:
+Or run the CLI once without installing:
 
 ```bash
 npx trackrev channels
@@ -45,6 +54,111 @@ dashboard does (50 links on the free tier). Analytics commands — `channels`, `
 `clicks`, `journey` — need a **paid plan**; on a free workspace they exit `3` with an upgrade
 message.
 
+## Node SDK
+
+Everything below, as a client for your own code. Twenty resources, 71 methods, and a
+hand-written `index.d.ts`, so an editor completes `trackrev.links.` and catches a misspelled
+option before the code runs.
+
+```js
+import { TrackRev } from "trackrev";
+
+const trackrev = new TrackRev(process.env.TRACKREV_KEY);
+
+const { channels } = await trackrev.channels.list({ days: 7 });
+
+const launch = await trackrev.links.create("https://acme.com/launch", "Launch", {
+  channels: ["youtube", "newsletter"],
+  maxClicks: 1000,
+});
+```
+
+Required arguments are positional; everything optional goes in a trailing object, named in
+camelCase and sent as the snake_case the API expects.
+
+```
+trackrev.attribution   .get .update
+trackrev.channels      .list
+trackrev.clicks        .list
+trackrev.commissions   .list .create .setStatus
+trackrev.credits       .list .markDelivered
+trackrev.domains       .list .get .add .verify .remove
+trackrev.export        .csv
+trackrev.folders       .list .get .create .update .remove .assign
+trackrev.keys          .list .create .revoke
+trackrev.links         .list .records .get .create .update .remove .createMany .qr
+trackrev.orders        .list
+trackrev.partners      .list .setStatus .setGroup
+trackrev.payouts       .list .settle
+trackrev.programs      .list .get .update .groups
+trackrev.referrals     .enroll .reportSignup .reportPurchase .stats
+                       .setPayoutMethod .setRewardMode
+trackrev.retargeting   .list .set .remove
+trackrev.revenue       .connections .connection .providers .connect
+                       .setWebhookSecret .disconnect .sync
+trackrev.settings      .notifications .setNotification .branding .updateBranding
+trackrev.visitors      .list .get .journey
+trackrev.webhooks      .list .events .get .create .update .remove
+trackrev.me()
+```
+
+### A referral program, end to end
+
+```js
+// Someone opts in. You get back their referral link.
+const { referral_link } = await trackrev.referrals.enroll(user.id, user.email, "paid");
+
+// Someone they invited signs up.
+await trackrev.referrals.reportSignup(newUser.id, { refCode: "abc123" });
+
+// That person pays. Idempotent on your own order id, so a replay never double-credits.
+await trackrev.referrals.reportPurchase(newUser.id, order.id, 49.99, { currency: "usd" });
+```
+
+### Errors
+
+Anything that is not a success rejects with a `TrackRevError` carrying the HTTP `status` and
+the API's own `code`. A request that never got an answer — server unreachable, or timed out —
+rejects with a `TrackRevConnectionError`, which is a `TrackRevError` with `status` 0.
+
+```js
+import { TrackRev, TrackRevError, TrackRevConnectionError } from "trackrev";
+
+try {
+  await trackrev.keys.create({ scope: "secret", label: "CI" });
+} catch (e) {
+  if (e instanceof TrackRevConnectionError) retryLater();
+  else if (e instanceof TrackRevError) console.error(e.status, e.code, e.message);
+  else throw e;
+}
+```
+
+### Retries
+
+A request that is safe to repeat is retried three times on a 429, a 5xx or a connection
+failure, backing off 400ms, 800ms, 1600ms with a little randomness so throttled clients do not
+all return in the same instant. A `Retry-After` header wins over that schedule.
+
+Safe to repeat means every `GET`, plus the three referral writes the API ignores a repeat of:
+`enroll`, `reportSignup` and `reportPurchase`. Every other write — creating a link, minting a
+key, settling a payout — is sent exactly once, because a retry there could do the work twice.
+
+### Options
+
+```js
+new TrackRev(key, {
+  apiUrl: "https://app.trackrev.io/api/v1", // point at staging or self-hosted
+  timeoutMs: 15000,                         // per attempt; 0 means no limit
+  maxRetries: 3,                            // 0 turns retries off
+});
+```
+
+An endpoint the SDK has no method for yet is one call away:
+
+```js
+await trackrev.request("GET", "/some/new/endpoint");
+```
+
 ## Commands
 
 <!-- cli:commands:start -->

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "trackrev",
-  "version": "0.2.0",
-  "description": "TrackRev in the terminal — create and manage tracking links, pull channel analytics, the raw click stream and any visitor's journey.",
+  "version": "0.3.0",
+  "description": "The TrackRev SDK and CLI — tracking links, channel analytics, referrals and affiliate payouts, from Node or the terminal.",
   "type": "module",
   "bin": {
     "trackrev": "src/index.js"
   },
   "exports": {
-    ".": "./src/index.js",
+    ".": {
+      "types": "./src/sdk/index.d.ts",
+      "default": "./src/sdk/index.js"
+    },
     "./registry": {
       "types": "./src/registry.d.ts",
       "default": "./src/registry.js"
@@ -27,7 +30,10 @@
     "attribution",
     "link-tracking",
     "short-links",
-    "cli"
+    "cli",
+    "sdk",
+    "affiliate",
+    "referral"
   ],
   "homepage": "https://trackrev.io",
   "license": "MIT",

package/src/commands/revenue.js

@@ -7,7 +7,8 @@ const COLUMNS = [
   { header: "provider",  value: (r) => r.provider },
   { header: "lastsync",  value: (r) => (r.last_sync_at ?? "").slice(0, 16).replace("T", " ") || null },
   { header: "webhook",   value: (r) => r.webhook_configured },
-  { header: "error",     value: (r) => r.last_error },
+  // Provider errors run long; the full text is in --json and in a pipe.
+  { header: "error",     value: (r) => r.last_error, max: 60 },
   { header: "id",        value: (r) => r.id },
 ];
 

package/src/lib/output.js

@@ -6,6 +6,18 @@ import { warn } from "./api.js";
 
 const TTY = process.stdout.isTTY;
 
+/** Widest a table cell renders before it is truncated with an ellipsis. */
+const DEFAULT_MAX_WIDTH = 48;
+
+/**
+ * Shorten a value for TABLE display only. Exported so the rule can be tested
+ * without a terminal: the test harness spawns the CLI, so stdout is a pipe,
+ * and pipes deliberately receive the untruncated value.
+ */
+export function truncate(value, max = DEFAULT_MAX_WIDTH) {
+  return value.length > max ? value.slice(0, max - 1) + "…" : value;
+}
+
 /** Raw value for a pipe: no padding, no separators, empty cell for null. */
 function rawCell(value) {
   return value === null || value === undefined ? "" : String(value);
@@ -48,6 +60,17 @@ export function emit(columns, rows, body, { json, empty = "No rows." } = {}) {
   }
 
   const table = [header, ...cells.map((line) => line.map((v, i) => pretty(v, columns[i].fixed)))];
+
+  // Cap each column so one long value cannot destroy the layout. A provider
+  // error can run to several hundred characters; left unbounded it pushes every
+  // other column off the screen and the table stops being a table. Truncation
+  // is display-only — the pipe and --json still carry the full text, which is
+  // where anyone reading a long message will actually want it.
+  for (const line of table) {
+    for (let i = 0; i < line.length; i++) {
+      line[i] = truncate(line[i], columns[i].max ?? DEFAULT_MAX_WIDTH);
+    }
+  }
   const widths = header.map((_, i) => Math.max(...table.map((line) => line[i].length)));
   for (const line of table) {
     console.log(

package/src/registry.d.ts

@@ -8,10 +8,29 @@ export interface CliFlag {
   default?: string;
 }
 
+/**
+ * The heading a command is filed under in `trackrev --help`, on /cli, on
+ * /agents and in the generated README tables. Kept in lockstep with the
+ * `group:` values in registry.js — a group that exists there but not here is
+ * invisible to every TypeScript consumer that filters by group.
+ */
+export type CliGroup =
+  | "Analytics"
+  | "Links"
+  | "Developers"
+  | "Setup"
+  | "Revenue"
+  | "Audience"
+  | "Domains"
+  | "Affiliate"
+  | "Money"
+  | "Settings"
+  | "Account";
+
 export interface CliCommand {
   noun: string;
   verb: string | null;
-  group: "Analytics" | "Links" | "Account";
+  group: CliGroup;
   summary: string;
   example: string;
   args: string[];

package/src/registry.js

@@ -20,7 +20,7 @@
  *
  * Kept honest by a test that asserts this matches package.json.
  */
-export const VERSION = "0.2.0";
+export const VERSION = "0.3.0";
 
 /** A flag definition. `arg` is the placeholder shown in help ("N", "ISO", "ID"). */
 const flag = (name, type, meaning, extra = {}) => ({ name, type, meaning, ...extra });

package/src/sdk/client.js

@@ -0,0 +1,177 @@
+import { attribution } from "./resources/attribution.js";
+import { channels } from "./resources/channels.js";
+import { clicks } from "./resources/clicks.js";
+import { commissions } from "./resources/commissions.js";
+import { credits } from "./resources/credits.js";
+import { domains } from "./resources/domains.js";
+import { exportCsv } from "./resources/export.js";
+import { folders } from "./resources/folders.js";
+import { keys } from "./resources/keys.js";
+import { links } from "./resources/links.js";
+import { orders } from "./resources/orders.js";
+import { partners } from "./resources/partners.js";
+import { payouts } from "./resources/payouts.js";
+import { programs } from "./resources/programs.js";
+import { referrals } from "./resources/referrals.js";
+import { retargeting } from "./resources/retargeting.js";
+import { revenue } from "./resources/revenue.js";
+import { settings } from "./resources/settings.js";
+import { visitors } from "./resources/visitors.js";
+import { webhooks } from "./resources/webhooks.js";
+export const VERSION = "0.3.0";
+const DEFAULT_API_URL = "https://app.trackrev.io/api/v1";
+
+const RETRYABLE_POSTS = new Set([
+  "/referrals/enroll",
+  "/referrals/report-signup",
+  "/referrals/report-purchase"
+])
+
+const sleep = (ms) => new Promise ((resolve)=> setTimeout(resolve, ms))
+
+export class TrackRevError extends Error {
+  constructor({ status, code, message }) {
+    super(message);
+
+    this.name = "TrackRevError";
+    this.status = status;
+    this.code = code;
+  }
+}
+export class TrackRevConnectionError extends TrackRevError {
+  constructor(message) {
+    super({
+      status: 0,
+      code: "connection_error",
+      message
+    });
+
+    this.name = "TrackRevConnectionError";
+  }
+}
+
+export class TrackRev {
+  constructor(key, {
+    apiUrl = DEFAULT_API_URL,
+    timeoutMs=15000,
+    maxRetries=3
+  } = {}) {
+    this.key = key;
+    this.apiUrl = apiUrl;
+    this.timeoutMs = timeoutMs;
+    this.maxRetries = maxRetries;
+    // One way to reach the API, handed to every resource, so a resource
+    // file never touches fetch or the key itself.
+    const call = (method, path, options) => this.request(method, path, options);
+
+    this.attribution = attribution(call);
+    this.channels = channels(call);
+    this.clicks = clicks(call);
+    this.commissions = commissions(call);
+    this.credits = credits(call);
+    this.domains = domains(call);
+    this.export = exportCsv(call);
+    this.folders = folders(call);
+    this.keys = keys(call);
+    this.links = links(call);
+    this.orders = orders(call);
+    this.partners = partners(call);
+    this.payouts = payouts(call);
+    this.programs = programs(call);
+    this.referrals = referrals(call);
+    this.retargeting = retargeting(call);
+    this.revenue = revenue(call);
+    this.settings = settings(call);
+    this.visitors = visitors(call);
+    this.webhooks = webhooks(call);
+  }
+
+  // Who am I, and what can this key do.
+  me() {
+    return this.request("GET", "/me");
+  }
+
+ 
+async request(method, path, options) {
+  const bare = path.split("?")[0];
+
+  const safeToRepeat =
+    method === "GET" || RETRYABLE_POSTS.has(bare);
+
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await this.#send(method, path, options);
+    } catch (e) {
+      const mightWorkLater =
+        e instanceof TrackRevConnectionError ||
+        e.status === 429 ||
+        e.status >= 500;
+
+      if (
+        !safeToRepeat ||
+        !mightWorkLater ||
+        attempt >= this.maxRetries
+      ) {
+        throw e;
+      }
+
+      const waitMs =
+        e.retryAfterMs ??
+        400 * 2 ** attempt + Math.random() * 200;
+
+      await sleep(waitMs);
+    }
+  }
+}
+  async #send(method, path, { body } = {}) {       
+    const url = this.apiUrl + path;
+    const payload = body ? JSON.stringify(body) : undefined;
+    let response;
+    let text;
+    try {
+      response = await fetch(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.key}`,
+          "Content-Type": "application/json"
+        },
+        body: payload,
+        signal: this.timeoutMs > 0 ? AbortSignal.timeout(this.timeoutMs): undefined
+      });
+      text= await response.text();
+    } catch (e) {
+      // fetch itself failed — server unreachable, DNS error. No response exists, timeout
+      if(e.name === 'TimeoutError'){
+        throw new TrackRevConnectionError(`Request timed out after ${this.timeoutMs}ms`);
+      }
+      throw new TrackRevConnectionError(e.message || "Network error");
+    }
+
+    // The API sends { error: { code, message } }, but never assume the
+    // body parses — a proxy in front of it can send HTML or nothing.
+    let data = text;
+    if(response.headers.get("Content-Type")?.includes("application/json")){
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = null;  
+      }
+    }
+   
+
+    if (!response.ok) {
+      const err =  new TrackRevError({
+        status: response.status,
+        code: data?.error?.code ?? "unknown_error",
+        message: data?.error?.message ?? `HTTP ${response.status}`
+      });
+      const retryAfter = Number(response.headers.get('Retry-After'));
+      if(retryAfter>0){
+        err.retryAfterMs = retryAfter * 1000;
+      }
+      throw err;
+    }
+
+    return data;
+  }
+}