@sunbay/checkout-sdk-protocol 0.0.2 → 0.0.3

package/dist/index.d.cts

@@ -1,21 +1,22 @@
 /**
- * 协议公开类型（真源）。
+ * Public protocol types (source of truth).
  *
- * 这些类型对外公开，供商户侧 SDK（transport/CheckoutInstance/Element）与
- * checkout 托管侧同步副本共同引用。字段与 checkout 后端现有类型对齐，但
- * 对外视图（PublicSessionView）**不含** rsaPublicKey 等敏感/内部字段。
+ * These types are public and shared by the merchant-side SDK (transport/CheckoutInstance/Element)
+ * and the checkout hosted-side synchronized copy. Fields align with the existing checkout backend
+ * types, but the public view (PublicSessionView) does **not** include sensitive/internal fields
+ * such as rsaPublicKey.
  */
 /**
- * 交易状态（直接复用 checkout 后端 TxnStatus，不转义）。
- * - `I` = 未支付 / 已创建（非终态）
- * - `S` = 成功（终态）
- * - `F` = 失败（终态）
- * - `R` = 需跳转 / 处理中（非终态）
+ * Transaction status (reuses the checkout backend TxnStatus verbatim, no translation).
+ * - `I` = unpaid / created (non-terminal)
+ * - `S` = succeeded (terminal)
+ * - `F` = failed (terminal)
+ * - `R` = requires redirect / processing (non-terminal)
  */
 type TxnStatus = 'I' | 'S' | 'F' | 'R';
 /**
- * 地址信息（对齐 checkout 后端 AddressInfo 字段）。
- * 非敏感数据，允许经公共协议传输。
+ * Address information (aligned with the checkout backend AddressInfo fields).
+ * Non-sensitive data; allowed to be transmitted over the public protocol.
  */
 interface AddressInfo {
     country: string;
@@ -30,10 +31,10 @@ interface AddressInfo {
     recipientName?: string;
     phone?: string;
 }
-/** 首期支持的支付方式。 */
+/** Payment methods supported in the first phase. */
 type PaymentMethod = 'card' | 'applePay' | 'googlePay';
 /**
- * 公开支付方式视图（对外只暴露 method/type/name/logoUrl，不含内部配置）。
+ * Public payment method view (only exposes method/type/name/logoUrl, no internal config).
  */
 interface PublicPaymentMethod {
     method: string;
@@ -41,15 +42,15 @@ interface PublicPaymentMethod {
     name: string;
     logoUrl: string;
 }
-/** 公开商品行。 */
+/** Public product line. */
 interface PublicProductLine {
     amount: number;
     name: string;
     num: string;
 }
 /**
- * 公开 Session 视图：金额 / 币种 / 商品 / collect 标记 / 可用支付方式 / 商户信息。
- * **不含** rsaPublicKey 等敏感或内部字段。
+ * Public session view: amount / currency / products / collect flags / available payment methods /
+ * merchant info. Does **not** include sensitive or internal fields such as rsaPublicKey.
  */
 interface PublicSessionView {
     sessionId: string;
@@ -69,8 +70,8 @@ interface PublicSessionView {
     merchantReturnUrl?: string;
 }
 /**
- * 支付结果四态（spec 8.2）。
- * `pending` 非终态，消费者不得只接受首条结果。
+ * Four payment outcome states (spec 8.2).
+ * `pending` is non-terminal; consumers must not accept only the first result.
  */
 type PaymentOutcome = {
     status: 'succeeded';
@@ -89,14 +90,14 @@ type PaymentOutcome = {
     operationId: string;
     txnId?: string;
 };
-/** 错误分类（spec 5.4）。 */
+/** Error categories (spec 5.4). */
 type CheckoutErrorCategory = 'configuration' | 'validation' | 'network' | 'runtime' | 'payment';
 /**
- * 结构化错误（spec 5.4）。
+ * Structured error (spec 5.4).
  */
 interface CheckoutError {
     code: string;
-    /** 展示用消息。 */
+    /** Message for display. */
     message: string;
     category: CheckoutErrorCategory;
     errorId: string;
@@ -105,149 +106,160 @@ interface CheckoutError {
     traceId?: string;
 }
 /**
- * 白名单设计变量（映射到 hosted 侧 `ThemeConfig`，复用现有 `generateThemeStyles` 与深色推导）。
+ * Whitelisted design variables (mapped to the hosted-side `ThemeConfig`, reusing the existing
+ * `generateThemeStyles` and dark-mode derivation).
  *
- * 全部可选；值为颜色或长度字符串，由 hosted 侧白名单校验器校验后方可进入 `<style>`。
- * 属性名使用 camelCase（如 `borderRadius`），hosted 侧转 kebab。
+ * All optional; values are color or length strings, and only enter `<style>` after being validated
+ * by the hosted-side whitelist validator. Property names use camelCase (e.g. `borderRadius`); the
+ * hosted side converts them to kebab-case.
  */
 interface AppearanceVariables {
-    /** 主色 → `ThemeConfig.primary`（并联动 ring）。 */
+    /** Primary color → `ThemeConfig.primary` (also drives ring). */
     colorPrimary?: string;
-    /** 背景色 → background / card / popover。 */
+    /** Background color → background / card / popover. */
     colorBackground?: string;
-    /** 文字色 → foreground。 */
+    /** Text color → foreground. */
     colorText?: string;
-    /** 边框色 → border / input。 */
+    /** Border color → border / input. */
     colorBorder?: string;
-    /** 危险色 → destructive。 */
+    /** Danger color → destructive. */
     colorDanger?: string;
-    /** 圆角 → radius（长度值）。 */
+    /** Border radius → radius (length value). */
     borderRadius?: string;
-    /** 字体族 → `:root` font-family（不进 `ThemeConfig`，单独注入）。 */
+    /** Font family → `:root` font-family (not part of `ThemeConfig`, injected separately). */
     fontFamily?: string;
 }
 /**
- * rules 可定制的元素锚点（语义 key，对应 hosted 侧 `data-sunbay-el`）。
+ * Customizable element anchors for rules (semantic keys, corresponding to the hosted-side
+ * `data-sunbay-el`).
  *
- * 选择器由 hosted 生成，商户只提供语义 key，不接受选择器字符串。
- * - `'input'`：卡号 / 有效期 / CVV 输入框；
- * - `'input:focus'`：输入框聚焦态；
- * - `'input:invalid'`：输入框错误态（`[data-sunbay-invalid]`）；
- * - `'label'`：iframe 内标签文字；
- * - `'error'`：iframe 内错误文字；
- * - `'cardBrand'`：卡品牌图标容器；
- * - `'cvvIcon'`：CVV 图标。
+ * Selectors are generated by the hosted side; merchants only provide semantic keys and selector
+ * strings are not accepted.
+ * - `'input'`: card number / expiry / CVV input fields;
+ * - `'input:focus'`: input focus state;
+ * - `'input:invalid'`: input error state (`[data-sunbay-invalid]`);
+ * - `'label'`: label text inside the iframe;
+ * - `'error'`: error text inside the iframe;
+ * - `'cardBrand'`: card brand icon container;
+ * - `'cvvIcon'`: CVV icon.
  */
 type AppearanceRuleTarget = 'input' | 'input:focus' | 'input:invalid' | 'label' | 'error' | 'cardBrand' | 'cvvIcon';
 /**
- * 单条 rule：白名单 CSS 属性（camelCase 或 kebab）到值的映射。
+ * A single rule: a mapping from whitelisted CSS properties (camelCase or kebab) to values.
  *
- * 属性名与值均由 hosted 侧白名单校验后方可进入 `<style>`；非白名单属性 / 非法值被丢弃。
+ * Both property names and values only enter `<style>` after hosted-side whitelist validation;
+ * non-whitelisted properties / invalid values are discarded.
  */
 type AppearanceRuleStyle = Record<string, string>;
 /**
- * 外观定制（appearance）。受控两层：`variables`（整体风格的白名单设计变量）+
- * `rules`（关键元素精调的受控语义选择器）。因 iframe 跨域 + PCI 合规，**不开放任意 CSS**。
+ * Appearance customization. Controlled in two layers: `variables` (whitelisted design variables for
+ * the overall style) + `rules` (controlled semantic selectors for fine-tuning key elements). Due to
+ * cross-origin iframes + PCI compliance, arbitrary CSS is **not** allowed.
  *
- * 所有进入 `<style>` 的文本全程由 hosted 侧白名单校验；appearance 不含任何卡值 / 支付参数。
+ * All text entering `<style>` is whitelist-validated by the hosted side throughout; appearance
+ * contains no card values / payment parameters.
  */
 interface Appearance {
-    /** 白名单设计变量（整体风格）。 */
+    /** Whitelisted design variables (overall style). */
     variables?: AppearanceVariables;
-    /** 受控语义规则（关键元素精调）；key 限 `AppearanceRuleTarget`。 */
+    /** Controlled semantic rules (fine-tuning key elements); keys limited to `AppearanceRuleTarget`. */
     rules?: Partial<Record<AppearanceRuleTarget, AppearanceRuleStyle>>;
     /**
-     * 配色方案偏好。
-     * - `'light'`：浅色；
-     * - `'dark'`：深色；
-     * - `'auto'`：跟随系统 / 宿主环境。
+     * Color scheme preference.
+     * - `'light'`: light;
+     * - `'dark'`: dark;
+     * - `'auto'`: follow the system / host environment.
      *
-     * 协议层只定义类型；缺省时的默认语义（SDK 默认 `'light'`）由消费方实现，
-     * 协议不强制默认值。向后兼容的可选新增字段。
+     * The protocol layer only defines the type; the default semantics when omitted (the SDK defaults
+     * to `'light'`) are implemented by the consumer, and the protocol does not enforce a default
+     * value. A backward-compatible optional new field.
      */
     colorScheme?: 'light' | 'dark' | 'auto';
 }
 /**
- * 支付方式过滤配置（spec 9：只做减法/排序，禁止前端增开）。
+ * Payment method filter configuration (spec 9: subtraction/ordering only, enabling new methods on
+ * the frontend is forbidden).
  */
 interface PaymentMethodFilter {
-    /** 要隐藏的支付方式（method 标识）。 */
+    /** Payment methods to hide (method identifiers). */
     hide?: string[];
-    /** 展示顺序（method 标识）。 */
+    /** Display order (method identifiers). */
     order?: string[];
 }
-/** 可挂载 Element 类型（spec 6）。 */
+/** Mountable Element types (spec 6). */
 type ElementType = 'card' | 'cardNumber' | 'cardExpiry' | 'cardCvc' | 'address' | 'expressCheckout';
-/** card Element 配置（spec 6）。 */
+/** card Element options (spec 6). */
 interface CardElementOptions {
     showBillingAddress?: boolean;
     showShippingAddress?: boolean;
     showPostalCode?: boolean;
     appearance?: Appearance;
 }
-/** 拆分卡字段配置（spec 6）。 */
+/** Split card field options (spec 6). */
 interface CardFieldElementOptions {
     appearance?: Appearance;
 }
-/** address Element 配置（spec 6）。 */
+/** address Element options (spec 6). */
 interface AddressElementOptions {
     mode: 'billing' | 'shipping';
     appearance?: Appearance;
 }
-/** Apple Pay 官方按钮主题。缺省跟随当前配色（浅 black / 深 white）。 */
+/** Apple Pay official button theme. Defaults to follow the current color scheme (light black / dark white). */
 type ApplePayButtonTheme = 'black' | 'white' | 'white-outline';
-/** Google Pay 官方按钮主题。缺省跟随当前配色（浅 black / 深 white）。 */
+/** Google Pay official button theme. Defaults to follow the current color scheme (light black / dark white). */
 type GooglePayButtonTheme = 'black' | 'white' | 'default';
-/** Apple Pay 官方按钮文案类型（`apple-pay-button` 的 `type` 属性，官方全集）。 */
+/** Apple Pay official button text type (the `type` attribute of `apple-pay-button`, full official set). */
 type ApplePayButtonType = 'plain' | 'buy' | 'donate' | 'check-out' | 'book' | 'subscribe' | 'reload' | 'add-money' | 'top-up' | 'order' | 'rent' | 'support' | 'contribute' | 'tip';
-/** Google Pay 官方按钮文案类型（`buttonType`，官方全集）。 */
+/** Google Pay official button text type (`buttonType`, full official set). */
 type GooglePayButtonType = 'buy' | 'plain' | 'checkout' | 'pay' | 'donate' | 'book' | 'order' | 'subscribe';
-/** Apple Pay 单钱包配置（显示时的细粒度选项）。 */
+/** Apple Pay single-wallet options (fine-grained options when shown). */
 interface ApplePayOptions {
-    /** 按钮主题；缺省跟随当前配色。 */
+    /** Button theme; defaults to follow the current color scheme. */
     buttonTheme?: ApplePayButtonTheme;
-    /** 按钮文案类型；缺省 `'pay'`。 */
+    /** Button text type; defaults to `'pay'`. */
     buttonType?: ApplePayButtonType;
 }
-/** Google Pay 单钱包配置（显示时的细粒度选项）。 */
+/** Google Pay single-wallet options (fine-grained options when shown). */
 interface GooglePayOptions {
-    /** 按钮主题；缺省跟随当前配色。 */
+    /** Button theme; defaults to follow the current color scheme. */
     buttonTheme?: GooglePayButtonTheme;
-    /** 按钮文案类型；缺省 `'pay'`。 */
+    /** Button text type; defaults to `'pay'`. */
     buttonType?: GooglePayButtonType;
 }
-/** expressCheckout Element 配置（spec 6）。 */
+/** expressCheckout Element options (spec 6). */
 interface ExpressCheckoutElementOptions {
     /**
-     * 各钱包开关 / 配置：
-     * - `false`：强制隐藏该钱包；
-     * - `true` 或缺省：自动显示（后端业务允许 ∩ 环境可用），主题跟随当前配色；
-     * - 配置对象：自动显示，并应用对象内的细粒度配置（如 buttonTheme）。
+     * Per-wallet toggle / configuration:
+     * - `false`: force-hide this wallet;
+     * - `true` or omitted: auto-show (backend business allows ∩ environment available), theme follows
+     *   the current color scheme;
+     * - config object: auto-show, and apply the fine-grained config in the object (e.g. buttonTheme).
      */
     paymentMethods?: {
         applePay?: boolean | ApplePayOptions;
         googlePay?: boolean | GooglePayOptions;
     };
-    /** 布局约束（首期仅最大列数）。 */
+    /** Layout constraints (first phase: maximum columns only). */
     layout?: {
         maxColumns?: number;
     };
-    /** 钱包按钮高度（像素，全局应用到所有钱包按钮）。hosted 侧 clamp 到 [30, 64]；缺省 40。 */
+    /** Wallet button height (pixels, applied globally to all wallet buttons). The hosted side clamps to [30, 64]; defaults to 40. */
     buttonHeight?: number;
 }
 /**
- * express 可用钱包视图（spec 6）。
- * 表示各钱包在当前环境下是否可用，用于 express 可用性事件载荷。
+ * Express available wallets view (spec 6).
+ * Indicates whether each wallet is available in the current environment; used as the payload for the
+ * express availability event.
  */
 interface AvailableWallets {
     applePay: boolean;
     googlePay: boolean;
 }
-/** Element 配置联合（按 type 区分）。 */
+/** Element options union (distinguished by type). */
 type ElementOptions = CardElementOptions | CardFieldElementOptions | AddressElementOptions | ExpressCheckoutElementOptions;
-/** Element 运行状态机（spec 6）。 */
+/** Element runtime state machine (spec 6). */
 type ElementStatus = 'created' | 'loading' | 'ready' | 'destroyed' | 'loadError';
-/** action 载荷（spec 8.3；qrCode/showContent 首期预留）。 */
+/** action payload (spec 8.3; qrCode/showContent reserved for the first phase). */
 interface PaymentAction {
     type: 'qrCode' | 'redirect' | 'showContent';
     redirectUrl?: string;
@@ -256,33 +268,35 @@ interface PaymentAction {
 }
 
 /**
- * 信封与握手契约（spec 5.1，真源）。
+ * Envelope and handshake contract (spec 5.1, source of truth).
  *
- * 协议名 `sunbay-checkout`，`major = 1`。与现有 Native Bridge `{v:1,type,...}`
- * 是不同协议，数字相同不代表兼容。
+ * Protocol name `sunbay-checkout`, `major = 1`. This is a different protocol from the existing
+ * Native Bridge `{v:1,type,...}`; identical numbers do not imply compatibility.
  *
- * `encodeEnvelope`/`decodeEnvelope`：JSON 序列化 + 最小运行时结构校验
- * （校验 protocol/major/kind/必填字段），非法抛错。解码器**不**校验 request.name
- * 是否为已知 CommandName —— 未知 name 仍解为 kind==='request'，由调用方拒绝。
+ * `encodeEnvelope`/`decodeEnvelope`: JSON serialization + minimal runtime structural validation
+ * (validates protocol/major/kind/required fields), throwing on invalid input. The decoder does
+ * **not** validate whether request.name is a known CommandName — an unknown name is still decoded
+ * as kind==='request' and rejected by the caller.
  */
 
-/** 协议名常量。 */
+/** Protocol name constant. */
 declare const PROTOCOL_NAME: "sunbay-checkout";
-/** 当前主版本。 */
+/** Current major version. */
 declare const PROTOCOL_MAJOR: 1;
 /**
- * 握手消息（spec 5.1）。main iframe 加载后先广播，此时尚无 checkoutId。
+ * Handshake message (spec 5.1). Broadcast first after the main iframe loads, when there is no
+ * checkoutId yet.
  */
 type RuntimeHello = {
     protocol: 'sunbay-checkout';
     kind: 'hello';
     runtimeId: string;
     supportedMajorVersions: number[];
-    /** 首期：['card','splitCard','address','express','paymentMethodFilter']。 */
+    /** First phase: ['card','splitCard','address','express','paymentMethodFilter']. */
     capabilities: string[];
 };
 /**
- * 初始化后的公共信封（spec 5.1）。
+ * Public envelope after initialization (spec 5.1).
  */
 type Envelope = {
     protocol: 'sunbay-checkout';
@@ -312,28 +326,28 @@ type Envelope = {
     operationId?: string;
     payload: unknown;
 });
-/** 协议校验失败错误。 */
+/** Protocol validation failure error. */
 declare class EnvelopeDecodeError extends Error {
     constructor(message: string);
 }
 /**
- * 将信封序列化为线缆字符串（JSON）。
+ * Serialize an envelope into a wire string (JSON).
  *
- * @param envelope 待发送的信封
- * @returns JSON 字符串
+ * @param envelope The envelope to send
+ * @returns JSON string
  * @example
  * const wire = encodeEnvelope({ protocol: 'sunbay-checkout', major: 1, ... });
  */
 declare function encodeEnvelope(envelope: Envelope): string;
 /**
- * 解析并最小结构校验信封。非法（缺 protocol、错 major、非法 kind、缺必填字段、
- * 非 JSON）一律抛 {@link EnvelopeDecodeError}。
+ * Parse and minimally structurally validate an envelope. Invalid input (missing protocol, wrong
+ * major, invalid kind, missing required fields, non-JSON) always throws {@link EnvelopeDecodeError}.
  *
- * 注意：解码器不校验 request.name 是否为已知命令 —— 未知 name 仍解为
- * kind==='request'，交由调用方（如 Orchestrator）拒绝。
+ * Note: the decoder does not validate whether request.name is a known command — an unknown name is
+ * still decoded as kind==='request' and left for the caller (e.g. the Orchestrator) to reject.
  *
- * @param wire 线缆字符串
- * @returns 已校验结构的信封
+ * @param wire The wire string
+ * @returns The structurally validated envelope
  * @example
  * const env = decodeEnvelope(wire);
  * if (env.kind === 'request') { ... }
@@ -341,10 +355,10 @@ declare function encodeEnvelope(envelope: Envelope): string;
 declare function decodeEnvelope(wire: string): Envelope;
 
 /**
- * 协议错误码常量（单一真源，spec 5.4）。
+ * Protocol error code constants (single source of truth, spec 5.4).
  *
- * 不提供可能误导重复付款的通用 `retryable` 布尔。
- * 仅保留实际会被产出的错误码；新增码须同时有产出点。
+ * Does not provide a generic `retryable` boolean that could mislead into duplicate payments.
+ * Only keeps error codes that are actually produced; new codes must have a production point.
  */
 declare const ErrorCode: {
     readonly INVALID_OPTIONS: "INVALID_OPTIONS";
@@ -359,20 +373,21 @@ declare const ErrorCode: {
     readonly PAYMENT_FLOW_ERROR: "PAYMENT_FLOW_ERROR";
     readonly UNSUPPORTED_CAPABILITY: "UNSUPPORTED_CAPABILITY";
 };
-/** 错误码字面量联合类型。 */
+/** Error code literal union type. */
 type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
 
 /**
- * 命令契约（商户 SDK → main，spec 5.2 表，真源）。
+ * Command contract (merchant SDK → main, spec 5.2 table, source of truth).
  *
- * 每命令的请求/响应类型在此定义；跨通道只传 JSON 可序列化数据。
+ * The request/response types for each command are defined here; only JSON-serializable data is sent
+ * across the channel.
  */
 
-/** 全部命令名（spec 5.2）。 */
+/** All command names (spec 5.2). */
 type CommandName = 'initialize' | 'createElement' | 'updateElement' | 'destroyElement' | 'focus' | 'blur' | 'clear' | 'updateCheckout' | 'getSession' | 'refresh' | 'getPaymentStatus' | 'confirm' | 'destroy';
-/** 已知命令名集合（供调用方校验 request.name 是否受支持）。 */
+/** Set of known command names (for callers to validate whether request.name is supported). */
 declare const COMMAND_NAMES: readonly CommandName[];
-/** 判断字符串是否为已知命令名。 */
+/** Determine whether a string is a known command name. */
 declare function isCommandName(name: string): name is CommandName;
 interface InitializeReq {
     sessionId: string;
@@ -444,7 +459,7 @@ type DestroyReq = Record<string, never>;
 interface DestroyResp {
     released: true;
 }
-/** 命令名 → 请求载荷映射。 */
+/** Command name → request payload mapping. */
 interface CommandRequestMap {
     initialize: InitializeReq;
     createElement: CreateElementReq;
@@ -460,7 +475,7 @@ interface CommandRequestMap {
     confirm: ConfirmReq;
     destroy: DestroyReq;
 }
-/** 命令名 → 成功响应载荷映射。 */
+/** Command name → success response payload mapping. */
 interface CommandResponseMap {
     initialize: InitializeResp;
     createElement: CreateElementResp;
@@ -478,24 +493,25 @@ interface CommandResponseMap {
 }
 
 /**
- * 事件契约（main → 商户 SDK，spec 5.3 表，真源）。
+ * Event contract (main → merchant SDK, spec 5.3 table, source of truth).
  *
- * 公开事件仅暴露 empty/complete/brand/error 等允许状态，**绝不含卡值**，
- * 不提供卡数据 getValue。`on` 注册后不重放历史事件。
+ * Public events only expose allowed states such as empty/complete/brand/error, and **never contain
+ * card values**; no card-data getValue is provided. After `on` registration, historical events are
+ * not replayed.
  */
 
-/** 全部事件名（spec 5.3）。 */
+/** All event names (spec 5.3). */
 type EventName = 'ready' | 'change' | 'focus' | 'blur' | 'loadError' | 'elementReady' | 'expressAvailabilityChange' | 'paymentStateChange' | 'paymentResult' | 'error';
-/** 已知事件名集合。 */
+/** Set of known event names. */
 declare const EVENT_NAMES: readonly EventName[];
-/** 判断字符串是否为已知事件名。 */
+/** Determine whether a string is a known event name. */
 declare function isEventName(name: string): name is EventName;
 interface ReadyEvent {
     elementId: string;
 }
 interface ElementReadyEvent {
     elementId: string;
-    /** 仅 expressCheckout Element ready 时携带：各钱包可用性。 */
+    /** Only carried when the expressCheckout Element is ready: per-wallet availability. */
     availableWallets?: AvailableWallets;
 }
 interface ChangeEvent {
@@ -503,7 +519,7 @@ interface ChangeEvent {
     empty: boolean;
     complete: boolean;
     error?: CheckoutError;
-    /** 仅卡号字段允许携带 brand；绝不含卡值。 */
+    /** Only the card number field may carry brand; never contains card values. */
     brand?: string;
 }
 interface FocusEvent {
@@ -517,8 +533,9 @@ interface LoadErrorEvent {
     error: CheckoutError;
 }
 /**
- * express 可用钱包变化事件（spec 6）。
- * 专用于 expressCheckout：以 AvailableWallets 表达各钱包（Apple/Google Pay）可用性。
+ * Express available-wallets change event (spec 6).
+ * Dedicated to expressCheckout: uses AvailableWallets to express the availability of each wallet
+ * (Apple/Google Pay).
  */
 interface ExpressAvailabilityChangeEvent {
     availableWallets: AvailableWallets;
@@ -526,7 +543,7 @@ interface ExpressAvailabilityChangeEvent {
 interface PaymentStateChangeEvent {
     operationId: string;
     method: PaymentMethod;
-    /** 过程状态；requiresAction 时携带 action 信息。 */
+    /** Intermediate state; carries action info when requiresAction. */
     state: string;
     action?: PaymentAction;
 }
@@ -536,11 +553,11 @@ interface PaymentResultEvent {
     outcome: PaymentOutcome;
 }
 interface ErrorEvent {
-    /** 异步主动流程错误；可含 operationId（如已创建）。 */
+    /** Error in an asynchronous proactive flow; may include operationId (if already created). */
     operationId?: string;
     error: CheckoutError;
 }
-/** 事件名 → 载荷映射。 */
+/** Event name → payload mapping. */
 interface EventPayloadMap {
     ready: ReadyEvent;
     change: ChangeEvent;
@@ -555,43 +572,47 @@ interface EventPayloadMap {
 }
 
 /**
- * iframe 布局协议:托管 iframe(checkout,child)→ 父窗口(商户 SDK,parent)的
- * **直连 postMessage** 契约,用于 iframe 自适应高度。
+ * iframe layout protocol: the **direct postMessage** contract from the hosted iframe (checkout,
+ * child) → parent window (merchant SDK, parent), used for iframe auto-height.
  *
- * 与外层 Envelope(商户 SDK ↔ main iframe)及内层点对点 port(element ↔ main)均区分:
- * 本消息由每个可见 field / element iframe 直接 postMessage 到其 `window.parent`(商户页),
- * 商户 SDK 的 Element 句柄监听后把外层 iframe 高度调整为内容真实高度(宽度保持 100%)。
+ * Distinct from both the outer Envelope (merchant SDK ↔ main iframe) and the inner point-to-point
+ * port (element ↔ main): this message is posted directly by each visible field / element iframe to
+ * its `window.parent` (the merchant page), and the merchant SDK's Element handle listens for it and
+ * adjusts the outer iframe height to the real content height (width stays 100%).
  *
- * 安全约束(AGENTS/spec):本消息**绝不含任何卡值**(明文或密文),仅携带 height 与
- * elementId。父窗口侧须校验来源(`event.source === iframe.contentWindow` 且
- * `event.origin === hostOrigin`)后方可采信,防止跨源伪造。
+ * Security constraint (AGENTS/spec): this message **never contains any card value** (plaintext or
+ * ciphertext); it only carries height and elementId. The parent-window side must validate the
+ * source (`event.source === iframe.contentWindow` and `event.origin === hostOrigin`) before
+ * trusting it, to prevent cross-origin forgery.
  */
-/** iframe 自适应高度消息的判别字面量(命名空间化,避免与其它 postMessage 碰撞)。 */
+/** Discriminant literal for the iframe auto-height message (namespaced to avoid colliding with other postMessages). */
 declare const IFRAME_RESIZE_MESSAGE_TYPE: "sunbay:checkout:iframe-resize";
 /**
- * iframe(child)→ 父窗口(SDK)的内容高度变更通知。
+ * Content height change notification from the iframe (child) → parent window (SDK).
  *
- * child 用 `ResizeObserver` 观测内容高度,变化时发送(去重);parent 据此设
- * `iframe.style.height`。绝不含卡值。
+ * The child observes content height with a `ResizeObserver` and sends on change (deduplicated); the
+ * parent sets `iframe.style.height` accordingly. Never contains card values.
  */
 interface IframeResizeMessage {
-    /** 判别字段,固定为 {@link IFRAME_RESIZE_MESSAGE_TYPE}。 */
+    /** Discriminant field, fixed to {@link IFRAME_RESIZE_MESSAGE_TYPE}. */
     type: typeof IFRAME_RESIZE_MESSAGE_TYPE;
     /**
-     * 目标 Element 的唯一 id。由商户 SDK 经 iframe src 的 `&elementId=` 下发,child 原样
-     * 回传,供父窗口在同一页面多个 iframe 间按句柄分发。
+     * The unique id of the target Element. Passed down by the merchant SDK via the iframe src's
+     * `&elementId=`, echoed back verbatim by the child, so the parent window can dispatch by handle
+     * among multiple iframes on the same page.
      */
     elementId: string;
-    /** 内容高度(CSS px,已 `Math.ceil`;有限且非负)。 */
+    /** Content height (CSS px, already `Math.ceil`-ed; finite and non-negative). */
     height: number;
 }
 /**
- * 是否为合法的 {@link IframeResizeMessage}。
+ * Whether the value is a valid {@link IframeResizeMessage}.
  *
- * 校验:非空对象 + type 字面量匹配 + elementId 为非空字符串 + height 为有限非负数。
+ * Validates: non-null object + type literal match + elementId is a non-empty string + height is a
+ * finite non-negative number.
  *
- * @param data - 任意来源数据(通常是 `MessageEvent.data`)。
- * @returns data 是否为合法的 iframe-resize 消息。
+ * @param data - Data from any source (typically `MessageEvent.data`).
+ * @returns Whether data is a valid iframe-resize message.
  */
 declare function isIframeResizeMessage(data: unknown): data is IframeResizeMessage;