# Node.js SDK

基于当前公共接口文档整理的 Node.js SDK，覆盖：

- 创建收款订单
- 查询收款订单状态
- 创建独享钱包
- 创建代付订单
- 请求签名
- 回调验签

## 安装

如果直接在本仓库里使用：

```bash
npm install ./sdk/nodejs
```

如果是复制到其他项目，也可以直接把整个目录带走使用。

## 基本用法

```js
import { UUGateClient } from 'uugate-openapi-sdk';

const client = new UUGateClient({
  baseUrl: 'https://api.uugate.com',
  merchantUid: '880001',
  apiKey: 'mch_xxxxxxxxxxxxxxxxxxxx',
});

const order = await client.createPayinOrder({
  chainCode: 'TRON',
  tokenSymbol: 'USDT',
  merchantOrderNo: 'M202604170001',
  amount: '100.00',
  notifyUrl: 'https://merchant.example.com/api/uugate/payin-notify',
});

console.log(order);
```

## 可用方法

```js
await client.createPayinOrder(payload);
await client.getPayinOrder(orderNo);
await client.createExclusiveBinding(payload);
await client.createPayoutOrder(payload);
```

## 回调验签

回调使用创建该订单时的 API Key，无需额外配置密钥。轮换 API Key 前应处理完未完成订单；自建接收服务需按原订单保留验签凭据。验签工具负责 HMAC 校验，接收端还需检查时间戳（建议 5 分钟）、nonce 和订单幂等性。

```js
import { verifyCallbackSignature } from 'uugate-openapi-sdk';

const valid = verifyCallbackSignature({
  apiKey: process.env.UUGATE_API_KEY,
  timestamp: req.header('x-callback-timestamp'),
  nonce: req.header('x-callback-nonce'),
  signature: req.header('x-callback-signature'),
  rawBody,
});
```

注意：

- `rawBody` 必须是原始请求体字符串，不能先改写字段顺序再验签。
- `notifyUrl` 是创建收款订单和创建代付订单时的必填字段，平台会按订单维度回调到对应地址。
- `createExclusiveBinding(payload)` 也支持可选 `notifyUrl`，用于给这条专属地址绑定独立的会员充值回调地址；同一 `bindKey` 重复提交会幂等返回同一条绑定和地址。
- `getPayinOrder(orderNo)` 在会员充值场景下会返回 `bindKey`；`deposit_completed` 回调也会带上 `bindKey`，可直接用来定位会员。
- SDK 使用和服务端一致的 HMAC-SHA256、规范化路径、规范化 query、规范化 JSON 规则。

## 示例

可参考 [examples/basic.js](./examples/basic.js)。