@drip-apex/sdk 0.1.0

package/src/guards.ts

@@ -0,0 +1,250 @@
+const BOT_RE = /bot|google|crawler|spider|robot|crawling|facebookexternalhit|bingpreview|slurp/i;
+
+export function isBot(): boolean {
+  return BOT_RE.test(navigator.userAgent);
+}
+
+export function isIframe(): boolean {
+  try {
+    return window.self !== window.top;
+  } catch {
+    return true;
+  }
+}
+
+export function isDuplicate(): boolean {
+  if ((globalThis as Record<string, unknown>).__drip) return true;
+  (globalThis as Record<string, unknown>).__drip = true;
+  return false;
+}
+
+export function isOptedOut(options?: { storageAllowed?: boolean }): boolean {
+  const storageAllowed = options?.storageAllowed !== false;
+  const param = new URLSearchParams(location.search).get("drip_optout");
+  if (param === "true") {
+    if (storageAllowed) {
+      try {
+        localStorage.setItem("drip_optout", "1");
+      } catch {}
+    }
+    return true;
+  }
+  if (param === "false") {
+    if (storageAllowed) {
+      try {
+        localStorage.removeItem("drip_optout");
+      } catch {}
+    }
+    return false;
+  }
+  if (!storageAllowed) return false;
+  try {
+    return localStorage.getItem("drip_optout") === "1";
+  } catch {
+    return false;
+  }
+}
+
+export function isScreenshotMode(): boolean {
+  const param = new URLSearchParams(location.search).get("drip_screenshot");
+  return param === "1" || param === "true";
+}
+
+const FORCE_EXPERIMENT_PARAM_NAMES = [
+  "drip_experiment_id",
+  "drip_experiment",
+  "experiment_id",
+  "experimentId",
+  "expId",
+];
+
+const FORCE_VARIATION_PARAM_NAMES = [
+  "drip_variation_id",
+  "drip_variation",
+  "variation_id",
+  "variationId",
+  "varId",
+];
+
+function readFirstParam(params: URLSearchParams, names: string[]): string | null {
+  for (const name of names) {
+    const value = params.get(name)?.trim();
+    if (value) return value;
+  }
+  return null;
+}
+
+function parseForceParams(params: URLSearchParams): Record<string, string> | null {
+  const param = params.get("drip_force");
+  if (param) {
+    const map = parseForceString(param);
+    if (map) return map;
+  }
+
+  const experimentId = readFirstParam(params, FORCE_EXPERIMENT_PARAM_NAMES);
+  const variationId = readFirstParam(params, FORCE_VARIATION_PARAM_NAMES);
+  if (experimentId && variationId) {
+    return { [experimentId]: variationId };
+  }
+  return null;
+}
+
+function isDebugQaParam(params: URLSearchParams): boolean {
+  return (
+    params.get("drip_debug") === "1" ||
+    params.get("apex_debug") === "1" ||
+    params.get("drip_devtools") === "1"
+  );
+}
+
+export function parseForceParam(options?: { cookieFallback?: boolean }): Record<string, string> | null {
+  // Check URL param first
+  const map = parseForceParams(new URLSearchParams(location.search));
+  if (map) return map;
+
+  // Fallback to QA cookie
+  if (options?.cookieFallback !== false) {
+    const cookie = readCookie("drip_qa_force");
+    if (cookie) {
+      const map = parseForceString(cookie);
+      if (map) return map;
+    }
+  }
+
+  return null;
+}
+
+function parseForceString(value: string): Record<string, string> | null {
+  const map: Record<string, string> = {};
+  for (const pair of value.split(",")) {
+    const [expId, varId] = pair.split(":");
+    if (expId && varId) map[expId] = varId;
+  }
+  return Object.keys(map).length ? map : null;
+}
+
+// ---------------------------------------------------------------------------
+// QA mode detection and cookie persistence
+// ---------------------------------------------------------------------------
+
+const QA_COOKIE = "drip_qa_force";
+const QA_SESSION_STORAGE_KEY = "drip_qa_session";
+const QA_COOKIE_MAX_AGE = 1800; // 30 minutes
+
+export function isQaMode(options?: { cookieFallback?: boolean }): boolean {
+  if (isScreenshotMode()) return false;
+  const params = new URLSearchParams(location.search);
+  const param = params.get("drip_qa");
+  if (param === "1") return true;
+  if (isDebugQaParam(params) && parseForceParams(params)) return true;
+  if (options?.cookieFallback === false) return false;
+  return !!readCookie(QA_COOKIE);
+}
+
+/**
+ * Persist the force map in a cookie so QA sessions survive navigation.
+ * Cookie expires after 30 minutes.
+ */
+export function persistQaForce(forceMap: Record<string, string>): void {
+  const value = Object.entries(forceMap)
+    .map(([k, v]) => `${k}:${v}`)
+    .join(",");
+  writeCookie(QA_COOKIE, value, QA_COOKIE_MAX_AGE);
+}
+
+function sanitizeQaSessionId(value: string | null): string | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  return /^[a-zA-Z0-9_-]{3,120}$/.test(trimmed) ? trimmed : null;
+}
+
+export function getQaSessionId(fallback: () => string, options?: { storageAllowed?: boolean }): string {
+  const storageAllowed = options?.storageAllowed !== false;
+  const param = sanitizeQaSessionId(
+    new URLSearchParams(location.search).get("drip_qa_session"),
+  );
+  if (param) {
+    if (storageAllowed) {
+      try {
+        sessionStorage.setItem(QA_SESSION_STORAGE_KEY, param);
+      } catch {}
+    }
+    return param;
+  }
+
+  if (!storageAllowed) return fallback();
+
+  try {
+    const stored = sanitizeQaSessionId(sessionStorage.getItem(QA_SESSION_STORAGE_KEY));
+    if (stored) return stored;
+    const generated = fallback();
+    sessionStorage.setItem(QA_SESSION_STORAGE_KEY, generated);
+    return generated;
+  } catch {
+    return fallback();
+  }
+}
+
+/**
+ * Exit QA mode: clear the force cookie and remove drip_qa/drip_force from URL.
+ */
+export function exitQaMode(): void {
+  deleteCookie(QA_COOKIE);
+  try {
+    sessionStorage.removeItem(QA_SESSION_STORAGE_KEY);
+  } catch {}
+  // Remove QA params from URL without reload
+  try {
+    const url = new URL(location.href);
+    url.searchParams.delete("drip_qa");
+    url.searchParams.delete("drip_force");
+    url.searchParams.delete("drip_experiment_id");
+    url.searchParams.delete("drip_experiment");
+    url.searchParams.delete("experiment_id");
+    url.searchParams.delete("experimentId");
+    url.searchParams.delete("expId");
+    url.searchParams.delete("drip_variation_id");
+    url.searchParams.delete("drip_variation");
+    url.searchParams.delete("variation_id");
+    url.searchParams.delete("variationId");
+    url.searchParams.delete("varId");
+    url.searchParams.delete("drip_qa_session");
+    url.searchParams.delete("drip_harness");
+    url.searchParams.delete("drip_debug");
+    url.searchParams.delete("apex_debug");
+    history.replaceState(null, "", url.toString());
+  } catch {}
+}
+
+// ---------------------------------------------------------------------------
+// Cookie helpers
+// ---------------------------------------------------------------------------
+
+export function readCookie(name: string): string | null {
+  try {
+    const match = document.cookie.match(new RegExp("(?:^|; )" + name + "=([^;]*)"));
+    return match ? decodeURIComponent(match[1]) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCookie(name: string, value: string, maxAge: number): void {
+  try {
+    document.cookie = `${name}=${encodeURIComponent(value)};path=/;max-age=${maxAge};samesite=lax`;
+  } catch {}
+}
+
+export function deleteCookie(name: string): void {
+  try {
+    document.cookie = `${name}=;path=/;max-age=0;samesite=lax`;
+  } catch {}
+}
+
+/** @internal — exposed for unit testing only. Tree-shaken from production build. */
+export const __test = {
+  parseForceString,
+  parseForceParams,
+  sanitizeQaSessionId,
+  BOT_RE,
+};

package/src/handover-cache-order.test.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+describe("cached configuration handover ordering", () => {
+  it("verifies through the credential-free endpoint with a bounded request", () => {
+    const source = readFileSync(new URL("./index.ts", import.meta.url), "utf8");
+    const start = source.indexOf("async function verifyBucketingHandoverToken");
+    const end = source.indexOf("function clearScheduledAnalyticsStart", start);
+    const verification = source.slice(start, end);
+
+    expect(verification).toContain("/v1/handover/verify");
+    expect(verification).toContain('"X-Drip-Shop": config.shopId');
+    expect(verification).toContain("JSON.stringify({ verifyToken: token })");
+    expect(verification).toContain("signal: AbortSignal.timeout(handoverMintTimeoutMs(config.externalTracking))");
+    expect(verification).not.toContain("ingestSignature");
+    expect(verification).not.toContain("X-Drip-Signature");
+  });
+
+  it("starts verification before a cached config can initialize and supplies its result", () => {
+    const source = readFileSync(new URL("./index.ts", import.meta.url), "utf8");
+    const cacheRead = source.indexOf("const cached = useConfigCache");
+    const verification = source.indexOf("const handoverPromise = readBucketingHandover", cacheRead);
+    const cachedBranch = source.indexOf("if (cached)", cacheRead);
+    const networkFetch = source.indexOf("fetchWithRetry(configUrl.toString()", cachedBranch);
+    const cachedPath = source.slice(cachedBranch, networkFetch);
+
+    expect(verification).toBeGreaterThan(cacheRead);
+    expect(verification).toBeLessThan(cachedBranch);
+    expect(cachedPath).toContain("handoverPromise.then(initCachedConfig)");
+    expect(cachedPath).toContain('"cache",\n        perfContext,\n        verifiedHandover');
+  });
+});

package/src/handover.test.ts

@@ -0,0 +1,349 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createBucketingHandoverPayload, installBucketingHandover, readBucketingHandover } from "./handover";
+
+describe("installBucketingHandover", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it("accepts only a Worker-verified, unexpired token for the current shop", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-06-25T12:00:00.000Z"));
+    vi.stubGlobal("location", { href: "https://checkout.example.com/?apex_bucket=signed.token" });
+    const settings = { domains: ["checkout.example.com"], handoverQueryParam: "apex_bucket" };
+    const verify = vi.fn(async () => ({
+      v: 2, shop: "shop_a", exp: Math.floor(Date.now() / 1000) + 120,
+      vid: "visitor_1", asg: [{ e: "exp_1", x: "var_1" }],
+    }));
+
+    await expect(readBucketingHandover(settings, "shop_a", verify)).resolves.toEqual({
+      visitorId: "visitor_1",
+      forceMap: { exp_1: "var_1" },
+    });
+    expect(verify).toHaveBeenCalledWith("signed.token");
+  });
+
+  it("rejects absent or invalid signatures and never decodes the raw payload", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-06-25T12:00:00.000Z"));
+    vi.stubGlobal("location", { href: "https://checkout.example.com/?apex_bucket=crafted-unsigned-payload" });
+    await expect(readBucketingHandover(
+      { domains: ["checkout.example.com"] }, "shop_a", async () => null,
+    )).resolves.toBeNull();
+  });
+
+  it("rejects a valid token minted for a different shop", async () => {
+    vi.stubGlobal("location", { href: "https://checkout.example.com/?drip_bucket=signed.token" });
+    await expect(readBucketingHandover(
+      { domains: ["checkout.example.com"] }, "shop_b",
+      async () => ({ shop: "shop_a", exp: Math.floor(Date.now() / 1000) + 120, vid: "attacker" }),
+    )).resolves.toBeNull();
+  });
+
+  it.each([1, 2])("rejects expired v%s payloads", async (version) => {
+    vi.stubGlobal("location", { href: "https://checkout.example.com/?drip_bucket=signed.token" });
+    await expect(readBucketingHandover(
+      { domains: ["checkout.example.com"] }, "shop_a",
+      async () => ({ v: version, shop: "shop_a", exp: Math.floor(Date.now() / 1000) - 1, vid: "expired" }),
+    )).resolves.toBeNull();
+  });
+
+  it("does not read handover params when external tracking has no domains", async () => {
+    vi.stubGlobal("location", { href: "https://checkout.example.com/?drip_bucket=signed.token" });
+    const verify = vi.fn(async () => ({ shop: "shop_a", exp: Math.floor(Date.now() / 1000) + 120 }));
+    await expect(readBucketingHandover({}, "shop_a", verify)).resolves.toBeNull();
+    expect(verify).not.toHaveBeenCalled();
+  });
+
+  it("does not append an unsigned payload when signing is unavailable", () => {
+    const listeners = new Map<string, EventListener>();
+    vi.stubGlobal("document", {
+      addEventListener: vi.fn((type: string, listener: EventListener) => {
+        listeners.set(type, listener);
+      }),
+      removeEventListener: vi.fn(),
+    });
+    vi.stubGlobal("location", { href: "https://store.example.com/products/a" });
+
+    let href = "https://checkout.example.com/next-step";
+    const link = {
+      getAttribute: (name: string) => (name === "href" ? href : null),
+      set href(value: string) {
+        href = value;
+      },
+      get href() {
+        return href;
+      },
+    };
+    const textNode = {
+      parentElement: {
+        closest: (selector: string) => (selector === "a[href]" ? link : null),
+      },
+    };
+
+    installBucketingHandover(
+      { domains: ["checkout.example.com"], handoverQueryParam: "apex_bucket" },
+      () => "payload",
+    );
+
+    listeners.get("click")?.({ target: textNode } as unknown as Event);
+
+    expect(href).toBe("https://checkout.example.com/next-step");
+  });
+
+  it("does not append an unsigned payload during pointer prefetch", () => {
+    const listeners = new Map<string, EventListener>();
+    vi.stubGlobal("document", {
+      addEventListener: vi.fn((type: string, listener: EventListener) => {
+        listeners.set(type, listener);
+      }),
+      removeEventListener: vi.fn(),
+    });
+    vi.stubGlobal("location", { href: "https://store.example.com/" });
+
+    let href = "https://checkout.example.com/next-step";
+    const link = {
+      closest: (selector: string) => (selector === "a[href]" ? link : null),
+      getAttribute: (name: string) => (name === "href" ? href : null),
+      set href(value: string) {
+        href = value;
+      },
+      get href() {
+        return href;
+      },
+      click: vi.fn(),
+    };
+
+    installBucketingHandover(
+      { domains: ["checkout.example.com"], handoverQueryParam: "apex_bucket" },
+      () => "payload",
+    );
+
+    listeners.get("pointerdown")?.({ target: link } as unknown as Event);
+
+    expect(href).toBe("https://checkout.example.com/next-step");
+  });
+
+  it("resumes a first configured-domain click without dispatching merchant handlers twice", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-06-25T12:00:00.000Z"));
+    const listeners = new Map<string, EventListener>();
+    vi.stubGlobal("document", {
+      addEventListener: vi.fn((type: string, listener: EventListener) => {
+        listeners.set(type, listener);
+      }),
+      removeEventListener: vi.fn(),
+    });
+    const assign = vi.fn();
+    vi.stubGlobal("location", { href: "https://store.example.com/", assign });
+
+    let href = "https://checkout.example.com/next-step";
+    const link = {
+      closest: (selector: string) => (selector === "a[href]" ? link : null),
+      getAttribute: (name: string) => (name === "href" ? href : null),
+      set href(value: string) {
+        href = value;
+      },
+      get href() {
+        return href;
+      },
+      click: vi.fn(),
+    };
+    let resolveMint: (value: string) => void = () => {};
+    const mint = vi.fn(() => new Promise<string>((resolve) => {
+      resolveMint = resolve;
+    }));
+    const basePayload = createBucketingHandoverPayload("visitor_3", [], { handoverTtlSeconds: 120 });
+
+    installBucketingHandover(
+      { domains: ["checkout.example.com"], handoverQueryParam: "apex_bucket", signed: true },
+      () => basePayload,
+      mint,
+    );
+
+    const preventDefault = vi.fn();
+    listeners.get("click")?.({ type: "click", target: link, preventDefault } as unknown as Event);
+    expect(href).toBe("https://checkout.example.com/next-step");
+    expect(preventDefault).toHaveBeenCalledOnce();
+    expect(mint).toHaveBeenCalledTimes(1);
+
+    resolveMint(`${basePayload}.signature`);
+    await vi.waitFor(() => expect(assign).toHaveBeenCalledOnce());
+
+    expect(href).toBe(`https://checkout.example.com/next-step?apex_bucket=${basePayload}.signature`);
+    expect(assign).toHaveBeenCalledWith(href);
+    expect(link.click).not.toHaveBeenCalled();
+  });
+
+  it("does not reuse expired signed handover payloads", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-06-25T12:00:00.000Z"));
+    const listeners = new Map<string, EventListener>();
+    vi.stubGlobal("document", {
+      addEventListener: vi.fn((type: string, listener: EventListener) => {
+        listeners.set(type, listener);
+      }),
+      removeEventListener: vi.fn(),
+    });
+    vi.stubGlobal("location", { href: "https://store.example.com/" });
+
+    let href = "https://checkout.example.com/next-step";
+    const link = {
+      closest: (selector: string) => (selector === "a[href]" ? link : null),
+      getAttribute: (name: string) => (name === "href" ? href : null),
+      set href(value: string) {
+        href = value;
+      },
+      get href() {
+        return href;
+      },
+    };
+    const initialBasePayload = createBucketingHandoverPayload("visitor_4", [], { handoverTtlSeconds: 120 });
+    const getPayload = vi.fn(() => createBucketingHandoverPayload("visitor_4", [], { handoverTtlSeconds: 120 }));
+
+    installBucketingHandover(
+      { domains: ["checkout.example.com"], handoverQueryParam: "apex_bucket", signed: true },
+      getPayload,
+      async () => `${initialBasePayload}.signature`,
+    );
+
+    listeners.get("pointerdown")?.({ target: link } as unknown as Event);
+    await Promise.resolve();
+    vi.setSystemTime(new Date("2026-06-25T12:02:01.000Z"));
+    href = "https://checkout.example.com/next-step";
+    listeners.get("click")?.({ target: link } as unknown as Event);
+
+    expect(href).toBe("https://checkout.example.com/next-step");
+    expect(href).not.toContain(`${initialBasePayload}.signature`);
+  });
+
+  it("adds only signed handover payloads to configured external checkout forms", async () => {
+    const listeners = new Map<string, EventListener>();
+    const hiddenInputs: Array<{ type: string; name: string; value: string }> = [];
+    let action = "https://checkout.example.com/pay";
+    const form = {
+      tagName: "FORM",
+      getAttribute: (name: string) => (name === "action" ? "https://checkout.example.com/pay" : null),
+      set action(value: string) {
+        action = value;
+      },
+      get action() {
+        return action;
+      },
+      querySelector: () => null,
+      appendChild: (input: { type: string; name: string; value: string }) => {
+        hiddenInputs.push(input);
+      },
+      requestSubmit: vi.fn(),
+    };
+    vi.stubGlobal("document", {
+      addEventListener: vi.fn((type: string, listener: EventListener) => {
+        listeners.set(type, listener);
+      }),
+      removeEventListener: vi.fn(),
+      createElement: vi.fn(() => ({ type: "", name: "", value: "" })),
+    });
+    vi.stubGlobal("location", { href: "https://store.example.com/" });
+
+    installBucketingHandover(
+      { domains: ["checkout.example.com"], handoverQueryParam: "apex_bucket" },
+      () => createBucketingHandoverPayload("visitor_form", []),
+      async () => `${createBucketingHandoverPayload("visitor_form", [])}.signature`,
+    );
+
+    const submitterAttributes = new Map([
+      ["formaction", "https://checkout.example.com/express-pay"],
+      ["formmethod", "post"],
+    ]);
+    const submitter = {
+      getAttribute: (name: string) => submitterAttributes.get(name) ?? null,
+      hasAttribute: (name: string) => submitterAttributes.has(name),
+      setAttribute: (name: string, value: string) => submitterAttributes.set(name, value),
+    } as unknown as HTMLElement;
+    const preventDefault = vi.fn();
+    listeners.get("submit")?.({
+      target: form,
+      submitter,
+      preventDefault,
+    } as unknown as SubmitEvent);
+    await vi.waitFor(() => expect(form.requestSubmit).toHaveBeenCalledOnce());
+
+    expect(preventDefault).toHaveBeenCalledOnce();
+    expect(submitter.getAttribute("formaction")).toContain("https://checkout.example.com/express-pay?apex_bucket=");
+    expect(submitter.getAttribute("formaction")).toContain(".signature");
+    expect(submitter.getAttribute("formmethod")).toBe("post");
+    expect(hiddenInputs).toHaveLength(1);
+    expect(hiddenInputs[0]).toMatchObject({ type: "hidden", name: "apex_bucket" });
+    expect(hiddenInputs[0].value).toContain(".signature");
+    expect(form.requestSubmit).toHaveBeenCalledWith(submitter);
+  });
+
+  it("does not inject handover inputs into non-configured forms", () => {
+    const listeners = new Map<string, EventListener>();
+    const hiddenInputs: Array<{ type: string; name: string; value: string }> = [];
+    const form = {
+      tagName: "FORM",
+      action: "https://store.example.com/account",
+      getAttribute: (name: string) => (name === "action" ? "/account" : null),
+      querySelector: () => null,
+      appendChild: (input: { type: string; name: string; value: string }) => {
+        hiddenInputs.push(input);
+      },
+      requestSubmit: vi.fn(),
+    };
+    vi.stubGlobal("document", {
+      addEventListener: vi.fn((type: string, listener: EventListener) => {
+        listeners.set(type, listener);
+      }),
+      removeEventListener: vi.fn(),
+      createElement: vi.fn(() => ({ type: "", name: "", value: "" })),
+    });
+    vi.stubGlobal("location", { href: "https://store.example.com/" });
+
+    const mint = vi.fn(async () => "payload.signature");
+    installBucketingHandover(
+      { domains: ["checkout.example.com"], handoverQueryParam: "apex_bucket" },
+      () => "payload",
+      mint,
+    );
+
+    const preventDefault = vi.fn();
+    listeners.get("submit")?.({ target: form, preventDefault } as unknown as Event);
+
+    expect(preventDefault).not.toHaveBeenCalled();
+    expect(mint).not.toHaveBeenCalled();
+    expect(form.requestSubmit).not.toHaveBeenCalled();
+    expect(hiddenInputs).toHaveLength(0);
+  });
+
+  it("does not delay or redispatch same-domain link clicks while minting is available", () => {
+    const listeners = new Map<string, EventListener>();
+    vi.stubGlobal("document", {
+      addEventListener: vi.fn((type: string, listener: EventListener) => {
+        listeners.set(type, listener);
+      }),
+      removeEventListener: vi.fn(),
+    });
+    vi.stubGlobal("location", { href: "https://store.example.com/" });
+
+    const link = {
+      closest: (selector: string) => (selector === "a[href]" ? link : null),
+      getAttribute: (name: string) => (name === "href" ? "/collections/new" : null),
+      click: vi.fn(),
+    };
+    const mint = vi.fn(async () => "payload.signature");
+    installBucketingHandover(
+      { domains: ["checkout.example.com"], handoverQueryParam: "apex_bucket" },
+      () => "payload",
+      mint,
+    );
+
+    const preventDefault = vi.fn();
+    listeners.get("click")?.({ type: "click", target: link, preventDefault } as unknown as Event);
+
+    expect(preventDefault).not.toHaveBeenCalled();
+    expect(mint).not.toHaveBeenCalled();
+    expect(link.click).not.toHaveBeenCalled();
+  });
+});