@warriorteam/redai-zalo-sdk 1.12.2 → 1.12.5

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.12.2",
+  "version": "1.12.5",
   "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",

package/ARCHITECTURE.md

@@ -1,265 +0,0 @@
-# RedAI Zalo SDK Architecture
-
-## Overview
-
-RedAI Zalo SDK là một TypeScript SDK hoàn chỉnh cho các API của Zalo, được thiết kế với kiến trúc modular và type-safe.
-
-## Cấu trúc thư mục
-
-```
-redai-zalo-sdk/
-├── src/
-│   ├── types/           # Type definitions
-│   │   ├── common.ts    # Common types và interfaces
-│   │   ├── auth.ts      # Authentication types
-│   │   ├── oa.ts        # Official Account types
-│   │   ├── message.ts   # Message types
-│   │   └── webhook.ts   # Webhook types
-│   ├── clients/         # HTTP clients
-│   │   ├── base-client.ts    # Base HTTP client
-│   │   └── zalo-client.ts    # Zalo-specific client
-│   ├── services/        # Business logic services
-│   │   ├── auth.service.ts     # Authentication service
-│   │   ├── oa.service.ts       # Official Account service
-│   │   └── message.service.ts  # Message service
-│   ├── utils/           # Utility functions
-│   ├── index.ts         # Main export file
-│   └── zalo-sdk.ts      # Main SDK class
-├── examples/            # Usage examples
-├── dist/               # Build output
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-## Kiến trúc chính
-
-### 1. Layered Architecture
-
-SDK được thiết kế theo kiến trúc phân lớp:
-
-```
-┌─────────────────┐
-│   Main SDK      │  ← ZaloSDK class (public API)
-├─────────────────┤
-│   Services      │  ← Business logic (AuthService, OAService, MessageService)
-├─────────────────┤
-│   Clients       │  ← HTTP communication (BaseClient, ZaloClient)
-├─────────────────┤
-│   Types         │  ← Type definitions và interfaces
-└─────────────────┘
-```
-
-### 2. Core Components
-
-#### ZaloSDK (Main Class)
-- Entry point cho tất cả các chức năng
-- Khởi tạo và quản lý các services
-- Cung cấp quick methods cho các tác vụ phổ biến
-- Quản lý configuration và lifecycle
-
-#### BaseClient
-- HTTP client cơ bản với axios
-- Retry mechanism
-- Error handling
-- Request/response logging
-- File upload support
-
-#### ZaloClient
-- Extends BaseClient
-- Zalo-specific endpoints
-- API versioning support
-- OAuth và ZNS endpoint handling
-
-#### Services
-- **AuthService**: OAuth flows, token management
-- **OAService**: Official Account operations
-- **MessageService**: Message sending và file upload
-
-### 3. Type System
-
-#### Comprehensive Types
-- Tất cả API responses được type-safe
-- Union types cho message types
-- Enum cho constants
-- Generic types cho reusability
-
-#### Error Handling
-- Custom `ZaloSDKError` class
-- Structured error information
-- Error code mapping
-
-### 4. Configuration
-
-```typescript
-interface ZaloSDKConfig {
-  appId: string;
-  appSecret: string;
-  timeout?: number;
-  debug?: boolean;
-  apiBaseUrl?: string;
-  retry?: {
-    attempts?: number;
-    delay?: number;
-  };
-}
-```
-
-## Design Patterns
-
-### 1. Builder Pattern
-SDK configuration với default values và validation.
-
-### 2. Service Pattern
-Mỗi service chịu trách nhiệm cho một domain cụ thể.
-
-### 3. Factory Pattern
-Client creation và service initialization.
-
-### 4. Strategy Pattern
-Different authentication flows (OA vs Social).
-
-### 5. Observer Pattern
-Webhook event handling (planned).
-
-## Key Features
-
-### 1. Type Safety
-- Full TypeScript support
-- Comprehensive type definitions
-- Generic types cho flexibility
-- Union types cho message variants
-
-### 2. Error Handling
-- Structured error responses
-- Retry mechanism
-- Detailed error information
-- Error code mapping
-
-### 3. Authentication
-- OAuth 2.0 flows
-- PKCE support
-- Token refresh
-- Multiple auth scopes
-
-### 4. Extensibility
-- Modular architecture
-- Easy to add new services
-- Plugin-ready design
-- Custom request support
-
-### 5. Developer Experience
-- IntelliSense support
-- Comprehensive documentation
-- Usage examples
-- Debug logging
-
-## API Design Principles
-
-### 1. Consistency
-- Consistent naming conventions
-- Uniform error handling
-- Standard response formats
-
-### 2. Simplicity
-- Easy-to-use public API
-- Quick methods cho common tasks
-- Sensible defaults
-
-### 3. Flexibility
-- Low-level access khi cần
-- Custom request support
-- Configurable behavior
-
-### 4. Reliability
-- Retry mechanisms
-- Error recovery
-- Connection testing
-
-## Future Enhancements
-
-### 1. Additional Services
-- ZNS Service (Zalo Notification Service)
-- User Management Service
-- Group Management Service
-- Webhook Service
-
-### 2. Advanced Features
-- Rate limiting
-- Caching
-- Batch operations
-- Real-time subscriptions
-
-### 3. Developer Tools
-- CLI tools
-- Testing utilities
-- Mock server
-- Documentation generator
-
-## Testing Strategy
-
-### 1. Unit Tests
-- Service logic testing
-- Type validation
-- Error handling
-
-### 2. Integration Tests
-- API endpoint testing
-- Authentication flows
-- File upload/download
-
-### 3. E2E Tests
-- Complete workflows
-- Real API interactions
-- Error scenarios
-
-## Performance Considerations
-
-### 1. HTTP Optimization
-- Connection pooling
-- Request compression
-- Timeout management
-
-### 2. Memory Management
-- Efficient data structures
-- Stream processing cho large files
-- Garbage collection friendly
-
-### 3. Network Efficiency
-- Batch requests
-- Caching strategies
-- Retry with backoff
-
-## Security
-
-### 1. Token Management
-- Secure token storage
-- Automatic refresh
-- Token validation
-
-### 2. Request Security
-- HTTPS only
-- Request signing
-- Parameter validation
-
-### 3. Error Information
-- Sanitized error messages
-- No sensitive data in logs
-- Secure debugging
-
-## Deployment
-
-### 1. Package Distribution
-- NPM package
-- TypeScript declarations
-- Source maps
-
-### 2. Versioning
-- Semantic versioning
-- Backward compatibility
-- Migration guides
-
-### 3. Documentation
-- API documentation
-- Usage examples
-- Migration guides