trackrev 0.1.0 → 0.3.0

package/src/sdk/resources/domains.js

@@ -0,0 +1,35 @@
+export function domains(request) {
+  return {
+    // Branded domains, each with the DNS records still needed.
+    list: () => {
+      return request("GET", "/domains");
+    },
+
+    // One domain, by id or by the domain name itself.
+    get: (idOrName) => {
+      return request("GET", `/domains/${encodeURIComponent(idOrName)}`);
+    },
+
+    // Register a branded domain, e.g. "go.brand.com". The response
+    // carries the verification records to add to your DNS; call verify()
+    // until the status turns active.
+    add: (domain) => {
+      return request("POST", "/domains", {
+        body: { domain },
+      });
+    },
+
+    // Re-check DNS now and return the fresh status.
+    verify: (idOrName) => {
+      return request("POST", `/domains/${encodeURIComponent(idOrName)}`, {
+        body: {},
+      });
+    },
+
+    // Detach it. Links keep working: slugs stay unique and resolve on
+    // the default short host.
+    remove: (idOrName) => {
+      return request("DELETE", `/domains/${encodeURIComponent(idOrName)}`);
+    },
+  };
+}

package/src/sdk/resources/export.js

@@ -0,0 +1,15 @@
+export function exportCsv(request) {
+  return {
+    // A CSV of one dataset: "channels", "links", "orders" or "visitors",
+    // over a window of days (default 30) or from/to. It comes back as
+    // text rather than JSON, so it needs a client that can read
+    // plain-text responses.
+    csv: (kind, { days, from, to } = {}) => {
+      const params = new URLSearchParams({ kind });
+      if (days) params.set("days", String(days));
+      if (from) params.set("from", from);
+      if (to) params.set("to", to);
+      return request("GET", `/export?${params}`);
+    },
+  };
+}

package/src/sdk/resources/folders.js

@@ -0,0 +1,55 @@
+export function folders(request) {
+  return {
+    // Campaign folders, each with how many campaigns it holds.
+    list: () => {
+      return request("GET", "/folders");
+    },
+
+    // One folder.
+    get: (id) => {
+      return request("GET", `/folders/${encodeURIComponent(id)}`);
+    },
+
+    // Create a folder. Dates are YYYY-MM-DD.
+    create: (name, { description, startDate, endDate } = {}) => {
+      return request("POST", "/folders", {
+        body: {
+          name,
+          description,
+          start_date: startDate,
+          end_date: endDate,
+        },
+      });
+    },
+
+    // Rename or re-date a folder. Only the fields you pass change.
+    update: (id, { name, description, startDate, endDate } = {}) => {
+      return request("PATCH", `/folders/${encodeURIComponent(id)}`, {
+        body: {
+          name,
+          description,
+          start_date: startDate,
+          end_date: endDate,
+        },
+      });
+    },
+
+    // Remove the folder. The campaigns inside are not deleted — they
+    // move back to ungrouped, and the response says how many.
+    remove: (id) => {
+      return request("DELETE", `/folders/${encodeURIComponent(id)}`);
+    },
+
+    // File a campaign into a folder. destinationId is a campaign (the
+    // destination behind a set of links), not a single link. Pass null
+    // as folderId to un-file it.
+    assign: (destinationId, folderId) => {
+      return request("POST", "/folders/assign", {
+        body: {
+          destination_id: destinationId,
+          folder_id: folderId,
+        },
+      });
+    },
+  };
+}

package/src/sdk/resources/keys.js

@@ -0,0 +1,28 @@
+export function keys(request) {
+  return {
+    // The workspace's API keys: prefixes and metadata only. Revoked keys
+    // are hidden unless you ask for them.
+    list: ({ includeRevoked } = {}) => {
+      const params = new URLSearchParams();
+      if (includeRevoked) params.set("include", "revoked");
+      const qs = params.toString();
+      return request("GET", qs ? `/keys?${qs}` : "/keys");
+    },
+
+    // Mint a key. scope is "secret" (server-side) or "public" (safe in a
+    // browser). The plaintext key comes back ONCE, as `secret` — it is
+    // never stored, so a lost key is re-issued, never recovered.
+    create: ({ scope, label } = {}) => {
+      return request("POST", "/keys", {
+        body: { scope, label },
+      });
+    },
+
+    // Revoke a key. The row stays so last_used_at survives for the audit
+    // trail. Revoking an already-revoked key succeeds. A key may revoke
+    // itself, and the next request with it gets a 401.
+    revoke: (id) => {
+      return request("DELETE", `/keys/${encodeURIComponent(id)}`);
+    },
+  };
+}

package/src/sdk/resources/links.js

@@ -0,0 +1,131 @@
+export function links(request) {
+  return {
+    // Performance per link for a window: days (default 30) or from/to.
+    // withSettings attaches each link's own record (expiry, password…).
+    list: ({ days, from, to, limit, withSettings } = {}) => {
+      const params = new URLSearchParams();
+      if (days) params.set("days", String(days));
+      if (from) params.set("from", from);
+      if (to) params.set("to", to);
+      if (limit) params.set("limit", String(limit));
+      if (withSettings) params.set("include", "settings");
+      const qs = params.toString();
+      return request("GET", qs ? `/links?${qs}` : "/links");
+    },
+
+    // The links themselves, newest first, with no window. To page, pass
+    // the next_cursor the previous call returned.
+    records: ({ limit, cursor, channel, destinationId, q } = {}) => {
+      const params = new URLSearchParams({ view: "records" });
+      if (limit) params.set("limit", String(limit));
+      if (cursor) params.set("cursor", cursor);
+      if (channel) params.set("channel", channel);
+      if (destinationId) params.set("destination_id", destinationId);
+      if (q) params.set("q", q);
+      return request("GET", `/links?${params}`);
+    },
+
+    // One link, by id, slug or short code.
+    get: (idOrSlug) => {
+      return request("GET", `/links/${encodeURIComponent(idOrSlug)}`);
+    },
+
+    // Create a campaign: one destination plus a link per channel. Pass
+    // channel: "email", channels: ["email", "x"], or smart: true.
+    create: (
+      url,
+      name,
+      {
+        channel,
+        channels,
+        smart,
+        campaign,
+        slug,
+        tags,
+        targeting,
+        expiresAt,
+        maxClicks,
+        expiredRedirectUrl,
+        password,
+        retargeting,
+        folderId,
+        external,
+      } = {}
+    ) => {
+      return request("POST", "/links", {
+        body: {
+          url,
+          name,
+          channel,
+          channels,
+          smart,
+          campaign,
+          slug,
+          tags,
+          targeting,
+          expires_at: expiresAt,
+          max_clicks: maxClicks,
+          expired_redirect_url: expiredRedirectUrl,
+          password,
+          retargeting,
+          folder_id: folderId,
+          external,
+        },
+      });
+    },
+
+    // Edit one link. Only the fields you pass change.
+    update: (
+      id,
+      {
+        slug,
+        utmCampaign,
+        utmTerm,
+        utmContent,
+        targeting,
+        expiresAt,
+        maxClicks,
+        expiredRedirectUrl,
+        password,
+        retargeting,
+      } = {}
+    ) => {
+      return request("PATCH", `/links/${encodeURIComponent(id)}`, {
+        body: {
+          slug,
+          utm_campaign: utmCampaign,
+          utm_term: utmTerm,
+          utm_content: utmContent,
+          targeting,
+          expires_at: expiresAt,
+          max_clicks: maxClicks,
+          expired_redirect_url: expiredRedirectUrl,
+          password,
+          retargeting,
+        },
+      });
+    },
+
+    // Delete one link. The campaign and its other channels stay.
+    remove: (id) => {
+      return request("DELETE", `/links/${encodeURIComponent(id)}`);
+    },
+
+    // Up to 500 links in one call, each row { url, name, channel, ... }.
+    // A bad row is reported in the response rather than thrown, so read
+    // result.rows instead of only catching errors.
+    createMany: (rows) => {
+      return request("POST", "/links/bulk", { body: { rows } });
+    },
+
+    // The link's QR code as SVG. It comes back as text rather than JSON,
+    // so it needs a client that can read plain-text responses.
+    qr: (idOrSlug, { size } = {}) => {
+      const params = new URLSearchParams();
+      if (size) params.set("size", String(size));
+      const qs = params.toString();
+      const path = `/links/${encodeURIComponent(idOrSlug)}/qr`;
+      return request("GET", qs ? `${path}?${qs}` : path);
+    },
+  };
+}

package/src/sdk/resources/orders.js

@@ -0,0 +1,15 @@
+export function orders(request) {
+  return {
+    // Synced purchases, newest first. On a free workspace amount is null
+    // and revenue_visible says so — revenue figures are hidden there.
+    list: ({ limit, cursor, status, email } = {}) => {
+      const params = new URLSearchParams();
+      if (limit) params.set("limit", String(limit));
+      if (cursor) params.set("cursor", cursor);
+      if (status) params.set("status", status);
+      if (email) params.set("email", email);
+      const qs = params.toString();
+      return request("GET", qs ? `/orders?${qs}` : "/orders");
+    },
+  };
+}

package/src/sdk/resources/partners.js

@@ -0,0 +1,37 @@
+export function partners(request) {
+  return {
+    // Affiliates across every program, or one program's.
+    // status: pending | approved | rejected | banned | archived.
+    list: ({ programId, status } = {}) => {
+      const params = new URLSearchParams();
+      if (programId) params.set("program_id", programId);
+      if (status) params.set("status", status);
+      const qs = params.toString();
+      return request("GET", qs ? `/partners?${qs}` : "/partners");
+    },
+
+    // Approve, reject, ban or archive an affiliate. Unlike the dashboard
+    // this sends no email, so re-running it doesn't mail anyone twice.
+    setStatus: (programId, partnerId, status) => {
+      return request("POST", "/partners/status", {
+        body: {
+          program_id: programId,
+          partner_id: partnerId,
+          status,
+        },
+      });
+    },
+
+    // Move an affiliate into a group. Pass null as groupId to drop them
+    // back to the program's own terms.
+    setGroup: (programId, partnerId, groupId) => {
+      return request("POST", "/partners/group", {
+        body: {
+          program_id: programId,
+          partner_id: partnerId,
+          group_id: groupId,
+        },
+      });
+    },
+  };
+}

package/src/sdk/resources/payouts.js

@@ -0,0 +1,22 @@
+export function payouts(request) {
+  return {
+    // Payout batches with open and all-time totals.
+    list: ({ status, limit } = {}) => {
+      const params = new URLSearchParams();
+      if (status) params.set("status", status);
+      if (limit) params.set("limit", String(limit));
+      const qs = params.toString();
+      return request("GET", qs ? `/payouts?${qs}` : "/payouts");
+    },
+
+    // Settle a batch you paid off-platform; reference is the rail's own
+    // id (a PayPal batch, a Wise transfer). The commissions it covers
+    // close out with it. Creating a batch stays dashboard-only, because
+    // it applies payout floors and fees that shouldn't live in two places.
+    settle: (id, { reference } = {}) => {
+      return request("PATCH", `/payouts/${encodeURIComponent(id)}`, {
+        body: { reference },
+      });
+    },
+  };
+}

package/src/sdk/resources/programs.js

@@ -0,0 +1,55 @@
+export function programs(request) {
+  return {
+    // The workspace's affiliate programs.
+    list: ({ includeArchived } = {}) => {
+      const params = new URLSearchParams();
+      if (includeArchived) params.set("include", "archived");
+      const qs = params.toString();
+      return request("GET", qs ? `/programs?${qs}` : "/programs");
+    },
+
+    // One program.
+    get: (id) => {
+      return request("GET", `/programs/${encodeURIComponent(id)}`);
+    },
+
+    // Change terms or status. Only the fields you pass change, because
+    // these values decide what affiliates are owed and an omitted field
+    // must never silently reset a rate. commissionRate is a fraction
+    // between 0 and 1 for percent programs, so 0.3 means 30%.
+    update: (
+      id,
+      {
+        name,
+        landingUrl,
+        commissionType,
+        commissionRate,
+        recurringMonths,
+        cookieWindowDays,
+        minPayout,
+        autoApprove,
+        status,
+      } = {}
+    ) => {
+      return request("PATCH", `/programs/${encodeURIComponent(id)}`, {
+        body: {
+          name,
+          landing_url: landingUrl,
+          commission_type: commissionType,
+          commission_rate: commissionRate,
+          recurring_months: recurringMonths,
+          cookie_window_days: cookieWindowDays,
+          min_payout: minPayout,
+          auto_approve: autoApprove,
+          status,
+        },
+      });
+    },
+
+    // The program's affiliate tiers. Each group shows its own overrides
+    // and a resolved block with the terms an affiliate in it really gets.
+    groups: (id) => {
+      return request("GET", `/programs/${encodeURIComponent(id)}/groups`);
+    },
+  };
+}

package/src/sdk/resources/referrals.js

@@ -0,0 +1,83 @@
+export function referrals(request) {
+  return {
+    // A user opts into your referral program. tier: "free" | "paid".
+    enroll: (externalUserId, email, tier, { name, programId } = {}) => {
+      return request("POST", "/referrals/enroll", {
+        body: {
+          external_user_id: externalUserId,
+          email,
+          tier,
+          name,
+          program_id: programId,
+        },
+      });
+    },
+
+    // A new user signed up. Pass one of refCode, vid or referrerExternalUserId
+    // so we know who referred them.
+    reportSignup: (
+      newUserExternalUserId,
+      { refCode, vid, referrerExternalUserId, email } = {}
+    ) => {
+      return request("POST", "/referrals/report-signup", {
+        body: {
+          new_user_external_user_id: newUserExternalUserId,
+          ref_code: refCode,
+          _vid: vid,
+          referrer_external_user_id: referrerExternalUserId,
+          email,
+        },
+      });
+    },
+
+    // A user paid. amount is in major units (49.99). Needs a secret key.
+    reportPurchase: (
+      externalUserId,
+      orderId,
+      amount,
+      { currency, email, recurring, ts } = {}
+    ) => {
+      return request("POST", "/referrals/report-purchase", {
+        body: {
+          external_user_id: externalUserId,
+          order_id: orderId,
+          amount,
+          currency,
+          email,
+          recurring,
+          ts,
+        },
+      });
+    },
+
+    // A user's referral link, KPIs and earnings. days: 7 to 90.
+    stats: (externalUserId, { email, tier, days } = {}) => {
+      const params = new URLSearchParams({ external_user_id: externalUserId });
+      if (email) params.set("email", email);
+      if (tier) params.set("tier", tier);
+      if (days) params.set("days", String(days));
+      return request("GET", `/referrals/stats?${params}`);
+    },
+
+    // Where an affiliate gets paid. PayPal only for now.
+    setPayoutMethod: (externalUserId, paypalEmail) => {
+      return request("POST", "/referrals/payout-method", {
+        body: {
+          external_user_id: externalUserId,
+          method: "paypal",
+          paypal_email: paypalEmail,
+        },
+      });
+    },
+
+    // Switch between earning credits ("referrer") and cash ("affiliate").
+    setRewardMode: (externalUserId, mode) => {
+      return request("POST", "/referrals/reward-mode", {
+        body: {
+          external_user_id: externalUserId,
+          mode,
+        },
+      });
+    },
+  };
+}

package/src/sdk/resources/retargeting.js

@@ -0,0 +1,23 @@
+export function retargeting(request) {
+  return {
+    // Your ad-pixel library, plus the catalogue of providers and the id
+    // shape each one expects.
+    list: () => {
+      return request("GET", "/retargeting");
+    },
+
+    // Store a provider's pixel, e.g. set("meta", "1234567890"). The id
+    // must match that provider's shape — that check is what keeps an
+    // arbitrary string out of the loader snippet the consent page runs.
+    set: (provider, pixelId) => {
+      return request("PUT", `/retargeting/${encodeURIComponent(provider)}`, {
+        body: { pixel_id: pixelId },
+      });
+    },
+
+    // Drop that provider's pixel.
+    remove: (provider) => {
+      return request("DELETE", `/retargeting/${encodeURIComponent(provider)}`);
+    },
+  };
+}

package/src/sdk/resources/revenue.js

@@ -0,0 +1,53 @@
+export function revenue(request) {
+  return {
+    // Connected billing providers. Credentials are never returned: each
+    // row only reports which fields are set.
+    connections: () => {
+      return request("GET", "/revenue/connections");
+    },
+
+    // One connection, without credentials.
+    connection: (id) => {
+      return request("GET", `/revenue/connections/${encodeURIComponent(id)}`);
+    },
+
+    // What can be connected, and which credential fields each provider
+    // needs. Stripe is absent by design — its key lives on the workspace.
+    providers: () => {
+      return request("GET", "/revenue/providers");
+    },
+
+    // Connect a provider, e.g. connect("paddle", { api_key: "..." }).
+    // The credentials are proved with one live read before anything is
+    // stored, so a bad key fails here instead of as an empty revenue
+    // column later. Re-connecting the same provider replaces the old row.
+    connect: (provider, credentials, { sandbox } = {}) => {
+      return request("POST", "/revenue/connections", {
+        body: { provider, credentials, sandbox },
+      });
+    },
+
+    // Set or clear the signing secret for instant webhook sync. With it
+    // set, sales arrive in seconds; without it the connection is
+    // cron-only. Pass null to clear.
+    setWebhookSecret: (id, webhookSecret) => {
+      return request("PATCH", `/revenue/connections/${encodeURIComponent(id)}`, {
+        body: { webhook_secret: webhookSecret },
+      });
+    },
+
+    // Disconnect a provider. Past orders are kept.
+    disconnect: (id) => {
+      return request("DELETE", `/revenue/connections/${encodeURIComponent(id)}`);
+    },
+
+    // Pull charges now. Omit connectionId to sync every connection plus
+    // Stripe. One row per provider comes back; a provider that fails
+    // reports its error without stopping the others.
+    sync: ({ connectionId } = {}) => {
+      return request("POST", "/revenue/sync", {
+        body: { connection_id: connectionId },
+      });
+    },
+  };
+}

package/src/sdk/resources/settings.js

@@ -0,0 +1,29 @@
+export function settings(request) {
+  return {
+    // Every transactional email, with whether it is on for this
+    // workspace. is_default: true means no preference is stored and the
+    // catalogue's own default applies.
+    notifications: () => {
+      return request("GET", "/settings/notifications");
+    },
+
+    // Turn one email on or off, e.g. setNotification("sale.created", false).
+    setNotification: (key, enabled) => {
+      return request("PATCH", "/settings/notifications", {
+        body: { key, enabled },
+      });
+    },
+
+    // The white-label settings affiliates see.
+    branding: () => {
+      return request("GET", "/settings/branding");
+    },
+
+    // Change the accent color or logo. Only the fields you pass change.
+    updateBranding: ({ color, logoUrl } = {}) => {
+      return request("PATCH", "/settings/branding", {
+        body: { color, logo_url: logoUrl },
+      });
+    },
+  };
+}

package/src/sdk/resources/visitors.js

@@ -0,0 +1,25 @@
+export function visitors(request) {
+  return {
+    // Visitors, most recently seen first. To page, pass the previous
+    // call's next_cursor as cursor.
+    list: ({ limit, cursor, email } = {}) => {
+      const params = new URLSearchParams();
+      if (limit) params.set("limit", String(limit));
+      if (cursor) params.set("cursor", cursor);
+      if (email) params.set("email", email);
+      const qs = params.toString();
+      return request("GET", qs ? `/visitors?${qs}` : "/visitors");
+    },
+
+    // One visitor. Their timeline is journey() below.
+    get: (id) => {
+      return request("GET", `/visitors/${encodeURIComponent(id)}`);
+    },
+
+    // Every click, identify event and order for one visitor, oldest
+    // first. id is the visitor_id that clicks carry.
+    journey: (id) => {
+      return request("GET", `/visitors/${encodeURIComponent(id)}/journey`);
+    },
+  };
+}

package/src/sdk/resources/webhooks.js

@@ -0,0 +1,41 @@
+export function webhooks(request) {
+  return {
+    // The workspace's outbound endpoints. The signing secret is never
+    // included here — it is shown once, when the endpoint is created.
+    list: () => {
+      return request("GET", "/webhooks");
+    },
+
+    // The catalogue of events an endpoint can subscribe to.
+    events: () => {
+      return request("GET", "/webhooks/events");
+    },
+
+    // One endpoint, without its secret.
+    get: (id) => {
+      return request("GET", `/webhooks/${encodeURIComponent(id)}`);
+    },
+
+    // Create an endpoint. url must be https. events is a list, e.g.
+    // ["sale.created"]. The response carries the signing secret ONCE —
+    // store it then, because no later read returns it.
+    create: (url, events) => {
+      return request("POST", "/webhooks", {
+        body: { url, events },
+      });
+    },
+
+    // Change the URL, the event list, or pause it with active: false.
+    // Only the fields you pass change.
+    update: (id, { url, events, active } = {}) => {
+      return request("PATCH", `/webhooks/${encodeURIComponent(id)}`, {
+        body: { url, events, active },
+      });
+    },
+
+    // Remove the endpoint. Deliveries stop at once.
+    remove: (id) => {
+      return request("DELETE", `/webhooks/${encodeURIComponent(id)}`);
+    },
+  };
+}