@drip-apex/sdk 0.1.0

package/src/runtime-tools.ts

@@ -0,0 +1,403 @@
+import { normalizeDataLayerEntry } from "./data-layer-normalize";
+
+type Cleanup = () => void;
+
+type DataLayerEntry = Record<string, unknown>;
+type DataLayerMatcher = Record<string, unknown> | Array<[string, unknown]>;
+
+type RuntimeToolsEnvironment = {
+  document?: Document;
+  window?: Window & typeof globalThis;
+  location?: Location;
+  track?: (type: string, data?: Record<string, unknown>) => void;
+  trackGoal?: (goalId: string, data?: Record<string, unknown>) => void;
+  signal?: (key: string, value: unknown, ttlDays?: number) => void;
+  reInit?: (forceReapply?: boolean) => unknown;
+  get?: (key: string) => unknown;
+};
+
+export type WaitForElementOptions = {
+  root?: ParentNode;
+  once?: boolean;
+  timeoutMs?: number;
+};
+
+export type DomChangedOptions = {
+  root?: Node;
+  subtree?: boolean;
+  debounceMs?: number;
+};
+
+export type ElementInViewOptions = {
+  root?: Element | Document | null;
+  rootMargin?: string;
+  threshold?: number;
+  once?: boolean;
+  timeoutMs?: number;
+};
+
+export type DataLayerOptions = {
+  layerName?: string;
+  once?: boolean;
+  timeoutMs?: number;
+};
+
+export type ApexRuntimeTools = {
+  waitForElement: (
+    selector: string,
+    callback: (element: Element) => void,
+    options?: WaitForElementOptions,
+  ) => Cleanup;
+  elementIsInView: (
+    selector: string,
+    callback: (element: Element) => void,
+    options?: ElementInViewOptions | boolean,
+  ) => Cleanup;
+  domChanged: (
+    callback: (mutations: MutationRecord[]) => void,
+    options?: DomChangedOptions,
+  ) => Cleanup;
+  domLoaded: (callback: () => void) => Cleanup;
+  waitForDataLayer: (
+    matcher: DataLayerMatcher,
+    callback: (entry: DataLayerEntry) => void,
+    options?: DataLayerOptions,
+  ) => Cleanup;
+  track: (type: string, data?: Record<string, unknown>) => void;
+  trackGoal: (goalId: string, data?: Record<string, unknown>) => void;
+  signal: (key: string, value: unknown, ttlDays?: number) => void;
+  redirect: (target: string) => void;
+  reInit: (forceReapply?: boolean) => unknown;
+  get: (key: string) => unknown;
+};
+
+function noopCleanup(): Cleanup {
+  return () => {};
+}
+
+function readDocument(env: RuntimeToolsEnvironment): Document | undefined {
+  return env.document ?? (typeof document !== "undefined" ? document : undefined);
+}
+
+function readWindow(
+  env: RuntimeToolsEnvironment,
+): (Window & typeof globalThis) | undefined {
+  return env.window ?? (typeof window !== "undefined" ? window : undefined);
+}
+
+function readLocation(env: RuntimeToolsEnvironment): Location | undefined {
+  return env.location ?? (typeof location !== "undefined" ? location : undefined);
+}
+
+function safeCallback<T>(callback: (value: T) => void, value: T): void {
+  try {
+    callback(value);
+  } catch {}
+}
+
+function isElement(value: unknown): value is Element {
+  return typeof Element !== "undefined" && value instanceof Element;
+}
+
+function isDocument(value: unknown): value is Document {
+  return typeof Document !== "undefined" && value instanceof Document;
+}
+
+function collectMatches(root: ParentNode, selector: string): Element[] {
+  const matches: Element[] = [];
+  if (isElement(root) && root.matches(selector)) {
+    matches.push(root);
+  }
+  try {
+    root.querySelectorAll(selector).forEach((element) => matches.push(element));
+  } catch {}
+  return matches;
+}
+
+function observeRootFor(root: ParentNode, doc: Document): Node | null {
+  if (isDocument(root)) {
+    return root.documentElement ?? root.body;
+  }
+  if (isElement(root)) return root;
+  return doc.documentElement ?? doc.body;
+}
+
+function normalizeInViewOptions(
+  options: ElementInViewOptions | boolean | undefined,
+): ElementInViewOptions {
+  if (typeof options === "boolean") return { once: !options };
+  return options ?? {};
+}
+
+function normalizeMatcher(matcher: DataLayerMatcher): Array<[string, unknown]> {
+  return Array.isArray(matcher) ? matcher : Object.entries(matcher);
+}
+
+function matchesDataLayerEntry(
+  entry: unknown,
+  matcher: DataLayerMatcher,
+): entry is DataLayerEntry {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+  const record = entry as DataLayerEntry;
+  return normalizeMatcher(matcher).every(([key, expected]) => {
+    if (expected instanceof RegExp) {
+      return expected.test(String(record[key] ?? ""));
+    }
+    return record[key] === expected;
+  });
+}
+
+export function createApexRuntimeTools(
+  env: RuntimeToolsEnvironment = {},
+): ApexRuntimeTools {
+  const tools: ApexRuntimeTools = {
+    waitForElement(
+      selector: string,
+      callback: (element: Element) => void,
+      options: WaitForElementOptions = {},
+    ): Cleanup {
+      const doc = readDocument(env);
+      if (!doc || !selector.trim()) return noopCleanup();
+      const root = options.root ?? doc;
+      const seen = new WeakSet<Element>();
+      let active = true;
+      let observer: MutationObserver | null = null;
+      let timeoutId: number | null = null;
+
+      const stop = () => {
+        active = false;
+        observer?.disconnect();
+        observer = null;
+        if (timeoutId !== null) {
+          readWindow(env)?.clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+      };
+
+      const handle = (scope: ParentNode) => {
+        if (!active) return;
+        for (const element of collectMatches(scope, selector)) {
+          if (seen.has(element)) continue;
+          seen.add(element);
+          safeCallback(callback, element);
+          if (options.once !== false) {
+            stop();
+            return;
+          }
+        }
+      };
+
+      handle(root);
+      if (!active || typeof MutationObserver === "undefined") return stop;
+
+      const observeTarget = observeRootFor(root, doc);
+      if (!observeTarget) return stop;
+      observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          mutation.addedNodes.forEach((node) => {
+            if (isElement(node)) handle(node);
+          });
+        }
+      });
+      observer.observe(observeTarget, { childList: true, subtree: true });
+
+      if (options.timeoutMs && options.timeoutMs > 0) {
+        timeoutId = readWindow(env)?.setTimeout(stop, options.timeoutMs) ?? null;
+      }
+      return stop;
+    },
+
+    elementIsInView(
+      selector: string,
+      callback: (element: Element) => void,
+      rawOptions?: ElementInViewOptions | boolean,
+    ): Cleanup {
+      const doc = readDocument(env);
+      const win = readWindow(env);
+      if (!doc || !win || !selector.trim()) return noopCleanup();
+      const options = normalizeInViewOptions(rawOptions);
+      const once = options.once !== false;
+      const observed = new WeakSet<Element>();
+      const cleanups: Cleanup[] = [];
+      let observer: IntersectionObserver | null = null;
+
+      const stop = () => {
+        observer?.disconnect();
+        observer = null;
+        cleanups.splice(0).forEach((cleanup) => cleanup());
+      };
+
+      if (typeof IntersectionObserver === "undefined") {
+        return tools.waitForElement(
+          selector,
+          (element: Element) => {
+            const rect = element.getBoundingClientRect();
+            const inView =
+              rect.width > 0 &&
+              rect.height > 0 &&
+              rect.bottom >= 0 &&
+              rect.right >= 0 &&
+              rect.top <= win.innerHeight &&
+              rect.left <= win.innerWidth;
+            if (inView) safeCallback(callback, element);
+          },
+          { once, timeoutMs: options.timeoutMs },
+        );
+      }
+
+      observer = new IntersectionObserver(
+        (entries) => {
+          for (const entry of entries) {
+            if (!entry.isIntersecting) continue;
+            safeCallback(callback, entry.target);
+            if (once) observer?.unobserve(entry.target);
+          }
+        },
+        {
+          root: isDocument(options.root) ? null : (options.root ?? null),
+          rootMargin: options.rootMargin,
+          threshold: options.threshold ?? 1,
+        },
+      );
+
+      cleanups.push(
+        tools.waitForElement(
+          selector,
+          (element: Element) => {
+            if (observed.has(element)) return;
+            observed.add(element);
+            observer?.observe(element);
+          },
+          { once: false, timeoutMs: options.timeoutMs },
+        ),
+      );
+      return stop;
+    },
+
+    domChanged(
+      callback: (mutations: MutationRecord[]) => void,
+      options: DomChangedOptions = {},
+    ): Cleanup {
+      const doc = readDocument(env);
+      const win = readWindow(env);
+      if (!doc || typeof MutationObserver === "undefined") return noopCleanup();
+      const root = options.root ?? doc.documentElement ?? doc.body;
+      if (!root) return noopCleanup();
+      const debounceMs = Math.max(0, options.debounceMs ?? 50);
+      let pending: MutationRecord[] = [];
+      let timeoutId: number | null = null;
+      const flush = () => {
+        timeoutId = null;
+        const mutations = pending;
+        pending = [];
+        safeCallback(callback, mutations);
+      };
+      const observer = new MutationObserver((mutations) => {
+        pending.push(...mutations);
+        if (debounceMs === 0) {
+          flush();
+          return;
+        }
+        if (timeoutId !== null) return;
+        timeoutId = win?.setTimeout(flush, debounceMs) ?? null;
+      });
+      observer.observe(root, { childList: true, subtree: options.subtree !== false });
+      return () => {
+        observer.disconnect();
+        if (timeoutId !== null) win?.clearTimeout(timeoutId);
+      };
+    },
+
+    domLoaded(callback: () => void): Cleanup {
+      const doc = readDocument(env);
+      if (!doc || doc.readyState !== "loading") {
+        safeCallback(callback, undefined);
+        return noopCleanup();
+      }
+      const handler = () => safeCallback(callback, undefined);
+      doc.addEventListener("DOMContentLoaded", handler, { once: true });
+      return () => doc.removeEventListener("DOMContentLoaded", handler);
+    },
+
+    waitForDataLayer(
+      matcher: DataLayerMatcher,
+      callback: (entry: DataLayerEntry) => void,
+      options: DataLayerOptions = {},
+    ): Cleanup {
+      const win = readWindow(env);
+      if (!win) return noopCleanup();
+      const layerName = options.layerName || "dataLayer";
+      const layerHost = win as unknown as Record<string, unknown>;
+      const layer = Array.isArray(layerHost[layerName])
+        ? (layerHost[layerName] as unknown[])
+        : [];
+      layerHost[layerName] = layer;
+      const originalPush = layer.push;
+      let active = true;
+      let timeoutId: number | null = null;
+
+      const process = (entry: unknown) => {
+        if (!active) return;
+        const normalized = normalizeDataLayerEntry(entry);
+        const rawRecord = entry && typeof entry === "object" && !Array.isArray(entry)
+          ? entry as DataLayerEntry
+          : null;
+        const candidate = normalized ?? (
+          rawRecord && typeof rawRecord[0] !== "string" ? rawRecord : null
+        );
+        if (!candidate || !matchesDataLayerEntry(candidate, matcher)) return;
+        safeCallback(callback, candidate);
+        if (options.once !== false) cleanup();
+      };
+      const cleanup = () => {
+        active = false;
+        if (layer.push === wrappedPush) layer.push = originalPush;
+        if (timeoutId !== null) {
+          win.clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+      };
+      const wrappedPush = function (...items: unknown[]) {
+        const result = originalPush.apply(layer, items);
+        items.forEach(process);
+        return result;
+      };
+
+      layer.slice(Math.max(0, layer.length - 50)).forEach(process);
+      if (active) layer.push = wrappedPush as typeof layer.push;
+      if (options.timeoutMs && options.timeoutMs > 0) {
+        timeoutId = win.setTimeout(cleanup, options.timeoutMs);
+      }
+      return cleanup;
+    },
+
+    track(type: string, data?: Record<string, unknown>) {
+      env.track?.(type, data);
+    },
+
+    trackGoal(goalId: string, data?: Record<string, unknown>) {
+      env.trackGoal?.(goalId, data);
+    },
+
+    signal(key: string, value: unknown, ttlDays?: number) {
+      env.signal?.(key, value, ttlDays);
+    },
+
+    redirect(target: string) {
+      const loc = readLocation(env);
+      if (!loc || !target.trim()) return;
+      loc.assign(new URL(target, loc.href).toString());
+    },
+
+    reInit(forceReapply?: boolean) {
+      return env.reInit?.(forceReapply);
+    },
+
+    get(key: string) {
+      if (key === "tools") return tools;
+      return env.get?.(key);
+    },
+  };
+
+  return tools;
+}

package/src/runtime.test.ts

@@ -0,0 +1,217 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  assignmentSignature,
+  canUseEmptyProjectProfile,
+  computeUrlDiffNeeds,
+  readPerfFlags,
+  resolveActivationMode,
+  resolvePlatform,
+  resolveRouterMode,
+  shouldReevaluateForUrlChange,
+} from "./runtime";
+import type { InitConfig } from "./types";
+
+const originalShopify = (globalThis as Record<string, unknown>).Shopify;
+const originalNavigation = (globalThis as Record<string, unknown>).navigation;
+
+afterEach(() => {
+  const g = globalThis as Record<string, unknown>;
+  g.Shopify = originalShopify;
+  g.navigation = originalNavigation;
+});
+
+describe("platform/router runtime", () => {
+  it("prefers explicit platformHint over profile and detection", () => {
+    const g = globalThis as Record<string, unknown>;
+    g.Shopify = { analytics: { publish: () => {} } };
+    const config: InitConfig = {
+      platformHint: "spa",
+      profile: { platform: "shopify", version: 1 },
+      experiments: [],
+    };
+    expect(resolvePlatform(config)).toBe("spa");
+  });
+
+  it("uses profile platform when platformHint is auto", () => {
+    const config: InitConfig = {
+      platformHint: "auto",
+      profile: { platform: "shopify", version: 1 },
+      experiments: [],
+    };
+    expect(resolvePlatform(config)).toBe("shopify");
+  });
+
+  it("defaults router mode to none for shopify", () => {
+    const config: InitConfig = { experiments: [] };
+    expect(resolveRouterMode(config, "shopify")).toBe("none");
+  });
+
+  it("respects navigation mode auto-detection", () => {
+    const g = globalThis as Record<string, unknown>;
+    g.navigation = { addEventListener: () => {} };
+    const config: InitConfig = { experiments: [] };
+    expect(resolveRouterMode(config, "spa")).toBe("navigation");
+  });
+
+  it("resolves activation mode to observer by default", () => {
+    expect(resolveActivationMode({ experiments: [] })).toBe("observer");
+    expect(resolveActivationMode({ experiments: [], activationMode: "manual" })).toBe("manual");
+  });
+
+  it("builds URL diff needs from targeting rules", () => {
+    const deps = computeUrlDiffNeeds([
+      {
+        id: "exp_1",
+        variations: [{ id: "var_1", weight: 1, mutations: [] }],
+        targeting: {
+          url: [{ type: "simple", pattern: "example.com/products/*?q=1#hero" }],
+        },
+      },
+    ]);
+
+    expect(deps.path).toBe(true);
+    expect(deps.search).toBe(true);
+    expect(deps.hash).toBe(true);
+  });
+
+  it("builds URL diff needs from route-captured runtime signals", () => {
+    const queryDeps = computeUrlDiffNeeds([], [
+      {
+        key: "utm.content",
+        capture: { mode: "url_parameter", parameter: "utm_content" },
+      },
+    ]);
+    expect(queryDeps).toEqual({ path: false, search: true, hash: false });
+
+    const domDeps = computeUrlDiffNeeds([], [
+      {
+        key: "product.type",
+        capture: { mode: "dom_selector", selector: "[data-product-type]" },
+      },
+    ]);
+    expect(domDeps).toEqual({ path: true, search: true, hash: true });
+
+    const globalDeps = computeUrlDiffNeeds([], [
+      {
+        key: "shopware.cart_count",
+        capture: { mode: "global", path: "Shopware.State.cart.count" },
+      },
+    ]);
+    expect(globalDeps).toEqual({ path: true, search: true, hash: true });
+  });
+
+  it("skips reevaluation when unrelated URL parts change", () => {
+    const deps = { path: true, search: false, hash: false };
+    expect(
+      shouldReevaluateForUrlChange(
+        "https://example.com/products/a?q=1",
+        "https://example.com/products/a?q=2",
+        deps,
+      ),
+    ).toBe(false);
+  });
+
+  it("reevaluates when drip_force changes even without URL targeting deps", () => {
+    const deps = { path: false, search: false, hash: false };
+    expect(
+      shouldReevaluateForUrlChange(
+        "https://example.com/products/a?drip_force=exp_1:var_a",
+        "https://example.com/products/b?drip_force=exp_1:var_b",
+        deps,
+      ),
+    ).toBe(true);
+  });
+
+  it("reevaluates when readable force params change without URL targeting deps", () => {
+    const deps = { path: false, search: false, hash: false };
+    expect(
+      shouldReevaluateForUrlChange(
+        "https://example.com/products/a?drip_experiment_id=exp_1&drip_variation_id=var_a",
+        "https://example.com/products/b?drip_experiment_id=exp_1&drip_variation_id=var_b",
+        deps,
+      ),
+    ).toBe(true);
+  });
+
+  it("produces deterministic assignment signatures", () => {
+    const a = assignmentSignature([
+      {
+        experimentId: "exp_b",
+        variationId: "var_2",
+      } as any,
+      {
+        experimentId: "exp_a",
+        variationId: "var_1",
+      } as any,
+    ]);
+    const b = assignmentSignature([
+      {
+        experimentId: "exp_a",
+        variationId: "var_1",
+      } as any,
+      {
+        experimentId: "exp_b",
+        variationId: "var_2",
+      } as any,
+    ]);
+    expect(a).toBe(b);
+  });
+
+  it("allows perf flag overrides per init config", () => {
+    const flags = readPerfFlags({
+      experiments: [],
+      perfFlags: { perf_spa_incremental_reapply_v1: false },
+    });
+    expect(flags.perf_platform_router_v1).toBe(true);
+    expect(flags.perf_spa_incremental_reapply_v1).toBe(false);
+    expect(flags.perf_empty_project_v1).toBe(false);
+  });
+
+  it("accepts only server-authorized, behavior-free empty projects", () => {
+    const config: InitConfig = {
+      experiments: [],
+      perfFlags: { perf_empty_project_v1: true },
+      runtimeFeatures: { sdkVariant: "live" },
+      runtimeProfile: "empty_project",
+    };
+
+    expect(canUseEmptyProjectProfile(config, [], "shopify")).toBe(true);
+    expect(canUseEmptyProjectProfile({ ...config, runtimeProfile: "full" }, [], "shopify")).toBe(false);
+    expect(canUseEmptyProjectProfile({ ...config, perfFlags: {} }, [], "shopify")).toBe(false);
+    expect(canUseEmptyProjectProfile({ ...config, signals: [{ key: "cart.count" }] }, [], "shopify")).toBe(false);
+    expect(canUseEmptyProjectProfile({ ...config, projectCode: { enabled: true, js: "run()" } }, [], "shopify")).toBe(false);
+    expect(canUseEmptyProjectProfile({ ...config, externalTracking: { domains: ["checkout.test"] } }, [], "shopify")).toBe(false);
+    expect(canUseEmptyProjectProfile(config, [{ id: "exp_1", variations: [] }], "shopify")).toBe(false);
+    expect(canUseEmptyProjectProfile(config, [], "spa")).toBe(false);
+  });
+
+  it.each<Array<[string, Partial<InitConfig>]>>([
+    ["data-layer triggers", { dataLayerTriggers: [{ event: "cart_updated" }] }],
+    ["exposure destinations", { exposureDestinations: { dataLayer: { enabled: true } } }],
+    ["semantic tracking", { semanticTracking: { enabled: true } }],
+    ["debug mode", { debug: { enabled: true } }],
+    ["runtime feature flags", { runtimeFeatures: { sdkVariant: "live", heatmap: true } }],
+    ["page triggers", { pageTrigger: { defaultMode: "dom_change" } }],
+    ["top-level router mode", { routerMode: "history" }],
+    ["SPA reinitialization", { spa: { reinitOnly: true } }],
+    ["SPA DOM observation", { spa: { domChangeTrigger: true } }],
+    ["SPA manual activation", { spa: { activationMode: "manual" } }],
+    ["SPA router mode", { spa: { routerMode: "history" } }],
+    ["variation prerequisites", {
+      projectPrerequisites: { showVariationsRule: "return false;" },
+    }],
+    ["tracking prerequisites", {
+      projectPrerequisites: { startTrackingRule: "return false;" },
+    }],
+  ])("rejects empty-project profiles with %s", (_label, override) => {
+    const config: InitConfig = {
+      experiments: [],
+      perfFlags: { perf_empty_project_v1: true },
+      runtimeFeatures: { sdkVariant: "live" },
+      runtimeProfile: "empty_project",
+      ...override,
+    };
+
+    expect(canUseEmptyProjectProfile(config, [], "shopify")).toBe(false);
+  });
+});