@neyric_w/wechat-sdk/README.md

微信服务号 OAuth SDK - 提供完整的网页授权功能

# @neyric_w/wechat-sdk

[![npm version](https://img.shields.io/npm/v/@neyric_w/wechat-sdk.svg)](https://www.npmjs.com/package/@neyric_w/wechat-sdk)
[![license](https://img.shields.io/npm/l/@neyric_w/wechat-sdk.svg)](https://github.com/neyric/wechat-sdk/blob/main/LICENSE)

一个简单易用的微信服务号 OAuth SDK，提供完整的网页授权功能，使用 TypeScript 编写，支持 ESM 和 CommonJS。

## 特性

- 🚀 **简单易用** - 清晰的 API 设计，开箱即用
- 📦 **双格式支持** - 同时支持 ESM 和 CommonJS
- 🔒 **类型安全** - 完整的 TypeScript 类型定义
- ⚡ **轻量级** - 无外部依赖，体积小巧
- 🛠️ **模块化** - 按功能模块组织，按需使用
- ✅ **测试覆盖** - 完整的单元测试

## 安装

```bash
npm install @neyric_w/wechat-sdk
# 或
yarn add @neyric_w/wechat-sdk
# 或
pnpm add @neyric_w/wechat-sdk
# 或
bun add @neyric_w/wechat-sdk
```

## 快速开始

```typescript
import { WechatSDK, WeChatScope } from '@neyric_w/wechat-sdk';

// 初始化 SDK
const wxsdk = new WechatSDK('your_app_id', 'your_app_secret');

// 生成授权链接
const authUrl = wxsdk.auth.getAuthURL({
  redirectUri: 'https://your-domain.com/callback',
  scope: WeChatScope.USERINFO,
  state: 'custom_state'
});

// 处理回调
const params = wxsdk.utils.parseCallback(callbackUrl);
if (params.code) {
  // 获取 access_token
  const tokenData = await wxsdk.auth.code2Session(params.code);
  
  // 获取用户信息
  const userInfo = await wxsdk.user.getUserInfo(
    tokenData.access_token,
    tokenData.openid
  );
}
```

## API 文档

### 授权模块 (auth)
- `getAuthURL(params)` - 生成授权链接
- `code2Session(code)` - code 换取 access_token
- `refreshToken(refreshToken)` - 刷新访问令牌
- `validateToken(token, openid)` - 验证令牌有效性

### 用户模块 (user)
- `getUserInfo(token, openid)` - 获取用户信息

### 工具模块 (utils)
- `parseCallback(url)` - 解析回调参数
- `isWeChatBrowser()` - 检测微信浏览器
- `generateRandomString(length)` - 生成随机字符串
- `isValidOpenId(openid)` - 验证 OpenID 格式
- `formatAvatarUrl(url, size)` - 格式化头像 URL

## 完整示例

查看 [GitHub 仓库](https://github.com/neyric/wechat-sdk) 获取更多示例和详细文档。

## License

MIT