@basis-theory/web-elements 3.0.0 → 3.1.0

package/dist/{index-DIVQdm8b.js → index-hHam_H0I.js}

@@ -150,6 +150,8 @@ const generateId = () => {
   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 LANGUAGE_TAG = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{1,8})*$/;
+const isLanguageTag = (value) => typeof value === "string" && LANGUAGE_TAG.test(value);
 const log = (action, metadata) => {
 };
 const createBasisTheoryError = (code, message, details) => {
@@ -195,6 +197,16 @@ const ConfigurationError = (message, details) => {
   error.name = "ConfigurationError";
   return error;
 };
+const HttpClientError = (message, status, data, headers) => {
+  const error = createBasisTheoryError("HTTP_CLIENT_ERROR", message, {
+    status
+  });
+  error.name = "HttpClientError";
+  error.status = status;
+  error.data = data;
+  error.headers = headers;
+  return error;
+};
 const ALLOWED_PROXY_SCHEMES = /* @__PURE__ */ new Set(["https:"]);
 const ALLOWED_METHODS = /* @__PURE__ */ new Set([
   "GET",
@@ -381,6 +393,35 @@ const validateProxyTarget = (url, proxyKey) => {
     validateProxyUrl(url);
   }
 };
+const FORBIDDEN_DESTINATION_HEADERS = new Set([...FORBIDDEN_PROXY_HEADERS].filter((header) => header !== "content-type"));
+const validateDestinationHeaders = (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_DESTINATION_HEADERS.has(key.toLowerCase().trim())) {
+      throw ValidationError(`Header '${key}' is not allowed in HTTP client requests`, "headers");
+    }
+  }
+};
+const validateDestinationRequest = (options) => {
+  if (options !== void 0 && (typeof options !== "object" || options === null)) {
+    throw ValidationError("HTTP client 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");
+  }
+  if (typeof (options == null ? void 0 : options.url) !== "string" || options.url.length === 0) {
+    throw ValidationError("url is required", "url");
+  }
+  validateProxyUrl(options.url);
+  validateDestinationHeaders(options == null ? void 0 : options.headers);
+};
 const validateProxyOptions = (options) => {
   if (options !== void 0 && (typeof options !== "object" || options === null)) {
     throw ValidationError("Proxy options must be a plain object", "options");
@@ -450,6 +491,8 @@ const createPostMessageClient = (iframe, config) => {
             ...error.retryCount !== void 0 && {
               retryCount: error.retryCount
             },
+            ...error.data !== void 0 && { data: error.data },
+            ...error.headers && { headers: error.headers },
             ...error.details && { details: error.details }
           });
           pending.reject(reconstructedError);
@@ -878,17 +921,21 @@ const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorEle
           elementId: id,
           // Include element ID for validation
           apiKey,
+          environment: sdkConfig.environment,
           apiTimeout: sdkConfig.timeoutMs,
           apiRetries: sdkConfig.retryConfig.maxRetries,
           theme: sdkConfig.theme,
           darkTheme: sdkConfig.darkTheme,
           themeMode: sdkConfig.themeMode,
+          direction: sdkConfig.direction,
+          language: sdkConfig.language,
           placeholder: options.placeholder,
           disabled: options.disabled,
           readOnly: options.readOnly,
           debug: sdkConfig.debug,
           binLookup: options.binLookup,
-          coBadge: options.coBadge
+          coBadge: options.coBadge,
+          enterKeyHint: options.enterKeyHint
         });
         if (iframe) iframe.style.opacity = "1";
       } catch (error) {
@@ -959,6 +1006,9 @@ const createCardNumberElement = (apiKey, sdkConfig, options = {}, coordinatorEle
       if (newOptions.coBadge !== void 0) {
         updatePayload.coBadge = newOptions.coBadge;
       }
+      if ("enterKeyHint" in newOptions) {
+        updatePayload.enterKeyHint = newOptions.enterKeyHint;
+      }
       if (newOptions.themeMode !== void 0) {
         updatePayload.themeMode = newOptions.themeMode;
         updatePayload.theme = sdkConfig.theme;
@@ -1097,13 +1147,17 @@ const createCVVElement = (apiKey, sdkConfig, options = {}, coordinatorElementId,
           theme: sdkConfig.theme,
           darkTheme: sdkConfig.darkTheme,
           themeMode: sdkConfig.themeMode,
+          direction: sdkConfig.direction,
+          language: sdkConfig.language,
           apiKey,
+          environment: sdkConfig.environment,
           apiTimeout: sdkConfig.timeoutMs,
           apiRetries: sdkConfig.retryConfig.maxRetries,
           placeholder: options.placeholder,
           disabled: options.disabled,
           readOnly: options.readOnly,
           showToggle: options.showToggle,
+          enterKeyHint: options.enterKeyHint,
           debug: sdkConfig.debug
         });
         if (iframe) iframe.style.opacity = "1";
@@ -1160,6 +1214,11 @@ const createCVVElement = (apiKey, sdkConfig, options = {}, coordinatorElementId,
         placeholder: newOptions.placeholder,
         disabled: newOptions.disabled,
         readOnly: newOptions.readOnly,
+        // Forwarded only when the caller named it, so an explicit
+        // `enterKeyHint: undefined` clears the hint but a partial update keeps it
+        ..."enterKeyHint" in newOptions && {
+          enterKeyHint: newOptions.enterKeyHint
+        },
         // ✅ SDK auto-coordination: Pass brand info for dynamic maxlength
         cardBrand: newOptions.cardBrand,
         cvvLengths: newOptions.cvvLengths
@@ -1296,12 +1355,16 @@ const createExpiryElement = (apiKey, sdkConfig, options = {}, coordinatorElement
           theme: sdkConfig.theme,
           darkTheme: sdkConfig.darkTheme,
           themeMode: sdkConfig.themeMode,
+          direction: sdkConfig.direction,
+          language: sdkConfig.language,
           apiKey,
+          environment: sdkConfig.environment,
           apiTimeout: sdkConfig.timeoutMs,
           apiRetries: sdkConfig.retryConfig.maxRetries,
           placeholder: options.placeholder,
           disabled: options.disabled,
           readOnly: options.readOnly,
+          enterKeyHint: options.enterKeyHint,
           debug: sdkConfig.debug
         });
         if (iframe) iframe.style.opacity = "1";
@@ -1357,7 +1420,12 @@ const createExpiryElement = (apiKey, sdkConfig, options = {}, coordinatorElement
       const updatePayload = {
         placeholder: newOptions.placeholder,
         disabled: newOptions.disabled,
-        readOnly: newOptions.readOnly
+        readOnly: newOptions.readOnly,
+        // Forwarded only when the caller named it, so an explicit
+        // `enterKeyHint: undefined` clears the hint but a partial update keeps it
+        ..."enterKeyHint" in newOptions && {
+          enterKeyHint: newOptions.enterKeyHint
+        }
       };
       if (newOptions.themeMode !== void 0) {
         updatePayload.themeMode = newOptions.themeMode;
@@ -1511,7 +1579,10 @@ const createTextElement = (apiKey, sdkConfig, options = {}, coordinatorElementId
           theme: sdkConfig.theme,
           darkTheme: sdkConfig.darkTheme,
           themeMode: sdkConfig.themeMode,
+          direction: sdkConfig.direction,
+          language: sdkConfig.language,
           apiKey,
+          environment: sdkConfig.environment,
           apiTimeout: sdkConfig.timeoutMs,
           apiRetries: sdkConfig.retryConfig.maxRetries,
           placeholder: options.placeholder,
@@ -1523,6 +1594,7 @@ const createTextElement = (apiKey, sdkConfig, options = {}, coordinatorElementId
           maxLength: options.maxLength,
           password: options.password,
           inputMode: options.inputMode,
+          enterKeyHint: options.enterKeyHint,
           mask: serializedMask,
           transform: serializedTransform,
           debug: sdkConfig.debug
@@ -1585,7 +1657,12 @@ const createTextElement = (apiKey, sdkConfig, options = {}, coordinatorElementId
         required: newOptions.required,
         maxLength: newOptions.maxLength,
         password: newOptions.password,
-        inputMode: newOptions.inputMode
+        inputMode: newOptions.inputMode,
+        // Forwarded only when the caller named it, so an explicit
+        // `enterKeyHint: undefined` clears the hint but a partial update keeps it
+        ..."enterKeyHint" in newOptions && {
+          enterKeyHint: newOptions.enterKeyHint
+        }
       };
       if (newOptions.themeMode !== void 0) {
         updatePayload.themeMode = newOptions.themeMode;
@@ -1811,16 +1888,21 @@ const warnUnknownKeys = (label, obj, knownKeys, deprecatedKeys) => {
     );
   }
 };
+const VALID_ENVIRONMENTS = ["us", "eu", "test"];
 const KNOWN_SDK_KEYS = /* @__PURE__ */ new Set([
   "elementsBaseUrl",
   "whitelabelDomain",
   "apiBaseUrl",
+  "environment",
   "debug",
   "allowClipboard",
+  "allowHttpClient",
   "measurePerformance",
   "timeoutMs",
   "retryConfig",
   "themeMode",
+  "direction",
+  "language",
   "theme",
   "darkTheme",
   "sessionAuthorizationUrl"
@@ -1868,6 +1950,9 @@ const validateSDKConfig = (options = {}) => {
   if (options.allowClipboard !== void 0 && typeof options.allowClipboard !== "boolean") {
     throw ConfigurationError("allowClipboard must be a boolean");
   }
+  if (options.allowHttpClient !== void 0 && typeof options.allowHttpClient !== "boolean") {
+    throw ConfigurationError("allowHttpClient must be a boolean");
+  }
   if (options.measurePerformance !== void 0 && typeof options.measurePerformance !== "boolean") {
     throw ConfigurationError("measurePerformance must be a boolean");
   }
@@ -1894,6 +1979,20 @@ const validateSDKConfig = (options = {}) => {
   if (!["light", "dark", "auto"].includes(themeMode)) {
     throw ConfigurationError('themeMode must be "light", "dark", or "auto"');
   }
+  if (options.environment !== void 0) {
+    if (!VALID_ENVIRONMENTS.includes(options.environment)) {
+      throw ConfigurationError(
+        `environment must be ${VALID_ENVIRONMENTS.map((e) => `"${e}"`).join(", ")}`
+      );
+    }
+  }
+  const direction = options.direction ?? "ltr";
+  if (!["ltr", "rtl"].includes(direction)) {
+    throw ConfigurationError('direction must be "ltr" or "rtl"');
+  }
+  if (options.language !== void 0 && !isLanguageTag(options.language)) {
+    throw ConfigurationError("language must be a BCP 47 language tag");
+  }
   if (options.sessionAuthorizationUrl !== void 0) {
     if (typeof options.sessionAuthorizationUrl !== "string" || options.sessionAuthorizationUrl.trim() === "") {
       throw ConfigurationError("sessionAuthorizationUrl must be a non-empty string");
@@ -1928,22 +2027,27 @@ const validateSDKConfig = (options = {}) => {
       }
       throw ConfigurationError("whitelabelDomain must be a valid URL");
     }
-    const { pathname } = new URL("https://js.basistheory.com/3.0.0/elements");
+    const { pathname } = new URL("https://js.basistheory.com/3.1.0/elements");
     resolvedBaseUrl = `${domainOrigin}${pathname}`;
   }
-  const finalBaseUrl = resolvedBaseUrl || "https://js.basistheory.com/3.0.0/elements";
+  const finalBaseUrl = resolvedBaseUrl || "https://js.basistheory.com/3.1.0/elements";
   const iframeOrigin = new URL(finalBaseUrl).origin;
   return {
     iframeOrigin,
     elementsBaseUrl: finalBaseUrl,
     apiBaseUrl: options.apiBaseUrl,
     // Optional - auto-detects if not provided
+    environment: options.environment,
+    // Optional - resolves as before when unset
     debug: options.debug ?? false,
     allowClipboard: options.allowClipboard ?? false,
+    allowHttpClient: options.allowHttpClient ?? false,
     measurePerformance: options.measurePerformance ?? false,
     timeoutMs: options.timeoutMs || 3e4,
     // 30s default for slow 3G connections
     themeMode,
+    direction,
+    language: options.language,
     theme: mergeWithDefaultTheme(options.theme),
     // Light theme or only theme
     darkTheme: options.darkTheme ? mergeWithDefaultTheme(options.darkTheme) : void 0,
@@ -1957,8 +2061,31 @@ const COMMON_ELEMENT_KEYS = /* @__PURE__ */ new Set([
   "placeholder",
   "ariaLabel",
   "disabled",
-  "readOnly"
+  "readOnly",
+  "enterKeyHint"
+]);
+const VALID_ENTER_KEY_HINTS = /* @__PURE__ */ new Set([
+  "enter",
+  "done",
+  "go",
+  "next",
+  "previous",
+  "search",
+  "send"
 ]);
+const CARD_ENTER_KEY_HINT_FIELDS = /* @__PURE__ */ new Set([
+  "cardNumber",
+  "expiryDate",
+  "cvv",
+  "cvc"
+]);
+const validateEnterKeyHintValue = (value, label) => {
+  if (typeof value !== "string" || !VALID_ENTER_KEY_HINTS.has(value)) {
+    throw ConfigurationError(
+      `${label} must be one of: ${Array.from(VALID_ENTER_KEY_HINTS).join(", ")}`
+    );
+  }
+};
 const ELEMENT_TYPE_KEYS = {
   cardNumber: /* @__PURE__ */ new Set([...COMMON_ELEMENT_KEYS, "binLookup", "coBadge"]),
   cvv: /* @__PURE__ */ new Set([...COMMON_ELEMENT_KEYS, "cardBrand", "cvvLengths"]),
@@ -2021,6 +2148,23 @@ const validateElementOptions = (type, options = {}) => {
   if (options.ariaLabel !== void 0 && typeof options.ariaLabel !== "string") {
     throw ConfigurationError("ariaLabel must be a string");
   }
+  if (options.enterKeyHint !== void 0) {
+    const enterKeyHint = options.enterKeyHint;
+    if (type === "card" && typeof enterKeyHint === "object" && enterKeyHint !== null && !Array.isArray(enterKeyHint)) {
+      warnUnknownKeys(
+        "enterKeyHint",
+        enterKeyHint,
+        CARD_ENTER_KEY_HINT_FIELDS
+      );
+      Object.entries(enterKeyHint).filter(([field]) => CARD_ENTER_KEY_HINT_FIELDS.has(field)).forEach(([field, value]) => {
+        if (value !== void 0) {
+          validateEnterKeyHintValue(value, `enterKeyHint.${field}`);
+        }
+      });
+    } else {
+      validateEnterKeyHintValue(enterKeyHint, "enterKeyHint");
+    }
+  }
   if (type === "text") {
     if (options.maxLength !== void 0) {
       if (typeof options.maxLength !== "number" || options.maxLength <= 0) {
@@ -2227,21 +2371,21 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
   let cardDisplayElementFactory = null;
   const lazyCardElement = async () => {
     if (!cardElementFactory) {
-      const module = await import("./create-card-C94szxMV.js");
+      const module = await import("./create-card-CoTyU6ju.js");
       cardElementFactory = module.createCardElement;
     }
     return cardElementFactory;
   };
   const lazyCopyButtonElement = async () => {
     if (!copyButtonElementFactory) {
-      const module = await import("./create-copy-button-Z1s9ao67.js");
+      const module = await import("./create-copy-button-D8VeinHW.js");
       copyButtonElementFactory = module.createCopyButtonElement;
     }
     return copyButtonElementFactory;
   };
   const lazyCardDisplayElement = async () => {
     if (!cardDisplayElementFactory) {
-      const module = await import("./create-card-display-DsLzA_vl.js");
+      const module = await import("./create-card-display-DQmTA_8S.js");
       cardDisplayElementFactory = module.createCardDisplayElement;
     }
     return cardDisplayElementFactory;
@@ -2336,11 +2480,15 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
       apiKey,
       apiBaseUrl: config.apiBaseUrl,
       // Optional - auto-detects if not provided
+      environment: config.environment,
+      // Optional - resolves as before when unset
       apiTimeout: 3e4,
       apiRetries: 3,
       // Frozen by the coordinator on this first config; copy references are
       // refused unless it's enabled here.
       allowClipboard: config.allowClipboard,
+      // Frozen alongside allowClipboard; bt.client.* is refused unless enabled here.
+      allowHttpClient: config.allowHttpClient,
       debug: config.debug || false,
       theme: config.theme,
       darkTheme: config.darkTheme,
@@ -2794,6 +2942,61 @@ const BasisTheory = (apiKey, options = {}, queuedCommands) => {
         delete: proxyVerb("DELETE")
       };
     })(),
+    client: (() => {
+      const invokeClient = guardAsync(async (method, url, body, options2 = {}) => {
+        if (!config.allowHttpClient) {
+          throw ConfigurationError(
+            "bt.client requires allowHttpClient: true on BasisTheory() initialization. Sending card data to a third party may affect PCI scope and must be enabled deliberately.",
+            { received: config.allowHttpClient, expected: true }
+          );
+        }
+        validateDestinationRequest({ url, method, headers: options2 == null ? void 0 : options2.headers });
+        log2("client invoked", { method, hasBody: body !== void 0 });
+        if (!coordinatorClient) {
+          log2("Waiting for coordinator initialization");
+          await initializeCoordinator();
+        }
+        if (!coordinatorClient) {
+          throw CoordinatorError("Coordinator failed to initialize");
+        }
+        const resolvedBody = body !== void 0 ? resolveElementReferences(body) : void 0;
+        try {
+          const result = await coordinatorClient.sendRequest(
+            "CMD_HTTP_CLIENT",
+            {
+              method,
+              url,
+              headers: options2 == null ? void 0 : options2.headers,
+              body: resolvedBody
+            },
+            { retries: 0 }
+          );
+          log2("client successful", { method });
+          return result;
+        } catch (error) {
+          log2("client failed", { method, error: error.message });
+          const transportError = error;
+          if (transportError.code === "HTTP_CLIENT_ERROR") {
+            throw HttpClientError(
+              transportError.message.replace(/^\[HTTP_CLIENT_ERROR\] /, ""),
+              transportError.status ?? -1,
+              transportError.data,
+              transportError.headers
+            );
+          }
+          throw error;
+        }
+      });
+      const withBody = (method) => (url, body, options2) => invokeClient(method, url, body, options2 ?? {});
+      const withoutBody = (method) => (url, options2) => invokeClient(method, url, void 0, options2 ?? {});
+      return {
+        get: withoutBody("GET"),
+        post: withBody("POST"),
+        put: withBody("PUT"),
+        patch: withBody("PATCH"),
+        delete: withoutBody("DELETE")
+      };
+    })(),
     updateThemeMode: guardAsync(async (mode) => {
       log2("updateThemeMode called", {
         oldMode: currentThemeMode,
@@ -2960,8 +3163,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";
-const buildDate = "2026-08-13T19:30:19.198Z";
+const version = "3.1.0";
+const buildDate = "2026-09-21T19:33:43.220Z";
 if (typeof window !== "undefined") {
   window.__BasisTheorySDK__ = BasisTheory;
 }