@sunbay/checkout-sdk-protocol 0.0.1 → 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,75 +106,160 @@ interface CheckoutError {
     traceId?: string;
 }
 /**
- * 外观定制（appearance）。首期为开放映射，交由托管侧解释。
+ * Whitelisted design variables (mapped to the hosted-side `ThemeConfig`, reusing the existing
+ * `generateThemeStyles` and dark-mode derivation).
+ *
+ * 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 {
+    /** Primary color → `ThemeConfig.primary` (also drives ring). */
+    colorPrimary?: string;
+    /** Background color → background / card / popover. */
+    colorBackground?: string;
+    /** Text color → foreground. */
+    colorText?: string;
+    /** Border color → border / input. */
+    colorBorder?: string;
+    /** Danger color → destructive. */
+    colorDanger?: string;
+    /** Border radius → radius (length value). */
+    borderRadius?: string;
+    /** Font family → `:root` font-family (not part of `ThemeConfig`, injected separately). */
+    fontFamily?: string;
+}
+/**
+ * Customizable element anchors for rules (semantic keys, corresponding to the hosted-side
+ * `data-sunbay-el`).
+ *
+ * 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';
+/**
+ * A single rule: a mapping from whitelisted CSS properties (camelCase or kebab) to values.
+ *
+ * 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 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.
+ *
+ * All text entering `<style>` is whitelist-validated by the hosted side throughout; appearance
+ * contains no card values / payment parameters.
  */
 interface Appearance {
-    theme?: string;
-    variables?: Record<string, string>;
+    /** Whitelisted design variables (overall style). */
+    variables?: AppearanceVariables;
+    /** Controlled semantic rules (fine-tuning key elements); keys limited to `AppearanceRuleTarget`. */
+    rules?: Partial<Record<AppearanceRuleTarget, AppearanceRuleStyle>>;
+    /**
+     * Color scheme preference.
+     * - `'light'`: light;
+     * - `'dark'`: dark;
+     * - `'auto'`: follow the system / host environment.
+     *
+     * 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;
 }
-/** expressCheckout Element 配置（spec 6）。 */
+/** Apple Pay official button theme. Defaults to follow the current color scheme (light black / dark white). */
+type ApplePayButtonTheme = 'black' | 'white' | 'white-outline';
+/** Google Pay official button theme. Defaults to follow the current color scheme (light black / dark white). */
+type GooglePayButtonTheme = 'black' | 'white' | 'default';
+/** 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 official button text type (`buttonType`, full official set). */
+type GooglePayButtonType = 'buy' | 'plain' | 'checkout' | 'pay' | 'donate' | 'book' | 'order' | 'subscribe';
+/** Apple Pay single-wallet options (fine-grained options when shown). */
+interface ApplePayOptions {
+    /** Button theme; defaults to follow the current color scheme. */
+    buttonTheme?: ApplePayButtonTheme;
+    /** Button text type; defaults to `'pay'`. */
+    buttonType?: ApplePayButtonType;
+}
+/** Google Pay single-wallet options (fine-grained options when shown). */
+interface GooglePayOptions {
+    /** Button theme; defaults to follow the current color scheme. */
+    buttonTheme?: GooglePayButtonTheme;
+    /** Button text type; defaults to `'pay'`. */
+    buttonType?: GooglePayButtonType;
+}
+/** expressCheckout Element options (spec 6). */
 interface ExpressCheckoutElementOptions {
     /**
-     * 各钱包开关（商户显式控制）：
-     * - `false`：强制隐藏该钱包；
-     * - `true` 或缺省：自动模式，按后端业务允许 ∩ 环境可用展示。
+     * 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;
-        googlePay?: boolean;
+        applePay?: boolean | ApplePayOptions;
+        googlePay?: boolean | GooglePayOptions;
     };
-    /** 布局约束（首期仅最大列数）。 */
+    /** Layout constraints (first phase: maximum columns only). */
     layout?: {
         maxColumns?: number;
     };
-    /** 按钮主题（按钱包区分）。 */
-    buttonTheme?: {
-        applePay?: string;
-        googlePay?: string;
-    };
-    /** 按钮高度（像素）。 */
+    /** 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;
@@ -182,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';
@@ -238,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') { ... }
@@ -267,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";
@@ -285,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;
@@ -370,7 +459,7 @@ type DestroyReq = Record<string, never>;
 interface DestroyResp {
     released: true;
 }
-/** 命令名 → 请求载荷映射。 */
+/** Command name → request payload mapping. */
 interface CommandRequestMap {
     initialize: InitializeReq;
     createElement: CreateElementReq;
@@ -386,7 +475,7 @@ interface CommandRequestMap {
     confirm: ConfirmReq;
     destroy: DestroyReq;
 }
-/** 命令名 → 成功响应载荷映射。 */
+/** Command name → success response payload mapping. */
 interface CommandResponseMap {
     initialize: InitializeResp;
     createElement: CreateElementResp;
@@ -404,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）。 */
-type EventName = 'ready' | 'change' | 'focus' | 'blur' | 'loadError' | 'elementReady' | 'availablePaymentMethodsChange' | 'expressAvailabilityChange' | 'paymentStateChange' | 'paymentResult' | 'error';
-/** 已知事件名集合。 */
+/** 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 {
@@ -429,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 {
@@ -442,13 +532,10 @@ interface LoadErrorEvent {
     elementId: string;
     error: CheckoutError;
 }
-interface AvailablePaymentMethodsChangeEvent {
-    availablePaymentMethods: PublicPaymentMethod[];
-}
 /**
- * express 可用钱包变化事件（spec 6）。
- * 专用于 expressCheckout：以 AvailableWallets 表达各钱包可用性，
- * 与 AvailablePaymentMethodsChangeEvent（PublicPaymentMethod[]）并存，互不破坏。
+ * 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;
@@ -456,7 +543,7 @@ interface ExpressAvailabilityChangeEvent {
 interface PaymentStateChangeEvent {
     operationId: string;
     method: PaymentMethod;
-    /** 过程状态；requiresAction 时携带 action 信息。 */
+    /** Intermediate state; carries action info when requiresAction. */
     state: string;
     action?: PaymentAction;
 }
@@ -466,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;
@@ -478,11 +565,55 @@ interface EventPayloadMap {
     blur: BlurEvent;
     loadError: LoadErrorEvent;
     elementReady: ElementReadyEvent;
-    availablePaymentMethodsChange: AvailablePaymentMethodsChangeEvent;
     expressAvailabilityChange: ExpressAvailabilityChangeEvent;
     paymentStateChange: PaymentStateChangeEvent;
     paymentResult: PaymentResultEvent;
     error: ErrorEvent;
 }
 
-export { type AddressElementOptions, type AddressInfo, type Appearance, type AvailablePaymentMethodsChangeEvent, type AvailableWallets, type BlurEvent, COMMAND_NAMES, type CardElementOptions, type CardFieldElementOptions, type ChangeEvent, type CheckoutError, type CheckoutErrorCategory, type CommandName, type CommandRequestMap, type CommandResponseMap, type ConfirmReq, type ConfirmResp, type CreateElementReq, type CreateElementResp, type DestroyElementReq, type DestroyElementResp, type DestroyReq, type DestroyResp, EVENT_NAMES, type ElementActionReq, type ElementActionResp, type ElementOptions, type ElementReadyEvent, type ElementStatus, type ElementType, type Envelope, EnvelopeDecodeError, ErrorCode, type ErrorCodeValue, type ErrorEvent, type EventName, type EventPayloadMap, type ExpressAvailabilityChangeEvent, type ExpressCheckoutElementOptions, type FocusEvent, type GetPaymentStatusReq, type GetPaymentStatusResp, type GetSessionReq, type GetSessionResp, type InitializeReq, type InitializeResp, type LoadErrorEvent, PROTOCOL_MAJOR, PROTOCOL_NAME, type PaymentAction, type PaymentMethod, type PaymentMethodFilter, type PaymentOutcome, type PaymentResultEvent, type PaymentStateChangeEvent, type PublicPaymentMethod, type PublicProductLine, type PublicSessionView, type ReadyEvent, type RuntimeHello, type TxnStatus, type UpdateCheckoutReq, type UpdateCheckoutResp, type UpdateElementReq, type UpdateElementResp, decodeEnvelope, encodeEnvelope, isCommandName, isEventName };
+/**
+ * iframe layout protocol: the **direct postMessage** contract from the hosted iframe (checkout,
+ * child) → parent window (merchant SDK, parent), used for iframe auto-height.
+ *
+ * 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%).
+ *
+ * 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.
+ */
+/** 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";
+/**
+ * Content height change notification from the iframe (child) → parent window (SDK).
+ *
+ * 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 {
+    /** Discriminant field, fixed to {@link IFRAME_RESIZE_MESSAGE_TYPE}. */
+    type: typeof IFRAME_RESIZE_MESSAGE_TYPE;
+    /**
+     * 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;
+    /** Content height (CSS px, already `Math.ceil`-ed; finite and non-negative). */
+    height: number;
+}
+/**
+ * Whether the value is a valid {@link IframeResizeMessage}.
+ *
+ * Validates: non-null object + type literal match + elementId is a non-empty string + height is a
+ * finite non-negative number.
+ *
+ * @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;
+
+export { type AddressElementOptions, type AddressInfo, type Appearance, type AppearanceRuleStyle, type AppearanceRuleTarget, type AppearanceVariables, type ApplePayButtonTheme, type ApplePayButtonType, type ApplePayOptions, type AvailableWallets, type BlurEvent, COMMAND_NAMES, type CardElementOptions, type CardFieldElementOptions, type ChangeEvent, type CheckoutError, type CheckoutErrorCategory, type CommandName, type CommandRequestMap, type CommandResponseMap, type ConfirmReq, type ConfirmResp, type CreateElementReq, type CreateElementResp, type DestroyElementReq, type DestroyElementResp, type DestroyReq, type DestroyResp, EVENT_NAMES, type ElementActionReq, type ElementActionResp, type ElementOptions, type ElementReadyEvent, type ElementStatus, type ElementType, type Envelope, EnvelopeDecodeError, ErrorCode, type ErrorCodeValue, type ErrorEvent, type EventName, type EventPayloadMap, type ExpressAvailabilityChangeEvent, type ExpressCheckoutElementOptions, type FocusEvent, type GetPaymentStatusReq, type GetPaymentStatusResp, type GetSessionReq, type GetSessionResp, type GooglePayButtonTheme, type GooglePayButtonType, type GooglePayOptions, IFRAME_RESIZE_MESSAGE_TYPE, type IframeResizeMessage, type InitializeReq, type InitializeResp, type LoadErrorEvent, PROTOCOL_MAJOR, PROTOCOL_NAME, type PaymentAction, type PaymentMethod, type PaymentMethodFilter, type PaymentOutcome, type PaymentResultEvent, type PaymentStateChangeEvent, type PublicPaymentMethod, type PublicProductLine, type PublicSessionView, type ReadyEvent, type RuntimeHello, type TxnStatus, type UpdateCheckoutReq, type UpdateCheckoutResp, type UpdateElementReq, type UpdateElementResp, decodeEnvelope, encodeEnvelope, isCommandName, isEventName, isIframeResizeMessage };