@joryio/web-sdk 0.0.0-stage → 1.3.0

package/src/core/utm.ts

@@ -0,0 +1,304 @@
+/**
+ * UTM Parameter Manager for tracking campaign attribution
+ * Supports first-touch, last-touch, and session-level attribution
+ */
+
+import { StorageManager } from './storage';
+import { Logger } from '../utils/logger';
+
+const FIRST_TOUCH_KEY = 'first_touch_utm';
+const LAST_TOUCH_KEY = 'last_touch_utm';
+const SESSION_UTM_KEY = 'session_utm';
+const SESSION_REFERRER_KEY = 'session_referrer';
+const SESSION_LANDING_PAGE_KEY = 'session_landing_page';
+
+export interface UTMParameters {
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_content?: string;
+  utm_term?: string;
+  referrer?: string;
+  landing_page?: string;
+  captured_at?: number;
+}
+
+export interface UTMData {
+  current: UTMParameters | null;      // Current session UTM
+  firstTouch: UTMParameters | null;   // First ever UTM (lifetime attribution)
+  lastTouch: UTMParameters | null;    // Most recent UTM (last touch attribution)
+}
+
+export class UTMManager {
+  private storage: StorageManager;
+  private logger: Logger;
+  private resetSessionOnNewCampaign: boolean;
+  // Whether the current URL's UTM differs from the STORED session UTM. Computed
+  // BEFORE captureUTMParameters() overwrites SESSION_UTM_KEY, otherwise the
+  // comparison always sees the just-written value and returns false.
+  private newCampaignDetected: boolean = false;
+
+  constructor(
+    storage: StorageManager,
+    logger: Logger,
+    resetSessionOnNewCampaign: boolean = false,
+  ) {
+    this.storage = storage;
+    this.logger = logger;
+    this.resetSessionOnNewCampaign = resetSessionOnNewCampaign;
+
+    // Compare the incoming URL against the previously stored session UTM BEFORE
+    // capturing (which overwrites it), so hasNewCampaign() reflects the real
+    // transition. Only relevant when the reset gate is on.
+    if (this.resetSessionOnNewCampaign) {
+      this.newCampaignDetected = this.detectNewCampaign();
+    }
+
+    // Capture UTM parameters on initialization
+    this.captureUTMParameters();
+  }
+
+  /**
+   * Capture UTM parameters from current URL
+   */
+  private captureUTMParameters(): void {
+    if (typeof window === 'undefined') {
+      return;
+    }
+
+    const urlParams = new URLSearchParams(window.location.search);
+    const utm: UTMParameters = {};
+    let hasUTM = false;
+
+    // Capture all 5 standard UTM parameters
+    const utmParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'] as const;
+
+    for (const param of utmParams) {
+      const value = urlParams.get(param);
+      if (value) {
+        utm[param] = value;
+        hasUTM = true;
+      }
+    }
+
+    // Capture referrer (if present)
+    if (document.referrer) {
+      utm.referrer = document.referrer;
+    }
+
+    // Capture landing page
+    utm.landing_page = window.location.href;
+    utm.captured_at = Date.now();
+
+    // If no UTM parameters found, check if we should still track referrer
+    if (!hasUTM) {
+      // Only track referrer/landing page for session if this is a new session
+      const existingSession = this.storage.get<UTMParameters>(SESSION_UTM_KEY);
+      if (!existingSession) {
+        this.storage.set(SESSION_UTM_KEY, utm);
+        this.storage.set(SESSION_REFERRER_KEY, utm.referrer || null);
+        this.storage.set(SESSION_LANDING_PAGE_KEY, utm.landing_page);
+        this.logger.debug('Captured session referrer and landing page');
+      }
+      return;
+    }
+
+    this.logger.debug('Captured UTM parameters:', utm);
+
+    // Store as current session UTM
+    this.storage.set(SESSION_UTM_KEY, utm);
+    this.storage.set(SESSION_REFERRER_KEY, utm.referrer || null);
+    this.storage.set(SESSION_LANDING_PAGE_KEY, utm.landing_page);
+
+    // Store as first touch if not already set (lifetime attribution)
+    const firstTouch = this.storage.get<UTMParameters>(FIRST_TOUCH_KEY);
+    if (!firstTouch) {
+      this.storage.set(FIRST_TOUCH_KEY, utm);
+      this.logger.debug('Set first touch UTM:', utm);
+    }
+
+    // Always update last touch (most recent attribution)
+    this.storage.set(LAST_TOUCH_KEY, utm);
+    this.logger.debug('Updated last touch UTM:', utm);
+  }
+
+  /**
+   * Get all UTM data (current, first touch, last touch)
+   */
+  getUTMData(): UTMData {
+    return {
+      current: this.storage.get<UTMParameters>(SESSION_UTM_KEY) || null,
+      firstTouch: this.storage.get<UTMParameters>(FIRST_TOUCH_KEY) || null,
+      lastTouch: this.storage.get<UTMParameters>(LAST_TOUCH_KEY) || null,
+    };
+  }
+
+  /**
+   * Get current session UTM parameters
+   */
+  getCurrentUTM(): UTMParameters | null {
+    return this.storage.get<UTMParameters>(SESSION_UTM_KEY) || null;
+  }
+
+  /**
+   * Get first touch UTM parameters (lifetime attribution)
+   */
+  getFirstTouchUTM(): UTMParameters | null {
+    return this.storage.get<UTMParameters>(FIRST_TOUCH_KEY) || null;
+  }
+
+  /**
+   * Get last touch UTM parameters (most recent attribution)
+   */
+  getLastTouchUTM(): UTMParameters | null {
+    return this.storage.get<UTMParameters>(LAST_TOUCH_KEY) || null;
+  }
+
+  /**
+   * Get session referrer
+   */
+  getSessionReferrer(): string | null {
+    return this.storage.get<string>(SESSION_REFERRER_KEY) || null;
+  }
+
+  /**
+   * Get session landing page
+   */
+  getSessionLandingPage(): string | null {
+    return this.storage.get<string>(SESSION_LANDING_PAGE_KEY) || null;
+  }
+
+  /**
+   * Whether a new campaign was detected on the current URL, compared against
+   * the session UTM as it was BEFORE this page's capture overwrote it. The
+   * comparison is done in the constructor / updateUTM() (pre-capture); this
+   * getter just returns the captured result so the answer isn't clobbered.
+   */
+  hasNewCampaign(): boolean {
+    return this.newCampaignDetected;
+  }
+
+  /**
+   * Compare the current URL's UTM parameters against the STORED session UTM.
+   * Returns true if the URL carries campaign params that differ from session.
+   * MUST be called before captureUTMParameters() overwrites SESSION_UTM_KEY.
+   */
+  private detectNewCampaign(): boolean {
+    if (typeof window === 'undefined') {
+      return false;
+    }
+
+    const urlParams = new URLSearchParams(window.location.search);
+    const currentSessionUTM = this.getCurrentUTM();
+
+    // If no session UTM exists, check if URL has any UTM params
+    if (!currentSessionUTM) {
+      return urlParams.has('utm_source') ||
+             urlParams.has('utm_medium') ||
+             urlParams.has('utm_campaign');
+    }
+
+    // Check if any UTM parameter has changed
+    const utmParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'] as const;
+
+    for (const param of utmParams) {
+      const urlValue = urlParams.get(param);
+      const sessionValue = currentSessionUTM[param];
+
+      if (urlValue && urlValue !== sessionValue) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Manually update UTM parameters (for SPAs that change URL without reload).
+   * Re-runs the new-campaign detection against the stored session UTM BEFORE
+   * capturing overwrites it, so a subsequent hasNewCampaign() is accurate.
+   */
+  updateUTM(): void {
+    if (this.resetSessionOnNewCampaign) {
+      this.newCampaignDetected = this.detectNewCampaign();
+    }
+    this.captureUTMParameters();
+  }
+
+  /**
+   * Clear session UTM (keeps first/last touch for attribution)
+   */
+  clearSessionUTM(): void {
+    this.storage.remove(SESSION_UTM_KEY);
+    this.storage.remove(SESSION_REFERRER_KEY);
+    this.storage.remove(SESSION_LANDING_PAGE_KEY);
+    this.logger.debug('Cleared session UTM');
+  }
+
+  /**
+   * Clear all UTM data (including first/last touch)
+   */
+  clearAllUTM(): void {
+    this.storage.remove(SESSION_UTM_KEY);
+    this.storage.remove(FIRST_TOUCH_KEY);
+    this.storage.remove(LAST_TOUCH_KEY);
+    this.storage.remove(SESSION_REFERRER_KEY);
+    this.storage.remove(SESSION_LANDING_PAGE_KEY);
+    this.logger.debug('Cleared all UTM data');
+  }
+
+  /**
+   * Reset UTM tracking (used on user logout)
+   */
+  reset(): void {
+    this.clearAllUTM();
+  }
+
+  /**
+   * Get UTM parameters formatted for event properties
+   */
+  getUTMProperties(): Record<string, any> {
+    const current = this.getCurrentUTM();
+    const firstTouch = this.getFirstTouchUTM();
+    const lastTouch = this.getLastTouchUTM();
+
+    const properties: Record<string, any> = {};
+
+    // Add current session UTM
+    if (current) {
+      if (current.utm_source) properties.utm_source = current.utm_source;
+      if (current.utm_medium) properties.utm_medium = current.utm_medium;
+      if (current.utm_campaign) properties.utm_campaign = current.utm_campaign;
+      if (current.utm_content) properties.utm_content = current.utm_content;
+      if (current.utm_term) properties.utm_term = current.utm_term;
+      if (current.referrer) properties.referrer = current.referrer;
+      if (current.landing_page) properties.landing_page = current.landing_page;
+    }
+
+    // Add first touch attribution
+    if (firstTouch) {
+      if (firstTouch.utm_source) properties.first_touch_utm_source = firstTouch.utm_source;
+      if (firstTouch.utm_medium) properties.first_touch_utm_medium = firstTouch.utm_medium;
+      if (firstTouch.utm_campaign) properties.first_touch_utm_campaign = firstTouch.utm_campaign;
+      if (firstTouch.utm_content) properties.first_touch_utm_content = firstTouch.utm_content;
+      if (firstTouch.utm_term) properties.first_touch_utm_term = firstTouch.utm_term;
+      if (firstTouch.referrer) properties.first_touch_referrer = firstTouch.referrer;
+      if (firstTouch.landing_page) properties.first_touch_landing_page = firstTouch.landing_page;
+      if (firstTouch.captured_at) properties.first_touch_captured_at = new Date(firstTouch.captured_at).toISOString();
+    }
+
+    // Add last touch attribution
+    if (lastTouch && lastTouch !== current) {
+      if (lastTouch.utm_source) properties.last_touch_utm_source = lastTouch.utm_source;
+      if (lastTouch.utm_medium) properties.last_touch_utm_medium = lastTouch.utm_medium;
+      if (lastTouch.utm_campaign) properties.last_touch_utm_campaign = lastTouch.utm_campaign;
+      if (lastTouch.utm_content) properties.last_touch_utm_content = lastTouch.utm_content;
+      if (lastTouch.utm_term) properties.last_touch_utm_term = lastTouch.utm_term;
+      if (lastTouch.referrer) properties.last_touch_referrer = lastTouch.referrer;
+      if (lastTouch.landing_page) properties.last_touch_landing_page = lastTouch.landing_page;
+      if (lastTouch.captured_at) properties.last_touch_captured_at = new Date(lastTouch.captured_at).toISOString();
+    }
+
+    return properties;
+  }
+}

package/src/core/values.ts

@@ -0,0 +1,85 @@
+/**
+ * Values the SDK can carry to the API (rule 49, the same on every SDK).
+ *
+ * JSON has no NaN or Infinity: `JSON.stringify` writes them as `null`, so an
+ * attribute of NaN silently became null on the profile - and a circular
+ * object or a BigInt made `JSON.stringify` THROW, which the network layer
+ * took for "offline" and retried forever. Because every attribute request
+ * carries the oldest pending write of every key, one such value held every
+ * later attribute write (and every in-app sync) of the page.
+ *
+ * Now a value is checked when it enters the SDK: the key holding a bad value
+ * is dropped with a warning, and the rest of the call goes ahead.
+ */
+
+/** Deeper than this is treated as unserializable (it would blow the stack). */
+const MAX_DEPTH = 100;
+
+/** Why this value cannot be sent, or null when it can. */
+export function valueProblem(value: unknown): string | null {
+  const ancestors: object[] = [];
+  const walk = (v: unknown, depth: number): string | null => {
+    switch (typeof v) {
+      case 'number':
+        return Number.isFinite(v) ? null : 'a non-finite number (NaN or Infinity)';
+      case 'bigint':
+        return 'a BigInt';
+      case 'function':
+        return 'a function';
+      case 'symbol':
+        return 'a symbol';
+      case 'object': {
+        if (v === null) return null;
+        if (depth > MAX_DEPTH) return `a value nested deeper than ${MAX_DEPTH} levels`;
+        // toJSON (a Date, say) decides its own form; serialized below.
+        if (typeof (v as any).toJSON === 'function') {
+          try {
+            JSON.stringify(v);
+            return null;
+          } catch {
+            return 'a value that cannot be serialized';
+          }
+        }
+        if (ancestors.includes(v as object)) return 'a circular reference';
+        ancestors.push(v as object);
+        try {
+          const children = Array.isArray(v) ? v : Object.values(v as Record<string, unknown>);
+          for (const child of children) {
+            const problem = walk(child, depth + 1);
+            if (problem) return problem;
+          }
+        } finally {
+          ancestors.pop();
+        }
+        return null;
+      }
+      default:
+        return null; // string, boolean, undefined
+    }
+  };
+  try {
+    return walk(value, 1);
+  } catch {
+    return 'a value that cannot be serialized';
+  }
+}
+
+/**
+ * A copy of `values` without the keys whose value cannot be sent; each one
+ * dropped is reported through `warn`.
+ */
+export function withoutUnsendableValues(
+  values: Record<string, any>,
+  warn: (key: string, problem: string) => void,
+): Record<string, any> {
+  const out: Record<string, any> = {};
+  for (const key of Object.keys(values)) {
+    const problem = valueProblem(values[key]);
+    if (problem) {
+      warn(key, problem);
+      continue;
+    }
+    out[key] = values[key];
+  }
+  return out;
+}

package/src/core/write-retry.ts

@@ -0,0 +1,136 @@
+import type { NetworkResponse } from './network';
+
+/**
+ * Who a write is about, captured when the call was made. `userId` is absent
+ * for a write made while the visitor was anonymous; it is filled in at SEND
+ * time when that anonymous id is still the current one (contract item 38).
+ */
+export interface WriteOwner {
+  anonymousId: string;
+  userId?: string;
+}
+
+/**
+ * A profile write described as DATA, so it can be kept in storage and sent on
+ * a later page view. Closures die with the page; these survive navigation.
+ */
+export type WriteRecord =
+  | {
+      kind: 'alias';
+      payload: { anonymousId: string; userId?: string; aliasLabel: string; aliasName: string };
+    }
+  | {
+      kind: 'subscription';
+      payload: { channel: any; status: any; userId?: string; anonymousId: string };
+    }
+  | {
+      kind: 'group';
+      payload: { groupId: string; channel: any; action: 'subscribe' | 'unsubscribe'; userId?: string; anonymousId: string };
+    }
+  | {
+      /** The `tracking_opted_out` profile marker (contract items 33 and 36). */
+      kind: 'marker';
+      payload: { value: boolean; userId?: string; anonymousId: string };
+    };
+
+/** @deprecated the pre-1.3.0 name; kept for state stored by an earlier build. */
+export type DeferredWriteRecord = WriteRecord;
+
+/** Hands a write to the SDK's outbox. Provided by JoryioSDK. */
+export type WriteRunner = (label: string, record: WriteRecord) => void;
+
+/**
+ * A WITHDRAWAL is always delivered (contract item 36): an unsubscribe, a
+ * group unsubscribe and the opt-out marker set to `true`. Opt-out, consent
+ * denied or pending, and wipeData() stop every other write - never these,
+ * because they are how the server learns that the person said no.
+ */
+export function isWithdrawal(record: WriteRecord): boolean {
+  switch (record.kind) {
+    case 'subscription':
+      return record.payload.status === 'unsubscribed';
+    case 'group':
+      return record.payload.action === 'unsubscribe';
+    case 'marker':
+      return record.payload.value === true;
+    default:
+      return false;
+  }
+}
+
+/**
+ * The same caps on every SDK (contract item 40): a 404 "no profile yet" is
+ * tried at most 5 times; any other retryable SERVER answer (a 401 for the
+ * current user, a 2xx with `success: false`) at most 10 times. Offline,
+ * timeouts, 429 and 5xx never count - they are waited out with a growing
+ * backoff instead.
+ */
+export const WRITE_MAX_ATTEMPTS = 10;
+export const WRITE_MAX_NOT_FOUND_ATTEMPTS = 5;
+
+/** Waits before the 2nd through 10th attempt; later waits stay at the last value. */
+export const WRITE_RETRY_DELAYS_MS = [2000, 5000, 15000, 30000, 60000, 60000, 60000, 60000, 60000];
+/** The longest wait between two attempts of one write, whatever the server or the backoff says. */
+export const WRITE_MAX_RETRY_DELAY_MS = 5 * 60 * 1000;
+
+/** Wait before the next attempt, after `failures` failed ones. */
+export function writeRetryDelay(failures: number, retryAfterMs?: number): number {
+  const base = WRITE_RETRY_DELAYS_MS[Math.min(Math.max(failures, 1), WRITE_RETRY_DELAYS_MS.length) - 1];
+  const grown = failures > WRITE_RETRY_DELAYS_MS.length
+    ? Math.min(base * Math.pow(2, failures - WRITE_RETRY_DELAYS_MS.length), WRITE_MAX_RETRY_DELAY_MS)
+    : base;
+  return Math.min(Math.max(grown, retryAfterMs ?? 0), WRITE_MAX_RETRY_DELAY_MS);
+}
+
+/**
+ * What to do with a write after one answer. The ONE rule every profile write
+ * follows (contract item 40) - subscriptions, aliases, attributes, the
+ * opt-out marker, push unregister and identify:
+ *
+ *  - `done`: stored.
+ *  - `retry`: try again later. `counts` says whether the attempt counts toward
+ *    the cap (`notFound` selects the 404 cap).
+ *  - `drop`: refused for good (400, 403, 409, 413, 422, other 4xx), or an
+ *    SDK-authentication 401 for a user who is no longer the current one - no
+ *    token for them will ever be set again (contract item 39).
+ *  - `hold`: the key was refused (401 that is not SDK auth): nothing is sent
+ *    for the rest of the page view; the write is kept for the next one.
+ *
+ * A 402 (ingestion paused for the workspace) is a `retry` that never counts
+ * (rule 50): it must not stop the outbox, because WITHDRAWALS queued behind
+ * the refused write are still accepted by the server. The SDK's gate holds
+ * every non-withdrawal while the pause lasts.
+ */
+export type WriteVerdict =
+  | { action: 'done' }
+  | { action: 'retry'; counts: boolean; notFound?: boolean; retryAfterMs?: number }
+  | { action: 'drop'; reason: string }
+  | { action: 'hold'; reason: string };
+
+export function classifyWriteResponse(
+  res: NetworkResponse,
+  ctx: { isSdkAuthError: boolean; ownerIsCurrentUser: boolean },
+): WriteVerdict {
+  if (res.ok) return { action: 'done' };
+  if (res.softFailure) return { action: 'retry', counts: true };
+  const status = res.status;
+  if (status === 0 || status === 408 || status === 429 || status >= 500) {
+    return { action: 'retry', counts: false, retryAfterMs: res.retryAfterMs };
+  }
+  if (status === 404) return { action: 'retry', counts: true, notFound: true };
+  if (status === 401) {
+    if (!ctx.isSdkAuthError) return { action: 'hold', reason: 'the SDK key was refused (401)' };
+    if (!ctx.ownerIsCurrentUser) {
+      return { action: 'drop', reason: 'SDK authentication refused a write of a user who is no longer signed in (401)' };
+    }
+    return { action: 'retry', counts: true };
+  }
+  // Paused workspace: wait, never count, never stop the withdrawals behind it.
+  if (status === 402) return { action: 'retry', counts: false, retryAfterMs: res.retryAfterMs };
+  return { action: 'drop', reason: `refused by the server (HTTP ${status})` };
+}
+
+/** True once a write has used up its attempts. */
+export function writeAttemptsExhausted(attempts: number, notFoundAttempts: number): boolean {
+  return attempts >= WRITE_MAX_ATTEMPTS || notFoundAttempts >= WRITE_MAX_NOT_FOUND_ATTEMPTS;
+}