npm package: @neuit/weapp
Description: 用于管理微信小程序的Node.js接口库
Author: 宁波诺幺信息技术有限公司
Latest version: 1.0.0

# @neuit/weapp

用于管理微信小程序的Node.js接口库

## 安装

```bash
npm install @neuit/weapp
```

## 配置

### 方式一：使用配置文件

在项目根目录创建 `.neuit.config.json` 文件：

```json
{
  "weapp_appid": "你的小程序AppID",
  "weapp_secret": "你的小程序AppSecret",
  "cache_mode": "file"
}
```

### 方式二：使用代码初始化

```javascript
const { setConfig } = require('@neuit/weapp');

setConfig({
  appid: '你的小程序AppID',
  secret: '你的小程序AppSecret',
  cache_mode: 'file' // 可选：缓存模式，默认为 'file'
});
```

## 使用示例

### 基础使用

```javascript
const { Base } = require('@neuit/weapp');

const base = new Base();

// 获取 access_token
const token = await base.getAccessToken('https://api.weixin.qq.com/cgi-bin/user/get');
console.log(token);

// 发送API请求
const result = await base.curl(
  'https://api.weixin.qq.com/cgi-bin/user/get',
  'GET',
  { openid: '用户的openid' }
);
console.log(result);
```

### 小程序登录

```javascript
const { Auth } = require('@neuit/weapp');

const auth = new Auth.Code2Session();

// 通过前端获取的code换取openid和session_key
try {
  const result = await auth.code2Session('前端wx.login()获取的code');
  
  if (result.errcode) {
    console.error('登录失败:', result.errmsg);
  } else {
    console.log('openid:', result.openid);
    console.log('session_key:', result.session_key);
    // 保存openid和session_key，建立用户会话
  }
} catch (error) {
  console.error('调用失败:', error.message);
}
```

## API 文档

### Auth 类

#### code2Session(js_code)

通过临时登录凭证code换取openid和session_key

**参数：**
- `js_code` (string): 小程序端调用wx.login()获取的临时登录凭证code

**返回：**
- `Promise<Object>`: 包含用户登录信息的对象
  - `openid` (string): 用户唯一标识
  - `session_key` (string): 会话密钥
  - `unionid` (string): 用户在开放平台的唯一标识符（可选，满足条件时返回）

**说明：**
- code只能使用一次，5分钟未被使用自动过期
- session_key是敏感信息，不应泄露给客户端
- 详细文档请参考：[Auth.Code2Session 文档](docs/Auth.Code2Session.md)

### Base 类

#### getAccessToken(_url)

获取 access_token

**参数：**
- `_url` (string): 请求的URL

**返回：**
- `Promise<string>`: access_token

**说明：**
- access_token 有效期为 7200 秒（2小时）
- 会自动缓存到本地文件，避免频繁请求
- 缓存文件保存在项目根目录的 `.neuit` 文件夹中

#### curl(_url, _method, _params)

发送HTTP请求到微信小程序API

**参数：**
- `_url` (string): 请求地址
- `_method` (string): 请求方法 (GET/POST)
- `_params` (Object): 请求参数

**返回：**
- `Promise<Object>`: 响应结果

**说明：**
- 自动处理 access_token 的添加
- 自动过滤空值参数

## access_token 管理

### 存储与更新

- `access_token` 的存储至少要保留 512 个字符空间
- `access_token` 的有效期目前为 **2 个小时**，SDK会自动定时刷新
- 使用中控服务器统一获取和刷新 `access_token`，其他业务逻辑服务器所使用的 `access_token` 均来自于该中控服务器
- SDK 会根据返回的 `expires_in` 自动设置过期时间，并提前 5 分钟刷新 token，确保业务平滑过渡

### 缓存模式

目前支持文件缓存模式 (`file`)，缓存文件存储在项目根目录的 `.neuit` 文件夹中。

## 配置项说明

| 配置项 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| appid | string | 是 | 小程序唯一凭证，即 AppID |
| secret | string | 是 | 小程序唯一凭证密钥，即 AppSecret |
| cache_mode | string | 否 | 缓存模式，默认为 'file' |

## 错误处理

API 调用失败时会抛出错误，错误信息包含微信返回的错误码和错误消息。

```javascript
try {
  const result = await base.curl('https://api.weixin.qq.com/cgi-bin/token', 'GET', {
    grant_type: 'client_credential',
    appid: 'xxx',
    secret: 'xxx'
  });
} catch (error) {
  console.error('API调用失败:', error.message);
}
```

## 参考文档

- [微信小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/mp-access-token/getAccessToken.html)

## License

MIT