Photon SDK

PhotonCore 是嵌入式收银台的宿主层 SDK，职责是管理 iframe 生命周期、会话握手与事件回调。

核心职责（v2）

• 加载/销毁 cashier iframe
• 与 iframe 建立安全消息通道（origin + source + sessionId + nonce）
• 提供 submit() 和事件回调给商户页面
• 同步最小化的 checkout 状态（用于刷新恢复）
• 按环境解析收银台地址，默认只走生产环境

非职责

• 不代理 cashier 的业务 API 请求
• 不代理 crypto 轮询与退款业务编排
• 不接触 PAN/CVV 等敏感数据
• 不内置 APP_ID / APP_SECRET，这些由 PhotonLens 在 iframe 内部管理

安装

npm install @photon1/photon-sdk

快速开始

import { Photon } from '@photon1/photon-sdk'

const photon = new Photon('pk_test_xxx', {
  baseURL: '/api',
  environment: 'production',
  platform: 'auto',
  authCode: 'ac_xxx',
  debug: true
})

const checkout = await photon.initEmbeddedCheckout({
  container: '#checkout',
  enabledMethods: ['cardInfo', 'billing', 'email', 'cryptoPay'],
  onReady: () => console.log('ready'),
  onComplete: (result) => console.log('complete', result),
  onError: (error) => console.error('error', error)
})

环境切换

SDK 内置以下 cashier 地址映射：

• production -> https://cashier.photonpay.com
• pre -> https://cashier1.pre.photontech.cc
• uat -> https://cashier1.uat.photontech.cc
• sit -> https://cashier1.sit.photontech.cc
• dev -> https://cashier1.dev.photontech.cc
• local -> http://localhost:3001

默认环境始终是 production。

只有以下场景允许切换到非生产环境：

• 页面运行在 localhost / 127.0.0.1 / 0.0.0.0
• 页面运行在 *.photontech.cc

这意味着外部商户即使传了 environment: 'sit'，SDK 也会自动回退到 production。

平台选择

• platform: 'auto'：默认值，按屏幕宽度和 matchMedia('(max-width: 768px)') 判断
• platform: 'desktop'：强制桌面策略
• platform: 'mobile'：强制移动策略

事件模型

EmbeddedCheckout 继承 EventEmitter，可监听：

• ready
• resize
• change
• validation
• submit_start
• complete
• submit_error
• 3ds_required
• 3ds_complete
• back_to_merchant
• error

npm 发包说明

PhotonCore 是 npm 包，不是把 dist/ 单独上传到 npm。

正确流程：

1. 在 PhotonCore 根目录执行 npm run build
2. 用 npm pack --dry-run 检查最终入包文件
3. 在 PhotonCore 根目录执行 npm publish

npm 真正上传的是整个包（tarball），而不是手工上传某个文件夹。

当前发包内容

包内只保留：

• dist/
• index.d.ts
• README.md
• LICENSE

不会再把 src/ 或 const/ 源码一起发布到 npm。

构建产物说明

• dist/photon-sdk.esm.js：给 Vite / Webpack / Rollup 等现代前端工程使用
• dist/photon-sdk.cjs：给 CommonJS / Node 工程使用
• dist/photon-sdk.umd.js：给 CDN / <script> 直插场景使用

npm 用户默认走 ESM/CJS；只有 CDN 场景才直接用 UMD。

本地开发

npm install
npm run build
npm run build:dev
npm pack --dry-run