Implement Tradedoubler affiliate adapter (#319)

Author: op-simoneromeo

packages/affiliates/tradedoubler/src/index.test.ts

@@ -1,4 +1,135 @@
 import { smokeTest } from '@profullstack/sh1pt-core/testing';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import adapter from './index.js';
 
 smokeTest(adapter, { idPrefix: 'affiliate' });
+
+const ctx = (secrets: Record<string, string> = { TRADEDOUBLER_API_TOKEN: 'td-token' }) => ({
+  secret: (key: string) => secrets[key],
+  log: () => {},
+});
+
+describe('Tradedoubler affiliate adapter', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('requires a Products API token before making requests', async () => {
+    await expect(adapter.connect(ctx({}), {})).rejects.toThrow('TRADEDOUBLER_API_TOKEN not in vault');
+  });
+
+  it('probes product feeds during connect and preserves configured publisher id', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse({
+      feeds: [
+        {
+          feedId: 19750,
+          currencyISOCode: 'GBP',
+          programs: [{ programId: 41305, name: 'Merchant UK' }],
+        },
+      ],
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(adapter.connect(ctx(), { accountId: '2038177' })).resolves.toEqual({
+      accountId: '2038177',
+    });
+    const [url, request] = fetchMock.mock.calls[0]!;
+    expect(String(url)).toBe('https://api.tradedoubler.com/1.0/productFeeds.json?token=td-token');
+    expect(request.headers.accept).toBe('application/json');
+  });
+
+  it('can read publisher id from the vault when config omits accountId', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ feeds: [] })));
+
+    await expect(adapter.connect(ctx({
+      TRADEDOUBLER_API_TOKEN: 'td-token',
+      TRADEDOUBLER_PUBLISHER_ID: '2038177',
+    }), {})).resolves.toEqual({
+      accountId: '2038177',
+    });
+  });
+
+  it('builds a direct Tradedoubler tracking URL with EPI values', async () => {
+    await expect(adapter.getTrackingLink?.(
+      ctx(),
+      '41305',
+      'https://merchant.example/path?q=coffee grinder',
+      {
+        accountId: '2038177',
+        adId: '2468',
+        clickRef: 'launch-1',
+        clickRef2: 'newsletter',
+      },
+    )).resolves.toEqual({
+      url: 'https://clk.tradedoubler.com/click?a(2038177)p(41305)g(2468)epi(launch-1)epi2(newsletter)url(https%3A%2F%2Fmerchant.example%2Fpath%3Fq%3Dcoffee%20grinder)',
+    });
+  });
+
+  it('requires publisher id and an absolute destination URL for tracking links', async () => {
+    await expect(adapter.getTrackingLink?.(ctx(), '41305', 'https://merchant.example', {}))
+      .rejects.toThrow('publisher id is required');
+    await expect(adapter.getTrackingLink?.(ctx(), '41305', '/relative', { accountId: '2038177' }))
+      .rejects.toThrow('must be an absolute URL');
+  });
+
+  it('uses matrix syntax to scope product-feed stats by program', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse({
+      feeds: [
+        {
+          feedId: 19750,
+          currencyISOCode: 'GBP',
+          programs: [{ programId: 41305, name: 'Merchant UK' }],
+        },
+        {
+          feedId: 20782,
+          currencyISOCode: 'EUR',
+          programs: [{ programId: 99999, name: 'Other Merchant' }],
+        },
+      ],
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(adapter.stats?.(ctx(), '41305', {})).resolves.toEqual({
+      publishers: 1,
+      clicks: 0,
+      conversions: 0,
+      revenue: 0,
+      commissionsPaid: 0,
+      currency: 'GBP',
+    });
+    const [url] = fetchMock.mock.calls[0]!;
+    expect(String(url)).toBe(
+      'https://api.tradedoubler.com/1.0/productFeeds.json;programId=41305?token=td-token',
+    );
+  });
+
+  it('falls back to configured currency when no matching feeds are returned', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ feeds: [] })));
+
+    await expect(adapter.stats?.(ctx(), '41305', { currency: 'SEK' })).resolves.toEqual({
+      publishers: 0,
+      clicks: 0,
+      conversions: 0,
+      revenue: 0,
+      commissionsPaid: 0,
+      currency: 'SEK',
+    });
+  });
+
+  it('redacts the API token from provider errors', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: false,
+      status: 401,
+      text: async () => 'token td-token is invalid',
+    }));
+
+    await expect(adapter.connect(ctx(), {})).rejects.toThrow('Tradedoubler 401: token [redacted] is invalid');
+  });
+});
+
+function jsonResponse(body: unknown) {
+  return {
+    ok: true,
+    json: async () => body,
+  };
+}

packages/affiliates/tradedoubler/src/index.ts

@@ -1,46 +1,196 @@
-import { defineAffiliate, tokenSetup } from '@profullstack/sh1pt-core';
+import { defineAffiliate, tokenSetup, type AffiliateConnectContext } from '@profullstack/sh1pt-core';
 
 interface Config {
   accountId?: string;
+  adId?: string;
+  baseUrl?: string;
+  clickRef?: string;
+  clickRef2?: string;
+  currency?: string;
+  trackingBaseUrl?: string;
 }
 
+const DEFAULT_API_BASE = 'https://api.tradedoubler.com';
+const DEFAULT_TRACKING_BASE = 'https://clk.tradedoubler.com';
+const PRODUCT_TOKEN_KEY = 'TRADEDOUBLER_API_TOKEN';
+const PUBLISHER_ID_KEY = 'TRADEDOUBLER_PUBLISHER_ID';
+
 export default defineAffiliate<Config>({
-  id: "affiliate-tradedoubler",
-  label: "Tradedoubler",
-  side: "both",
+  id: 'affiliate-tradedoubler',
+  label: 'Tradedoubler',
+  side: 'publisher',
 
   async connect(ctx, config) {
-    const token = ctx.secret("TRADEDOUBLER_API_TOKEN");
-    if (!token) throw new Error("TRADEDOUBLER_API_TOKEN not in vault — run `sh1pt promote affiliates setup`");
-    return { accountId: config.accountId ?? "affiliate-tradedoubler" };
-  },
-
-  async createProgram(ctx, program) {
-    ctx.log(`[stub] ${"affiliate-tradedoubler"} createProgram name=${program.name} commission=${program.commissionRate}${program.commissionType === 'percentage' ? '%' : ''}`);
+    const feeds = await tradedoublerGet(ctx, config, '/1.0/productFeeds.json');
+    const firstFeed = collectItems(feeds, ['feeds'])[0];
     return {
-      programId: `stub-${Date.now()}`,
-      marketplaceUrl: "https://www.tradedoubler.com",
+      accountId:
+        config.accountId
+        ?? ctx.secret(PUBLISHER_ID_KEY)
+        ?? stringField(firstFeed, ['siteId', 'publisherId'])
+        ?? 'affiliate-tradedoubler',
     };
   },
 
-  async getTrackingLink(ctx, programId, destinationUrl) {
-    ctx.log(`[stub] ${"affiliate-tradedoubler"} getTrackingLink program=${programId}`);
-    return { url: destinationUrl };
+  async getTrackingLink(ctx, programId, destinationUrl, config) {
+    ctx.log(`tradedoubler tracking link · program=${programId}`);
+    const publisherId = config.accountId ?? ctx.secret(PUBLISHER_ID_KEY);
+    if (!publisherId) throw new Error('Tradedoubler accountId / publisher id is required');
+    if (!destinationUrl) throw new Error('Tradedoubler destinationUrl is required');
+    try {
+      new URL(destinationUrl);
+    } catch {
+      throw new Error('Tradedoubler destinationUrl must be an absolute URL');
+    }
+    const parts = [
+      matrixPart('a', publisherId),
+      matrixPart('p', programId),
+    ];
+    if (config.adId) parts.push(matrixPart('g', config.adId));
+    if (config.clickRef) parts.push(matrixPart('epi', config.clickRef));
+    if (config.clickRef2) parts.push(matrixPart('epi2', config.clickRef2));
+    parts.push(matrixPart('url', destinationUrl, true));
+    return {
+      url: `${trimSlash(config.trackingBaseUrl ?? DEFAULT_TRACKING_BASE)}/click?${parts.join('')}`,
+    };
   },
 
-  async stats(ctx, programId) {
-    ctx.log(`[stub] ${"affiliate-tradedoubler"} stats program=${programId}`);
-    return { publishers: 0, clicks: 0, conversions: 0, revenue: 0, commissionsPaid: 0, currency: 'USD' };
+  async stats(ctx, programId, config) {
+    ctx.log(`tradedoubler product-feed stats · program=${programId}`);
+    const data = await tradedoublerGet(ctx, config, '/1.0/productFeeds.json', { programId });
+    const feeds = collectItems(data, ['feeds']);
+    const matchingFeeds = feeds.filter((feed) => feedMatchesProgram(feed, programId));
+    const scopedFeeds = matchingFeeds.length > 0 ? matchingFeeds : feeds;
+    return {
+      publishers: scopedFeeds.length > 0 ? 1 : 0,
+      clicks: 0,
+      conversions: 0,
+      revenue: 0,
+      commissionsPaid: 0,
+      currency:
+        firstString(scopedFeeds, ['currencyISOCode', 'currency'])
+        ?? config.currency
+        ?? 'EUR',
+    };
   },
 
   setup: tokenSetup<Config>({
-    secretKey: "TRADEDOUBLER_API_TOKEN",
-    label: "Tradedoubler",
-    vendorDocUrl: "https://www.tradedoubler.com",
+    secretKey: PRODUCT_TOKEN_KEY,
+    label: 'Tradedoubler',
+    vendorDocUrl: 'https://dev.tradedoubler.com/products/publisher/',
     steps: [
-      "Log into tradedoubler.com → My Account → API",
-      "Generate a token",
-      "Paste below",
+      'Open the Tradedoubler publisher interface and create a Products API token',
+      'Paste the Products API token below',
+      'Optionally store TRADEDOUBLER_PUBLISHER_ID or set accountId for direct click tracking links',
+    ],
+    fields: [
+      {
+        key: 'accountId',
+        message: 'Optional Tradedoubler publisher id used in click tracking URLs:',
+      },
+      {
+        key: 'clickRef',
+        message: 'Optional EPI value to attach to tracking links:',
+      },
+      {
+        key: 'clickRef2',
+        message: 'Optional EPI2 value to attach to tracking links:',
+      },
     ],
   }),
 });
+
+type TdRecord = Record<string, unknown>;
+
+async function tradedoublerGet(
+  ctx: AffiliateConnectContext,
+  config: Config,
+  path: string,
+  matrix: Record<string, string | number | undefined> = {},
+): Promise<unknown> {
+  const token = ctx.secret(PRODUCT_TOKEN_KEY);
+  if (!token) throw new Error(`${PRODUCT_TOKEN_KEY} not in vault`);
+  const url = new URL(`${trimSlash(config.baseUrl ?? DEFAULT_API_BASE)}${withMatrix(path, matrix)}`);
+  url.searchParams.set('token', token);
+  const res = await fetch(url, {
+    headers: {
+      accept: 'application/json',
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Tradedoubler ${res.status}: ${redact(text, token).slice(0, 200)}`);
+  }
+  return res.json();
+}
+
+function withMatrix(path: string, matrix: Record<string, string | number | undefined>): string {
+  const suffix = Object.entries(matrix)
+    .filter(([, value]) => value !== undefined && String(value).length > 0)
+    .map(([key, value]) => `;${key}=${encodeURIComponent(String(value))}`)
+    .join('');
+  return `${path}${suffix}`;
+}
+
+function matrixPart(key: string, value: string, encodeFullUrl = false): string {
+  return `${key}(${encodeFullUrl ? encodeURIComponent(value) : encodeMatrixValue(value)})`;
+}
+
+function encodeMatrixValue(value: string): string {
+  return encodeURIComponent(value).replace(/%2F/gi, '/');
+}
+
+function feedMatchesProgram(feed: TdRecord, programId: string): boolean {
+  if (stringField(feed, ['programId', 'id']) === programId) return true;
+  const programs = feed.programs;
+  if (!Array.isArray(programs)) return false;
+  return programs
+    .filter(isRecord)
+    .some((program) => stringField(program, ['programId', 'id']) === programId);
+}
+
+function collectItems(data: unknown, keys: string[]): TdRecord[] {
+  if (Array.isArray(data)) return data.filter(isRecord);
+  if (!isRecord(data)) return [];
+  for (const key of keys) {
+    const value = data[key];
+    if (Array.isArray(value)) return value.filter(isRecord);
+  }
+  if (Array.isArray(data.items)) return data.items.filter(isRecord);
+  if (Array.isArray(data.data)) return data.data.filter(isRecord);
+  return [data];
+}
+
+function isRecord(value: unknown): value is TdRecord {
+  return typeof value === 'object' && value !== null;
+}
+
+function stringField(item: TdRecord | undefined, keys: string[]): string | undefined {
+  if (!item) return undefined;
+  for (const key of keys) {
+    const value = item[key];
+    if (typeof value === 'string' && value.length > 0) return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  }
+  return undefined;
+}
+
+function firstString(items: TdRecord[], keys: string[]): string | undefined {
+  for (const item of items) {
+    const value = stringField(item, keys);
+    if (value) return value;
+  }
+  return undefined;
+}
+
+function redact(text: string, ...values: Array<string | undefined>): string {
+  let redacted = text;
+  for (const value of values) {
+    if (value) redacted = redacted.split(value).join('[redacted]');
+  }
+  return redacted;
+}
+
+function trimSlash(value: string): string {
+  return value.replace(/\/+$/, '');
+}