@sunbay/checkout-sdk-protocol 0.0.0-stage → 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,488 @@
+/**
+ * 协议公开类型（真源）。
+ *
+ * 这些类型对外公开，供商户侧 SDK（transport/CheckoutInstance/Element）与
+ * checkout 托管侧同步副本共同引用。字段与 checkout 后端现有类型对齐，但
+ * 对外视图（PublicSessionView）**不含** rsaPublicKey 等敏感/内部字段。
+ */
+/**
+ * 交易状态（直接复用 checkout 后端 TxnStatus，不转义）。
+ * - `I` = 未支付 / 已创建（非终态）
+ * - `S` = 成功（终态）
+ * - `F` = 失败（终态）
+ * - `R` = 需跳转 / 处理中（非终态）
+ */
+type TxnStatus = 'I' | 'S' | 'F' | 'R';
+/**
+ * 地址信息（对齐 checkout 后端 AddressInfo 字段）。
+ * 非敏感数据，允许经公共协议传输。
+ */
+interface AddressInfo {
+    country: string;
+    state?: string;
+    city: string;
+    line1: string;
+    line2?: string;
+    postalCode: string;
+    district?: string;
+    firstName?: string;
+    lastName?: string;
+    recipientName?: string;
+    phone?: string;
+}
+/** 首期支持的支付方式。 */
+type PaymentMethod = 'card' | 'applePay' | 'googlePay';
+/**
+ * 公开支付方式视图（对外只暴露 method/type/name/logoUrl，不含内部配置）。
+ */
+interface PublicPaymentMethod {
+    method: string;
+    type: string;
+    name: string;
+    logoUrl: string;
+}
+/** 公开商品行。 */
+interface PublicProductLine {
+    amount: number;
+    name: string;
+    num: string;
+}
+/**
+ * 公开 Session 视图：金额 / 币种 / 商品 / collect 标记 / 可用支付方式 / 商户信息。
+ * **不含** rsaPublicKey 等敏感或内部字段。
+ */
+interface PublicSessionView {
+    sessionId: string;
+    sessionType: string;
+    currency: string;
+    totalAmount: number;
+    productList: PublicProductLine[];
+    taxAmount: number;
+    productAmount: number;
+    description: string;
+    expiresAt: string;
+    collectBillingAddress: boolean;
+    collectShippingAddress: boolean;
+    paymentMethods: PublicPaymentMethod[];
+    merchantName: string;
+    merchantLogoUrl: string;
+    merchantReturnUrl?: string;
+}
+/**
+ * 支付结果四态（spec 8.2）。
+ * `pending` 非终态，消费者不得只接受首条结果。
+ */
+type PaymentOutcome = {
+    status: 'succeeded';
+    operationId: string;
+    txnId: string;
+} | {
+    status: 'failed';
+    operationId: string;
+    txnId?: string;
+    error: CheckoutError;
+} | {
+    status: 'canceled';
+    operationId: string;
+} | {
+    status: 'pending';
+    operationId: string;
+    txnId?: string;
+};
+/** 错误分类（spec 5.4）。 */
+type CheckoutErrorCategory = 'configuration' | 'validation' | 'network' | 'runtime' | 'payment';
+/**
+ * 结构化错误（spec 5.4）。
+ */
+interface CheckoutError {
+    code: string;
+    /** 展示用消息。 */
+    message: string;
+    category: CheckoutErrorCategory;
+    errorId: string;
+    elementId?: string;
+    field?: string;
+    traceId?: string;
+}
+/**
+ * 外观定制（appearance）。首期为开放映射，交由托管侧解释。
+ */
+interface Appearance {
+    theme?: string;
+    variables?: Record<string, string>;
+}
+/**
+ * 支付方式过滤配置（spec 9：只做减法/排序，禁止前端增开）。
+ */
+interface PaymentMethodFilter {
+    /** 要隐藏的支付方式（method 标识）。 */
+    hide?: string[];
+    /** 展示顺序（method 标识）。 */
+    order?: string[];
+}
+/** 可挂载 Element 类型（spec 6）。 */
+type ElementType = 'card' | 'cardNumber' | 'cardExpiry' | 'cardCvc' | 'address' | 'expressCheckout';
+/** card Element 配置（spec 6）。 */
+interface CardElementOptions {
+    showBillingAddress?: boolean;
+    showShippingAddress?: boolean;
+    showPostalCode?: boolean;
+    appearance?: Appearance;
+}
+/** 拆分卡字段配置（spec 6）。 */
+interface CardFieldElementOptions {
+    appearance?: Appearance;
+}
+/** address Element 配置（spec 6）。 */
+interface AddressElementOptions {
+    mode: 'billing' | 'shipping';
+    appearance?: Appearance;
+}
+/** expressCheckout Element 配置（spec 6）。 */
+interface ExpressCheckoutElementOptions {
+    /**
+     * 各钱包开关（商户显式控制）：
+     * - `false`：强制隐藏该钱包；
+     * - `true` 或缺省：自动模式，按后端业务允许 ∩ 环境可用展示。
+     */
+    paymentMethods?: {
+        applePay?: boolean;
+        googlePay?: boolean;
+    };
+    /** 布局约束（首期仅最大列数）。 */
+    layout?: {
+        maxColumns?: number;
+    };
+    /** 按钮主题（按钱包区分）。 */
+    buttonTheme?: {
+        applePay?: string;
+        googlePay?: string;
+    };
+    /** 按钮高度（像素）。 */
+    buttonHeight?: number;
+}
+/**
+ * express 可用钱包视图（spec 6）。
+ * 表示各钱包在当前环境下是否可用，用于 express 可用性事件载荷。
+ */
+interface AvailableWallets {
+    applePay: boolean;
+    googlePay: boolean;
+}
+/** Element 配置联合（按 type 区分）。 */
+type ElementOptions = CardElementOptions | CardFieldElementOptions | AddressElementOptions | ExpressCheckoutElementOptions;
+/** Element 运行状态机（spec 6）。 */
+type ElementStatus = 'created' | 'loading' | 'ready' | 'destroyed' | 'loadError';
+/** action 载荷（spec 8.3；qrCode/showContent 首期预留）。 */
+interface PaymentAction {
+    type: 'qrCode' | 'redirect' | 'showContent';
+    redirectUrl?: string;
+    qrData?: string;
+    content?: string;
+}
+
+/**
+ * 信封与握手契约（spec 5.1，真源）。
+ *
+ * 协议名 `sunbay-checkout`，`major = 1`。与现有 Native Bridge `{v:1,type,...}`
+ * 是不同协议，数字相同不代表兼容。
+ *
+ * `encodeEnvelope`/`decodeEnvelope`：JSON 序列化 + 最小运行时结构校验
+ * （校验 protocol/major/kind/必填字段），非法抛错。解码器**不**校验 request.name
+ * 是否为已知 CommandName —— 未知 name 仍解为 kind==='request'，由调用方拒绝。
+ */
+
+/** 协议名常量。 */
+declare const PROTOCOL_NAME: "sunbay-checkout";
+/** 当前主版本。 */
+declare const PROTOCOL_MAJOR: 1;
+/**
+ * 握手消息（spec 5.1）。main iframe 加载后先广播，此时尚无 checkoutId。
+ */
+type RuntimeHello = {
+    protocol: 'sunbay-checkout';
+    kind: 'hello';
+    runtimeId: string;
+    supportedMajorVersions: number[];
+    /** 首期：['card','splitCard','address','express','paymentMethodFilter']。 */
+    capabilities: string[];
+};
+/**
+ * 初始化后的公共信封（spec 5.1）。
+ */
+type Envelope = {
+    protocol: 'sunbay-checkout';
+    major: 1;
+    runtimeId: string;
+    checkoutId: string;
+    elementId?: string;
+} & ({
+    kind: 'request';
+    requestId: string;
+    name: string;
+    payload: unknown;
+} | {
+    kind: 'response';
+    requestId: string;
+    ok: true;
+    data: unknown;
+} | {
+    kind: 'response';
+    requestId: string;
+    ok: false;
+    error: CheckoutError;
+} | {
+    kind: 'event';
+    eventId: string;
+    name: string;
+    operationId?: string;
+    payload: unknown;
+});
+/** 协议校验失败错误。 */
+declare class EnvelopeDecodeError extends Error {
+    constructor(message: string);
+}
+/**
+ * 将信封序列化为线缆字符串（JSON）。
+ *
+ * @param envelope 待发送的信封
+ * @returns JSON 字符串
+ * @example
+ * const wire = encodeEnvelope({ protocol: 'sunbay-checkout', major: 1, ... });
+ */
+declare function encodeEnvelope(envelope: Envelope): string;
+/**
+ * 解析并最小结构校验信封。非法（缺 protocol、错 major、非法 kind、缺必填字段、
+ * 非 JSON）一律抛 {@link EnvelopeDecodeError}。
+ *
+ * 注意：解码器不校验 request.name 是否为已知命令 —— 未知 name 仍解为
+ * kind==='request'，交由调用方（如 Orchestrator）拒绝。
+ *
+ * @param wire 线缆字符串
+ * @returns 已校验结构的信封
+ * @example
+ * const env = decodeEnvelope(wire);
+ * if (env.kind === 'request') { ... }
+ */
+declare function decodeEnvelope(wire: string): Envelope;
+
+/**
+ * 协议错误码常量（单一真源，spec 5.4）。
+ *
+ * 不提供可能误导重复付款的通用 `retryable` 布尔。
+ * 仅保留实际会被产出的错误码；新增码须同时有产出点。
+ */
+declare const ErrorCode: {
+    readonly INVALID_OPTIONS: "INVALID_OPTIONS";
+    readonly ELEMENT_CONFLICT: "ELEMENT_CONFLICT";
+    readonly INSTANCE_DESTROYED: "INSTANCE_DESTROYED";
+    readonly CHECKOUT_BUSY: "CHECKOUT_BUSY";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly SESSION_LOAD_FAILED: "SESSION_LOAD_FAILED";
+    readonly RUNTIME_LOAD_FAILED: "RUNTIME_LOAD_FAILED";
+    readonly PROTOCOL_UNSUPPORTED: "PROTOCOL_UNSUPPORTED";
+    readonly REQUEST_TIMEOUT: "REQUEST_TIMEOUT";
+    readonly PAYMENT_FLOW_ERROR: "PAYMENT_FLOW_ERROR";
+    readonly UNSUPPORTED_CAPABILITY: "UNSUPPORTED_CAPABILITY";
+};
+/** 错误码字面量联合类型。 */
+type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+/**
+ * 命令契约（商户 SDK → main，spec 5.2 表，真源）。
+ *
+ * 每命令的请求/响应类型在此定义；跨通道只传 JSON 可序列化数据。
+ */
+
+/** 全部命令名（spec 5.2）。 */
+type CommandName = 'initialize' | 'createElement' | 'updateElement' | 'destroyElement' | 'focus' | 'blur' | 'clear' | 'updateCheckout' | 'getSession' | 'refresh' | 'getPaymentStatus' | 'confirm' | 'destroy';
+/** 已知命令名集合（供调用方校验 request.name 是否受支持）。 */
+declare const COMMAND_NAMES: readonly CommandName[];
+/** 判断字符串是否为已知命令名。 */
+declare function isCommandName(name: string): name is CommandName;
+interface InitializeReq {
+    sessionId: string;
+    locale?: string;
+    appearance?: Appearance;
+    paymentMethods?: PaymentMethodFilter;
+}
+interface InitializeResp {
+    capabilities: string[];
+    session: PublicSessionView;
+}
+interface CreateElementReq {
+    elementId: string;
+    type: ElementType;
+    options?: ElementOptions;
+}
+interface CreateElementResp {
+    elementId: string;
+    registered: true;
+}
+interface UpdateElementReq {
+    elementId: string;
+    patch: Partial<ElementOptions>;
+}
+interface UpdateElementResp {
+    elementId: string;
+    options: ElementOptions;
+}
+interface DestroyElementReq {
+    elementId: string;
+}
+interface DestroyElementResp {
+    elementId: string;
+    released: true;
+}
+interface ElementActionReq {
+    elementId: string;
+}
+interface ElementActionResp {
+    elementId: string;
+    done: true;
+}
+interface UpdateCheckoutReq {
+    locale?: string;
+    appearance?: Appearance;
+}
+interface UpdateCheckoutResp {
+    updated: true;
+}
+type GetSessionReq = Record<string, never>;
+type GetSessionResp = PublicSessionView;
+type GetPaymentStatusReq = Record<string, never>;
+interface GetPaymentStatusResp {
+    txnStatus: TxnStatus;
+    txnId?: string;
+}
+interface ConfirmReq {
+    operationId: string;
+    billingAddress?: AddressInfo;
+    shippingAddress?: AddressInfo;
+    customerName?: string;
+    email?: string;
+    returnUrl?: string;
+}
+interface ConfirmResp {
+    accepted: true;
+}
+type DestroyReq = Record<string, never>;
+interface DestroyResp {
+    released: true;
+}
+/** 命令名 → 请求载荷映射。 */
+interface CommandRequestMap {
+    initialize: InitializeReq;
+    createElement: CreateElementReq;
+    updateElement: UpdateElementReq;
+    destroyElement: DestroyElementReq;
+    focus: ElementActionReq;
+    blur: ElementActionReq;
+    clear: ElementActionReq;
+    updateCheckout: UpdateCheckoutReq;
+    getSession: GetSessionReq;
+    refresh: GetSessionReq;
+    getPaymentStatus: GetPaymentStatusReq;
+    confirm: ConfirmReq;
+    destroy: DestroyReq;
+}
+/** 命令名 → 成功响应载荷映射。 */
+interface CommandResponseMap {
+    initialize: InitializeResp;
+    createElement: CreateElementResp;
+    updateElement: UpdateElementResp;
+    destroyElement: DestroyElementResp;
+    focus: ElementActionResp;
+    blur: ElementActionResp;
+    clear: ElementActionResp;
+    updateCheckout: UpdateCheckoutResp;
+    getSession: GetSessionResp;
+    refresh: GetSessionResp;
+    getPaymentStatus: GetPaymentStatusResp;
+    confirm: ConfirmResp;
+    destroy: DestroyResp;
+}
+
+/**
+ * 事件契约（main → 商户 SDK，spec 5.3 表，真源）。
+ *
+ * 公开事件仅暴露 empty/complete/brand/error 等允许状态，**绝不含卡值**，
+ * 不提供卡数据 getValue。`on` 注册后不重放历史事件。
+ */
+
+/** 全部事件名（spec 5.3）。 */
+type EventName = 'ready' | 'change' | 'focus' | 'blur' | 'loadError' | 'elementReady' | 'availablePaymentMethodsChange' | 'expressAvailabilityChange' | 'paymentStateChange' | 'paymentResult' | 'error';
+/** 已知事件名集合。 */
+declare const EVENT_NAMES: readonly EventName[];
+/** 判断字符串是否为已知事件名。 */
+declare function isEventName(name: string): name is EventName;
+interface ReadyEvent {
+    elementId: string;
+}
+interface ElementReadyEvent {
+    elementId: string;
+    /** 仅 expressCheckout Element ready 时携带：各钱包可用性。 */
+    availableWallets?: AvailableWallets;
+}
+interface ChangeEvent {
+    elementId: string;
+    empty: boolean;
+    complete: boolean;
+    error?: CheckoutError;
+    /** 仅卡号字段允许携带 brand；绝不含卡值。 */
+    brand?: string;
+}
+interface FocusEvent {
+    elementId: string;
+}
+interface BlurEvent {
+    elementId: string;
+}
+interface LoadErrorEvent {
+    elementId: string;
+    error: CheckoutError;
+}
+interface AvailablePaymentMethodsChangeEvent {
+    availablePaymentMethods: PublicPaymentMethod[];
+}
+/**
+ * express 可用钱包变化事件（spec 6）。
+ * 专用于 expressCheckout：以 AvailableWallets 表达各钱包可用性，
+ * 与 AvailablePaymentMethodsChangeEvent（PublicPaymentMethod[]）并存，互不破坏。
+ */
+interface ExpressAvailabilityChangeEvent {
+    availableWallets: AvailableWallets;
+}
+interface PaymentStateChangeEvent {
+    operationId: string;
+    method: PaymentMethod;
+    /** 过程状态；requiresAction 时携带 action 信息。 */
+    state: string;
+    action?: PaymentAction;
+}
+interface PaymentResultEvent {
+    operationId: string;
+    method: PaymentMethod;
+    outcome: PaymentOutcome;
+}
+interface ErrorEvent {
+    /** 异步主动流程错误；可含 operationId（如已创建）。 */
+    operationId?: string;
+    error: CheckoutError;
+}
+/** 事件名 → 载荷映射。 */
+interface EventPayloadMap {
+    ready: ReadyEvent;
+    change: ChangeEvent;
+    focus: FocusEvent;
+    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 };

package/dist/index.mjs

@@ -0,0 +1,153 @@
+// src/envelope.ts
+var PROTOCOL_NAME = "sunbay-checkout";
+var PROTOCOL_MAJOR = 1;
+var ENVELOPE_KINDS = ["request", "response", "event"];
+var EnvelopeDecodeError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EnvelopeDecodeError";
+  }
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function assertString(obj, key) {
+  if (typeof obj[key] !== "string") {
+    throw new EnvelopeDecodeError(`Envelope field "${key}" is missing or not a string`);
+  }
+}
+function encodeEnvelope(envelope) {
+  return JSON.stringify(envelope);
+}
+function decodeEnvelope(wire) {
+  let parsed;
+  try {
+    parsed = JSON.parse(wire);
+  } catch {
+    throw new EnvelopeDecodeError("Envelope is not valid JSON");
+  }
+  if (!isRecord(parsed)) {
+    throw new EnvelopeDecodeError("Envelope must be an object");
+  }
+  if (parsed.protocol !== PROTOCOL_NAME) {
+    throw new EnvelopeDecodeError(
+      `protocol must be "${PROTOCOL_NAME}", received ${JSON.stringify(parsed.protocol)}`
+    );
+  }
+  if (parsed.major !== PROTOCOL_MAJOR) {
+    throw new EnvelopeDecodeError(
+      `major must be ${PROTOCOL_MAJOR}, received ${JSON.stringify(parsed.major)}`
+    );
+  }
+  assertString(parsed, "runtimeId");
+  assertString(parsed, "checkoutId");
+  if (parsed.elementId !== void 0 && typeof parsed.elementId !== "string") {
+    throw new EnvelopeDecodeError("elementId must be a string when present");
+  }
+  const kind = parsed.kind;
+  if (typeof kind !== "string" || !ENVELOPE_KINDS.includes(kind)) {
+    throw new EnvelopeDecodeError(`Invalid kind: ${JSON.stringify(kind)}`);
+  }
+  switch (kind) {
+    case "request": {
+      assertString(parsed, "requestId");
+      assertString(parsed, "name");
+      if (!("payload" in parsed)) {
+        throw new EnvelopeDecodeError("request envelope is missing payload");
+      }
+      break;
+    }
+    case "response": {
+      assertString(parsed, "requestId");
+      if (typeof parsed.ok !== "boolean") {
+        throw new EnvelopeDecodeError("response envelope is missing boolean ok");
+      }
+      if (parsed.ok === true) {
+        if (!("data" in parsed)) {
+          throw new EnvelopeDecodeError("successful response is missing data");
+        }
+      } else if (!isRecord(parsed.error)) {
+        throw new EnvelopeDecodeError("failed response is missing error object");
+      }
+      break;
+    }
+    case "event": {
+      assertString(parsed, "eventId");
+      assertString(parsed, "name");
+      if (!("payload" in parsed)) {
+        throw new EnvelopeDecodeError("event envelope is missing payload");
+      }
+      if ("operationId" in parsed && parsed.operationId !== void 0 && typeof parsed.operationId !== "string") {
+        throw new EnvelopeDecodeError("operationId must be a string when present");
+      }
+      break;
+    }
+  }
+  return parsed;
+}
+
+// src/errors.ts
+var ErrorCode = {
+  INVALID_OPTIONS: "INVALID_OPTIONS",
+  ELEMENT_CONFLICT: "ELEMENT_CONFLICT",
+  INSTANCE_DESTROYED: "INSTANCE_DESTROYED",
+  CHECKOUT_BUSY: "CHECKOUT_BUSY",
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  SESSION_LOAD_FAILED: "SESSION_LOAD_FAILED",
+  RUNTIME_LOAD_FAILED: "RUNTIME_LOAD_FAILED",
+  PROTOCOL_UNSUPPORTED: "PROTOCOL_UNSUPPORTED",
+  REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
+  PAYMENT_FLOW_ERROR: "PAYMENT_FLOW_ERROR",
+  UNSUPPORTED_CAPABILITY: "UNSUPPORTED_CAPABILITY"
+};
+
+// src/commands.ts
+var COMMAND_NAMES = [
+  "initialize",
+  "createElement",
+  "updateElement",
+  "destroyElement",
+  "focus",
+  "blur",
+  "clear",
+  "updateCheckout",
+  "getSession",
+  "refresh",
+  "getPaymentStatus",
+  "confirm",
+  "destroy"
+];
+function isCommandName(name) {
+  return COMMAND_NAMES.includes(name);
+}
+
+// src/events.ts
+var EVENT_NAMES = [
+  "ready",
+  "change",
+  "focus",
+  "blur",
+  "loadError",
+  "elementReady",
+  "availablePaymentMethodsChange",
+  "expressAvailabilityChange",
+  "paymentStateChange",
+  "paymentResult",
+  "error"
+];
+function isEventName(name) {
+  return EVENT_NAMES.includes(name);
+}
+export {
+  COMMAND_NAMES,
+  EVENT_NAMES,
+  EnvelopeDecodeError,
+  ErrorCode,
+  PROTOCOL_MAJOR,
+  PROTOCOL_NAME,
+  decodeEnvelope,
+  encodeEnvelope,
+  isCommandName,
+  isEventName
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/envelope.ts","../src/errors.ts","../src/commands.ts","../src/events.ts"],"sourcesContent":["/**\n * 信封与握手契约（spec 5.1，真源）。\n *\n * 协议名 `sunbay-checkout`，`major = 1`。与现有 Native Bridge `{v:1,type,...}`\n * 是不同协议，数字相同不代表兼容。\n *\n * `encodeEnvelope`/`decodeEnvelope`：JSON 序列化 + 最小运行时结构校验\n * （校验 protocol/major/kind/必填字段），非法抛错。解码器**不**校验 request.name\n * 是否为已知 CommandName —— 未知 name 仍解为 kind==='request'，由调用方拒绝。\n */\n\nimport type { CheckoutError } from './types';\n\n/** 协议名常量。 */\nexport const PROTOCOL_NAME = 'sunbay-checkout' as const;\n/** 当前主版本。 */\nexport const PROTOCOL_MAJOR = 1 as const;\n\n/**\n * 握手消息（spec 5.1）。main iframe 加载后先广播，此时尚无 checkoutId。\n */\nexport type RuntimeHello = {\n    protocol: 'sunbay-checkout';\n    kind: 'hello';\n    runtimeId: string;\n    supportedMajorVersions: number[];\n    /** 首期：['card','splitCard','address','express','paymentMethodFilter']。 */\n    capabilities: string[];\n};\n\n/**\n * 初始化后的公共信封（spec 5.1）。\n */\nexport type Envelope = {\n    protocol: 'sunbay-checkout';\n    major: 1;\n    runtimeId: string;\n    checkoutId: string;\n    elementId?: string;\n} & (\n    | { kind: 'request'; requestId: string; name: string; payload: unknown }\n    | { kind: 'response'; requestId: string; ok: true; data: unknown }\n    | { kind: 'response'; requestId: string; ok: false; error: CheckoutError }\n    | { kind: 'event'; eventId: string; name: string; operationId?: string; payload: unknown }\n);\n\n/** 合法 kind 集合。 */\nconst ENVELOPE_KINDS = ['request', 'response', 'event'] as const;\n\n/** 协议校验失败错误。 */\nexport class EnvelopeDecodeError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = 'EnvelopeDecodeError';\n    }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n    return typeof value === 'object' && value !== null;\n}\n\nfunction assertString(obj: Record<string, unknown>, key: string): void {\n    if (typeof obj[key] !== 'string') {\n        throw new EnvelopeDecodeError(`Envelope field \"${key}\" is missing or not a string`);\n    }\n}\n\n/**\n * 将信封序列化为线缆字符串（JSON）。\n *\n * @param envelope 待发送的信封\n * @returns JSON 字符串\n * @example\n * const wire = encodeEnvelope({ protocol: 'sunbay-checkout', major: 1, ... });\n */\nexport function encodeEnvelope(envelope: Envelope): string {\n    return JSON.stringify(envelope);\n}\n\n/**\n * 解析并最小结构校验信封。非法（缺 protocol、错 major、非法 kind、缺必填字段、\n * 非 JSON）一律抛 {@link EnvelopeDecodeError}。\n *\n * 注意：解码器不校验 request.name 是否为已知命令 —— 未知 name 仍解为\n * kind==='request'，交由调用方（如 Orchestrator）拒绝。\n *\n * @param wire 线缆字符串\n * @returns 已校验结构的信封\n * @example\n * const env = decodeEnvelope(wire);\n * if (env.kind === 'request') { ... }\n */\nexport function decodeEnvelope(wire: string): Envelope {\n    let parsed: unknown;\n    try {\n        parsed = JSON.parse(wire);\n    } catch {\n        throw new EnvelopeDecodeError('Envelope is not valid JSON');\n    }\n\n    if (!isRecord(parsed)) {\n        throw new EnvelopeDecodeError('Envelope must be an object');\n    }\n\n    if (parsed.protocol !== PROTOCOL_NAME) {\n        throw new EnvelopeDecodeError(\n            `protocol must be \"${PROTOCOL_NAME}\", received ${JSON.stringify(parsed.protocol)}`\n        );\n    }\n    if (parsed.major !== PROTOCOL_MAJOR) {\n        throw new EnvelopeDecodeError(\n            `major must be ${PROTOCOL_MAJOR}, received ${JSON.stringify(parsed.major)}`\n        );\n    }\n\n    assertString(parsed, 'runtimeId');\n    assertString(parsed, 'checkoutId');\n    if (parsed.elementId !== undefined && typeof parsed.elementId !== 'string') {\n        throw new EnvelopeDecodeError('elementId must be a string when present');\n    }\n\n    const kind = parsed.kind;\n    if (typeof kind !== 'string' || !(ENVELOPE_KINDS as readonly string[]).includes(kind)) {\n        throw new EnvelopeDecodeError(`Invalid kind: ${JSON.stringify(kind)}`);\n    }\n\n    switch (kind) {\n        case 'request': {\n            assertString(parsed, 'requestId');\n            assertString(parsed, 'name');\n            if (!('payload' in parsed)) {\n                throw new EnvelopeDecodeError('request envelope is missing payload');\n            }\n            break;\n        }\n        case 'response': {\n            assertString(parsed, 'requestId');\n            if (typeof parsed.ok !== 'boolean') {\n                throw new EnvelopeDecodeError('response envelope is missing boolean ok');\n            }\n            if (parsed.ok === true) {\n                if (!('data' in parsed)) {\n                    throw new EnvelopeDecodeError('successful response is missing data');\n                }\n            } else if (!isRecord(parsed.error)) {\n                throw new EnvelopeDecodeError('failed response is missing error object');\n            }\n            break;\n        }\n        case 'event': {\n            assertString(parsed, 'eventId');\n            assertString(parsed, 'name');\n            if (!('payload' in parsed)) {\n                throw new EnvelopeDecodeError('event envelope is missing payload');\n            }\n            if (\n                'operationId' in parsed &&\n                parsed.operationId !== undefined &&\n                typeof parsed.operationId !== 'string'\n            ) {\n                throw new EnvelopeDecodeError('operationId must be a string when present');\n            }\n            break;\n        }\n    }\n\n    // 结构已校验，确认为 Envelope 形状。\n    return parsed as unknown as Envelope;\n}\n","/**\n * 协议错误码常量（单一真源，spec 5.4）。\n *\n * 不提供可能误导重复付款的通用 `retryable` 布尔。\n * 仅保留实际会被产出的错误码；新增码须同时有产出点。\n */\n\nexport const ErrorCode = {\n    INVALID_OPTIONS: 'INVALID_OPTIONS',\n    ELEMENT_CONFLICT: 'ELEMENT_CONFLICT',\n    INSTANCE_DESTROYED: 'INSTANCE_DESTROYED',\n    CHECKOUT_BUSY: 'CHECKOUT_BUSY',\n    VALIDATION_ERROR: 'VALIDATION_ERROR',\n    SESSION_LOAD_FAILED: 'SESSION_LOAD_FAILED',\n    RUNTIME_LOAD_FAILED: 'RUNTIME_LOAD_FAILED',\n    PROTOCOL_UNSUPPORTED: 'PROTOCOL_UNSUPPORTED',\n    REQUEST_TIMEOUT: 'REQUEST_TIMEOUT',\n    PAYMENT_FLOW_ERROR: 'PAYMENT_FLOW_ERROR',\n    UNSUPPORTED_CAPABILITY: 'UNSUPPORTED_CAPABILITY',\n} as const;\n\n/** 错误码字面量联合类型。 */\nexport type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];\n","/**\n * 命令契约（商户 SDK → main，spec 5.2 表，真源）。\n *\n * 每命令的请求/响应类型在此定义；跨通道只传 JSON 可序列化数据。\n */\n\nimport type {\n    Appearance,\n    AddressInfo,\n    ElementOptions,\n    ElementType,\n    PaymentMethodFilter,\n    PublicSessionView,\n    TxnStatus,\n} from './types';\n\n/** 全部命令名（spec 5.2）。 */\nexport type CommandName =\n    | 'initialize'\n    | 'createElement'\n    | 'updateElement'\n    | 'destroyElement'\n    | 'focus'\n    | 'blur'\n    | 'clear'\n    | 'updateCheckout'\n    | 'getSession'\n    | 'refresh'\n    | 'getPaymentStatus'\n    | 'confirm'\n    | 'destroy';\n\n/** 已知命令名集合（供调用方校验 request.name 是否受支持）。 */\nexport const COMMAND_NAMES: readonly CommandName[] = [\n    'initialize',\n    'createElement',\n    'updateElement',\n    'destroyElement',\n    'focus',\n    'blur',\n    'clear',\n    'updateCheckout',\n    'getSession',\n    'refresh',\n    'getPaymentStatus',\n    'confirm',\n    'destroy',\n];\n\n/** 判断字符串是否为已知命令名。 */\nexport function isCommandName(name: string): name is CommandName {\n    return (COMMAND_NAMES as readonly string[]).includes(name);\n}\n\n// --- initialize ---\nexport interface InitializeReq {\n    sessionId: string;\n    locale?: string;\n    appearance?: Appearance;\n    paymentMethods?: PaymentMethodFilter;\n}\nexport interface InitializeResp {\n    capabilities: string[];\n    session: PublicSessionView;\n}\n\n// --- createElement ---\nexport interface CreateElementReq {\n    elementId: string;\n    type: ElementType;\n    options?: ElementOptions;\n}\nexport interface CreateElementResp {\n    elementId: string;\n    registered: true;\n}\n\n// --- updateElement ---\nexport interface UpdateElementReq {\n    elementId: string;\n    patch: Partial<ElementOptions>;\n}\nexport interface UpdateElementResp {\n    elementId: string;\n    options: ElementOptions;\n}\n\n// --- destroyElement ---\nexport interface DestroyElementReq {\n    elementId: string;\n}\nexport interface DestroyElementResp {\n    elementId: string;\n    released: true;\n}\n\n// --- focus / blur / clear（仅输入类 Element）---\nexport interface ElementActionReq {\n    elementId: string;\n}\nexport interface ElementActionResp {\n    elementId: string;\n    done: true;\n}\n\n// --- updateCheckout（不改会话/金额）---\nexport interface UpdateCheckoutReq {\n    locale?: string;\n    appearance?: Appearance;\n}\nexport interface UpdateCheckoutResp {\n    updated: true;\n}\n\n// --- getSession / refresh ---\nexport type GetSessionReq = Record<string, never>;\nexport type GetSessionResp = PublicSessionView;\n\n// --- getPaymentStatus（原样返回 TxnStatus，不转义）---\nexport type GetPaymentStatusReq = Record<string, never>;\nexport interface GetPaymentStatusResp {\n    txnStatus: TxnStatus;\n    txnId?: string;\n}\n\n// --- confirm（仅表示开始执行）---\nexport interface ConfirmReq {\n    operationId: string;\n    billingAddress?: AddressInfo;\n    shippingAddress?: AddressInfo;\n    customerName?: string;\n    email?: string;\n    returnUrl?: string;\n}\nexport interface ConfirmResp {\n    accepted: true;\n}\n\n// --- destroy ---\nexport type DestroyReq = Record<string, never>;\nexport interface DestroyResp {\n    released: true;\n}\n\n/** 命令名 → 请求载荷映射。 */\nexport interface CommandRequestMap {\n    initialize: InitializeReq;\n    createElement: CreateElementReq;\n    updateElement: UpdateElementReq;\n    destroyElement: DestroyElementReq;\n    focus: ElementActionReq;\n    blur: ElementActionReq;\n    clear: ElementActionReq;\n    updateCheckout: UpdateCheckoutReq;\n    getSession: GetSessionReq;\n    refresh: GetSessionReq;\n    getPaymentStatus: GetPaymentStatusReq;\n    confirm: ConfirmReq;\n    destroy: DestroyReq;\n}\n\n/** 命令名 → 成功响应载荷映射。 */\nexport interface CommandResponseMap {\n    initialize: InitializeResp;\n    createElement: CreateElementResp;\n    updateElement: UpdateElementResp;\n    destroyElement: DestroyElementResp;\n    focus: ElementActionResp;\n    blur: ElementActionResp;\n    clear: ElementActionResp;\n    updateCheckout: UpdateCheckoutResp;\n    getSession: GetSessionResp;\n    refresh: GetSessionResp;\n    getPaymentStatus: GetPaymentStatusResp;\n    confirm: ConfirmResp;\n    destroy: DestroyResp;\n}\n","/**\n * 事件契约（main → 商户 SDK，spec 5.3 表，真源）。\n *\n * 公开事件仅暴露 empty/complete/brand/error 等允许状态，**绝不含卡值**，\n * 不提供卡数据 getValue。`on` 注册后不重放历史事件。\n */\n\nimport type {\n    AvailableWallets,\n    CheckoutError,\n    PaymentAction,\n    PaymentMethod,\n    PaymentOutcome,\n    PublicPaymentMethod,\n} from './types';\n\n/** 全部事件名（spec 5.3）。 */\nexport type EventName =\n    | 'ready'\n    | 'change'\n    | 'focus'\n    | 'blur'\n    | 'loadError'\n    | 'elementReady'\n    | 'availablePaymentMethodsChange'\n    | 'expressAvailabilityChange'\n    | 'paymentStateChange'\n    | 'paymentResult'\n    | 'error';\n\n/** 已知事件名集合。 */\nexport const EVENT_NAMES: readonly EventName[] = [\n    'ready',\n    'change',\n    'focus',\n    'blur',\n    'loadError',\n    'elementReady',\n    'availablePaymentMethodsChange',\n    'expressAvailabilityChange',\n    'paymentStateChange',\n    'paymentResult',\n    'error',\n];\n\n/** 判断字符串是否为已知事件名。 */\nexport function isEventName(name: string): name is EventName {\n    return (EVENT_NAMES as readonly string[]).includes(name);\n}\n\n// --- 输入 Element 事件 ---\nexport interface ReadyEvent {\n    elementId: string;\n}\nexport interface ElementReadyEvent {\n    elementId: string;\n    /** 仅 expressCheckout Element ready 时携带：各钱包可用性。 */\n    availableWallets?: AvailableWallets;\n}\nexport interface ChangeEvent {\n    elementId: string;\n    empty: boolean;\n    complete: boolean;\n    error?: CheckoutError;\n    /** 仅卡号字段允许携带 brand；绝不含卡值。 */\n    brand?: string;\n}\nexport interface FocusEvent {\n    elementId: string;\n}\nexport interface BlurEvent {\n    elementId: string;\n}\nexport interface LoadErrorEvent {\n    elementId: string;\n    error: CheckoutError;\n}\n\n// --- Express 事件 ---\nexport interface AvailablePaymentMethodsChangeEvent {\n    availablePaymentMethods: PublicPaymentMethod[];\n}\n\n/**\n * express 可用钱包变化事件（spec 6）。\n * 专用于 expressCheckout：以 AvailableWallets 表达各钱包可用性，\n * 与 AvailablePaymentMethodsChangeEvent（PublicPaymentMethod[]）并存，互不破坏。\n */\nexport interface ExpressAvailabilityChangeEvent {\n    availableWallets: AvailableWallets;\n}\n\n// --- Checkout 级事件 ---\nexport interface PaymentStateChangeEvent {\n    operationId: string;\n    method: PaymentMethod;\n    /** 过程状态；requiresAction 时携带 action 信息。 */\n    state: string;\n    action?: PaymentAction;\n}\nexport interface PaymentResultEvent {\n    operationId: string;\n    method: PaymentMethod;\n    outcome: PaymentOutcome;\n}\nexport interface ErrorEvent {\n    /** 异步主动流程错误；可含 operationId（如已创建）。 */\n    operationId?: string;\n    error: CheckoutError;\n}\n\n/** 事件名 → 载荷映射。 */\nexport interface EventPayloadMap {\n    ready: ReadyEvent;\n    change: ChangeEvent;\n    focus: FocusEvent;\n    blur: BlurEvent;\n    loadError: LoadErrorEvent;\n    elementReady: ElementReadyEvent;\n    availablePaymentMethodsChange: AvailablePaymentMethodsChangeEvent;\n    expressAvailabilityChange: ExpressAvailabilityChangeEvent;\n    paymentStateChange: PaymentStateChangeEvent;\n    paymentResult: PaymentResultEvent;\n    error: ErrorEvent;\n}\n"],"mappings":"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","names":[]}