@openpartner/sdk 0.1.0 → 0.2.0

package/dist/browser.js

@@ -48,15 +48,22 @@ var DEFAULTS = {
   cookieName: "_cref",
   queryParam: "cref",
   storageKey: "openpartner:cref",
+  stripe: true,
+  referralCookie: false,
   onError: (err) => {
     console.warn("[openpartner] identify failed", err);
   }
 };
+var STRIPE_REFERENCE_RE = /^[A-Za-z0-9_-]{1,200}$/;
+var STRIPE_EMBED_SELECTOR = "stripe-pricing-table, stripe-buy-button";
 var OpenPartner = class _OpenPartner {
   constructor(config) {
     __publicField(this, "config");
+    __publicField(this, "observer", null);
     this.config = { ...DEFAULTS, ...config };
     this.captureCref();
+    this.writeReferralCookie();
+    if (this.config.stripe !== false) this.watchStripe();
   }
   static init(config) {
     return new _OpenPartner(config);
@@ -86,6 +93,84 @@ var OpenPartner = class _OpenPartner {
     if (typeof localStorage === "undefined") return;
     localStorage.removeItem(this.config.storageKey);
   }
+  /**
+   * Add the referral to every Stripe Payment Link and Pricing Table / Buy
+   * Button embed under `root` that doesn't carry a reference already.
+   * Runs on its own at init and for anything added later; call it yourself
+   * only if you build Stripe elements inside a shadow root. Returns how
+   * many it changed.
+   */
+  linkStripe(root = document) {
+    const referral = this.getReferral();
+    if (!referral || !STRIPE_REFERENCE_RE.test(referral) || typeof document === "undefined") return 0;
+    const hosts = /* @__PURE__ */ new Set(["buy.stripe.com", ...this.stripeLinkHosts()]);
+    let changed = 0;
+    const anchors = [];
+    if (root instanceof HTMLAnchorElement) anchors.push(root);
+    anchors.push(...Array.from(root.querySelectorAll("a[href]")));
+    for (const a of anchors) {
+      let url;
+      try {
+        url = new URL(a.href);
+      } catch {
+        continue;
+      }
+      if (!hosts.has(url.hostname.toLowerCase()) || url.searchParams.has("client_reference_id")) continue;
+      url.searchParams.set("client_reference_id", referral);
+      a.href = url.toString();
+      changed += 1;
+    }
+    const embeds = [];
+    if (root instanceof Element && root.matches(STRIPE_EMBED_SELECTOR)) embeds.push(root);
+    embeds.push(...Array.from(root.querySelectorAll(STRIPE_EMBED_SELECTOR)));
+    for (const el of embeds) {
+      if (el.hasAttribute("client-reference-id")) continue;
+      el.setAttribute("client-reference-id", referral);
+      changed += 1;
+    }
+    return changed;
+  }
+  /** Stop watching the page for new Stripe links and embeds. */
+  stopLinkingStripe() {
+    this.observer?.disconnect();
+    this.observer = null;
+  }
+  stripeLinkHosts() {
+    const cfg = this.config.stripe;
+    return typeof cfg === "object" && cfg.linkHosts ? cfg.linkHosts.map((h) => h.trim().toLowerCase()).filter(Boolean) : [];
+  }
+  /**
+   * Link what's on the page now, then anything added or re-pointed later
+   * (SPAs, Stripe embeds mounted on demand). Only with a referral: a visitor
+   * who didn't come from a partner link costs nothing.
+   *
+   * Pricing Table and Buy Button embeds read client-reference-id when
+   * Stripe's script renders them, so the script tag belongs in <head>,
+   * ahead of the embed: the observer then sets the attribute as the
+   * element is parsed, before Stripe upgrades it.
+   */
+  watchStripe() {
+    if (typeof document === "undefined" || !this.getReferral()) return;
+    this.linkStripe(document);
+    if (typeof MutationObserver === "undefined") return;
+    this.observer = new MutationObserver((records) => {
+      for (const record of records) {
+        if (record.type === "attributes") {
+          if (record.target instanceof HTMLAnchorElement) this.linkStripe(record.target);
+          continue;
+        }
+        for (const node of Array.from(record.addedNodes)) {
+          if (node instanceof Element) this.linkStripe(node);
+        }
+      }
+    });
+    this.observer.observe(document.documentElement, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["href"]
+    });
+  }
   /**
    * Capture the cref from query string or cookie and stash in
    * localStorage. Runs on init so the value survives SPA navigations,
@@ -104,6 +189,19 @@ var OpenPartner = class _OpenPartner {
       localStorage.setItem(this.config.storageKey, cookieCref);
     }
   }
+  /** Mirror the referral into the brand's own first-party cookie (when
+   *  configured), refreshed on every page load that has one. */
+  writeReferralCookie() {
+    const cfg = this.config.referralCookie;
+    if (!cfg || typeof document === "undefined") return;
+    const referral = this.getReferral();
+    if (!referral || !STRIPE_REFERENCE_RE.test(referral)) return;
+    const name = cfg.name ?? "op_ref";
+    const maxAge = Math.round((cfg.days ?? 90) * 86400);
+    const secure = typeof location !== "undefined" && location.protocol === "https:" ? "; Secure" : "";
+    const domain = cfg.domain ? `; Domain=${cfg.domain}` : "";
+    document.cookie = `${name}=${encodeURIComponent(referral)}; Max-Age=${maxAge}; Path=/; SameSite=Lax${domain}${secure}`;
+  }
   readCookie(name) {
     if (typeof document === "undefined") return null;
     const match = document.cookie.match(new RegExp(`(^|; )${name}=([^;]+)`));

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/shared.ts","../src/browser.ts"],"sourcesContent":["/**\n * Shared types + error class for both the browser and server entry\n * points.\n *\n * Keeping these in their own module means browser imports won't drag in\n * `fetch` polyfills or server-only code, and server imports won't touch\n * anything that references `window` or `document`.\n */\n\nexport class OpenPartnerError extends Error {\n  constructor(\n    message: string,\n    public readonly status: number,\n    public readonly code?: string,\n    public readonly detail?: unknown,\n  ) {\n    super(message);\n    this.name = 'OpenPartnerError';\n  }\n}\n\nexport interface IdentifyResponse {\n  ok: boolean;\n  identityId: string | null;\n  firstStitch: boolean;\n  backfilledAttributions?: number;\n}\n\nexport interface EventAttribution {\n  status: 'attributed' | 'no_identity' | 'no_click' | 'outside_window' | 'already_attributed';\n  model?: 'last_click' | 'first_click' | 'linear' | 'position';\n  touches?: Array<{\n    clickId: string;\n    partnerId: string;\n    weight: number;\n    attributionId: string;\n    commissionId?: string;\n  }>;\n}\n\nexport interface EventResponse {\n  ok: boolean;\n  eventId: string;\n  attribution: EventAttribution;\n}\n\n/**\n * Small fetch helper used by both entries. Normalizes non-2xx responses\n * into OpenPartnerError so callers can try/catch with a stable shape\n * instead of poking at Response objects themselves.\n */\nexport type JsonRequestInit = Omit<RequestInit, 'body'> & { body?: unknown };\n\nexport async function requestJson<T>(\n  input: string,\n  init: JsonRequestInit = {},\n  fetchImpl: typeof fetch = globalThis.fetch,\n): Promise<T> {\n  const headers = new Headers(init.headers);\n  if (init.body !== undefined && !headers.has('content-type')) {\n    headers.set('content-type', 'application/json');\n  }\n  const res = await fetchImpl(input, {\n    ...init,\n    headers,\n    body:\n      init.body === undefined\n        ? undefined\n        : typeof init.body === 'string'\n          ? init.body\n          : JSON.stringify(init.body),\n  });\n\n  const text = await res.text();\n  let body: unknown = undefined;\n  if (text) {\n    try {\n      body = JSON.parse(text);\n    } catch {\n      body = text;\n    }\n  }\n\n  if (!res.ok) {\n    const errBody = (body ?? {}) as { error?: string; detail?: unknown };\n    throw new OpenPartnerError(\n      errBody.error ?? `${res.status} ${res.statusText}`,\n      res.status,\n      errBody.error,\n      errBody.detail ?? body,\n    );\n  }\n\n  return body as T;\n}\n","/**\n * Browser SDK — runs inside a merchant's web app. Captures the `cref`\n * attribution token from landing-page URLs and the first-party cookie\n * the click router sets, stashes it in localStorage so it survives\n * Safari / ITP cookie expiry and SPA navigations, and stitches to the\n * authenticated user on signup or login.\n *\n * Typical integration:\n *\n *   import { OpenPartner } from '@openpartner/sdk';\n *\n *   const op = OpenPartner.init({ apiUrl: 'https://openpartner.example.com' });\n *\n *   // After login/signup, once you know who the user is:\n *   await op.identify(user.id);\n */\n\nimport { OpenPartnerError, requestJson, type IdentifyResponse } from './shared.js';\n\nexport { OpenPartnerError };\nexport type { IdentifyResponse };\n\nexport interface OpenPartnerConfig {\n  /** Base URL of your OpenPartner API, e.g. \"https://openpartner.example.com\". */\n  apiUrl: string;\n  /** First-party cookie name set by the click router. Default `_cref`. */\n  cookieName?: string;\n  /** Query-string parameter that carries the cref on the landing URL. Default `cref`. */\n  queryParam?: string;\n  /** localStorage key the captured cref is stashed under. Default `openpartner:cref`. */\n  storageKey?: string;\n  /**\n   * Called when identify() fails. Default: log to console. Pass a noop\n   * to suppress entirely or hook into your observability stack.\n   */\n  onError?: (err: unknown) => void;\n}\n\nconst DEFAULTS = {\n  cookieName: '_cref',\n  queryParam: 'cref',\n  storageKey: 'openpartner:cref',\n  onError: (err: unknown) => {\n    console.warn('[openpartner] identify failed', err);\n  },\n};\n\nexport class OpenPartner {\n  private config: Required<OpenPartnerConfig>;\n\n  private constructor(config: OpenPartnerConfig) {\n    this.config = { ...DEFAULTS, ...config } as Required<OpenPartnerConfig>;\n    this.captureCref();\n  }\n\n  static init(config: OpenPartnerConfig): OpenPartner {\n    return new OpenPartner(config);\n  }\n\n  /** The cref we're holding onto, if any. Useful for debugging. */\n  getCref(): string | null {\n    if (typeof localStorage === 'undefined') return null;\n    return localStorage.getItem(this.config.storageKey);\n  }\n\n  /**\n   * Captured referral token for this visitor. Pass to Stripe Checkout\n   * as `client_reference_id` to enable webhook-based attribution\n   * without an explicit identify() call:\n   *\n   *   stripe.checkout.sessions.create({\n   *     client_reference_id: op.getReferral() ?? undefined,\n   *     // ...\n   *   });\n   *\n   * Returns null if the visitor didn't arrive via a partner link.\n   */\n  getReferral(): string | null {\n    return this.getCref();\n  }\n\n  /** Explicitly discard the captured cref. */\n  clear(): void {\n    if (typeof localStorage === 'undefined') return;\n    localStorage.removeItem(this.config.storageKey);\n  }\n\n  /**\n   * Capture the cref from query string or cookie and stash in\n   * localStorage. Runs on init so the value survives SPA navigations,\n   * ITP cookie expiry, and subsequent page loads.\n   */\n  private captureCref(): void {\n    if (typeof window === 'undefined' || typeof localStorage === 'undefined') return;\n\n    const url = new URL(window.location.href);\n    const queryCref = url.searchParams.get(this.config.queryParam);\n\n    if (queryCref) {\n      localStorage.setItem(this.config.storageKey, queryCref);\n      return;\n    }\n\n    const cookieCref = this.readCookie(this.config.cookieName);\n    if (cookieCref && !localStorage.getItem(this.config.storageKey)) {\n      localStorage.setItem(this.config.storageKey, cookieCref);\n    }\n  }\n\n  private readCookie(name: string): string | null {\n    if (typeof document === 'undefined') return null;\n    const match = document.cookie.match(new RegExp(`(^|; )${name}=([^;]+)`));\n    return match ? decodeURIComponent(match[2]!) : null;\n  }\n\n  /**\n   * Stitch the current captured click to an authenticated user. Call\n   * this on login, signup, or anywhere the user becomes known.\n   *\n   * No-op if no cref was captured. Errors are reported through\n   * `config.onError` by default — attribution is best-effort from the\n   * browser — but you can await this and try/catch if you want to\n   * surface failures explicitly.\n   */\n  async identify(userId: string): Promise<IdentifyResponse | null> {\n    const cref = this.getCref();\n    if (!cref) return null;\n\n    try {\n      return await requestJson<IdentifyResponse>(`${this.config.apiUrl}/attribution/identify`, {\n        method: 'POST',\n        body: { cref, userId, ts: Date.now() },\n        keepalive: true,\n      });\n    } catch (err) {\n      this.config.onError(err);\n      return null;\n    }\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/shared.ts","../src/browser.ts"],"sourcesContent":["/**\n * Shared types + error class for both the browser and server entry\n * points.\n *\n * Keeping these in their own module means browser imports won't drag in\n * `fetch` polyfills or server-only code, and server imports won't touch\n * anything that references `window` or `document`.\n */\n\nexport class OpenPartnerError extends Error {\n  constructor(\n    message: string,\n    public readonly status: number,\n    public readonly code?: string,\n    public readonly detail?: unknown,\n  ) {\n    super(message);\n    this.name = 'OpenPartnerError';\n  }\n}\n\nexport interface IdentifyResponse {\n  ok: boolean;\n  identityId: string | null;\n  firstStitch: boolean;\n  backfilledAttributions?: number;\n}\n\nexport interface EventAttribution {\n  /**\n   * 'not_attributed' only appears on a replay (`replayed: true`) of an event\n   * that didn't attribute the first time; which miss it was isn't stored.\n   * 'corrective': refund / chargeback / dispute_created / invoice_payment_failed —\n   * recorded, never attributed.\n   */\n  status:\n    | 'attributed'\n    | 'no_identity'\n    | 'no_click'\n    | 'outside_window'\n    | 'already_attributed'\n    | 'not_attributed'\n    | 'corrective';\n  model?: 'last_click' | 'first_click' | 'linear' | 'position';\n  touches?: Array<{\n    clickId: string;\n    partnerId: string;\n    weight: number;\n    attributionId: string;\n    commissionId?: string;\n  }>;\n}\n\nexport interface EventResponse {\n  ok: boolean;\n  eventId: string;\n  attribution: EventAttribution;\n  /** True when an earlier call with the same externalEventId already\n   *  recorded this event; eventId and attribution are that call's. */\n  replayed?: boolean;\n}\n\nexport interface ConversionResponse extends EventResponse {\n  /** The user the conversion was recorded under: the userId you passed, or\n   *  the click's own `click:<clickId>` user. */\n  userId: string;\n}\n\n/**\n * Small fetch helper used by both entries. Normalizes non-2xx responses\n * into OpenPartnerError so callers can try/catch with a stable shape\n * instead of poking at Response objects themselves.\n */\nexport type JsonRequestInit = Omit<RequestInit, 'body'> & { body?: unknown };\n\nexport async function requestJson<T>(\n  input: string,\n  init: JsonRequestInit = {},\n  fetchImpl: typeof fetch = globalThis.fetch,\n): Promise<T> {\n  const headers = new Headers(init.headers);\n  if (init.body !== undefined && !headers.has('content-type')) {\n    headers.set('content-type', 'application/json');\n  }\n  const res = await fetchImpl(input, {\n    ...init,\n    headers,\n    body:\n      init.body === undefined\n        ? undefined\n        : typeof init.body === 'string'\n          ? init.body\n          : JSON.stringify(init.body),\n  });\n\n  const text = await res.text();\n  let body: unknown = undefined;\n  if (text) {\n    try {\n      body = JSON.parse(text);\n    } catch {\n      body = text;\n    }\n  }\n\n  if (!res.ok) {\n    const errBody = (body ?? {}) as { error?: string; detail?: unknown };\n    throw new OpenPartnerError(\n      errBody.error ?? `${res.status} ${res.statusText}`,\n      res.status,\n      errBody.error,\n      errBody.detail ?? body,\n    );\n  }\n\n  return body as T;\n}\n","/**\n * Browser SDK — runs inside a merchant's web app. Captures the `cref`\n * attribution token from landing-page URLs and the first-party cookie\n * the click router sets, stashes it in localStorage so it survives\n * Safari / ITP cookie expiry and SPA navigations, and stitches to the\n * authenticated user on signup or login.\n *\n * Typical integration:\n *\n *   import { OpenPartner } from '@openpartner/sdk';\n *\n *   const op = OpenPartner.init({ apiUrl: 'https://openpartner.example.com' });\n *\n *   // After login/signup, once you know who the user is:\n *   await op.identify(user.id);\n *\n * With a captured referral it also hands the click to Stripe on its own:\n * Payment Links (buy.stripe.com) get `client_reference_id`, and Stripe\n * Pricing Table / Buy Button embeds get `client-reference-id`, including\n * ones added to the page later. A brand whose Stripe account is connected\n * to OpenPartner then needs no code for those checkouts. `stripe: false`\n * turns it off.\n *\n * No bundler? The same SDK ships as a script tag that starts itself\n * (auto.ts), served at /op.js by an OpenPartner portal.\n */\n\nimport { OpenPartnerError, requestJson, type IdentifyResponse } from './shared.js';\n\nexport { OpenPartnerError };\nexport type { IdentifyResponse };\n\nexport interface StripeLinkingConfig {\n  /** Extra Payment Link hosts — a custom domain set up for Payment Links\n   *  in Stripe (e.g. \"pay.yourbrand.com\"). buy.stripe.com is always on. */\n  linkHosts?: string[];\n}\n\nexport interface OpenPartnerConfig {\n  /** Base URL of your OpenPartner API, e.g. \"https://openpartner.example.com\". */\n  apiUrl: string;\n  /** First-party cookie name set by the click router. Default `_cref`. */\n  cookieName?: string;\n  /** Query-string parameter that carries the cref on the landing URL. Default `cref`. */\n  queryParam?: string;\n  /** localStorage key the captured cref is stashed under. Default `openpartner:cref`. */\n  storageKey?: string;\n  /**\n   * Hand the captured referral to Stripe Payment Links and Pricing Table /\n   * Buy Button embeds on the page. Default on; `false` turns it off.\n   */\n  stripe?: boolean | StripeLinkingConfig;\n  /**\n   * Also keep the referral in a first-party cookie, so your server can read\n   * it straight off the request when it creates a Stripe Checkout Session\n   * (`client_reference_id: req.cookies.op_ref`). Off by default; the\n   * script-tag build turns it on. `domain` shares it across subdomains\n   * (\".yourbrand.com\") when visitors land on one and check out on another.\n   */\n  referralCookie?: false | { name?: string; domain?: string; days?: number };\n  /**\n   * Called when identify() fails. Default: log to console. Pass a noop\n   * to suppress entirely or hook into your observability stack.\n   */\n  onError?: (err: unknown) => void;\n}\n\nconst DEFAULTS = {\n  cookieName: '_cref',\n  queryParam: 'cref',\n  storageKey: 'openpartner:cref',\n  stripe: true,\n  referralCookie: false,\n  onError: (err: unknown) => {\n    console.warn('[openpartner] identify failed', err);\n  },\n};\n\n/** Stripe accepts a client_reference_id of letters, digits, \"-\" and \"_\",\n *  up to 200, and silently drops anything else. A click id always fits; a\n *  value that doesn't came from somewhere else and isn't sent. */\nconst STRIPE_REFERENCE_RE = /^[A-Za-z0-9_-]{1,200}$/;\nconst STRIPE_EMBED_SELECTOR = 'stripe-pricing-table, stripe-buy-button';\n\nexport class OpenPartner {\n  private config: Required<OpenPartnerConfig>;\n  private observer: MutationObserver | null = null;\n\n  private constructor(config: OpenPartnerConfig) {\n    this.config = { ...DEFAULTS, ...config } as Required<OpenPartnerConfig>;\n    this.captureCref();\n    this.writeReferralCookie();\n    if (this.config.stripe !== false) this.watchStripe();\n  }\n\n  static init(config: OpenPartnerConfig): OpenPartner {\n    return new OpenPartner(config);\n  }\n\n  /** The cref we're holding onto, if any. Useful for debugging. */\n  getCref(): string | null {\n    if (typeof localStorage === 'undefined') return null;\n    return localStorage.getItem(this.config.storageKey);\n  }\n\n  /**\n   * Captured referral token for this visitor. Pass to Stripe Checkout\n   * as `client_reference_id` to enable webhook-based attribution\n   * without an explicit identify() call:\n   *\n   *   stripe.checkout.sessions.create({\n   *     client_reference_id: op.getReferral() ?? undefined,\n   *     // ...\n   *   });\n   *\n   * Returns null if the visitor didn't arrive via a partner link.\n   */\n  getReferral(): string | null {\n    return this.getCref();\n  }\n\n  /** Explicitly discard the captured cref. */\n  clear(): void {\n    if (typeof localStorage === 'undefined') return;\n    localStorage.removeItem(this.config.storageKey);\n  }\n\n  /**\n   * Add the referral to every Stripe Payment Link and Pricing Table / Buy\n   * Button embed under `root` that doesn't carry a reference already.\n   * Runs on its own at init and for anything added later; call it yourself\n   * only if you build Stripe elements inside a shadow root. Returns how\n   * many it changed.\n   */\n  linkStripe(root: ParentNode = document): number {\n    const referral = this.getReferral();\n    if (!referral || !STRIPE_REFERENCE_RE.test(referral) || typeof document === 'undefined') return 0;\n    const hosts = new Set(['buy.stripe.com', ...this.stripeLinkHosts()]);\n    let changed = 0;\n\n    const anchors: HTMLAnchorElement[] = [];\n    if (root instanceof HTMLAnchorElement) anchors.push(root);\n    anchors.push(...Array.from(root.querySelectorAll<HTMLAnchorElement>('a[href]')));\n    for (const a of anchors) {\n      let url: URL;\n      try {\n        url = new URL(a.href);\n      } catch {\n        continue;\n      }\n      // One the brand set itself (or an earlier pass) stays as it is.\n      if (!hosts.has(url.hostname.toLowerCase()) || url.searchParams.has('client_reference_id')) continue;\n      url.searchParams.set('client_reference_id', referral);\n      a.href = url.toString();\n      changed += 1;\n    }\n\n    const embeds: Element[] = [];\n    if (root instanceof Element && root.matches(STRIPE_EMBED_SELECTOR)) embeds.push(root);\n    embeds.push(...Array.from(root.querySelectorAll(STRIPE_EMBED_SELECTOR)));\n    for (const el of embeds) {\n      if (el.hasAttribute('client-reference-id')) continue;\n      el.setAttribute('client-reference-id', referral);\n      changed += 1;\n    }\n    return changed;\n  }\n\n  /** Stop watching the page for new Stripe links and embeds. */\n  stopLinkingStripe(): void {\n    this.observer?.disconnect();\n    this.observer = null;\n  }\n\n  private stripeLinkHosts(): string[] {\n    const cfg = this.config.stripe;\n    return typeof cfg === 'object' && cfg.linkHosts ? cfg.linkHosts.map((h) => h.trim().toLowerCase()).filter(Boolean) : [];\n  }\n\n  /**\n   * Link what's on the page now, then anything added or re-pointed later\n   * (SPAs, Stripe embeds mounted on demand). Only with a referral: a visitor\n   * who didn't come from a partner link costs nothing.\n   *\n   * Pricing Table and Buy Button embeds read client-reference-id when\n   * Stripe's script renders them, so the script tag belongs in <head>,\n   * ahead of the embed: the observer then sets the attribute as the\n   * element is parsed, before Stripe upgrades it.\n   */\n  private watchStripe(): void {\n    if (typeof document === 'undefined' || !this.getReferral()) return;\n    this.linkStripe(document);\n    if (typeof MutationObserver === 'undefined') return;\n    this.observer = new MutationObserver((records) => {\n      for (const record of records) {\n        if (record.type === 'attributes') {\n          // An href re-pointed at a Payment Link.\n          if (record.target instanceof HTMLAnchorElement) this.linkStripe(record.target);\n          continue;\n        }\n        for (const node of Array.from(record.addedNodes)) {\n          if (node instanceof Element) this.linkStripe(node);\n        }\n      }\n    });\n    // Our own edits only ever add a missing reference, so the second pass\n    // they trigger finds nothing to change.\n    this.observer.observe(document.documentElement, {\n      childList: true,\n      subtree: true,\n      attributes: true,\n      attributeFilter: ['href'],\n    });\n  }\n\n  /**\n   * Capture the cref from query string or cookie and stash in\n   * localStorage. Runs on init so the value survives SPA navigations,\n   * ITP cookie expiry, and subsequent page loads.\n   */\n  private captureCref(): void {\n    if (typeof window === 'undefined' || typeof localStorage === 'undefined') return;\n\n    const url = new URL(window.location.href);\n    const queryCref = url.searchParams.get(this.config.queryParam);\n\n    if (queryCref) {\n      localStorage.setItem(this.config.storageKey, queryCref);\n      return;\n    }\n\n    const cookieCref = this.readCookie(this.config.cookieName);\n    if (cookieCref && !localStorage.getItem(this.config.storageKey)) {\n      localStorage.setItem(this.config.storageKey, cookieCref);\n    }\n  }\n\n  /** Mirror the referral into the brand's own first-party cookie (when\n   *  configured), refreshed on every page load that has one. */\n  private writeReferralCookie(): void {\n    const cfg = this.config.referralCookie;\n    if (!cfg || typeof document === 'undefined') return;\n    const referral = this.getReferral();\n    if (!referral || !STRIPE_REFERENCE_RE.test(referral)) return;\n    const name = cfg.name ?? 'op_ref';\n    const maxAge = Math.round((cfg.days ?? 90) * 86400);\n    const secure = typeof location !== 'undefined' && location.protocol === 'https:' ? '; Secure' : '';\n    const domain = cfg.domain ? `; Domain=${cfg.domain}` : '';\n    document.cookie = `${name}=${encodeURIComponent(referral)}; Max-Age=${maxAge}; Path=/; SameSite=Lax${domain}${secure}`;\n  }\n\n  private readCookie(name: string): string | null {\n    if (typeof document === 'undefined') return null;\n    const match = document.cookie.match(new RegExp(`(^|; )${name}=([^;]+)`));\n    return match ? decodeURIComponent(match[2]!) : null;\n  }\n\n  /**\n   * Stitch the current captured click to an authenticated user. Call\n   * this on login, signup, or anywhere the user becomes known.\n   *\n   * No-op if no cref was captured. Errors are reported through\n   * `config.onError` by default — attribution is best-effort from the\n   * browser — but you can await this and try/catch if you want to\n   * surface failures explicitly.\n   */\n  async identify(userId: string): Promise<IdentifyResponse | null> {\n    const cref = this.getCref();\n    if (!cref) return null;\n\n    try {\n      return await requestJson<IdentifyResponse>(`${this.config.apiUrl}/attribution/identify`, {\n        method: 'POST',\n        body: { cref, userId, ts: Date.now() },\n        keepalive: true,\n      });\n    } catch (err) {\n      this.config.onError(err);\n      return null;\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/server.cjs

@@ -88,6 +88,16 @@ var OpenPartnerServer = class {
   async trackEvent(params) {
     return this.request("/attribution/events", { method: "POST", body: params });
   }
+  /**
+   * Record a conversion against a click in one call, for when you have the
+   * click id but no identify()'d user: a lender reporting a funded loan, a
+   * CRM closing a deal. Stitches the click and records the event together.
+   * Throws `click_not_found` (404) for a click outside your program and
+   * `click_flagged` (422) for one flagged as fraud.
+   */
+  async trackConversion(params) {
+    return this.request("/attribution/conversions", { method: "POST", body: params });
+  }
   /**
    * Stitch an attribution token (cref) to a known userId. Normally the
    * browser SDK does this; use this overload if your backend receives

package/dist/server.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server.ts","../src/shared.ts"],"sourcesContent":["/**\n * Server SDK — runs inside a merchant's backend. Used for the\n * server-to-server pieces of the attribution pipeline: posting\n * conversion events (signup / invoice_paid / custom), stitching\n * clicks to users from the backend, and reading dashboard snapshots.\n *\n * Typical integration:\n *\n *   import { OpenPartnerServer } from '@openpartner/sdk/server';\n *\n *   const op = new OpenPartnerServer({\n *     apiUrl: process.env.OPENPARTNER_API_URL!,\n *     apiKey: process.env.OPENPARTNER_API_KEY!,\n *   });\n *\n *   // On signup:\n *   await op.trackEvent({ userId, type: 'signup' });\n *\n *   // On invoice paid:\n *   await op.trackEvent({ userId, type: 'invoice_paid', value: 249, currency: 'USD' });\n */\n\nimport { OpenPartnerError, requestJson, type EventResponse, type IdentifyResponse, type JsonRequestInit } from './shared.js';\n\nexport { OpenPartnerError };\nexport type { EventResponse, IdentifyResponse };\nexport type { EventAttribution } from './shared.js';\n\nexport interface OpenPartnerServerConfig {\n  /** Base URL of the OpenPartner API. */\n  apiUrl: string;\n  /**\n   * Admin or scoped API key. For event ingest you need admin or a key\n   * with the right scope (the core API currently uses admin-only for\n   * /attribution/events). Never expose this to the browser.\n   */\n  apiKey: string;\n  /** Optional fetch override for tests or custom transports. */\n  fetch?: typeof fetch;\n}\n\nexport interface TrackEventParams {\n  /** The user the event pertains to. Must match how the browser SDK called identify(). */\n  userId: string;\n  /** Event type — typically 'signup' | 'trial_started' | 'subscription_created' | 'invoice_paid' | custom. */\n  type: string;\n  /** Dollar (or currency) value of the event, for percent-commission rules. */\n  value?: number;\n  /** ISO 4217 currency code. Defaults to USD on the server if omitted. */\n  currency?: string;\n  /** Arbitrary metadata you want to attach (stripeEventId, invoiceId, etc). */\n  metadata?: Record<string, unknown>;\n  /** Event time. Defaults to now on the server. Pass ISO 8601 to override. */\n  ts?: string;\n}\n\nexport class OpenPartnerServer {\n  private readonly apiUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(config: OpenPartnerServerConfig) {\n    if (!config.apiUrl) throw new OpenPartnerError('apiUrl is required', 400, 'config_missing');\n    if (!config.apiKey) throw new OpenPartnerError('apiKey is required', 400, 'config_missing');\n    this.apiUrl = config.apiUrl.replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n    this.fetchImpl = config.fetch ?? globalThis.fetch;\n  }\n\n  /**\n   * Record a conversion event. The server walks the userId back to a\n   * click, applies the campaign's attribution model, and writes the\n   * resulting attribution + commission rows.\n   */\n  async trackEvent(params: TrackEventParams): Promise<EventResponse> {\n    return this.request<EventResponse>('/attribution/events', { method: 'POST', body: params });\n  }\n\n  /**\n   * Stitch an attribution token (cref) to a known userId. Normally the\n   * browser SDK does this; use this overload if your backend receives\n   * the cref from the browser (e.g. as part of a signup payload) and\n   * wants to own the stitch call.\n   */\n  async identify(params: { cref: string; userId: string; ts?: number }): Promise<IdentifyResponse> {\n    return this.request<IdentifyResponse>('/attribution/identify', {\n      method: 'POST',\n      body: params,\n    });\n  }\n\n  private async request<T>(path: string, init: JsonRequestInit): Promise<T> {\n    const headers = new Headers(init.headers);\n    headers.set('authorization', `Bearer ${this.apiKey}`);\n    return requestJson<T>(\n      `${this.apiUrl}${path}`,\n      { ...init, headers },\n      // Inject the configured fetch so tests (or alternate transports)\n      // can intercept.\n      this.fetchImpl,\n    );\n  }\n}\n","/**\n * Shared types + error class for both the browser and server entry\n * points.\n *\n * Keeping these in their own module means browser imports won't drag in\n * `fetch` polyfills or server-only code, and server imports won't touch\n * anything that references `window` or `document`.\n */\n\nexport class OpenPartnerError extends Error {\n  constructor(\n    message: string,\n    public readonly status: number,\n    public readonly code?: string,\n    public readonly detail?: unknown,\n  ) {\n    super(message);\n    this.name = 'OpenPartnerError';\n  }\n}\n\nexport interface IdentifyResponse {\n  ok: boolean;\n  identityId: string | null;\n  firstStitch: boolean;\n  backfilledAttributions?: number;\n}\n\nexport interface EventAttribution {\n  status: 'attributed' | 'no_identity' | 'no_click' | 'outside_window' | 'already_attributed';\n  model?: 'last_click' | 'first_click' | 'linear' | 'position';\n  touches?: Array<{\n    clickId: string;\n    partnerId: string;\n    weight: number;\n    attributionId: string;\n    commissionId?: string;\n  }>;\n}\n\nexport interface EventResponse {\n  ok: boolean;\n  eventId: string;\n  attribution: EventAttribution;\n}\n\n/**\n * Small fetch helper used by both entries. Normalizes non-2xx responses\n * into OpenPartnerError so callers can try/catch with a stable shape\n * instead of poking at Response objects themselves.\n */\nexport type JsonRequestInit = Omit<RequestInit, 'body'> & { body?: unknown };\n\nexport async function requestJson<T>(\n  input: string,\n  init: JsonRequestInit = {},\n  fetchImpl: typeof fetch = globalThis.fetch,\n): Promise<T> {\n  const headers = new Headers(init.headers);\n  if (init.body !== undefined && !headers.has('content-type')) {\n    headers.set('content-type', 'application/json');\n  }\n  const res = await fetchImpl(input, {\n    ...init,\n    headers,\n    body:\n      init.body === undefined\n        ? undefined\n        : typeof init.body === 'string'\n          ? init.body\n          : JSON.stringify(init.body),\n  });\n\n  const text = await res.text();\n  let body: unknown = undefined;\n  if (text) {\n    try {\n      body = JSON.parse(text);\n    } catch {\n      body = text;\n    }\n  }\n\n  if (!res.ok) {\n    const errBody = (body ?? {}) as { error?: string; detail?: unknown };\n    throw new OpenPartnerError(\n      errBody.error ?? `${res.status} ${res.statusText}`,\n      res.status,\n      errBody.error,\n      errBody.detail ?? body,\n    );\n  }\n\n  return body as T;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACSO,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC1C,YACE,SACgB,QACA,MACA,QAChB;AACA,UAAM,OAAO;AAJG;AACA;AACA;AAGhB,SAAK,OAAO;AAAA,EACd;AACF;AAkCA,eAAsB,YACpB,OACA,OAAwB,CAAC,GACzB,YAA0B,WAAW,OACzB;AACZ,QAAM,UAAU,IAAI,QAAQ,KAAK,OAAO;AACxC,MAAI,KAAK,SAAS,UAAa,CAAC,QAAQ,IAAI,cAAc,GAAG;AAC3D,YAAQ,IAAI,gBAAgB,kBAAkB;AAAA,EAChD;AACA,QAAM,MAAM,MAAM,UAAU,OAAO;AAAA,IACjC,GAAG;AAAA,IACH;AAAA,IACA,MACE,KAAK,SAAS,SACV,SACA,OAAO,KAAK,SAAS,WACnB,KAAK,OACL,KAAK,UAAU,KAAK,IAAI;AAAA,EAClC,CAAC;AAED,QAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,MAAI,OAAgB;AACpB,MAAI,MAAM;AACR,QAAI;AACF,aAAO,KAAK,MAAM,IAAI;AAAA,IACxB,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AAEA,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,UAAW,QAAQ,CAAC;AAC1B,UAAM,IAAI;AAAA,MACR,QAAQ,SAAS,GAAG,IAAI,MAAM,IAAI,IAAI,UAAU;AAAA,MAChD,IAAI;AAAA,MACJ,QAAQ;AAAA,MACR,QAAQ,UAAU;AAAA,IACpB;AAAA,EACF;AAEA,SAAO;AACT;;;ADtCO,IAAM,oBAAN,MAAwB;AAAA,EAK7B,YAAY,QAAiC;AAJ7C,wBAAiB;AACjB,wBAAiB;AACjB,wBAAiB;AAGf,QAAI,CAAC,OAAO,OAAQ,OAAM,IAAI,iBAAiB,sBAAsB,KAAK,gBAAgB;AAC1F,QAAI,CAAC,OAAO,OAAQ,OAAM,IAAI,iBAAiB,sBAAsB,KAAK,gBAAgB;AAC1F,SAAK,SAAS,OAAO,OAAO,QAAQ,OAAO,EAAE;AAC7C,SAAK,SAAS,OAAO;AACrB,SAAK,YAAY,OAAO,SAAS,WAAW;AAAA,EAC9C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,WAAW,QAAkD;AACjE,WAAO,KAAK,QAAuB,uBAAuB,EAAE,QAAQ,QAAQ,MAAM,OAAO,CAAC;AAAA,EAC5F;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,SAAS,QAAkF;AAC/F,WAAO,KAAK,QAA0B,yBAAyB;AAAA,MAC7D,QAAQ;AAAA,MACR,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AAAA,EAEA,MAAc,QAAW,MAAc,MAAmC;AACxE,UAAM,UAAU,IAAI,QAAQ,KAAK,OAAO;AACxC,YAAQ,IAAI,iBAAiB,UAAU,KAAK,MAAM,EAAE;AACpD,WAAO;AAAA,MACL,GAAG,KAAK,MAAM,GAAG,IAAI;AAAA,MACrB,EAAE,GAAG,MAAM,QAAQ;AAAA;AAAA;AAAA,MAGnB,KAAK;AAAA,IACP;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/server.ts","../src/shared.ts"],"sourcesContent":["/**\n * Server SDK — runs inside a merchant's backend. Used for the\n * server-to-server pieces of the attribution pipeline: posting\n * conversion events (signup / invoice_paid / custom), stitching\n * clicks to users from the backend, and reading dashboard snapshots.\n *\n * Typical integration:\n *\n *   import { OpenPartnerServer } from '@openpartner/sdk/server';\n *\n *   const op = new OpenPartnerServer({\n *     apiUrl: process.env.OPENPARTNER_API_URL!,\n *     apiKey: process.env.OPENPARTNER_API_KEY!,\n *   });\n *\n *   // On signup:\n *   await op.trackEvent({ userId, type: 'signup' });\n *\n *   // On invoice paid — externalEventId makes retries safe:\n *   await op.trackEvent({ userId, type: 'invoice_paid', value: 249, currency: 'USD', externalEventId: invoice.id });\n *\n *   // Holding only the click id (from the link's {click_id} macro)? One call:\n *   await op.trackConversion({ clickId, type: 'loan_funded', value: 5000, externalEventId: `${loan.id}:funded` });\n */\n\nimport {\n  OpenPartnerError,\n  requestJson,\n  type ConversionResponse,\n  type EventResponse,\n  type IdentifyResponse,\n  type JsonRequestInit,\n} from './shared.js';\n\nexport { OpenPartnerError };\nexport type { ConversionResponse, EventResponse, IdentifyResponse };\nexport type { EventAttribution } from './shared.js';\n\nexport interface OpenPartnerServerConfig {\n  /** Base URL of the OpenPartner API. */\n  apiUrl: string;\n  /**\n   * Admin or scoped API key. Event ingest (/attribution/events) accepts\n   * an admin key or a scoped key with `events:write`. Never expose this\n   * to the browser.\n   */\n  apiKey: string;\n  /** Optional fetch override for tests or custom transports. */\n  fetch?: typeof fetch;\n}\n\nexport interface TrackEventParams {\n  /** The user the event pertains to. Must match how the browser SDK called identify(). */\n  userId: string;\n  /** Event type — typically 'signup' | 'trial_started' | 'subscription_created' | 'invoice_paid' | custom. */\n  type: string;\n  /** Dollar (or currency) value of the event, for percent-commission rules. */\n  value?: number;\n  /** ISO 4217 currency code. Defaults to USD on the server if omitted. */\n  currency?: string;\n  /** Arbitrary metadata you want to attach (stripeEventId, invoiceId, etc). */\n  metadata?: Record<string, unknown>;\n  /** Event time. Defaults to now on the server. Pass ISO 8601 to override. */\n  ts?: string;\n  /**\n   * Idempotency key: your system's stable id for this one event (order id,\n   * invoice id, CRM deal-stage change id), max 120 chars. Strongly\n   * recommended. A retried call with the same key returns the original\n   * event and attribution (`replayed: true`) instead of recording and\n   * commissioning it twice. Unique per event, not per order: an order's\n   * `subscription_created` and its `invoice_paid` need different keys.\n   * Reusing a key for a different userId / type / value / currency throws\n   * an `OpenPartnerError` with code `external_event_id_conflict` (409).\n   */\n  externalEventId?: string;\n}\n\nexport interface TrackConversionParams {\n  /** The click id the partner link handed you: the `{click_id}` macro in the\n   *  destination URL, or the `cref` query parameter. */\n  clickId: string;\n  /** Event type, e.g. 'loan_funded', 'opportunity_won', 'invoice_paid'. */\n  type: string;\n  /** Value of the conversion, for percent-commission rules. */\n  value?: number;\n  /** ISO 4217 currency code. Defaults to USD on the server if omitted. */\n  currency?: string;\n  /**\n   * Required idempotency key: your stable id for this one conversion (loan\n   * id plus stage, order id), max 120 chars. A retry returns the original\n   * result (`replayed: true`); reusing it for a different click or\n   * conversion throws `external_event_id_conflict` (409).\n   */\n  externalEventId: string;\n  /**\n   * Your own id for the user, if you have one. Omit it and the conversion is\n   * recorded under the click's own user, credited to that click alone.\n   */\n  userId?: string;\n  metadata?: Record<string, unknown>;\n  /** Event time. Defaults to now on the server. ISO 8601. */\n  ts?: string;\n}\n\nexport class OpenPartnerServer {\n  private readonly apiUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(config: OpenPartnerServerConfig) {\n    if (!config.apiUrl) throw new OpenPartnerError('apiUrl is required', 400, 'config_missing');\n    if (!config.apiKey) throw new OpenPartnerError('apiKey is required', 400, 'config_missing');\n    this.apiUrl = config.apiUrl.replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n    this.fetchImpl = config.fetch ?? globalThis.fetch;\n  }\n\n  /**\n   * Record a conversion event. The server walks the userId back to a\n   * click, applies the campaign's attribution model, and writes the\n   * resulting attribution + commission rows.\n   */\n  async trackEvent(params: TrackEventParams): Promise<EventResponse> {\n    return this.request<EventResponse>('/attribution/events', { method: 'POST', body: params });\n  }\n\n  /**\n   * Record a conversion against a click in one call, for when you have the\n   * click id but no identify()'d user: a lender reporting a funded loan, a\n   * CRM closing a deal. Stitches the click and records the event together.\n   * Throws `click_not_found` (404) for a click outside your program and\n   * `click_flagged` (422) for one flagged as fraud.\n   */\n  async trackConversion(params: TrackConversionParams): Promise<ConversionResponse> {\n    return this.request<ConversionResponse>('/attribution/conversions', { method: 'POST', body: params });\n  }\n\n  /**\n   * Stitch an attribution token (cref) to a known userId. Normally the\n   * browser SDK does this; use this overload if your backend receives\n   * the cref from the browser (e.g. as part of a signup payload) and\n   * wants to own the stitch call.\n   */\n  async identify(params: { cref: string; userId: string; ts?: number }): Promise<IdentifyResponse> {\n    return this.request<IdentifyResponse>('/attribution/identify', {\n      method: 'POST',\n      body: params,\n    });\n  }\n\n  private async request<T>(path: string, init: JsonRequestInit): Promise<T> {\n    const headers = new Headers(init.headers);\n    headers.set('authorization', `Bearer ${this.apiKey}`);\n    return requestJson<T>(\n      `${this.apiUrl}${path}`,\n      { ...init, headers },\n      // Inject the configured fetch so tests (or alternate transports)\n      // can intercept.\n      this.fetchImpl,\n    );\n  }\n}\n","/**\n * Shared types + error class for both the browser and server entry\n * points.\n *\n * Keeping these in their own module means browser imports won't drag in\n * `fetch` polyfills or server-only code, and server imports won't touch\n * anything that references `window` or `document`.\n */\n\nexport class OpenPartnerError extends Error {\n  constructor(\n    message: string,\n    public readonly status: number,\n    public readonly code?: string,\n    public readonly detail?: unknown,\n  ) {\n    super(message);\n    this.name = 'OpenPartnerError';\n  }\n}\n\nexport interface IdentifyResponse {\n  ok: boolean;\n  identityId: string | null;\n  firstStitch: boolean;\n  backfilledAttributions?: number;\n}\n\nexport interface EventAttribution {\n  /**\n   * 'not_attributed' only appears on a replay (`replayed: true`) of an event\n   * that didn't attribute the first time; which miss it was isn't stored.\n   * 'corrective': refund / chargeback / dispute_created / invoice_payment_failed —\n   * recorded, never attributed.\n   */\n  status:\n    | 'attributed'\n    | 'no_identity'\n    | 'no_click'\n    | 'outside_window'\n    | 'already_attributed'\n    | 'not_attributed'\n    | 'corrective';\n  model?: 'last_click' | 'first_click' | 'linear' | 'position';\n  touches?: Array<{\n    clickId: string;\n    partnerId: string;\n    weight: number;\n    attributionId: string;\n    commissionId?: string;\n  }>;\n}\n\nexport interface EventResponse {\n  ok: boolean;\n  eventId: string;\n  attribution: EventAttribution;\n  /** True when an earlier call with the same externalEventId already\n   *  recorded this event; eventId and attribution are that call's. */\n  replayed?: boolean;\n}\n\nexport interface ConversionResponse extends EventResponse {\n  /** The user the conversion was recorded under: the userId you passed, or\n   *  the click's own `click:<clickId>` user. */\n  userId: string;\n}\n\n/**\n * Small fetch helper used by both entries. Normalizes non-2xx responses\n * into OpenPartnerError so callers can try/catch with a stable shape\n * instead of poking at Response objects themselves.\n */\nexport type JsonRequestInit = Omit<RequestInit, 'body'> & { body?: unknown };\n\nexport async function requestJson<T>(\n  input: string,\n  init: JsonRequestInit = {},\n  fetchImpl: typeof fetch = globalThis.fetch,\n): Promise<T> {\n  const headers = new Headers(init.headers);\n  if (init.body !== undefined && !headers.has('content-type')) {\n    headers.set('content-type', 'application/json');\n  }\n  const res = await fetchImpl(input, {\n    ...init,\n    headers,\n    body:\n      init.body === undefined\n        ? undefined\n        : typeof init.body === 'string'\n          ? init.body\n          : JSON.stringify(init.body),\n  });\n\n  const text = await res.text();\n  let body: unknown = undefined;\n  if (text) {\n    try {\n      body = JSON.parse(text);\n    } catch {\n      body = text;\n    }\n  }\n\n  if (!res.ok) {\n    const errBody = (body ?? {}) as { error?: string; detail?: unknown };\n    throw new OpenPartnerError(\n      errBody.error ?? `${res.status} ${res.statusText}`,\n      res.status,\n      errBody.error,\n      errBody.detail ?? body,\n    );\n  }\n\n  return body as T;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACSO,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC1C,YACE,SACgB,QACA,MACA,QAChB;AACA,UAAM,OAAO;AAJG;AACA;AACA;AAGhB,SAAK,OAAO;AAAA,EACd;AACF;AAwDA,eAAsB,YACpB,OACA,OAAwB,CAAC,GACzB,YAA0B,WAAW,OACzB;AACZ,QAAM,UAAU,IAAI,QAAQ,KAAK,OAAO;AACxC,MAAI,KAAK,SAAS,UAAa,CAAC,QAAQ,IAAI,cAAc,GAAG;AAC3D,YAAQ,IAAI,gBAAgB,kBAAkB;AAAA,EAChD;AACA,QAAM,MAAM,MAAM,UAAU,OAAO;AAAA,IACjC,GAAG;AAAA,IACH;AAAA,IACA,MACE,KAAK,SAAS,SACV,SACA,OAAO,KAAK,SAAS,WACnB,KAAK,OACL,KAAK,UAAU,KAAK,IAAI;AAAA,EAClC,CAAC;AAED,QAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,MAAI,OAAgB;AACpB,MAAI,MAAM;AACR,QAAI;AACF,aAAO,KAAK,MAAM,IAAI;AAAA,IACxB,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AAEA,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,UAAW,QAAQ,CAAC;AAC1B,UAAM,IAAI;AAAA,MACR,QAAQ,SAAS,GAAG,IAAI,MAAM,IAAI,IAAI,UAAU;AAAA,MAChD,IAAI;AAAA,MACJ,QAAQ;AAAA,MACR,QAAQ,UAAU;AAAA,IACpB;AAAA,EACF;AAEA,SAAO;AACT;;;ADZO,IAAM,oBAAN,MAAwB;AAAA,EAK7B,YAAY,QAAiC;AAJ7C,wBAAiB;AACjB,wBAAiB;AACjB,wBAAiB;AAGf,QAAI,CAAC,OAAO,OAAQ,OAAM,IAAI,iBAAiB,sBAAsB,KAAK,gBAAgB;AAC1F,QAAI,CAAC,OAAO,OAAQ,OAAM,IAAI,iBAAiB,sBAAsB,KAAK,gBAAgB;AAC1F,SAAK,SAAS,OAAO,OAAO,QAAQ,OAAO,EAAE;AAC7C,SAAK,SAAS,OAAO;AACrB,SAAK,YAAY,OAAO,SAAS,WAAW;AAAA,EAC9C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,WAAW,QAAkD;AACjE,WAAO,KAAK,QAAuB,uBAAuB,EAAE,QAAQ,QAAQ,MAAM,OAAO,CAAC;AAAA,EAC5F;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,gBAAgB,QAA4D;AAChF,WAAO,KAAK,QAA4B,4BAA4B,EAAE,QAAQ,QAAQ,MAAM,OAAO,CAAC;AAAA,EACtG;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,SAAS,QAAkF;AAC/F,WAAO,KAAK,QAA0B,yBAAyB;AAAA,MAC7D,QAAQ;AAAA,MACR,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AAAA,EAEA,MAAc,QAAW,MAAc,MAAmC;AACxE,UAAM,UAAU,IAAI,QAAQ,KAAK,OAAO;AACxC,YAAQ,IAAI,iBAAiB,UAAU,KAAK,MAAM,EAAE;AACpD,WAAO;AAAA,MACL,GAAG,KAAK,MAAM,GAAG,IAAI;AAAA,MACrB,EAAE,GAAG,MAAM,QAAQ;AAAA;AAAA;AAAA,MAGnB,KAAK;AAAA,IACP;AAAA,EACF;AACF;","names":[]}

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { E as EventResponse, I as IdentifyResponse } from './shared-CLfBjPeb.cjs';
-export { a as EventAttribution, O as OpenPartnerError } from './shared-CLfBjPeb.cjs';
+import { E as EventResponse, C as ConversionResponse, I as IdentifyResponse } from './shared-dh1vlldf.cjs';
+export { a as EventAttribution, O as OpenPartnerError } from './shared-dh1vlldf.cjs';
 
 /**
  * Server SDK — runs inside a merchant's backend. Used for the
@@ -19,17 +19,20 @@ export { a as EventAttribution, O as OpenPartnerError } from './shared-CLfBjPeb.
  *   // On signup:
  *   await op.trackEvent({ userId, type: 'signup' });
  *
- *   // On invoice paid:
- *   await op.trackEvent({ userId, type: 'invoice_paid', value: 249, currency: 'USD' });
+ *   // On invoice paid — externalEventId makes retries safe:
+ *   await op.trackEvent({ userId, type: 'invoice_paid', value: 249, currency: 'USD', externalEventId: invoice.id });
+ *
+ *   // Holding only the click id (from the link's {click_id} macro)? One call:
+ *   await op.trackConversion({ clickId, type: 'loan_funded', value: 5000, externalEventId: `${loan.id}:funded` });
  */
 
 interface OpenPartnerServerConfig {
     /** Base URL of the OpenPartner API. */
     apiUrl: string;
     /**
-     * Admin or scoped API key. For event ingest you need admin or a key
-     * with the right scope (the core API currently uses admin-only for
-     * /attribution/events). Never expose this to the browser.
+     * Admin or scoped API key. Event ingest (/attribution/events) accepts
+     * an admin key or a scoped key with `events:write`. Never expose this
+     * to the browser.
      */
     apiKey: string;
     /** Optional fetch override for tests or custom transports. */
@@ -48,6 +51,43 @@ interface TrackEventParams {
     metadata?: Record<string, unknown>;
     /** Event time. Defaults to now on the server. Pass ISO 8601 to override. */
     ts?: string;
+    /**
+     * Idempotency key: your system's stable id for this one event (order id,
+     * invoice id, CRM deal-stage change id), max 120 chars. Strongly
+     * recommended. A retried call with the same key returns the original
+     * event and attribution (`replayed: true`) instead of recording and
+     * commissioning it twice. Unique per event, not per order: an order's
+     * `subscription_created` and its `invoice_paid` need different keys.
+     * Reusing a key for a different userId / type / value / currency throws
+     * an `OpenPartnerError` with code `external_event_id_conflict` (409).
+     */
+    externalEventId?: string;
+}
+interface TrackConversionParams {
+    /** The click id the partner link handed you: the `{click_id}` macro in the
+     *  destination URL, or the `cref` query parameter. */
+    clickId: string;
+    /** Event type, e.g. 'loan_funded', 'opportunity_won', 'invoice_paid'. */
+    type: string;
+    /** Value of the conversion, for percent-commission rules. */
+    value?: number;
+    /** ISO 4217 currency code. Defaults to USD on the server if omitted. */
+    currency?: string;
+    /**
+     * Required idempotency key: your stable id for this one conversion (loan
+     * id plus stage, order id), max 120 chars. A retry returns the original
+     * result (`replayed: true`); reusing it for a different click or
+     * conversion throws `external_event_id_conflict` (409).
+     */
+    externalEventId: string;
+    /**
+     * Your own id for the user, if you have one. Omit it and the conversion is
+     * recorded under the click's own user, credited to that click alone.
+     */
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    /** Event time. Defaults to now on the server. ISO 8601. */
+    ts?: string;
 }
 declare class OpenPartnerServer {
     private readonly apiUrl;
@@ -60,6 +100,14 @@ declare class OpenPartnerServer {
      * resulting attribution + commission rows.
      */
     trackEvent(params: TrackEventParams): Promise<EventResponse>;
+    /**
+     * Record a conversion against a click in one call, for when you have the
+     * click id but no identify()'d user: a lender reporting a funded loan, a
+     * CRM closing a deal. Stitches the click and records the event together.
+     * Throws `click_not_found` (404) for a click outside your program and
+     * `click_flagged` (422) for one flagged as fraud.
+     */
+    trackConversion(params: TrackConversionParams): Promise<ConversionResponse>;
     /**
      * Stitch an attribution token (cref) to a known userId. Normally the
      * browser SDK does this; use this overload if your backend receives
@@ -74,4 +122,5 @@ declare class OpenPartnerServer {
     private request;
 }
 
-export { EventResponse, IdentifyResponse, OpenPartnerServer, type OpenPartnerServerConfig, type TrackEventParams };
+export { ConversionResponse, EventResponse, IdentifyResponse, OpenPartnerServer };
+export type { OpenPartnerServerConfig, TrackConversionParams, TrackEventParams };

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { E as EventResponse, I as IdentifyResponse } from './shared-CLfBjPeb.js';
-export { a as EventAttribution, O as OpenPartnerError } from './shared-CLfBjPeb.js';
+import { E as EventResponse, C as ConversionResponse, I as IdentifyResponse } from './shared-dh1vlldf.js';
+export { a as EventAttribution, O as OpenPartnerError } from './shared-dh1vlldf.js';
 
 /**
  * Server SDK — runs inside a merchant's backend. Used for the
@@ -19,17 +19,20 @@ export { a as EventAttribution, O as OpenPartnerError } from './shared-CLfBjPeb.
  *   // On signup:
  *   await op.trackEvent({ userId, type: 'signup' });
  *
- *   // On invoice paid:
- *   await op.trackEvent({ userId, type: 'invoice_paid', value: 249, currency: 'USD' });
+ *   // On invoice paid — externalEventId makes retries safe:
+ *   await op.trackEvent({ userId, type: 'invoice_paid', value: 249, currency: 'USD', externalEventId: invoice.id });
+ *
+ *   // Holding only the click id (from the link's {click_id} macro)? One call:
+ *   await op.trackConversion({ clickId, type: 'loan_funded', value: 5000, externalEventId: `${loan.id}:funded` });
  */
 
 interface OpenPartnerServerConfig {
     /** Base URL of the OpenPartner API. */
     apiUrl: string;
     /**
-     * Admin or scoped API key. For event ingest you need admin or a key
-     * with the right scope (the core API currently uses admin-only for
-     * /attribution/events). Never expose this to the browser.
+     * Admin or scoped API key. Event ingest (/attribution/events) accepts
+     * an admin key or a scoped key with `events:write`. Never expose this
+     * to the browser.
      */
     apiKey: string;
     /** Optional fetch override for tests or custom transports. */
@@ -48,6 +51,43 @@ interface TrackEventParams {
     metadata?: Record<string, unknown>;
     /** Event time. Defaults to now on the server. Pass ISO 8601 to override. */
     ts?: string;
+    /**
+     * Idempotency key: your system's stable id for this one event (order id,
+     * invoice id, CRM deal-stage change id), max 120 chars. Strongly
+     * recommended. A retried call with the same key returns the original
+     * event and attribution (`replayed: true`) instead of recording and
+     * commissioning it twice. Unique per event, not per order: an order's
+     * `subscription_created` and its `invoice_paid` need different keys.
+     * Reusing a key for a different userId / type / value / currency throws
+     * an `OpenPartnerError` with code `external_event_id_conflict` (409).
+     */
+    externalEventId?: string;
+}
+interface TrackConversionParams {
+    /** The click id the partner link handed you: the `{click_id}` macro in the
+     *  destination URL, or the `cref` query parameter. */
+    clickId: string;
+    /** Event type, e.g. 'loan_funded', 'opportunity_won', 'invoice_paid'. */
+    type: string;
+    /** Value of the conversion, for percent-commission rules. */
+    value?: number;
+    /** ISO 4217 currency code. Defaults to USD on the server if omitted. */
+    currency?: string;
+    /**
+     * Required idempotency key: your stable id for this one conversion (loan
+     * id plus stage, order id), max 120 chars. A retry returns the original
+     * result (`replayed: true`); reusing it for a different click or
+     * conversion throws `external_event_id_conflict` (409).
+     */
+    externalEventId: string;
+    /**
+     * Your own id for the user, if you have one. Omit it and the conversion is
+     * recorded under the click's own user, credited to that click alone.
+     */
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    /** Event time. Defaults to now on the server. ISO 8601. */
+    ts?: string;
 }
 declare class OpenPartnerServer {
     private readonly apiUrl;
@@ -60,6 +100,14 @@ declare class OpenPartnerServer {
      * resulting attribution + commission rows.
      */
     trackEvent(params: TrackEventParams): Promise<EventResponse>;
+    /**
+     * Record a conversion against a click in one call, for when you have the
+     * click id but no identify()'d user: a lender reporting a funded loan, a
+     * CRM closing a deal. Stitches the click and records the event together.
+     * Throws `click_not_found` (404) for a click outside your program and
+     * `click_flagged` (422) for one flagged as fraud.
+     */
+    trackConversion(params: TrackConversionParams): Promise<ConversionResponse>;
     /**
      * Stitch an attribution token (cref) to a known userId. Normally the
      * browser SDK does this; use this overload if your backend receives
@@ -74,4 +122,5 @@ declare class OpenPartnerServer {
     private request;
 }
 
-export { EventResponse, IdentifyResponse, OpenPartnerServer, type OpenPartnerServerConfig, type TrackEventParams };
+export { ConversionResponse, EventResponse, IdentifyResponse, OpenPartnerServer };
+export type { OpenPartnerServerConfig, TrackConversionParams, TrackEventParams };

package/dist/server.js

@@ -63,6 +63,16 @@ var OpenPartnerServer = class {
   async trackEvent(params) {
     return this.request("/attribution/events", { method: "POST", body: params });
   }
+  /**
+   * Record a conversion against a click in one call, for when you have the
+   * click id but no identify()'d user: a lender reporting a funded loan, a
+   * CRM closing a deal. Stitches the click and records the event together.
+   * Throws `click_not_found` (404) for a click outside your program and
+   * `click_flagged` (422) for one flagged as fraud.
+   */
+  async trackConversion(params) {
+    return this.request("/attribution/conversions", { method: "POST", body: params });
+  }
   /**
    * Stitch an attribution token (cref) to a known userId. Normally the
    * browser SDK does this; use this overload if your backend receives

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/shared.ts","../src/server.ts"],"sourcesContent":["/**\n * Shared types + error class for both the browser and server entry\n * points.\n *\n * Keeping these in their own module means browser imports won't drag in\n * `fetch` polyfills or server-only code, and server imports won't touch\n * anything that references `window` or `document`.\n */\n\nexport class OpenPartnerError extends Error {\n  constructor(\n    message: string,\n    public readonly status: number,\n    public readonly code?: string,\n    public readonly detail?: unknown,\n  ) {\n    super(message);\n    this.name = 'OpenPartnerError';\n  }\n}\n\nexport interface IdentifyResponse {\n  ok: boolean;\n  identityId: string | null;\n  firstStitch: boolean;\n  backfilledAttributions?: number;\n}\n\nexport interface EventAttribution {\n  status: 'attributed' | 'no_identity' | 'no_click' | 'outside_window' | 'already_attributed';\n  model?: 'last_click' | 'first_click' | 'linear' | 'position';\n  touches?: Array<{\n    clickId: string;\n    partnerId: string;\n    weight: number;\n    attributionId: string;\n    commissionId?: string;\n  }>;\n}\n\nexport interface EventResponse {\n  ok: boolean;\n  eventId: string;\n  attribution: EventAttribution;\n}\n\n/**\n * Small fetch helper used by both entries. Normalizes non-2xx responses\n * into OpenPartnerError so callers can try/catch with a stable shape\n * instead of poking at Response objects themselves.\n */\nexport type JsonRequestInit = Omit<RequestInit, 'body'> & { body?: unknown };\n\nexport async function requestJson<T>(\n  input: string,\n  init: JsonRequestInit = {},\n  fetchImpl: typeof fetch = globalThis.fetch,\n): Promise<T> {\n  const headers = new Headers(init.headers);\n  if (init.body !== undefined && !headers.has('content-type')) {\n    headers.set('content-type', 'application/json');\n  }\n  const res = await fetchImpl(input, {\n    ...init,\n    headers,\n    body:\n      init.body === undefined\n        ? undefined\n        : typeof init.body === 'string'\n          ? init.body\n          : JSON.stringify(init.body),\n  });\n\n  const text = await res.text();\n  let body: unknown = undefined;\n  if (text) {\n    try {\n      body = JSON.parse(text);\n    } catch {\n      body = text;\n    }\n  }\n\n  if (!res.ok) {\n    const errBody = (body ?? {}) as { error?: string; detail?: unknown };\n    throw new OpenPartnerError(\n      errBody.error ?? `${res.status} ${res.statusText}`,\n      res.status,\n      errBody.error,\n      errBody.detail ?? body,\n    );\n  }\n\n  return body as T;\n}\n","/**\n * Server SDK — runs inside a merchant's backend. Used for the\n * server-to-server pieces of the attribution pipeline: posting\n * conversion events (signup / invoice_paid / custom), stitching\n * clicks to users from the backend, and reading dashboard snapshots.\n *\n * Typical integration:\n *\n *   import { OpenPartnerServer } from '@openpartner/sdk/server';\n *\n *   const op = new OpenPartnerServer({\n *     apiUrl: process.env.OPENPARTNER_API_URL!,\n *     apiKey: process.env.OPENPARTNER_API_KEY!,\n *   });\n *\n *   // On signup:\n *   await op.trackEvent({ userId, type: 'signup' });\n *\n *   // On invoice paid:\n *   await op.trackEvent({ userId, type: 'invoice_paid', value: 249, currency: 'USD' });\n */\n\nimport { OpenPartnerError, requestJson, type EventResponse, type IdentifyResponse, type JsonRequestInit } from './shared.js';\n\nexport { OpenPartnerError };\nexport type { EventResponse, IdentifyResponse };\nexport type { EventAttribution } from './shared.js';\n\nexport interface OpenPartnerServerConfig {\n  /** Base URL of the OpenPartner API. */\n  apiUrl: string;\n  /**\n   * Admin or scoped API key. For event ingest you need admin or a key\n   * with the right scope (the core API currently uses admin-only for\n   * /attribution/events). Never expose this to the browser.\n   */\n  apiKey: string;\n  /** Optional fetch override for tests or custom transports. */\n  fetch?: typeof fetch;\n}\n\nexport interface TrackEventParams {\n  /** The user the event pertains to. Must match how the browser SDK called identify(). */\n  userId: string;\n  /** Event type — typically 'signup' | 'trial_started' | 'subscription_created' | 'invoice_paid' | custom. */\n  type: string;\n  /** Dollar (or currency) value of the event, for percent-commission rules. */\n  value?: number;\n  /** ISO 4217 currency code. Defaults to USD on the server if omitted. */\n  currency?: string;\n  /** Arbitrary metadata you want to attach (stripeEventId, invoiceId, etc). */\n  metadata?: Record<string, unknown>;\n  /** Event time. Defaults to now on the server. Pass ISO 8601 to override. */\n  ts?: string;\n}\n\nexport class OpenPartnerServer {\n  private readonly apiUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(config: OpenPartnerServerConfig) {\n    if (!config.apiUrl) throw new OpenPartnerError('apiUrl is required', 400, 'config_missing');\n    if (!config.apiKey) throw new OpenPartnerError('apiKey is required', 400, 'config_missing');\n    this.apiUrl = config.apiUrl.replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n    this.fetchImpl = config.fetch ?? globalThis.fetch;\n  }\n\n  /**\n   * Record a conversion event. The server walks the userId back to a\n   * click, applies the campaign's attribution model, and writes the\n   * resulting attribution + commission rows.\n   */\n  async trackEvent(params: TrackEventParams): Promise<EventResponse> {\n    return this.request<EventResponse>('/attribution/events', { method: 'POST', body: params });\n  }\n\n  /**\n   * Stitch an attribution token (cref) to a known userId. Normally the\n   * browser SDK does this; use this overload if your backend receives\n   * the cref from the browser (e.g. as part of a signup payload) and\n   * wants to own the stitch call.\n   */\n  async identify(params: { cref: string; userId: string; ts?: number }): Promise<IdentifyResponse> {\n    return this.request<IdentifyResponse>('/attribution/identify', {\n      method: 'POST',\n      body: params,\n    });\n  }\n\n  private async request<T>(path: string, init: JsonRequestInit): Promise<T> {\n    const headers = new Headers(init.headers);\n    headers.set('authorization', `Bearer ${this.apiKey}`);\n    return requestJson<T>(\n      `${this.apiUrl}${path}`,\n      { ...init, headers },\n      // Inject the configured fetch so tests (or alternate transports)\n      // can intercept.\n      this.fetchImpl,\n    );\n  }\n}\n"],"mappings":";;;;;AASO,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC1C,YACE,SACgB,QACA,MACA,QAChB;AACA,UAAM,OAAO;AAJG;AACA;AACA;AAGhB,SAAK,OAAO;AAAA,EACd;AACF;AAkCA,eAAsB,YACpB,OACA,OAAwB,CAAC,GACzB,YAA0B,WAAW,OACzB;AACZ,QAAM,UAAU,IAAI,QAAQ,KAAK,OAAO;AACxC,MAAI,KAAK,SAAS,UAAa,CAAC,QAAQ,IAAI,cAAc,GAAG;AAC3D,YAAQ,IAAI,gBAAgB,kBAAkB;AAAA,EAChD;AACA,QAAM,MAAM,MAAM,UAAU,OAAO;AAAA,IACjC,GAAG;AAAA,IACH;AAAA,IACA,MACE,KAAK,SAAS,SACV,SACA,OAAO,KAAK,SAAS,WACnB,KAAK,OACL,KAAK,UAAU,KAAK,IAAI;AAAA,EAClC,CAAC;AAED,QAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,MAAI,OAAgB;AACpB,MAAI,MAAM;AACR,QAAI;AACF,aAAO,KAAK,MAAM,IAAI;AAAA,IACxB,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AAEA,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,UAAW,QAAQ,CAAC;AAC1B,UAAM,IAAI;AAAA,MACR,QAAQ,SAAS,GAAG,IAAI,MAAM,IAAI,IAAI,UAAU;AAAA,MAChD,IAAI;AAAA,MACJ,QAAQ;AAAA,MACR,QAAQ,UAAU;AAAA,IACpB;AAAA,EACF;AAEA,SAAO;AACT;;;ACtCO,IAAM,oBAAN,MAAwB;AAAA,EAK7B,YAAY,QAAiC;AAJ7C,wBAAiB;AACjB,wBAAiB;AACjB,wBAAiB;AAGf,QAAI,CAAC,OAAO,OAAQ,OAAM,IAAI,iBAAiB,sBAAsB,KAAK,gBAAgB;AAC1F,QAAI,CAAC,OAAO,OAAQ,OAAM,IAAI,iBAAiB,sBAAsB,KAAK,gBAAgB;AAC1F,SAAK,SAAS,OAAO,OAAO,QAAQ,OAAO,EAAE;AAC7C,SAAK,SAAS,OAAO;AACrB,SAAK,YAAY,OAAO,SAAS,WAAW;AAAA,EAC9C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,WAAW,QAAkD;AACjE,WAAO,KAAK,QAAuB,uBAAuB,EAAE,QAAQ,QAAQ,MAAM,OAAO,CAAC;AAAA,EAC5F;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,SAAS,QAAkF;AAC/F,WAAO,KAAK,QAA0B,yBAAyB;AAAA,MAC7D,QAAQ;AAAA,MACR,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AAAA,EAEA,MAAc,QAAW,MAAc,MAAmC;AACxE,UAAM,UAAU,IAAI,QAAQ,KAAK,OAAO;AACxC,YAAQ,IAAI,iBAAiB,UAAU,KAAK,MAAM,EAAE;AACpD,WAAO;AAAA,MACL,GAAG,KAAK,MAAM,GAAG,IAAI;AAAA,MACrB,EAAE,GAAG,MAAM,QAAQ;AAAA;AAAA;AAAA,MAGnB,KAAK;AAAA,IACP;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/shared.ts","../src/server.ts"],"sourcesContent":["/**\n * Shared types + error class for both the browser and server entry\n * points.\n *\n * Keeping these in their own module means browser imports won't drag in\n * `fetch` polyfills or server-only code, and server imports won't touch\n * anything that references `window` or `document`.\n */\n\nexport class OpenPartnerError extends Error {\n  constructor(\n    message: string,\n    public readonly status: number,\n    public readonly code?: string,\n    public readonly detail?: unknown,\n  ) {\n    super(message);\n    this.name = 'OpenPartnerError';\n  }\n}\n\nexport interface IdentifyResponse {\n  ok: boolean;\n  identityId: string | null;\n  firstStitch: boolean;\n  backfilledAttributions?: number;\n}\n\nexport interface EventAttribution {\n  /**\n   * 'not_attributed' only appears on a replay (`replayed: true`) of an event\n   * that didn't attribute the first time; which miss it was isn't stored.\n   * 'corrective': refund / chargeback / dispute_created / invoice_payment_failed —\n   * recorded, never attributed.\n   */\n  status:\n    | 'attributed'\n    | 'no_identity'\n    | 'no_click'\n    | 'outside_window'\n    | 'already_attributed'\n    | 'not_attributed'\n    | 'corrective';\n  model?: 'last_click' | 'first_click' | 'linear' | 'position';\n  touches?: Array<{\n    clickId: string;\n    partnerId: string;\n    weight: number;\n    attributionId: string;\n    commissionId?: string;\n  }>;\n}\n\nexport interface EventResponse {\n  ok: boolean;\n  eventId: string;\n  attribution: EventAttribution;\n  /** True when an earlier call with the same externalEventId already\n   *  recorded this event; eventId and attribution are that call's. */\n  replayed?: boolean;\n}\n\nexport interface ConversionResponse extends EventResponse {\n  /** The user the conversion was recorded under: the userId you passed, or\n   *  the click's own `click:<clickId>` user. */\n  userId: string;\n}\n\n/**\n * Small fetch helper used by both entries. Normalizes non-2xx responses\n * into OpenPartnerError so callers can try/catch with a stable shape\n * instead of poking at Response objects themselves.\n */\nexport type JsonRequestInit = Omit<RequestInit, 'body'> & { body?: unknown };\n\nexport async function requestJson<T>(\n  input: string,\n  init: JsonRequestInit = {},\n  fetchImpl: typeof fetch = globalThis.fetch,\n): Promise<T> {\n  const headers = new Headers(init.headers);\n  if (init.body !== undefined && !headers.has('content-type')) {\n    headers.set('content-type', 'application/json');\n  }\n  const res = await fetchImpl(input, {\n    ...init,\n    headers,\n    body:\n      init.body === undefined\n        ? undefined\n        : typeof init.body === 'string'\n          ? init.body\n          : JSON.stringify(init.body),\n  });\n\n  const text = await res.text();\n  let body: unknown = undefined;\n  if (text) {\n    try {\n      body = JSON.parse(text);\n    } catch {\n      body = text;\n    }\n  }\n\n  if (!res.ok) {\n    const errBody = (body ?? {}) as { error?: string; detail?: unknown };\n    throw new OpenPartnerError(\n      errBody.error ?? `${res.status} ${res.statusText}`,\n      res.status,\n      errBody.error,\n      errBody.detail ?? body,\n    );\n  }\n\n  return body as T;\n}\n","/**\n * Server SDK — runs inside a merchant's backend. Used for the\n * server-to-server pieces of the attribution pipeline: posting\n * conversion events (signup / invoice_paid / custom), stitching\n * clicks to users from the backend, and reading dashboard snapshots.\n *\n * Typical integration:\n *\n *   import { OpenPartnerServer } from '@openpartner/sdk/server';\n *\n *   const op = new OpenPartnerServer({\n *     apiUrl: process.env.OPENPARTNER_API_URL!,\n *     apiKey: process.env.OPENPARTNER_API_KEY!,\n *   });\n *\n *   // On signup:\n *   await op.trackEvent({ userId, type: 'signup' });\n *\n *   // On invoice paid — externalEventId makes retries safe:\n *   await op.trackEvent({ userId, type: 'invoice_paid', value: 249, currency: 'USD', externalEventId: invoice.id });\n *\n *   // Holding only the click id (from the link's {click_id} macro)? One call:\n *   await op.trackConversion({ clickId, type: 'loan_funded', value: 5000, externalEventId: `${loan.id}:funded` });\n */\n\nimport {\n  OpenPartnerError,\n  requestJson,\n  type ConversionResponse,\n  type EventResponse,\n  type IdentifyResponse,\n  type JsonRequestInit,\n} from './shared.js';\n\nexport { OpenPartnerError };\nexport type { ConversionResponse, EventResponse, IdentifyResponse };\nexport type { EventAttribution } from './shared.js';\n\nexport interface OpenPartnerServerConfig {\n  /** Base URL of the OpenPartner API. */\n  apiUrl: string;\n  /**\n   * Admin or scoped API key. Event ingest (/attribution/events) accepts\n   * an admin key or a scoped key with `events:write`. Never expose this\n   * to the browser.\n   */\n  apiKey: string;\n  /** Optional fetch override for tests or custom transports. */\n  fetch?: typeof fetch;\n}\n\nexport interface TrackEventParams {\n  /** The user the event pertains to. Must match how the browser SDK called identify(). */\n  userId: string;\n  /** Event type — typically 'signup' | 'trial_started' | 'subscription_created' | 'invoice_paid' | custom. */\n  type: string;\n  /** Dollar (or currency) value of the event, for percent-commission rules. */\n  value?: number;\n  /** ISO 4217 currency code. Defaults to USD on the server if omitted. */\n  currency?: string;\n  /** Arbitrary metadata you want to attach (stripeEventId, invoiceId, etc). */\n  metadata?: Record<string, unknown>;\n  /** Event time. Defaults to now on the server. Pass ISO 8601 to override. */\n  ts?: string;\n  /**\n   * Idempotency key: your system's stable id for this one event (order id,\n   * invoice id, CRM deal-stage change id), max 120 chars. Strongly\n   * recommended. A retried call with the same key returns the original\n   * event and attribution (`replayed: true`) instead of recording and\n   * commissioning it twice. Unique per event, not per order: an order's\n   * `subscription_created` and its `invoice_paid` need different keys.\n   * Reusing a key for a different userId / type / value / currency throws\n   * an `OpenPartnerError` with code `external_event_id_conflict` (409).\n   */\n  externalEventId?: string;\n}\n\nexport interface TrackConversionParams {\n  /** The click id the partner link handed you: the `{click_id}` macro in the\n   *  destination URL, or the `cref` query parameter. */\n  clickId: string;\n  /** Event type, e.g. 'loan_funded', 'opportunity_won', 'invoice_paid'. */\n  type: string;\n  /** Value of the conversion, for percent-commission rules. */\n  value?: number;\n  /** ISO 4217 currency code. Defaults to USD on the server if omitted. */\n  currency?: string;\n  /**\n   * Required idempotency key: your stable id for this one conversion (loan\n   * id plus stage, order id), max 120 chars. A retry returns the original\n   * result (`replayed: true`); reusing it for a different click or\n   * conversion throws `external_event_id_conflict` (409).\n   */\n  externalEventId: string;\n  /**\n   * Your own id for the user, if you have one. Omit it and the conversion is\n   * recorded under the click's own user, credited to that click alone.\n   */\n  userId?: string;\n  metadata?: Record<string, unknown>;\n  /** Event time. Defaults to now on the server. ISO 8601. */\n  ts?: string;\n}\n\nexport class OpenPartnerServer {\n  private readonly apiUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(config: OpenPartnerServerConfig) {\n    if (!config.apiUrl) throw new OpenPartnerError('apiUrl is required', 400, 'config_missing');\n    if (!config.apiKey) throw new OpenPartnerError('apiKey is required', 400, 'config_missing');\n    this.apiUrl = config.apiUrl.replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n    this.fetchImpl = config.fetch ?? globalThis.fetch;\n  }\n\n  /**\n   * Record a conversion event. The server walks the userId back to a\n   * click, applies the campaign's attribution model, and writes the\n   * resulting attribution + commission rows.\n   */\n  async trackEvent(params: TrackEventParams): Promise<EventResponse> {\n    return this.request<EventResponse>('/attribution/events', { method: 'POST', body: params });\n  }\n\n  /**\n   * Record a conversion against a click in one call, for when you have the\n   * click id but no identify()'d user: a lender reporting a funded loan, a\n   * CRM closing a deal. Stitches the click and records the event together.\n   * Throws `click_not_found` (404) for a click outside your program and\n   * `click_flagged` (422) for one flagged as fraud.\n   */\n  async trackConversion(params: TrackConversionParams): Promise<ConversionResponse> {\n    return this.request<ConversionResponse>('/attribution/conversions', { method: 'POST', body: params });\n  }\n\n  /**\n   * Stitch an attribution token (cref) to a known userId. Normally the\n   * browser SDK does this; use this overload if your backend receives\n   * the cref from the browser (e.g. as part of a signup payload) and\n   * wants to own the stitch call.\n   */\n  async identify(params: { cref: string; userId: string; ts?: number }): Promise<IdentifyResponse> {\n    return this.request<IdentifyResponse>('/attribution/identify', {\n      method: 'POST',\n      body: params,\n    });\n  }\n\n  private async request<T>(path: string, init: JsonRequestInit): Promise<T> {\n    const headers = new Headers(init.headers);\n    headers.set('authorization', `Bearer ${this.apiKey}`);\n    return requestJson<T>(\n      `${this.apiUrl}${path}`,\n      { ...init, headers },\n      // Inject the configured fetch so tests (or alternate transports)\n      // can intercept.\n      this.fetchImpl,\n    );\n  }\n}\n"],"mappings":";;;;;AASO,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC1C,YACE,SACgB,QACA,MACA,QAChB;AACA,UAAM,OAAO;AAJG;AACA;AACA;AAGhB,SAAK,OAAO;AAAA,EACd;AACF;AAwDA,eAAsB,YACpB,OACA,OAAwB,CAAC,GACzB,YAA0B,WAAW,OACzB;AACZ,QAAM,UAAU,IAAI,QAAQ,KAAK,OAAO;AACxC,MAAI,KAAK,SAAS,UAAa,CAAC,QAAQ,IAAI,cAAc,GAAG;AAC3D,YAAQ,IAAI,gBAAgB,kBAAkB;AAAA,EAChD;AACA,QAAM,MAAM,MAAM,UAAU,OAAO;AAAA,IACjC,GAAG;AAAA,IACH;AAAA,IACA,MACE,KAAK,SAAS,SACV,SACA,OAAO,KAAK,SAAS,WACnB,KAAK,OACL,KAAK,UAAU,KAAK,IAAI;AAAA,EAClC,CAAC;AAED,QAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,MAAI,OAAgB;AACpB,MAAI,MAAM;AACR,QAAI;AACF,aAAO,KAAK,MAAM,IAAI;AAAA,IACxB,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AAEA,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,UAAW,QAAQ,CAAC;AAC1B,UAAM,IAAI;AAAA,MACR,QAAQ,SAAS,GAAG,IAAI,MAAM,IAAI,IAAI,UAAU;AAAA,MAChD,IAAI;AAAA,MACJ,QAAQ;AAAA,MACR,QAAQ,UAAU;AAAA,IACpB;AAAA,EACF;AAEA,SAAO;AACT;;;ACZO,IAAM,oBAAN,MAAwB;AAAA,EAK7B,YAAY,QAAiC;AAJ7C,wBAAiB;AACjB,wBAAiB;AACjB,wBAAiB;AAGf,QAAI,CAAC,OAAO,OAAQ,OAAM,IAAI,iBAAiB,sBAAsB,KAAK,gBAAgB;AAC1F,QAAI,CAAC,OAAO,OAAQ,OAAM,IAAI,iBAAiB,sBAAsB,KAAK,gBAAgB;AAC1F,SAAK,SAAS,OAAO,OAAO,QAAQ,OAAO,EAAE;AAC7C,SAAK,SAAS,OAAO;AACrB,SAAK,YAAY,OAAO,SAAS,WAAW;AAAA,EAC9C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,WAAW,QAAkD;AACjE,WAAO,KAAK,QAAuB,uBAAuB,EAAE,QAAQ,QAAQ,MAAM,OAAO,CAAC;AAAA,EAC5F;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,gBAAgB,QAA4D;AAChF,WAAO,KAAK,QAA4B,4BAA4B,EAAE,QAAQ,QAAQ,MAAM,OAAO,CAAC;AAAA,EACtG;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,SAAS,QAAkF;AAC/F,WAAO,KAAK,QAA0B,yBAAyB;AAAA,MAC7D,QAAQ;AAAA,MACR,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AAAA,EAEA,MAAc,QAAW,MAAc,MAAmC;AACxE,UAAM,UAAU,IAAI,QAAQ,KAAK,OAAO;AACxC,YAAQ,IAAI,iBAAiB,UAAU,KAAK,MAAM,EAAE;AACpD,WAAO;AAAA,MACL,GAAG,KAAK,MAAM,GAAG,IAAI;AAAA,MACrB,EAAE,GAAG,MAAM,QAAQ;AAAA;AAAA;AAAA,MAGnB,KAAK;AAAA,IACP;AAAA,EACF;AACF;","names":[]}

package/dist/{shared-CLfBjPeb.d.cts → shared-dh1vlldf.d.cts}

@@ -9,8 +9,8 @@
 declare class OpenPartnerError extends Error {
     readonly status: number;
     readonly code?: string | undefined;
-    readonly detail?: unknown;
-    constructor(message: string, status: number, code?: string | undefined, detail?: unknown);
+    readonly detail?: unknown | undefined;
+    constructor(message: string, status: number, code?: string | undefined, detail?: unknown | undefined);
 }
 interface IdentifyResponse {
     ok: boolean;
@@ -19,7 +19,13 @@ interface IdentifyResponse {
     backfilledAttributions?: number;
 }
 interface EventAttribution {
-    status: 'attributed' | 'no_identity' | 'no_click' | 'outside_window' | 'already_attributed';
+    /**
+     * 'not_attributed' only appears on a replay (`replayed: true`) of an event
+     * that didn't attribute the first time; which miss it was isn't stored.
+     * 'corrective': refund / chargeback / dispute_created / invoice_payment_failed —
+     * recorded, never attributed.
+     */
+    status: 'attributed' | 'no_identity' | 'no_click' | 'outside_window' | 'already_attributed' | 'not_attributed' | 'corrective';
     model?: 'last_click' | 'first_click' | 'linear' | 'position';
     touches?: Array<{
         clickId: string;
@@ -33,6 +39,15 @@ interface EventResponse {
     ok: boolean;
     eventId: string;
     attribution: EventAttribution;
+    /** True when an earlier call with the same externalEventId already
+     *  recorded this event; eventId and attribution are that call's. */
+    replayed?: boolean;
+}
+interface ConversionResponse extends EventResponse {
+    /** The user the conversion was recorded under: the userId you passed, or
+     *  the click's own `click:<clickId>` user. */
+    userId: string;
 }
 
-export { type EventResponse as E, type IdentifyResponse as I, OpenPartnerError as O, type EventAttribution as a };
+export { OpenPartnerError as O };
+export type { ConversionResponse as C, EventResponse as E, IdentifyResponse as I, EventAttribution as a };

package/dist/{shared-CLfBjPeb.d.ts → shared-dh1vlldf.d.ts}

@@ -9,8 +9,8 @@
 declare class OpenPartnerError extends Error {
     readonly status: number;
     readonly code?: string | undefined;
-    readonly detail?: unknown;
-    constructor(message: string, status: number, code?: string | undefined, detail?: unknown);
+    readonly detail?: unknown | undefined;
+    constructor(message: string, status: number, code?: string | undefined, detail?: unknown | undefined);
 }
 interface IdentifyResponse {
     ok: boolean;
@@ -19,7 +19,13 @@ interface IdentifyResponse {
     backfilledAttributions?: number;
 }
 interface EventAttribution {
-    status: 'attributed' | 'no_identity' | 'no_click' | 'outside_window' | 'already_attributed';
+    /**
+     * 'not_attributed' only appears on a replay (`replayed: true`) of an event
+     * that didn't attribute the first time; which miss it was isn't stored.
+     * 'corrective': refund / chargeback / dispute_created / invoice_payment_failed —
+     * recorded, never attributed.
+     */
+    status: 'attributed' | 'no_identity' | 'no_click' | 'outside_window' | 'already_attributed' | 'not_attributed' | 'corrective';
     model?: 'last_click' | 'first_click' | 'linear' | 'position';
     touches?: Array<{
         clickId: string;
@@ -33,6 +39,15 @@ interface EventResponse {
     ok: boolean;
     eventId: string;
     attribution: EventAttribution;
+    /** True when an earlier call with the same externalEventId already
+     *  recorded this event; eventId and attribution are that call's. */
+    replayed?: boolean;
+}
+interface ConversionResponse extends EventResponse {
+    /** The user the conversion was recorded under: the userId you passed, or
+     *  the click's own `click:<clickId>` user. */
+    userId: string;
 }
 
-export { type EventResponse as E, type IdentifyResponse as I, OpenPartnerError as O, type EventAttribution as a };
+export { OpenPartnerError as O };
+export type { ConversionResponse as C, EventResponse as E, IdentifyResponse as I, EventAttribution as a };