@drip-apex/sdk 0.1.0 → 0.3.0

package/src/guards.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from "vitest";
-import { __test, getQaSessionId, isQaMode, isScreenshotMode } from "./guards";
+import { __test, clearQaForceFromUrl, getQaSessionId, isQaMode, isScreenshotMode, parseForceParam, persistQaForce, persistUrlQaForce } from "./guards";
 
 const { parseForceString, parseForceParams, sanitizeQaSessionId, BOT_RE } = __test;
 
@@ -40,6 +40,9 @@ describe("parseForceString", () => {
 });
 
 describe("parseForceParams", () => {
+  it("never parses the clear sentinel as a variation force", () => {
+    expect(parseForceParams(new URLSearchParams("drip_force=clear"))).toBeNull();
+  });
   it("keeps supporting canonical drip_force pairs", () => {
     expect(
       parseForceParams(
@@ -68,6 +71,69 @@ describe("parseForceParams", () => {
       ),
     ).toEqual({ exp_canonical: "var_canonical" });
   });
+
+  it("does not fall through to aliases when canonical force is clear or malformed", () => {
+    const aliases = "&drip_experiment_id=exp_alias&drip_variation_id=var_alias";
+    expect(parseForceParams(new URLSearchParams(`drip_force=clear${aliases}`))).toBeNull();
+    expect(parseForceParams(new URLSearchParams(`drip_force=malformed${aliases}`))).toBeNull();
+  });
+});
+
+describe("QA force lifetime", () => {
+  const originals = {
+    location: Object.getOwnPropertyDescriptor(globalThis, "location"),
+    document: Object.getOwnPropertyDescriptor(globalThis, "document"),
+    history: Object.getOwnPropertyDescriptor(globalThis, "history"),
+    sessionStorage: Object.getOwnPropertyDescriptor(globalThis, "sessionStorage"),
+  };
+
+  afterEach(() => {
+    for (const [key, descriptor] of Object.entries(originals)) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else delete (globalThis as Record<string, unknown>)[key];
+    }
+  });
+
+  function install(url: string) {
+    const cookieWrites: string[] = [];
+    const removed: string[] = [];
+    let replaced = "";
+    Object.defineProperty(globalThis, "location", { configurable: true, value: { href: url, search: new URL(url).search } });
+    Object.defineProperty(globalThis, "document", { configurable: true, value: { get cookie() { return "drip_qa_force=exp_old%3Avar_old"; }, set cookie(value: string) { cookieWrites.push(value); } } });
+    Object.defineProperty(globalThis, "history", { configurable: true, value: { replaceState: (_a: unknown, _b: string, value: string) => { replaced = value; } } });
+    Object.defineProperty(globalThis, "sessionStorage", { configurable: true, value: { removeItem: (key: string) => removed.push(key) } });
+    return { cookieWrites, removed, replaced: () => replaced };
+  }
+
+  it("clear sentinel deletes the force cookie and session key and strips QA parameters", () => {
+    const observed = install("https://shop.test/p?x=1&drip_force=clear&drip_qa=1&drip_qa_session=qa_1&drip_debug=1");
+    expect(clearQaForceFromUrl()).toBe(true);
+    expect(observed.cookieWrites).toContain("drip_qa_force=;path=/;max-age=0;samesite=lax");
+    expect(observed.removed).toEqual(["drip_qa_session"]);
+    expect(observed.replaced()).toBe("https://shop.test/p?x=1");
+  });
+
+  it("renews the cookie on a paramless cookie-backed load", () => {
+    const observed = install("https://shop.test/p");
+    persistUrlQaForce({ exp_old: "var_old" });
+    expect(observed.cookieWrites).toEqual([
+      "drip_qa_force=exp_old%3Avar_old;path=/;max-age=1800;samesite=lax",
+    ]);
+  });
+
+  it("persists and renews an explicit URL force", () => {
+    const observed = install("https://shop.test/p?drip_force=exp_1%3Avar_1");
+    persistUrlQaForce({ exp_1: "var_1" });
+    expect(observed.cookieWrites).toEqual([
+      "drip_qa_force=exp_1%3Avar_1;path=/;max-age=1800;samesite=lax",
+    ]);
+  });
+
+  it("keeps assistant persistence explicit and independent of the URL", () => {
+    const observed = install("https://shop.test/p");
+    persistQaForce({ exp_2: "var_2" });
+    expect(observed.cookieWrites).toHaveLength(1);
+  });
 });
 
 describe("BOT_RE", () => {
@@ -188,6 +254,38 @@ describe("isQaMode", () => {
     expect(isScreenshotMode()).toBe(true);
     expect(isQaMode()).toBe(false);
   });
+
+  it("treats an empty force parameter as authoritative over a stale QA cookie", () => {
+    Object.defineProperty(globalThis, "document", {
+      configurable: true,
+      value: { cookie: "drip_qa_force=exp_1%3Avar_1" },
+    });
+    setSearch("?drip_force=");
+
+    expect(parseForceParam()).toBeNull();
+    expect(isQaMode()).toBe(false);
+  });
+
+  it("keeps the cookie fallback when the force parameter is absent", () => {
+    Object.defineProperty(globalThis, "document", {
+      configurable: true,
+      value: { cookie: "drip_qa_force=exp_1%3Avar_1" },
+    });
+    setSearch("");
+
+    expect(parseForceParam()).toEqual({ exp_1: "var_1" });
+    expect(isQaMode()).toBe(true);
+  });
+
+  it("keeps a non-empty force parameter authoritative", () => {
+    Object.defineProperty(globalThis, "document", {
+      configurable: true,
+      value: { cookie: "drip_qa_force=exp_old%3Avar_old" },
+    });
+    setSearch("?drip_force=exp_new%3Avar_new");
+
+    expect(parseForceParam()).toEqual({ exp_new: "var_new" });
+  });
 });
 
 describe("QA session IDs", () => {

package/src/guards.ts

@@ -76,9 +76,9 @@ function readFirstParam(params: URLSearchParams, names: string[]): string | 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;
+  if (param !== null) {
+    if (param.trim().toLowerCase() === "clear") return null;
+    return parseForceString(param);
   }
 
   const experimentId = readFirstParam(params, FORCE_EXPERIMENT_PARAM_NAMES);
@@ -89,6 +89,17 @@ function parseForceParams(params: URLSearchParams): Record<string, string> | nul
   return null;
 }
 
+export function hasExplicitForceParam(): boolean {
+  return parseForceParams(new URLSearchParams(location.search)) !== null;
+}
+
+export function clearQaForceFromUrl(): boolean {
+  const force = new URLSearchParams(location.search).get("drip_force")?.trim().toLowerCase();
+  if (force !== "clear") return false;
+  exitQaMode();
+  return true;
+}
+
 function isDebugQaParam(params: URLSearchParams): boolean {
   return (
     params.get("drip_debug") === "1" ||
@@ -97,18 +108,21 @@ function isDebugQaParam(params: URLSearchParams): boolean {
   );
 }
 
-export function parseForceParam(options?: { cookieFallback?: boolean }): Record<string, string> | null {
+export function parseForceParam(): Record<string, string> | null {
   // Check URL param first
-  const map = parseForceParams(new URLSearchParams(location.search));
+  const params = new URLSearchParams(location.search);
+  const map = parseForceParams(params);
   if (map) return map;
+  // A present canonical parameter is authoritative even when empty, cleared,
+  // or malformed. In particular, `?drip_force=` must not resurrect a stale
+  // QA force from the cookie.
+  if (params.has("drip_force")) return null;
 
-  // Fallback to QA cookie
-  if (options?.cookieFallback !== false) {
-    const cookie = readCookie("drip_qa_force");
-    if (cookie) {
-      const map = parseForceString(cookie);
-      if (map) return map;
-    }
+  // Fallback to the functional QA cookie.
+  const cookie = readCookie("drip_qa_force");
+  if (cookie) {
+    const map = parseForceString(cookie);
+    if (map) return map;
   }
 
   return null;
@@ -131,19 +145,19 @@ 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 {
+export function isQaMode(): 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;
+  if (params.has("drip_force")) return false;
   return !!readCookie(QA_COOKIE);
 }
 
 /**
  * Persist the force map in a cookie so QA sessions survive navigation.
- * Cookie expires after 30 minutes.
+ * Cookie expires at most 30 minutes after the latest QA page load or assistant force.
  */
 export function persistQaForce(forceMap: Record<string, string>): void {
   const value = Object.entries(forceMap)
@@ -152,6 +166,11 @@ export function persistQaForce(forceMap: Record<string, string>): void {
   writeCookie(QA_COOKIE, value, QA_COOKIE_MAX_AGE);
 }
 
+/** Persist an explicit URL force or renew an existing cookie-backed force. */
+export function persistUrlQaForce(forceMap: Record<string, string>): void {
+  if (hasExplicitForceParam() || readCookie(QA_COOKIE)) persistQaForce(forceMap);
+}
+
 function sanitizeQaSessionId(value: string | null): string | null {
   if (!value) return null;
   const trimmed = value.trim();

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

@@ -3,7 +3,7 @@ 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 source = readFileSync(new URL("./config-runtime.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);
@@ -17,7 +17,7 @@ describe("cached configuration handover ordering", () => {
   });
 
   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 source = readFileSync(new URL("./public-api.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);
@@ -27,6 +27,9 @@ describe("cached configuration handover ordering", () => {
     expect(verification).toBeGreaterThan(cacheRead);
     expect(verification).toBeLessThan(cachedBranch);
     expect(cachedPath).toContain("handoverPromise.then(initCachedConfig)");
-    expect(cachedPath).toContain('"cache",\n        perfContext,\n        verifiedHandover');
+    expect(cachedPath).toContain(
+      '"cache",\n          perfContext,\n          cachedVerifiedRedirectCarry,\n          verifiedHandover',
+    );
+    expect(cachedPath).toContain("verifiedRedirectCarryPromise");
   });
 });

package/src/handover.test.ts

@@ -1,5 +1,10 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { createBucketingHandoverPayload, installBucketingHandover, readBucketingHandover } from "./handover";
+import {
+  createBucketingHandoverPayload,
+  installBucketingHandover,
+  readBucketingHandover,
+  readBucketingHandoverPayload,
+} from "./handover";
 
 describe("installBucketingHandover", () => {
   afterEach(() => {
@@ -33,6 +38,43 @@ describe("installBucketingHandover", () => {
     )).resolves.toBeNull();
   });
 
+  it.each([
+    ["CJK", "访客用户"],
+    ["emoji", "visitor_🧪🚀"],
+  ])("round-trips UTF-8 %s visitor ids", (_label, visitorId) => {
+    const payload = createBucketingHandoverPayload(
+      visitorId,
+      [{ experimentId: "exp_utf8", variationId: "var_utf8", index: 0, mutations: [], isControl: false, hashValue: "hash_utf8" }],
+    );
+
+    expect(payload).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(readBucketingHandoverPayload(payload)).toEqual({
+      visitorId,
+      forceMap: { exp_utf8: "var_utf8" },
+    });
+  });
+
+  it("ignores redirect attribution in an unverified handover payload", () => {
+    const encoded = btoa(JSON.stringify({
+      v: 2,
+      exp: Math.floor(Date.now() / 1000) + 120,
+      vid: "visitor_1",
+      asg: [{ e: "exp_1", x: "var_1" }],
+      ra: {
+        e: "exp_1",
+        v: "var_1",
+        d: "https://destination.example/landing",
+        iat: Date.now(),
+        t: "unverified-bearer-material",
+      },
+    })).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+    expect(readBucketingHandoverPayload(encoded)).toEqual({
+      visitorId: "visitor_1",
+      forceMap: { exp_1: "var_1" },
+    });
+  });
+
   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(
@@ -125,9 +167,9 @@ describe("installBucketingHandover", () => {
     expect(href).toBe("https://checkout.example.com/next-step");
   });
 
-  it("resumes a first configured-domain click without dispatching merchant handlers twice", async () => {
+  it("reuses a freshly minted token when only iat and exp change during the request", async () => {
     vi.useFakeTimers();
-    vi.setSystemTime(new Date("2026-06-25T12:00:00.000Z"));
+    vi.setSystemTime(new Date("2026-06-25T12:00:00.900Z"));
     const listeners = new Map<string, EventListener>();
     vi.stubGlobal("document", {
       addEventListener: vi.fn((type: string, listener: EventListener) => {
@@ -158,7 +200,7 @@ describe("installBucketingHandover", () => {
 
     installBucketingHandover(
       { domains: ["checkout.example.com"], handoverQueryParam: "apex_bucket", signed: true },
-      () => basePayload,
+      () => createBucketingHandoverPayload("visitor_3", [], { handoverTtlSeconds: 120 }),
       mint,
     );
 
@@ -168,6 +210,7 @@ describe("installBucketingHandover", () => {
     expect(preventDefault).toHaveBeenCalledOnce();
     expect(mint).toHaveBeenCalledTimes(1);
 
+    vi.setSystemTime(new Date("2026-06-25T12:00:01.100Z"));
     resolveMint(`${basePayload}.signature`);
     await vi.waitFor(() => expect(assign).toHaveBeenCalledOnce());
 
@@ -176,6 +219,58 @@ describe("installBucketingHandover", () => {
     expect(link.click).not.toHaveBeenCalled();
   });
 
+  it("does not reuse a freshly minted token after assignments change", 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;
+      },
+    };
+    let variationId = "variation_a";
+    const getPayload = () => createBucketingHandoverPayload(
+      "visitor_assignment",
+      [{ experimentId: "experiment_1", variationId }],
+    );
+    const mintedBasePayload = getPayload();
+    let resolveMint: (value: string) => void = () => {};
+    const mint = vi.fn(() => new Promise<string>((resolve) => {
+      resolveMint = resolve;
+    }));
+
+    installBucketingHandover(
+      { domains: ["checkout.example.com"], handoverQueryParam: "apex_bucket", signed: true },
+      getPayload,
+      mint,
+    );
+
+    const preventDefault = vi.fn();
+    listeners.get("click")?.({ type: "click", target: link, preventDefault } as unknown as Event);
+    variationId = "variation_b";
+    resolveMint(`${mintedBasePayload}.signature`);
+    await vi.waitFor(() => expect(assign).toHaveBeenCalledOnce());
+
+    expect(preventDefault).toHaveBeenCalledOnce();
+    expect(href).toBe("https://checkout.example.com/next-step");
+    expect(assign).toHaveBeenCalledWith(href);
+  });
+
   it("does not reuse expired signed handover payloads", async () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-06-25T12:00:00.000Z"));
@@ -186,7 +281,8 @@ describe("installBucketingHandover", () => {
       }),
       removeEventListener: vi.fn(),
     });
-    vi.stubGlobal("location", { href: "https://store.example.com/" });
+    const assign = vi.fn();
+    vi.stubGlobal("location", { href: "https://store.example.com/", assign });
 
     let href = "https://checkout.example.com/next-step";
     const link = {
@@ -208,16 +304,66 @@ describe("installBucketingHandover", () => {
       async () => `${initialBasePayload}.signature`,
     );
 
-    listeners.get("pointerdown")?.({ target: link } as unknown as Event);
-    await Promise.resolve();
+    const firstPreventDefault = vi.fn();
+    listeners.get("click")?.({ type: "click", target: link, preventDefault: firstPreventDefault } as unknown as Event);
+    await vi.waitFor(() => expect(assign).toHaveBeenCalledOnce());
+    expect(firstPreventDefault).toHaveBeenCalledOnce();
+    expect(href).toContain(`${initialBasePayload}.signature`);
+
     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);
+    assign.mockClear();
+    const secondPreventDefault = vi.fn();
+    listeners.get("click")?.({ type: "click", target: link, preventDefault: secondPreventDefault } as unknown as Event);
+    await vi.waitFor(() => expect(assign).toHaveBeenCalledOnce());
 
+    expect(secondPreventDefault).toHaveBeenCalledOnce();
     expect(href).toBe("https://checkout.example.com/next-step");
     expect(href).not.toContain(`${initialBasePayload}.signature`);
   });
 
+  it("treats a malformed mint-time base payload as a cache miss without throwing", 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;
+      },
+    };
+    const signedBasePayload = createBucketingHandoverPayload("visitor_valid", []);
+    installBucketingHandover(
+      { domains: ["checkout.example.com"], handoverQueryParam: "apex_bucket", signed: true },
+      () => "%",
+      async () => `${signedBasePayload}.signature`,
+    );
+
+    const preventDefault = vi.fn();
+    expect(() => {
+      listeners.get("click")?.({ type: "click", target: link, preventDefault } as unknown as Event);
+    }).not.toThrow();
+    await vi.waitFor(() => expect(assign).toHaveBeenCalledOnce());
+
+    expect(preventDefault).toHaveBeenCalledOnce();
+    expect(href).toBe("https://checkout.example.com/next-step");
+    expect(assign).toHaveBeenCalledWith(href);
+  });
+
   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 }> = [];

package/src/handover.ts

@@ -3,6 +3,13 @@ import type { Assignment, ExternalTrackingSettings } from "./types";
 export type HandoverData = {
   visitorId?: string;
   forceMap?: Record<string, string>;
+  redirectAttribution?: {
+    experimentId: string;
+    variationId: string;
+    destinationUrl: string;
+    issuedAt: number;
+    token: string;
+  };
 };
 
 const DEFAULT_HANDOVER_TTL_SECONDS = 120;
@@ -30,7 +37,29 @@ function enabledDomains(settings?: ExternalTrackingSettings): string[] {
 
 function encodePayload(value: unknown): string {
   const json = JSON.stringify(value);
-  return btoa(json).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  const bytes = new TextEncoder().encode(json);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function decodePayloadRecord(value: string): Record<string, unknown> {
+  const payloadPart = value.includes(".") ? value.split(".")[0] : value;
+  const normalized = payloadPart.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  let json: string;
+  try {
+    json = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    // Preserve compatibility with v2 payloads emitted before UTF-8 encoding.
+    json = binary;
+  }
+  return JSON.parse(json) as Record<string, unknown>;
 }
 
 type VerifiedHandoverPayload = Record<string, unknown>;
@@ -58,19 +87,69 @@ function decodeVerifiedPayload(parsed: VerifiedHandoverPayload, shopId: string):
         }
       }
     }
+    const rawAttribution = parsed.ra;
+    const redirectAttribution = rawAttribution && typeof rawAttribution === "object"
+      && typeof (rawAttribution as Record<string, unknown>).e === "string"
+      && typeof (rawAttribution as Record<string, unknown>).v === "string"
+      && typeof (rawAttribution as Record<string, unknown>).d === "string"
+      && typeof (rawAttribution as Record<string, unknown>).iat === "number"
+      && typeof (rawAttribution as Record<string, unknown>).t === "string"
+      ? {
+          experimentId: (rawAttribution as Record<string, unknown>).e as string,
+          variationId: (rawAttribution as Record<string, unknown>).v as string,
+          destinationUrl: (rawAttribution as Record<string, unknown>).d as string,
+          issuedAt: (rawAttribution as Record<string, unknown>).iat as number,
+          token: (rawAttribution as Record<string, unknown>).t as string,
+        }
+      : undefined;
+    return { visitorId: visitorIdV2 ?? visitorId, forceMap, redirectAttribution };
+  } catch {
+    return null;
+  }
+}
+
+function decodePayload(value: string): HandoverData | null {
+  try {
+    const parsed = decodePayloadRecord(value);
+    if (parsed.v === 2) {
+      const exp = typeof parsed.exp === "number" ? parsed.exp : 0;
+      if (!exp || Math.floor(Date.now() / 1000) > exp) return null;
+    }
+    const visitorId = typeof parsed.visitorId === "string" ? parsed.visitorId : undefined;
+    const visitorIdV2 = typeof parsed.vid === "string" ? parsed.vid : undefined;
+    const forceMap: Record<string, string> = {};
+    const assignments = Array.isArray(parsed.assignments)
+      ? parsed.assignments
+      : Array.isArray(parsed.asg)
+        ? parsed.asg
+        : [];
+    for (const item of assignments) {
+      if (!item || typeof item !== "object") continue;
+      const record = item as Record<string, unknown>;
+      if (typeof record.experimentId === "string" && typeof record.variationId === "string") {
+        forceMap[record.experimentId] = record.variationId;
+      } else if (typeof record.e === "string" && typeof record.x === "string") {
+        forceMap[record.e] = record.x;
+      }
+    }
+    // Redirect attribution (`ra`) is bearer-backed evidence and is trusted only
+    // after Worker verification in decodeVerifiedPayload. This unverified
+    // compatibility reader intentionally ignores it.
     return { visitorId: visitorIdV2 ?? visitorId, forceMap };
   } catch {
     return null;
   }
 }
 
-function readPayloadExp(value: string): number | null {
+/** Decode a handover token carried by another runtime transport. */
+export function readBucketingHandoverPayload(value: string): HandoverData | null {
+  return decodePayload(value);
+}
+
+export function bucketingHandoverExpiresAtMs(value: string): number | null {
   try {
-    const payloadPart = value.includes(".") ? value.split(".")[0] : value;
-    const normalized = payloadPart.replace(/-/g, "+").replace(/_/g, "/");
-    const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
-    const parsed = JSON.parse(atob(padded)) as Record<string, unknown>;
-    return typeof parsed.exp === "number" ? parsed.exp : null;
+    const parsed = decodePayloadRecord(value);
+    return typeof parsed.exp === "number" ? parsed.exp * 1000 : null;
   } catch {
     return null;
   }
@@ -139,6 +218,15 @@ export async function readBucketingHandover(
   if (!globalThis.location || !enabledDomains(settings).length || !shopId) return null;
   const value = new URL(globalThis.location.href).searchParams.get(paramName(settings));
   if (!value) return null;
+  return verifyBucketingHandoverToken(value, shopId, verifyToken);
+}
+
+export async function verifyBucketingHandoverToken(
+  value: string,
+  shopId: string,
+  verifyToken: (token: string) => Promise<unknown>,
+): Promise<HandoverData | null> {
+  if (!value || !shopId) return null;
   try {
     const verified = await verifyToken(value);
     return verified && typeof verified === "object"
@@ -156,7 +244,7 @@ export function hasBucketingHandover(settings?: ExternalTrackingSettings): boole
 
 export function createBucketingHandoverPayload(
   visitorId: string,
-  assignments: Assignment[],
+  assignments: Array<Pick<Assignment, "experimentId" | "variationId">>,
   settings?: ExternalTrackingSettings,
 ): string {
   const iat = Math.floor(Date.now() / 1000);
@@ -172,6 +260,23 @@ export function createBucketingHandoverPayload(
   });
 }
 
+function bucketingHandoverCacheKey(encodedPayload: string): string | null {
+  try {
+    const parsed = decodePayloadRecord(encodedPayload);
+    if (typeof parsed.vid !== "string" || !Array.isArray(parsed.asg)) return null;
+    const assignments: Array<{ e: string; x: string }> = [];
+    for (const assignment of parsed.asg) {
+      if (!assignment || typeof assignment !== "object") return null;
+      const record = assignment as Record<string, unknown>;
+      if (typeof record.e !== "string" || typeof record.x !== "string") return null;
+      assignments.push({ e: record.e, x: record.x });
+    }
+    return JSON.stringify({ vid: parsed.vid, asg: assignments });
+  } catch {
+    return null;
+  }
+}
+
 export function installBucketingHandover(
   settings: ExternalTrackingSettings | undefined,
   getPayload: () => string | null,
@@ -180,19 +285,22 @@ export function installBucketingHandover(
   const domains = enabledDomains(settings);
   if (!domains.length || !globalThis.document) return () => {};
   let cachedSignedPayload: string | null = null;
-  let cachedBasePayload: string | null = null;
+  let cachedBaseKey: string | null = null;
   let cachedSignedPayloadExp = 0;
   let mintInFlight: Promise<string | null> | null = null;
   const mint = () => {
     if (!mintPayload) return null;
     const basePayload = getPayload();
     if (!basePayload) return null;
+    const baseKey = bucketingHandoverCacheKey(basePayload);
     if (!mintInFlight) {
       mintInFlight = mintPayload()
         .then((payload) => {
           cachedSignedPayload = payload;
-          cachedBasePayload = payload ? basePayload : null;
-          cachedSignedPayloadExp = payload ? readPayloadExp(payload) ?? 0 : 0;
+          cachedBaseKey = payload ? baseKey : null;
+          cachedSignedPayloadExp = payload
+            ? Math.floor((bucketingHandoverExpiresAtMs(payload) ?? 0) / 1000)
+            : 0;
           return payload;
         })
         .catch(() => null)
@@ -205,10 +313,12 @@ export function installBucketingHandover(
 
   const bestPayload = (): string | null => {
     const basePayload = getPayload();
+    const baseKey = basePayload ? bucketingHandoverCacheKey(basePayload) : null;
     const now = Math.floor(Date.now() / 1000);
     if (
       cachedSignedPayload
-      && cachedBasePayload === basePayload
+      && cachedBaseKey !== null
+      && cachedBaseKey === baseKey
       && cachedSignedPayloadExp > now
     ) {
       return cachedSignedPayload;