TGFun SDK (TypeScript)

一个对接 TGFUN 开放平台（V3 & V4）的轻量 TypeScript/Node.js SDK。

• 加/解密：AES/ECB/PKCS5Padding，服务端返回 data 的十六进制密文自动解密为明文对象
• 封装接口：access_token、玩家注册、上分、下分、获取游戏地址、注单明细、玩家余额、V4玩家汇总统计
• 兼容 CJS/ESM，内置示例脚本可直接运行

控制台：https://tgbot.tgfun.xyz/console/

安装

npm i tgfunsdk

运行环境：Node.js >= 18

快速开始

import { createTGFunClient } from 'tgfunsdk';

const client = createTGFunClient({
  baseURL: 'https://api.tgfun.xyz', // 每个商户网关不同，请填你控制台展示的域名
  appId: 'your-appid',
  appSecret: 'your-secret',
  v3Key: '你的V3接口密钥字符串' // 注意：按文档直接使用字符串字节作为 AES 密钥
});

// 1) 获取 access_token（SDK已自动解密）
const tokenResp = await client.getAccessToken();
const accessToken = tokenResp.data.access_token;

// 2) 注册玩家（自动加密请求体，自动解密响应）
await client.v3RegisterPlayer(
  { playerID: 'player-001', playerName: 'Alice', currency: 'US-COIN' },
  accessToken
);

// 3) 查询余额
const bal = await client.v3Balance({ playerID: 'player-001' }, accessToken);
console.log(bal.data.balance);

API 列表（V3）

• getAccessToken() → POST /openapi/v3/game/token

  • 入参：appid、secret（明文）
  • 返回：{ code, message, data: { result, access_token, expires_in } }

• v3RegisterPlayer({ playerID, playerName, currency }, token) → POST /openapi/v3/game/create/player

  • Header：Authorization: <access_token>
  • Body：明文 JSON 先 AES 加密为十六进制，外层 { data: hex }
  • 返回：{ code, message, data }，SDK 自动解密；若解密后不是 JSON，则包装为 { result: string }

• v3TransferIn({ payID, playerID, coin, currency }, token) → POST /openapi/v3/game/transfer/in

  • 返回（解密后）：{ result, balance, transID }

• v3TransferOut({ payID, playerID, coin, outall, currency }, token) → POST /openapi/v3/game/transfer/out

  • 返回（解密后）：{ result, outAmount, balance, transID }

• v3CreateUrl({ playerID, gameUUID, gameLang }, token) → POST /openapi/v3/game/create/url

  • 返回（解密后）：{ result, url }

• v3DetailList({ page, size, queryDate? }, token) → POST /openapi/v3/game/detail/list

  • 返回（解密后）：{ page, size, total, content, hasNext }

• v3Balance({ playerID }, token) → POST /openapi/v3/game/player/balance

  • 返回（解密后）：{ result, playerID, balance, currency }

说明：玩家注册/上下分/获取地址/注单/余额等 V3 接口，SDK 会：

1. 将你的明文 JSON 参数序列化并使用 AES/ECB/PKCS5 加密；
2. 以 { data: <hex密文> } 形式发送；
3. 接收响应后，若 code === '000000'，自动对 data 执行十六进制解密并 JSON.parse；
4. 如果解密明文不是 JSON，则会包装为 { result: <解密明文> }，方便直接判断成功/失败。

API 列表（V4）

• v4GetAccessToken(grantType) → POST /openapi/v4/game/token

  • Body：{ data: <AES十六进制密文>, grant_type: <明文> }（密文由 { appid, secret } 加密得到）
  • 返回：{ code, message, data: { result, access_token, expires_in } }

• v4RegisterPlayer({ playerID, playerName, currency, invitePlayerID? }, token) → POST /openapi/v4/game/create/player

• v4TransferIn({ payID, playerID, coin, currency }, token) → POST /openapi/v4/game/transfer/in

• v4TransferOut({ payID, playerID, coin, currency }, token) → POST /openapi/v4/game/transfer/out

• v4CreateUrl({ playerID, gameUUID, gameLang }, token) → POST /openapi/v4/game/create/url

• v4DetailList({ page, size, queryDate? }, token) → POST /openapi/v4/game/detail/list

• v4Balance({ playerID }, token) → POST /openapi/v4/game/player/balance

• v4PlayerSummary({ playerID }, token) → POST /openapi/v4/game/player/summary

  • 返回（解密后）：{ result, playerID, totalWin, totalLose, totalAmount }

• v4RuleConfig(token) → POST /openapi/v4/transfer/rule/config

• v4RuleConfigUpdate({ maxAmount, maxTimes }, token) → POST /openapi/v4/transfer/rule/config/update

说明：V4 的加/解密与 V3 保持一致（AES/ECB/PKCS5，十六进制）。SDK 同样会自动加密请求体、解密响应 data。

类型导出

SDK 导出常用类型于 types 命名空间，例如：AccessTokenResponse、V3BalanceResponse 等，可按需引入。

运行内置示例

仓库内提供了可运行的示例脚本：

1. 仅获取 token 并打印明文

node scripts/test-token.mjs

2. 全量演示（V3 + V4）：token → 注册 → 上分 → 下分 → 余额 → 注单 → 获取地址 → V4汇总

npm run build
node scripts/v3-full-demo.mjs

如需在自己项目中运行，请务必替换为你的 baseURL/appId/secret/v3Key，并确保控制台已开通对应接口权限。

常见问题

• Q：v3Key 需要 Base64 解码吗？

  • A：不用。按官方 Java 示例，new SecretKeySpec(secretKey.getBytes(), "AES")，即直接以字符串字节作为密钥（长度需为 16/24/32 字节）。

• Q：为什么我拿到的注册返回不是 JSON？

  • A：平台部分接口解密后可能返回简单文本；SDK 已将这类返回包装为 { result: string }，仍可通过 result 判断成功/失败。

许可证

MIT