@warriorteam/redai-zalo-sdk 1.12.0 → 1.12.2

package/docs/WEBHOOK_MESSAGE_HELPERS.md

@@ -1,230 +0,0 @@
-# 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/webhook-message-classification.ts

@@ -1,285 +0,0 @@
-/**
- * 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();
-}