@warriorteam/redai-zalo-sdk 1.4.1 → 1.5.0

package/docs/GROUP_MANAGEMENT.md

@@ -1,232 +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",
-  group_description: "Customer support group",
-  asset_id: "your_asset_id", // Get from getAssetId()
-  member_user_ids: ["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.
+# 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",
+  group_description: "Customer support group",
+  asset_id: "your_asset_id", // Get from getAssetId()
+  member_user_ids: ["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.