@drip-apex/sdk 0.1.0

package/src/handover.ts

@@ -0,0 +1,309 @@
+import type { Assignment, ExternalTrackingSettings } from "./types";
+
+export type HandoverData = {
+  visitorId?: string;
+  forceMap?: Record<string, string>;
+};
+
+const DEFAULT_HANDOVER_TTL_SECONDS = 120;
+const DEFAULT_HANDOVER_MINT_TIMEOUT_MS = 250;
+
+function paramName(settings?: ExternalTrackingSettings): string {
+  return settings?.handoverQueryParam || "drip_bucket";
+}
+
+function ttlSeconds(settings?: ExternalTrackingSettings): number {
+  const ttl = Number(settings?.handoverTtlSeconds ?? DEFAULT_HANDOVER_TTL_SECONDS);
+  return Number.isFinite(ttl) ? Math.max(30, Math.min(600, Math.floor(ttl))) : DEFAULT_HANDOVER_TTL_SECONDS;
+}
+
+export function handoverMintTimeoutMs(settings?: ExternalTrackingSettings): number {
+  const timeout = Number(settings?.handoverMintTimeoutMs ?? DEFAULT_HANDOVER_MINT_TIMEOUT_MS);
+  return Number.isFinite(timeout) ? Math.max(50, Math.min(2000, Math.floor(timeout))) : DEFAULT_HANDOVER_MINT_TIMEOUT_MS;
+}
+
+function enabledDomains(settings?: ExternalTrackingSettings): string[] {
+  return (settings?.domains ?? [])
+    .map((domain) => domain.trim().replace(/^https?:\/\//i, "").replace(/\/.*$/, "").toLowerCase())
+    .filter(Boolean);
+}
+
+function encodePayload(value: unknown): string {
+  const json = JSON.stringify(value);
+  return btoa(json).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+type VerifiedHandoverPayload = Record<string, unknown>;
+
+function decodeVerifiedPayload(parsed: VerifiedHandoverPayload, shopId: string): HandoverData | null {
+  try {
+    const exp = typeof parsed.exp === "number" ? parsed.exp : 0;
+    if (!exp || Math.floor(Date.now() / 1000) > exp || parsed.shop !== shopId) 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
+        : [];
+    if (Array.isArray(assignments)) {
+      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;
+        }
+      }
+    }
+    return { visitorId: visitorIdV2 ?? visitorId, forceMap };
+  } catch {
+    return null;
+  }
+}
+
+function readPayloadExp(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;
+  } catch {
+    return null;
+  }
+}
+
+function hostMatches(hostname: string, domains: string[]): boolean {
+  const normalized = hostname.toLowerCase();
+  return domains.some((domain) => normalized === domain || normalized.endsWith(`.${domain}`));
+}
+
+function appendHandover(url: URL, settings: ExternalTrackingSettings | undefined, payload: string): string {
+  url.searchParams.set(paramName(settings), payload);
+  return url.toString();
+}
+
+function closestLink(target: EventTarget | null): HTMLAnchorElement | null {
+  const candidate = target as
+    | {
+        closest?: (selector: string) => Element | null;
+        parentElement?: { closest?: (selector: string) => Element | null };
+      }
+    | null;
+  if (!candidate) return null;
+  const direct = typeof candidate.closest === "function"
+    ? candidate.closest("a[href]")
+    : null;
+  if (direct) return direct as HTMLAnchorElement;
+  const fromParent = typeof candidate.parentElement?.closest === "function"
+    ? candidate.parentElement.closest("a[href]")
+    : null;
+  return fromParent as HTMLAnchorElement | null;
+}
+
+function resumeLinkNavigation(link: HTMLAnchorElement): void {
+  const target = link.getAttribute("target");
+  if (
+    target
+    && target.toLowerCase() !== "_self"
+    && typeof globalThis.open === "function"
+  ) {
+    globalThis.open(link.href, target);
+    return;
+  }
+  // A synthetic click is the only general way to reproduce the download
+  // attribute, but it would re-dispatch merchant handlers. Direct navigation
+  // still honors server-provided Content-Disposition downloads.
+  globalThis.location?.assign(link.href);
+}
+
+function submissionAction(
+  form: HTMLFormElement,
+  submitter: HTMLElement | null,
+): string {
+  const submitterAction = submitter?.getAttribute("formaction");
+  if (submitterAction != null) {
+    return submitterAction || globalThis.location?.href || "";
+  }
+  return form.getAttribute("action") || globalThis.location?.href || "";
+}
+
+export async function readBucketingHandover(
+  settings: ExternalTrackingSettings | undefined,
+  shopId: string,
+  verifyToken: (token: string) => Promise<unknown>,
+): Promise<HandoverData | null> {
+  if (!globalThis.location || !enabledDomains(settings).length || !shopId) return null;
+  const value = new URL(globalThis.location.href).searchParams.get(paramName(settings));
+  if (!value) return null;
+  try {
+    const verified = await verifyToken(value);
+    return verified && typeof verified === "object"
+      ? decodeVerifiedPayload(verified as VerifiedHandoverPayload, shopId)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function hasBucketingHandover(settings?: ExternalTrackingSettings): boolean {
+  if (!globalThis.location || !enabledDomains(settings).length) return false;
+  return Boolean(new URL(globalThis.location.href).searchParams.get(paramName(settings)));
+}
+
+export function createBucketingHandoverPayload(
+  visitorId: string,
+  assignments: Assignment[],
+  settings?: ExternalTrackingSettings,
+): string {
+  const iat = Math.floor(Date.now() / 1000);
+  return encodePayload({
+    v: 2,
+    iat,
+    exp: iat + ttlSeconds(settings),
+    vid: visitorId,
+    asg: assignments.map((assignment) => ({
+      e: assignment.experimentId,
+      x: assignment.variationId,
+    })),
+  });
+}
+
+export function installBucketingHandover(
+  settings: ExternalTrackingSettings | undefined,
+  getPayload: () => string | null,
+  mintPayload?: () => Promise<string | null>,
+): () => void {
+  const domains = enabledDomains(settings);
+  if (!domains.length || !globalThis.document) return () => {};
+  let cachedSignedPayload: string | null = null;
+  let cachedBasePayload: 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;
+    if (!mintInFlight) {
+      mintInFlight = mintPayload()
+        .then((payload) => {
+          cachedSignedPayload = payload;
+          cachedBasePayload = payload ? basePayload : null;
+          cachedSignedPayloadExp = payload ? readPayloadExp(payload) ?? 0 : 0;
+          return payload;
+        })
+        .catch(() => null)
+        .finally(() => {
+          mintInFlight = null;
+        });
+    }
+    return mintInFlight;
+  };
+
+  const bestPayload = (): string | null => {
+    const basePayload = getPayload();
+    const now = Math.floor(Date.now() / 1000);
+    if (
+      cachedSignedPayload
+      && cachedBasePayload === basePayload
+      && cachedSignedPayloadExp > now
+    ) {
+      return cachedSignedPayload;
+    }
+    // A raw payload is only minting input. Destinations reject it by design,
+    // so never put it on a navigation when signing is unavailable or pending.
+    return null;
+  };
+
+  const rewriteUrl = (rawUrl: string | null | undefined): string | null => {
+    if (!rawUrl) return null;
+    try {
+      const url = new URL(rawUrl, globalThis.location?.href);
+      if (!hostMatches(url.hostname, domains)) return null;
+      const payload = bestPayload();
+      if (!payload) return null;
+      return appendHandover(url, settings, payload);
+    } catch {
+      return null;
+    }
+  };
+
+  const isHandoverTarget = (rawUrl: string | null | undefined): boolean => {
+    if (!rawUrl) return false;
+    try {
+      return hostMatches(new URL(rawUrl, globalThis.location?.href).hostname, domains);
+    } catch {
+      return false;
+    }
+  };
+
+  const handleLinkEvent = (event: Event) => {
+    const link = closestLink(event.target);
+    if (!link) return;
+    if (!isHandoverTarget(link.getAttribute("href"))) return;
+    const pending = mint();
+    const rewrite = () => {
+      const next = rewriteUrl(link.getAttribute("href"));
+      if (next) link.href = next;
+    };
+    if (event.type === "click" && pending && !bestPayload()) {
+      event.preventDefault();
+      void pending.then(() => {
+        rewrite();
+        resumeLinkNavigation(link);
+      });
+      return;
+    }
+    void pending?.then(rewrite);
+    rewrite();
+  };
+
+  const resubmitting = new WeakSet<HTMLFormElement>();
+  const handleSubmit = (event: Event) => {
+    const form = event.target as HTMLFormElement | null;
+    if (!form || form.tagName !== "FORM") return;
+    if (resubmitting.delete(form)) return;
+    const submitter = (event as SubmitEvent).submitter ?? null;
+    const rawAction = submissionAction(form, submitter);
+    if (!isHandoverTarget(rawAction)) return;
+    const pending = mint();
+    if (!pending) return;
+    event.preventDefault();
+    void pending.then(() => {
+      const payload = bestPayload();
+      const action = rewriteUrl(rawAction);
+      if (payload && action) {
+        if (submitter?.hasAttribute("formaction")) {
+          submitter.setAttribute("formaction", action);
+        } else {
+          form.action = action;
+        }
+        const name = paramName(settings);
+        let input = form.querySelector(`input[name="${name}"]`) as HTMLInputElement | null;
+        if (!input) {
+          input = document.createElement("input");
+          input.type = "hidden";
+          input.name = name;
+          form.appendChild(input);
+        }
+        input.value = payload;
+      }
+      resubmitting.add(form);
+      if (submitter) {
+        form.requestSubmit(submitter);
+      } else {
+        form.requestSubmit();
+      }
+    });
+  };
+
+  document.addEventListener("click", handleLinkEvent, true);
+  document.addEventListener("submit", handleSubmit, true);
+  return () => {
+    document.removeEventListener("click", handleLinkEvent, true);
+    document.removeEventListener("submit", handleSubmit, true);
+  };
+}

package/src/hash.ts

@@ -0,0 +1,214 @@
+const UID_KEY = "drip_uid";
+
+type StorageMode = "localStorage" | "sessionStorage" | "cookie" | "memory";
+
+let storageMode: StorageMode = "localStorage";
+let encodeStorageValues = false;
+let cookieDomain = "";
+let memoryUserId: string | null = null;
+
+export function murmurhash3_32_gc(key: string, seed = 0): number {
+  let remainder = key.length & 3;
+  let bytes = key.length - remainder;
+  let h1 = seed;
+  let c1 = 0xcc9e2d51;
+  let c2 = 0x1b873593;
+  let i = 0;
+
+  while (i < bytes) {
+    let k1 =
+      (key.charCodeAt(i) & 0xff) |
+      ((key.charCodeAt(++i) & 0xff) << 8) |
+      ((key.charCodeAt(++i) & 0xff) << 16) |
+      ((key.charCodeAt(++i) & 0xff) << 24);
+    ++i;
+
+    k1 = Math.imul(k1, c1);
+    k1 = (k1 << 15) | (k1 >>> 17);
+    k1 = Math.imul(k1, c2);
+
+    h1 ^= k1;
+    h1 = (h1 << 13) | (h1 >>> 19);
+    h1 = Math.imul(h1, 5) + 0xe6546b64;
+  }
+
+  let k1 = 0;
+  switch (remainder) {
+    case 3:
+      k1 ^= (key.charCodeAt(i + 2) & 0xff) << 16;
+    case 2:
+      k1 ^= (key.charCodeAt(i + 1) & 0xff) << 8;
+    case 1:
+      k1 ^= key.charCodeAt(i) & 0xff;
+      k1 = Math.imul(k1, c1);
+      k1 = (k1 << 15) | (k1 >>> 17);
+      k1 = Math.imul(k1, c2);
+      h1 ^= k1;
+  }
+
+  h1 ^= key.length;
+  h1 ^= h1 >>> 16;
+  h1 = Math.imul(h1, 0x85ebca6b);
+  h1 ^= h1 >>> 13;
+  h1 = Math.imul(h1, 0xc2b2ae35);
+  h1 ^= h1 >>> 16;
+
+  return h1 >>> 0;
+}
+
+export function hashToFloat(seed: string, value: string): number {
+  const hash = murmurhash3_32_gc(seed + value, 1);
+  return (hash % 10000) / 10000;
+}
+
+export function variationHashToFloat(experimentId: string, value: string): number {
+  return hashToFloat(`${experimentId}:variation`, value);
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+
+function generateId(): string {
+  if (globalThis.crypto && globalThis.crypto.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    return bytesToHex(bytes);
+  }
+  return Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+
+export function configureIdentityStorage(settings?: {
+  storageMode?: StorageMode;
+  encodeStorageValues?: boolean;
+  cookieDomain?: string;
+}): void {
+  storageMode = settings?.storageMode ?? "localStorage";
+  encodeStorageValues = settings?.encodeStorageValues === true;
+  cookieDomain = normalizeCookieDomain(settings?.cookieDomain);
+}
+
+function normalizeCookieDomain(value: string | undefined): string {
+  const normalized = (value ?? "")
+    .trim()
+    .replace(/^https?:\/\//i, "")
+    .replace(/\/.*$/, "")
+    .replace(/[?#].*$/, "")
+    .replace(/:\d+$/, "")
+    .toLowerCase();
+  if (!normalized || normalized === "localhost" || normalized.includes(":")) return "";
+  const candidate = normalized.replace(/^\.+/, ".");
+  const labels = candidate.replace(/^\./, "").split(".");
+  return labels.length > 1
+    && labels.every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))
+    ? candidate
+    : "";
+}
+
+function encodeStoredValue(value: string): string {
+  if (!encodeStorageValues) return value;
+  try {
+    return "b64:" + btoa(value).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  } catch {
+    return value;
+  }
+}
+
+function decodeStoredValue(value: string | null): string | null {
+  if (!value) return null;
+  if (!value.startsWith("b64:")) return value;
+  try {
+    const raw = value.slice(4).replace(/-/g, "+").replace(/_/g, "/");
+    const padded = raw + "=".repeat((4 - (raw.length % 4)) % 4);
+    return atob(padded);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lifetime (cross-session) storage permitted by the configured identity
+ * storage mode. Only localStorage mode has one; sessionStorage/memory/cookie
+ * modes return null so lifetime counters stay unpersisted under them.
+ */
+export function lifetimeIdentityStorage(): Storage | null {
+  if (storageMode !== "localStorage") return null;
+  try {
+    return globalThis.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function browserStorage(): Storage | null {
+  try {
+    if (storageMode === "sessionStorage") return globalThis.sessionStorage ?? null;
+    if (storageMode === "localStorage") return globalThis.localStorage ?? null;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function readStorage(): string | null {
+  if (storageMode === "memory") return memoryUserId;
+  if (storageMode === "cookie") return null;
+  try {
+    return decodeStoredValue(browserStorage()?.getItem(UID_KEY) || null);
+  } catch {
+    return null;
+  }
+}
+
+function writeStorage(value: string): void {
+  if (storageMode === "memory") {
+    memoryUserId = value;
+    return;
+  }
+  if (storageMode === "cookie") return;
+  try {
+    browserStorage()?.setItem(UID_KEY, encodeStoredValue(value));
+  } catch {
+    // ignore
+  }
+}
+
+function readCookie(): string | null {
+  if (!globalThis.document?.cookie) return null;
+  const match = globalThis.document.cookie.match(
+    new RegExp("(^| )" + UID_KEY + "=([^;]+)"),
+  );
+  return match ? decodeStoredValue(decodeURIComponent(match[2])) : null;
+}
+
+function writeCookie(value: string): void {
+  if (!globalThis.document) return;
+  const expires = new Date(Date.now() + 365 * 864e5).toUTCString();
+  const domain = cookieDomain ? "; domain=" + cookieDomain : "";
+  globalThis.document.cookie =
+    UID_KEY + "=" + encodeURIComponent(encodeStoredValue(value)) + "; expires=" + expires + "; path=/" + domain;
+}
+
+export function getUserId(provided?: string): string {
+  if (provided) return provided;
+  const existing = readStorage() || readCookie();
+  if (existing) return existing;
+  const created = generateId();
+  writeStorage(created);
+  if (storageMode !== "memory") writeCookie(created);
+  return created;
+}
+
+export function getEphemeralUserId(provided?: string): string {
+  return provided || generateId();
+}
+
+export function adoptUserId(value: string): void {
+  if (!value) return;
+  writeStorage(value);
+  if (storageMode !== "memory") writeCookie(value);
+}