@whalet/payment-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 复制到剪贴板：优先 Async Clipboard API，失败或非安全上下文时用 execCommand 回退
+ * （HTTP、部分 iframe / Permissions-Policy 下 clipboard.writeText 不可用）
+ */
+declare function copyTextToClipboard(text: string): Promise<boolean>;
+
+/**
+ * 与 UI 对齐的最小错误码表（仅保留当前 SDK 使用项）。
+ */
+declare const PaymentErrorCodes: {
+    /** 网关拒绝 / mock 失败 */
+    readonly DECLINED: "DECLINED";
+    /** 网关订单与宿主入参不一致 */
+    readonly ORDER_VALIDATION_MISMATCH: "ORDER_VALIDATION_MISMATCH";
+    /** 会话支付方式不含所选 id */
+    readonly METHOD_NOT_AVAILABLE: "METHOD_NOT_AVAILABLE";
+    /** 需要 clientIp 但公网 IP 探测失败（网络、拦截、超时等） */
+    readonly CLIENT_IP_UNAVAILABLE: "CLIENT_IP_UNAVAILABLE";
+};
+type PaymentErrorCode = (typeof PaymentErrorCodes)[keyof typeof PaymentErrorCodes];
+/**
+ * 可序列化、可展示给 UI / 日志的错误载体（不含堆栈）。
+ */
+interface PaymentError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+declare function createPaymentError(code: string, message: string, details?: Record<string, unknown>): PaymentError;
+
+/**
+ * 跨模块共享的领域类型：环境、会话与支付结果。
+ * 刻意不包含密钥、卡号等敏感字段；敏感逻辑应在服务端完成。
+ */
+
+/** 运行环境：本地/联调（dev）、沙箱（test）、生产（prod）。 */
+type PaymentEnvironment = 'dev' | 'test' | 'prod';
+/**
+ * 收银台 UI 的粗粒度状态机，供组件绑定 loading / 禁用 / 成功页等。
+ * 字符串值需保持稳定，便于持久化调试与埋点。
+ */
+declare enum PaymentFlowState {
+    Idle = "idle",
+    Loading = "loading",
+    Ready = "ready",
+    /** 非 `open/sdk/payment` 接口 HTTP 成功但业务 `status` 非 success */
+    Error = "error",
+    Completed = "completed"
+}
+/**
+ * 商户创建支付会话后下发给前端的会话锚点。
+ * `sessionData` 为网关签名密文（常见为 Base64），SDK **不得解析**，支付请求须原样回传。
+ */
+interface PaymentSdkSession {
+    /** 会话主键（与网关订单/会话对齐）。 */
+    id: string;
+    /** 网关生成的签名密文；含 amount、userId 等，由网关校验。 */
+    sessionData: string;
+}
+/**
+ * 会话结果：仅含可在浏览器侧持有的安全字段。
+ * `paymentMethodIds` 为网关/会话下发的可用方式 id；展示名由 UI 与 `paymentMethodCopy` 等决定。
+ */
+interface PaymentSession {
+    id: string;
+    /**
+     * 与 {@link PaymentSdkSession.sessionData} 一致；支付提交时须随请求原样携带。
+     */
+    sessionData: string;
+    clientKey: string;
+    environment: PaymentEnvironment;
+    /** 当前会话可用的支付方式 id 列表。 */
+    paymentMethodIds: string[];
+    /** ISO 8601 等格式的过期时间，若网关返回则透传。 */
+    expiresAt?: string;
+    /** 网关侧订单唯一标识（与 checkout detail / 支付接口约定一致）。 */
+    tradeUniId?: string;
+    /** 网关订单金额，用于与宿主初始化 `amount` 交叉校验。 */
+    orderAmount?: {
+        value: number;
+        currency: string;
+    };
+    /** 网关订单地区/国家码，用于与宿主 `countryCode` 交叉校验。 */
+    orderRegion?: string;
+    /**
+     * Raw `info.paymentMethodList` entries from sessions (e.g. `paymentMethodCode`),
+     * for host display or passthrough on submit; same source as {@link paymentMethodIds}, different shape.
+     */
+    paymentMethodList?: unknown[];
+    /** Sessions `info.locale` (e.g. `auto`), independent of UI `locale`. */
+    checkoutLocale?: string;
+    /**
+     * `sessions.info.customerEmail`: default source for card submit `email`.
+     */
+    customerEmail?: string;
+    /**
+     * 对齐 whalet-checkout `acquiringInfo.addressMode`：是否展示/透传账单地址。
+     */
+    addressMode?: 'Display_Transmission' | 'Transmission' | 'Not_Transmission';
+    /**
+     * 服务端预填账单（`Display_Transmission` 回显）。
+     */
+    serverBillingAddress?: Record<string, unknown>;
+    /** 收货地址（若网关下发）。 */
+    shippingAddress?: Record<string, unknown>;
+}
+/**
+ * 用户完成一次支付尝试后的联合结果。
+ * - success：网关确认成功，带交易号
+ * - failure：业务或网关拒绝，带 {@link PaymentError}
+ * - pending：需后续动作（如 3DS），当前 SDK 为占位
+ */
+type PaymentCompletedResult = {
+    status: 'success';
+    transactionId: string;
+} | {
+    status: 'failure';
+    error: PaymentError;
+} | {
+    status: 'pending';
+    action?: string;
+};
+/**
+ * open-checkout POST 请求体中与网关约定的少量公共字段（由 UI 层 HTTP 输入合并）。
+ */
+interface CheckoutDetailExtras {
+    /** 与网关 `linkUniId` 对齐；常见与 `clientKey` 相同 */
+    linkUniId?: string;
+}
+
+export { type CheckoutDetailExtras, type PaymentCompletedResult, type PaymentEnvironment, type PaymentError, type PaymentErrorCode, PaymentErrorCodes, PaymentFlowState, type PaymentSdkSession, type PaymentSession, copyTextToClipboard, createPaymentError };

package/dist/index.js

@@ -0,0 +1,60 @@
+// src/utils/copyTextToClipboard.ts
+async function copyTextToClipboard(text) {
+  if (typeof document === "undefined") return false;
+  if (typeof navigator !== "undefined" && window.isSecureContext && navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(text);
+      return true;
+    } catch {
+    }
+  }
+  try {
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.setAttribute("readonly", "");
+    ta.style.position = "fixed";
+    ta.style.left = "-9999px";
+    ta.style.top = "0";
+    ta.setAttribute("aria-hidden", "true");
+    document.body.appendChild(ta);
+    ta.focus();
+    ta.select();
+    ta.setSelectionRange(0, text.length);
+    const ok = document.execCommand("copy");
+    document.body.removeChild(ta);
+    return ok;
+  } catch {
+    return false;
+  }
+}
+
+// src/types/paymentError.ts
+var PaymentErrorCodes = {
+  /** 网关拒绝 / mock 失败 */
+  DECLINED: "DECLINED",
+  /** 网关订单与宿主入参不一致 */
+  ORDER_VALIDATION_MISMATCH: "ORDER_VALIDATION_MISMATCH",
+  /** 会话支付方式不含所选 id */
+  METHOD_NOT_AVAILABLE: "METHOD_NOT_AVAILABLE",
+  /** 需要 clientIp 但公网 IP 探测失败（网络、拦截、超时等） */
+  CLIENT_IP_UNAVAILABLE: "CLIENT_IP_UNAVAILABLE"
+};
+function createPaymentError(code, message, details) {
+  return { code, message, details };
+}
+
+// src/types/types.ts
+var PaymentFlowState = /* @__PURE__ */ ((PaymentFlowState2) => {
+  PaymentFlowState2["Idle"] = "idle";
+  PaymentFlowState2["Loading"] = "loading";
+  PaymentFlowState2["Ready"] = "ready";
+  PaymentFlowState2["Error"] = "error";
+  PaymentFlowState2["Completed"] = "completed";
+  return PaymentFlowState2;
+})(PaymentFlowState || {});
+export {
+  PaymentErrorCodes,
+  PaymentFlowState,
+  copyTextToClipboard,
+  createPaymentError
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@whalet/payment-core",
+  "description": "支付域核心：领域类型、最小错误码与通用工具（无 HTTP 适配器）。",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --outDir dist",
+    "lint": "eslint src --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.1.8",
+    "tsup": "8.5.1",
+    "typescript": "5.6.3",
+    "vitest": "4.1.8"
+  }
+}