# @payermax/core-loader

> PayerMax Web SDK loader for NPM and browser integration

Latest version **0.1.2** (published 2026-09-24) · SEE LICENSE IN LICENSE.md license · 0 weekly downloads

## Install

```sh
npm install @payermax/core-loader
pnpm add @payermax/core-loader
yarn add @payermax/core-loader
bun add @payermax/core-loader
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.2 |
| Published | 2026-09-24 |
| First published | 2026-09-24 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE.md |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 0 |
| Unpacked size | 59 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | payermax |

## Links

- npm: https://www.npmjs.com/package/@payermax/core-loader
- npm.io page: https://npm.io/package/@payermax/core-loader

## Recent versions

- 0.1.2 (latest) — 2026-09-24
- 0.1.1 — 2026-09-24
- 0.1.0 — 2026-09-24

## README

# @payermax/core-loader

`@payermax/core-loader` 是 PayerMax 业务内核的 NPM 加载器，面向具备构建流程的应用：它负责全球 CDN 决策与缓存，并在内核资源执行后从 `window.PMXSDKKernels[name]` 取得内核实例。`loadSDK()` 只保证内核可用；内核拿到之后怎么用（调不调 `init`、调什么业务 API），由各内核自己定义，与 loader 无关。

## 安装

```bash
npm install @payermax/core-loader
```

## 加载内核

目前仅提供 `dropin` 一个可对接内核。未知名称会在任何网络请求前失败。

NPM 薄壳使用稳定别名加载资源，按规范化 `cdnList` 分区执行并发健康探测、500ms 冷启动回退、24 小时优选缓存、空闲刷新、资源下载超时和失败源恢复。

```ts
import { loadSDK } from '@payermax/core-loader';

const sdk = await loadSDK('dropin');
```

需要覆盖默认候选 CDN 时：

```ts
const sdk = await loadSDK('dropin', {
  cdnList: ['https://sdk-a.example.com', 'https://sdk-b.example.com']
});
```

根入口还导出 `createLoader(options)`。它创建一个拥有独立 CDN 决策和内核加载状态的 loader；常规应用只需使用默认的 `loadSDK()`。

在真实浏览器环境中，导入 `@payermax/core-loader` 会静默启动默认 loader 的 CDN 决策（缓存、健康探测与兜底排序），但不会下载业务内核。因此后续 `loadSDK()` 可复用已完成或进行中的决策。Node、SSR 或缺少 DOM / `Image` 能力的环境不会触发该预热副作用。

## 商户集成示例（Drop-in）

以下示例说明商户拿到内核实例后的一种用法。`create` / `mount` / `on` / `emit` 都是 Drop-in 内核自己定义的 API，不属于 loader；`loadSDK()` resolve 仅表示内核可用，不代表组件可交互。

```ts
import { loadSDK } from '@payermax/core-loader';

const PMdropin = await loadSDK('dropin'); // 即 window.PMXSDKKernels.dropin

const card = PMdropin.create('card', {
  clientKey: 'YOUR_CLIENT_KEY',   // 由商户服务端创建支付会话后返回
  sessionKey: 'YOUR_SESSION_KEY', // 不要手工拼接或长期存储
  // ... 具体参考payermaxMax官网前置组建集成方式
});

card.mount('.frame-card');
card.on('ready', () => {
  // 移除自定义 loading，允许用户开始输入
});
card.on('form-check', (e) => {
  payButton.disabled = !e.isFormValid;
});
```

支付时用 `emit('canMakePayment')` 换取 `paymentToken`，再调用商户后端下单：

```ts
card.emit('setDisabled', true);
try {
  const res = await card.emit('canMakePayment');
  if (res.code !== 'APPLY_SUCCESS') throw new Error(res.msg || res.code);
  await orderAndPay(res.data.paymentToken); // 商户自有后端下单/支付接口
} finally {
  card.emit('setDisabled', false);
}
```

注意：

- Drop-in 场景下没有 `init`，商户不调用它即可；其他内核若提供 `init`，商户按该内核文档调用。
- `loadSDK()` resolve 后，卡还要等 `form-check` 校验通过后再解锁支付按钮。
- `clientKey` / `sessionKey` 应由商户服务端创建支付会话后返回；前端支付结果不作为最终订单状态依据，以服务端通知或查询结果为准。

完整的组件参数、支付链路与 API 定义请以 Drop-in 产品文档为准。

## 内核发布约束

所有候选资源位置必须为同一内核名最终提供同一已批准的字节产物。内核脚本完成后注册 `window.PMXSDKKernels[name]`；注册表示内核可调用。资源成功执行后的运行时异常不触发 CDN 切换。

---
_Source: https://npm.io/package/@payermax/core-loader · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._