@warriorteam/redai-zalo-sdk 1.1.0 → 1.1.1

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/GROUP_MANAGEMENT.md

@@ -0,0 +1,232 @@
+# Group Management Service
+
+The `GroupManagementService` provides comprehensive group management capabilities for Zalo Official Account (OA) using the Group Message Framework (GMF).
+
+## Features
+
+- ✅ Create new groups with asset_id
+- ✅ Update group information and avatar
+- ✅ Invite and remove members
+- ✅ Manage pending member requests
+- ✅ Add and remove admin rights
+- ✅ Delete groups
+- ✅ Get group information and member lists
+- ✅ Manage group quota and assets
+- ✅ Get conversation history
+
+## Prerequisites
+
+1. **OA Requirements:**
+   - OA must be granted GMF (Group Message Framework) permissions
+   - Access token must have "manage_group" and "group_message" scopes
+   - OA must have active status and be verified
+
+2. **Limits:**
+   - Maximum groups: 10-100 (depends on service package)
+   - Maximum members per group: 200 people
+   - Group creation frequency: max 10 groups/day
+   - Member invitation frequency: max 500 invitations/day
+
+## Usage
+
+### Initialize SDK
+
+```typescript
+import { ZaloSDK } from 'redai-zalo-sdk';
+
+const sdk = new ZaloSDK({
+  appId: 'your_app_id',
+  appSecret: 'your_app_secret',
+});
+
+const groupManagement = sdk.groupManagement;
+```
+
+### 1. Create Group
+
+```typescript
+const groupData = {
+  group_name: "Support Group",
+  description: "Customer support group",
+  asset_id: "your_asset_id", // Get from getAssetId()
+  member_uids: ["user1", "user2", "user3"]
+};
+
+const result = await groupManagement.createGroup(accessToken, groupData);
+console.log(`Group created with ID: ${result.group_id}`);
+```
+
+### 2. Get Group Information
+
+```typescript
+const groupInfo = await groupManagement.getGroupInfo(accessToken, groupId);
+console.log('Group details:', groupInfo);
+```
+
+### 3. Update Group Information
+
+```typescript
+const updateData = {
+  group_name: "New Group Name",
+  description: "Updated description"
+};
+
+await groupManagement.updateGroupInfo(accessToken, groupId, updateData);
+```
+
+### 4. Invite Members
+
+```typescript
+const inviteData = {
+  member_uids: ["user4", "user5"]
+};
+
+const result = await groupManagement.inviteMembers(accessToken, groupId, inviteData);
+console.log(`Invited ${result.invited_count} members`);
+```
+
+### 5. Manage Pending Members
+
+```typescript
+// Get pending members
+const pending = await groupManagement.getPendingMembers(accessToken, groupId);
+
+// Accept pending members
+const memberIds = pending.data?.members.map(m => m.user_id) || [];
+await groupManagement.acceptPendingMembers(accessToken, groupId, memberIds);
+
+// Or reject pending members
+await groupManagement.rejectPendingMembers(accessToken, groupId, memberIds);
+```
+
+### 6. Manage Admins
+
+```typescript
+// Add admin rights
+const adminData = { admin_uids: ["user1"] };
+await groupManagement.addAdmins(accessToken, groupId, adminData);
+
+// Remove admin rights
+await groupManagement.removeAdmins(accessToken, groupId, adminData);
+```
+
+### 7. Get Asset ID for Group Creation
+
+```typescript
+// Get single asset_id
+const assetId = await groupManagement.getAssetId(accessToken);
+
+// Get all available asset_ids
+const assets = await groupManagement.getAssetIds(accessToken);
+console.log('Available assets:', assets.data);
+```
+
+### 8. Get Group Members
+
+```typescript
+const members = await groupManagement.getGroupMembers(accessToken, groupId, 0, 10);
+console.log('Group members:', members.data?.members);
+```
+
+### 9. Remove Members
+
+```typescript
+const memberIds = ["user1", "user2"];
+await groupManagement.removeMembers(accessToken, groupId, memberIds);
+```
+
+### 10. Delete Group
+
+```typescript
+await groupManagement.deleteGroup(accessToken, groupId);
+console.log('Group deleted successfully');
+```
+
+### 11. Get Groups of OA
+
+```typescript
+const groups = await groupManagement.getGroupsOfOA(accessToken, 0, 20);
+console.log(`Found ${groups.total} groups:`, groups.groups);
+```
+
+### 12. Get Group Quota
+
+```typescript
+import { GMFProductType, QuotaType } from 'redai-zalo-sdk';
+
+const quota = await groupManagement.getGroupQuota(
+  accessToken, 
+  GMFProductType.GMF10, 
+  QuotaType.SUB_QUOTA
+);
+console.log('Group quota:', quota);
+```
+
+## Error Handling
+
+```typescript
+try {
+  const result = await groupManagement.createGroup(accessToken, groupData);
+  console.log('Success:', result);
+} catch (error) {
+  if (error instanceof ZaloSDKError) {
+    console.error('Zalo API Error:', error.message, error.code);
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { ZaloSDK, GMFProductType } from 'redai-zalo-sdk';
+
+class GroupManager {
+  private sdk: ZaloSDK;
+  
+  constructor() {
+    this.sdk = new ZaloSDK({
+      appId: process.env.ZALO_APP_ID!,
+      appSecret: process.env.ZALO_APP_SECRET!,
+    });
+  }
+
+  async createAndManageGroup(accessToken: string) {
+    try {
+      // 1. Get asset_id for group creation
+      const assetId = await this.sdk.groupManagement.getAssetId(accessToken);
+      
+      // 2. Create new group
+      const newGroup = await this.sdk.groupManagement.createGroup(accessToken, {
+        group_name: "Support Team",
+        description: "Customer support team",
+        asset_id: assetId,
+        member_uids: ["user1", "user2"]
+      });
+      
+      // 3. Invite more members
+      await this.sdk.groupManagement.inviteMembers(accessToken, newGroup.group_id, {
+        member_uids: ["user3", "user4"]
+      });
+      
+      // 4. Add admin
+      await this.sdk.groupManagement.addAdmins(accessToken, newGroup.group_id, {
+        admin_uids: ["user1"]
+      });
+      
+      // 5. Get group info
+      const groupInfo = await this.sdk.groupManagement.getGroupInfo(accessToken, newGroup.group_id);
+      
+      return groupInfo;
+    } catch (error) {
+      console.error('Group management error:', error);
+      throw error;
+    }
+  }
+}
+```
+
+## 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.