@sunbay/checkout-sdk-js 0.0.2 → 0.0.3

package/dist/index.cjs

@@ -62,8 +62,9 @@ var MainFrameTransport = class {
     this.eventHandlers = /* @__PURE__ */ new Map();
     this.helloHandler = null;
     /**
-     * 握手协商出的运行时 id；未注入前为空串。出站 request 信封据此填充，
-     * main 端点仅处理 runtimeId 与自身一致的请求，空串会被静默丢弃。
+     * Runtime id negotiated during the handshake; empty string before injection. Outbound request
+     * envelopes are filled from it; the main endpoint only processes requests whose runtimeId
+     * matches its own, and an empty string is silently dropped.
      */
     this.runtimeId = "";
     this.destroyed = false;
@@ -76,9 +77,9 @@ var MainFrameTransport = class {
     window.addEventListener("message", this.messageListener);
   }
   /**
-   * 创建隐藏 0 尺寸 main iframe，append 到 document.body。
+   * Create the hidden, 0-size main iframe and append it to document.body.
    *
-   * @returns 已挂载的 iframe 元素。
+   * @returns The mounted iframe element.
    * @example
    * const iframe = transport.createHiddenIframe();
    */
@@ -100,11 +101,11 @@ var MainFrameTransport = class {
     return iframe;
   }
   /**
-   * 发送一条 request 信封，按 requestId 配对响应。
+   * Send one request envelope and pair the response by requestId.
    *
-   * @param name - 命令名。
-   * @param payload - 命令载荷（JSON 可序列化）。
-   * @returns 响应 data；失败（ok:false / 超时 / destroy）reject 一个 CheckoutError。
+   * @param name - Command name.
+   * @param payload - Command payload (JSON-serializable).
+   * @returns The response data; on failure (ok:false / timeout / destroy) rejects with a CheckoutError.
    * @example
    * const session = await transport.request('getSession', {});
    */
@@ -145,10 +146,10 @@ var MainFrameTransport = class {
     });
   }
   /**
-   * 注册事件 handler（分发 kind:'event' 信封的 payload）。
+   * Register an event handler (dispatches the payload of kind:'event' envelopes).
    *
-   * @param event - 事件名。
-   * @param handler - 回调。
+   * @param event - Event name.
+   * @param handler - Callback.
    */
   on(event, handler) {
     let set = this.eventHandlers.get(event);
@@ -159,10 +160,10 @@ var MainFrameTransport = class {
     set.add(handler);
   }
   /**
-   * 注销事件 handler。
+   * Unregister an event handler.
    *
-   * @param event - 事件名。
-   * @param handler - 先前注册的回调。
+   * @param event - Event name.
+   * @param handler - The previously registered callback.
    */
   off(event, handler) {
     const set = this.eventHandlers.get(event);
@@ -174,24 +175,26 @@ var MainFrameTransport = class {
     }
   }
   /**
-   * 注册握手（RuntimeHello）回调。hello 阶段尚无 checkoutId，单独处理。
+   * Register the handshake (RuntimeHello) callback. The hello phase has no checkoutId yet and is
+   * handled separately.
    *
-   * @param handler - 收到 hello 时调用。
+   * @param handler - Called when a hello is received.
    */
   onHello(handler) {
     this.helloHandler = handler;
   }
   /**
-   * 注入握手协商出的运行时 id。必须在发送首个 request（initialize）之前调用，
-   * 否则出站信封 runtimeId 为空串、被 main 端点静默丢弃导致请求超时。
+   * Inject the runtime id negotiated during the handshake. Must be called before sending the first
+   * request (initialize), otherwise the outbound envelope's runtimeId is an empty string, gets
+   * silently dropped by the main endpoint, and the request times out.
    *
-   * @param runtimeId - RuntimeHello 中的 runtimeId。
+   * @param runtimeId - The runtimeId from RuntimeHello.
    */
   setRuntimeId(runtimeId) {
     this.runtimeId = runtimeId;
   }
   /**
-   * 销毁：移除 iframe、清监听，未决 request 以 INSTANCE_DESTROYED reject。
+   * Destroy: remove the iframe, clear listeners, and reject pending requests with INSTANCE_DESTROYED.
    */
   destroy() {
     if (this.destroyed) {
@@ -211,7 +214,7 @@ var MainFrameTransport = class {
     }
     this.iframe = null;
   }
-  /** 按命令名解析超时时长。 */
+  /** Resolve the timeout by command name. */
   resolveTimeout(name) {
     if (name === "initialize") {
       return this.timeouts.initialize;
@@ -219,20 +222,22 @@ var MainFrameTransport = class {
     return this.timeouts.default;
   }
   /**
-   * 点对点 port relay（父窗口中继，Stripe controller 模型）。
+   * Point-to-point port relay (parent-window relay, Stripe controller model).
    *
-   * 兄弟 iframe（main 与各 Element iframe）之间拿不到彼此 window 引用，无法直接
-   * transfer MessagePort。本层（商户页，唯一同时可达两端且知其 origin 的角色）在
-   * 收到某 Element iframe 的 `element-online` 时：
-   * 1. 建 `MessageChannel`；
-   * 2. `port1` → main iframe（`relay-port`，targetOrigin=hostOrigin）；
-   * 3. `port2` → 发起的 Element iframe（即 `event.source`，targetOrigin=hostOrigin）。
+   * Sibling iframes (main and the various Element iframes) cannot obtain each other's window
+   * references, so they cannot transfer a MessagePort directly. This layer (the merchant page,
+   * the only party that can reach both ends and knows their origin) does the following when it
+   * receives an `element-online` from some Element iframe:
+   * 1. Create a `MessageChannel`;
+   * 2. `port1` → main iframe (`relay-port`, targetOrigin=hostOrigin);
+   * 3. `port2` → the originating Element iframe (i.e. `event.source`, targetOrigin=hostOrigin).
    *
-   * 两端 origin 均为 hostOrigin，targetOrigin 恒正确（跨域亦不被丢弃）。
-   * 本层只搬运**空 port**，绝不接触卡值（卡值在 port 建立后端到端传输）。
+   * Both ends' origin is hostOrigin, so targetOrigin is always correct (and not dropped across
+   * origins). This layer only carries **empty ports** and never touches card values (which are
+   * transmitted end-to-end after the port is established).
    *
-   * @param event 入站 message（origin 已校验为 hostOrigin）
-   * @returns 是否作为 element-online 处理（是则调用方应 return）
+   * @param event Inbound message (origin already verified as hostOrigin)
+   * @returns Whether it was handled as element-online (if so, the caller should return)
    */
   tryHandleElementOnline(event) {
     const data = event.data;
@@ -261,7 +266,7 @@ var MainFrameTransport = class {
     elementWin.postMessage(relayMsg, this.hostOrigin, [channel.port2]);
     return true;
   }
-  /** 处理入站 message：过滤 origin，识别 relay / hello / Envelope 并分发。 */
+  /** Handle an inbound message: filter origin, recognize relay / hello / Envelope and dispatch. */
   handleMessage(event) {
     if (this.destroyed) {
       return;
@@ -302,7 +307,7 @@ var MainFrameTransport = class {
       this.handleEvent(envelope);
     }
   }
-  /** 分发 response 到配对的未决 request。 */
+  /** Dispatch a response to the paired pending request. */
   handleResponse(envelope) {
     const entry = this.pending.get(envelope.requestId);
     if (!entry) {
@@ -316,7 +321,7 @@ var MainFrameTransport = class {
       entry.reject(envelope.error);
     }
   }
-  /** 分发 event 到注册的 handler。 */
+  /** Dispatch an event to the registered handlers. */
   handleEvent(envelope) {
     const set = this.eventHandlers.get(envelope.name);
     if (!set) {
@@ -359,17 +364,18 @@ var CheckoutElement = class _CheckoutElement {
     this.status = "created";
     this.container = null;
     this.iframe = null;
-    /** mount 期间临时订阅的事件 handler（resolve/reject 后解绑）。 */
+    /** Event handlers temporarily subscribed during mount (unbound after resolve/reject). */
     this.readyHandler = null;
     this.loadErrorHandler = null;
-    /** 仅 expressCheckout：常驻订阅的 expressAvailabilityChange handler（destroy 时解绑）。 */
+    /** expressCheckout only: the persistently subscribed expressAvailabilityChange handler (unbound on destroy). */
     this.availabilityHandler = null;
     /**
-     * iframe 自适应高度：挂载期间常驻的 window 'message' 监听器（iframe 消失/销毁时解绑）。
-     * 存引用以便 removeEventListener；null 表示未监听。
+     * iframe auto-height: the window 'message' listener that stays resident during mount (unbound
+     * when the iframe disappears/is destroyed). Keeps a reference so removeEventListener can be
+     * called; null means not listening.
      */
     this.resizeHandler = null;
-    /** 最近一次已应用的 iframe 高度（px），用于去重，避免冗余 style 写入；null 表示尚未设置。 */
+    /** The most recently applied iframe height (px), used for deduplication to avoid redundant style writes; null means not yet set. */
     this.lastHeight = null;
     this.elementId = opts.elementId;
     this.type = opts.type;
@@ -384,26 +390,28 @@ var CheckoutElement = class _CheckoutElement {
     this.installInputActions();
     this.installExpressAvailability();
   }
-  /** 当前状态（只读快照，供外部/测试观测）。 */
+  /** The current status (read-only snapshot, for external/test observation). */
   getStatus() {
     return this.status;
   }
   /**
-   * 仅 expressCheckout：返回当前各钱包可用性快照（其他类型恒为 undefined）。
+   * expressCheckout only: return the current snapshot of each wallet's availability (always
+   * undefined for other types).
    *
-   * 初值来自 elementReady 的 availableWallets，之后由 expressAvailabilityChange 更新。
+   * The initial value comes from elementReady's availableWallets, then is updated by
+   * expressAvailabilityChange.
    *
-   * @returns 可用性快照；尚未就绪或非 express 时为 undefined。
+   * @returns The availability snapshot; undefined when not yet ready or non-express.
    */
   getAvailableWallets() {
     return this.availableWallets;
   }
   /**
-   * 挂载到商户 DOM 目标：插入可见 iframe、发 createElement、等 elementReady。
+   * Mount at the merchant DOM target: insert a visible iframe, send createElement, await elementReady.
    *
-   * @param selectorOrEl - CSS 选择器或 HTMLElement 容器；容器须唯一且为空。
-   * @returns elementReady 后 resolve；失败移除节点并 reject（loadError / INVALID_OPTIONS）。
-   * @throws 已销毁时抛 INSTANCE_DESTROYED。
+   * @param selectorOrEl - A CSS selector or an HTMLElement container; the container must be unique and empty.
+   * @returns Resolves after elementReady; on failure removes the node and rejects (loadError / INVALID_OPTIONS).
+   * @throws INSTANCE_DESTROYED when already destroyed.
    * @example
    * await element.mount('#card-field');
    */
@@ -442,6 +450,7 @@ var CheckoutElement = class _CheckoutElement {
     iframe.style.border = "0";
     iframe.style.width = "100%";
     iframe.style.display = "block";
+    iframe.setAttribute("scrolling", "no");
     container.appendChild(iframe);
     this.iframe = iframe;
     this.installResizeListener();
@@ -501,10 +510,10 @@ var CheckoutElement = class _CheckoutElement {
     });
   }
   /**
-   * 卸载：发 destroyElement、移除 iframe；幂等；保留句柄与配置。
+   * Unmount: send destroyElement, remove the iframe; idempotent; keeps the handle and configuration.
    *
-   * @returns 完成后 resolve（未挂载时直接 resolve）。
-   * @throws 已销毁时抛 INSTANCE_DESTROYED。
+   * @returns Resolves on completion (resolves directly when not mounted).
+   * @throws INSTANCE_DESTROYED when already destroyed.
    */
   async unmount() {
     this.assertAlive();
@@ -520,7 +529,7 @@ var CheckoutElement = class _CheckoutElement {
     }
   }
   /**
-   * 销毁句柄：幂等；移除 iframe；此后非 destroy/off 调用抛 INSTANCE_DESTROYED。
+   * Destroy the handle: idempotent; remove the iframe; afterwards any non-destroy/off call throws INSTANCE_DESTROYED.
    */
   destroy() {
     if (this.status === "destroyed") {
@@ -544,11 +553,11 @@ var CheckoutElement = class _CheckoutElement {
     this.onDestroy?.(this.elementId);
   }
   /**
-   * 更新 Element 配置：发 updateElement；非法字段由托管侧整次拒绝。
+   * Update the Element configuration: send updateElement; illegal fields are rejected wholesale by the hosted side.
    *
-   * @param patch - 配置增量。
-   * @returns 成功写回本地 options 后 resolve。
-   * @throws 已销毁时抛 INSTANCE_DESTROYED。
+   * @param patch - Configuration delta.
+   * @returns Resolves after successfully writing back the local options.
+   * @throws INSTANCE_DESTROYED when already destroyed.
    */
   async update(patch) {
     this.assertAlive();
@@ -562,26 +571,26 @@ var CheckoutElement = class _CheckoutElement {
     }
   }
   /**
-   * 注册事件 handler（透传到 transport，按事件名分发）。
+   * Register an event handler (passed through to the transport, dispatched by event name).
    *
-   * @param event - 事件名。
-   * @param handler - 回调。
-   * @throws 已销毁时抛 INSTANCE_DESTROYED。
+   * @param event - Event name.
+   * @param handler - Callback.
+   * @throws INSTANCE_DESTROYED when already destroyed.
    */
   on(event, handler) {
     this.assertAlive();
     this.transport.on(event, handler);
   }
   /**
-   * 注销事件 handler（销毁后仍可安全调用）。
+   * Unregister an event handler (still safe to call after destruction).
    *
-   * @param event - 事件名。
-   * @param handler - 先前注册的回调。
+   * @param event - Event name.
+   * @param handler - The previously registered callback.
    */
   off(event, handler) {
     this.transport.off(event, handler);
   }
-  /** 已挂载后安装输入类动作方法（由构造后自动调用）。 */
+  /** Install input-class action methods (automatically called after construction). */
   installInputActions() {
     if (!INPUT_TYPES.includes(this.type)) {
       return;
@@ -591,10 +600,10 @@ var CheckoutElement = class _CheckoutElement {
     this.clear = () => this.sendAction("clear");
   }
   /**
-   * 仅 expressCheckout：常驻订阅 expressAvailabilityChange，更新本地可用性快照。
+   * expressCheckout only: persistently subscribe to expressAvailabilityChange and update the local availability snapshot.
    *
-   * 该事件载荷不含 elementId；express 为单例（由 CheckoutInstance 保证），
-   * 故无需按 elementId 过滤。非 express 类型不订阅。
+   * This event payload has no elementId; express is a singleton (guaranteed by CheckoutInstance),
+   * so there is no need to filter by elementId. Non-express types do not subscribe.
    */
   installExpressAvailability() {
     if (this.type !== "expressCheckout") {
@@ -612,18 +621,18 @@ var CheckoutElement = class _CheckoutElement {
     this.availabilityHandler = handler;
     this.transport.on("expressAvailabilityChange", handler);
   }
-  /** 发送一条输入类动作命令（销毁后同步抛 INSTANCE_DESTROYED）。 */
+  /** Send one input-class action command (synchronously throws INSTANCE_DESTROYED after destruction). */
   sendAction(name) {
     this.assertAlive();
     return this.transport.request(name, { elementId: this.elementId }).then(() => void 0);
   }
-  /** 若已销毁则抛 INSTANCE_DESTROYED。 */
+  /** Throw INSTANCE_DESTROYED if already destroyed. */
   assertAlive() {
     if (this.status === "destroyed") {
       throw makeError2(import_checkout_sdk_protocol3.ErrorCode.INSTANCE_DESTROYED, "Checkout instance has been destroyed", this.elementId);
     }
   }
-  /** 解析挂载容器（选择器须唯一命中一个元素）。 */
+  /** Resolve the mount container (the selector must uniquely match a single element). */
   resolveContainer(selectorOrEl) {
     if (typeof selectorOrEl !== "string") {
       return selectorOrEl;
@@ -636,26 +645,34 @@ var CheckoutElement = class _CheckoutElement {
     return node instanceof HTMLElement ? node : null;
   }
   /**
-   * 解析 iframe src：拆分字段走 /sdk/field/，其余走 /sdk/element/，带 checkoutId 与 elementId；
-   * 若提供了初始 colorScheme，则追加 `&colorScheme=<值>`（首帧无闪）；
-   * 若初始 appearance 含 variables 或 rules，则追加
-   * `&appearance=<encodeURIComponent(JSON.stringify(appearance))>`（首帧即生效，无闪）。
-   * 仅含 colorScheme（无 variables/rules）的 appearance 不拼接，避免空外观串。
-   * 对 expressCheckout，另追加钱包开关 / 每钱包 buttonType / 全局 buttonHeight
-   * （见 {@link resolveExpressQuery}）。
+   * Resolve the iframe src: split fields go to /sdk/field/, the rest to /sdk/element/, with
+   * checkoutId and elementId; if an initial colorScheme is provided, append `&colorScheme=<value>`
+   * (no flash on the first frame); if the initial appearance contains variables or rules, append
+   * `&appearance=<encodeURIComponent(JSON.stringify(appearance))>` (takes effect on the first
+   * frame, no flash). An appearance containing only colorScheme (no variables/rules) is not
+   * appended, to avoid an empty appearance string. For expressCheckout, additionally append the
+   * wallet toggles / per-wallet buttonType / global buttonHeight (see {@link resolveExpressQuery}).
    *
-   * elementId 随 src 下发，供托管 child 在 iframe-resize 消息中原样回传，父窗口据此在
-   * 同页多个 iframe 间按句柄分发高度。
+   * elementId is sent with the src so the hosted child echoes it verbatim in iframe-resize
+   * messages, letting the parent window dispatch the height per handle among multiple iframes on
+   * the same page.
    */
   resolveSrc() {
     const segment = FIELD_TYPES.includes(this.type) ? "field" : "element";
     let query = `?checkoutId=${encodeURIComponent(this.checkoutId)}`;
     query += `&elementId=${encodeURIComponent(this.elementId)}`;
+    if (this.type === "address") {
+      const mode = this.options?.mode;
+      if (mode) {
+        query += `&mode=${encodeURIComponent(mode)}`;
+      }
+    }
     if (this.colorScheme) {
       query += `&colorScheme=${encodeURIComponent(this.colorScheme)}`;
     }
-    if (this.appearance && (this.appearance.variables || this.appearance.rules)) {
-      query += `&appearance=${encodeURIComponent(JSON.stringify(this.appearance))}`;
+    const effectiveAppearance = this.perElementAppearance() ?? this.appearance;
+    if (effectiveAppearance && (effectiveAppearance.variables || effectiveAppearance.rules)) {
+      query += `&appearance=${encodeURIComponent(JSON.stringify(effectiveAppearance))}`;
     }
     if (this.type === "expressCheckout") {
       query += this.resolveExpressQuery();
@@ -663,16 +680,26 @@ var CheckoutElement = class _CheckoutElement {
     return `${this.hostOrigin}/sdk/${segment}/${this.type}${query}`;
   }
   /**
-   * 构造 expressCheckout 专属 query 片段（仅 expressCheckout 调用）：
-   * - 钱包显式置为 `false` → `&applePay=false` / `&googlePay=false`（强制隐藏，保持
-   *   既有开关语义；`true` / 缺省 → 自动，不拼开关）；
-   * - 钱包以对象形态配置且含 `buttonType` → `&applePayButtonType=<v>` /
-   *   `&googlePayButtonType=<v>`（布尔开关 / 缺省 → 不拼）；
-   * - 全局 `buttonHeight`（有限数）→ `&buttonHeight=<n>`。
+   * Extract a per-element appearance (from the Element's own options, i.e. the second
+   * argument of create(type, options)). Returns undefined when absent. Used so per-element
+   * customization (e.g. CardFieldElementOptions.appearance) is honored on the first frame.
+   */
+  perElementAppearance() {
+    const opts = this.options;
+    return opts?.appearance;
+  }
+  /**
+   * Build the expressCheckout-specific query fragment (only called for expressCheckout):
+   * - a wallet explicitly set to `false` → `&applePay=false` / `&googlePay=false` (force hidden,
+   *   preserving the existing toggle semantics; `true` / absent → automatic, no toggle appended);
+   * - a wallet configured in object form containing `buttonType` → `&applePayButtonType=<v>` /
+   *   `&googlePayButtonType=<v>` (boolean toggle / absent → not appended);
+   * - global `buttonHeight` (a finite number) → `&buttonHeight=<n>`.
    *
-   * 仅在有值时拼接；不拼空串。本片段不触碰卡值，仅承载展示配置。
+   * Appended only when there is a value; empty strings are not appended. This fragment never
+   * touches card values and only carries display configuration.
    *
-   * @returns 以 `&` 起始的 query 片段（无可拼项时返回空串）。
+   * @returns A query fragment starting with `&` (returns an empty string when nothing is appendable).
    */
   resolveExpressQuery() {
     const options = this.options;
@@ -700,13 +727,14 @@ var CheckoutElement = class _CheckoutElement {
     return query;
   }
   /**
-   * 安装 iframe 自适应高度监听：订阅 window 'message'，仅采信来自本 iframe
-   * `contentWindow` 且 origin === hostOrigin 的合法 {@link IframeResizeMessage}，
-   * 且 elementId 与本句柄匹配时，将外层 iframe 高度调整为内容真实高度（宽度保持 100%）。
+   * Install the iframe auto-height listener: subscribe to window 'message', only trust a valid
+   * {@link IframeResizeMessage} from this iframe's `contentWindow` with origin === hostOrigin, and
+   * when the elementId matches this handle, adjust the outer iframe's height to the content's real
+   * height (width stays 100%).
    *
-   * 安全：先校验 `event.source === iframe.contentWindow`（关键来源校验），
-   * 再校验 `event.origin === hostOrigin`（更严格的同源校验），防跨源伪造。
-   * 高度去重：与上次相同则跳过，避免冗余 style 写入。
+   * Security: first verify `event.source === iframe.contentWindow` (the key source check), then
+   * verify `event.origin === hostOrigin` (a stricter same-origin check), to prevent cross-origin forgery.
+   * Height deduplication: skip if identical to the last one, to avoid redundant style writes.
    */
   installResizeListener() {
     const handler = (event) => {
@@ -735,7 +763,7 @@ var CheckoutElement = class _CheckoutElement {
     this.resizeHandler = handler;
     window.addEventListener("message", handler);
   }
-  /** 解绑 iframe 自适应高度监听并重置去重状态（幂等）。 */
+  /** Unbind the iframe auto-height listener and reset the deduplication state (idempotent). */
   teardownResizeListener() {
     if (this.resizeHandler) {
       window.removeEventListener("message", this.resizeHandler);
@@ -743,7 +771,7 @@ var CheckoutElement = class _CheckoutElement {
     }
     this.lastHeight = null;
   }
-  /** 移除 iframe DOM 节点（若存在），并解绑自适应高度监听。 */
+  /** Remove the iframe DOM node (if present) and unbind the auto-height listener. */
   removeIframe() {
     this.teardownResizeListener();
     if (this.iframe && this.iframe.parentNode) {
@@ -751,7 +779,7 @@ var CheckoutElement = class _CheckoutElement {
     }
     this.iframe = null;
   }
-  /** 工厂：等价于 `new CheckoutElement(opts)`（供 CheckoutInstance 统一入口）。 */
+  /** Factory: equivalent to `new CheckoutElement(opts)` (a unified entry for CheckoutInstance). */
   static create(opts) {
     return new _CheckoutElement(opts);
   }
@@ -774,14 +802,16 @@ function makeError3(code, message, category = "configuration") {
 }
 var CheckoutInstance = class {
   constructor(opts) {
-    /** 已创建的 Element（按 elementId 索引）。 */
+    /** Created Elements (indexed by elementId). */
     /**
-     * 互斥注册表的**单一数据源**：elementId → 已创建的 CheckoutElement。
-     * 互斥判定由本 Map 实时推导（见 {@link assertNoConflict}），元素 `destroy()` 经
-     * {@link releaseElement} 从本 Map 移除以释放名额（允许销毁后重建同类互斥 Element）。
+     * The **single source of truth** for the mutual-exclusion registry: elementId → the created
+     * CheckoutElement. Mutual-exclusion decisions are derived live from this Map (see
+     * {@link assertNoConflict}); an element's `destroy()` removes itself from this Map via
+     * {@link releaseElement} to free the slot (allowing a mutually-exclusive Element of the same
+     * kind to be recreated after destruction).
      */
     this.elements = /* @__PURE__ */ new Map();
-    /** 当前未决 confirm（同一时刻至多一个）。 */
+    /** The current pending confirm (at most one at a time). */
     this.pendingConfirm = null;
     this.destroyed = false;
     this.checkoutId = opts.checkoutId;
@@ -797,17 +827,17 @@ var CheckoutInstance = class {
     this.transport.on("paymentResult", this.paymentResultHandler);
   }
   /**
-   * 创建一个 Element 句柄（不自动挂载；互斥冲突抛 ELEMENT_CONFLICT）。
+   * Create an Element handle (not auto-mounted; a mutual-exclusion conflict throws ELEMENT_CONFLICT).
    *
-   * 互斥规则（spec 6）：
-   * - 聚合 `card` 与任一拆分字段（cardNumber/cardExpiry/cardCvc）互斥。
-   * - 同 `mode`（billing/shipping）的 address 不可重复。
-   * - `expressCheckout` 单例。
+   * Mutual-exclusion rules (spec 6):
+   * - The combined `card` and any split field (cardNumber/cardExpiry/cardCvc) are mutually exclusive.
+   * - An address with the same `mode` (billing/shipping) cannot be duplicated.
+   * - `expressCheckout` is a singleton.
    *
-   * @param type - Element 类型。
-   * @param options - 初始 Element 配置。
-   * @returns 新建的 CheckoutElement。
-   * @throws 已销毁时抛 INSTANCE_DESTROYED；互斥冲突抛 ELEMENT_CONFLICT。
+   * @param type - Element type.
+   * @param options - Initial Element configuration.
+   * @returns The newly created CheckoutElement.
+   * @throws INSTANCE_DESTROYED when already destroyed; ELEMENT_CONFLICT on a mutual-exclusion conflict.
    */
   create(type, options) {
     this.assertAlive();
@@ -829,12 +859,13 @@ var CheckoutInstance = class {
     return element;
   }
   /**
-   * 发起支付确认。生成 operationId，发 confirm 命令拿 accepted，返回的 Promise
-   * 由后续同 operationId 的 paymentResult 事件兑现。进行中再次调用 → CHECKOUT_BUSY。
+   * Initiate a payment confirmation. Generates an operationId, sends the confirm command to obtain
+   * accepted, and the returned Promise is fulfilled by a later paymentResult event with the same
+   * operationId. Calling again while in progress → CHECKOUT_BUSY.
    *
-   * @param opts - 账单/配送地址、姓名、邮箱、returnUrl 等可选参数。
-   * @returns 支付终态结果 PaymentOutcome。
-   * @throws 已销毁时 reject INSTANCE_DESTROYED；进行中 reject CHECKOUT_BUSY。
+   * @param opts - Optional parameters such as billing/shipping address, name, email, returnUrl.
+   * @returns The terminal PaymentOutcome.
+   * @throws rejects INSTANCE_DESTROYED when destroyed; rejects CHECKOUT_BUSY when in progress.
    */
   confirm(opts) {
     if (this.destroyed) {
@@ -860,10 +891,10 @@ var CheckoutInstance = class {
     });
   }
   /**
-   * 获取最新会话视图（透传 getSession 命令并写回本地快照）。
+   * Get the latest session view (passes through the getSession command and writes back the local snapshot).
    *
-   * @returns 最新 PublicSessionView。
-   * @throws 已销毁时 reject INSTANCE_DESTROYED。
+   * @returns The latest PublicSessionView.
+   * @throws rejects INSTANCE_DESTROYED when destroyed.
    */
   async getSession() {
     this.assertAlive();
@@ -872,10 +903,10 @@ var CheckoutInstance = class {
     return resp;
   }
   /**
-   * 刷新会话（透传 refresh 命令并写回本地快照）。
+   * Refresh the session (passes through the refresh command and writes back the local snapshot).
    *
-   * @returns 刷新后的 PublicSessionView。
-   * @throws 已销毁时 reject INSTANCE_DESTROYED。
+   * @returns The refreshed PublicSessionView.
+   * @throws rejects INSTANCE_DESTROYED when destroyed.
    */
   async refresh() {
     this.assertAlive();
@@ -884,20 +915,20 @@ var CheckoutInstance = class {
     return resp;
   }
   /**
-   * 查询支付状态（原样返回 TxnStatus，不转义）。
+   * Query the payment status (returns TxnStatus as-is, no transformation).
    *
-   * @returns txnStatus（可能含 txnId）。
-   * @throws 已销毁时 reject INSTANCE_DESTROYED。
+   * @returns txnStatus (may include txnId).
+   * @throws rejects INSTANCE_DESTROYED when destroyed.
    */
   async getPaymentStatus() {
     this.assertAlive();
     return await this.transport.request("getPaymentStatus", {});
   }
   /**
-   * 更新结账外观/语言（不改会话或金额）。
+   * Update the checkout appearance/locale (does not change the session or the amount).
    *
-   * @param patch - locale / appearance 增量。
-   * @throws 已销毁时 reject INSTANCE_DESTROYED。
+   * @param patch - locale / appearance delta.
+   * @throws rejects INSTANCE_DESTROYED when destroyed.
    */
   async updateCheckout(patch) {
     this.assertAlive();
@@ -905,29 +936,30 @@ var CheckoutInstance = class {
     await this.transport.request("updateCheckout", payload);
   }
   /**
-   * 注册 Checkout 级事件 handler（透传 transport）。
+   * Register a Checkout-level event handler (passes through the transport).
    *
-   * @param event - 事件名。
-   * @param handler - 回调。
-   * @throws 已销毁时抛 INSTANCE_DESTROYED。
+   * @param event - Event name.
+   * @param handler - Callback.
+   * @throws INSTANCE_DESTROYED when destroyed.
    */
   on(event, handler) {
     this.assertAlive();
     this.transport.on(event, handler);
   }
   /**
-   * 注销事件 handler（销毁后仍可安全调用）。
+   * Unregister an event handler (safe to call after destruction).
    *
-   * @param event - 事件名。
-   * @param handler - 先前注册的回调。
+   * @param event - Event name.
+   * @param handler - The previously registered callback.
    */
   off(event, handler) {
     this.transport.off(event, handler);
   }
   /**
-   * 销毁实例：幂等。释放全部 Element、解绑 paymentResult 监听、以
-   * INSTANCE_DESTROYED reject 未决 confirm、发 destroy 命令并销毁 transport。
-   * 此后迟到的 paymentResult 一律忽略，不改写已结束的 Promise。
+   * Destroy the instance: idempotent. Releases all Elements, unbinds the paymentResult listener,
+   * rejects the pending confirm with INSTANCE_DESTROYED, sends the destroy command and destroys
+   * the transport. Any late paymentResult afterwards is ignored and does not overwrite an already
+   * settled Promise.
    */
   destroy() {
     if (this.destroyed) {
@@ -948,13 +980,13 @@ var CheckoutInstance = class {
     void Promise.resolve(this.transport.request("destroy", {})).catch(() => void 0);
     this.transport.destroy();
   }
-  /** 若已销毁则抛 INSTANCE_DESTROYED。 */
+  /** Throw INSTANCE_DESTROYED if already destroyed. */
   assertAlive() {
     if (this.destroyed) {
       throw makeError3(import_checkout_sdk_protocol4.ErrorCode.INSTANCE_DESTROYED, "Checkout instance has been destroyed", "runtime");
     }
   }
-  /** 互斥检查：冲突时抛 ELEMENT_CONFLICT（由 elements Map 实时推导，不改变注册表）。 */
+  /** Mutual-exclusion check: throws ELEMENT_CONFLICT on conflict (derived live from the elements Map, does not mutate the registry). */
   assertNoConflict(type, options) {
     const existing = [...this.elements.values()];
     const has = (t) => existing.some((e) => e.type === t);
@@ -1004,9 +1036,10 @@ var CheckoutInstance = class {
     }
   }
   /**
-   * 元素 `destroy()` 回调：从互斥注册表（elements Map）移除该 elementId，释放名额。
-   * 幂等；实例整体 destroy 时（已置 destroyed）走统一 `elements.clear()` 路径，此处 no-op，
-   * 避免遍历 elements 调 element.destroy() 时的并发修改。
+   * Element `destroy()` callback: remove this elementId from the mutual-exclusion registry (the
+   * elements Map) to free the slot. Idempotent; when the whole instance is destroyed (destroyed
+   * already set) it goes through the unified `elements.clear()` path, so this is a no-op here,
+   * avoiding concurrent modification while iterating elements to call element.destroy().
    */
   releaseElement(elementId) {
     if (this.destroyed) {
@@ -1014,7 +1047,7 @@ var CheckoutInstance = class {
     }
     this.elements.delete(elementId);
   }
-  /** 处理 paymentResult 事件：按 operationId 兑现未决 confirm；迟到/不匹配忽略。 */
+  /** Handle the paymentResult event: fulfill the pending confirm by operationId; late/mismatched ones are ignored. */
   handlePaymentResult(payload) {
     if (this.destroyed) {
       return;
@@ -1041,9 +1074,10 @@ var CheckoutInstance = class {
 // src/config/env.ts
 var HOST_ORIGINS = {
   dev: "https://checkout.sunbay-dev.com",
+  test: "https://checkout.sunbay-uat.us",
   prod: "https://checkout.sunbay.us"
 };
-function resolveHostOrigin(env = "dev", override) {
+function resolveHostOrigin(env = "prod", override) {
   if (override) {
     return override;
   }
@@ -1137,7 +1171,7 @@ if (typeof window !== "undefined") {
   const w = window;
   w.SunbayCheckout = { ...w.SunbayCheckout ?? {}, createCheckout };
 }
-var version = true ? "0.0.2" : "0.0.0";
+var version = true ? "0.0.3" : "0.0.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CheckoutElement,