@drip-apex/sdk 0.1.0 → 0.3.0

package/src/assignment-cookie-sync.test.ts

@@ -0,0 +1,202 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  ASSIGNMENT_SYNC_COOKIE_MAX_BYTES,
+  ASSIGNMENT_SYNC_COOKIE_NAME,
+  clearAssignmentSyncCookie,
+  discoverRegistrableDomain,
+  encodeStoredAssignment,
+  writeAssignmentSyncCookie,
+  type AssignmentSyncPayload,
+} from "./assignment-cookie-sync";
+
+function decodeWithPixelFormat(raw: string): { storedAt: number; data: AssignmentSyncPayload } {
+  const normalized = raw.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+  return JSON.parse(atob(padded));
+}
+
+function payload(assignments: AssignmentSyncPayload["assignments"] = []): AssignmentSyncPayload {
+  return {
+    visitorId: "visitor-1",
+    sessionId: "session-1",
+    qaMode: false,
+    qaSessionId: "",
+    assignments,
+  };
+}
+
+function installDomainAwareCookieJar(acceptedDomain?: string) {
+  const values = new Map<string, string>();
+  const writes: string[] = [];
+  const documentRef = {} as Document;
+  Object.defineProperty(documentRef, "cookie", {
+    configurable: true,
+    get: () => Array.from(values, ([name, value]) => `${name}=${value}`).join("; "),
+    set: (raw: string) => {
+      writes.push(raw);
+      const segments = raw.split(";").map((segment) => segment.trim());
+      const domain = segments.find((segment) => segment.toLowerCase().startsWith("domain="))
+        ?.slice("domain=".length)
+        .replace(/^\./, "");
+      if (domain && domain !== acceptedDomain) return;
+      const separator = segments[0].indexOf("=");
+      const name = segments[0].slice(0, separator);
+      const value = segments[0].slice(separator + 1);
+      if (segments.some((segment) => segment.toLowerCase() === "max-age=0")) {
+        values.delete(name);
+      } else {
+        values.set(name, value);
+      }
+    },
+  });
+  return { documentRef, writes, values };
+}
+
+describe("assignment cookie sync", () => {
+  const originalDocument = globalThis.document;
+  const originalLocation = globalThis.location;
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (originalDocument) {
+      (globalThis as any).document = originalDocument;
+    } else {
+      delete (globalThis as any).document;
+    }
+    if (originalLocation) {
+      (globalThis as any).location = originalLocation;
+    } else {
+      delete (globalThis as any).location;
+    }
+  });
+
+  it("encodes a payload in the pixel's base64url wrapper format", () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_234_567);
+    const input = payload([{ experimentId: "exp-1", variationId: "var-1", assignmentEpoch: 4 }]);
+
+    expect(decodeWithPixelFormat(encodeStoredAssignment(input))).toEqual({
+      storedAt: 1_234_567,
+      data: input,
+    });
+  });
+
+  it("retains the pixel's two-hour staleness boundary", () => {
+    vi.spyOn(Date, "now").mockReturnValue(10_000);
+    const stored = decodeWithPixelFormat(encodeStoredAssignment(payload()));
+    const assignmentMaxAgeMs = 2 * 60 * 60 * 1_000;
+
+    expect(10_000 + assignmentMaxAgeMs - stored.storedAt > assignmentMaxAgeMs).toBe(false);
+    expect(10_001 + assignmentMaxAgeMs - stored.storedAt > assignmentMaxAgeMs).toBe(true);
+  });
+
+  it("discovers example.co.uk after the browser rejects co.uk", () => {
+    const { documentRef, writes } = installDomainAwareCookieJar("example.co.uk");
+
+    expect(discoverRegistrableDomain("shop.example.co.uk", documentRef)).toBe("example.co.uk");
+    expect(writes[0]).toContain("Domain=.co.uk");
+    expect(writes.some((write) => write.includes("Domain=.example.co.uk"))).toBe(true);
+  });
+
+  it.each(["localhost", "127.0.0.1", "[::1]"])("uses a host-only cookie on %s", (hostname) => {
+    const { documentRef } = installDomainAwareCookieJar();
+    expect(discoverRegistrableDomain(hostname, documentRef)).toBeUndefined();
+  });
+
+  it("writes the shared-domain cookie with the required attributes", () => {
+    const { documentRef, writes } = installDomainAwareCookieJar("example.com");
+    (globalThis as any).document = documentRef;
+    (globalThis as any).location = { hostname: "store.example.com" };
+
+    const result = writeAssignmentSyncCookie(payload([
+      { experimentId: "exp-1", variationId: "var-1" },
+    ]));
+
+    expect(result).toMatchObject({ written: true, domain: "example.com", truncatedAssignmentCount: 0 });
+    const cookieWrite = writes.find((write) => write.startsWith(`${ASSIGNMENT_SYNC_COOKIE_NAME}=`));
+    expect(cookieWrite).toMatch(/; Max-Age=7200; Path=\/; SameSite=Lax; Secure; Domain=\.example\.com$/);
+  });
+
+  it("drops the oldest assignments until the encoded value fits", () => {
+    const { documentRef, writes } = installDomainAwareCookieJar("example.com");
+    (globalThis as any).document = documentRef;
+    (globalThis as any).location = { hostname: "store.example.com" };
+    const assignments = Array.from({ length: 80 }, (_, index) => ({
+      experimentId: `exp-${String(index).padStart(3, "0")}-${"x".repeat(80)}`,
+      variationId: `var-${String(index).padStart(3, "0")}-${"y".repeat(80)}`,
+    }));
+
+    const result = writeAssignmentSyncCookie(payload(assignments));
+    const cookieWrite = writes.find((write) => write.startsWith(`${ASSIGNMENT_SYNC_COOKIE_NAME}=`))!;
+    const encoded = cookieWrite.slice(cookieWrite.indexOf("=") + 1, cookieWrite.indexOf(";"));
+    const decoded = decodeWithPixelFormat(encoded);
+
+    expect(result.written).toBe(true);
+    expect(result.truncatedAssignmentCount).toBeGreaterThan(0);
+    expect(result.encodedBytes).toBeLessThanOrEqual(ASSIGNMENT_SYNC_COOKIE_MAX_BYTES);
+    expect(decoded.data.assignments).toEqual(assignments.slice(result.truncatedAssignmentCount));
+  });
+});
+
+describe("clearAssignmentSyncCookie", () => {
+  it("expires the cookie host-only and across every registrable-domain suffix", () => {
+    const writes: string[] = [];
+    const doc = {
+      get cookie() {
+        return "";
+      },
+      set cookie(value: string) {
+        writes.push(value);
+      },
+    };
+    const originalDocument = globalThis.document;
+    const originalLocation = globalThis.location;
+    Object.defineProperty(globalThis, "document", { value: doc, configurable: true });
+    Object.defineProperty(globalThis, "location", {
+      value: { hostname: "shop.example.co.uk" },
+      configurable: true,
+    });
+    try {
+      clearAssignmentSyncCookie();
+    } finally {
+      Object.defineProperty(globalThis, "document", { value: originalDocument, configurable: true });
+      Object.defineProperty(globalThis, "location", { value: originalLocation, configurable: true });
+    }
+    expect(
+      writes.some(
+        (w) => w.startsWith(`${ASSIGNMENT_SYNC_COOKIE_NAME}=; Max-Age=0`) && !w.includes("Domain="),
+      ),
+    ).toBe(true);
+    expect(writes.some((w) => w.includes("Domain=.example.co.uk"))).toBe(true);
+    expect(writes.some((w) => w.includes("Domain=.co.uk"))).toBe(true);
+    expect(writes.every((w) => w.includes("Max-Age=0"))).toBe(true);
+    // Expiries must not carry `Secure`: a Secure write is dropped on http
+    // origins, which would leave the cookie behind.
+    expect(writes.every((w) => !w.includes("Secure"))).toBe(true);
+  });
+
+  it("skips the domain sweep on localhost and IP hosts", () => {
+    for (const hostname of ["localhost", "127.0.0.1"]) {
+      const writes: string[] = [];
+      const doc = {
+        get cookie() {
+          return "";
+        },
+        set cookie(value: string) {
+          writes.push(value);
+        },
+      };
+      const originalDocument = globalThis.document;
+      const originalLocation = globalThis.location;
+      Object.defineProperty(globalThis, "document", { value: doc, configurable: true });
+      Object.defineProperty(globalThis, "location", { value: { hostname }, configurable: true });
+      try {
+        clearAssignmentSyncCookie();
+      } finally {
+        Object.defineProperty(globalThis, "document", { value: originalDocument, configurable: true });
+        Object.defineProperty(globalThis, "location", { value: originalLocation, configurable: true });
+      }
+      expect(writes).toHaveLength(1);
+      expect(writes[0]).not.toContain("Domain=");
+    }
+  });
+});

package/src/assignment-cookie-sync.ts

@@ -0,0 +1,189 @@
+export const ASSIGNMENT_SYNC_COOKIE_NAME = "drip_assignment_sync_v1";
+export const ASSIGNMENT_SYNC_COOKIE_MAX_AGE_SECONDS = 7_200;
+export const ASSIGNMENT_SYNC_COOKIE_MAX_BYTES = 3_800;
+
+export type AssignmentSyncPayload = {
+  visitorId: string | null;
+  sessionId: string;
+  cartToken?: string;
+  qaMode: boolean;
+  qaSessionId: string;
+  cohort?: "holdout" | "active";
+  holdoutConfigEpoch?: number;
+  assignments: Array<{
+    experimentId: string;
+    variationId: string;
+    assignmentEpoch?: number;
+  }>;
+};
+
+export type AssignmentSyncCookieWriteResult = {
+  written: boolean;
+  assignmentCount: number;
+  truncatedAssignmentCount: number;
+  encodedBytes: number;
+  domain?: string;
+  reason?: "document_unavailable" | "visitor_id_missing" | "cookie_too_large" | "cookie_write_failed";
+};
+
+type CookieDocument = Pick<Document, "cookie">;
+
+function encodeStoredAssignmentAt(data: AssignmentSyncPayload, storedAt: number): string {
+  return btoa(JSON.stringify({ storedAt, data }))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export function encodeStoredAssignment(data: AssignmentSyncPayload): string {
+  return encodeStoredAssignmentAt(data, Date.now());
+}
+
+function hasCookie(documentRef: CookieDocument, name: string, value: string): boolean {
+  return documentRef.cookie
+    .split(";")
+    .some((part) => part.trim() === `${name}=${value}`);
+}
+
+function isIpv4(hostname: string): boolean {
+  const parts = hostname.split(".");
+  return parts.length === 4 && parts.every((part) => {
+    if (!/^\d{1,3}$/.test(part)) return false;
+    const value = Number(part);
+    return value >= 0 && value <= 255;
+  });
+}
+
+function isIpHost(hostname: string): boolean {
+  const unbracketed = hostname.replace(/^\[|\]$/g, "");
+  return isIpv4(unbracketed) || unbracketed.includes(":");
+}
+
+function cookieAttributes(domain?: string): string {
+  return `Path=/; SameSite=Lax; Secure${domain ? `; Domain=.${domain}` : ""}`;
+}
+
+export function discoverRegistrableDomain(
+  hostname: string,
+  documentRef: CookieDocument,
+): string | undefined {
+  const normalized = hostname.trim().replace(/\.$/, "").toLowerCase();
+  if (!normalized || normalized === "localhost" || normalized.endsWith(".localhost") || isIpHost(normalized)) {
+    return undefined;
+  }
+
+  const labels = normalized.split(".").filter(Boolean);
+  if (labels.length < 2) return undefined;
+
+  const probeName = "__drip_assignment_domain_probe";
+  const probeValue = Date.now().toString(36);
+  for (let start = labels.length - 2; start >= 0; start -= 1) {
+    const candidate = labels.slice(start).join(".");
+    const attributes = cookieAttributes(candidate);
+    try {
+      documentRef.cookie = `${probeName}=${probeValue}; Max-Age=5; ${attributes}`;
+      const accepted = hasCookie(documentRef, probeName, probeValue);
+      documentRef.cookie = `${probeName}=; Max-Age=0; ${attributes}`;
+      if (accepted) return candidate;
+    } catch {
+      // Try the next longer suffix when this candidate is not writable.
+    }
+  }
+  return undefined;
+}
+
+export function writeAssignmentSyncCookie(
+  payload: AssignmentSyncPayload,
+): AssignmentSyncCookieWriteResult {
+  const originalAssignmentCount = payload.assignments.length;
+  if (typeof document === "undefined" || typeof location === "undefined") {
+    return {
+      written: false,
+      assignmentCount: originalAssignmentCount,
+      truncatedAssignmentCount: 0,
+      encodedBytes: 0,
+      reason: "document_unavailable",
+    };
+  }
+  if (!payload.visitorId) {
+    return {
+      written: false,
+      assignmentCount: originalAssignmentCount,
+      truncatedAssignmentCount: 0,
+      encodedBytes: 0,
+      reason: "visitor_id_missing",
+    };
+  }
+
+  try {
+    const storedAt = Date.now();
+    let assignments = payload.assignments.slice();
+    let encoded = encodeStoredAssignmentAt({ ...payload, assignments }, storedAt);
+    while (encoded.length > ASSIGNMENT_SYNC_COOKIE_MAX_BYTES && assignments.length > 0) {
+      assignments = assignments.slice(1);
+      encoded = encodeStoredAssignmentAt({ ...payload, assignments }, storedAt);
+    }
+
+    const truncatedAssignmentCount = originalAssignmentCount - assignments.length;
+    if (encoded.length > ASSIGNMENT_SYNC_COOKIE_MAX_BYTES) {
+      return {
+        written: false,
+        assignmentCount: assignments.length,
+        truncatedAssignmentCount,
+        encodedBytes: encoded.length,
+        reason: "cookie_too_large",
+      };
+    }
+
+    const domain = discoverRegistrableDomain(location.hostname, document);
+    document.cookie = `${ASSIGNMENT_SYNC_COOKIE_NAME}=${encoded}; Max-Age=${ASSIGNMENT_SYNC_COOKIE_MAX_AGE_SECONDS}; ${cookieAttributes(domain)}`;
+    if (!hasCookie(document, ASSIGNMENT_SYNC_COOKIE_NAME, encoded)) {
+      return {
+        written: false,
+        assignmentCount: assignments.length,
+        truncatedAssignmentCount,
+        encodedBytes: encoded.length,
+        reason: "cookie_write_failed",
+      };
+    }
+    return {
+      written: true,
+      assignmentCount: assignments.length,
+      truncatedAssignmentCount,
+      encodedBytes: encoded.length,
+      ...(domain ? { domain } : {}),
+    };
+  } catch {
+    return {
+      written: false,
+      assignmentCount: originalAssignmentCount,
+      truncatedAssignmentCount: 0,
+      encodedBytes: 0,
+      reason: "cookie_write_failed",
+    };
+  }
+}
+
+export function clearAssignmentSyncCookie(): void {
+  if (typeof document === "undefined" || typeof location === "undefined") return;
+  try {
+    // No `Secure` on the expiry: deletion matches name+domain+path only, and a
+    // Secure-attributed write would be dropped on http origins, leaving the
+    // cookie behind exactly where the purge matters.
+    const expire = `${ASSIGNMENT_SYNC_COOKIE_NAME}=; Max-Age=0; Path=/; SameSite=Lax`;
+    // Host-only first, then every candidate registrable-domain suffix. Deleting
+    // with a Domain the cookie was never set on is a no-op, so sweeping all
+    // suffixes removes the cookie without re-probing which one was used.
+    document.cookie = expire;
+    const normalized = location.hostname.trim().replace(/\.$/, "").toLowerCase();
+    if (!normalized || normalized === "localhost" || normalized.endsWith(".localhost") || isIpHost(normalized)) {
+      return; // Host-only expiry is sufficient; the write path never sets Domain here.
+    }
+    const labels = normalized.split(".").filter(Boolean);
+    for (let start = labels.length - 2; start >= 0; start -= 1) {
+      document.cookie = `${expire}; Domain=.${labels.slice(start).join(".")}`;
+    }
+  } catch {
+    // Best effort: consent purge must never throw.
+  }
+}