@basis-theory/web-elements 3.0.0-beta.3 → 3.0.0-beta.5

package/dist/{index-BBfuUaLw.js → index-Dyy7tm5Z.js}

@@ -15,7 +15,9 @@ const REDACT_PATTERNS = [
   /secret/i,
   /token/i,
   /ssn/i,
-  /track/i
+  /track/i,
+  /session_key/i,
+  /^apikey$/i
 ];
 const isPANField = (key) => {
   return PAN_PATTERNS.some((pattern) => pattern.test(key));
@@ -140,6 +142,16 @@ const createDebugLogger = (packageName, enabled) => {
     console.log(`🔍 [${timestamp}] [${packageName}] ${action}`, sanitized);
   };
 };
+const generateId = () => {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  const random = () => Math.random().toString(36).substring(2);
+  const randomPart = (random() + random() + random() + random()).substring(0, 32);
+  return `${randomPart.substring(0, 8)}-${randomPart.substring(8, 12)}-${randomPart.substring(12, 16)}-${randomPart.substring(16, 20)}-${randomPart.substring(20, 32)}`;
+};
+const log = (action, metadata) => {
+};
 const createBasisTheoryError = (code, message, details) => {
   const error = new Error(message);
   error.name = "BasisTheoryError";
@@ -162,7 +174,7 @@ const BasisTheoryError = (code, message, details) => {
   return error;
 };
 const ValidationError = (message, field, details) => {
-  const error = createBasisTheoryError("VALIDATION_ERROR", message, details);
+  const error = createBasisTheoryError("VALIDATION_ERROR", message, field ? { field, ...details } : details);
   error.name = "ValidationError";
   error.field = field;
   return error;
@@ -183,7 +195,201 @@ const ConfigurationError = (message, details) => {
   error.name = "ConfigurationError";
   return error;
 };
-const log = (action, metadata) => {
+const ALLOWED_PROXY_SCHEMES = /* @__PURE__ */ new Set(["https:"]);
+const ALLOWED_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE"
+]);
+const FORBIDDEN_PROXY_HEADERS = /* @__PURE__ */ new Set([
+  // Request smuggling prevention
+  "host",
+  "content-length",
+  "transfer-encoding",
+  "te",
+  "trailer",
+  // Connection manipulation prevention
+  "connection",
+  "upgrade",
+  "keep-alive",
+  "proxy-connection",
+  // Proxy bypass prevention
+  "via",
+  "proxy-authorization",
+  // BasisTheory credential protection
+  "bt-api-key",
+  "bt-proxy-key",
+  "bt-proxy-url",
+  "bt-idempotency-key",
+  // Forwarded headers
+  "x-forwarded-for",
+  "x-forwarded-host",
+  "x-real-ip",
+  // SDK owns serialization format — body is always JSON.stringify'd
+  "content-type"
+]);
+const validateProxyHeaders = (headers) => {
+  if (!headers)
+    return;
+  for (const [key, value] of Object.entries(headers)) {
+    if (/[\r\n]/.test(value)) {
+      throw ValidationError(`Header '${key}' value contains illegal CRLF`, "headers");
+    }
+    if (/[\r\n]/.test(key)) {
+      throw ValidationError(`Header name '${key}' contains illegal CRLF`, "headers");
+    }
+    if (FORBIDDEN_PROXY_HEADERS.has(key.toLowerCase().trim())) {
+      throw ValidationError(`Header '${key}' is not allowed in proxy requests`, "headers");
+    }
+  }
+};
+const parseIPv4 = (hostname) => {
+  const clean = hostname.replace(/^\[|\]$/g, "");
+  if (/^(0x[\da-f]+|\d+)$/i.test(clean)) {
+    const num = clean.toLowerCase().startsWith("0x") ? parseInt(clean, 16) : parseInt(clean, 10);
+    if (num >= 0 && num <= 4294967295) {
+      return [
+        num >>> 24 & 255,
+        num >>> 16 & 255,
+        num >>> 8 & 255,
+        num & 255
+      ];
+    }
+    return null;
+  }
+  const parts = clean.split(".");
+  if (parts.length !== 4) {
+    return null;
+  }
+  const octets = [];
+  for (const part of parts) {
+    let value;
+    if (part.toLowerCase().startsWith("0x")) {
+      value = parseInt(part, 16);
+    } else if (part.startsWith("0") && part.length > 1 && !/[89]/.test(part)) {
+      value = parseInt(part, 8);
+    } else {
+      value = parseInt(part, 10);
+    }
+    if (isNaN(value) || value < 0 || value > 255) {
+      return null;
+    }
+    octets.push(value);
+  }
+  return octets;
+};
+const isPrivateIPv4 = (octets) => {
+  const a = octets[0];
+  const b = octets[1];
+  if (a === void 0 || b === void 0)
+    return true;
+  if (a === 127)
+    return true;
+  if (a === 10)
+    return true;
+  if (a === 172 && b >= 16 && b <= 31)
+    return true;
+  if (a === 192 && b === 168)
+    return true;
+  if (a === 169 && b === 254)
+    return true;
+  if (a === 0)
+    return true;
+  return false;
+};
+const isBlockedIPv6 = (hostname) => {
+  const clean = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  if (clean === "::1" || clean === "0:0:0:0:0:0:0:1" || clean === "0000:0000:0000:0000:0000:0000:0000:0001") {
+    return true;
+  }
+  if (clean.startsWith("fe8") || clean.startsWith("fe9") || clean.startsWith("fea") || clean.startsWith("feb")) {
+    return true;
+  }
+  if (clean.startsWith("fc") || clean.startsWith("fd")) {
+    return true;
+  }
+  const ipv4MappedDotted = clean.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (ipv4MappedDotted) {
+    const ipv4Part = ipv4MappedDotted[1];
+    if (ipv4Part) {
+      const ipv4Octets = parseIPv4(ipv4Part);
+      if (ipv4Octets && isPrivateIPv4(ipv4Octets)) {
+        return true;
+      }
+    }
+  }
+  const ipv4MappedHex = clean.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (ipv4MappedHex) {
+    const highPart = ipv4MappedHex[1];
+    const lowPart = ipv4MappedHex[2];
+    if (!highPart || !lowPart) {
+      return true;
+    }
+    const high = parseInt(highPart, 16);
+    const low = parseInt(lowPart, 16);
+    const octets = [
+      high >>> 8 & 255,
+      high & 255,
+      low >>> 8 & 255,
+      low & 255
+    ];
+    if (isPrivateIPv4(octets)) {
+      return true;
+    }
+  }
+  return false;
+};
+const validateSsrfProtection = (parsed) => {
+  const hostname = parsed.hostname.toLowerCase();
+  if (parsed.username || parsed.password) {
+    throw ValidationError("URL must not contain userinfo (username/password)", "url");
+  }
+  if (hostname === "localhost") {
+    throw ValidationError("URL must not target localhost", "url");
+  }
+  if (hostname.startsWith("[") || isBlockedIPv6(hostname)) {
+    if (isBlockedIPv6(hostname)) {
+      throw ValidationError("URL must not target loopback or link-local IPv6 addresses", "url");
+    }
+  }
+  const ipv4Octets = parseIPv4(hostname);
+  if (ipv4Octets && isPrivateIPv4(ipv4Octets)) {
+    throw ValidationError("URL must not target private or internal IP addresses", "url");
+  }
+};
+const validateProxyUrl = (url) => {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw ValidationError("Invalid URL format", "url");
+  }
+  if (!ALLOWED_PROXY_SCHEMES.has(parsed.protocol)) {
+    throw ValidationError(`URL scheme '${parsed.protocol}' is not allowed. Only https: is permitted`, "url");
+  }
+  validateSsrfProtection(parsed);
+};
+const validateProxyTarget = (url, proxyKey) => {
+  const hasUrl = typeof url === "string" && url.length > 0;
+  const hasKey = typeof proxyKey === "string" && proxyKey.length > 0;
+  if (hasUrl === hasKey) {
+    throw ValidationError("Specify exactly one of url or proxyKey", "url/proxyKey");
+  }
+  if (hasUrl) {
+    validateProxyUrl(url);
+  }
+};
+const validateProxyOptions = (options) => {
+  if (options !== void 0 && (typeof options !== "object" || options === null)) {
+    throw ValidationError("Proxy options must be a plain object", "options");
+  }
+  if ((options == null ? void 0 : options.method) !== void 0 && !ALLOWED_METHODS.has(options.method)) {
+    throw ValidationError(`Method '${options.method}' is not allowed`, "method");
+  }
+  validateProxyTarget(options == null ? void 0 : options.url, options == null ? void 0 : options.proxyKey);
+  validateProxyHeaders(options == null ? void 0 : options.headers);
 };
 const DEFAULT_RETRY_CONFIG = {
   maxRetries: 2,
@@ -267,9 +473,10 @@ const createPostMessageClient = (iframe, config) => {
         try {
           callback(payload);
         } catch (err) {
-          if (config.debug) {
-            console.error(`[PostMessage Client] Error in event subscriber for ${type}:`, err);
-          }
+          log2("Error in event subscriber", {
+            type,
+            error: err.message
+          });
         }
       });
     } else if (!nonce) {
@@ -283,7 +490,7 @@ const createPostMessageClient = (iframe, config) => {
   const retryConfig = typeof config.retries === "number" ? { ...DEFAULT_RETRY_CONFIG, maxRetries: config.retries } : typeof config.retries === "object" ? config.retries : DEFAULT_RETRY_CONFIG;
   const sendRequestOnce = (type, payload) => {
     return new Promise((resolve, reject) => {
-      const nonce = crypto.randomUUID();
+      const nonce = generateId();
       const timestamp = Date.now();
       if (!iframe.contentWindow) {
         reject(BasisTheoryError("IFRAME_NOT_READY", "Iframe not ready"));
@@ -298,9 +505,10 @@ const createPostMessageClient = (iframe, config) => {
       iframe.contentWindow.postMessage({ type, nonce, timestamp, payload }, config.targetOrigin);
     });
   };
-  const sendRequest = async (type, payload) => {
+  const sendRequest = async (type, payload, options) => {
+    const maxRetries = (options == null ? void 0 : options.retries) !== void 0 ? options.retries : retryConfig.maxRetries;
     let lastError = null;
-    for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
       try {
         return await sendRequestOnce(type, payload);
       } catch (error) {
@@ -316,11 +524,11 @@ const createPostMessageClient = (iframe, config) => {
           });
           throw error;
         }
-        if (attempt < retryConfig.maxRetries) {
+        if (attempt < maxRetries) {
           const delay = getRetryDelay(attempt, retryConfig);
           log2("Retrying request", {
             attempt: attempt + 1,
-            maxRetries: retryConfig.maxRetries,
+            maxRetries,
             delayMs: delay,
             error: errorMessage
           });
@@ -328,7 +536,7 @@ const createPostMessageClient = (iframe, config) => {
         }
       }
     }
-    throw lastError || new Error(`Request failed after ${retryConfig.maxRetries} retries: ${type}`);
+    throw lastError || new Error(`Request failed after ${maxRetries} retries: ${type}`);
   };
   const ping = async (timeout = 1e3) => {
     const start = Date.now();
@@ -405,7 +613,7 @@ const createIframe = (config) => {
   iframe.src = config.src;
   iframe.setAttribute("sandbox", config.sandbox);
   iframe.title = config.title;
-  iframe.setAttribute("allow", "payment *");
+  iframe.setAttribute("allow", config.allow ?? "payment *");
   iframe.setAttribute("importance", "high");
   iframe.style.opacity = "0";
   return iframe;
@@ -444,7 +652,9 @@ const createEventDispatcher = (config) => {
           bin: payload.bin,
           cvvLengths: payload.cvvLengths,
           potentialBrands: payload.potentialBrands,
-          matchStrength: payload.matchStrength
+          matchStrength: payload.matchStrength,
+          networks: payload.networks,
+          selectedNetwork: payload.selectedNetwork
         };
         dispatch("change", cardDetail);
       } else if (elementType === "card") {
@@ -453,27 +663,47 @@ const createEventDispatcher = (config) => {
           cardBrand: payload.cardBrand,
           last4: payload.last4,
           bin: payload.bin,
+          networks: payload.networks,
+          selectedNetwork: payload.selectedNetwork,
           errors: payload.errors || null
         });
       } else {
         dispatch("change", changeDetail);
       }
     });
+    client.subscribe(
+      "EVENT_NETWORK_CHANGED",
+      (payload) => {
+        if (elementType !== "cardNumber" && elementType !== "card") {
+          return;
+        }
+        const detail = {
+          network: payload.network,
+          previousNetwork: payload.previousNetwork,
+          availableNetworks: payload.availableNetworks ?? [],
+          selectionMode: payload.selectionMode ?? "auto"
+        };
+        dispatch("networkChanged", detail);
+      }
+    );
     client.subscribe("EVENT_FOCUS", () => {
       dispatch("focus", {});
     });
     client.subscribe("EVENT_BLUR", () => {
       dispatch("blur", {});
     });
-    client.subscribe("EVENT_ERROR", (payload) => {
-      dispatch("error", {
-        code: payload.code,
-        message: payload.message,
-        status: payload.status,
-        validationErrors: payload.validationErrors,
-        metadata: payload.metadata || {}
-      });
-    });
+    client.subscribe(
+      "EVENT_ERROR",
+      (payload) => {
+        dispatch("error", {
+          code: payload.code,
+          message: payload.message,
+          status: payload.status,
+          validationErrors: payload.validationErrors,
+          metadata: payload.metadata || {}
+        });
+      }
+    );
   };
   const dispatchError = (code, message, error) => {
     dispatch("error", {
@@ -490,7 +720,7 @@ const createEventDispatcher = (config) => {
     dispatchError
   };
 };
-const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady) => {
+const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount) => {
   let iframe = null;
   let client = null;
   let mounter = null;
@@ -511,6 +741,12 @@ const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorEle
       eventTarget
     });
     eventDispatcher.setupSubscriptions();
+    client.subscribe("EVENT_CONTENT_HEIGHT", (payload) => {
+      const h = payload == null ? void 0 : payload.heightPx;
+      if (iframe && typeof h === "number" && h > 0) {
+        iframe.style.height = `${Math.ceil(h)}px`;
+      }
+    });
   };
   return {
     id,
@@ -518,6 +754,9 @@ const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorEle
     get mounted() {
       return isMounted;
     },
+    get loaded() {
+      return isMounted;
+    },
     mount: async (selector) => {
       if (isMounted) {
         throw ElementError("Element is already mounted");
@@ -587,7 +826,9 @@ const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorEle
           placeholder: options.placeholder,
           disabled: options.disabled,
           readOnly: options.readOnly,
-          debug: sdkConfig.debug
+          debug: sdkConfig.debug,
+          binLookup: options.binLookup,
+          coBadge: options.coBadge
         });
         if (iframe) iframe.style.opacity = "1";
       } catch (error) {
@@ -617,16 +858,17 @@ const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorEle
       if (!isMounted) {
         throw ElementError("Element is not mounted");
       }
-      if (client) {
-        client.sendRequest("CMD_CLEAR_CACHE", {}).catch((error) => {
-          log("Failed to send clear cache command", {
-            error: error.message
-          });
+      notifyCoordinatorElementUnmount(id).catch((error) => {
+        log("Failed to notify coordinator of element unmount", {
+          error: error.message
         });
+      });
+      if (client) {
         client.destroy();
         client = null;
       }
       if (mounter && iframe) {
+        iframe.style.height = "";
         mounter.unmount(iframe);
         iframe = null;
         mounter = null;
@@ -640,10 +882,23 @@ const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorEle
         throw ElementError("Element must be mounted before updating");
       }
       const updatePayload = {
-        placeholder: newOptions.placeholder,
-        disabled: newOptions.disabled,
-        readOnly: newOptions.readOnly
+        elementId: id
       };
+      if (newOptions.placeholder !== void 0) {
+        updatePayload.placeholder = newOptions.placeholder;
+      }
+      if (newOptions.disabled !== void 0) {
+        updatePayload.disabled = newOptions.disabled;
+      }
+      if (newOptions.readOnly !== void 0) {
+        updatePayload.readOnly = newOptions.readOnly;
+      }
+      if (newOptions.binLookup !== void 0) {
+        updatePayload.binLookup = newOptions.binLookup;
+      }
+      if (newOptions.coBadge !== void 0) {
+        updatePayload.coBadge = newOptions.coBadge;
+      }
       if (newOptions.themeMode !== void 0) {
         updatePayload.themeMode = newOptions.themeMode;
         updatePayload.theme = sdkConfig.theme;
@@ -669,6 +924,12 @@ const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorEle
       }
       client.sendRequest("CMD_CLEAR", {});
     },
+    setNetwork: async (network) => {
+      if (!isMounted || !client) {
+        throw ElementError("Element must be mounted before setNetwork");
+      }
+      await client.sendRequest("CMD_SET_NETWORK", { network });
+    },
     on: (eventType, listener) => {
       eventTarget.addEventListener(
         eventType,
@@ -681,7 +942,7 @@ const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorEle
     }
   };
 };
-const createCVVElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady) => {
+const createCVVElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount) => {
   let iframe = null;
   let client = null;
   let mounter = null;
@@ -707,6 +968,9 @@ const createCVVElement = (apiKey, sdkConfig, options = {}, coordinatorElementId,
     get mounted() {
       return isMounted;
     },
+    get loaded() {
+      return isMounted;
+    },
     mount: async (selector) => {
       if (isMounted) {
         throw ElementError("Element is already mounted", id);
@@ -804,12 +1068,12 @@ const createCVVElement = (apiKey, sdkConfig, options = {}, coordinatorElementId,
       if (!isMounted) {
         throw ElementError("Element is not mounted");
       }
-      if (client) {
-        client.sendRequest("CMD_CLEAR_CACHE", {}).catch((error) => {
-          log("Failed to send clear cache command", {
-            error: error.message
-          });
+      notifyCoordinatorElementUnmount(id).catch((error) => {
+        log("Failed to notify coordinator of element unmount", {
+          error: error.message
         });
+      });
+      if (client) {
         client.destroy();
         client = null;
       }
@@ -871,7 +1135,7 @@ const createCVVElement = (apiKey, sdkConfig, options = {}, coordinatorElementId,
     }
   };
 };
-const createExpiryElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady) => {
+const createExpiryElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount) => {
   let iframe = null;
   let client = null;
   let mounter = null;
@@ -897,6 +1161,9 @@ const createExpiryElement = (apiKey, sdkConfig, options = {}, coordinatorElement
     get mounted() {
       return isMounted;
     },
+    get loaded() {
+      return isMounted;
+    },
     mount: async (selector) => {
       if (isMounted) {
         throw ElementError("Element is already mounted", id);
@@ -993,12 +1260,12 @@ const createExpiryElement = (apiKey, sdkConfig, options = {}, coordinatorElement
       if (!isMounted) {
         throw ElementError("Element is not mounted");
       }
-      if (client) {
-        client.sendRequest("CMD_CLEAR_CACHE", {}).catch((error) => {
-          log("Failed to send clear cache command", {
-            error: error.message
-          });
+      notifyCoordinatorElementUnmount(id).catch((error) => {
+        log("Failed to notify coordinator of element unmount", {
+          error: error.message
         });
+      });
+      if (client) {
         client.destroy();
         client = null;
       }
@@ -1057,7 +1324,7 @@ const createExpiryElement = (apiKey, sdkConfig, options = {}, coordinatorElement
     }
   };
 };
-const createTextElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady) => {
+const createTextElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount) => {
   let iframe = null;
   let client = null;
   let mounter = null;
@@ -1090,6 +1357,9 @@ const createTextElement = (apiKey, sdkConfig, options = {}, coordinatorElementId
     get mounted() {
       return isMounted;
     },
+    get loaded() {
+      return isMounted;
+    },
     mount: async (selector) => {
       if (isMounted) {
         throw ElementError("Element is already mounted", id);
@@ -1207,12 +1477,12 @@ const createTextElement = (apiKey, sdkConfig, options = {}, coordinatorElementId
       if (!isMounted) {
         throw ElementError("Element is not mounted");
       }
-      if (client) {
-        client.sendRequest("CMD_CLEAR_CACHE", {}).catch((error) => {
-          log("Failed to send clear cache command", {
-            error: error.message
-          });
+      notifyCoordinatorElementUnmount(id).catch((error) => {
+        log("Failed to notify coordinator of element unmount", {
+          error: error.message
         });
+      });
+      if (client) {
         client.destroy();
         client = null;
       }
@@ -1465,6 +1735,7 @@ const warnUnknownKeys = (label, obj, knownKeys, deprecatedKeys) => {
 };
 const KNOWN_SDK_KEYS = /* @__PURE__ */ new Set([
   "elementsBaseUrl",
+  "whitelabelDomain",
   "apiBaseUrl",
   "debug",
   "measurePerformance",
@@ -1472,7 +1743,8 @@ const KNOWN_SDK_KEYS = /* @__PURE__ */ new Set([
   "retryConfig",
   "themeMode",
   "theme",
-  "darkTheme"
+  "darkTheme",
+  "sessionAuthorizationUrl"
 ]);
 const DEPRECATED_SDK_KEYS = /* @__PURE__ */ new Map([
   ["iframeOrigin", 'Use "elementsBaseUrl" instead.']
@@ -1540,7 +1812,44 @@ const validateSDKConfig = (options = {}) => {
   if (!["light", "dark", "auto"].includes(themeMode)) {
     throw ConfigurationError('themeMode must be "light", "dark", or "auto"');
   }
-  const finalBaseUrl = baseUrl || "https://js.basistheory.com/3.0.0-beta.3/elements";
+  if (options.sessionAuthorizationUrl !== void 0) {
+    if (typeof options.sessionAuthorizationUrl !== "string" || options.sessionAuthorizationUrl.trim() === "") {
+      throw ConfigurationError("sessionAuthorizationUrl must be a non-empty string");
+    }
+    try {
+      const parsed = new URL(options.sessionAuthorizationUrl, window.location.origin);
+      if (parsed.protocol === "http:" && parsed.hostname !== "localhost" && parsed.hostname !== "127.0.0.1") {
+        throw ConfigurationError("sessionAuthorizationUrl must use https://.");
+      }
+    } catch (error) {
+      if (error instanceof Error && error.name === "ConfigurationError") {
+        throw error;
+      }
+    }
+  }
+  let resolvedBaseUrl = baseUrl;
+  if (resolvedBaseUrl === void 0 && options.whitelabelDomain !== void 0) {
+    const { whitelabelDomain } = options;
+    if (typeof whitelabelDomain !== "string" || whitelabelDomain.trim().length === 0) {
+      throw ConfigurationError("whitelabelDomain must be a non-empty string");
+    }
+    let domainOrigin;
+    try {
+      const parsed = new URL(whitelabelDomain);
+      if (parsed.protocol !== "https:") {
+        throw ConfigurationError("whitelabelDomain must use https://");
+      }
+      domainOrigin = parsed.origin;
+    } catch (error) {
+      if (error instanceof Error && error.name === "ConfigurationError") {
+        throw error;
+      }
+      throw ConfigurationError("whitelabelDomain must be a valid URL");
+    }
+    const { pathname } = new URL("https://js.basistheory.com/3.0.0-beta.5/elements");
+    resolvedBaseUrl = `${domainOrigin}${pathname}`;
+  }
+  const finalBaseUrl = resolvedBaseUrl || "https://js.basistheory.com/3.0.0-beta.5/elements";
   const iframeOrigin = new URL(finalBaseUrl).origin;
   return {
     iframeOrigin,
@@ -1556,7 +1865,9 @@ const validateSDKConfig = (options = {}) => {
     // Light theme or only theme
     darkTheme: options.darkTheme ? mergeWithDefaultTheme(options.darkTheme) : void 0,
     // Optional dark theme
-    retryConfig
+    retryConfig,
+    sessionAuthorizationUrl: options.sessionAuthorizationUrl
+    // Optional - required for cardDisplay
   };
 };
 const COMMON_ELEMENT_KEYS = /* @__PURE__ */ new Set([
@@ -1566,7 +1877,7 @@ const COMMON_ELEMENT_KEYS = /* @__PURE__ */ new Set([
   "readOnly"
 ]);
 const ELEMENT_TYPE_KEYS = {
-  cardNumber: /* @__PURE__ */ new Set([...COMMON_ELEMENT_KEYS]),
+  cardNumber: /* @__PURE__ */ new Set([...COMMON_ELEMENT_KEYS, "binLookup", "coBadge"]),
   cvv: /* @__PURE__ */ new Set([...COMMON_ELEMENT_KEYS, "cardBrand", "cvvLengths"]),
   // Internal coordination props
   expiry: /* @__PURE__ */ new Set([...COMMON_ELEMENT_KEYS]),
@@ -1585,7 +1896,21 @@ const ELEMENT_TYPE_KEYS = {
     "layout",
     "stackAt",
     "iconPosition",
-    "cardBrands"
+    "cardBrands",
+    "binLookup",
+    "coBadge"
+  ]),
+  copyButton: /* @__PURE__ */ new Set([
+    "allowClipboard",
+    "value",
+    "text",
+    "disabled"
+  ]),
+  cardDisplay: /* @__PURE__ */ new Set([
+    "tokenId",
+    "number",
+    "cvc",
+    "expiration"
   ])
 };
 const validateElementOptions = (type, options = {}) => {
@@ -1636,6 +1961,14 @@ const validateElementOptions = (type, options = {}) => {
       }
     }
   }
+  if (type === "copyButton") {
+    const copyOpts = options;
+    if (copyOpts.allowClipboard !== true) {
+      throw ConfigurationError(
+        "CopyButton requires allowClipboard: true. Clipboard access for raw card data may not be PCI compliant and must be explicitly enabled."
+      );
+    }
+  }
   if (type === "card") {
     const cardOptions = options;
     if (cardOptions.layout !== void 0) {
@@ -1678,15 +2011,158 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
   let coordinatorClient = null;
   let coordinatorReadyPromise = null;
   let coordinatorInitStarted = false;
+  let coordinatorLoadTimeout = null;
+  let rejectCoordinatorLoad = null;
+  let destroyed = false;
+  const assertNotDestroyed = () => {
+    if (destroyed) {
+      throw ConfigurationError(
+        "SDK instance has been destroyed. Create a new instance with BasisTheory()"
+      );
+    }
+  };
+  const guardSync = (fn) => (...args) => {
+    assertNotDestroyed();
+    return fn(...args);
+  };
+  const guardAsync = (fn) => async (...args) => {
+    assertNotDestroyed();
+    return fn(...args);
+  };
   let currentThemeMode = options.themeMode || "auto";
+  const createLazyElementWrapper = (lazyFactory, elementType, elementId, elementApiKey, elementConfig, elementOptions, ensureCoordinator, notifyUnmount, coordinatorRequest) => {
+    let realElement = null;
+    let loadPromise = null;
+    const loadRealElement = async () => {
+      if (!loadPromise) {
+        loadPromise = (async () => {
+          const factory = await lazyFactory();
+          realElement = factory(
+            elementApiKey,
+            elementConfig,
+            elementOptions,
+            elementId,
+            ensureCoordinator,
+            notifyUnmount,
+            coordinatorRequest
+          );
+        })();
+      }
+      await loadPromise;
+    };
+    const ensureLoaded = () => {
+      if (!realElement) throw ElementError("Element not initialized");
+      return realElement;
+    };
+    const wrapper = {
+      id: elementId,
+      type: elementType,
+      get mounted() {
+        return (realElement == null ? void 0 : realElement.mounted) ?? false;
+      },
+      get loaded() {
+        return (realElement == null ? void 0 : realElement.loaded) ?? false;
+      },
+      mount: async (selector) => {
+        await loadRealElement();
+        return realElement.mount(selector);
+      },
+      unmount: () => ensureLoaded().unmount(),
+      update: async (opts) => ensureLoaded().update(opts),
+      focus: () => ensureLoaded().focus(),
+      blur: () => ensureLoaded().blur(),
+      clear: () => ensureLoaded().clear(),
+      on: (eventType, listener) => {
+        if (!realElement) {
+          let unsubscribe = null;
+          let cancelled = false;
+          loadRealElement().then(() => {
+            if (!cancelled) unsubscribe = realElement.on(eventType, listener);
+          });
+          return () => {
+            cancelled = true;
+            unsubscribe == null ? void 0 : unsubscribe();
+          };
+        }
+        return realElement.on(eventType, listener);
+      },
+      setValueRef: async (refElement) => {
+        if (!realElement) {
+          await loadRealElement();
+        }
+        if (realElement && "setValueRef" in realElement && typeof realElement.setValueRef === "function") {
+          return realElement.setValueRef(refElement);
+        }
+        throw ElementError("setValueRef not available on this element type");
+      }
+    };
+    if (elementType === "card") {
+      Object.defineProperties(wrapper, {
+        number: {
+          get: () => realElement == null ? void 0 : realElement.number,
+          enumerable: true
+        },
+        expiryDate: {
+          get: () => realElement == null ? void 0 : realElement.expiryDate,
+          enumerable: true
+        },
+        cvc: {
+          get: () => realElement == null ? void 0 : realElement.cvc,
+          enumerable: true
+        }
+      });
+    }
+    return wrapper;
+  };
+  const notifyCoordinatorElementUnmount = async (elementId) => {
+    if (!coordinatorClient) {
+      log2("Cannot notify coordinator of unmount - coordinator not initialized", {
+        elementId
+      });
+      return;
+    }
+    try {
+      await coordinatorClient.sendRequest("CMD_BROADCAST_ELEMENT_UNMOUNT", {
+        elementId
+      });
+      log2("Notified coordinator of element unmount", { elementId });
+    } catch (error) {
+      log2("Failed to notify coordinator of element unmount", {
+        elementId,
+        error: error.message
+      });
+    }
+  };
+  const sendCoordinatorRequest = async (command, payload) => {
+    if (!coordinatorClient) {
+      throw CoordinatorError("Coordinator not initialized");
+    }
+    return coordinatorClient.sendRequest(command, payload);
+  };
   let cardElementFactory = null;
+  let copyButtonElementFactory = null;
+  let cardDisplayElementFactory = null;
   const lazyCardElement = async () => {
     if (!cardElementFactory) {
-      const module = await import("./create-card-DipDWgph.js");
+      const module = await import("./create-card-CB_YcP_4.js");
       cardElementFactory = module.createCardElement;
     }
     return cardElementFactory;
   };
+  const lazyCopyButtonElement = async () => {
+    if (!copyButtonElementFactory) {
+      const module = await import("./create-copy-button-2XtKTEo3.js");
+      copyButtonElementFactory = module.createCopyButtonElement;
+    }
+    return copyButtonElementFactory;
+  };
+  const lazyCardDisplayElement = async () => {
+    if (!cardDisplayElementFactory) {
+      const module = await import("./create-card-display-kBupMJwe.js");
+      cardDisplayElementFactory = module.createCardDisplayElement;
+    }
+    return cardDisplayElementFactory;
+  };
   const syncFactories = {
     cardNumber: createCardNumberElement,
     cvv: createCVVElement,
@@ -1694,7 +2170,9 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
     text: createTextElement
   };
   const lazyFactories = {
-    card: lazyCardElement
+    card: lazyCardElement,
+    copyButton: lazyCopyButtonElement,
+    cardDisplay: lazyCardDisplayElement
   };
   const ensureCoordinatorInitialized = () => {
     if (coordinatorReadyPromise) {
@@ -1736,7 +2214,10 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
       url: coordinatorIframe.src
     });
     await new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
+      rejectCoordinatorLoad = reject;
+      coordinatorLoadTimeout = setTimeout(() => {
+        coordinatorLoadTimeout = null;
+        rejectCoordinatorLoad = null;
         reject(
           new Error(
             `Coordinator load timeout (${config.timeoutMs}ms). Try increasing timeoutMs for slow connections.`
@@ -1746,13 +2227,21 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
       coordinatorIframe.addEventListener(
         "load",
         () => {
-          clearTimeout(timeout);
+          if (coordinatorLoadTimeout !== null) {
+            clearTimeout(coordinatorLoadTimeout);
+          }
+          coordinatorLoadTimeout = null;
+          rejectCoordinatorLoad = null;
           log2("Coordinator iframe loaded");
           resolve();
         },
         { once: true }
       );
     });
+    if (destroyed) {
+      log2("Coordinator load resolved after destroy — aborting init");
+      return;
+    }
     coordinatorClient = createPostMessageClient(coordinatorIframe, {
       targetOrigin: new URL(config.elementsBaseUrl).origin,
       timeout: 3e4,
@@ -1770,6 +2259,9 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
       theme: config.theme,
       darkTheme: config.darkTheme,
       themeMode: config.themeMode
+      // sessionAuthorizationUrl is intentionally NOT sent to the coordinator:
+      // the merchant-authorization fetch now runs in the parent page (see
+      // create-card-display.ts), so the coordinator never needs the URL.
     });
     log2("Coordinator initialized successfully");
   };
@@ -1779,7 +2271,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
      * createElement is now SYNCHRONOUS - returns Element instantly
      * Coordinator initialization starts on first element (but doesn't block)
      */
-    createElement: (type, elementOptions) => {
+    createElement: guardSync((type, elementOptions) => {
       const syncFactory = syncFactories[type];
       const lazyFactory = lazyFactories[type];
       if (!syncFactory && !lazyFactory) {
@@ -1802,68 +2294,22 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           config,
           elementOptions,
           localElementId,
-          ensureCoordinatorInitialized
+          ensureCoordinatorInitialized,
+          notifyCoordinatorElementUnmount,
+          sendCoordinatorRequest
         );
       } else {
-        let realElement = null;
-        let loadPromise = null;
-        const loadRealElement = async () => {
-          if (!loadPromise) {
-            loadPromise = (async () => {
-              const factory = await lazyFactory();
-              realElement = factory(
-                apiKey,
-                config,
-                elementOptions,
-                localElementId,
-                ensureCoordinatorInitialized
-              );
-            })();
-          }
-          await loadPromise;
-        };
-        element = {
-          id: localElementId,
+        element = createLazyElementWrapper(
+          lazyFactory,
           type,
-          get mounted() {
-            return (realElement == null ? void 0 : realElement.mounted) ?? false;
-          },
-          get fields() {
-            return realElement == null ? void 0 : realElement.fields;
-          },
-          mount: async (selector) => {
-            await loadRealElement();
-            return realElement.mount(selector);
-          },
-          unmount: () => {
-            if (!realElement) throw ElementError("Element not initialized");
-            return realElement.unmount();
-          },
-          update: async (opts) => {
-            if (!realElement) throw ElementError("Element not initialized");
-            return realElement.update(opts);
-          },
-          focus: () => {
-            if (!realElement) throw ElementError("Element not initialized");
-            return realElement.focus();
-          },
-          blur: () => {
-            if (!realElement) throw ElementError("Element not initialized");
-            return realElement.blur();
-          },
-          clear: () => {
-            if (!realElement) throw ElementError("Element not initialized");
-            return realElement.clear();
-          },
-          on: (eventType, listener) => {
-            if (!realElement) {
-              loadRealElement().then(() => realElement.on(eventType, listener));
-              return () => {
-              };
-            }
-            return realElement.on(eventType, listener);
-          }
-        };
+          localElementId,
+          apiKey,
+          config,
+          elementOptions,
+          ensureCoordinatorInitialized,
+          notifyCoordinatorElementUnmount,
+          sendCoordinatorRequest
+        );
       }
       elements.set(element.id, element);
       if (type === "cardNumber") {
@@ -1902,8 +2348,8 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
         });
       }
       return element;
-    },
-    tokenize: async (payload, options2) => {
+    }),
+    tokenize: guardAsync(async (payload, options2) => {
       log2("tokenize called", {
         hasPayload: !!payload,
         hasOptions: !!options2,
@@ -1940,7 +2386,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
         });
         throw error;
       }
-    },
+    }),
     /**
      * Token CRUD operations
      * Supports Element references - automatically resolves to secure values
@@ -1950,7 +2396,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
        * Create a new token
        * Supports Element references in data (same as tokenize)
        */
-      create: async (request) => {
+      create: guardAsync(async (request) => {
         if (!request || typeof request !== "object" || Array.isArray(request)) {
           throw ValidationError("Token data must be a non-null object");
         }
@@ -1985,7 +2431,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           });
           throw error;
         }
-      },
+      }),
       /**
        * Retrieve a token by ID
        *
@@ -1993,7 +2439,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
        * @param options - Optional configuration
        * @param options.apiKey - Optional session key for authorized access (from sessions.create + authorize)
        */
-      retrieve: async (id, options2) => {
+      retrieve: guardAsync(async (id, options2) => {
         log2("tokens.retrieve called", {
           tokenId: id,
           hasSessionKey: !!(options2 == null ? void 0 : options2.apiKey)
@@ -2023,12 +2469,12 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           });
           throw error;
         }
-      },
+      }),
       /**
        * Update a token
        * Supports Element references in data
        */
-      update: async (id, request) => {
+      update: guardAsync(async (id, request) => {
         log2("tokens.update called", { tokenId: id });
         if (!coordinatorClient) {
           await initializeCoordinator();
@@ -2050,7 +2496,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           });
           throw error;
         }
-      },
+      }),
       /**
        * Encrypt token data with client-side JWE
        * Uses ECDH-ES key agreement and A256GCM authenticated encryption
@@ -2061,7 +2507,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
        * @param keyId - Key identifier for decryption lookup
        * @returns Encrypted JWE token(s)
        */
-      encrypt: async (tokenData, publicKeyPEM, keyId) => {
+      encrypt: guardAsync(async (tokenData, publicKeyPEM, keyId) => {
         log2("tokens.encrypt called", {
           isSingleToken: "type" in tokenData && "data" in tokenData,
           keyId
@@ -2102,14 +2548,14 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           });
           throw error;
         }
-      }
+      })
     },
     sessions: {
       /**
        * Create a new session for temporary elevated access
        * Note: Session must be authorized by a Private Application on your backend
        */
-      create: async () => {
+      create: guardAsync(async () => {
         log2("sessions.create called");
         if (!coordinatorClient) {
           await initializeCoordinator();
@@ -2133,13 +2579,13 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           });
           throw error;
         }
-      }
+      })
     },
     tokenIntents: {
       /**
        * Create a token intent with element reference support
        */
-      create: async (data, options2) => {
+      create: guardAsync(async (data, options2) => {
         log2("tokenIntents.create called", {
           type: data.type,
           hasData: !!data.data,
@@ -2172,11 +2618,11 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           });
           throw error;
         }
-      },
+      }),
       /**
        * Get a token intent by ID
        */
-      get: async (id, options2) => {
+      get: guardAsync(async (id, options2) => {
         log2("tokenIntents.get called", {
           intentId: id
         });
@@ -2204,9 +2650,57 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           });
           throw error;
         }
-      }
+      })
     },
-    updateThemeMode: async (mode) => {
+    proxy: (() => {
+      const invokeProxy = guardAsync(async (method, options2 = {}) => {
+        validateProxyOptions({ ...options2, method });
+        log2("proxy invoked", {
+          method,
+          hasUrl: !!options2.url,
+          hasProxyKey: !!options2.proxyKey
+        });
+        if (!coordinatorClient) {
+          log2("Waiting for coordinator initialization");
+          await initializeCoordinator();
+        }
+        if (!coordinatorClient) {
+          throw CoordinatorError("Coordinator failed to initialize");
+        }
+        const resolvedBody = options2.body !== void 0 ? resolveElementReferences(options2.body) : void 0;
+        try {
+          const result = await coordinatorClient.sendRequest(
+            "CMD_PROXY",
+            {
+              method,
+              url: options2.url,
+              proxyKey: options2.proxyKey,
+              headers: options2.headers,
+              body: resolvedBody,
+              includeResponseHeaders: options2.includeResponseHeaders
+            },
+            { retries: 0 }
+          );
+          log2("proxy successful", { method });
+          return result;
+        } catch (error) {
+          log2("proxy failed", {
+            method,
+            error: error.message
+          });
+          throw error;
+        }
+      });
+      const proxyVerb = (method) => (options2) => invokeProxy(method, options2 ?? {});
+      return {
+        get: proxyVerb("GET"),
+        post: proxyVerb("POST"),
+        put: proxyVerb("PUT"),
+        patch: proxyVerb("PATCH"),
+        delete: proxyVerb("DELETE")
+      };
+    })(),
+    updateThemeMode: guardAsync(async (mode) => {
       log2("updateThemeMode called", {
         oldMode: currentThemeMode,
         newMode: mode,
@@ -2245,6 +2739,79 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
         mode,
         updatedCount: Array.from(elements.values()).filter((el) => el.mounted).length
       });
+    }),
+    /**
+     * Destroys this instance and removes its elements from the page. Once
+     * destroyed, its other methods throw; create a new instance with
+     * BasisTheory() to recover. Safe to call more than once.
+     */
+    destroy: async () => {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
+      log2("Destroying SDK instance", {
+        elementCount: elements.size,
+        hasCoordinator: coordinatorIframe !== null
+      });
+      for (const [id, element] of elements) {
+        if (!element.mounted) {
+          continue;
+        }
+        try {
+          element.unmount();
+        } catch (error) {
+          log2("Failed to unmount element during destroy", {
+            elementId: id,
+            error: error.message
+          });
+        }
+      }
+      elements.clear();
+      if (coordinatorLoadTimeout !== null) {
+        clearTimeout(coordinatorLoadTimeout);
+        coordinatorLoadTimeout = null;
+      }
+      if (rejectCoordinatorLoad) {
+        rejectCoordinatorLoad(
+          ConfigurationError(
+            "SDK instance has been destroyed. Create a new instance with BasisTheory()"
+          )
+        );
+        rejectCoordinatorLoad = null;
+      }
+      if (coordinatorClient) {
+        const CACHE_CLEAR_TIMEOUT_MS = 2e3;
+        const cacheCleared = coordinatorClient.sendRequest("CMD_CLEAR_ALL_CACHE", {}, { retries: 0 }).catch((error) => {
+          log2("Failed to clear coordinator cache during destroy", {
+            error: error.message
+          });
+        });
+        let capTimeout;
+        const cap = new Promise((resolve) => {
+          capTimeout = setTimeout(() => {
+            log2("Coordinator cache-clear timed out during destroy", {
+              timeoutMs: CACHE_CLEAR_TIMEOUT_MS
+            });
+            resolve();
+          }, CACHE_CLEAR_TIMEOUT_MS);
+        });
+        await Promise.race([cacheCleared, cap]);
+        if (capTimeout !== void 0) {
+          clearTimeout(capTimeout);
+        }
+      }
+      if (coordinatorClient) {
+        coordinatorClient.destroy();
+        coordinatorClient = null;
+      }
+      if (coordinatorIframe) {
+        coordinatorIframe.remove();
+        coordinatorIframe = null;
+      }
+      coordinatorReadyPromise = null;
+      coordinatorInitStarted = false;
+      log2("SDK instance destroyed");
     }
   };
   if (queuedCommands && queuedCommands.length > 0) {
@@ -2299,19 +2866,21 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
 if (typeof window !== "undefined" && typeof document !== "undefined" && document.currentScript && !window.BasisTheory) {
   window.BasisTheory = BasisTheory;
 }
-const version = "3.0.0-beta.3";
-const buildDate = "2026-04-13T19:51:30.877Z";
+const version = "3.0.0-beta.5";
+const buildDate = "2026-07-16T14:24:00.230Z";
 if (typeof window !== "undefined") {
   window.__BasisTheorySDK__ = BasisTheory;
 }
 export {
   BasisTheory as B,
+  ConfigurationError as C,
   ElementError as E,
   createPostMessageClient as a,
   createEventDispatcher as b,
   createIframe as c,
   createMounter as d,
   buildDate as e,
+  generateId as g,
   log as l,
   version as v
 };