@basis-theory/web-elements 3.0.0-beta.4 → 3.0.0-beta.6

package/dist/{index-BOedIhUN.js → index-DPhSs28B.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";
@@ -183,8 +195,6 @@ 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",
@@ -463,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) {
@@ -477,9 +488,9 @@ const createPostMessageClient = (iframe, config) => {
   };
   window.addEventListener("message", handleMessage);
   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) => {
+  const sendRequestOnce = (type, payload, transfer) => {
     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"));
@@ -491,15 +502,21 @@ const createPostMessageClient = (iframe, config) => {
       }, config.timeout || 5e3);
       pendingRequests.set(nonce, { resolve, reject, timeout, timestamp });
       log2("Sending request", { type, nonce });
-      iframe.contentWindow.postMessage({ type, nonce, timestamp, payload }, config.targetOrigin);
+      const message = { type, nonce, timestamp, payload };
+      if (transfer == null ? void 0 : transfer.length) {
+        iframe.contentWindow.postMessage(message, config.targetOrigin, transfer);
+      } else {
+        iframe.contentWindow.postMessage(message, config.targetOrigin);
+      }
     });
   };
   const sendRequest = async (type, payload, options) => {
-    const maxRetries = (options == null ? void 0 : options.retries) !== void 0 ? options.retries : retryConfig.maxRetries;
+    var _a;
+    const maxRetries = ((_a = options == null ? void 0 : options.transfer) == null ? void 0 : _a.length) ? 0 : (options == null ? void 0 : options.retries) !== void 0 ? options.retries : retryConfig.maxRetries;
     let lastError = null;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       try {
-        return await sendRequestOnce(type, payload);
+        return await sendRequestOnce(type, payload, options == null ? void 0 : options.transfer);
       } catch (error) {
         lastError = error;
         const errorMessage = error.message;
@@ -597,6 +614,54 @@ const createMounter = () => {
     }
   };
 };
+const CMD_REGISTER_ELEMENT = "CMD_REGISTER_ELEMENT";
+const CMD_BIND_ELEMENT_PORT = "CMD_BIND_ELEMENT_PORT";
+const CMD_BIND_COORDINATOR_PORT = "CMD_BIND_COORDINATOR_PORT";
+const bindCoordinatorPort = async ({
+  elementId,
+  elementType,
+  client,
+  coordinatorRequest
+}) => {
+  await coordinatorRequest(CMD_REGISTER_ELEMENT, {
+    elementId,
+    type: elementType
+  });
+  const channel = new MessageChannel();
+  const coordinatorBind = await coordinatorRequest(
+    CMD_BIND_ELEMENT_PORT,
+    { elementId },
+    { retries: 0, transfer: [channel.port2] }
+  );
+  if (!(coordinatorBind == null ? void 0 : coordinatorBind.success)) {
+    channel.port1.close();
+    throw ElementError(
+      `Coordinator rejected the element port (${(coordinatorBind == null ? void 0 : coordinatorBind.error) ?? "UNKNOWN"})`,
+      elementId,
+      { elementType }
+    );
+  }
+  const elementBind = await client.sendRequest(
+    CMD_BIND_COORDINATOR_PORT,
+    { elementId },
+    { retries: 0, transfer: [channel.port1] }
+  ).catch((error) => {
+    log("Failed to hand coordinator port to element", {
+      error: error.message
+    });
+    return { success: false, error: error.message };
+  });
+  if (!(elementBind == null ? void 0 : elementBind.success)) {
+    await coordinatorRequest("CMD_BROADCAST_ELEMENT_UNMOUNT", {
+      elementId
+    }).catch(() => void 0);
+    throw ElementError(
+      `Element rejected the coordinator port (${(elementBind == null ? void 0 : elementBind.error) ?? "UNKNOWN"})`,
+      elementId,
+      { elementType }
+    );
+  }
+};
 const createIframe = (config) => {
   const iframe = document.createElement("iframe");
   iframe.src = config.src;
@@ -709,7 +774,7 @@ const createEventDispatcher = (config) => {
     dispatchError
   };
 };
-const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount) => {
+const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount, coordinatorRequest) => {
   let iframe = null;
   let client = null;
   let mounter = null;
@@ -743,6 +808,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");
@@ -800,6 +868,12 @@ const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorEle
       try {
         await ensureCoordinatorReady();
         await readyPromise;
+        await bindCoordinatorPort({
+          elementId: id,
+          elementType: type,
+          client,
+          coordinatorRequest
+        });
         await client.sendRequest("CMD_SET_CONFIG", {
           elementId: id,
           // Include element ID for validation
@@ -928,7 +1002,7 @@ const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorEle
     }
   };
 };
-const createCVVElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount) => {
+const createCVVElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount, coordinatorRequest) => {
   let iframe = null;
   let client = null;
   let mounter = null;
@@ -954,6 +1028,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);
@@ -1008,6 +1085,12 @@ const createCVVElement = (apiKey, sdkConfig, options = {}, coordinatorElementId,
       try {
         await ensureCoordinatorReady();
         await readyPromise;
+        await bindCoordinatorPort({
+          elementId: id,
+          elementType: type,
+          client,
+          coordinatorRequest
+        });
         await client.sendRequest("CMD_SET_CONFIG", {
           elementId: id,
           // Include element ID for validation
@@ -1118,7 +1201,7 @@ const createCVVElement = (apiKey, sdkConfig, options = {}, coordinatorElementId,
     }
   };
 };
-const createExpiryElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount) => {
+const createExpiryElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount, coordinatorRequest) => {
   let iframe = null;
   let client = null;
   let mounter = null;
@@ -1144,6 +1227,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);
@@ -1198,6 +1284,12 @@ const createExpiryElement = (apiKey, sdkConfig, options = {}, coordinatorElement
       try {
         await ensureCoordinatorReady();
         await readyPromise;
+        await bindCoordinatorPort({
+          elementId: id,
+          elementType: type,
+          client,
+          coordinatorRequest
+        });
         await client.sendRequest("CMD_SET_CONFIG", {
           elementId: id,
           // Include element ID for validation
@@ -1304,7 +1396,7 @@ const createExpiryElement = (apiKey, sdkConfig, options = {}, coordinatorElement
     }
   };
 };
-const createTextElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount) => {
+const createTextElement = (apiKey, sdkConfig, options = {}, coordinatorElementId, ensureCoordinatorReady, notifyCoordinatorElementUnmount, coordinatorRequest) => {
   let iframe = null;
   let client = null;
   let mounter = null;
@@ -1337,6 +1429,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);
@@ -1391,6 +1486,12 @@ const createTextElement = (apiKey, sdkConfig, options = {}, coordinatorElementId
       try {
         await ensureCoordinatorReady();
         await readyPromise;
+        await bindCoordinatorPort({
+          elementId: id,
+          elementType: type,
+          client,
+          coordinatorRequest
+        });
         const serializedTransform = options.transform ? {
           pattern: options.transform[0].source,
           flags: options.transform[0].flags,
@@ -1712,14 +1813,17 @@ const warnUnknownKeys = (label, obj, knownKeys, deprecatedKeys) => {
 };
 const KNOWN_SDK_KEYS = /* @__PURE__ */ new Set([
   "elementsBaseUrl",
+  "whitelabelDomain",
   "apiBaseUrl",
   "debug",
+  "allowClipboard",
   "measurePerformance",
   "timeoutMs",
   "retryConfig",
   "themeMode",
   "theme",
-  "darkTheme"
+  "darkTheme",
+  "sessionAuthorizationUrl"
 ]);
 const DEPRECATED_SDK_KEYS = /* @__PURE__ */ new Map([
   ["iframeOrigin", 'Use "elementsBaseUrl" instead.']
@@ -1761,6 +1865,9 @@ const validateSDKConfig = (options = {}) => {
   if (options.debug !== void 0 && typeof options.debug !== "boolean") {
     throw ConfigurationError("debug must be a boolean");
   }
+  if (options.allowClipboard !== void 0 && typeof options.allowClipboard !== "boolean") {
+    throw ConfigurationError("allowClipboard must be a boolean");
+  }
   if (options.measurePerformance !== void 0 && typeof options.measurePerformance !== "boolean") {
     throw ConfigurationError("measurePerformance must be a boolean");
   }
@@ -1787,7 +1894,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.4/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.6/elements");
+    resolvedBaseUrl = `${domainOrigin}${pathname}`;
+  }
+  const finalBaseUrl = resolvedBaseUrl || "https://js.basistheory.com/3.0.0-beta.6/elements";
   const iframeOrigin = new URL(finalBaseUrl).origin;
   return {
     iframeOrigin,
@@ -1795,6 +1939,7 @@ const validateSDKConfig = (options = {}) => {
     apiBaseUrl: options.apiBaseUrl,
     // Optional - auto-detects if not provided
     debug: options.debug ?? false,
+    allowClipboard: options.allowClipboard ?? false,
     measurePerformance: options.measurePerformance ?? false,
     timeoutMs: options.timeoutMs || 3e4,
     // 30s default for slow 3G connections
@@ -1803,7 +1948,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([
@@ -1841,6 +1988,12 @@ const ELEMENT_TYPE_KEYS = {
     "value",
     "text",
     "disabled"
+  ]),
+  cardDisplay: /* @__PURE__ */ new Set([
+    "tokenId",
+    "number",
+    "cvc",
+    "expiration"
   ])
 };
 const validateElementOptions = (type, options = {}) => {
@@ -1941,7 +2094,109 @@ 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", {
@@ -1961,22 +2216,36 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
       });
     }
   };
+  const sendCoordinatorRequest = async (command, payload, options2) => {
+    if (!coordinatorClient) {
+      throw CoordinatorError("Coordinator not initialized");
+    }
+    return coordinatorClient.sendRequest(command, payload, options2);
+  };
   let cardElementFactory = null;
   let copyButtonElementFactory = null;
+  let cardDisplayElementFactory = null;
   const lazyCardElement = async () => {
     if (!cardElementFactory) {
-      const module = await import("./create-card-B5zEHyRg.js");
+      const module = await import("./create-card-C0MwL3Ou.js");
       cardElementFactory = module.createCardElement;
     }
     return cardElementFactory;
   };
   const lazyCopyButtonElement = async () => {
     if (!copyButtonElementFactory) {
-      const module = await import("./create-copy-button-DrAz8g0m.js");
+      const module = await import("./create-copy-button-DlJ3VvAn.js");
       copyButtonElementFactory = module.createCopyButtonElement;
     }
     return copyButtonElementFactory;
   };
+  const lazyCardDisplayElement = async () => {
+    if (!cardDisplayElementFactory) {
+      const module = await import("./create-card-display-DscvxIs4.js");
+      cardDisplayElementFactory = module.createCardDisplayElement;
+    }
+    return cardDisplayElementFactory;
+  };
   const syncFactories = {
     cardNumber: createCardNumberElement,
     cvv: createCVVElement,
@@ -1985,7 +2254,8 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
   };
   const lazyFactories = {
     card: lazyCardElement,
-    copyButton: lazyCopyButtonElement
+    copyButton: lazyCopyButtonElement,
+    cardDisplay: lazyCardDisplayElement
   };
   const ensureCoordinatorInitialized = () => {
     if (coordinatorReadyPromise) {
@@ -2027,7 +2297,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.`
@@ -2037,13 +2310,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,
@@ -2057,10 +2338,16 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
       // Optional - auto-detects if not provided
       apiTimeout: 3e4,
       apiRetries: 3,
+      // Frozen by the coordinator on this first config; copy references are
+      // refused unless it's enabled here.
+      allowClipboard: config.allowClipboard,
       debug: config.debug || false,
       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");
   };
@@ -2070,7 +2357,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) {
@@ -2079,6 +2366,12 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
       if (elementOptions) {
         validateElementOptions(type, elementOptions);
       }
+      if (type === "copyButton" && !config.allowClipboard) {
+        throw ConfigurationError(
+          "copyButton requires allowClipboard: true on BasisTheory() initialization. Clipboard access for raw card data may not be PCI compliant and must be enabled explicitly.",
+          { received: config.allowClipboard, expected: true, elementType: type }
+        );
+      }
       const localElementId = `${type}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
       log2("Creating element (sync)", {
         type,
@@ -2094,79 +2387,21 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           elementOptions,
           localElementId,
           ensureCoordinatorInitialized,
-          notifyCoordinatorElementUnmount
+          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,
-                notifyCoordinatorElementUnmount
-              );
-            })();
-          }
-          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);
-          },
-          // Forward setValueRef for CopyButtonElement
-          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");
-          }
-        };
+          localElementId,
+          apiKey,
+          config,
+          elementOptions,
+          ensureCoordinatorInitialized,
+          notifyCoordinatorElementUnmount,
+          sendCoordinatorRequest
+        );
       }
       elements.set(element.id, element);
       if (type === "cardNumber") {
@@ -2205,8 +2440,8 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
         });
       }
       return element;
-    },
-    tokenize: async (payload, options2) => {
+    }),
+    tokenize: guardAsync(async (payload, options2) => {
       log2("tokenize called", {
         hasPayload: !!payload,
         hasOptions: !!options2,
@@ -2243,7 +2478,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
         });
         throw error;
       }
-    },
+    }),
     /**
      * Token CRUD operations
      * Supports Element references - automatically resolves to secure values
@@ -2253,7 +2488,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");
         }
@@ -2288,7 +2523,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           });
           throw error;
         }
-      },
+      }),
       /**
        * Retrieve a token by ID
        *
@@ -2296,7 +2531,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)
@@ -2326,12 +2561,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();
@@ -2353,7 +2588,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           });
           throw error;
         }
-      },
+      }),
       /**
        * Encrypt token data with client-side JWE
        * Uses ECDH-ES key agreement and A256GCM authenticated encryption
@@ -2364,7 +2599,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
@@ -2405,14 +2640,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();
@@ -2436,13 +2671,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,
@@ -2475,11 +2710,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
         });
@@ -2507,15 +2742,16 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           });
           throw error;
         }
-      }
+      })
     },
     proxy: (() => {
-      const invokeProxy = async (method, options2 = {}) => {
+      const invokeProxy = guardAsync(async (method, options2 = {}) => {
         validateProxyOptions({ ...options2, method });
         log2("proxy invoked", {
           method,
           hasUrl: !!options2.url,
-          hasProxyKey: !!options2.proxyKey
+          hasProxyKey: !!options2.proxyKey,
+          hasApiKey: !!options2.apiKey
         });
         if (!coordinatorClient) {
           log2("Waiting for coordinator initialization");
@@ -2534,7 +2770,8 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
               proxyKey: options2.proxyKey,
               headers: options2.headers,
               body: resolvedBody,
-              includeResponseHeaders: options2.includeResponseHeaders
+              includeResponseHeaders: options2.includeResponseHeaders,
+              apiKey: options2.apiKey
             },
             { retries: 0 }
           );
@@ -2547,7 +2784,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
           });
           throw error;
         }
-      };
+      });
       const proxyVerb = (method) => (options2) => invokeProxy(method, options2 ?? {});
       return {
         get: proxyVerb("GET"),
@@ -2557,7 +2794,7 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
         delete: proxyVerb("DELETE")
       };
     })(),
-    updateThemeMode: async (mode) => {
+    updateThemeMode: guardAsync(async (mode) => {
       log2("updateThemeMode called", {
         oldMode: currentThemeMode,
         newMode: mode,
@@ -2596,6 +2833,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) {
@@ -2650,8 +2960,8 @@ 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.4";
-const buildDate = "2026-06-09T15:35:24.276Z";
+const version = "3.0.0-beta.6";
+const buildDate = "2026-08-05T15:06:02.574Z";
 if (typeof window !== "undefined") {
   window.__BasisTheorySDK__ = BasisTheory;
 }
@@ -2660,10 +2970,11 @@ export {
   ConfigurationError as C,
   ElementError as E,
   createPostMessageClient as a,
-  createEventDispatcher as b,
+  bindCoordinatorPort as b,
   createIframe as c,
-  createMounter as d,
-  buildDate as e,
+  createEventDispatcher as d,
+  createMounter as e,
+  buildDate as f,
   log as l,
   version as v
 };