@eos3/quickpay 第三方快速接入

本文档面向在 Telegram Mini App 中接入 @eos3/quickpay 的前端开发者。

你只需要完成四步：

1. 安装 SDK。
2. 初始化 eosConnect client。
3. 检查并开启快捷支付。
4. 调用 pay() 发起支付。

默认情况下，SDK 使用 EOS 主网和官方 EOS3 API：https://eos3.app。

1. 安装

npm install @eos3/quickpay

2. 初始化

在应用启动文件、支付模块或框架 plugin/composable 里创建一次 client：

import { setupEosConnect } from '@eos3/quickpay';

export const eosConnect = setupEosConnect({
  botUsername: 'your_bot',
  projectName: 'Your Mini App',
  projectDescription: 'A short description shown on wallet binding screens.',
  defaultConnectOptions: {
    assetLimits: [
      {
        tokenContract: 'core.vaulta',
        symbol: 'A',
        precision: 4,
        dailyLimit: '10',
        totalBudget: '100'
      }
    ]
  }
});

setupEosConnect() 会自动注册 SDK 内置 UI、注入默认样式并挂载隐藏弹窗。React、Vue 和纯 HTML + JS 都不需要手写 <eos-connect-modal>。

3. 初始化参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | botUsername | string | 你的业务 bot 标识，用于区分不同 Mini App 的快捷支付配置。 | | projectName | string | 展示在绑定/授权页面上的项目名称。 | | projectDescription | string | 可选，展示在绑定/授权页面上的项目简介。 | | defaultConnectOptions.assetLimits | EosConnectAssetLimit[] | 用户开启快捷支付时看到的默认额度。 | | defaultConnectOptions.allowedActions | EosConnectAllowedAction[] | 可选，允许授权的自定义 action。普通 token 支付不需要。 | | locale | 'en' \| 'zh-CN' \| string | 可选，内置 UI 语言；不传时自动推断。 |

额度类型：

interface EosConnectAssetLimit {
  tokenContract: string;
  symbol: string;
  precision: number;
  dailyLimit?: string | null;
  totalBudget?: string | null;
}

4. 检查快捷支付

页面启动时调用：

const quickPay = await eosConnect.checkQuickPay();

if (quickPay.enabled) {
  enablePayButton();
} else {
  showEnableQuickPayButton();
}

返回值：

type EosConnectQuickPayStatus = {
  enabled: boolean;
  account: string | null;
  reason: string | null;
};

业务只需要用 enabled 判断支付按钮是否可用。checkQuickPay() 不返回余额；余额展示请走你自己的业务接口。

5. 开启快捷支付

当 quickPay.enabled === false 时，让用户点击按钮后调用：

await eosConnect.enableQuickPay();

SDK 会打开内置弹窗并处理后续流程。业务不需要自己拼绑定链接，也不需要管理弹窗状态。

6. 发起支付

快捷支付开启后调用：

const result = await eosConnect.pay({
  to: 'receiver1111',
  amount: '1.2500',
  memo: 'order-123',
  tokenContract: 'core.vaulta',
  symbol: 'A'
});

console.log(result.txid);

pay() 参数：

| 参数 | 类型 | 说明 | | --- | --- | --- | | to | string | 收款 EOS 账号。 | | amount | string | 支付数量。 | | memo | string | 可选 memo。 | | tokenContract | string | token 合约账号，建议每次显式传。 | | symbol | string | token 符号，建议每次显式传。 |

返回值：

type EosConnectPayResult = {
  ok: true;
  txid: string;
};

7. 自定义 action

普通 token 支付只需要 pay()。如果你的 Mini App 还需要授权自定义 action，可以在初始化时声明：

const eosConnect = setupEosConnect({
  botUsername: 'your_bot',
  projectName: 'Your Mini App',
  defaultConnectOptions: {
    allowedActions: [
      { contract: 'thirdapp1111', action: 'claim' },
      { contract: 'thirdapp1111', action: 'checkin' }
    ]
  }
});

执行时调用：

const result = await eosConnect.exec({
  contract: 'thirdapp1111',
  action: 'claim',
  data: '0000000000000000'
});

不要用 exec() 做 token transfer，转账请使用 pay()。

8. 错误处理

建议在 UI 边界统一处理错误：

import { normalizeEosConnectError } from '@eos3/quickpay';

try {
  await eosConnect.pay({
    to: 'receiver1111',
    amount: '1.2500',
    memo: 'order-123',
    tokenContract: 'core.vaulta',
    symbol: 'A'
  });
} catch (error) {
  const normalized = normalizeEosConnectError(error);
  showError(normalized.message);
}

9. 断开快捷支付

await eosConnect.disconnect();

disconnect() 会清空当前设备的快捷支付状态。如果你的产品需要“撤销授权”，请在钱包/权限管理页单独提供入口。