@sunbay/checkout-sdk-js 0.0.0-stage → 0.0.2

package/dist/index.d.cts

@@ -0,0 +1,467 @@
+import { ElementType, CommandName, EventName, ElementOptions, Appearance, ElementStatus, AvailableWallets, PublicSessionView, ConfirmReq, PaymentOutcome, GetPaymentStatusResp, PaymentMethodFilter } from '@sunbay/checkout-sdk-protocol';
+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）。
+ *
+ * 职责：
+ * - 由 `CheckoutInstance.create` 构造（单测时以 mock transport + 构造参注入）。
+ * - 在商户 DOM 目标挂载**可见** iframe，并通过 transport 转发 Element 命令。
+ * - 维护状态机 `created → loading → ready → destroyed`（`loadError` 为旁支）。
+ * - 订阅 transport 的 `elementReady` / `loadError` 事件，按**自身 elementId** 过滤，
+ *   驱动 `mount()` 的 resolve / reject。
+ *
+ * 安全约束（AGENTS/spec）：本层只做 DOM 挂载与协议命令转发，**绝不触碰卡值**。
+ * 卡数据仅存在于托管 iframe 内，不经由本句柄或 transport 传输。
+ */
+
+/**
+ * transport 依赖的最小接口（由 MainFrameTransport 满足）。
+ *
+ * 仅声明 Element 句柄需要的方法，便于单测注入 mock。
+ */
+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 组装）。 */
+interface CheckoutElementOptions {
+    /** Element 唯一 id（由实例生成，用于命令/事件配对）。 */
+    elementId: string;
+    /** Element 类型（决定 iframe 路径与可用动作）。 */
+    type: ElementType;
+    /** 托管页面 origin（不带尾部斜杠）。 */
+    hostOrigin: string;
+    /**
+     * 当前 checkout 会话 id。随 iframe src 以 `?checkoutId=` 下发，供托管字段/element
+     * iframe 加入正确的同源信令频道（`sunbay-checkout:<checkoutId>`）与 main 配对；
+     * 缺失会导致字段频道名不匹配、永不就绪。
+     */
+    checkoutId: string;
+    /** 传输层。 */
+    transport: ElementTransport;
+    /** 初始 Element 配置（随 createElement 下发）。 */
+    initialOptions?: ElementOptions;
+    /**
+     * 句柄销毁回调（由 CheckoutInstance 注入）。`destroy()` 成功销毁时以本 elementId 调用，
+     * 使实例从互斥注册表（elements Map）移除自身，从而允许销毁后重建同类互斥 Element
+     * （如切换 expressCheckout 的 buttonType/buttonHeight 需重建 iframe）。`unmount()` 不调用
+     * （保留句柄、仍占名额、可 remount）。
+     */
+    onDestroy?: (elementId: string) => void;
+    /**
+     * 初始配色方案（来自 createCheckout 的 appearance.colorScheme）。
+     * 仅当提供时拼进 iframe src 的 `&colorScheme=<值>`，使托管 iframe 在首帧即按该
+     * 配色渲染（无闪）。缺省时不拼接，由托管侧按默认（light）处理。运行时切换走
+     * updateCheckout 命令，不走此处。
+     */
+    colorScheme?: 'light' | 'dark' | 'auto';
+    /**
+     * 初始外观定制（来自 createCheckout 的 appearance）。
+     * 仅当含 `variables` 或 `rules` 时序列化进 iframe src 的
+     * `&appearance=<encodeURIComponent(JSON)>`，使托管 iframe 在首帧即按该外观渲染（无闪）。
+     * 仅含 `colorScheme`（无 variables/rules）时不拼接，避免空外观字符串；colorScheme 走独立
+     * `&colorScheme=`。运行时切换走 updateCheckout 命令，不走此处。
+     */
+    appearance?: Appearance;
+}
+declare class CheckoutElement {
+    /** Element 唯一 id。 */
+    readonly elementId: string;
+    /** Element 类型。 */
+    readonly type: ElementType;
+    /** 地址 Element 的 mode（billing/shipping；仅 address 有意义），供实例按 mode 判互斥。 */
+    readonly mode: string | undefined;
+    private readonly hostOrigin;
+    private readonly checkoutId;
+    private readonly transport;
+    private options;
+    /** 初始配色方案（拼进 iframe src；缺省不拼）。 */
+    private readonly colorScheme;
+    /** 初始外观定制（含 variables/rules 时拼进 iframe src；缺省或仅 colorScheme 不拼）。 */
+    private readonly appearance;
+    /** 销毁回调（实例注入）：destroy() 末尾调用，使实例从互斥注册表移除自身以释放名额。 */
+    private readonly onDestroy;
+    private status;
+    private container;
+    private iframe;
+    /** mount 期间临时订阅的事件 handler（resolve/reject 后解绑）。 */
+    private readyHandler;
+    private loadErrorHandler;
+    /**
+     * 仅 expressCheckout：各钱包可用性快照。
+     * 初次来自 elementReady.availableWallets，之后随 expressAvailabilityChange 更新。
+     */
+    private availableWallets;
+    /** 仅 expressCheckout：常驻订阅的 expressAvailabilityChange handler（destroy 时解绑）。 */
+    private availabilityHandler;
+    /**
+     * iframe 自适应高度：挂载期间常驻的 window 'message' 监听器（iframe 消失/销毁时解绑）。
+     * 存引用以便 removeEventListener；null 表示未监听。
+     */
+    private resizeHandler;
+    /** 最近一次已应用的 iframe 高度（px），用于去重，避免冗余 style 写入；null 表示尚未设置。 */
+    private lastHeight;
+    constructor(opts: CheckoutElementOptions);
+    /** 当前状态（只读快照，供外部/测试观测）。 */
+    getStatus(): ElementStatus;
+    /**
+     * 仅 expressCheckout：返回当前各钱包可用性快照（其他类型恒为 undefined）。
+     *
+     * 初值来自 elementReady 的 availableWallets，之后由 expressAvailabilityChange 更新。
+     *
+     * @returns 可用性快照；尚未就绪或非 express 时为 undefined。
+     */
+    getAvailableWallets(): AvailableWallets | undefined;
+    /**
+     * 挂载到商户 DOM 目标：插入可见 iframe、发 createElement、等 elementReady。
+     *
+     * @param selectorOrEl - CSS 选择器或 HTMLElement 容器；容器须唯一且为空。
+     * @returns elementReady 后 resolve；失败移除节点并 reject（loadError / INVALID_OPTIONS）。
+     * @throws 已销毁时抛 INSTANCE_DESTROYED。
+     * @example
+     * await element.mount('#card-field');
+     */
+    mount(selectorOrEl: string | HTMLElement): Promise<void>;
+    /**
+     * 卸载：发 destroyElement、移除 iframe；幂等；保留句柄与配置。
+     *
+     * @returns 完成后 resolve（未挂载时直接 resolve）。
+     * @throws 已销毁时抛 INSTANCE_DESTROYED。
+     */
+    unmount(): Promise<void>;
+    /**
+     * 销毁句柄：幂等；移除 iframe；此后非 destroy/off 调用抛 INSTANCE_DESTROYED。
+     */
+    destroy(): void;
+    /**
+     * 更新 Element 配置：发 updateElement；非法字段由托管侧整次拒绝。
+     *
+     * @param patch - 配置增量。
+     * @returns 成功写回本地 options 后 resolve。
+     * @throws 已销毁时抛 INSTANCE_DESTROYED。
+     */
+    update(patch: Partial<ElementOptions>): Promise<void>;
+    /**
+     * 注册事件 handler（透传到 transport，按事件名分发）。
+     *
+     * @param event - 事件名。
+     * @param handler - 回调。
+     * @throws 已销毁时抛 INSTANCE_DESTROYED。
+     */
+    on(event: EventName, handler: (payload: unknown) => void): void;
+    /**
+     * 注销事件 handler（销毁后仍可安全调用）。
+     *
+     * @param event - 事件名。
+     * @param handler - 先前注册的回调。
+     */
+    off(event: EventName, handler: (payload: unknown) => void): void;
+    /** 聚焦（仅输入类，expressCheckout 不提供）。 */
+    focus?: () => Promise<void>;
+    /** 失焦（仅输入类，expressCheckout 不提供）。 */
+    blur?: () => Promise<void>;
+    /** 清空（仅输入类，expressCheckout 不提供）。 */
+    clear?: () => Promise<void>;
+    /** 已挂载后安装输入类动作方法（由构造后自动调用）。 */
+    private installInputActions;
+    /**
+     * 仅 expressCheckout：常驻订阅 expressAvailabilityChange，更新本地可用性快照。
+     *
+     * 该事件载荷不含 elementId；express 为单例（由 CheckoutInstance 保证），
+     * 故无需按 elementId 过滤。非 express 类型不订阅。
+     */
+    private installExpressAvailability;
+    /** 发送一条输入类动作命令（销毁后同步抛 INSTANCE_DESTROYED）。 */
+    private sendAction;
+    /** 若已销毁则抛 INSTANCE_DESTROYED。 */
+    private assertAlive;
+    /** 解析挂载容器（选择器须唯一命中一个元素）。 */
+    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}）。
+     *
+     * elementId 随 src 下发，供托管 child 在 iframe-resize 消息中原样回传，父窗口据此在
+     * 同页多个 iframe 间按句柄分发高度。
+     */
+    private resolveSrc;
+    /**
+     * 构造 expressCheckout 专属 query 片段（仅 expressCheckout 调用）：
+     * - 钱包显式置为 `false` → `&applePay=false` / `&googlePay=false`（强制隐藏，保持
+     *   既有开关语义；`true` / 缺省 → 自动，不拼开关）；
+     * - 钱包以对象形态配置且含 `buttonType` → `&applePayButtonType=<v>` /
+     *   `&googlePayButtonType=<v>`（布尔开关 / 缺省 → 不拼）；
+     * - 全局 `buttonHeight`（有限数）→ `&buttonHeight=<n>`。
+     *
+     * 仅在有值时拼接；不拼空串。本片段不触碰卡值，仅承载展示配置。
+     *
+     * @returns 以 `&` 起始的 query 片段（无可拼项时返回空串）。
+     */
+    private resolveExpressQuery;
+    /**
+     * 安装 iframe 自适应高度监听：订阅 window 'message'，仅采信来自本 iframe
+     * `contentWindow` 且 origin === hostOrigin 的合法 {@link IframeResizeMessage}，
+     * 且 elementId 与本句柄匹配时，将外层 iframe 高度调整为内容真实高度（宽度保持 100%）。
+     *
+     * 安全：先校验 `event.source === iframe.contentWindow`（关键来源校验），
+     * 再校验 `event.origin === hostOrigin`（更严格的同源校验），防跨源伪造。
+     * 高度去重：与上次相同则跳过，避免冗余 style 写入。
+     */
+    private installResizeListener;
+    /** 解绑 iframe 自适应高度监听并重置去重状态（幂等）。 */
+    private teardownResizeListener;
+    /** 移除 iframe DOM 节点（若存在），并解绑自适应高度监听。 */
+    private removeIframe;
+    /** 工厂：等价于 `new CheckoutElement(opts)`（供 CheckoutInstance 统一入口）。 */
+    static create(opts: CheckoutElementOptions): CheckoutElement;
+}
+
+/**
+ * CheckoutInstance —— 商户侧结账实例句柄（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` 一律忽略。
+ *
+ * 安全约束（AGENTS/spec）：本层只搬运协议命令/事件，**绝不触碰卡值**。
+ */
+
+/**
+ * CheckoutInstance 依赖的最小 transport 接口（由 MainFrameTransport 满足）。
+ *
+ * 比 ElementTransport 多出 `onHello/createHiddenIframe/destroy`，供 createCheckout
+ * 握手接线与实例销毁使用。单测可注入 mock。
+ */
+interface InstanceTransport {
+    request(name: CommandName, payload: unknown): Promise<unknown>;
+    on(event: EventName, handler: (payload: unknown) => void): void;
+    off(event: EventName, handler: (payload: unknown) => void): void;
+    onHello(handler: (hello: unknown) => void): void;
+    setRuntimeId(runtimeId: string): void;
+    createHiddenIframe(): unknown;
+    destroy(): void;
+}
+/** CheckoutInstance 构造参数（由 createCheckout 组装）。 */
+interface CheckoutInstanceOptions {
+    /** 结账唯一 id。 */
+    checkoutId: string;
+    /** 协商后的运行时 id（来自 RuntimeHello）。 */
+    runtimeId: string;
+    /** 托管页面 origin（不带尾部斜杠）。 */
+    hostOrigin: string;
+    /** 已就绪 transport。 */
+    transport: InstanceTransport;
+    /** initialize 返回的 capabilities。 */
+    capabilities: string[];
+    /** initialize 返回的初始会话视图。 */
+    session: PublicSessionView;
+    /**
+     * 初始外观定制（来自 createCheckout 的 appearance）。
+     * 透传给每个 create 出的 Element，序列化进其 iframe src（首帧无闪）：
+     * - colorScheme 拼 `&colorScheme=`；
+     * - variables/rules 拼 `&appearance=`（仅当非空）。
+     * 缺省不拼接。运行时切换走 updateCheckout 命令。
+     */
+    appearance?: Appearance;
+}
+/** confirm 可选参数（对齐 ConfirmReq，去掉由实例生成的 operationId）。 */
+type ConfirmOptions = Omit<ConfirmReq, 'operationId'>;
+declare class CheckoutInstance {
+    /** 结账唯一 id。 */
+    readonly checkoutId: string;
+    /** 协商后的运行时 id。 */
+    readonly runtimeId: string;
+    /** 协商后的能力集合。 */
+    readonly capabilities: readonly string[];
+    private readonly hostOrigin;
+    private readonly transport;
+    private session;
+    /** 初始外观定制（透传给 create 出的每个 Element 的 iframe src）。 */
+    private readonly appearance;
+    /** 已创建的 Element（按 elementId 索引）。 */
+    /**
+     * 互斥注册表的**单一数据源**：elementId → 已创建的 CheckoutElement。
+     * 互斥判定由本 Map 实时推导（见 {@link assertNoConflict}），元素 `destroy()` 经
+     * {@link releaseElement} 从本 Map 移除以释放名额（允许销毁后重建同类互斥 Element）。
+     */
+    private readonly elements;
+    /** 当前未决 confirm（同一时刻至多一个）。 */
+    private pendingConfirm;
+    /** paymentResult 事件订阅 handler（destroy 时解绑）。 */
+    private readonly paymentResultHandler;
+    private destroyed;
+    constructor(opts: CheckoutInstanceOptions);
+    /**
+     * 创建一个 Element 句柄（不自动挂载；互斥冲突抛 ELEMENT_CONFLICT）。
+     *
+     * 互斥规则（spec 6）：
+     * - 聚合 `card` 与任一拆分字段（cardNumber/cardExpiry/cardCvc）互斥。
+     * - 同 `mode`（billing/shipping）的 address 不可重复。
+     * - `expressCheckout` 单例。
+     *
+     * @param type - Element 类型。
+     * @param options - 初始 Element 配置。
+     * @returns 新建的 CheckoutElement。
+     * @throws 已销毁时抛 INSTANCE_DESTROYED；互斥冲突抛 ELEMENT_CONFLICT。
+     */
+    create(type: ElementType, options?: ElementOptions): CheckoutElement;
+    /**
+     * 发起支付确认。生成 operationId，发 confirm 命令拿 accepted，返回的 Promise
+     * 由后续同 operationId 的 paymentResult 事件兑现。进行中再次调用 → CHECKOUT_BUSY。
+     *
+     * @param opts - 账单/配送地址、姓名、邮箱、returnUrl 等可选参数。
+     * @returns 支付终态结果 PaymentOutcome。
+     * @throws 已销毁时 reject INSTANCE_DESTROYED；进行中 reject CHECKOUT_BUSY。
+     */
+    confirm(opts?: ConfirmOptions): Promise<PaymentOutcome>;
+    /**
+     * 获取最新会话视图（透传 getSession 命令并写回本地快照）。
+     *
+     * @returns 最新 PublicSessionView。
+     * @throws 已销毁时 reject INSTANCE_DESTROYED。
+     */
+    getSession(): Promise<PublicSessionView>;
+    /**
+     * 刷新会话（透传 refresh 命令并写回本地快照）。
+     *
+     * @returns 刷新后的 PublicSessionView。
+     * @throws 已销毁时 reject INSTANCE_DESTROYED。
+     */
+    refresh(): Promise<PublicSessionView>;
+    /**
+     * 查询支付状态（原样返回 TxnStatus，不转义）。
+     *
+     * @returns txnStatus（可能含 txnId）。
+     * @throws 已销毁时 reject INSTANCE_DESTROYED。
+     */
+    getPaymentStatus(): Promise<GetPaymentStatusResp>;
+    /**
+     * 更新结账外观/语言（不改会话或金额）。
+     *
+     * @param patch - locale / appearance 增量。
+     * @throws 已销毁时 reject INSTANCE_DESTROYED。
+     */
+    updateCheckout(patch: {
+        locale?: string;
+        appearance?: Appearance;
+    }): Promise<void>;
+    /**
+     * 注册 Checkout 级事件 handler（透传 transport）。
+     *
+     * @param event - 事件名。
+     * @param handler - 回调。
+     * @throws 已销毁时抛 INSTANCE_DESTROYED。
+     */
+    on(event: EventName, handler: (payload: unknown) => void): void;
+    /**
+     * 注销事件 handler（销毁后仍可安全调用）。
+     *
+     * @param event - 事件名。
+     * @param handler - 先前注册的回调。
+     */
+    off(event: EventName, handler: (payload: unknown) => void): void;
+    /**
+     * 销毁实例：幂等。释放全部 Element、解绑 paymentResult 监听、以
+     * INSTANCE_DESTROYED reject 未决 confirm、发 destroy 命令并销毁 transport。
+     * 此后迟到的 paymentResult 一律忽略，不改写已结束的 Promise。
+     */
+    destroy(): void;
+    /** 若已销毁则抛 INSTANCE_DESTROYED。 */
+    private assertAlive;
+    /** 互斥检查：冲突时抛 ELEMENT_CONFLICT（由 elements Map 实时推导，不改变注册表）。 */
+    private assertNoConflict;
+    /**
+     * 元素 `destroy()` 回调：从互斥注册表（elements Map）移除该 elementId，释放名额。
+     * 幂等；实例整体 destroy 时（已置 destroyed）走统一 `elements.clear()` 路径，此处 no-op，
+     * 避免遍历 elements 调 element.destroy() 时的并发修改。
+     */
+    private releaseElement;
+    /** 处理 paymentResult 事件：按 operationId 兑现未决 confirm；迟到/不匹配忽略。 */
+    private handlePaymentResult;
+}
+
+/**
+ * 运行环境标识。
+ * - `dev`：开发/测试托管页面。
+ * - `prod`：生产托管页面。
+ */
+type Env = 'dev' | 'prod';
+
+/**
+ * createCheckout —— 商户 SDK 的唯一异步入口（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}。
+ *
+ * 安全约束（AGENTS/spec）：本层只做握手/初始化编排，**绝不触碰卡值**。
+ */
+
+/**
+ * 创建 CheckoutInstance 时可注入的内部 transport 工厂（仅供测试/高级定制）。
+ *
+ * 真实场景使用内置 MainFrameTransport；测试可注入 mock 以驱动 hello/事件。
+ */
+type TransportFactory = (args: {
+    checkoutId: string;
+    hostOrigin: string;
+}) => InstanceTransport;
+/** createCheckout 参数。 */
+interface CreateCheckoutOptions {
+    /** 后端创建的结账会话 id（必填）。 */
+    sessionId: string;
+    /** 运行环境（dev/prod），默认 dev。 */
+    env?: Env;
+    /** 覆盖托管 origin（优先于 env）。 */
+    hostOrigin?: string;
+    /** 语言。 */
+    locale?: string;
+    /** 外观定制。 */
+    appearance?: Appearance;
+    /** 支付方式过滤（只做减法/排序）。 */
+    paymentMethods?: PaymentMethodFilter;
+    /** 内部注入点：自定义 transport 工厂（测试用，不属于公开 API 契约）。 */
+    __transportFactory?: TransportFactory;
+}
+/**
+ * 创建一个结账实例：握手 + 初始化成功后 resolve。
+ *
+ * @param opts - 结账参数。
+ * @returns 就绪的 CheckoutInstance。
+ * @throws reject RUNTIME_LOAD_FAILED（握手超时）/ PROTOCOL_UNSUPPORTED（无共同主版本）
+ *         / 或 initialize 的业务错误。
+ * @example
+ * const checkout = await createCheckout({ sessionId: 'sess_x', env: 'prod' });
+ */
+declare function createCheckout(opts: CreateCheckoutOptions): Promise<CheckoutInstance>;
+
+/**
+ * @sunbay/checkout-js 公共入口（真源）。
+ *
+ * 导出 `createCheckout` 入口、`CheckoutInstance` / `CheckoutElement` 句柄类型，
+ * 以及协议公开类型（供 TS 使用者消费）。
+ * IIFE 产物下，额外在 `window.SunbayCheckout` 暴露 `{ createCheckout }`。
+ */
+
+declare const version: string;
+
+export { CheckoutElement, type CheckoutElementOptions, CheckoutInstance, type CheckoutInstanceOptions, type ConfirmOptions, type CreateCheckoutOptions, type ElementTransport, type Env, type InstanceTransport, type TransportFactory, createCheckout, version };