@newngapi/ngapi-npm/README.en.md

专为NG游戏平台设计的官方TypeScript SDK，让您能简单、高效地与NG游戏平台的API服务进行集成。

# 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)

## Overview

The NG API SDK is the official TypeScript development kit designed for the NG gaming platform. It provides a complete, type-safe interface to help developers quickly and securely integrate the various features of the NG gaming platform.

### Core Features

- Player Account Management (create, get balance)
- Fund Transfers (deposit, withdraw, transfer all)
- Transaction Record Queries (real-time, historical, by order ID)
- Quota Inquiry (get merchant balance)
- Game URL Generation (regular and demo games)
- Game Information (get game codes)

## Installation

```bash
npm install @newngapi/ngapi-npm
```
or
```bash
yarn add @newngapi/ngapi-npm
```

## Quick Start

Below is a simple usage example. We highly recommend checking the `examples` directory for more comprehensive and runnable examples.

```typescript
import { Client, CurrencyCode } from '@newngapi/ngapi-npm';

// 1. Initialize the Client
// Please replace baseUrl with your actual API endpoint.
// Contact NG to obtain your sn and secretKey.
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. Create a player
        const createResponse = await client.createPlayer('ag', playerId, currency);
        if (createResponse.code === 10000) {
            console.log(`Player ${playerId} created successfully!`);
        }

        // 3. Get player balance
        const balanceResponse = await client.getBalance('ag', playerId, currency);
        if (balanceResponse.code === 10000) {
            console.log(`Balance for player ${playerId}:`, balanceResponse.data);
        }

    } catch (error) {
        console.error('An unexpected error occurred during the request:', error);
    }
}

main();
```

## Running the Official Examples

This project includes a detailed example file covering all SDK features, which is the best way to learn and debug the SDK.

1.  **Clone the Repository**
    ```bash
    git clone https://github.com/newngapi/ngapi-npm.git
    cd ngapi-npm
    ```

2.  **Install Dependencies**
    ```bash
    npm install
    ```

3.  **Configure the Example File**
    Open `examples/usage.ts` and replace the `config` object at the top with your actual credentials:
    ```typescript
    const config = {
      baseUrl: "https://api.ng777.net", // Your API endpoint
      sn: "YOUR_SN",                   // Your sn
      secretKey: "YOUR_SECRET_KEY",    // Your secretKey
    };
    ```

4.  **Install ts-node**
    `ts-node` is a tool that allows you to run TypeScript files directly.
    ```bash
    npm install -g ts-node
    ```

5.  **Run the Example**
    ```bash
    ts-node examples/usage.ts
    ```
    You will see detailed request paths, parameters, and responses for each API call in your console. You can comment out calls in the `main` function to test specific features individually.

## Local Development and Testing

We welcome community contributions. If you wish to contribute or debug locally, please follow these steps.

### Install Dependencies
```bash
npm install
```

### Run Tests
This project uses Jest for unit testing to ensure code quality and stability.
```bash
# Run all tests
npm test

# Generate a test coverage report
npm test -- --coverage
```

### Code Style
This project uses ESLint and Prettier to maintain a consistent code style.
```bash
# Check for linting errors
npm run lint

# Automatically fix linting issues
npm run lint -- --fix
```

## Error Handling
The SDK performs parameter validation before sending requests and returns error responses in the same format as the official NG API. For a detailed list of error codes, please refer to the [Official NG Documentation](https://wiki.neapi.com).

```typescript
{
    "code": 10001, // Error code, 10000 means success
    "msg": "Error message",
    "data": null
}
```

## Official Resources
- **Official Website**: [https://www.neapi.com](https://www.neapi.com)
- **Official Documentation**: [https://wiki.neapi.com](https://wiki.neapi.com)
- **Contact Email**: [newngapi@gmail.com](mailto:newngapi@gmail.com)

## License
This project is open-sourced under the [MIT](LICENSE) license.