npm package: @gulibs/tegg-wechat-open-api
Description: WeChat Open API plugin for Egg.js - mini-program, official account, and pay integration
Author: HectorGu
Latest version: 0.0.1

# @gulibs/tegg-wechat-open-api

Egg.js 4.x 微信开放 API 插件，基于 [@gulibs/wechat-open-api](https://www.npmjs.com/package/@gulibs/wechat-open-api)，提供小程序（MiniprogramClient）、公众号（OfficialAccountClient）、服务号（ServiceAccountClient）能力。

**微信支付**请使用 [@gulibs/tegg-wechat-pay-v3](https://www.npmjs.com/package/@gulibs/tegg-wechat-pay-v3)。

## Features

- **小程序**（MiniprogramClient）：code2Session、getAccessToken、getStableAccessToken、getPhoneNumber、sendSubscribeMessage、checkText、checkImageAndMedia、generateUrlLink
- **公众号**（OfficialAccountClient）：getAccessToken、getStableAccessToken、createQrcode、getUserInfo、setUserRemark、getTags、batchTagUsers、createMenu、getMenu
- **服务号**（ServiceAccountClient）：在公众号能力基础上增加 getOAuthAccessToken、refreshOAuthAccessToken、checkOAuthAccessToken、getOAuthUserInfo、sendTemplateMessage、sendSubscribeNotify
- **TypeScript** 类型完整
- **单例**：最多一个小程序、一个公众号、一个服务号客户端

## Requirements

- Node.js >= 22.18.0
- Egg.js >= 4.1.0-beta.35

## Install

```bash
npm i @gulibs/tegg-wechat-open-api
# 或
npm i @gulibs/tegg-wechat-open-api@latest
```

Beta 版本需指定 `@beta` 标签。

## Quick Start

### 1. 启用插件

```typescript
// config/plugin.ts
import wechatOpenApiPlugin from '@gulibs/tegg-wechat-open-api';

export default {
  ...wechatOpenApiPlugin(),
};
```

### 2. 配置

```typescript
// config/config.default.ts
export default {
  teggWechatOpenApi: {
    app: true,
    agent: false,
    // 小程序（可选）
    wechatApp: {
      appid: 'your-miniprogram-appid',
      secret: 'your-miniprogram-secret',
      apiUrl: 'https://api.weixin.qq.com', // 可选
    },
    // 公众号（可选）
    wechatOfficialAccount: {
      appid: 'your-official-account-appid',
      secret: 'your-official-account-secret',
    },
    // 服务号（可选，在公众号能力上增加网页授权、模板消息、订阅通知）
    wechatServiceAccount: {
      appid: 'your-service-account-appid',
      secret: 'your-service-account-secret',
    },
  },
};
```

### 3. 使用

```typescript
// 小程序登录
const session = await ctx.teggWechatOpenApi.app?.code2Session('wx_login_code');

// 小程序 access_token
const tokenRes = await ctx.teggWechatOpenApi.app?.getAccessToken();

// 公众号用户信息
const userInfo = await ctx.teggWechatOpenApi.officialAccount?.getUserInfo(
  accessToken,
  openid,
);

// 公众号创建临时二维码
const qr = await ctx.teggWechatOpenApi.officialAccount?.createQrcode({
  access_token: accessToken,
  expire_seconds: 3600,
  action_name: 'QR_STR_SCENE',
  action_info: { scene: { scene_str: 'scene_value' } },
});

// 服务号：网页授权 access_token、模板消息、订阅通知
const oauthToken = await ctx.teggWechatOpenApi.serviceAccount?.getOAuthAccessToken(code);
const userInfo = await ctx.teggWechatOpenApi.serviceAccount?.getOAuthUserInfo(oauthToken.access_token, oauthToken.openid);
```

## Config

| 配置项 | 类型 | 默认 | 说明 |
|--------|------|------|------|
| `teggWechatOpenApi.app` | boolean | true | 是否在 app 进程启用 |
| `teggWechatOpenApi.agent` | boolean | false | 是否在 agent 进程启用 |
| `teggWechatOpenApi.wechatApp` | WechatAppClientConfig | - | 小程序配置（appid, secret, apiUrl?） |
| `teggWechatOpenApi.wechatOfficialAccount` | WechatOfficialAccountClientConfig | - | 公众号配置 |
| `teggWechatOpenApi.wechatServiceAccount` | WechatServiceAccountClientConfig | - | 服务号配置 |

## API

- `app.teggWechatOpenApi` / `ctx.teggWechatOpenApi` → `{ app?: MiniprogramClient; officialAccount?: OfficialAccountClient; serviceAccount?: ServiceAccountClient }`
- 仅配置了的客户端会存在，调用时请使用可选链 `?.`。
- 方法名与 [@gulibs/wechat-open-api](https://www.npmjs.com/package/@gulibs/wechat-open-api) 一致（如 getAccessToken、getUserInfo、createQrcode、createMenu、getMenu 等）。

## 微信支付

本插件不包含微信支付能力，请使用 [@gulibs/tegg-wechat-pay-v3](https://www.npmjs.com/package/@gulibs/tegg-wechat-pay-v3)。

## References

- [@gulibs/wechat-open-api](https://www.npmjs.com/package/@gulibs/wechat-open-api)
- [微信小程序开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
- [微信公众号开发文档](https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html)

## License

MIT