ql-lib

安装

npm install ql-lib

快速开始

const { createClient } = require('ql-lib');

// 创建客户端
const client = createClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

// 查询余额
const result = await client.getBalance();
console.log(result);

初始化方式

方式一：直接使用 API Key（简单场景）

const { createClient } = require('ql-lib');

const client = createClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  // baseUrl: 'https://custom-domain.com/api/gateway' // 可选，自定义网关地址
});

方式二：动态获取凭证（推荐生产环境）

const { GatewayApiService } = require('ql-lib');

const client = new GatewayApiService({
  getCredentials: () => {
    // 从数据库/缓存/配置中心获取凭证
    return {
      apiKey: process.env.API_KEY,
      apiSecret: process.env.API_SECRET
    };
  },
  logger: {
    debug: (...args) => console.log('[QL]', ...args),
    error: (...args) => console.error('[QL]', ...args)
  }
});

方式三：自定义网关地址

const client = createClient({
  baseUrl: 'https://your-gateway-domain.com/api/gateway',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

API 方法

充值相关

创建支付订单

const result = await client.createRechargeOrder({
  amount: 100,                          // 充值金额（元）
  orgId: 'org_123',                     // 可选：组织ID
  returnUrl: 'https://your-site.com/pay/success'  // 可选：支付成功回调地址
});

// 成功返回
// {
//   success: true,
//   data: {
//     outTradeNo: 'ORDER_xxx',
//     payUrl: 'https://...'  // 跳转此链接完成支付
//   }
// }

查询订单状态

const result = await client.queryRechargeOrder('ORDER_xxx');

// 返回
// {
//   success: true,
//   data: {
//     status: 'SUCCESS',  // PENDING / SUCCESS / FAILED
//     amount: 100,
//     paidAt: '2024-01-01T00:00:00Z'
//   }
// }

获取订单列表

const result = await client.getRechargeOrderList({
  page: 1,
  pageSize: 10,
  status: 'SUCCESS'  // 可选：PENDING / SUCCESS / FAILED
});

余额相关

查询余额

const result = await client.getBalance({ orgId: 'org_123' });

// 返回
// {
//   success: true,
//   data: {
//     balance: 1000,      // 当前余额（积分）
//     totalRecharge: 5000 // 累计充值（积分）
//   }
// }

扣除积分

const result = await client.deductScore({
  score: 100,               // 扣除积分数量
  orgId: 'org_123',         // 可选：组织ID
  deductType: 'api_call',   // 可选：扣除类型
  remark: '调用API消费'      // 可选：备注
});

消费明细

const result = await client.getConsumeRecords({
  page: 1,
  pageSize: 20,
  startTime: '2024-01-01T00:00:00Z',
  endTime: '2024-01-31T23:59:59Z'
});

充值明细

const result = await client.getRechargeRecords({
  page: 1,
  pageSize: 20,
  status: 'SUCCESS'
});

积分统计

const result = await client.getBalanceStats({ orgId: 'org_123' });

抖音相关

获取抖音授权链接

const result = await client.generateOAuthUrl('my-platform', 'custom-state-123');

// 返回
// {
//   success: true,
//   data: {
//     authUrl: 'https://open.douyin.com/...'
//   }
// }

发送抖音私信

const result = await client.sendMessage({
  id: 'msg_123',
  toUserId: 'douyin_user_id',
  content: '你好，这是测试消息',
  msgId: 'platform_msg_id',
  conversationId: 'conv_123',
  scene: 'im_replay_msg',  // 可选，默认 im_replay_msg
  channel: 3               // 可选，默认 3
});

解除抖音授权

const result = await client.deleteAuth('account_id_123');

工具方法

金额与积分转换

const { GatewayApiService } = require('ql-lib');

// 金额转积分（1元 = 1积分）
const score = GatewayApiService.amountToScore(100.5);  // 100.5

// 积分转金额
const amount = GatewayApiService.scoreToAmount(1000);  // 1000

精确计算

// 精确加法
const sum = GatewayApiService.add(0.1, 0.2);  // 0.3（而非 0.30000000000000004）

// 精确减法
const diff = GatewayApiService.sub(1, 0.9);   // 0.1

// 精确乘法
const product = GatewayApiService.mul(0.1, 3); // 0.3

// 精确除法
const quotient = GatewayApiService.div(1, 3);  // 0.3333333333333333

错误处理

所有接口统一返回格式：

{
  success: true,    // 是否成功
  data: {...},      // 成功时返回的数据
  error: '错误信息'  // 失败时的错误信息
}

使用示例：

const result = await client.getBalance();

if (!result.success) {
  console.error('查询失败:', result.error);
  return;
}

console.log('当前余额:', result.data.balance);

完整示例

const { createClient, GatewayApiService } = require('ql-lib');

async function main() {
  // 创建客户端
  const client = createClient({
    apiKey: process.env.QL_API_KEY,
    apiSecret: process.env.QL_API_SECRET
  });

  try {
    // 1. 查询余额
    const balanceRes = await client.getBalance();
    if (balanceRes.success) {
      console.log('当前余额:', balanceRes.data.balance);
    }

    // 2. 创建充值订单
    const orderRes = await client.createRechargeOrder({
      amount: 100,
      returnUrl: 'https://mysite.com/pay/callback'
    });
    if (orderRes.success) {
      console.log('支付链接:', orderRes.data.payUrl);
    }

    // 3. 扣除积分
    const deductRes = await client.deductScore({
      score: 10,
      remark: 'API调用费用'
    });
    if (deductRes.success) {
      console.log('扣除成功');
    }

    // 4. 金额计算
    const needScore = GatewayApiService.amountToScore(50);  // 50积分
    console.log('50元可兑换:', needScore, '积分');

  } catch (err) {
    console.error('操作失败:', err);
  }
}

main();

Webhook 验证

用于验证接收到的 Webhook 回调请求

基础用法

const { WebhookValidator } = require('ql-lib');

// 创建验证器
const validator = new WebhookValidator({
  secret: 'your-webhook-secret',
  tolerance: 300  // 可选，时间戳容错时间（秒），默认 5 分钟
});

// 验证请求
const result = validator.validate(headers, rawBody);

if (result.valid) {
  console.log('验证通过:', result.data);
} else {
  console.error('验证失败:', result.error);
}

Express 中间件用法

const express = require('express');
const { WebhookValidator } = require('ql-lib');

const app = express();

// 配置 rawBody（必须）
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString();
  }
}));

// 创建验证器
const validator = new WebhookValidator({ secret: 'your-webhook-secret' });

// 使用中间件
app.post('/webhook', validator.middleware(), (req, res) => {
  // 验证通过，数据在 req.webhookData
  console.log('收到 webhook:', req.webhookData);
  res.json({ received: true });
});

TypeScript 支持

本库包含完整的 TypeScript 类型定义：

import { createClient, GatewayApiService, ApiResponse, CreateRechargeOrderParams } from 'ql-lib';

const client = createClient({
  apiKey: 'your-key',
  apiSecret: 'your-secret'
});

const result: ApiResponse = await client.getBalance();

许可证

MIT