@drip-apex/sdk 0.1.0

package/src/runtime.ts

@@ -0,0 +1,268 @@
+import type {
+  ActivationMode,
+  Assignment,
+  Experiment,
+  InitConfig,
+  PerfFeatureFlag,
+  PlatformHint,
+  RouterMode,
+} from "./types";
+
+type UrlDiffNeeds = {
+  path: boolean;
+  search: boolean;
+  hash: boolean;
+};
+
+export type PerfFlagState = Record<PerfFeatureFlag, boolean>;
+
+const PERF_FLAG_DEFAULTS: PerfFlagState = {
+  perf_platform_router_v1: true,
+  perf_shopify_pixel_buffer_v1: true,
+  perf_spa_incremental_reapply_v1: true,
+  perf_empty_project_v1: false,
+};
+
+function hasOwnEntries(value: unknown): boolean {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length > 0);
+}
+
+function hasProjectCode(config: InitConfig): boolean {
+  const projectCode = config.projectCode;
+  return Boolean(
+    projectCode?.enabled
+    || projectCode?.css?.trim()
+    || projectCode?.helperJs?.trim()
+    || projectCode?.js?.trim(),
+  );
+}
+
+/**
+ * Browser-side validation for a server-compiled empty-project profile. The
+ * browser may reject the profile, but never upgrades a full profile itself.
+ */
+export function canUseEmptyProjectProfile(
+  config: InitConfig,
+  experiments: Experiment[],
+  platform?: PlatformHint,
+): boolean {
+  if (config.runtimeProfile !== "empty_project") return false;
+  if (!readPerfFlags(config).perf_empty_project_v1) return false;
+  if (experiments.length > 0) return false;
+  if ((config.signals?.length ?? 0) > 0) return false;
+  if (hasOwnEntries(config.commerce)) return false;
+  if ((config.dataLayerTriggers?.length ?? 0) > 0) return false;
+  if ((config.externalTracking?.domains?.length ?? 0) > 0) return false;
+  if (hasOwnEntries(config.exposureDestinations)) return false;
+  if (hasProjectCode(config)) return false;
+  if (config.semanticTracking?.enabled) return false;
+  if (config.debug?.enabled) return false;
+  if (config.runtimeFeatures && Object.entries(config.runtimeFeatures).some(([key, enabled]) => (
+    key !== "sdkVariant" && enabled === true
+  ))) return false;
+  if (config.runtimeFeatures?.sdkVariant && config.runtimeFeatures.sdkVariant !== "live") return false;
+  if (config.pageTrigger?.defaultMode && config.pageTrigger.defaultMode !== "direct") return false;
+  if (config.routerMode && config.routerMode !== "auto" && config.routerMode !== "none") return false;
+  if (config.spa && (
+    config.spa.reinitOnly
+    || config.spa.domChangeTrigger
+    || config.spa.activationMode === "manual"
+    || (config.spa.routerMode && config.spa.routerMode !== "auto" && config.spa.routerMode !== "none")
+  )) return false;
+  if (config.profile?.platform === "spa" || config.platformHint === "spa" || platform === "spa") return false;
+  if (config.projectPrerequisites?.showVariationsRule?.trim()
+    && config.projectPrerequisites.showVariationsRule.trim() !== "return true;") return false;
+  if (config.projectPrerequisites?.startTrackingRule?.trim()
+    && config.projectPrerequisites.startTrackingRule.trim() !== "return true;") return false;
+  return true;
+}
+
+function hasNavigationApi(): boolean {
+  const w = globalThis as Record<string, unknown>;
+  const nav = w.navigation as { addEventListener?: unknown } | undefined;
+  return Boolean(nav && typeof nav.addEventListener === "function");
+}
+
+function hasShopifyRuntime(): boolean {
+  const w = globalThis as Record<string, unknown>;
+  const shopify = w.Shopify as { analytics?: { publish?: unknown } } | undefined;
+  return Boolean(shopify?.analytics && typeof shopify.analytics.publish === "function");
+}
+
+function hasShopwareRuntime(): boolean {
+  const w = globalThis as Record<string, unknown>;
+  if (w.PluginManager) return true;
+  if (w.Shopware) return true;
+  if (typeof document === "undefined") return false;
+  return Boolean(
+    document.querySelector("[data-shopware], [data-off-canvas-main-navigation], .cms-page, .is--ctl-index"),
+  );
+}
+
+function hasSpaMarkers(): boolean {
+  if (typeof document === "undefined") return false;
+  return Boolean(
+    document.getElementById("__next")
+    || document.querySelector("[data-reactroot], [ng-version], [data-sveltekit], [data-v-app], [data-router-view]"),
+  );
+}
+
+export function detectRuntimePlatform(): PlatformHint {
+  if (hasShopifyRuntime()) return "shopify";
+  if (hasShopwareRuntime()) return "shopware";
+  if (hasSpaMarkers() || hasNavigationApi()) return "spa";
+  return "auto";
+}
+
+export function resolvePlatform(config: InitConfig): PlatformHint {
+  if (config.platformHint && config.platformHint !== "auto") {
+    return config.platformHint;
+  }
+  const profilePlatform = config.profile?.platform;
+  if (profilePlatform && profilePlatform !== "auto") {
+    return profilePlatform;
+  }
+  return detectRuntimePlatform();
+}
+
+export function resolveRouterMode(config: InitConfig, platform: PlatformHint): RouterMode {
+  if (config.spa?.reinitOnly) return "none";
+  const requested = config.spa?.routerMode ?? config.routerMode ?? "auto";
+  if (requested !== "auto") return requested;
+  if (platform === "shopify" && !config.spa?.domChangeTrigger) return "none";
+  return hasNavigationApi() ? "navigation" : "history";
+}
+
+export function resolveActivationMode(config: InitConfig): ActivationMode {
+  const requested = config.spa?.activationMode ?? config.activationMode ?? "auto";
+  if (requested === "manual") return "manual";
+  return "observer";
+}
+
+export function readPerfFlags(config: InitConfig): PerfFlagState {
+  const out = { ...PERF_FLAG_DEFAULTS };
+  const configured = config.perfFlags ?? {};
+  for (const key of Object.keys(out) as PerfFeatureFlag[]) {
+    if (typeof configured[key] === "boolean") out[key] = configured[key]!;
+  }
+  return out;
+}
+
+function parseMaybeUrl(url: string): URL | null {
+  try {
+    return new URL(url, "https://_");
+  } catch {
+    return null;
+  }
+}
+
+function readForceSignature(params: URLSearchParams): string {
+  const canonical = params.get("drip_force") ?? "";
+  if (canonical) return canonical;
+  const experimentId =
+    params.get("drip_experiment_id") ??
+    params.get("drip_experiment") ??
+    params.get("experiment_id") ??
+    params.get("experimentId") ??
+    params.get("expId") ??
+    "";
+  const variationId =
+    params.get("drip_variation_id") ??
+    params.get("drip_variation") ??
+    params.get("variation_id") ??
+    params.get("variationId") ??
+    params.get("varId") ??
+    "";
+  return experimentId && variationId ? `${experimentId}:${variationId}` : "";
+}
+
+function markUrlDepsForPattern(
+  deps: UrlDiffNeeds,
+  pattern: string,
+  type: "regex" | "simple",
+): void {
+  if (type === "regex") {
+    deps.path = true;
+    deps.search = true;
+    deps.hash = true;
+    return;
+  }
+  deps.path = true;
+  if (pattern.includes("?")) deps.search = true;
+  if (pattern.includes("#")) deps.hash = true;
+}
+
+export function computeUrlDiffNeeds(
+  experiments: Experiment[],
+  signals: InitConfig["signals"] = [],
+): UrlDiffNeeds {
+  const deps: UrlDiffNeeds = { path: false, search: false, hash: false };
+  for (const exp of experiments) {
+    const rules = exp.targeting?.url;
+    if (!rules || rules.length === 0) continue;
+    for (const rule of rules) {
+      markUrlDepsForPattern(deps, rule.pattern, rule.type);
+      if (deps.path && deps.search && deps.hash) return deps;
+    }
+  }
+
+  for (const definition of signals ?? []) {
+    const mode = definition.capture?.mode;
+    if (mode === "url_parameter") {
+      deps.search = true;
+    }
+    if (mode === "dom_selector" || mode === "global") {
+      deps.path = true;
+      deps.search = true;
+      deps.hash = true;
+    }
+    if (deps.path && deps.search && deps.hash) return deps;
+  }
+
+  return deps;
+}
+
+export function shouldReevaluateForUrlChange(
+  previousUrl: string,
+  nextUrl: string,
+  deps: UrlDiffNeeds,
+): boolean {
+  if (previousUrl === nextUrl) return false;
+  const prev = parseMaybeUrl(previousUrl);
+  const next = parseMaybeUrl(nextUrl);
+  if (!prev || !next) return true;
+  if (deps.path && prev.pathname !== next.pathname) return true;
+  if (deps.search && prev.search !== next.search) return true;
+  if (deps.hash && prev.hash !== next.hash) return true;
+  if (!deps.path && !deps.search && !deps.hash) {
+    const prevForce = readForceSignature(prev.searchParams);
+    const nextForce = readForceSignature(next.searchParams);
+    return prevForce !== nextForce;
+  }
+  return false;
+}
+
+export function assignmentSignature(assignments: Assignment[]): string {
+  if (!assignments.length) return "none";
+  return assignments
+    .map((item) => item.experimentId + ":" + item.variationId)
+    .sort()
+    .join("|");
+}
+
+export function getBlankScreenMs(): number {
+  try {
+    if (typeof performance === "undefined") return 0;
+    const timing = performance.timing;
+    if (timing && timing.navigationStart > 0 && timing.domContentLoadedEventStart > 0) {
+      return Math.max(0, timing.domContentLoadedEventStart - timing.navigationStart);
+    }
+    const nav = performance.getEntriesByType?.("navigation")?.[0] as { domContentLoadedEventStart?: number } | undefined;
+    if (nav && typeof nav.domContentLoadedEventStart === "number") {
+      return Math.max(0, Math.round(nav.domContentLoadedEventStart));
+    }
+  } catch {
+    // ignore perf API failures
+  }
+  return 0;
+}

package/src/safe-regex.ts

@@ -0,0 +1,35 @@
+/**
+ * Safe wrapper around RegExp construction and testing.
+ * Prevents crashes from invalid patterns and guards against
+ * extremely long patterns that could cause ReDoS.
+ */
+
+const MAX_PATTERN_LENGTH = 1024;
+const MAX_CACHE_ENTRIES = 256;
+const regexCache = new Map<string, RegExp | null>();
+
+function cacheRegex(pattern: string, compiled: RegExp | null): void {
+  if (!regexCache.has(pattern) && regexCache.size >= MAX_CACHE_ENTRIES) {
+    const oldest = regexCache.keys().next().value;
+    if (oldest) regexCache.delete(oldest);
+  }
+  regexCache.set(pattern, compiled);
+}
+
+export function safeRegexTest(pattern: string, input: string): boolean {
+  if (!pattern || pattern.length > MAX_PATTERN_LENGTH) return false;
+
+  if (regexCache.has(pattern)) {
+    const cached = regexCache.get(pattern);
+    return cached ? cached.test(input) : false;
+  }
+
+  try {
+    const compiled = new RegExp(pattern);
+    cacheRegex(pattern, compiled);
+    return compiled.test(input);
+  } catch {
+    cacheRegex(pattern, null);
+    return false;
+  }
+}

package/src/sanitize.ts

@@ -0,0 +1,34 @@
+/**
+ * Lightweight HTML sanitizer using the browser's DOMParser.
+ * Strips <script> tags, on* event handlers, and javascript: URLs.
+ */
+export function sanitizeHtml(html: string): string {
+  const doc = new DOMParser().parseFromString(html, "text/html");
+
+  // Remove all <script> elements
+  for (const script of Array.from(doc.querySelectorAll("script"))) {
+    script.remove();
+  }
+
+  // Walk every element to strip dangerous attributes
+  for (const el of Array.from(doc.body.querySelectorAll("*"))) {
+    for (const attr of Array.from(el.attributes)) {
+      // Remove on* event handler attributes (onclick, onerror, etc.)
+      if (attr.name.toLowerCase().startsWith("on")) {
+        el.removeAttribute(attr.name);
+        continue;
+      }
+
+      // Remove javascript: URLs in href, src, action, formaction, xlink:href
+      const urlAttrs = ["href", "src", "action", "formaction", "xlink:href"];
+      if (urlAttrs.includes(attr.name.toLowerCase())) {
+        const value = attr.value.replace(/\s+/g, "").toLowerCase();
+        if (value.startsWith("javascript:")) {
+          el.removeAttribute(attr.name);
+        }
+      }
+    }
+  }
+
+  return doc.body.innerHTML;
+}

package/src/semantic.ts

@@ -0,0 +1,245 @@
+import type { SemanticTrackingRule, SemanticTrackingSettings } from "./types";
+
+type TrackFn = (type: string, data?: Record<string, unknown>) => void;
+
+type Controller = {
+  stop: () => void;
+};
+
+type NormalizedRule = Required<
+  Pick<
+    SemanticTrackingRule,
+    "id" | "eventType" | "action" | "selector" | "labelSource" | "indexStrategy" | "oncePerSession"
+  >
+> &
+  Omit<
+    SemanticTrackingRule,
+    "id" | "eventType" | "action" | "selector" | "labelSource" | "indexStrategy" | "oncePerSession"
+  >;
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+function normalizeSampleRate(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value)
+    ? clamp(value, 0, 1)
+    : 0.25;
+}
+
+function sampledIn(sampleRate: number): boolean {
+  if (sampleRate >= 1) return true;
+  if (sampleRate <= 0) return false;
+  const key = "drip_semantic_sample";
+  try {
+    const existing = sessionStorage.getItem(key);
+    if (existing === "1") return true;
+    if (existing === "0") return false;
+    const selected = Math.random() < sampleRate;
+    sessionStorage.setItem(key, selected ? "1" : "0");
+    return selected;
+  } catch {
+    return Math.random() < sampleRate;
+  }
+}
+
+function cleanUrl(): string {
+  return location.origin + location.pathname;
+}
+
+function normalizeRules(settings: SemanticTrackingSettings): NormalizedRule[] {
+  const rules = Array.isArray(settings.rules) ? settings.rules : [];
+  return rules
+    .map((rule): NormalizedRule | null => {
+      const id = rule.id?.trim();
+      const eventType = rule.eventType?.trim();
+      const selector = rule.selector?.trim();
+      if (!id || !eventType || !selector) return null;
+      return {
+        ...rule,
+        id,
+        eventType,
+        selector,
+        action: rule.action === "visibility" ? "visibility" : "click",
+        labelSource: rule.labelSource ?? "text",
+        indexStrategy: rule.indexStrategy ?? "dom_order",
+        oncePerSession: rule.oncePerSession !== false,
+      };
+    })
+    .filter((rule): rule is NormalizedRule => Boolean(rule));
+}
+
+function pathMatches(rule: NormalizedRule): boolean {
+  const pattern = rule.pathPattern?.trim();
+  if (!pattern) return true;
+  const path = `${location.pathname}${location.search}`;
+  if (pattern.startsWith("regex:")) {
+    try {
+      return new RegExp(pattern.slice(6)).test(path);
+    } catch {
+      return false;
+    }
+  }
+  return path.includes(pattern);
+}
+
+function elementText(element: Element): string {
+  const tag = element.tagName.toLowerCase();
+  if (tag === "input" || tag === "textarea" || tag === "select") {
+    return (
+      element.getAttribute("aria-label") ||
+      element.getAttribute("title") ||
+      element.getAttribute("value") ||
+      ""
+    ).replace(/\s+/g, " ").trim().slice(0, 120);
+  }
+  return (
+    element.textContent ||
+    element.getAttribute("aria-label") ||
+    element.getAttribute("title") ||
+    element.getAttribute("alt") ||
+    ""
+  ).replace(/\s+/g, " ").trim().slice(0, 120);
+}
+
+function labelFor(rule: NormalizedRule, element: Element): string {
+  if (rule.labelSource === "constant") return rule.label || rule.elementRole || rule.id;
+  if (rule.labelSource === "attribute" && rule.attribute) {
+    return (element.getAttribute(rule.attribute) || rule.label || elementText(element)).slice(0, 180);
+  }
+  return (rule.label || elementText(element) || rule.elementRole || rule.id).slice(0, 180);
+}
+
+function productContext(): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  const canonical = document.querySelector<HTMLLinkElement>("link[rel='canonical']")?.href;
+  const productId = document.querySelector<HTMLElement>("[data-product-id]")?.dataset.productId;
+  const handle = canonical ? canonical.split("/products/")[1]?.split(/[?#/]/)[0] : undefined;
+  if (productId) out.product_id = productId;
+  if (handle) out.product_handle = handle;
+  return out;
+}
+
+function elementIndex(rule: NormalizedRule, element: Element, elements: Element[]): number | null {
+  if (rule.indexStrategy === "none") return null;
+  const index = elements.indexOf(element);
+  return index >= 0 ? index + 1 : null;
+}
+
+function basePayload(rule: NormalizedRule, element: Element, elements: Element[]) {
+  const rect = element.getBoundingClientRect();
+  const index = elementIndex(rule, element, elements);
+  return {
+    semantic_rule_id: rule.id,
+    semantic_event: rule.eventType,
+    semantic_role: rule.elementRole ?? "",
+    semantic_label: labelFor(rule, element),
+    page_type: rule.pageType ?? "",
+    element_index: index,
+    element_tag: element.tagName.toLowerCase(),
+    element_text: elementText(element),
+    element_width: Math.round(rect.width),
+    element_height: Math.round(rect.height),
+    path: location.pathname,
+    page_url: cleanUrl(),
+    ...productContext(),
+  };
+}
+
+function dedupeKey(rule: NormalizedRule, element: Element, elements: Element[]): string {
+  const index = elementIndex(rule, element, elements) ?? 0;
+  return `${rule.id}:${cleanUrl()}:${index}:${labelFor(rule, element)}`;
+}
+
+export function startSemanticCapture(
+  settings: SemanticTrackingSettings | undefined,
+  track: TrackFn,
+): Controller | null {
+  if (!settings?.enabled) return null;
+  if (!sampledIn(normalizeSampleRate(settings.sampleRate))) return null;
+
+  const rules = normalizeRules(settings).filter(pathMatches);
+  if (!rules.length) return null;
+
+  const maxEvents = Math.max(1, Math.min(500, Math.round(settings.maxEventsPerSession ?? 120)));
+  const minVisibleMs = Math.max(100, Math.min(10_000, Math.round(settings.minVisibleMs ?? 700)));
+  const threshold = Math.max(0.05, Math.min(1, settings.visibilityThreshold ?? 0.5));
+  const seen = new Set<string>();
+  const timers = new Map<Element, number>();
+  let emitted = 0;
+
+  function emit(rule: NormalizedRule, element: Element, elements: Element[], extra: Record<string, unknown> = {}) {
+    if (emitted >= maxEvents) return;
+    const key = dedupeKey(rule, element, elements);
+    if (rule.oncePerSession && seen.has(key)) return;
+    seen.add(key);
+    emitted += 1;
+    track(rule.eventType, { ...basePayload(rule, element, elements), ...extra });
+  }
+
+  const visibilityRules = rules.filter((rule) => rule.action === "visibility");
+  const clickRules = rules.filter((rule) => rule.action === "click");
+  const observers: IntersectionObserver[] = [];
+
+  for (const rule of visibilityRules) {
+    let elements: Element[] = [];
+    try {
+      elements = Array.from(document.querySelectorAll(rule.selector));
+    } catch {
+      continue;
+    }
+    if (!elements.length) continue;
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.intersectionRatio < threshold) continue;
+          if (timers.has(entry.target)) continue;
+          const timer = window.setTimeout(() => {
+            timers.delete(entry.target);
+            const rect = entry.target.getBoundingClientRect();
+            if (rect.width <= 0 || rect.height <= 0) return;
+            emit(rule, entry.target, elements, {
+              visible_ms: minVisibleMs,
+              visibility_pct: Math.round(entry.intersectionRatio * 100),
+            });
+          }, minVisibleMs);
+          timers.set(entry.target, timer);
+        }
+      },
+      { threshold: [threshold] },
+    );
+    elements.forEach((element) => observer.observe(element));
+    observers.push(observer);
+  }
+
+  const onClick = (event: MouseEvent) => {
+    const target = event.target instanceof Element ? event.target : null;
+    if (!target) return;
+    for (const rule of clickRules) {
+      if (!pathMatches(rule)) continue;
+      let matched: Element | null = null;
+      try {
+        matched = target.closest(rule.selector);
+      } catch {
+        continue;
+      }
+      if (!matched) continue;
+      const elements = Array.from(document.querySelectorAll(rule.selector));
+      emit(rule, matched, elements, {
+        viewport_x: Math.round(event.clientX),
+        viewport_y: Math.round(event.clientY),
+      });
+    }
+  };
+
+  document.addEventListener("click", onClick, { capture: true, passive: true });
+
+  return {
+    stop() {
+      document.removeEventListener("click", onClick, { capture: true });
+      observers.forEach((observer) => observer.disconnect());
+      for (const timer of timers.values()) window.clearTimeout(timer);
+      timers.clear();
+    },
+  };
+}

package/src/shopify-cart-events.test.ts

@@ -0,0 +1,76 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  fetchWithoutShopifyCartMutationNotification,
+  onShopifyCartMutation,
+} from "./shopify-cart-events";
+
+describe("shared Shopify cart mutation events", () => {
+  let nativeFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    nativeFetch = vi.fn(async () => new Response("original", { status: 200 }));
+    vi.stubGlobal("fetch", nativeFetch);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    document.body.innerHTML = "";
+  });
+
+  it("installs once, supports detached calls, and restores fetch after the last cleanup", async () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const original = window.fetch;
+    const stopFirst = onShopifyCartMutation(first);
+    const wrapped = window.fetch;
+    const stopSecond = onShopifyCartMutation(second);
+
+    expect(window.fetch).toBe(wrapped);
+    const detached = window.fetch;
+    const response = await detached("/cart/add.js", { method: "POST" });
+    expect(await response.text()).toBe("original");
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+
+    stopFirst();
+    expect(window.fetch).toBe(wrapped);
+    stopSecond();
+    expect(window.fetch).toBe(original);
+  });
+
+  it("preserves rejected mutations and ignores failed responses", async () => {
+    const error = new Error("network failed");
+    nativeFetch
+      .mockResolvedValueOnce(new Response("failed", { status: 500 }))
+      .mockRejectedValueOnce(error);
+    const handler = vi.fn();
+    const stop = onShopifyCartMutation(handler);
+
+    await expect(window.fetch("/cart/change.js")).resolves.toMatchObject({ status: 500 });
+    await expect(window.fetch("/cart/clear.js")).rejects.toBe(error);
+    expect(handler).not.toHaveBeenCalled();
+    stop();
+  });
+
+  it("ignores cross-origin and suppressed Apex cart writes", async () => {
+    const handler = vi.fn();
+    const stop = onShopifyCartMutation(handler);
+
+    await window.fetch("https://other.test/cart/add.js");
+    await fetchWithoutShopifyCartMutationNotification("/cart/update.js", { method: "POST" });
+    expect(handler).not.toHaveBeenCalled();
+    stop();
+  });
+
+  it("also observes classic add-to-cart form submits", () => {
+    document.body.innerHTML = '<form action="/cart/add" method="post"></form>';
+    const handler = vi.fn();
+    const stop = onShopifyCartMutation(handler);
+    document.querySelector("form")!.dispatchEvent(new Event("submit", { bubbles: true }));
+    return Promise.resolve().then(() => {
+      expect(handler).toHaveBeenCalledTimes(1);
+      stop();
+    });
+  });
+});