@warriorteam/redai-zalo-sdk 1.1.0 → 1.2.0

package/docs/ARTICLE_MANAGEMENT.md

@@ -0,0 +1,336 @@
+# Article Management Service
+
+The `ArticleService` and `VideoUploadService` provide comprehensive article management capabilities for Zalo Official Account (OA).
+
+## Features
+
+### ArticleService
+- ✅ Create normal articles with rich content
+- ✅ Create video articles
+- ✅ Update existing articles
+- ✅ Get article details and lists
+- ✅ Remove articles
+- ✅ Track article creation/update progress
+- ✅ Comprehensive validation
+
+### VideoUploadService
+- ✅ Upload video files for articles
+- ✅ Check video processing status
+- ✅ Wait for upload completion with polling
+- ✅ Upload videos from URLs
+- ✅ Get video information
+
+## Prerequisites
+
+1. **OA Requirements:**
+   - OA must have permission to create articles
+   - Access token must have "manage_article" scope
+   - OA must have active status and be verified
+
+2. **Content Limits:**
+   - Title: max 150 characters
+   - Author: max 50 characters (normal articles only)
+   - Description: max 300 characters
+   - Image size: max 1MB per image
+   - Video size: max 50MB per video
+   - Video formats: MP4, AVI only
+
+## Usage
+
+### Initialize SDK
+
+```typescript
+import { ZaloSDK } from 'redai-zalo-sdk';
+
+const sdk = new ZaloSDK({
+  appId: 'your_app_id',
+  appSecret: 'your_app_secret',
+});
+
+const article = sdk.article;
+const videoUpload = sdk.videoUpload;
+```
+
+### 1. Create Normal Article
+
+```typescript
+import { ArticleType, ArticleStatus, CommentStatus, CoverType, BodyItemType } from 'redai-zalo-sdk';
+
+const normalArticle = {
+  type: ArticleType.NORMAL,
+  title: "Welcome to Our Service",
+  author: "RedAI Team",
+  description: "This is a comprehensive guide to our new features",
+  cover: {
+    cover_type: CoverType.PHOTO,
+    photo_url: "https://example.com/cover.jpg",
+    status: ArticleStatus.SHOW
+  },
+  body: [
+    {
+      type: BodyItemType.TEXT,
+      content: "Welcome to our new service! Here's what you need to know..."
+    },
+    {
+      type: BodyItemType.IMAGE,
+      url: "https://example.com/image1.jpg"
+    },
+    {
+      type: BodyItemType.TEXT,
+      content: "For more information, please contact us."
+    }
+  ],
+  tracking_link: "https://your-website.com/tracking",
+  status: ArticleStatus.SHOW,
+  comment: CommentStatus.SHOW
+};
+
+const result = await article.createNormalArticle(accessToken, normalArticle);
+console.log(`Article creation token: ${result.token}`);
+```
+
+### 2. Create Video Article
+
+```typescript
+const videoArticle = {
+  type: ArticleType.VIDEO,
+  title: "Product Demo Video",
+  description: "Watch our latest product demonstration",
+  video_id: "your_video_id", // Get from video upload
+  avatar: "https://example.com/thumbnail.jpg",
+  status: ArticleStatus.SHOW,
+  comment: CommentStatus.SHOW
+};
+
+const result = await article.createVideoArticle(accessToken, videoArticle);
+console.log(`Video article creation token: ${result.token}`);
+```
+
+### 3. Upload Video for Articles
+
+```typescript
+// Upload video file
+const videoFile = new File([videoBuffer], 'demo.mp4', { type: 'video/mp4' });
+const uploadResult = await videoUpload.uploadVideo(accessToken, videoFile);
+
+// Wait for processing completion
+const finalResult = await videoUpload.waitForUploadCompletion(
+  accessToken, 
+  uploadResult.token,
+  5 * 60 * 1000, // 5 minutes timeout
+  5 * 1000       // 5 seconds polling interval
+);
+
+console.log(`Video ID: ${finalResult.video_id}`);
+```
+
+### 4. Upload Video from URL
+
+```typescript
+const uploadResult = await videoUpload.uploadVideoFromUrl(
+  accessToken,
+  'https://example.com/video.mp4'
+);
+
+const finalResult = await videoUpload.waitForUploadCompletion(
+  accessToken,
+  uploadResult.token
+);
+```
+
+### 5. Check Article Creation Progress
+
+```typescript
+const progress = await article.checkArticleProcess(accessToken, token);
+
+switch (progress.status) {
+  case 'processing':
+    console.log('Article is still being processed...');
+    break;
+  case 'success':
+    console.log(`Article created with ID: ${progress.article_id}`);
+    break;
+  case 'failed':
+    console.error(`Article creation failed: ${progress.error_message}`);
+    break;
+}
+```
+
+### 6. Get Article Details
+
+```typescript
+const articleDetail = await article.getArticleDetail(accessToken, articleId);
+console.log('Article details:', articleDetail);
+```
+
+### 7. Get Article List
+
+```typescript
+const articleList = await article.getArticleList(accessToken, {
+  offset: 0,
+  limit: 20,
+  type: 'normal' // or 'video'
+});
+
+console.log(`Found ${articleList.data.total} articles`);
+articleList.data.articles.forEach(article => {
+  console.log(`- ${article.title} (${article.total_view} views)`);
+});
+```
+
+### 8. Update Article
+
+```typescript
+const updateData = {
+  id: articleId,
+  type: ArticleType.NORMAL,
+  title: "Updated Article Title",
+  author: "Updated Author",
+  description: "Updated description",
+  cover: {
+    cover_type: CoverType.PHOTO,
+    photo_url: "https://example.com/new-cover.jpg",
+    status: ArticleStatus.SHOW
+  },
+  body: [
+    {
+      type: BodyItemType.TEXT,
+      content: "Updated content..."
+    }
+  ],
+  status: ArticleStatus.SHOW
+};
+
+const updateResult = await article.updateNormalArticle(accessToken, updateData);
+console.log(`Update token: ${updateResult.token}`);
+```
+
+### 9. Remove Article
+
+```typescript
+const removeResult = await article.removeArticle(accessToken, articleId);
+console.log(removeResult.message);
+```
+
+### 10. Check Video Status
+
+```typescript
+const videoStatus = await videoUpload.checkVideoStatus(accessToken, token);
+
+console.log(`Status: ${videoStatus.status}`);
+console.log(`Progress: ${videoStatus.convert_percent}%`);
+
+if (videoStatus.video_id) {
+  console.log(`Video ID: ${videoStatus.video_id}`);
+}
+```
+
+## Error Handling
+
+```typescript
+import { ZaloSDKError } from 'redai-zalo-sdk';
+
+try {
+  const result = await article.createNormalArticle(accessToken, articleData);
+  console.log('Success:', result);
+} catch (error) {
+  if (error instanceof ZaloSDKError) {
+    console.error('Zalo API Error:', error.message, error.code);
+    console.error('Details:', error.details);
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { ZaloSDK, ArticleType, CoverType, BodyItemType, ArticleStatus } from 'redai-zalo-sdk';
+
+class ArticleManager {
+  private sdk: ZaloSDK;
+  
+  constructor() {
+    this.sdk = new ZaloSDK({
+      appId: process.env.ZALO_APP_ID!,
+      appSecret: process.env.ZALO_APP_SECRET!,
+    });
+  }
+
+  async createCompleteArticle(accessToken: string) {
+    try {
+      // 1. Upload video first (if needed)
+      const videoFile = new File([videoBuffer], 'demo.mp4');
+      const videoUpload = await this.sdk.videoUpload.uploadVideo(accessToken, videoFile);
+      const videoResult = await this.sdk.videoUpload.waitForUploadCompletion(
+        accessToken, 
+        videoUpload.token
+      );
+
+      // 2. Create article with video
+      const article = await this.sdk.article.createNormalArticle(accessToken, {
+        type: ArticleType.NORMAL,
+        title: "Complete Guide",
+        author: "RedAI Team",
+        description: "A complete guide with video content",
+        cover: {
+          cover_type: CoverType.PHOTO,
+          photo_url: "https://example.com/cover.jpg",
+          status: ArticleStatus.SHOW
+        },
+        body: [
+          {
+            type: BodyItemType.TEXT,
+            content: "Introduction to our service..."
+          },
+          {
+            type: BodyItemType.VIDEO,
+            video_id: videoResult.video_id
+          },
+          {
+            type: BodyItemType.TEXT,
+            content: "Thank you for watching!"
+          }
+        ],
+        status: ArticleStatus.SHOW
+      });
+
+      // 3. Wait for article creation
+      const articleProgress = await this.sdk.article.checkArticleProcess(
+        accessToken, 
+        article.token
+      );
+
+      return articleProgress;
+    } catch (error) {
+      console.error('Article creation error:', error);
+      throw error;
+    }
+  }
+}
+```
+
+## Validation Rules
+
+### Normal Articles
+- Title: required, max 150 characters
+- Author: required, max 50 characters  
+- Description: required, max 300 characters
+- Cover: required, must specify type and corresponding URL/ID
+- Body: required, at least one item
+
+### Video Articles
+- Title: required, max 150 characters
+- Description: required, max 300 characters
+- Video ID: required, must be valid uploaded video
+- Avatar: required, thumbnail URL
+
+### Video Files
+- Formats: MP4, AVI only
+- Size: max 50MB
+- Processing: asynchronous, use polling to check status
+
+## API Reference
+
+For detailed API documentation, see the TypeScript definitions in the source code. All methods include comprehensive JSDoc comments with parameter descriptions and return types.

package/docs/CONSULTATION_SERVICE.md

@@ -0,0 +1,330 @@
+# Consultation Service - Hướng Dẫn Sử Dụng
+
+## Tổng Quan
+
+`ConsultationService` là dịch vụ chuyên dụng để gửi tin nhắn tư vấn (Customer Service) qua Zalo Official Account. Tin nhắn tư vấn cho phép OA gửi tin nhắn chủ động đến người dùng trong khung thời gian nhất định để hỗ trợ và tư vấn khách hàng.
+
+## Điều Kiện Gửi Tin Nhắn Tư Vấn
+
+### 1. Thời Gian Gửi
+- **Khung thời gian**: Chỉ được gửi trong vòng **48 giờ** kể từ khi người dùng tương tác cuối cùng với OA
+- **Tương tác bao gồm**:
+  - Gửi tin nhắn đến OA
+  - Nhấn button/quick reply
+  - Gọi điện thoại từ OA
+  - Truy cập website từ OA
+
+### 2. Nội Dung Tin Nhắn
+- **Mục đích**: Phải liên quan đến tư vấn, hỗ trợ khách hàng
+- **Bao gồm**: Trả lời câu hỏi, hướng dẫn sử dụng, hỗ trợ kỹ thuật
+- **Không được**: Chứa nội dung quảng cáo trực tiếp
+
+### 3. Điều Kiện Người Dùng
+- Người dùng phải đã follow OA
+- Người dùng không được block OA
+- Người dùng phải có tương tác gần đây với OA
+
+### 4. Tần Suất Gửi
+- Không giới hạn số lượng tin nhắn tư vấn trong ngày
+- Cần tuân thủ nguyên tắc không spam
+
+## Khởi Tạo Service
+
+```typescript
+import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
+
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret",
+  debug: true
+});
+
+// Lấy consultation service
+const consultationService = zalo.consultation;
+```
+
+## Các Phương Thức Chính
+
+### 1. Gửi Tin Nhắn Văn Bản
+
+```typescript
+// Gửi tin nhắn văn bản tư vấn
+const response = await consultationService.sendTextMessage(
+  accessToken,
+  { user_id: "user-id-here" },
+  {
+    type: "text",
+    text: "Xin chào! Tôi có thể hỗ trợ gì cho bạn?"
+  }
+);
+
+console.log("Message ID:", response.message_id);
+console.log("Quota remaining:", response.quota?.remain);
+```
+
+**Giới hạn văn bản:**
+- Nội dung không được để trống
+- Tối đa 2000 ký tự
+
+### 2. Gửi Tin Nhắn Hình Ảnh
+
+```typescript
+// Gửi hình ảnh tư vấn
+const response = await consultationService.sendImageMessage(
+  accessToken,
+  { user_id: "user-id-here" },
+  {
+    type: "image",
+    attachment: {
+      type: "image",
+      payload: {
+        url: "https://example.com/support-image.jpg"
+      }
+    }
+  }
+);
+```
+
+### 3. Gửi File Đính Kèm
+
+```typescript
+// Gửi file hướng dẫn
+const response = await consultationService.sendFileMessage(
+  accessToken,
+  { user_id: "user-id-here" },
+  {
+    type: "file",
+    url: "https://example.com/user-manual.pdf",
+    filename: "Hướng dẫn sử dụng.pdf",
+    attachment: {
+      type: "file",
+      payload: {
+        url: "https://example.com/user-manual.pdf"
+      }
+    }
+  }
+);
+```
+
+### 4. Gửi Sticker
+
+```typescript
+// Gửi sticker thân thiện
+const response = await consultationService.sendStickerMessage(
+  accessToken,
+  { user_id: "user-id-here" },
+  {
+    type: "sticker",
+    sticker_id: "sticker-id",
+    attachment: {
+      type: "sticker",
+      payload: {
+        id: "sticker-id"
+      }
+    }
+  }
+);
+```
+
+### 5. Gửi Tin Nhắn Tổng Quát
+
+```typescript
+// Gửi bất kỳ loại tin nhắn nào
+const response = await consultationService.sendMessage(
+  accessToken,
+  { user_id: "user-id-here" },
+  {
+    type: "text",
+    text: "Cảm ơn bạn đã liên hệ. Chúng tôi sẽ hỗ trợ bạn ngay!"
+  }
+);
+```
+
+## Xử Lý Lỗi
+
+```typescript
+import { ZaloSDKError } from "@warriorteam/redai-zalo-sdk";
+
+try {
+  const response = await consultationService.sendTextMessage(
+    accessToken,
+    { user_id: "user-id" },
+    { type: "text", text: "Hello!" }
+  );
+} catch (error) {
+  if (error instanceof ZaloSDKError) {
+    console.error("Zalo API Error:", error.message);
+    console.error("Error Code:", error.code);
+    
+    // Xử lý các lỗi phổ biến
+    switch (error.code) {
+      case -216:
+        console.log("Access token không hợp lệ");
+        break;
+      case -201:
+        console.log("Tham số không hợp lệ");
+        break;
+      case -223:
+        console.log("Đã vượt quá quota");
+        break;
+      default:
+        console.log("Lỗi khác:", error.message);
+    }
+  }
+}
+```
+
+## Ví Dụ Thực Tế
+
+### Hệ Thống Hỗ Trợ Khách Hàng
+
+```typescript
+class CustomerSupportBot {
+  constructor(private consultationService: ConsultationService) {}
+
+  async handleUserQuestion(accessToken: string, userId: string, question: string) {
+    try {
+      // Phân tích câu hỏi và tạo phản hồi
+      const response = this.generateResponse(question);
+      
+      // Gửi tin nhắn tư vấn
+      await this.consultationService.sendTextMessage(
+        accessToken,
+        { user_id: userId },
+        {
+          type: "text",
+          text: response
+        }
+      );
+
+      // Gửi thêm hình ảnh hướng dẫn nếu cần
+      if (this.needsVisualGuide(question)) {
+        await this.consultationService.sendImageMessage(
+          accessToken,
+          { user_id: userId },
+          {
+            type: "image",
+            attachment: {
+              type: "image",
+              payload: {
+                url: "https://example.com/guide-image.jpg"
+              }
+            }
+          }
+        );
+      }
+
+    } catch (error) {
+      console.error("Failed to send consultation message:", error);
+    }
+  }
+
+  private generateResponse(question: string): string {
+    // Logic tạo phản hồi dựa trên câu hỏi
+    if (question.includes("đăng nhập")) {
+      return "Để đăng nhập, bạn vui lòng làm theo các bước sau...";
+    }
+    
+    if (question.includes("thanh toán")) {
+      return "Về vấn đề thanh toán, chúng tôi hỗ trợ các phương thức...";
+    }
+    
+    return "Cảm ơn bạn đã liên hệ. Chúng tôi sẽ hỗ trợ bạn ngay!";
+  }
+
+  private needsVisualGuide(question: string): boolean {
+    return question.includes("hướng dẫn") || question.includes("cách làm");
+  }
+}
+```
+
+### Tích Hợp Với Webhook
+
+```typescript
+// Xử lý tin nhắn từ webhook
+app.post('/webhook', async (req, res) => {
+  const event = req.body;
+  
+  if (event.event_name === 'user_send_text') {
+    const userId = event.sender.id;
+    const userMessage = event.message.text;
+    
+    // Kiểm tra xem có phải câu hỏi cần hỗ trợ không
+    if (userMessage.includes('help') || userMessage.includes('hỗ trợ')) {
+      
+      // Gửi tin nhắn tư vấn
+      await consultationService.sendTextMessage(
+        accessToken,
+        { user_id: userId },
+        {
+          type: "text",
+          text: "Tôi có thể hỗ trợ bạn về các vấn đề sau:\n1. Đăng nhập\n2. Thanh toán\n3. Sử dụng sản phẩm\nBạn cần hỗ trợ về vấn đề nào?"
+        }
+      );
+    }
+  }
+  
+  res.status(200).send('OK');
+});
+```
+
+## Best Practices
+
+### 1. Kiểm Tra Thời Gian Tương Tác
+```typescript
+// Kiểm tra thời gian tương tác cuối cùng trước khi gửi
+const lastInteraction = await getUserLastInteraction(userId);
+const hoursSinceLastInteraction = (Date.now() - lastInteraction) / (1000 * 60 * 60);
+
+if (hoursSinceLastInteraction > 48) {
+  console.log("Không thể gửi tin nhắn tư vấn - quá 48 giờ");
+  return;
+}
+```
+
+### 2. Quản Lý Quota
+```typescript
+// Kiểm tra quota trước khi gửi
+const quota = await zalo.oa.getQuotaSummary(accessToken);
+if (quota.consultation.remaining <= 0) {
+  console.log("Đã hết quota tin nhắn tư vấn");
+  return;
+}
+```
+
+### 3. Retry Logic
+```typescript
+async function sendWithRetry(
+  consultationService: ConsultationService,
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: Message,
+  maxRetries = 3
+) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await consultationService.sendMessage(accessToken, recipient, message);
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+      
+      // Đợi trước khi retry
+      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
+    }
+  }
+}
+```
+
+## Lưu Ý Quan Trọng
+
+1. **Tuân thủ chính sách**: Chỉ gửi tin nhắn tư vấn thực sự, không spam
+2. **Theo dõi quota**: Kiểm tra quota thường xuyên để tránh vượt giới hạn
+3. **Xử lý lỗi**: Luôn có cơ chế xử lý lỗi phù hợp
+4. **Logging**: Ghi log để theo dõi và debug
+5. **Rate limiting**: Tránh gửi quá nhiều tin nhắn trong thời gian ngắn
+
+## Tài Liệu Liên Quan
+
+- [Message Types](./MESSAGE_TYPES.md) - Các loại tin nhắn được hỗ trợ
+- [Webhook Events](./WEBHOOK_EVENTS.md) - Xử lý sự kiện webhook
+- [Error Handling](./ERROR_HANDLING.md) - Xử lý lỗi chi tiết
+- [Quota Management](./QUOTA_MANAGEMENT.md) - Quản lý quota tin nhắn