@runbandit/sdk 1.0.0 → 2.0.1

package/dist/index.js

@@ -1,4 +1,45 @@
+// src/session.ts
+var SESSION_ID_KEY = "bandits_session_id";
+var SESSION_CREATED_AT_KEY = "bandits_session_created_at";
+var DEFAULT_SESSION_TTL_MS = 864e5;
+function generateId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === "x" ? r : r & 3 | 8).toString(16);
+  });
+}
+function getOrCreateSessionId(options = {}) {
+  const { storage, now = () => Date.now(), ttlMs = DEFAULT_SESSION_TTL_MS } = options;
+  if (!storage) return generateId();
+  try {
+    const stored = storage.getItem(SESSION_ID_KEY);
+    const storedAt = storage.getItem(SESSION_CREATED_AT_KEY);
+    if (stored && storedAt) {
+      const age = now() - parseInt(storedAt, 10);
+      if (age < ttlMs) return stored;
+    }
+    const id = generateId();
+    storage.setItem(SESSION_ID_KEY, id);
+    storage.setItem(SESSION_CREATED_AT_KEY, String(now()));
+    return id;
+  } catch {
+    return generateId();
+  }
+}
+function defaultSessionStorage() {
+  return typeof window !== "undefined" && window.localStorage ? window.localStorage : null;
+}
+
 // src/client.ts
+function currentPageUrl() {
+  if (typeof location !== "undefined" && location.origin && location.pathname) {
+    return location.origin + location.pathname;
+  }
+  return void 0;
+}
 var BanditsClient = class {
   config;
   namedEventQueue = [];
@@ -23,6 +64,8 @@ var BanditsClient = class {
       context,
       sessionId: this.sessionId
     };
+    const pageUrl = currentPageUrl();
+    if (pageUrl) request.pageUrl = pageUrl;
     const response = await this.makeRequest(
       "/assignments",
       "POST",
@@ -57,7 +100,7 @@ var BanditsClient = class {
       sessionId: this.sessionId
     };
     if (opts?.immediate) {
-      const url = `${this.config.apiUrl}/events`;
+      const url = `${this.normalizeApiUrl()}/events`;
       try {
         void fetch(url, {
           method: "POST",
@@ -82,7 +125,7 @@ var BanditsClient = class {
     this.namedEventQueue = [];
     if (namedEvents.length === 0) return;
     try {
-      await fetch(`${this.config.apiUrl}/events/batch`, {
+      await fetch(`${this.normalizeApiUrl()}/events/batch`, {
         method: "POST",
         headers: {
           "Authorization": `Bearer ${this.config.apiKey}`,
@@ -144,34 +187,59 @@ var BanditsClient = class {
       throw new Error(response.error || "Failed to record funnel reward");
     }
   }
-  generateId() {
-    if (typeof crypto !== "undefined" && crypto.randomUUID) {
-      return crypto.randomUUID();
+  async getBundle(bundleId, userId, context) {
+    const request = {
+      bundleId,
+      userId,
+      context,
+      sessionId: this.sessionId
+    };
+    const pageUrl = currentPageUrl();
+    if (pageUrl) request.pageUrl = pageUrl;
+    const response = await this.makeRequest("/bundles/assignment", "POST", request);
+    if (!response.success || !response.data) {
+      throw new Error(response.error || "Failed to get bundle assignment");
+    }
+    const payload = response.data?.data ?? response.data;
+    if (!payload?.bundleAssignmentId || !payload?.slots) {
+      throw new Error("Invalid bundle assignment response");
     }
-    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-      const r = Math.random() * 16 | 0;
-      return (c === "x" ? r : r & 3 | 8).toString(16);
+    return {
+      bundleAssignmentId: payload.bundleAssignmentId,
+      slots: payload.slots
+    };
+  }
+  async trackBundleReward(bundleId, userId, value) {
+    const response = await this.makeRequest(`/bundles/${bundleId}/reward`, "POST", {
+      userId,
+      value
     });
+    if (!response.success) {
+      throw new Error(response.error || "Failed to record bundle reward");
+    }
   }
-  getOrCreateSessionId() {
-    if (typeof window !== "undefined" && window.localStorage) {
-      const stored = localStorage.getItem("bandits_session_id");
-      const storedAt = localStorage.getItem("bandits_session_created_at");
-      if (stored && storedAt) {
-        const age = Date.now() - parseInt(storedAt, 10);
-        if (age < this.config.sessionTtl) {
-          return stored;
-        }
-      }
-      const id = this.generateId();
-      localStorage.setItem("bandits_session_id", id);
-      localStorage.setItem("bandits_session_created_at", String(Date.now()));
-      return id;
+  generateId() {
+    return generateId();
+  }
+  /**
+   * Normalize the apiUrl by adding /api prefix if not present.
+   * Supports both 'https://runbandit.com' and 'https://runbandit.com/api'.
+   */
+  normalizeApiUrl() {
+    let baseUrl = this.config.apiUrl.replace(/\/$/, "");
+    if (!baseUrl.endsWith("/api")) {
+      baseUrl = `${baseUrl}/api`;
     }
-    return this.generateId();
+    return baseUrl;
+  }
+  getOrCreateSessionId() {
+    return getOrCreateSessionId({
+      storage: defaultSessionStorage(),
+      ttlMs: this.config.sessionTtl
+    });
   }
   async makeRequest(endpoint, method, body, extraHeaders) {
-    const url = `${this.config.apiUrl}${endpoint}`;
+    const url = `${this.normalizeApiUrl()}${endpoint}`;
     const headers = {
       "Authorization": `Bearer ${this.config.apiKey}`,
       "Content-Type": "application/json",
@@ -220,6 +288,13 @@ var BanditsClient = class {
 };
 
 // ../shared/dist/types.js
+var PLACEMENTS = [
+  "hero_headline",
+  "hero_subhead",
+  "cta_primary",
+  "banner_text",
+  "badge_text"
+];
 var ExperimentStatus;
 (function(ExperimentStatus2) {
   ExperimentStatus2["DRAFT"] = "draft";
@@ -230,12 +305,54 @@ var ExperimentStatus;
 })(ExperimentStatus || (ExperimentStatus = {}));
 var BanditAlgorithm;
 (function(BanditAlgorithm2) {
-  BanditAlgorithm2["EPSILON_GREEDY"] = "epsilon_greedy";
-  BanditAlgorithm2["UCB1"] = "ucb1";
   BanditAlgorithm2["THOMPSON_SAMPLING"] = "thompson_sampling";
   BanditAlgorithm2["CONTEXTUAL_LINEAR"] = "contextual_linear";
-  BanditAlgorithm2["CONTEXTUAL_NEURAL"] = "contextual_neural";
 })(BanditAlgorithm || (BanditAlgorithm = {}));
+var Posterior;
+(function(Posterior2) {
+  Posterior2["BETA"] = "beta";
+  Posterior2["NORMAL_GAMMA"] = "normal_gamma";
+})(Posterior || (Posterior = {}));
+function normalizePosterior(posterior) {
+  return posterior === Posterior.NORMAL_GAMMA ? Posterior.NORMAL_GAMMA : Posterior.BETA;
+}
+var ForgettingMode;
+(function(ForgettingMode2) {
+  ForgettingMode2["NONE"] = "none";
+  ForgettingMode2["DISCOUNTED"] = "discounted";
+  ForgettingMode2["SLIDING_WINDOW"] = "sliding_window";
+})(ForgettingMode || (ForgettingMode = {}));
+var DEFAULT_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1e3;
+var DEFAULT_WINDOW_MS = 14 * 24 * 60 * 60 * 1e3;
+var STATIONARY = { mode: ForgettingMode.NONE };
+function resolveForgetting(config) {
+  switch (config?.mode) {
+    case ForgettingMode.DISCOUNTED:
+      return {
+        mode: ForgettingMode.DISCOUNTED,
+        halfLifeMs: config.halfLifeMs && config.halfLifeMs > 0 ? config.halfLifeMs : DEFAULT_HALF_LIFE_MS
+      };
+    case ForgettingMode.SLIDING_WINDOW:
+      return {
+        mode: ForgettingMode.SLIDING_WINDOW,
+        windowMs: config.windowMs && config.windowMs > 0 ? config.windowMs : DEFAULT_WINDOW_MS
+      };
+    default:
+      return STATIONARY;
+  }
+}
+var LEGACY_ALGORITHM_ALIASES = {
+  epsilon_greedy: BanditAlgorithm.THOMPSON_SAMPLING,
+  ucb1: BanditAlgorithm.THOMPSON_SAMPLING,
+  contextual_neural: BanditAlgorithm.CONTEXTUAL_LINEAR
+};
+function normalizeAlgorithm(algorithm) {
+  if (algorithm === BanditAlgorithm.THOMPSON_SAMPLING)
+    return BanditAlgorithm.THOMPSON_SAMPLING;
+  if (algorithm === BanditAlgorithm.CONTEXTUAL_LINEAR)
+    return BanditAlgorithm.CONTEXTUAL_LINEAR;
+  return LEGACY_ALGORITHM_ALIASES[algorithm ?? ""] ?? BanditAlgorithm.THOMPSON_SAMPLING;
+}
 var ContentType;
 (function(ContentType2) {
   ContentType2["PLAIN_TEXT"] = "plain_text";
@@ -275,7 +392,7 @@ var FunnelStatus;
 })(FunnelStatus || (FunnelStatus = {}));
 
 // ../shared/dist/utils.js
-function generateId() {
+function generateId2() {
   return Math.random().toString(36).substring(2) + Date.now().toString(36);
 }
 function validateTreatmentWeights(treatments) {
@@ -368,23 +485,720 @@ function buildSubdomainUrl(subdomain, baseDomain, path = "", protocol = "https")
   const url = `${protocol}://${subdomain}.${baseDomain}`;
   return path ? `${url}${path.startsWith("/") ? path : "/" + path}` : url;
 }
+
+// ../shared/dist/email-token.js
+var EMAIL_TOKEN_PARAM = "bt";
+var encoder = new TextEncoder();
+function base64UrlEncode(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(value) {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded + "=".repeat((4 - padded.length % 4) % 4));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++)
+    bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+async function hmac(secret, message) {
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(message)));
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++)
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+async function hashRecipient(recipientId, companySecret) {
+  const digest = await hmac(companySecret, `recipient:${recipientId}`);
+  return base64UrlEncode(digest.slice(0, 16));
+}
+async function mintEmailToken(payload, key) {
+  const body = base64UrlEncode(encoder.encode(JSON.stringify({
+    c: payload.c,
+    r: payload.r,
+    k: payload.k,
+    l: payload.l,
+    v: key.version
+  })));
+  const signature = base64UrlEncode(await hmac(key.secret, body));
+  return `${body}.${signature}`;
+}
+async function verifyEmailToken(token, keys) {
+  const parts = token.split(".");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    return { valid: false, reason: "malformed" };
+  }
+  const [body, signature] = parts;
+  let payload;
+  try {
+    payload = JSON.parse(new TextDecoder().decode(base64UrlDecode(body)));
+  } catch {
+    return { valid: false, reason: "malformed" };
+  }
+  if (!payload || typeof payload.c !== "string" || typeof payload.r !== "string" || !Array.isArray(payload.k) || !payload.k.every((arm) => Number.isInteger(arm) && arm >= 0) || !Number.isInteger(payload.l) || payload.l < 0 || !Number.isInteger(payload.v)) {
+    return { valid: false, reason: "malformed" };
+  }
+  const key = keys.find((candidate) => candidate.version === payload.v);
+  if (!key)
+    return { valid: false, reason: "unknown_key" };
+  const expected = base64UrlEncode(await hmac(key.secret, body));
+  if (!timingSafeEqual(expected, signature)) {
+    return { valid: false, reason: "bad_signature" };
+  }
+  return { valid: true, payload };
+}
+function appendEmailToken(url, token) {
+  const hashIndex = url.indexOf("#");
+  const fragment = hashIndex === -1 ? "" : url.slice(hashIndex);
+  const base = hashIndex === -1 ? url : url.slice(0, hashIndex);
+  const separator = base.includes("?") ? "&" : "?";
+  return `${base}${separator}${EMAIL_TOKEN_PARAM}=${encodeURIComponent(token)}${fragment}`;
+}
+
+// ../shared/dist/email-plan.js
+async function uniformFor(salt, recipientId, slotIndex) {
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(salt), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${recipientId}:${slotIndex}`)));
+  let value = 0;
+  for (let i = 0; i < 6; i++)
+    value = value * 256 + mac[i];
+  return value / 2 ** 48;
+}
+function pickArm(probabilities, uniform) {
+  if (probabilities.length === 0)
+    return -1;
+  const total = probabilities.reduce((sum, p) => sum + Math.max(p, 0), 0);
+  if (total <= 0) {
+    return Math.min(probabilities.length - 1, Math.floor(uniform * probabilities.length));
+  }
+  const target = uniform * total;
+  let cumulative = 0;
+  for (let i = 0; i < probabilities.length; i++) {
+    cumulative += Math.max(probabilities[i], 0);
+    if (target < cumulative)
+      return i;
+  }
+  return probabilities.length - 1;
+}
+async function sampleCombination(plan, recipientId) {
+  const combination = [];
+  for (let i = 0; i < plan.slots.length; i++) {
+    const slot = plan.slots[i];
+    const uniform = await uniformFor(plan.salt, recipientId, i);
+    const chosen = pickArm(slot.probabilities, uniform);
+    combination.push(chosen === -1 ? 0 : slot.arms[chosen]?.armIndex ?? 0);
+  }
+  return combination;
+}
+async function impressionManifest(plan, recipientIds) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const recipientId of recipientIds) {
+    for (let i = 0; i < plan.slots.length; i++) {
+      const slot = plan.slots[i];
+      const uniform = await uniformFor(plan.salt, recipientId, i);
+      const chosen = pickArm(slot.probabilities, uniform);
+      const arm = slot.arms[chosen === -1 ? 0 : chosen];
+      if (!arm)
+        continue;
+      const key = `${slot.experimentId}:${arm.treatmentId}`;
+      const entry = counts.get(key);
+      if (entry)
+        entry.count++;
+      else
+        counts.set(key, {
+          experimentId: slot.experimentId,
+          treatmentId: arm.treatmentId,
+          count: 1
+        });
+    }
+  }
+  return Array.from(counts.values());
+}
+
+// ../shared/dist/email-blocks.js
+function isSlotBinding(value) {
+  return typeof value === "object" && value !== null && typeof value.$slot === "string";
+}
+var CONTENT_WIDTH = 600;
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function resolve(value, slots, missing) {
+  if (value === void 0)
+    return "";
+  if (!isSlotBinding(value))
+    return value;
+  const resolved = slots[value.$slot];
+  if (resolved === void 0) {
+    missing.push(value.$slot);
+    return "";
+  }
+  return resolved;
+}
+function extractDocumentSlots(document) {
+  const names = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (value) => {
+    if (isSlotBinding(value)) {
+      if (!seen.has(value.$slot)) {
+        seen.add(value.$slot);
+        names.push(value.$slot);
+      }
+      return;
+    }
+    if (Array.isArray(value))
+      value.forEach(visit);
+    else if (typeof value === "object" && value !== null)
+      Object.values(value).forEach(visit);
+  };
+  visit(document.subject);
+  visit(document.preheader);
+  document.blocks.forEach(visit);
+  return names;
+}
+function renderBlock(block, slots, missing) {
+  const align = block.align ?? "left";
+  switch (block.type) {
+    case "heading": {
+      const size = block.level === 3 ? 18 : block.level === 2 ? 22 : 28;
+      const color = escapeHtml(resolve(block.color, slots, missing) || "#111111");
+      return `<tr><td style="padding:12px 24px;text-align:${align};font-family:Arial,Helvetica,sans-serif;font-size:${size}px;line-height:1.3;font-weight:bold;color:${color}">${escapeHtml(resolve(block.text, slots, missing))}</td></tr>`;
+    }
+    case "text": {
+      const color = escapeHtml(resolve(block.color, slots, missing) || "#333333");
+      return `<tr><td style="padding:8px 24px;text-align:${align};font-family:Arial,Helvetica,sans-serif;font-size:16px;line-height:1.5;color:${color}">${escapeHtml(resolve(block.text, slots, missing))}</td></tr>`;
+    }
+    case "button": {
+      const href = escapeHtml(resolve(block.href, slots, missing));
+      const label = escapeHtml(resolve(block.text, slots, missing));
+      const bg = escapeHtml(resolve(block.backgroundColor, slots, missing) || "#1a73e8");
+      const fg = escapeHtml(resolve(block.textColor, slots, missing) || "#ffffff");
+      return `<tr><td style="padding:16px 24px;text-align:${align}">
+<!--[if mso]><v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word" href="${href}" style="height:44px;v-text-anchor:middle;width:220px;" arcsize="12%" strokecolor="${bg}" fillcolor="${bg}"><w:anchorlock/><center style="color:${fg};font-family:Arial,sans-serif;font-size:16px;font-weight:bold;">${label}</center></v:roundrect><![endif]-->
+<!--[if !mso]><!--><a href="${href}" style="display:inline-block;padding:13px 28px;background-color:${bg};color:${fg};font-family:Arial,Helvetica,sans-serif;font-size:16px;font-weight:bold;text-decoration:none;border-radius:6px">${label}</a><!--<![endif]-->
+</td></tr>`;
+    }
+    case "image": {
+      const src = escapeHtml(resolve(block.src, slots, missing));
+      const alt = escapeHtml(resolve(block.alt, slots, missing));
+      const width = block.width ?? CONTENT_WIDTH;
+      const img = `<img src="${src}" alt="${alt}" width="${width}" style="display:block;border:0;outline:none;text-decoration:none;max-width:100%;height:auto" />`;
+      const href = block.href ? escapeHtml(resolve(block.href, slots, missing)) : "";
+      return `<tr><td style="padding:0;text-align:center">${href ? `<a href="${href}">${img}</a>` : img}</td></tr>`;
+    }
+    case "divider":
+      return `<tr><td style="padding:12px 24px"><table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0"><tr><td style="border-top:1px solid ${escapeHtml(block.color ?? "#e5e5e5")};font-size:0;line-height:0">&nbsp;</td></tr></table></td></tr>`;
+    case "spacer":
+      return `<tr><td style="height:${block.height ?? 24}px;font-size:0;line-height:0">&nbsp;</td></tr>`;
+    default:
+      return "";
+  }
+}
+function renderEmailDocument(document, slots) {
+  const missingSlots = [];
+  const width = document.contentWidth ?? CONTENT_WIDTH;
+  const background = escapeHtml(document.backgroundColor ?? "#f4f4f5");
+  const subject = resolve(document.subject, slots, missingSlots);
+  const preheader = resolve(document.preheader, slots, missingSlots);
+  const body = document.blocks.map((block) => renderBlock(block, slots, missingSlots)).join("\n");
+  const html = `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<meta name="x-apple-disable-message-reformatting" />
+<title>${escapeHtml(subject)}</title>
+<!--[if mso]><xml><o:OfficeDocumentSettings><o:PixelsPerInch>96</o:PixelsPerInch></o:OfficeDocumentSettings></xml><![endif]-->
+</head>
+<body style="margin:0;padding:0;background-color:${background}">
+<div style="display:none;font-size:0;line-height:0;max-height:0;overflow:hidden;mso-hide:all">${escapeHtml(preheader)}</div>
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background-color:${background}">
+<tr><td align="center" style="padding:24px 12px">
+<table role="presentation" width="${width}" cellpadding="0" cellspacing="0" border="0" style="width:${width}px;max-width:100%;background-color:#ffffff;border-radius:8px">
+${body}
+</table>
+</td></tr>
+</table>
+</body>
+</html>`;
+  return { subject, html, missingSlots };
+}
+
+// src/snapshot-cache.ts
+var STORAGE_KEY = "bandits_snapshot";
+var REPORT_QUEUE_KEY = "bandits_pending_reports";
+var DECISIONS_KEY = "bandits_client_assignments";
+function pickTreatment(treatments, draw) {
+  if (treatments.length === 0) return null;
+  let cumulative = 0;
+  for (const treatment of treatments) {
+    cumulative += treatment.pct;
+    if (draw < cumulative) return treatment;
+  }
+  return treatments[treatments.length - 1];
+}
+var DEFAULT_ASSIGNMENT_TTL_SECONDS = 86400;
+function randomId() {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let id = "";
+  for (let i = 0; i < 24; i++) {
+    id += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return id;
+}
+var SnapshotClient = class {
+  config;
+  storage;
+  now;
+  fetchImpl;
+  snapshot = null;
+  queue = [];
+  sessionId;
+  inFlight = null;
+  constructor(config) {
+    this.config = config;
+    this.now = config.now ?? (() => Date.now());
+    this.fetchImpl = config.fetchImpl ?? ((...args) => fetch(...args));
+    this.storage = config.storage ?? (typeof window !== "undefined" && window.localStorage ? window.localStorage : null);
+    this.queue = this.readQueue();
+    this.sessionId = getOrCreateSessionId({
+      storage: this.storage ?? defaultSessionStorage(),
+      now: this.now,
+      ttlMs: config.sessionTtl
+    });
+    if (config.inlineSnapshot) {
+      this.snapshot = config.inlineSnapshot;
+      this.persistSnapshot(config.inlineSnapshot);
+    } else {
+      this.snapshot = this.readSnapshot();
+    }
+  }
+  /**
+   * Decide an arm with no network call, or return null.
+   *
+   * Null means "this caller must fall back" - a cold cache, an expired one, an
+   * unknown experiment, or one whose state cannot be served from a static
+   * document. Returning null rather than the control is deliberate: the caller
+   * renders control itself, and no impression is reported for it. Reporting a
+   * forced-control impression would inflate the control arm's trials with
+   * decisions the bandit never made.
+   */
+  getAssignmentSync(experimentId, userId) {
+    const snapshot = this.freshSnapshot();
+    if (!snapshot) return null;
+    const experiment = snapshot.experiments[experimentId];
+    if (!experiment || experiment.mode !== "snapshot") return null;
+    const key = `${experimentId}:${userId}`;
+    const decisions = this.readDecisions();
+    const stored = decisions[key];
+    if (stored && stored.expiresAt > this.now()) {
+      const held = experiment.treatments.find((t) => t.id === stored.treatmentId);
+      if (held) {
+        return {
+          clientAssignmentId: stored.clientAssignmentId,
+          experimentId,
+          treatmentId: held.id,
+          config: held.config
+        };
+      }
+    }
+    const treatment = pickTreatment(experiment.treatments, Math.random());
+    if (!treatment) return null;
+    const clientAssignmentId = randomId();
+    const ttlSeconds = experiment.assignmentTtl ?? DEFAULT_ASSIGNMENT_TTL_SECONDS;
+    decisions[key] = {
+      clientAssignmentId,
+      treatmentId: treatment.id,
+      // expiresAt is milliseconds here; assignmentTtl arrives in seconds.
+      expiresAt: this.now() + ttlSeconds * 1e3
+    };
+    this.writeDecisions(decisions);
+    this.queue.push({
+      clientAssignmentId,
+      experimentId,
+      treatmentId: treatment.id,
+      userId,
+      sessionId: this.sessionId
+    });
+    this.persistQueue();
+    return {
+      clientAssignmentId,
+      experimentId,
+      treatmentId: treatment.id,
+      config: treatment.config
+    };
+  }
+  /** Fetch a fresh snapshot and cache it. Safe to call on every pageview. */
+  async refresh() {
+    const response = await this.fetchImpl(`${this.config.apiUrl}/snapshot`, {
+      method: "GET",
+      headers: { "x-api-key": this.config.publishableKey }
+    });
+    if (!response.ok) return;
+    const snapshot = await response.json();
+    this.snapshot = snapshot;
+    this.persistSnapshot(snapshot);
+  }
+  /**
+   * Post queued impressions.
+   *
+   * The queue is only cleared on success. A failed flush leaves the reports in
+   * storage, so a pageview that happened offline is still counted when the
+   * next one succeeds - the trial really did occur, and dropping it would bias
+   * the arm's denominator downward.
+   */
+  async flush() {
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = this.doFlush().finally(() => {
+      this.inFlight = null;
+    });
+    return this.inFlight;
+  }
+  async doFlush() {
+    if (this.queue.length === 0) return;
+    const reports = this.queue.slice(0, 1e3);
+    try {
+      const response = await this.fetchImpl(`${this.config.apiUrl}/assignments/report`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-api-key": this.config.publishableKey
+        },
+        body: JSON.stringify({ reports }),
+        keepalive: true
+      });
+      if (!response.ok) return;
+    } catch {
+      return;
+    }
+    this.queue = this.queue.slice(reports.length);
+    this.persistQueue();
+  }
+  /** The session id these reports are attributed under. */
+  getSessionId() {
+    return this.sessionId;
+  }
+  pendingReportCount() {
+    return this.queue.length;
+  }
+  /** The cached snapshot, or null when absent or past its ttl. */
+  freshSnapshot() {
+    if (!this.snapshot) return null;
+    if (this.snapshot.ttl === 0) return null;
+    const ageMs = this.now() - this.snapshot.generatedAt;
+    if (ageMs > this.snapshot.ttl * 1e3) return null;
+    return this.snapshot;
+  }
+  readSnapshot() {
+    if (!this.storage) return null;
+    try {
+      const raw = this.storage.getItem(STORAGE_KEY);
+      return raw ? JSON.parse(raw) : null;
+    } catch {
+      return null;
+    }
+  }
+  persistSnapshot(snapshot) {
+    if (!this.storage) return;
+    try {
+      this.storage.setItem(STORAGE_KEY, JSON.stringify(snapshot));
+    } catch {
+    }
+  }
+  readQueue() {
+    if (!this.storage) return [];
+    try {
+      const raw = this.storage.getItem(REPORT_QUEUE_KEY);
+      return raw ? JSON.parse(raw) : [];
+    } catch {
+      return [];
+    }
+  }
+  /** Stored decisions, pruned of expired entries. */
+  readDecisions() {
+    if (!this.storage) return {};
+    try {
+      const raw = this.storage.getItem(DECISIONS_KEY);
+      if (!raw) return {};
+      const parsed = JSON.parse(raw);
+      const now = this.now();
+      const live = {};
+      for (const [k, d] of Object.entries(parsed)) {
+        if (d && d.expiresAt > now) live[k] = d;
+      }
+      return live;
+    } catch {
+      return {};
+    }
+  }
+  writeDecisions(decisions) {
+    if (!this.storage) return;
+    try {
+      this.storage.setItem(DECISIONS_KEY, JSON.stringify(decisions));
+    } catch {
+    }
+  }
+  persistQueue() {
+    if (!this.storage) return;
+    try {
+      this.storage.setItem(REPORT_QUEUE_KEY, JSON.stringify(this.queue));
+    } catch {
+    }
+  }
+};
+
+// src/email-links.ts
+var UNTRACKABLE_SCHEME = /^(mailto:|tel:|sms:|javascript:|data:|#)/i;
+var NOTRACK_ATTRIBUTE = "data-bandit-notrack";
+function isTrackable(url) {
+  const trimmed = url.trim();
+  if (!trimmed || UNTRACKABLE_SCHEME.test(trimmed)) return false;
+  return /^https?:\/\//i.test(trimmed);
+}
+function appendToken(url, token) {
+  const hashIndex = url.indexOf("#");
+  const fragment = hashIndex === -1 ? "" : url.slice(hashIndex);
+  const base = hashIndex === -1 ? url : url.slice(0, hashIndex);
+  const separator = base.includes("?") ? base.includes("&amp;") ? "&amp;" : "&" : "?";
+  return `${base}${separator}${EMAIL_TOKEN_PARAM}=${token}${fragment}`;
+}
+function scanAnchors(html) {
+  const anchors = [];
+  let i = 0;
+  while (i < html.length) {
+    const lt = html.indexOf("<", i);
+    if (lt === -1) break;
+    if (html.startsWith("<!--", lt)) {
+      if (html.startsWith("<!--[if", lt) || html.startsWith("<!--<![endif]", lt)) {
+        const close = html.indexOf(">", lt);
+        i = close === -1 ? html.length : close + 1;
+        continue;
+      }
+      const end = html.indexOf("-->", lt);
+      i = end === -1 ? html.length : end + 3;
+      continue;
+    }
+    const rawText = /^<(script|style)\b/i.exec(html.slice(lt, lt + 8));
+    if (rawText) {
+      const closing = new RegExp(`</${rawText[1]}\\s*>`, "i");
+      const rest = html.slice(lt);
+      const match = closing.exec(rest);
+      i = match ? lt + match.index + match[0].length : html.length;
+      continue;
+    }
+    const isLinkElement = /^<a[\s/>]/i.test(html.slice(lt, lt + 3)) || /^<v:roundrect[\s/>]/i.test(html.slice(lt, lt + 13));
+    if (!isLinkElement) {
+      i = lt + 1;
+      continue;
+    }
+    const tagEnd = findTagEnd(html, lt);
+    if (tagEnd === -1) break;
+    const tag = html.slice(lt, tagEnd);
+    if (!new RegExp(NOTRACK_ATTRIBUTE, "i").test(tag)) {
+      const href = findHref(html, lt, tagEnd);
+      if (href && isTrackable(href.url)) anchors.push(href);
+    }
+    i = tagEnd;
+  }
+  return anchors;
+}
+function findTagEnd(html, start) {
+  let quote = null;
+  for (let i = start + 1; i < html.length; i++) {
+    const ch = html[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === ">") return i + 1;
+  }
+  return -1;
+}
+function findHref(html, tagStart, tagEnd) {
+  const tag = html.slice(tagStart, tagEnd);
+  const match = /\shref\s*=\s*("([^"]*)"|'([^']*)'|([^\s>]+))/i.exec(tag);
+  if (!match) return null;
+  const quoted = match[2] !== void 0 || match[3] !== void 0;
+  const value = match[2] ?? match[3] ?? match[4] ?? "";
+  const valueStart = tagStart + match.index + match[0].indexOf(match[1]) + (quoted ? 1 : 0);
+  return { valueStart, valueEnd: valueStart + value.length, url: value };
+}
+function extractEmailLinks(html) {
+  const seen = /* @__PURE__ */ new Set();
+  const urls = [];
+  for (const anchor of scanAnchors(html)) {
+    if (seen.has(anchor.url)) continue;
+    seen.add(anchor.url);
+    urls.push(anchor.url);
+  }
+  return urls;
+}
+function rewriteEmailLinks(html, options) {
+  const { linkTable, tokens } = options;
+  const indexOfUrl = /* @__PURE__ */ new Map();
+  linkTable.forEach((url, index) => {
+    if (!indexOfUrl.has(url)) indexOfUrl.set(url, index);
+  });
+  const anchors = scanAnchors(html);
+  const untracked = [];
+  let rewritten = 0;
+  let output = html;
+  for (let i = anchors.length - 1; i >= 0; i--) {
+    const anchor = anchors[i];
+    const index = indexOfUrl.get(anchor.url);
+    if (index === void 0 || tokens[index] === void 0) {
+      untracked.push(anchor.url);
+      continue;
+    }
+    output = output.slice(0, anchor.valueStart) + appendToken(anchor.url, tokens[index]) + output.slice(anchor.valueEnd);
+    rewritten++;
+  }
+  return { html: output, rewritten, untracked: untracked.reverse() };
+}
+
+// src/email.ts
+var SLOT_PATTERN = /\{\{\s*bandit\.([a-zA-Z0-9_-]+)\s*\}\}/g;
+function renderEmail(templateHtml, options) {
+  const missingSlots = [];
+  const substituted = templateHtml.replace(SLOT_PATTERN, (match, name) => {
+    const value = options.slots[name];
+    if (value === void 0) {
+      missingSlots.push(name);
+      return match;
+    }
+    return value;
+  });
+  const { html, rewritten, untracked } = rewriteEmailLinks(substituted, {
+    linkTable: options.linkTable,
+    tokens: options.tokens
+  });
+  return { html, rewritten, untracked, missingSlots };
+}
+function extractSlotNames(templateHtml) {
+  const names = /* @__PURE__ */ new Set();
+  for (const match of templateHtml.matchAll(SLOT_PATTERN)) names.add(match[1]);
+  return [...names];
+}
+
+// src/email-plan.ts
+async function renderFromPlan(plan, recipientId, templateHtml, companySecret) {
+  const slots = {};
+  const combination = [];
+  for (let i = 0; i < plan.slots.length; i++) {
+    const slot = plan.slots[i];
+    const chosen = pickArm(slot.probabilities, await uniformFor(plan.salt, recipientId, i));
+    const index = chosen === -1 ? 0 : chosen;
+    combination.push(slot.arms[index]?.armIndex ?? 0);
+    const config = slot.configs[index];
+    slots[slot.name] = typeof config === "string" ? config : config?.content ?? config?.text ?? "";
+  }
+  const recipientHash = await hashRecipient(recipientId, companySecret);
+  const tokens = await Promise.all(
+    plan.linkTable.map(
+      (_, linkIndex) => mintEmailToken(
+        { c: plan.campaignId, r: recipientHash, k: combination, l: linkIndex },
+        plan.signingKey
+      )
+    )
+  );
+  const rendered = renderEmail(templateHtml, {
+    slots,
+    linkTable: plan.linkTable,
+    tokens
+  });
+  return { ...rendered, combination, tokens };
+}
+function shouldRefreshPlan(plan, recipientsRenderedSincePlan, now = Date.now()) {
+  return recipientsRenderedSincePlan >= plan.refreshEvery || now >= plan.expiresAt;
+}
+async function reportPlanImpressions(plan, recipientIds, options) {
+  const counts = await impressionManifest(plan, recipientIds);
+  if (counts.length === 0) return { recorded: false, alreadyRecorded: false };
+  const response = await fetch(`${options.apiUrl}/api/email/impressions`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "x-api-key": options.apiKey },
+    body: JSON.stringify({
+      campaignId: plan.campaignId,
+      // Derived from the recipients this call covers, so a retry of the same
+      // chunk collapses onto the same key without the caller needing to
+      // invent and persist an idempotency token of its own.
+      batchKey: options.batchKey ?? await batchKeyFor(plan.campaignId, recipientIds),
+      counts
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to report impressions: ${response.status}`);
+  }
+  const body = await response.json();
+  return body.data ?? { recorded: false, alreadyRecorded: false };
+}
+async function batchKeyFor(campaignId, recipientIds) {
+  const material = `${campaignId}|${[...recipientIds].sort().join(",")}`;
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(material));
+  return Array.from(new Uint8Array(digest).slice(0, 16)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
 export {
   BanditAlgorithm,
   BanditsClient as BanditClient,
   BanditsClient,
   ContentType,
+  DEFAULT_HALF_LIFE_MS,
+  DEFAULT_SESSION_TTL_MS,
+  DEFAULT_WINDOW_MS,
+  EMAIL_TOKEN_PARAM,
   ExperimentStatus,
+  ForgettingMode,
   FunnelStatus,
+  PLACEMENTS,
+  Posterior,
+  SESSION_CREATED_AT_KEY,
+  SESSION_ID_KEY,
+  STATIONARY,
+  SnapshotClient,
+  appendEmailToken,
   buildSubdomainUrl,
   calculateConfidenceInterval,
+  extractDocumentSlots,
+  extractEmailLinks,
+  extractSlotNames,
   extractSubdomain,
-  generateId,
+  generateId2 as generateId,
   generateSubdomain,
   getContentTypeCategory,
+  getOrCreateSessionId,
+  hashRecipient,
+  impressionManifest,
+  isSlotBinding,
   isValidEmail,
   isValidSubdomain,
+  mintEmailToken,
+  normalizeAlgorithm,
+  normalizePosterior,
   normalizeTreatmentWeights,
+  pickArm,
+  pickTreatment,
+  renderEmail,
+  renderEmailDocument,
+  renderFromPlan,
+  reportPlanImpressions,
+  resolveForgetting,
+  rewriteEmailLinks,
+  sampleCombination,
   sanitizeMetadata,
-  validateTreatmentWeights
+  shouldRefreshPlan,
+  uniformFor,
+  validateTreatmentWeights,
+  verifyEmailToken
 };
 //# sourceMappingURL=index.js.map