@warriorteam/redai-zalo-sdk 1.11.0 → 1.12.0

package/docs/WEBHOOK_MESSAGE_HELPERS.md

@@ -0,0 +1,230 @@
+# Webhook Message Helper Functions
+
+Tài liệu này mô tả các hàm helper để phân biệt các loại sự kiện tin nhắn trong Zalo webhook.
+
+## Tổng quan
+
+RedAI Zalo SDK cung cấp các hàm helper để dễ dàng phân biệt các loại sự kiện tin nhắn:
+
+1. **Tin nhắn từ người dùng cá nhân** - `isUserMessageEvent()`
+2. **Tin nhắn từ group** - `isGroupMessageEvent()`  
+3. **Tin nhắn OA gửi cho cá nhân** - `isOAToUserMessageEvent()`
+4. **Tin nhắn OA gửi tới group** - `isOAToGroupMessageEvent()`
+5. **Xác định hướng và đích của tin nhắn** - `getMessageDirection()`
+
+## Import
+
+```typescript
+import {
+  isUserMessageEvent,
+  isGroupMessageEvent,
+  isOAToUserMessageEvent,
+  isOAToGroupMessageEvent,
+  getMessageDirection,
+  WebhookEvent,
+} from '@warriorteam/redai-zalo-sdk';
+```
+
+## Sử dụng
+
+### 1. Phân biệt tin nhắn từ người dùng cá nhân
+
+```typescript
+function handleWebhook(event: WebhookEvent) {
+  if (isUserMessageEvent(event)) {
+    console.log('Nhận được tin nhắn từ người dùng cá nhân');
+    console.log('Sender:', event.sender.id);
+    console.log('Content:', event.message.text);
+    
+    // Xử lý tin nhắn từ user cá nhân
+    handleUserMessage(event);
+  }
+}
+```
+
+### 2. Phân biệt tin nhắn từ group
+
+```typescript
+function handleWebhook(event: WebhookEvent) {
+  if (isGroupMessageEvent(event)) {
+    console.log('Nhận được tin nhắn từ group');
+    console.log('Group ID:', event.recipient.id);
+    console.log('Sender:', event.sender.id);
+    console.log('Content:', event.message.text);
+    
+    // Xử lý tin nhắn từ group
+    handleGroupMessage(event);
+  }
+}
+```
+
+### 3. Phân biệt tin nhắn OA gửi cho cá nhân
+
+```typescript
+function handleWebhook(event: WebhookEvent) {
+  if (isOAToUserMessageEvent(event)) {
+    console.log('OA đã gửi tin nhắn cho người dùng cá nhân');
+    console.log('Recipient:', event.recipient.id);
+    console.log('Content:', event.message.text);
+    
+    // Xử lý tin nhắn OA gửi cho user
+    handleOAToUserMessage(event);
+  }
+}
+```
+
+### 4. Phân biệt tin nhắn OA gửi tới group
+
+```typescript
+function handleWebhook(event: WebhookEvent) {
+  if (isOAToGroupMessageEvent(event)) {
+    console.log('OA đã gửi tin nhắn tới group');
+    console.log('Group ID:', event.recipient.id);
+    console.log('Content:', event.message.text);
+    
+    // Xử lý tin nhắn OA gửi tới group
+    handleOAToGroupMessage(event);
+  }
+}
+```
+
+### 5. Xác định hướng và đích của tin nhắn
+
+```typescript
+function handleWebhook(event: WebhookEvent) {
+  const messageInfo = getMessageDirection(event);
+  
+  console.log('Direction:', messageInfo.direction); // 'incoming' | 'outgoing' | 'unknown'
+  console.log('Target:', messageInfo.target);       // 'user' | 'group' | 'unknown'
+  console.log('Description:', messageInfo.description);
+  
+  // Xử lý dựa trên hướng và đích
+  switch (`${messageInfo.direction}-${messageInfo.target}`) {
+    case 'incoming-user':
+      handleIncomingUserMessage(event);
+      break;
+    case 'incoming-group':
+      handleIncomingGroupMessage(event);
+      break;
+    case 'outgoing-user':
+      handleOutgoingUserMessage(event);
+      break;
+    case 'outgoing-group':
+      handleOutgoingGroupMessage(event);
+      break;
+    default:
+      console.log('Unknown message type');
+  }
+}
+```
+
+## Ví dụ tổng hợp
+
+```typescript
+import {
+  isUserMessageEvent,
+  isGroupMessageEvent,
+  isOAToUserMessageEvent,
+  isOAToGroupMessageEvent,
+  getMessageDirection,
+  WebhookEvent,
+} from '@warriorteam/redai-zalo-sdk';
+
+class ZaloWebhookHandler {
+  handleWebhook(event: WebhookEvent) {
+    // Cách 1: Sử dụng các hàm kiểm tra riêng lẻ
+    if (isUserMessageEvent(event)) {
+      this.handleUserMessage(event);
+    } else if (isGroupMessageEvent(event)) {
+      this.handleGroupMessage(event);
+    } else if (isOAToUserMessageEvent(event)) {
+      this.handleOAToUserMessage(event);
+    } else if (isOAToGroupMessageEvent(event)) {
+      this.handleOAToGroupMessage(event);
+    }
+
+    // Cách 2: Sử dụng getMessageDirection
+    const messageInfo = getMessageDirection(event);
+    this.logMessageInfo(messageInfo);
+  }
+
+  private handleUserMessage(event: UserMessageWebhookEvent) {
+    console.log('Processing user message:', event.message.text);
+    // Logic xử lý tin nhắn từ user cá nhân
+  }
+
+  private handleGroupMessage(event: GroupWebhookEvent) {
+    console.log('Processing group message:', event.message.text);
+    // Logic xử lý tin nhắn từ group
+  }
+
+  private handleOAToUserMessage(event: OAMessageWebhookEvent) {
+    console.log('Processing OA to user message:', event.message.text);
+    // Logic xử lý tin nhắn OA gửi cho user
+  }
+
+  private handleOAToGroupMessage(event: GroupWebhookEvent) {
+    console.log('Processing OA to group message:', event.message.text);
+    // Logic xử lý tin nhắn OA gửi tới group
+  }
+
+  private logMessageInfo(messageInfo: ReturnType<typeof getMessageDirection>) {
+    console.log(`Message: ${messageInfo.direction} -> ${messageInfo.target}`);
+    console.log(`Description: ${messageInfo.description}`);
+  }
+}
+```
+
+## Các loại sự kiện được hỗ trợ
+
+### User Message Events (Tin nhắn từ người dùng cá nhân)
+- `user_send_text`
+- `user_send_image`
+- `user_send_location`
+- `user_send_link`
+- `user_send_sticker`
+- `user_send_gif`
+- `user_send_audio`
+- `user_send_video`
+- `user_send_file`
+- `user_received_message`
+- `user_seen_message`
+- `user_send_business_card`
+
+### Group Message Events (Tin nhắn từ group)
+- `user_send_group_text`
+- `user_send_group_link`
+- `user_send_group_audio`
+- `user_send_group_location`
+- `user_send_group_video`
+- `user_send_group_business_card`
+- `user_send_group_sticker`
+- `user_send_group_gif`
+- `user_send_group_file`
+
+### OA to User Events (OA gửi cho cá nhân)
+- `oa_send_text`
+- `oa_send_image`
+- `oa_send_gif`
+- `oa_send_list`
+- `oa_send_file`
+- `oa_send_sticker`
+- `oa_send_template`
+
+### OA to Group Events (OA gửi tới group)
+- `oa_send_group_text`
+- `oa_send_group_image`
+- `oa_send_group_link`
+- `oa_send_group_audio`
+- `oa_send_group_location`
+- `oa_send_group_video`
+- `oa_send_group_business_card`
+- `oa_send_group_sticker`
+- `oa_send_group_gif`
+- `oa_send_group_file`
+
+## Lưu ý
+
+1. Các hàm helper này chỉ hoạt động với các sự kiện tin nhắn, không áp dụng cho các sự kiện khác như follow/unfollow.
+2. Sử dụng TypeScript để có type safety tốt nhất.
+3. Các hàm này đã được test kỹ lưỡng và an toàn để sử dụng trong production.

package/examples/oa-auth-with-pkce.ts

@@ -29,34 +29,56 @@ async function basicOAAuth() {
   console.log('Custom State:', customAuthResult.state);
 }
 
-// Example 2: OA Auth with PKCE for enhanced security
+// Example 2: OA Auth with PKCE for enhanced security (Manual PKCE)
 async function oaAuthWithPKCE() {
-  console.log('\n=== OA Auth with PKCE ===');
-  
+  console.log('\n=== OA Auth with Manual PKCE ===');
+
   const redirectUri = 'https://your-app.com/callback';
-  
+
   // Step 1: Generate PKCE configuration
   const pkce = sdk.auth.generatePKCE();
   console.log('Generated PKCE:');
   console.log('- Code Verifier:', pkce.code_verifier);
   console.log('- Code Challenge:', pkce.code_challenge);
   console.log('- Challenge Method:', pkce.code_challenge_method);
-  
-  // Step 2: Create auth URL with PKCE
-  const authResult = sdk.auth.createOAAuthUrl(redirectUri, undefined, pkce);
-  
+
+  // Step 2: Create auth URL with manual PKCE
+  const authResult = sdk.auth.createOAAuthUrl(redirectUri, undefined, pkce, true);
+
   console.log('\nAuthorization URL with PKCE:', authResult.url);
   console.log('Generated State:', authResult.state);
-  
+  console.log('Used PKCE:', authResult.pkce);
+
   // IMPORTANT: Store the code_verifier and state for later use
   // You'll need these when exchanging the authorization code for access token
   console.log('\n⚠️  IMPORTANT: Store these values for token exchange:');
   console.log('- Code Verifier:', pkce.code_verifier);
   console.log('- State:', authResult.state);
-  
+
   return { pkce, state: authResult.state };
 }
 
+// Example 2b: OA Auth with Auto-Generated PKCE
+async function oaAuthWithAutoPKCE() {
+  console.log('\n=== OA Auth with Auto-Generated PKCE ===');
+
+  const redirectUri = 'https://your-app.com/callback';
+
+  // Create auth URL with auto-generated PKCE (pkce=undefined, usePkce=true)
+  const authResult = sdk.auth.createOAAuthUrl(redirectUri, undefined, undefined, true);
+
+  console.log('Authorization URL with Auto PKCE:', authResult.url);
+  console.log('Generated State:', authResult.state);
+  console.log('Auto-Generated PKCE:', authResult.pkce);
+
+  // IMPORTANT: Store the auto-generated PKCE and state
+  console.log('\n⚠️  IMPORTANT: Store these auto-generated values:');
+  console.log('- Code Verifier:', authResult.pkce?.code_verifier);
+  console.log('- State:', authResult.state);
+
+  return authResult;
+}
+
 // Example 3: Complete flow - Authorization + Token Exchange
 async function completeOAFlow() {
   console.log('\n=== Complete OA Flow with PKCE ===');
@@ -133,6 +155,7 @@ async function runExamples() {
   try {
     await basicOAAuth();
     await oaAuthWithPKCE();
+    await oaAuthWithAutoPKCE();
     await completeOAFlow();
     await getAuthUrlsExample();
   } catch (error) {
@@ -144,6 +167,7 @@ async function runExamples() {
 export {
   basicOAAuth,
   oaAuthWithPKCE,
+  oaAuthWithAutoPKCE,
   completeOAFlow,
   getAuthUrlsExample,
   runExamples

package/examples/webhook-message-classification.ts

@@ -0,0 +1,285 @@
+/**
+ * Ví dụ sử dụng các hàm helper để phân loại tin nhắn webhook
+ */
+
+import {
+  isUserMessageEvent,
+  isGroupMessageEvent,
+  isOAToUserMessageEvent,
+  isOAToGroupMessageEvent,
+  getMessageDirection,
+  WebhookEvent,
+  UserMessageWebhookEvent,
+  GroupWebhookEvent,
+  OAMessageWebhookEvent,
+} from '@warriorteam/redai-zalo-sdk';
+
+/**
+ * Service xử lý webhook với phân loại tin nhắn
+ */
+export class ZaloWebhookMessageHandler {
+  /**
+   * Xử lý webhook event chính
+   */
+  public handleWebhook(event: WebhookEvent): void {
+    console.log('=== Webhook Event Received ===');
+    console.log('Event Name:', event.event_name);
+    console.log('Timestamp:', event.timestamp);
+
+    // Phương pháp 1: Sử dụng các hàm kiểm tra riêng lẻ
+    this.classifyBySpecificChecks(event);
+
+    // Phương pháp 2: Sử dụng getMessageDirection
+    this.classifyByDirection(event);
+
+    // Xử lý tin nhắn dựa trên loại
+    this.processMessage(event);
+  }
+
+  /**
+   * Phân loại bằng các hàm kiểm tra riêng lẻ
+   */
+  private classifyBySpecificChecks(event: WebhookEvent): void {
+    console.log('\n--- Classification by Specific Checks ---');
+
+    if (isUserMessageEvent(event)) {
+      console.log('✅ Tin nhắn từ người dùng cá nhân');
+      this.logUserMessageDetails(event);
+    } else if (isGroupMessageEvent(event)) {
+      console.log('✅ Tin nhắn từ group');
+      this.logGroupMessageDetails(event);
+    } else if (isOAToUserMessageEvent(event)) {
+      console.log('✅ OA gửi tin nhắn cho người dùng cá nhân');
+      this.logOAToUserDetails(event);
+    } else if (isOAToGroupMessageEvent(event)) {
+      console.log('✅ OA gửi tin nhắn tới group');
+      this.logOAToGroupDetails(event);
+    } else {
+      console.log('❓ Sự kiện không phải tin nhắn hoặc không xác định');
+    }
+  }
+
+  /**
+   * Phân loại bằng getMessageDirection
+   */
+  private classifyByDirection(event: WebhookEvent): void {
+    console.log('\n--- Classification by Direction ---');
+
+    const messageInfo = getMessageDirection(event);
+    console.log(`Direction: ${messageInfo.direction}`);
+    console.log(`Target: ${messageInfo.target}`);
+    console.log(`Description: ${messageInfo.description}`);
+
+    // Xử lý dựa trên direction và target
+    const key = `${messageInfo.direction}-${messageInfo.target}`;
+    switch (key) {
+      case 'incoming-user':
+        console.log('🔵 Xử lý tin nhắn đến từ user cá nhân');
+        break;
+      case 'incoming-group':
+        console.log('🟢 Xử lý tin nhắn đến từ group');
+        break;
+      case 'outgoing-user':
+        console.log('🟡 Xử lý tin nhắn OA gửi cho user');
+        break;
+      case 'outgoing-group':
+        console.log('🟠 Xử lý tin nhắn OA gửi tới group');
+        break;
+      default:
+        console.log('⚪ Sự kiện không xác định');
+    }
+  }
+
+  /**
+   * Xử lý tin nhắn dựa trên loại
+   */
+  private processMessage(event: WebhookEvent): void {
+    console.log('\n--- Message Processing ---');
+
+    if (isUserMessageEvent(event)) {
+      this.processUserMessage(event);
+    } else if (isGroupMessageEvent(event)) {
+      this.processGroupMessage(event);
+    } else if (isOAToUserMessageEvent(event)) {
+      this.processOAToUserMessage(event);
+    } else if (isOAToGroupMessageEvent(event)) {
+      this.processOAToGroupMessage(event);
+    }
+  }
+
+  /**
+   * Xử lý tin nhắn từ user cá nhân
+   */
+  private processUserMessage(event: UserMessageWebhookEvent): void {
+    console.log('Processing user message...');
+    
+    // Logic xử lý tin nhắn từ user cá nhân
+    // - Lưu vào database
+    // - Trigger AI response
+    // - Update conversation state
+    
+    console.log('✅ User message processed');
+  }
+
+  /**
+   * Xử lý tin nhắn từ group
+   */
+  private processGroupMessage(event: GroupWebhookEvent): void {
+    console.log('Processing group message...');
+    
+    // Logic xử lý tin nhắn từ group
+    // - Check if OA is mentioned
+    // - Apply group-specific rules
+    // - Handle group moderation
+    
+    console.log('✅ Group message processed');
+  }
+
+  /**
+   * Xử lý tin nhắn OA gửi cho user
+   */
+  private processOAToUserMessage(event: OAMessageWebhookEvent): void {
+    console.log('Processing OA to user message...');
+    
+    // Logic xử lý tin nhắn OA gửi
+    // - Log outbound message
+    // - Update delivery status
+    // - Track engagement metrics
+    
+    console.log('✅ OA to user message processed');
+  }
+
+  /**
+   * Xử lý tin nhắn OA gửi tới group
+   */
+  private processOAToGroupMessage(event: GroupWebhookEvent): void {
+    console.log('Processing OA to group message...');
+    
+    // Logic xử lý tin nhắn OA gửi tới group
+    // - Log group broadcast
+    // - Track group engagement
+    // - Update group statistics
+    
+    console.log('✅ OA to group message processed');
+  }
+
+  /**
+   * Log chi tiết tin nhắn user
+   */
+  private logUserMessageDetails(event: UserMessageWebhookEvent): void {
+    console.log(`  - Sender ID: ${event.sender.id}`);
+    console.log(`  - Recipient ID: ${event.recipient.id}`);
+    if ('message' in event && event.message.text) {
+      console.log(`  - Text: ${event.message.text}`);
+    }
+  }
+
+  /**
+   * Log chi tiết tin nhắn group
+   */
+  private logGroupMessageDetails(event: GroupWebhookEvent): void {
+    console.log(`  - Sender ID: ${event.sender.id}`);
+    console.log(`  - Group ID: ${event.recipient.id}`);
+    if ('oa_id' in event) {
+      console.log(`  - OA ID: ${event.oa_id}`);
+    }
+    if ('message' in event && event.message.text) {
+      console.log(`  - Text: ${event.message.text}`);
+    }
+  }
+
+  /**
+   * Log chi tiết OA to user
+   */
+  private logOAToUserDetails(event: OAMessageWebhookEvent): void {
+    console.log(`  - OA ID: ${event.sender.id}`);
+    console.log(`  - User ID: ${event.recipient.id}`);
+    if ('message' in event && event.message.text) {
+      console.log(`  - Text: ${event.message.text}`);
+    }
+  }
+
+  /**
+   * Log chi tiết OA to group
+   */
+  private logOAToGroupDetails(event: GroupWebhookEvent): void {
+    console.log(`  - OA ID: ${event.sender.id}`);
+    console.log(`  - Group ID: ${event.recipient.id}`);
+    if ('oa_id' in event) {
+      console.log(`  - OA ID: ${event.oa_id}`);
+    }
+    if ('message' in event && event.message.text) {
+      console.log(`  - Text: ${event.message.text}`);
+    }
+  }
+}
+
+/**
+ * Ví dụ sử dụng
+ */
+export function exampleUsage(): void {
+  const handler = new ZaloWebhookMessageHandler();
+
+  // Ví dụ 1: Tin nhắn từ user cá nhân
+  const userMessage = {
+    app_id: 'test-app',
+    user_id_by_app: 'test-user',
+    event_name: 'user_send_text',
+    timestamp: '1234567890',
+    sender: { id: 'user123' },
+    recipient: { id: 'oa123' },
+    message: { msg_id: 'msg123', text: 'Xin chào!' }
+  };
+
+  console.log('=== Example 1: User Message ===');
+  handler.handleWebhook(userMessage as any);
+
+  // Ví dụ 2: Tin nhắn từ group
+  const groupMessage = {
+    app_id: 'test-app',
+    user_id_by_app: 'test-user',
+    event_name: 'user_send_group_text',
+    timestamp: '1234567890',
+    oa_id: 'oa123',
+    sender: { id: 'user456' },
+    recipient: { id: 'group789' },
+    message: { msg_id: 'msg456', text: 'Hello group!' }
+  };
+
+  console.log('\n=== Example 2: Group Message ===');
+  handler.handleWebhook(groupMessage as any);
+
+  // Ví dụ 3: OA gửi cho user
+  const oaToUserMessage = {
+    app_id: 'test-app',
+    user_id_by_app: 'test-user',
+    event_name: 'oa_send_text',
+    timestamp: '1234567890',
+    sender: { id: 'oa123' },
+    recipient: { id: 'user789' },
+    message: { msg_id: 'msg789', text: 'Cảm ơn bạn đã liên hệ!' }
+  };
+
+  console.log('\n=== Example 3: OA to User Message ===');
+  handler.handleWebhook(oaToUserMessage as any);
+
+  // Ví dụ 4: OA gửi tới group
+  const oaToGroupMessage = {
+    app_id: 'test-app',
+    user_id_by_app: 'test-user',
+    event_name: 'oa_send_group_text',
+    timestamp: '1234567890',
+    oa_id: 'oa123',
+    sender: { id: 'oa123' },
+    recipient: { id: 'group456' },
+    message: { msg_id: 'msg101', text: 'Thông báo từ OA!' }
+  };
+
+  console.log('\n=== Example 4: OA to Group Message ===');
+  handler.handleWebhook(oaToGroupMessage as any);
+}
+
+// Chạy ví dụ nếu file được execute trực tiếp
+if (require.main === module) {
+  exampleUsage();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warriorteam/redai-zalo-sdk",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account, ZNS, Consultation Service, Group Messaging, and Social APIs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",