@cloudbase/agent-adapter-wx 1.0.1-alpha.23

package/README.md

@@ -0,0 +1,221 @@
+# @cloudbase/agent-adapter-wx
+
+WeChat adapter for AG-Kit - Forward LLM messages to WeChat platforms
+
+## Features
+
+✅ **Multi-Platform Support**: WeChat Mini Program, Official Account (Service/Subscription), Enterprise WeChat Customer Service
+✅ **Automatic Token Management**: Built-in caching and refresh mechanism
+✅ **Type-Safe**: Full TypeScript support with Zod validation
+✅ **Simple API**: Easy-to-use interface for sending messages
+✅ **Batch Operations**: Send multiple messages at once
+✅ **Async Support**: Fire-and-forget message sending
+
+## Installation
+
+```bash
+npm install @cloudbase/agent-adapter-wx
+# or
+yarn add @cloudbase/agent-adapter-wx
+# or
+pnpm add @cloudbase/agent-adapter-wx
+```
+
+## Quick Start
+
+```typescript
+import { WeChatSender, WeChatPlatform } from "@cloudbase/agent-adapter-wx";
+
+// Initialize sender
+const sender = new WeChatSender({
+  platform: WeChatPlatform.MINI_APP,
+  appId: "your-app-id",
+  appSecret: "your-app-secret",
+});
+
+// Send a message
+await sender.send({
+  toUser: "user-openid",
+  message: {
+    content: "Hello from LLM!",
+    type: "text",
+  },
+});
+```
+
+## Usage Examples
+
+### Send LLM Response to WeChat
+
+```typescript
+import { WeChatSender, WeChatPlatform } from "@cloudbase/agent-adapter-wx";
+
+// Initialize for WeChat Mini Program
+const sender = new WeChatSender({
+  platform: WeChatPlatform.MINI_APP,
+  appId: process.env.WECHAT_APP_ID!,
+  appSecret: process.env.WECHAT_APP_SECRET!,
+});
+
+// Get response from any LLM (OpenAI, Claude, etc.)
+const llmResponse = await getLLMResponse("What is the weather today?");
+
+// Send to WeChat
+await sender.send({
+  toUser: "user-openid",
+  message: {
+    content: llmResponse.content,
+    type: "text",
+  },
+  recommendQuestions: [
+    "What about tomorrow?",
+    "Show me the forecast",
+    "Temperature details",
+  ],
+});
+```
+
+### Enterprise WeChat Customer Service
+
+```typescript
+const sender = new WeChatSender({
+  platform: WeChatPlatform.CUSTOM_SERVICE,
+  appId: "your-corp-id",
+  appSecret: "your-corp-secret",
+  openKfId: "your-kf-id",
+});
+
+await sender.send({
+  toUser: "user-openid",
+  message: {
+    content: "Your AI assistant response",
+    type: "text",
+  },
+  msgId: "original-message-id",
+});
+```
+
+### Batch Sending
+
+```typescript
+const messages = [
+  {
+    toUser: "user1",
+    message: { content: "Message 1", type: "text" as const },
+  },
+  {
+    toUser: "user2",
+    message: { content: "Message 2", type: "text" as const },
+  },
+];
+
+const results = await sender.sendBatch(messages);
+console.log(results);
+```
+
+### Async Sending (Fire and Forget)
+
+```typescript
+// Send without waiting for response
+sender.sendAsync({
+  toUser: "user-openid",
+  message: {
+    content: "Notification message",
+    type: "text",
+  },
+});
+```
+
+## API Reference
+
+### WeChatSender
+
+#### Constructor
+
+```typescript
+new WeChatSender(config: WeChatConfig)
+```
+
+#### Methods
+
+- `send(options: SendMessageOptions, originMsg?: any): Promise<WeChatAPIResponse>`
+- `sendBatch(messages: SendMessageOptions[]): Promise<WeChatAPIResponse[]>`
+- `sendAsync(options: SendMessageOptions, originMsg?: any): Promise<void>`
+- `clearCache(): void`
+- `getConfig(): WeChatConfig`
+
+### Types
+
+#### WeChatPlatform
+
+```typescript
+enum WeChatPlatform {
+  CUSTOM_SERVICE = "WXCustomerService",
+  MINI_APP = "WXMiniApp",
+  SERVICE = "WXService",
+  SUBSCRIPTION = "WXSubscription",
+}
+```
+
+#### WeChatConfig
+
+```typescript
+interface WeChatConfig {
+  platform: WeChatPlatform;
+  appId: string;
+  appSecret: string;
+  openKfId?: string;
+  tokenCacheTTL?: number; // default: 7200000 (2 hours)
+}
+```
+
+#### SendMessageOptions
+
+```typescript
+interface SendMessageOptions {
+  toUser: string;
+  message: {
+    content: string;
+    type: "text" | "image" | "event" | "voice";
+    imageUrl?: string;
+  };
+  recommendQuestions?: string[];
+  msgId?: string;
+}
+```
+
+## Platform-Specific Notes
+
+### WeChat Mini Program
+- Uses customer service message API
+- Requires user to interact with mini program first
+
+### Official Account (Service/Subscription)
+- Uses customer service message API
+- User must follow the account
+
+### Enterprise WeChat Customer Service
+- Requires `openKfId` configuration
+- Supports message threading with `msgId`
+
+## Error Handling
+
+```typescript
+try {
+  await sender.send({
+    toUser: "user-openid",
+    message: { content: "Hello", type: "text" },
+  });
+} catch (error) {
+  console.error("Failed to send message:", error);
+}
+```
+
+## License
+
+ISC
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+