@sunbay/checkout-sdk-js 0.0.2 → 0.0.3

package/dist/index.d.ts

@@ -2,249 +2,273 @@ import { ElementType, CommandName, EventName, ElementOptions, Appearance, Elemen
 export { AddressElementOptions, AddressInfo, Appearance, CardElementOptions, CardFieldElementOptions, CheckoutError, CheckoutErrorCategory, ElementOptions, ElementStatus, ElementType, ErrorCode, ErrorCodeValue, ExpressCheckoutElementOptions, PaymentMethod, PaymentMethodFilter, PaymentOutcome, PublicPaymentMethod, PublicProductLine, PublicSessionView, TxnStatus } from '@sunbay/checkout-sdk-protocol';
 
 /**
- * CheckoutElement —— 商户侧 Element 句柄（spec 6）。
+ * CheckoutElement — the merchant-side Element handle (spec 6).
  *
- * 职责：
- * - 由 `CheckoutInstance.create` 构造（单测时以 mock transport + 构造参注入）。
- * - 在商户 DOM 目标挂载**可见** iframe，并通过 transport 转发 Element 命令。
- * - 维护状态机 `created → loading → ready → destroyed`（`loadError` 为旁支）。
- * - 订阅 transport 的 `elementReady` / `loadError` 事件，按**自身 elementId** 过滤，
- *   驱动 `mount()` 的 resolve / reject。
+ * Responsibilities:
+ * - Constructed by `CheckoutInstance.create` (in unit tests, injected via a mock transport +
+ *   constructor args).
+ * - Mount a **visible** iframe at the merchant DOM target and forward Element commands through the
+ *   transport.
+ * - Maintain the state machine `created → loading → ready → destroyed` (with `loadError` as a side branch).
+ * - Subscribe to the transport's `elementReady` / `loadError` events, filter by **its own elementId**,
+ *   and drive the resolve / reject of `mount()`.
  *
- * 安全约束（AGENTS/spec）：本层只做 DOM 挂载与协议命令转发，**绝不触碰卡值**。
- * 卡数据仅存在于托管 iframe 内，不经由本句柄或 transport 传输。
+ * Security constraint (AGENTS/spec): this layer only does DOM mounting and protocol command
+ * forwarding and **never touches card values**. Card data exists only inside the hosted iframe and
+ * is never transmitted via this handle or the transport.
  */
 
 /**
- * transport 依赖的最小接口（由 MainFrameTransport 满足）。
+ * The minimal interface the transport depends on (satisfied by MainFrameTransport).
  *
- * 仅声明 Element 句柄需要的方法，便于单测注入 mock。
+ * Only declares the methods the Element handle needs, to make mock injection in unit tests easy.
  */
 interface ElementTransport {
     request(name: CommandName, payload: unknown): Promise<unknown>;
     on(event: EventName, handler: (payload: unknown) => void): void;
     off(event: EventName, handler: (payload: unknown) => void): void;
 }
-/** CheckoutElement 构造参数（由 CheckoutInstance.create 组装）。 */
+/** CheckoutElement constructor parameters (assembled by CheckoutInstance.create). */
 interface CheckoutElementOptions {
-    /** Element 唯一 id（由实例生成，用于命令/事件配对）。 */
+    /** Unique Element id (generated by the instance, used to pair commands/events). */
     elementId: string;
-    /** Element 类型（决定 iframe 路径与可用动作）。 */
+    /** Element type (determines the iframe path and available actions). */
     type: ElementType;
-    /** 托管页面 origin（不带尾部斜杠）。 */
+    /** Hosted page origin (without a trailing slash). */
     hostOrigin: string;
     /**
-     * 当前 checkout 会话 id。随 iframe src 以 `?checkoutId=` 下发，供托管字段/element
-     * iframe 加入正确的同源信令频道（`sunbay-checkout:<checkoutId>`）与 main 配对；
-     * 缺失会导致字段频道名不匹配、永不就绪。
+     * The current checkout session id. Sent with the iframe src as `?checkoutId=`, so that hosted
+     * fields/element iframes join the correct same-origin signaling channel
+     * (`sunbay-checkout:<checkoutId>`) and pair with main; missing it causes the field channel name
+     * to mismatch and never become ready.
      */
     checkoutId: string;
-    /** 传输层。 */
+    /** The transport layer. */
     transport: ElementTransport;
-    /** 初始 Element 配置（随 createElement 下发）。 */
+    /** Initial Element configuration (sent with createElement). */
     initialOptions?: ElementOptions;
     /**
-     * 句柄销毁回调（由 CheckoutInstance 注入）。`destroy()` 成功销毁时以本 elementId 调用，
-     * 使实例从互斥注册表（elements Map）移除自身，从而允许销毁后重建同类互斥 Element
-     * （如切换 expressCheckout 的 buttonType/buttonHeight 需重建 iframe）。`unmount()` 不调用
-     * （保留句柄、仍占名额、可 remount）。
+     * Handle destruction callback (injected by CheckoutInstance). Called with this elementId when
+     * `destroy()` successfully destroys the handle, so the instance removes itself from the
+     * mutual-exclusion registry (elements Map), thereby allowing a mutually-exclusive Element of the
+     * same kind to be recreated after destruction (e.g. switching expressCheckout's
+     * buttonType/buttonHeight requires recreating the iframe). Not called by `unmount()` (which
+     * keeps the handle, still occupies the slot, and can remount).
      */
     onDestroy?: (elementId: string) => void;
     /**
-     * 初始配色方案（来自 createCheckout 的 appearance.colorScheme）。
-     * 仅当提供时拼进 iframe src 的 `&colorScheme=<值>`，使托管 iframe 在首帧即按该
-     * 配色渲染（无闪）。缺省时不拼接，由托管侧按默认（light）处理。运行时切换走
-     * updateCheckout 命令，不走此处。
+     * Initial color scheme (from createCheckout's appearance.colorScheme).
+     * Only when provided is it appended to the iframe src's `&colorScheme=<value>`, so the hosted
+     * iframe renders with that scheme on the first frame (no flash). When absent it is not appended
+     * and the hosted side handles the default (light). Runtime switching goes through the
+     * updateCheckout command, not here.
      */
     colorScheme?: 'light' | 'dark' | 'auto';
     /**
-     * 初始外观定制（来自 createCheckout 的 appearance）。
-     * 仅当含 `variables` 或 `rules` 时序列化进 iframe src 的
-     * `&appearance=<encodeURIComponent(JSON)>`，使托管 iframe 在首帧即按该外观渲染（无闪）。
-     * 仅含 `colorScheme`（无 variables/rules）时不拼接，避免空外观字符串；colorScheme 走独立
-     * `&colorScheme=`。运行时切换走 updateCheckout 命令，不走此处。
+     * Initial appearance customization (from createCheckout's appearance).
+     * Only when it contains `variables` or `rules` is it serialized into the iframe src's
+     * `&appearance=<encodeURIComponent(JSON)>`, so the hosted iframe renders with that appearance on
+     * the first frame (no flash). When it contains only `colorScheme` (no variables/rules) it is not
+     * appended, to avoid an empty appearance string; colorScheme goes via the separate
+     * `&colorScheme=`. Runtime switching goes through the updateCheckout command, not here.
      */
     appearance?: Appearance;
 }
 declare class CheckoutElement {
-    /** Element 唯一 id。 */
+    /** Unique Element id. */
     readonly elementId: string;
-    /** Element 类型。 */
+    /** Element type. */
     readonly type: ElementType;
-    /** 地址 Element 的 mode（billing/shipping；仅 address 有意义），供实例按 mode 判互斥。 */
+    /** The address Element's mode (billing/shipping; only meaningful for address), used by the instance to judge mutual exclusion by mode. */
     readonly mode: string | undefined;
     private readonly hostOrigin;
     private readonly checkoutId;
     private readonly transport;
     private options;
-    /** 初始配色方案（拼进 iframe src；缺省不拼）。 */
+    /** Initial color scheme (appended to the iframe src; not appended when absent). */
     private readonly colorScheme;
-    /** 初始外观定制（含 variables/rules 时拼进 iframe src；缺省或仅 colorScheme 不拼）。 */
+    /** Initial appearance customization (appended to the iframe src when it contains variables/rules; not appended when absent or colorScheme-only). */
     private readonly appearance;
-    /** 销毁回调（实例注入）：destroy() 末尾调用，使实例从互斥注册表移除自身以释放名额。 */
+    /** Destruction callback (injected by the instance): called at the end of destroy() so the instance removes itself from the mutual-exclusion registry to free the slot. */
     private readonly onDestroy;
     private status;
     private container;
     private iframe;
-    /** mount 期间临时订阅的事件 handler（resolve/reject 后解绑）。 */
+    /** Event handlers temporarily subscribed during mount (unbound after resolve/reject). */
     private readyHandler;
     private loadErrorHandler;
     /**
-     * 仅 expressCheckout：各钱包可用性快照。
-     * 初次来自 elementReady.availableWallets，之后随 expressAvailabilityChange 更新。
+     * expressCheckout only: a snapshot of each wallet's availability.
+     * Initially from elementReady.availableWallets, then updated by expressAvailabilityChange.
      */
     private availableWallets;
-    /** 仅 expressCheckout：常驻订阅的 expressAvailabilityChange handler（destroy 时解绑）。 */
+    /** expressCheckout only: the persistently subscribed expressAvailabilityChange handler (unbound on destroy). */
     private availabilityHandler;
     /**
-     * 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.
      */
     private resizeHandler;
-    /** 最近一次已应用的 iframe 高度（px），用于去重，避免冗余 style 写入；null 表示尚未设置。 */
+    /** The most recently applied iframe height (px), used for deduplication to avoid redundant style writes; null means not yet set. */
     private lastHeight;
     constructor(opts: CheckoutElementOptions);
-    /** 当前状态（只读快照，供外部/测试观测）。 */
+    /** The current status (read-only snapshot, for external/test observation). */
     getStatus(): ElementStatus;
     /**
-     * 仅 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(): AvailableWallets | undefined;
     /**
-     * 挂载到商户 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');
      */
     mount(selectorOrEl: string | HTMLElement): Promise<void>;
     /**
-     * 卸载：发 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.
      */
     unmount(): Promise<void>;
     /**
-     * 销毁句柄：幂等；移除 iframe；此后非 destroy/off 调用抛 INSTANCE_DESTROYED。
+     * Destroy the handle: idempotent; remove the iframe; afterwards any non-destroy/off call throws INSTANCE_DESTROYED.
      */
     destroy(): void;
     /**
-     * 更新 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.
      */
     update(patch: Partial<ElementOptions>): Promise<void>;
     /**
-     * 注册事件 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: EventName, handler: (payload: unknown) => void): void;
     /**
-     * 注销事件 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: EventName, handler: (payload: unknown) => void): void;
-    /** 聚焦（仅输入类，expressCheckout 不提供）。 */
+    /** Focus (input classes only, not provided by expressCheckout). */
     focus?: () => Promise<void>;
-    /** 失焦（仅输入类，expressCheckout 不提供）。 */
+    /** Blur (input classes only, not provided by expressCheckout). */
     blur?: () => Promise<void>;
-    /** 清空（仅输入类，expressCheckout 不提供）。 */
+    /** Clear (input classes only, not provided by expressCheckout). */
     clear?: () => Promise<void>;
-    /** 已挂载后安装输入类动作方法（由构造后自动调用）。 */
+    /** Install input-class action methods (automatically called after construction). */
     private installInputActions;
     /**
-     * 仅 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.
      */
     private installExpressAvailability;
-    /** 发送一条输入类动作命令（销毁后同步抛 INSTANCE_DESTROYED）。 */
+    /** Send one input-class action command (synchronously throws INSTANCE_DESTROYED after destruction). */
     private sendAction;
-    /** 若已销毁则抛 INSTANCE_DESTROYED。 */
+    /** Throw INSTANCE_DESTROYED if already destroyed. */
     private assertAlive;
-    /** 解析挂载容器（选择器须唯一命中一个元素）。 */
+    /** Resolve the mount container (the selector must uniquely match a single element). */
     private resolveContainer;
     /**
-     * 解析 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.
      */
     private resolveSrc;
     /**
-     * 构造 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.
+     */
+    private perElementAppearance;
+    /**
+     * 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).
      */
     private resolveExpressQuery;
     /**
-     * 安装 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.
      */
     private installResizeListener;
-    /** 解绑 iframe 自适应高度监听并重置去重状态（幂等）。 */
+    /** Unbind the iframe auto-height listener and reset the deduplication state (idempotent). */
     private teardownResizeListener;
-    /** 移除 iframe DOM 节点（若存在），并解绑自适应高度监听。 */
+    /** Remove the iframe DOM node (if present) and unbind the auto-height listener. */
     private removeIframe;
-    /** 工厂：等价于 `new CheckoutElement(opts)`（供 CheckoutInstance 统一入口）。 */
+    /** Factory: equivalent to `new CheckoutElement(opts)` (a unified entry for CheckoutInstance). */
     static create(opts: CheckoutElementOptions): CheckoutElement;
 }
 
 /**
- * CheckoutInstance —— 商户侧结账实例句柄（spec 4 / 7 / 8）。
+ * CheckoutInstance — the merchant-side checkout instance handle (spec 4 / 7 / 8).
  *
- * 职责：
- * - 由 `createCheckout` 在握手 + initialize 成功后构造（持有已就绪 transport、
- *   runtimeId、capabilities、初始 PublicSessionView）。
- * - `create` 组装并返回 {@link CheckoutElement}，维护**互斥注册表**（card 与拆分
- *   字段互斥、同 mode 地址互斥、expressCheckout 单例 → `ELEMENT_CONFLICT`）。
- * - `confirm` 生成 operationId、发 confirm 命令拿 accepted，Promise 由后续同
- *   operationId 的 `paymentResult` 事件兑现；进行中再 confirm → `CHECKOUT_BUSY`。
- * - `getSession/refresh/getPaymentStatus/updateCheckout` 透传对应命令。
- * - `destroy` 幂等：释放 Element、解绑监听、以 INSTANCE_DESTROYED reject 未决 confirm、
- *   发 destroy 命令并销毁 transport；此后迟到的 `paymentResult` 一律忽略。
+ * Responsibilities:
+ * - Constructed by `createCheckout` after a successful handshake + initialize (holds the ready
+ *   transport, runtimeId, capabilities, and the initial PublicSessionView).
+ * - `create` assembles and returns a {@link CheckoutElement}, maintaining a **mutual-exclusion
+ *   registry** (card and split fields are mutually exclusive, same-mode addresses are mutually
+ *   exclusive, expressCheckout is a singleton → `ELEMENT_CONFLICT`).
+ * - `confirm` generates an operationId, sends the confirm command to obtain accepted, and the
+ *   Promise is fulfilled by a later `paymentResult` event with the same operationId; calling
+ *   confirm again while in progress → `CHECKOUT_BUSY`.
+ * - `getSession/refresh/getPaymentStatus/updateCheckout` pass through to the corresponding commands.
+ * - `destroy` is idempotent: releases Elements, unbinds listeners, rejects the pending confirm with
+ *   INSTANCE_DESTROYED, sends the destroy command and destroys the transport; any late
+ *   `paymentResult` afterwards is ignored.
  *
- * 安全约束（AGENTS/spec）：本层只搬运协议命令/事件，**绝不触碰卡值**。
+ * Security constraint (AGENTS/spec): this layer only ferries protocol commands/events and
+ * **never touches card values**.
  */
 
 /**
- * CheckoutInstance 依赖的最小 transport 接口（由 MainFrameTransport 满足）。
+ * The minimal transport interface CheckoutInstance depends on (satisfied by MainFrameTransport).
  *
- * 比 ElementTransport 多出 `onHello/createHiddenIframe/destroy`，供 createCheckout
- * 握手接线与实例销毁使用。单测可注入 mock。
+ * Adds `onHello/createHiddenIframe/destroy` beyond ElementTransport, used by createCheckout for
+ * handshake wiring and for instance destruction. Tests can inject a mock.
  */
 interface InstanceTransport {
     request(name: CommandName, payload: unknown): Promise<unknown>;
@@ -255,211 +279,219 @@ interface InstanceTransport {
     createHiddenIframe(): unknown;
     destroy(): void;
 }
-/** CheckoutInstance 构造参数（由 createCheckout 组装）。 */
+/** CheckoutInstance constructor parameters (assembled by createCheckout). */
 interface CheckoutInstanceOptions {
-    /** 结账唯一 id。 */
+    /** Unique checkout id. */
     checkoutId: string;
-    /** 协商后的运行时 id（来自 RuntimeHello）。 */
+    /** Negotiated runtime id (from RuntimeHello). */
     runtimeId: string;
-    /** 托管页面 origin（不带尾部斜杠）。 */
+    /** Hosted page origin (without a trailing slash). */
     hostOrigin: string;
-    /** 已就绪 transport。 */
+    /** The ready transport. */
     transport: InstanceTransport;
-    /** initialize 返回的 capabilities。 */
+    /** The capabilities returned by initialize. */
     capabilities: string[];
-    /** initialize 返回的初始会话视图。 */
+    /** The initial session view returned by initialize. */
     session: PublicSessionView;
     /**
-     * 初始外观定制（来自 createCheckout 的 appearance）。
-     * 透传给每个 create 出的 Element，序列化进其 iframe src（首帧无闪）：
-     * - colorScheme 拼 `&colorScheme=`；
-     * - variables/rules 拼 `&appearance=`（仅当非空）。
-     * 缺省不拼接。运行时切换走 updateCheckout 命令。
+     * Initial appearance customization (from createCheckout's appearance).
+     * Passed through to every created Element and serialized into its iframe src (no flash on the
+     * first frame):
+     * - colorScheme appended as `&colorScheme=`;
+     * - variables/rules appended as `&appearance=` (only when non-empty).
+     * Not appended when absent. Runtime switching goes through the updateCheckout command.
      */
     appearance?: Appearance;
 }
-/** confirm 可选参数（对齐 ConfirmReq，去掉由实例生成的 operationId）。 */
+/** Optional confirm parameters (aligned with ConfirmReq, minus the instance-generated operationId). */
 type ConfirmOptions = Omit<ConfirmReq, 'operationId'>;
 declare class CheckoutInstance {
-    /** 结账唯一 id。 */
+    /** Unique checkout id. */
     readonly checkoutId: string;
-    /** 协商后的运行时 id。 */
+    /** Negotiated runtime id. */
     readonly runtimeId: string;
-    /** 协商后的能力集合。 */
+    /** Negotiated capability set. */
     readonly capabilities: readonly string[];
     private readonly hostOrigin;
     private readonly transport;
     private session;
-    /** 初始外观定制（透传给 create 出的每个 Element 的 iframe src）。 */
+    /** Initial appearance customization (passed through to each created Element's iframe src). */
     private readonly appearance;
-    /** 已创建的 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).
      */
     private readonly elements;
-    /** 当前未决 confirm（同一时刻至多一个）。 */
+    /** The current pending confirm (at most one at a time). */
     private pendingConfirm;
-    /** paymentResult 事件订阅 handler（destroy 时解绑）。 */
+    /** The paymentResult event subscription handler (unbound on destroy). */
     private readonly paymentResultHandler;
     private destroyed;
     constructor(opts: CheckoutInstanceOptions);
     /**
-     * 创建一个 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: ElementType, options?: ElementOptions): CheckoutElement;
     /**
-     * 发起支付确认。生成 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?: ConfirmOptions): Promise<PaymentOutcome>;
     /**
-     * 获取最新会话视图（透传 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.
      */
     getSession(): Promise<PublicSessionView>;
     /**
-     * 刷新会话（透传 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.
      */
     refresh(): Promise<PublicSessionView>;
     /**
-     * 查询支付状态（原样返回 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.
      */
     getPaymentStatus(): Promise<GetPaymentStatusResp>;
     /**
-     * 更新结账外观/语言（不改会话或金额）。
+     * 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.
      */
     updateCheckout(patch: {
         locale?: string;
         appearance?: Appearance;
     }): Promise<void>;
     /**
-     * 注册 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: EventName, handler: (payload: unknown) => void): void;
     /**
-     * 注销事件 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: EventName, handler: (payload: unknown) => void): void;
     /**
-     * 销毁实例：幂等。释放全部 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(): void;
-    /** 若已销毁则抛 INSTANCE_DESTROYED。 */
+    /** Throw INSTANCE_DESTROYED if already destroyed. */
     private assertAlive;
-    /** 互斥检查：冲突时抛 ELEMENT_CONFLICT（由 elements Map 实时推导，不改变注册表）。 */
+    /** Mutual-exclusion check: throws ELEMENT_CONFLICT on conflict (derived live from the elements Map, does not mutate the registry). */
     private assertNoConflict;
     /**
-     * 元素 `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().
      */
     private releaseElement;
-    /** 处理 paymentResult 事件：按 operationId 兑现未决 confirm；迟到/不匹配忽略。 */
+    /** Handle the paymentResult event: fulfill the pending confirm by operationId; late/mismatched ones are ignored. */
     private handlePaymentResult;
 }
 
 /**
- * 运行环境标识。
- * - `dev`：开发/测试托管页面。
- * - `prod`：生产托管页面。
+ * Runtime environment identifier.
+ * - `dev`: development hosted page.
+ * - `test`: UAT/test hosted page.
+ * - `prod`: production hosted page.
  */
-type Env = 'dev' | 'prod';
+type Env = 'dev' | 'test' | 'prod';
 
 /**
- * createCheckout —— 商户 SDK 的唯一异步入口（spec 4）。
+ * createCheckout — the merchant SDK's single async entry (spec 4).
  *
- * 流程：
- * 1. 生成 `checkoutId`，`resolveHostOrigin(env, hostOrigin)` 得托管 origin。
- * 2. 建 transport、`createHiddenIframe()` 加载托管 main iframe。
- * 3. 注册 onHello；等 RuntimeHello（超时 15s → reject RUNTIME_LOAD_FAILED）。
- * 4. 选共同主版本（无交集 → reject PROTOCOL_UNSUPPORTED）。
- * 5. 发 `initialize`（sessionId/locale/appearance/paymentMethods），拿
- *    capabilities + PublicSessionView；任一步失败 reject 并销毁 transport。
- * 6. 用握手 runtimeId 注入 transport，构造并 resolve {@link CheckoutInstance}。
+ * Flow:
+ * 1. Generate `checkoutId`, derive the hosted origin via `resolveHostOrigin(env, hostOrigin)`.
+ * 2. Build the transport, `createHiddenIframe()` to load the hosted main iframe.
+ * 3. Register onHello; wait for RuntimeHello (timeout 15s → reject RUNTIME_LOAD_FAILED).
+ * 4. Pick a common major version (no intersection → reject PROTOCOL_UNSUPPORTED).
+ * 5. Send `initialize` (sessionId/locale/appearance/paymentMethods) to obtain
+ *    capabilities + PublicSessionView; any step failing rejects and destroys the transport.
+ * 6. Inject the handshake runtimeId into the transport, construct and resolve {@link CheckoutInstance}.
  *
- * 安全约束（AGENTS/spec）：本层只做握手/初始化编排，**绝不触碰卡值**。
+ * Security constraint (AGENTS/spec): this layer only orchestrates handshake/initialization and
+ * **never touches card values**.
  */
 
 /**
- * 创建 CheckoutInstance 时可注入的内部 transport 工厂（仅供测试/高级定制）。
+ * Internal transport factory injectable when creating a CheckoutInstance (test/advanced use only).
  *
- * 真实场景使用内置 MainFrameTransport；测试可注入 mock 以驱动 hello/事件。
+ * Real scenarios use the built-in MainFrameTransport; tests may inject a mock to drive hello/events.
  */
 type TransportFactory = (args: {
     checkoutId: string;
     hostOrigin: string;
 }) => InstanceTransport;
-/** createCheckout 参数。 */
+/** createCheckout parameters. */
 interface CreateCheckoutOptions {
-    /** 后端创建的结账会话 id（必填）。 */
+    /** Checkout session id created by the backend (required). */
     sessionId: string;
-    /** 运行环境（dev/prod），默认 dev。 */
+    /** Runtime environment (dev/test/prod), defaults to prod. */
     env?: Env;
-    /** 覆盖托管 origin（优先于 env）。 */
+    /** Override the hosted origin (takes precedence over env). */
     hostOrigin?: string;
-    /** 语言。 */
+    /** Locale. */
     locale?: string;
-    /** 外观定制。 */
+    /** Appearance customization. */
     appearance?: Appearance;
-    /** 支付方式过滤（只做减法/排序）。 */
+    /** Payment method filter (subtractive/reordering only). */
     paymentMethods?: PaymentMethodFilter;
-    /** 内部注入点：自定义 transport 工厂（测试用，不属于公开 API 契约）。 */
+    /** Internal injection point: custom transport factory (test use; not part of the public API contract). */
     __transportFactory?: TransportFactory;
 }
 /**
- * 创建一个结账实例：握手 + 初始化成功后 resolve。
+ * Create a checkout instance: resolves after a successful handshake + initialization.
  *
- * @param opts - 结账参数。
- * @returns 就绪的 CheckoutInstance。
- * @throws reject RUNTIME_LOAD_FAILED（握手超时）/ PROTOCOL_UNSUPPORTED（无共同主版本）
- *         / 或 initialize 的业务错误。
+ * @param opts - Checkout parameters.
+ * @returns A ready CheckoutInstance.
+ * @throws reject RUNTIME_LOAD_FAILED (handshake timeout) / PROTOCOL_UNSUPPORTED (no common major
+ *         version) / or the initialize business error.
  * @example
  * const checkout = await createCheckout({ sessionId: 'sess_x', env: 'prod' });
  */
 declare function createCheckout(opts: CreateCheckoutOptions): Promise<CheckoutInstance>;
 
 /**
- * @sunbay/checkout-js 公共入口（真源）。
+ * @sunbay/checkout-js public entry (source of truth).
  *
- * 导出 `createCheckout` 入口、`CheckoutInstance` / `CheckoutElement` 句柄类型，
- * 以及协议公开类型（供 TS 使用者消费）。
- * IIFE 产物下，额外在 `window.SunbayCheckout` 暴露 `{ createCheckout }`。
+ * Exports the `createCheckout` entry, the `CheckoutInstance` / `CheckoutElement` handle types,
+ * and the public protocol types (for TS consumers).
+ * In the IIFE build, additionally exposes `{ createCheckout }` on `window.SunbayCheckout`.
  */
 
 declare const version: string;