trackrev 0.1.0 → 0.3.0

package/src/sdk/index.d.ts

@@ -0,0 +1,534 @@
+/**
+ * Type definitions for the TrackRev SDK.
+ *
+ * Hand-written, and the reason an editor can autocomplete `trackrev.links.`
+ * and underline a misspelled option before the code ever runs.
+ *
+ * What is typed here is everything you SEND: the method names, which arguments
+ * are required, and the exact spelling of every option. What comes back is
+ * typed as `ApiResult`, because response shapes belong to the API and are
+ * documented at https://trackrev.io/docs — pass a type of your own when you
+ * want one checked:
+ *
+ *   const link = (await trackrev.links.get("summer")) as MyLink;
+ */
+/** The SDK's own version, e.g. "0.3.0". Matches package.json. */
+export const VERSION: string;
+/** A decoded JSON response. Fields are reached without a compile-time check. */
+export type ApiResult = Record<string, any>;
+
+/** YYYY-MM-DD. */
+export type DateString = string;
+
+/** An ISO 8601 timestamp, e.g. "2026-09-24T10:00:00.000Z". */
+export type Timestamp = string;
+
+export interface TrackRevOptions {
+  /** Defaults to "https://app.trackrev.io/api/v1". */
+  apiUrl?: string;
+  /** Give up on one attempt after this long. 0 means no limit. Default 15000. */
+  timeoutMs?: number;
+  /** Retries after the first attempt, for requests that are safe to repeat. Default 3. */
+  maxRetries?: number;
+}
+
+/**
+ * Any answer from the API that was not a success: a bad request, a missing
+ * key, a plan gate, a rate limit, a server fault.
+ */
+export class TrackRevError extends Error {
+  constructor(init: { status: number; code: string; message: string });
+  name: string;
+  /** The HTTP status, or 0 when the request never got an answer. */
+  status: number;
+  /** The API's own code, e.g. "bad_request", "unauthorized", "plan_required". */
+  code: string;
+  /** Present on a 429 that carried a Retry-After header. */
+  retryAfterMs?: number;
+}
+
+/** The request never got an answer: the server was unreachable, or it timed out. */
+export class TrackRevConnectionError extends TrackRevError {
+  constructor(message: string);
+  status: 0;
+  code: "connection_error";
+}
+
+/* ── Shared option shapes ─────────────────────────────────────────────────── */
+
+/** A reporting window: `days`, or `from`/`to`. */
+export interface WindowOptions {
+  /** Default 30. */
+  days?: number;
+  from?: DateString;
+  to?: DateString;
+}
+
+/** Cursor paging: pass the `next_cursor` the previous call returned. */
+export interface PageOptions {
+  limit?: number;
+  cursor?: string;
+}
+
+/* ── Values the API validates ─────────────────────────────────────────────── */
+
+export type AttributionModel = "last_touch" | "first_touch" | "linear";
+export type CommissionStatus = "pending" | "eligible" | "paid" | "refunded" | "void" | "fraud";
+export type CommissionType = "percent" | "flat";
+export type ProgramStatus = "active" | "paused" | "archived";
+export type PartnerStatus = "pending" | "approved" | "rejected" | "banned" | "archived";
+export type CreditStatus = "earned" | "delivered" | "all";
+export type KeyScope = "secret" | "public";
+export type ReferrerTier = "free" | "paid";
+export type RewardMode = "referrer" | "affiliate";
+export type ExportKind = "channels" | "links" | "orders" | "visitors";
+
+/* ── attribution ──────────────────────────────────────────────────────────── */
+
+export interface AttributionResource {
+  /** The workspace's model and lookback window, plus the catalogue of models. */
+  get(): Promise<ApiResult>;
+  /** Both settings retroactively change every revenue figure the product reports. */
+  update(options?: {
+    model?: AttributionModel;
+    /** Clamped to 1–365. */
+    windowDays?: number;
+  }): Promise<ApiResult>;
+}
+
+/* ── channels ─────────────────────────────────────────────────────────────── */
+
+export interface ChannelsResource {
+  /** Performance per traffic source, ranked by revenue. */
+  list(options?: WindowOptions & {
+    /** Add all-time lifetime value per channel. */
+    ltv?: boolean;
+  }): Promise<ApiResult>;
+}
+
+/* ── clicks ───────────────────────────────────────────────────────────────── */
+
+export interface ClicksResource {
+  /** The raw click stream, newest first. Bots are excluded unless asked for. */
+  list(options?: {
+    limit?: number;
+    /** The previous call's `next_cursor`; null means you reached the end. */
+    before?: string;
+    linkId?: string;
+    includeBots?: boolean;
+  }): Promise<ApiResult>;
+}
+
+/* ── commissions ──────────────────────────────────────────────────────────── */
+
+export interface CommissionsResource {
+  /** The commission ledger, newest first. */
+  list(options?: PageOptions & {
+    status?: CommissionStatus;
+    partnerId?: string;
+  }): Promise<ApiResult>;
+  /** Record an off-platform deal by hand. `earnings` is what the partner takes home. */
+  create(
+    programId: string,
+    partnerId: string,
+    amount: number,
+    earnings: number,
+    options?: { currency?: string; notes?: string },
+  ): Promise<ApiResult>;
+  /** Refused once the commission sits in a payout batch. */
+  setStatus(id: string | number, status: CommissionStatus): Promise<ApiResult>;
+}
+
+/* ── credits ──────────────────────────────────────────────────────────────── */
+
+export interface CreditsResource {
+  /** Credit grants plus a balance summary. Pass `partnerId` or `externalUserId`. */
+  list(options?: {
+    partnerId?: string;
+    externalUserId?: string;
+    /** Default "all". */
+    status?: CreditStatus;
+    limit?: number;
+  }): Promise<ApiResult>;
+  /** Confirm a credit was applied in your product. Safe to call twice. */
+  markDelivered(id: string): Promise<ApiResult>;
+}
+
+/* ── domains ──────────────────────────────────────────────────────────────── */
+
+export interface DomainsResource {
+  /** Branded domains, each with the DNS records still needed. */
+  list(): Promise<ApiResult>;
+  get(idOrName: string): Promise<ApiResult>;
+  /** Register a branded domain, e.g. "go.brand.com". */
+  add(domain: string): Promise<ApiResult>;
+  /** Re-check DNS now and return the fresh status. */
+  verify(idOrName: string): Promise<ApiResult>;
+  /** Links keep working: slugs resolve on the default short host. */
+  remove(idOrName: string): Promise<ApiResult>;
+}
+
+/* ── export ───────────────────────────────────────────────────────────────── */
+
+export interface ExportResource {
+  /** Comes back as CSV text, not JSON. */
+  csv(kind: ExportKind, options?: WindowOptions): Promise<string>;
+}
+
+/* ── folders ──────────────────────────────────────────────────────────────── */
+
+export interface FoldersResource {
+  /** Campaign folders, each with how many campaigns it holds. */
+  list(): Promise<ApiResult>;
+  get(id: string): Promise<ApiResult>;
+  create(
+    name: string,
+    options?: {
+      description?: string;
+      startDate?: DateString;
+      endDate?: DateString;
+    },
+  ): Promise<ApiResult>;
+  /** Only the fields you pass change. */
+  update(
+    id: string,
+    options?: {
+      name?: string;
+      description?: string;
+      startDate?: DateString;
+      endDate?: DateString;
+    },
+  ): Promise<ApiResult>;
+  /** The campaigns inside are not deleted — they move back to ungrouped. */
+  remove(id: string): Promise<ApiResult>;
+  /**
+   * File a campaign into a folder. `destinationId` is a campaign (the
+   * destination behind a set of links), not a single link. Pass null to un-file.
+   */
+  assign(destinationId: string, folderId: string | null): Promise<ApiResult>;
+}
+
+/* ── keys ─────────────────────────────────────────────────────────────────── */
+
+export interface KeysResource {
+  /** Prefixes and metadata only — never the key itself. */
+  list(options?: { includeRevoked?: boolean }): Promise<ApiResult>;
+  /** The plaintext key comes back ONCE, as `secret`. A lost key is re-issued, never recovered. */
+  create(options?: { scope?: KeyScope; label?: string }): Promise<ApiResult>;
+  /** The row stays so `last_used_at` survives for the audit trail. */
+  revoke(id: string): Promise<ApiResult>;
+}
+
+/* ── links ────────────────────────────────────────────────────────────────── */
+
+/** Where a click goes, by where it came from. */
+export interface LinkTargeting {
+  [rule: string]: unknown;
+}
+
+export interface LinkCreateOptions {
+  /** One channel, e.g. "email". */
+  channel?: string;
+  /** Several channels, e.g. ["email", "x"]. */
+  channels?: string[];
+  /** Let TrackRev pick the channel per click. */
+  smart?: boolean;
+  campaign?: string;
+  slug?: string;
+  tags?: string[];
+  targeting?: LinkTargeting;
+  expiresAt?: Timestamp;
+  maxClicks?: number;
+  expiredRedirectUrl?: string;
+  password?: string;
+  retargeting?: boolean;
+  folderId?: string;
+  external?: boolean;
+}
+
+export interface LinkUpdateOptions {
+  slug?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+  targeting?: LinkTargeting;
+  expiresAt?: Timestamp;
+  maxClicks?: number;
+  expiredRedirectUrl?: string;
+  password?: string;
+  retargeting?: boolean;
+}
+
+/** One row for `createMany`. */
+export interface LinkBulkRow {
+  url: string;
+  name?: string;
+  channel?: string;
+  [field: string]: unknown;
+}
+
+export interface LinksResource {
+  /** Performance per link for a window. */
+  list(options?: WindowOptions & {
+    limit?: number;
+    /** Attach each link's own record (expiry, password…). */
+    withSettings?: boolean;
+  }): Promise<ApiResult>;
+  /** The links themselves, newest first, with no window. */
+  records(options?: PageOptions & {
+    channel?: string;
+    destinationId?: string;
+    /** Search text. */
+    q?: string;
+  }): Promise<ApiResult>;
+  /** By id, slug or short code. */
+  get(idOrSlug: string): Promise<ApiResult>;
+  /** Create a campaign: one destination plus a link per channel. */
+  create(url: string, name: string, options?: LinkCreateOptions): Promise<ApiResult>;
+  /** Only the fields you pass change. */
+  update(id: string, options?: LinkUpdateOptions): Promise<ApiResult>;
+  /** The campaign and its other channels stay. */
+  remove(id: string): Promise<ApiResult>;
+  /** Up to 500 links in one call. A bad row is reported in `rows`, not thrown. */
+  createMany(rows: LinkBulkRow[]): Promise<ApiResult>;
+  /** The QR code as SVG text, not JSON. */
+  qr(idOrSlug: string, options?: { size?: number }): Promise<string>;
+}
+
+/* ── orders ───────────────────────────────────────────────────────────────── */
+
+export interface OrdersResource {
+  /** Synced purchases, newest first. On a free workspace `amount` is null. */
+  list(options?: PageOptions & {
+    status?: string;
+    email?: string;
+  }): Promise<ApiResult>;
+}
+
+/* ── partners ─────────────────────────────────────────────────────────────── */
+
+export interface PartnersResource {
+  /** Affiliates across every program, or one program's. */
+  list(options?: { programId?: string; status?: PartnerStatus }): Promise<ApiResult>;
+  /** Unlike the dashboard this sends no email, so re-running it mails nobody twice. */
+  setStatus(programId: string, partnerId: string, status: PartnerStatus): Promise<ApiResult>;
+  /** Pass null as `groupId` to drop them back to the program's own terms. */
+  setGroup(programId: string, partnerId: string, groupId: string | null): Promise<ApiResult>;
+}
+
+/* ── payouts ──────────────────────────────────────────────────────────────── */
+
+export interface PayoutsResource {
+  /** Payout batches with open and all-time totals. */
+  list(options?: { status?: string; limit?: number }): Promise<ApiResult>;
+  /** Settle a batch you paid off-platform. Creating a batch stays dashboard-only. */
+  settle(id: string | number, options?: {
+    /** The rail's own id — a PayPal batch, a Wise transfer. */
+    reference?: string;
+  }): Promise<ApiResult>;
+}
+
+/* ── programs ─────────────────────────────────────────────────────────────── */
+
+export interface ProgramsResource {
+  list(options?: { includeArchived?: boolean }): Promise<ApiResult>;
+  get(id: string): Promise<ApiResult>;
+  /** Only the fields you pass change: an omitted field must never reset a rate. */
+  update(
+    id: string,
+    options?: {
+      name?: string;
+      landingUrl?: string;
+      commissionType?: CommissionType;
+      /** A 0–1 fraction for percent programs, so 0.3 means 30%. Dollars for flat. */
+      commissionRate?: number;
+      recurringMonths?: number;
+      cookieWindowDays?: number;
+      minPayout?: number;
+      autoApprove?: boolean;
+      status?: ProgramStatus;
+    },
+  ): Promise<ApiResult>;
+  /** The program's affiliate tiers, each with the terms an affiliate in it really gets. */
+  groups(id: string): Promise<ApiResult>;
+}
+
+/* ── referrals ────────────────────────────────────────────────────────────── */
+
+export interface ReferralsResource {
+  /** A user opts into your referral program. */
+  enroll(
+    externalUserId: string,
+    email: string,
+    tier: ReferrerTier,
+    options?: { name?: string; programId?: string },
+  ): Promise<ApiResult>;
+  /** A new user signed up. Pass one of `refCode`, `vid` or `referrerExternalUserId`. */
+  reportSignup(
+    newUserExternalUserId: string,
+    options?: {
+      refCode?: string;
+      vid?: string;
+      referrerExternalUserId?: string;
+      email?: string;
+    },
+  ): Promise<ApiResult>;
+  /** A user paid. Needs a secret key. Idempotent on your `orderId`. */
+  reportPurchase(
+    externalUserId: string,
+    orderId: string,
+    /** Major units, e.g. 49.99. */
+    amount: number,
+    options?: {
+      /** Default "usd". */
+      currency?: string;
+      email?: string;
+      /** True for renewals. */
+      recurring?: boolean;
+      ts?: Timestamp;
+    },
+  ): Promise<ApiResult>;
+  /** A user's referral link, KPIs and earnings. */
+  stats(
+    externalUserId: string,
+    options?: {
+      email?: string;
+      tier?: ReferrerTier;
+      /** 7 to 90. */
+      days?: number;
+    },
+  ): Promise<ApiResult>;
+  /** Where an affiliate gets paid. PayPal only for now. */
+  setPayoutMethod(externalUserId: string, paypalEmail: string): Promise<ApiResult>;
+  /** Switch between earning credits ("referrer") and cash ("affiliate"). */
+  setRewardMode(externalUserId: string, mode: RewardMode): Promise<ApiResult>;
+}
+
+/* ── retargeting ──────────────────────────────────────────────────────────── */
+
+export interface RetargetingResource {
+  /** Your ad-pixel library, plus the id shape each provider expects. */
+  list(): Promise<ApiResult>;
+  /** e.g. set("meta", "1234567890"). The id must match that provider's shape. */
+  set(provider: string, pixelId: string): Promise<ApiResult>;
+  remove(provider: string): Promise<ApiResult>;
+}
+
+/* ── revenue ──────────────────────────────────────────────────────────────── */
+
+export interface RevenueResource {
+  /** Connected billing providers. Credentials are never returned. */
+  connections(): Promise<ApiResult>;
+  connection(id: string): Promise<ApiResult>;
+  /** What can be connected, and which credential fields each one needs. */
+  providers(): Promise<ApiResult>;
+  /** Proved with one live read before anything is stored, so a bad key fails here. */
+  connect(
+    provider: string,
+    credentials: Record<string, string>,
+    options?: { sandbox?: boolean },
+  ): Promise<ApiResult>;
+  /** With it set, sales arrive in seconds; without it the connection is cron-only. */
+  setWebhookSecret(id: string, webhookSecret: string | null): Promise<ApiResult>;
+  /** Past orders are kept. */
+  disconnect(id: string): Promise<ApiResult>;
+  /** Omit `connectionId` to sync every connection plus Stripe. */
+  sync(options?: { connectionId?: string }): Promise<ApiResult>;
+}
+
+/* ── settings ─────────────────────────────────────────────────────────────── */
+
+export interface SettingsResource {
+  /** Every transactional email, with whether it is on for this workspace. */
+  notifications(): Promise<ApiResult>;
+  /** e.g. setNotification("sale.created", false). */
+  setNotification(key: string, enabled: boolean): Promise<ApiResult>;
+  /** The white-label settings affiliates see. */
+  branding(): Promise<ApiResult>;
+  /** Only the fields you pass change. */
+  updateBranding(options?: { color?: string; logoUrl?: string }): Promise<ApiResult>;
+}
+
+/* ── visitors ─────────────────────────────────────────────────────────────── */
+
+export interface VisitorsResource {
+  /** Visitors, most recently seen first. */
+  list(options?: PageOptions & { email?: string }): Promise<ApiResult>;
+  get(id: string): Promise<ApiResult>;
+  /** Every click, identify event and order for one visitor, oldest first. */
+  journey(id: string): Promise<ApiResult>;
+}
+
+/* ── webhooks ─────────────────────────────────────────────────────────────── */
+
+export interface WebhooksResource {
+  /** The signing secret is never included here. */
+  list(): Promise<ApiResult>;
+  /** The catalogue of events an endpoint can subscribe to. */
+  events(): Promise<ApiResult>;
+  get(id: string): Promise<ApiResult>;
+  /** `url` must be https. The response carries the signing secret ONCE. */
+  create(url: string, events: string[]): Promise<ApiResult>;
+  /** Only the fields you pass change. Pause it with `active: false`. */
+  update(
+    id: string,
+    options?: { url?: string; events?: string[]; active?: boolean },
+  ): Promise<ApiResult>;
+  /** Deliveries stop at once. */
+  remove(id: string): Promise<ApiResult>;
+}
+
+/* ── The client ───────────────────────────────────────────────────────────── */
+
+/**
+ * The TrackRev API client.
+ *
+ *   import { TrackRev } from "trackrev";
+ *
+ *   const trackrev = new TrackRev(process.env.TRACKREV_KEY);
+ *   const { channels } = await trackrev.channels.list({ days: 7 });
+ *
+ * Every method rejects with a TrackRevError when the API says no.
+ */
+export class TrackRev {
+  constructor(key: string, options?: TrackRevOptions);
+
+  key: string;
+  apiUrl: string;
+  timeoutMs: number;
+  maxRetries: number;
+
+  /** Who am I, and what can this key do. */
+  me(): Promise<ApiResult>;
+
+  /**
+   * The one way every resource reaches the API. Call it directly for an
+   * endpoint the SDK has no method for yet.
+   */
+  request(
+    method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE",
+    path: string,
+    options?: { body?: unknown },
+  ): Promise<any>;
+
+  attribution: AttributionResource;
+  channels: ChannelsResource;
+  clicks: ClicksResource;
+  commissions: CommissionsResource;
+  credits: CreditsResource;
+  domains: DomainsResource;
+  export: ExportResource;
+  folders: FoldersResource;
+  keys: KeysResource;
+  links: LinksResource;
+  orders: OrdersResource;
+  partners: PartnersResource;
+  payouts: PayoutsResource;
+  programs: ProgramsResource;
+  referrals: ReferralsResource;
+  retargeting: RetargetingResource;
+  revenue: RevenueResource;
+  settings: SettingsResource;
+  visitors: VisitorsResource;
+  webhooks: WebhooksResource;
+}

package/src/sdk/index.js

@@ -0,0 +1 @@
+export { TrackRev, TrackRevError, TrackRevConnectionError, VERSION } from "./client.js";

package/src/sdk/resources/attribution.js

@@ -0,0 +1,20 @@
+export function attribution(request) {
+  return {
+    // The workspace's attribution model and lookback window, plus the
+    // catalogue of models, so a client can offer the choice without
+    // hardcoding the list.
+    get: () => {
+      return request("GET", "/attribution");
+    },
+
+    // Change the model or the window. Both retroactively change every
+    // revenue figure the product reports, because the engine replays
+    // each journey against whatever is set here. windowDays is clamped
+    // to 1–365.
+    update: ({ model, windowDays } = {}) => {
+      return request("PATCH", "/attribution", {
+        body: { model, window_days: windowDays },
+      });
+    },
+  };
+}

package/src/sdk/resources/channels.js

@@ -0,0 +1,16 @@
+export function channels(request) {
+  return {
+    // Performance per traffic source, ranked by revenue. Window: days
+    // (default 30) or from/to as YYYY-MM-DD. ltv adds all-time lifetime
+    // value per channel.
+    list: ({ days, from, to, ltv } = {}) => {
+      const params = new URLSearchParams();
+      if (days) params.set("days", String(days));
+      if (from) params.set("from", from);
+      if (to) params.set("to", to);
+      if (ltv) params.set("ltv", "1");
+      const qs = params.toString();
+      return request("GET", qs ? `/channels?${qs}` : "/channels");
+    },
+  };
+}

package/src/sdk/resources/clicks.js

@@ -0,0 +1,16 @@
+export function clicks(request) {
+  return {
+    // The raw click stream, newest first. To page, pass the previous
+    // call's next_cursor as before; null means you reached the end.
+    // Bot clicks are excluded unless you ask for them.
+    list: ({ limit, before, linkId, includeBots } = {}) => {
+      const params = new URLSearchParams();
+      if (limit) params.set("limit", String(limit));
+      if (before) params.set("before", before);
+      if (linkId) params.set("link_id", linkId);
+      if (includeBots) params.set("bots", "include");
+      const qs = params.toString();
+      return request("GET", qs ? `/clicks?${qs}` : "/clicks");
+    },
+  };
+}

package/src/sdk/resources/commissions.js

@@ -0,0 +1,40 @@
+export function commissions(request) {
+  return {
+    // The commission ledger, newest first. chain_level is 1 for the
+    // affiliate who sold and 2 or more for an upline earning from them.
+    list: ({ limit, cursor, status, partnerId } = {}) => {
+      const params = new URLSearchParams();
+      if (limit) params.set("limit", String(limit));
+      if (cursor) params.set("cursor", cursor);
+      if (status) params.set("status", status);
+      if (partnerId) params.set("partner_id", partnerId);
+      const qs = params.toString();
+      return request("GET", qs ? `/commissions?${qs}` : "/commissions");
+    },
+
+    // Record an off-platform deal by hand. earnings is what the partner
+    // takes home and is required, because a manual commission exists
+    // precisely when the program's normal rate did not apply.
+    create: (programId, partnerId, amount, earnings, { currency, notes } = {}) => {
+      return request("POST", "/commissions", {
+        body: {
+          program_id: programId,
+          partner_id: partnerId,
+          amount,
+          earnings,
+          currency,
+          notes,
+        },
+      });
+    },
+
+    // Usually voiding one entered in error. Refused once the commission
+    // sits in a payout batch, where voiding it would leave the batch
+    // total disagreeing with its rows.
+    setStatus: (id, status) => {
+      return request("PATCH", `/commissions/${encodeURIComponent(id)}`, {
+        body: { status },
+      });
+    },
+  };
+}

package/src/sdk/resources/credits.js

@@ -0,0 +1,23 @@
+export function credits(request) {
+  return {
+    // Credit grants plus a balance summary. Pass partnerId or
+    // externalUserId — one of the two is required. status: "earned",
+    // "delivered" or "all" (default all).
+    list: ({ partnerId, externalUserId, status, limit } = {}) => {
+      const params = new URLSearchParams();
+      if (partnerId) params.set("partner_id", partnerId);
+      if (externalUserId) params.set("external_user_id", externalUserId);
+      if (status) params.set("status", status);
+      if (limit) params.set("limit", String(limit));
+      const qs = params.toString();
+      return request("GET", qs ? `/credits?${qs}` : "/credits");
+    },
+
+    // Confirm a credit was actually applied in your product: it moves
+    // from earned to delivered and fires credit.delivered. Calling it on
+    // an already-delivered credit succeeds and changes nothing.
+    markDelivered: (id) => {
+      return request("POST", `/credits/${encodeURIComponent(id)}/mark-delivered`);
+    },
+  };
+}