npm package: @newngapi/ngapi-npm
Description: 专为NG游戏平台设计的官方TypeScript SDK，让您能简单、高效地与NG游戏平台的API服务进行集成。
Author: NG API Team
Latest version: 1.0.0

# NG API SDK (TypeScript/JavaScript)

[![NPM Version](https://img.shields.io/npm/v/@newngapi/ngapi-npm.svg?style=flat-square)](https://www.npmjs.com/package/@newngapi/ngapi-npm)
[![NPM Downloads](https://img.shields.io/npm/dt/@newngapi/ngapi-npm.svg?style=flat-square)](https://www.npmjs.com/package/@newngapi/ngapi-npm)
[![License](https://img.shields.io/npm/l/@newngapi/ngapi-npm.svg?style=flat-square)](https://github.com/newngapi/ngapi-npm/blob/main/LICENSE)
[![Build Status](https://img.shields.io/github/actions/workflow/status/newngapi/ngapi-npm/ci.yml?branch=main&style=flat-square)](https://github.com/newngapi/ngapi-npm/actions)


## 项目概述

NG API SDK 是一个专为 NG 游戏平台设计的官方 TypeScript 开发工具包。它提供了一套完整的、类型安全的接口，帮助开发者快速、安全地集成 NG 游戏平台的各项功能。

### 主要功能

- 玩家账户管理 (创建、查询余额)
- 资金转账 (转入、转出、一键回收)
- 交易记录查询 (实时、历史、按订单号)
- 额度查询 (查询商户余额)
- 游戏 URL 生成 (普通游戏、试玩游戏)
- 游戏信息查询 (获取游戏代码)

## 安装

```bash
npm install @newngapi/ngapi-npm
```
或者
```bash
yarn add @newngapi/ngapi-npm
```

## 快速上手

下面是一个简单的使用示例。我们强烈建议您查看 `examples` 目录以获取更完整、可直接运行的范例。

```typescript
import { Client, CurrencyCode } from '@newngapi/ngapi-npm';

// 1. 初始化客户端
// 请将 baseUrl 替换为您的实际 API 地址
// sn 和 secretKey 请联系 NG 获取
const client = new Client({
    baseUrl: 'https://api.ng777.net',
    sn: 'YOUR_SN',
    secretKey: 'YOUR_SECRET_KEY'
});

async function main() {
    try {
        const playerId = 'testuser01';
        const currency: CurrencyCode = 'CNY';

        // 2. 创建玩家
        const createResponse = await client.createPlayer('ag', playerId, currency);
        if (createResponse.code === 10000) {
            console.log(`玩家 ${playerId} 创建成功!`);
        }

        // 3. 查询余额
        const balanceResponse = await client.getBalance('ag', playerId, currency);
        if (balanceResponse.code === 10000) {
            console.log(`玩家 ${playerId} 的余额为:`, balanceResponse.data);
        }

    } catch (error) {
        console.error('请求时发生意外错误:', error);
    }
}

main();
```

## 运行官方示例

本项目提供了一个包含所有 SDK 功能的详细示例文件，这是学习和调试 SDK 的最佳方式。

1.  **克隆项目**
    ```bash
    git clone https://github.com/newngapi/ngapi-npm.git
    cd ngapi-npm
    ```

2.  **安装依赖**
    ```bash
    npm install
    ```

3.  **配置示例文件**
    打开 `examples/usage.ts` 文件，将文件顶部的 `config` 对象替换为您的真实配置：
    ```typescript
    const config = {
      baseUrl: "https://api.ng777.net", // 您的 API 地址
      sn: "YOUR_SN",                   // 您的 sn
      secretKey: "YOUR_SECRET_KEY",    // 您的 secretKey
    };
    ```

4.  **安装 ts-node**
    `ts-node` 是一个可以直接运行 TypeScript 文件的工具。
    ```bash
    npm install -g ts-node
    ```

5.  **运行示例**
    ```bash
    ts-node examples/usage.ts
    ```
    您将在控制台看到每个 API 调用的详细请求路径、参数和返回结果。您可以随意注释掉 `main` 函数中的某些调用，来单独测试您感兴趣的功能。


## 本地开发与测试

我们欢迎社区贡献。如果您希望参与开发或在本地进行调试，请遵循以下步骤。

### 安装依赖
```bash
npm install
```

### 运行测试
本项目使用 Jest 进行单元测试，确保了代码的质量和稳定性。
```bash
# 运行所有测试
npm test

# 生成测试覆盖率报告
npm test -- --coverage
```

### 代码风格检查
本项目使用 ESLint 和 Prettier 保证代码风格的一致性。
```bash
# 检查代码风格
npm run lint

# 自动修复代码风格问题
npm run lint -- --fix
```

## 错误处理
SDK 会在发起 API 请求前进行参数校验，并以与 NG 官方 API 相同的格式返回错误响应。详细的错误码列表请参考 [NG 官方文档](https://wiki.neapi.com)。

```typescript
{
    "code": 10001, // 错误码, 10000 代表成功
    "msg": "错误信息",
    "data": null
}
```

## 官方资源
- **官方网站**: [https://www.neapi.com](https://www.neapi.com)
- **官方文档**: [https://wiki.neapi.com](https://wiki.neapi.com)
- **联系邮箱**: [newngapi@gmail.com](mailto:newngapi@gmail.com)

## 许可证
本项目基于 [MIT](LICENSE) 协议开源。