@drip-apex/sdk 0.1.0 → 0.3.0

package/src/global-runtime-reconciler.test.ts

@@ -0,0 +1,271 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  commerceAssignmentResponseFixture,
+  commercePriceFixture as commerce,
+  installCommerceProductPage,
+  priceExperimentsFixture,
+} from "./test-fixtures/commerce";
+import type { Experiment } from "./types";
+
+function trackedEvents(fetchMock: ReturnType<typeof vi.fn>): { type: string; data?: Record<string, unknown> }[] {
+  return fetchMock.mock.calls
+    .filter((call) => String(call[0]).endsWith("/events"))
+    .flatMap((call) => JSON.parse(String((call[1] as RequestInit | undefined)?.body)).events);
+}
+
+describe("global runtime reconciler", () => {
+  const originalFetch = globalThis.fetch;
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.resetModules();
+    delete (globalThis as any).__drip;
+    delete (globalThis as any).drip;
+    delete (globalThis as any).Apex;
+    localStorage.clear();
+    sessionStorage.clear();
+    document.head.innerHTML = "";
+    document.body.innerHTML = "";
+    history.replaceState({}, "", "/products/current-product");
+    fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/cart.js")) {
+        return Response.json({ token: "cart-runtime?key=runtime-secret" });
+      }
+      if (url.includes("/v1/assign")) {
+        return Response.json(commerceAssignmentResponseFixture);
+      }
+      return new Response("ok", { status: 202 });
+    });
+    globalThis.fetch = fetchMock as typeof fetch;
+  });
+
+  afterEach(async () => {
+    const { cleanupCommercePrice } = await import("./commerce-price");
+    const { cleanupCommerceShipping } = await import("./commerce-shipping");
+    cleanupCommercePrice();
+    cleanupCommerceShipping();
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    globalThis.fetch = originalFetch;
+    delete (globalThis as any).__drip;
+    delete (globalThis as any).drip;
+    delete (globalThis as any).Apex;
+    delete (window as Window & { Shopify?: unknown }).Shopify;
+    delete (window as Window & { ShopifyAnalytics?: unknown }).ShopifyAnalytics;
+    document.head.innerHTML = "";
+    document.body.innerHTML = "";
+  });
+
+  // F6 / S11 / F12
+  it("keeps click goals wired after a force-reset recheck that changes no assignment", async () => {
+    document.body.innerHTML =
+      '<h1 class="headline">Original</h1><button class="buy">Buy</button>';
+    const { flush, init, reInit } = await import("./index");
+
+    init({
+      antiFlickerMode: "off",
+      endpoint: "https://events.test",
+      experiments: [{
+        id: "exp_force_goal",
+        status: "running",
+        trafficAllocation: 1,
+        targeting: {
+          pageRules: [{
+            id: "page_force_goal",
+            includeRules: [{ type: "simple", pattern: "/products/*" }],
+            trigger: { deactivationMode: "force-reset" },
+          }],
+        },
+        variations: [{
+          id: "var_force_goal",
+          weight: 1,
+          mutations: [{ selector: ".headline", action: "text", text: "Treatment" }],
+        }],
+        goals: [{
+          id: "goal_force_click",
+          type: "click",
+          selector: ".buy",
+          pageId: "page_force_goal",
+        }],
+      }],
+      shopId: "shop_123",
+      trackingStart: "immediate",
+      userId: "visitor_force_goal",
+    });
+    await Promise.resolve();
+    document.querySelector<HTMLElement>(".buy")!.click();
+
+    reInit();
+    await Promise.resolve();
+    document.querySelector<HTMLElement>(".buy")!.click();
+    await flush();
+
+    const goals = trackedEvents(fetchMock).filter((event) => event.type === "goal");
+    expect(goals.map((event) => event.data?.goalId)).toEqual([
+      "goal_force_click",
+      "goal_force_click",
+    ]);
+  });
+
+  // F5
+  it("keeps the charge-correctness cart listener armed through a display-plane page teardown", async () => {
+    installCommerceProductPage();
+    const { getDiagnostics, init, reInit } = await import("./index");
+
+    init({
+      antiFlickerMode: "off",
+      commerce,
+      endpoint: "https://events.test",
+      experiments: [{
+        id: "exp_display_only",
+        status: "running",
+        trafficAllocation: 1,
+        targeting: {
+          pageRules: [
+            {
+              id: "page_display_product",
+              includeRules: [{ type: "simple", pattern: "/products/*" }],
+              trigger: { deactivationMode: "reset" },
+            },
+            {
+              id: "page_display_everywhere",
+              includeRules: [{ type: "simple", pattern: "/*" }],
+            },
+          ],
+        },
+        variations: [{
+          id: "var_display_only",
+          weight: 1,
+          mutations: [{ selector: ".price", action: "attribute", attribute: "data-arm", value: "b" }],
+        }],
+      }],
+      ingestSignature: "ingest-token",
+      shopId: "shop_123",
+      trackingStart: "immediate",
+      userId: "visitor_display_only",
+    });
+    history.replaceState({}, "", "/collections/all");
+    reInit();
+    expect(getDiagnostics().pageActivation).toEqual(expect.arrayContaining([
+      expect.objectContaining({ pageId: "page_display_product", active: false }),
+      expect.objectContaining({ pageId: "page_display_everywhere", active: true }),
+    ]));
+
+    // Let the init-time stamp settle so the only remaining source of a cart
+    // sync is the mutation listener itself.
+    await vi.waitFor(() =>
+      expect(getDiagnostics().spa.lastShopifyCartSync?.status).not.toBe("pending"));
+    const before = getDiagnostics().spa.lastShopifyCartSync;
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(getDiagnostics().spa.lastShopifyCartSync).toBe(before);
+
+    // The charge plane is page-independent: the price authorization plane is
+    // still live, so a cart mutation must still refresh the cohort stamp.
+    await fetch(new URL("/cart/add.js", location.origin).toString(), { method: "POST" });
+    await vi.waitFor(() =>
+      expect(getDiagnostics().spa.lastShopifyCartSync).not.toBe(before));
+  });
+
+  // F4
+  it("does not resurrect a deactivated page's price treatment from a cart-authorization callback", async () => {
+    installCommerceProductPage();
+    const experiments: Experiment[] = [
+      {
+        ...priceExperimentsFixture[0]!,
+        targeting: {
+          pageRules: [{
+            id: "page_price_product",
+            includeRules: [{ type: "simple", pattern: "/products/*" }],
+            trigger: { deactivationMode: "reset" },
+          }],
+        },
+      },
+      {
+        id: "exp_sibling",
+        status: "running",
+        trafficAllocation: 1,
+        variations: [{ id: "var_sibling", weight: 1, mutations: [] }],
+      },
+    ];
+    const { confirmCartAttributesWritten, getSignedCartAttributes, init, reInit } =
+      await import("./index");
+
+    init({
+      antiFlickerMode: "off",
+      commerce,
+      endpoint: "https://events.test",
+      experiments,
+      ingestSignature: "ingest-token",
+      shopId: "shop_123",
+      trackingStart: "immediate",
+      userId: "visitor_price_page",
+    });
+    await vi.waitFor(() =>
+      expect(document.querySelector(".price")?.textContent).toBe("€1.149,95"));
+
+    history.replaceState({}, "", "/collections/all");
+    reInit();
+    await vi.waitFor(() =>
+      expect(document.querySelector(".price")?.textContent).toBe("€1.299,00"));
+
+    const cartToken = "gid://shopify/Cart/abc?key=cart-secret";
+    const entries = await getSignedCartAttributes(cartToken);
+    confirmCartAttributesWritten(cartToken);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(entries.length).toBeGreaterThan(0);
+    expect(document.querySelector(".price")?.textContent).toBe("€1.299,00");
+  });
+
+  // S7
+  it("keeps another page's harness polling alive through a force-reset reapply", async () => {
+    vi.useFakeTimers();
+    const manifestUrl = "https://harness.test/manifest.json";
+    const manifestCalls = () =>
+      fetchMock.mock.calls.filter((call) => String(call[0]) === manifestUrl).length;
+    const { init, reInit } = await import("./index");
+
+    init({
+      antiFlickerMode: "off",
+      endpoint: "https://events.test",
+      experiments: [
+        {
+          id: "exp_harness",
+          status: "running",
+          trafficAllocation: 1,
+          variations: [{
+            id: "var_harness",
+            weight: 1,
+            mutations: [],
+            harnessSession: { manifestUrl, pollIntervalMs: 250, version: 1 },
+          }],
+        },
+        {
+          id: "exp_force_page",
+          status: "running",
+          trafficAllocation: 1,
+          targeting: {
+            pageRules: [{
+              id: "page_force_harness",
+              includeRules: [{ type: "simple", pattern: "/products/*" }],
+              trigger: { deactivationMode: "force-reset" },
+            }],
+          },
+          variations: [{ id: "var_force_page", weight: 1, mutations: [] }],
+        },
+      ],
+      shopId: "shop_123",
+      trackingStart: "immediate",
+      userId: "visitor_harness_page",
+    });
+    expect(manifestCalls()).toBe(1);
+
+    reInit();
+    const afterReapply = manifestCalls();
+    vi.advanceTimersByTime(600);
+    expect(manifestCalls()).toBeGreaterThan(afterReapply);
+  });
+});

package/src/goal-eligibility.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { goalIsEligible } from "./goal-eligibility";
+
+const HREF = "https://shop.example/checkout/thank-you?step=done";
+const NO_PAGES: ReadonlySet<string> = new Set();
+
+describe("goalIsEligible", () => {
+  it("decides page-scoped goals entirely by page activation", () => {
+    expect(goalIsEligible({ pageId: "page_1", urlPattern: "never-matches" }, new Set(["page_1"]), HREF)).toBe(true);
+    expect(goalIsEligible({ pageId: "page_1", urlPattern: ".*" }, NO_PAGES, HREF)).toBe(false);
+  });
+
+  it("matches every URL when the pattern is empty", () => {
+    expect(goalIsEligible({ urlPattern: "" }, NO_PAGES, HREF)).toBe(true);
+    expect(goalIsEligible({ urlPattern: null }, NO_PAGES, HREF)).toBe(true);
+    expect(goalIsEligible({}, NO_PAGES, HREF)).toBe(true);
+  });
+
+  it("tests the full href, not a path-relative substring", () => {
+    expect(goalIsEligible({ urlPattern: "checkout/thank-you" }, NO_PAGES, HREF)).toBe(true);
+    // A path-anchored pattern can never match an absolute href — the goal arm
+    // deliberately differs from the experiment URL-targeting matcher.
+    expect(goalIsEligible({ urlPattern: "^/checkout" }, NO_PAGES, HREF)).toBe(false);
+  });
+
+  it("fails closed on an invalid regex pattern", () => {
+    expect(goalIsEligible({ urlPattern: "([unclosed" }, NO_PAGES, HREF)).toBe(false);
+  });
+});

package/src/goal-eligibility.ts

@@ -0,0 +1,17 @@
+import { safeRegexTest } from "./safe-regex";
+
+// The single decision for whether a goal is active on a page (APX-102 arms):
+// a goal carrying a pageId is decided entirely by Page activation and its
+// url_pattern is never consulted; otherwise an empty pattern matches every
+// URL and a non-empty pattern is a full-href regex test (no slash escaping,
+// no path fallback — deliberately NOT the experiment URL-targeting matcher).
+// The SDK runtime and the CLI both consume this function; the edge engine
+// inlines the same two arms (packages/worker/src/edge-engine `goalActive`).
+export function goalIsEligible(
+  goal: { pageId?: string | null; urlPattern?: string | null },
+  pageActiveIds: ReadonlySet<string>,
+  href: string,
+): boolean {
+  if (goal.pageId) return pageActiveIds.has(goal.pageId);
+  return !goal.urlPattern || safeRegexTest(goal.urlPattern, href);
+}

package/src/goals.test.ts

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { setupGoals } from "./goals";
+import { setupGoals, triggerGoal, triggerGoalsForEvent } from "./goals";
 import { setJsPolicy } from "./js";
 
 const assignment = { experimentId: "exp", variationId: "var" } as const;
@@ -20,6 +20,7 @@ describe("goal capture policy", () => {
     setupGoals([], [], vi.fn());
     setJsPolicy("hybrid");
     document.body.innerHTML = "";
+    localStorage.clear();
   });
 
   it("drops PII-shaped captures only under strict policy", () => {
@@ -40,3 +41,145 @@ describe("goal capture policy", () => {
     });
   });
 });
+
+describe("goal page scope", () => {
+  afterEach(() => {
+    setupGoals([], [], vi.fn());
+    document.body.innerHTML = "";
+    localStorage.clear();
+    window.history.replaceState({}, "", "/");
+  });
+
+  function clickGoal(overrides: Record<string, unknown> = {}) {
+    return {
+      id: "goal",
+      type: "click" as const,
+      selector: "button",
+      ...overrides,
+    };
+  }
+
+  function wire(goal: ReturnType<typeof clickGoal>, activePages = new Set<string>()) {
+    const callback = vi.fn();
+    setupGoals(
+      [assignment],
+      [{ id: "exp", goals: [goal] }],
+      callback,
+      activePages,
+    );
+    return callback;
+  }
+
+  it("fires a scoped click only while its Page is active", () => {
+    document.body.innerHTML = "<button>Buy</button>";
+    const active = wire(clickGoal({ pageId: "page-products" }), new Set(["page-products"]));
+    document.querySelector("button")!.click();
+    expect(active).toHaveBeenCalledOnce();
+
+    const inactive = wire(clickGoal({ pageId: "page-products" }), new Set());
+    document.querySelector("button")!.click();
+    expect(inactive).not.toHaveBeenCalled();
+  });
+
+  it("uses urlPattern as the backstop for unscoped click goals", () => {
+    document.body.innerHTML = "<button>Buy</button>";
+    window.history.replaceState({}, "", "/products/shirt");
+    const matching = wire(clickGoal({ urlPattern: "/products/" }));
+    document.querySelector("button")!.click();
+    expect(matching).toHaveBeenCalledOnce();
+
+    window.history.replaceState({}, "", "/collections/sale");
+    const nonMatching = wire(clickGoal({ urlPattern: "/products/" }));
+    document.querySelector("button")!.click();
+    expect(nonMatching).not.toHaveBeenCalled();
+  });
+
+  it("preserves global behavior for legacy click goals without scope", () => {
+    document.body.innerHTML = "<button>Buy</button>";
+    const callback = wire(clickGoal());
+    document.querySelector("button")!.click();
+    expect(callback).toHaveBeenCalledOnce();
+  });
+
+  it("uses Page state for scoped pageview goals and URL matching for unscoped ones", () => {
+    window.history.replaceState({}, "", "/products/shirt");
+    const scoped = vi.fn();
+    setupGoals(
+      [assignment],
+      [{
+        id: "exp",
+        goals: [{ id: "view", type: "pageview", pageId: "page-products" }],
+      }],
+      scoped,
+      new Set(["page-products"]),
+    );
+    expect(scoped).toHaveBeenCalledOnce();
+
+    const inactive = vi.fn();
+    setupGoals(
+      [assignment],
+      [{
+        id: "exp",
+        goals: [{ id: "view", type: "pageview", pageId: "page-products" }],
+      }],
+      inactive,
+      new Set(),
+    );
+    expect(inactive).not.toHaveBeenCalled();
+
+    const urlScoped = vi.fn();
+    setupGoals(
+      [assignment],
+      [{
+        id: "exp",
+        goals: [{ id: "view-url", type: "pageview", urlPattern: "/products/" }],
+      }],
+      urlScoped,
+      new Set(),
+    );
+    expect(urlScoped).toHaveBeenCalledOnce();
+  });
+
+  it("normalizes both sides when matching project-level custom goals", () => {
+    const callback = vi.fn();
+    setupGoals([assignment], [], callback, new Set());
+    triggerGoalsForEvent(
+      "click_to__atc",
+      [assignment],
+      [{
+        id: "exp",
+        goals: [{ id: "custom", type: "custom", eventName: "click_to_ atc" }],
+      }],
+      { plan: "pro" },
+    );
+    expect(callback).toHaveBeenCalledWith("custom", assignment, { plan: "pro" });
+  });
+
+  it("fires a project-level revenue goal regardless of active Pages", () => {
+    const callback = vi.fn();
+    const experiments = [{
+      id: "exp",
+      goals: [{ id: "revenue", type: "revenue" as const }],
+    }];
+    setupGoals([assignment], experiments, callback, new Set());
+    triggerGoal("revenue", [assignment], experiments, { revenue: 42 });
+    expect(callback).toHaveBeenCalledWith("revenue", assignment, { revenue: 42 });
+  });
+
+  it("keeps countOnce dedup across deactivate and reactivate", () => {
+    document.body.innerHTML = "<button>Buy</button>";
+    const goal = clickGoal({ pageId: "page-products", countOnce: true });
+    const callback = wire(goal, new Set(["page-products"]));
+    document.querySelector("button")!.click();
+
+    setupGoals([assignment], [{ id: "exp", goals: [goal] }], callback, new Set());
+    setupGoals(
+      [assignment],
+      [{ id: "exp", goals: [goal] }],
+      callback,
+      new Set(["page-products"]),
+    );
+    document.querySelector("button")!.click();
+    expect(callback).toHaveBeenCalledOnce();
+  });
+});

package/src/goals.ts

@@ -1,7 +1,9 @@
 import { Goal, Assignment, CaptureRule } from "./types";
 import { safeRegexTest } from "./safe-regex";
+import { goalIsEligible } from "./goal-eligibility";
 import { containsPiiToken } from "./pii-keys";
 import { isStrictJsPolicy } from "./js";
+import { normalizeEventName } from "@drip/event-schema/event-name";
 
 type GoalCallback = (
   goalId: string,
@@ -14,6 +16,10 @@ let onGoal: GoalCallback | null = null;
 let clickListener: ((e: Event) => void) | null = null;
 let activeClickGoals: { goal: Goal; assignment: Assignment }[] = [];
 
+function goalIsActiveOnPage(goal: Goal, pageActiveIds: ReadonlySet<string>): boolean {
+  return goalIsEligible(goal, pageActiveIds, location.href);
+}
+
 function getFiredGoals(): Record<string, string[]> {
   try {
     return JSON.parse(localStorage.getItem(STORAGE_KEY) || "{}");
@@ -89,13 +95,39 @@ function findByText(start: Element, text: string): Element | null {
   const needle = text.trim().toLowerCase();
   while (el && el !== document.documentElement) {
     if ((el.textContent || "").trim().toLowerCase().includes(needle)) return el;
-    el = el.parentElement;
+    el = parentAcrossShadowBoundary(el);
+  }
+  return null;
+}
+
+function parentAcrossShadowBoundary(element: Element): Element | null {
+  if (element.parentElement) return element.parentElement;
+  const root = element.getRootNode();
+  return typeof ShadowRoot === "function" && root instanceof ShadowRoot ? root.host : null;
+}
+
+function closestAcrossShadowBoundary(start: Element, selector: string): Element | null {
+  let element: Element | null = start;
+  while (element) {
+    const matched = element.closest(selector);
+    if (matched) return matched;
+    const root = element.getRootNode();
+    element = typeof ShadowRoot === "function" && root instanceof ShadowRoot ? root.host : null;
   }
   return null;
 }
 
 function handleClick(e: Event): void {
-  const target = e.target as Element;
+  const composedTarget = e.composedPath?.()[0];
+  let resolved: Element | null = null;
+  if (typeof Element === "function" && composedTarget instanceof Element) {
+    resolved = composedTarget;
+  } else if (typeof Node === "function" && composedTarget instanceof Node) {
+    // A composed path can start at a Text node; its parent is the real
+    // shadow-internal element, while e.target is only the retargeted host.
+    resolved = composedTarget.parentElement;
+  }
+  const target = (resolved ?? e.target) as Element;
   if (!target?.closest) return;
   for (const entry of activeClickGoals) {
     const { selector, textMatch } = entry.goal;
@@ -104,7 +136,7 @@ function handleClick(e: Event): void {
     let matched: Element | null = null;
 
     if (selector) {
-      matched = target.closest(selector);
+      matched = closestAcrossShadowBoundary(target, selector);
       if (!matched) continue;
       // If textMatch is also set, verify the text
       if (textMatch && !textMatches(matched, textMatch)) continue;
@@ -119,10 +151,55 @@ function handleClick(e: Event): void {
   }
 }
 
+function collectActiveGoals(
+  assignments: Assignment[],
+  experiments: { id: string; goals?: Goal[] }[],
+  pageActiveIds: ReadonlySet<string>,
+): { goal: Goal; assignment: Assignment }[] {
+  const expMap = new Map(experiments.map((e) => [e.id, e]));
+  const active: { goal: Goal; assignment: Assignment }[] = [];
+  for (const assignment of assignments) {
+    const exp = expMap.get(assignment.experimentId);
+    if (!exp?.goals) continue;
+    for (const goal of exp.goals) {
+      if (!goalIsActiveOnPage(goal, pageActiveIds)) continue;
+      active.push({ goal, assignment });
+    }
+  }
+  return active;
+}
+
+/**
+ * Identity of the goal wiring the given inputs would produce. The runtime
+ * diffs this set to decide whether a re-wire is needed, so wiring stays
+ * idempotent across repeated reconciliation passes.
+ */
+export function goalWiringKeys(
+  assignments: Assignment[],
+  experiments: { id: string; goals?: Goal[] }[],
+  pageActiveIds: ReadonlySet<string> = new Set(),
+): Set<string> {
+  return new Set(
+    collectActiveGoals(assignments, experiments, pageActiveIds).map(
+      ({ goal, assignment }) =>
+        [
+          assignment.experimentId,
+          assignment.variationId,
+          goal.id,
+          goal.pageId ?? "",
+          goal.type,
+          goal.selector ?? "",
+          goal.textMatch ?? "",
+        ].join("\u0000"),
+    ),
+  );
+}
+
 export function setupGoals(
   assignments: Assignment[],
   experiments: { id: string; goals?: Goal[] }[],
   callback: GoalCallback,
+  pageActiveIds: ReadonlySet<string> = new Set(),
 ): void {
   onGoal = callback;
   activeClickGoals = [];
@@ -132,22 +209,19 @@ export function setupGoals(
     clickListener = null;
   }
 
-  const expMap = new Map(experiments.map((e) => [e.id, e]));
   let hasClickGoals = false;
 
-  for (const assignment of assignments) {
-    const exp = expMap.get(assignment.experimentId);
-    if (!exp?.goals) continue;
-    for (const goal of exp.goals) {
-      if (goal.type === "click" && (goal.selector || goal.textMatch)) {
-        activeClickGoals.push({ goal, assignment });
-        hasClickGoals = true;
-      }
-      if (goal.type === "pageview") {
-        if (!goal.urlPattern || safeRegexTest(goal.urlPattern, location.href)) {
-          fireGoal(goal, assignment);
-        }
-      }
+  for (const { goal, assignment } of collectActiveGoals(
+    assignments,
+    experiments,
+    pageActiveIds,
+  )) {
+    if (goal.type === "click" && (goal.selector || goal.textMatch)) {
+      activeClickGoals.push({ goal, assignment });
+      hasClickGoals = true;
+    }
+    if (goal.type === "pageview") {
+      fireGoal(goal, assignment);
     }
   }
 
@@ -179,12 +253,17 @@ export function triggerGoalsForEvent(
   data?: Record<string, unknown>,
 ): void {
   if (!eventName) return;
+  const normalizedEventName = normalizeEventName(eventName);
   const expMap = new Map(experiments.map((e) => [e.id, e]));
   for (const assignment of assignments) {
     const exp = expMap.get(assignment.experimentId);
     if (!exp?.goals) continue;
     for (const goal of exp.goals) {
-      if (goal.type === "custom" && goal.eventName === eventName) {
+      if (
+        goal.type === "custom" &&
+        goal.eventName &&
+        normalizeEventName(goal.eventName) === normalizedEventName
+      ) {
         fireGoal(goal, assignment, data);
       }
     }