@warriorteam/redai-zalo-sdk 1.2.0 → 1.3.0

package/docs/API_REFERENCE.md

@@ -0,0 +1,680 @@
+# RedAI Zalo SDK - API Reference
+
+## Tổng quan
+
+RedAI Zalo SDK cung cấp các API hoàn chỉnh để tích hợp với các dịch vụ của Zalo, bao gồm Official Account, ZNS, Social API, và nhiều dịch vụ khác.
+
+## Cấu trúc SDK
+
+```typescript
+import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
+
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret",
+  debug: true
+});
+```
+
+---
+
+## ZaloSDK Class
+
+### Constructor
+
+```typescript
+constructor(config: ZaloSDKConfig)
+```
+
+#### ZaloSDKConfig
+
+```typescript
+interface ZaloSDKConfig {
+  appId: string;                    // App ID từ Zalo Developer
+  appSecret: string;                // App Secret từ Zalo Developer
+  timeout?: number;                 // Timeout cho request (mặc định: 30000ms)
+  debug?: boolean;                  // Bật chế độ debug (mặc định: false)
+  apiBaseUrl?: string;              // Base URL API (mặc định: https://openapi.zalo.me)
+  retry?: {
+    attempts?: number;              // Số lần retry (mặc định: 3)
+    delay?: number;                 // Delay giữa các retry (mặc định: 1000ms)
+  };
+}
+```
+
+### Quick Methods
+
+#### getOAAccessToken()
+```typescript
+async getOAAccessToken(code: string, redirectUri: string): Promise<AccessToken>
+```
+Lấy access token cho Official Account từ authorization code.
+
+#### getSocialAccessToken()
+```typescript
+async getSocialAccessToken(code: string, redirectUri: string, codeVerifier?: string): Promise<AccessToken>
+```
+Lấy access token cho Social API từ authorization code.
+
+#### refreshOAAccessToken()
+```typescript
+async refreshOAAccessToken(refreshToken: string): Promise<AccessToken>
+```
+Refresh access token cho Official Account.
+
+#### refreshSocialAccessToken()
+```typescript
+async refreshSocialAccessToken(refreshToken: string): Promise<AccessToken>
+```
+Refresh access token cho Social API.
+
+---
+
+## AuthService
+
+Xử lý authentication flows và quản lý token.
+
+### Methods
+
+#### createOAAuthUrl()
+```typescript
+createOAAuthUrl(redirectUri: string, state?: string): string
+```
+Tạo URL authorization cho Official Account.
+
+#### createSocialAuthUrl()
+```typescript
+createSocialAuthUrl(redirectUri: string, state?: string): string
+```
+Tạo URL authorization cho Social API.
+
+#### getOAAccessToken()
+```typescript
+async getOAAccessToken(params: AuthCodeParams): Promise<AccessToken>
+```
+
+#### getSocialAccessToken()
+```typescript
+async getSocialAccessToken(params: AuthCodeParams): Promise<AccessToken>
+```
+
+#### getSocialUserInfo()
+```typescript
+async getSocialUserInfo(accessToken: string, fields?: string): Promise<SocialUserInfo>
+```
+
+#### generatePKCE()
+```typescript
+generatePKCE(): PKCEConfig
+```
+Tạo PKCE cho Social API authorization.
+
+#### validateAccessToken()
+```typescript
+async validateAccessToken(accessToken: string): Promise<TokenValidation>
+```
+
+---
+
+## OAService
+
+Quản lý Official Account information và quota.
+
+### Methods
+
+#### getOAInfo()
+```typescript
+async getOAInfo(accessToken: string): Promise<OAInfo>
+```
+Lấy thông tin Official Account.
+
+**Response:**
+```typescript
+interface OAInfo {
+  oa_id: string;
+  name: string;
+  description: string;
+  oa_alias: string;
+  is_verified: boolean;
+  oa_type: number;
+  package_name: string;
+  package_valid_through_date: string;
+  package_auto_renew_date: string;
+  linked_zca: string;
+  num_follower: number;
+  avatar: string;
+  cover: string;
+}
+```
+
+#### getMessageQuota()
+```typescript
+async getMessageQuota(accessToken: string): Promise<MessageQuota>
+```
+Lấy thông tin quota tin nhắn.
+
+#### getQuotaSummary()
+```typescript
+async getQuotaSummary(accessToken: string): Promise<QuotaSummary>
+```
+Lấy tổng quan quota chi tiết.
+
+#### validateOAToken()
+```typescript
+async validateOAToken(accessToken: string): Promise<boolean>
+```
+
+---
+
+## ConsultationService
+
+Gửi tin nhắn customer support trong vòng 48 giờ.
+
+### Methods
+
+#### sendTextMessage()
+```typescript
+async sendTextMessage(
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: ConsultationTextMessage
+): Promise<SendMessageResponse>
+```
+
+**Ví dụ:**
+```typescript
+await zalo.consultation.sendTextMessage(accessToken, 
+  { user_id: "user-id" },
+  { type: "text", text: "Xin chào! Tôi có thể hỗ trợ gì cho bạn?" }
+);
+```
+
+#### sendImageMessage()
+```typescript
+async sendImageMessage(
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: ConsultationImageMessage
+): Promise<SendMessageResponse>
+```
+
+#### sendFileMessage()
+```typescript
+async sendFileMessage(
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: ConsultationFileMessage
+): Promise<SendMessageResponse>
+```
+
+#### sendStickerMessage()
+```typescript
+async sendStickerMessage(
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: ConsultationStickerMessage
+): Promise<SendMessageResponse>
+```
+
+#### sendQuoteMessage()
+```typescript
+async sendQuoteMessage(
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: ConsultationQuoteMessage
+): Promise<SendMessageResponse>
+```
+
+#### sendRequestInfoMessage()
+```typescript
+async sendRequestInfoMessage(
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: ConsultationRequestInfoMessage
+): Promise<SendMessageResponse>
+```
+
+---
+
+## ZNSService
+
+Zalo Notification Service - gửi tin nhắn thông báo qua template.
+
+### Methods
+
+#### sendMessage()
+```typescript
+async sendMessage(
+  accessToken: string,
+  request: ZNSMessageRequest
+): Promise<ZNSMessageResponse>
+```
+
+**ZNSMessageRequest:**
+```typescript
+interface ZNSMessageRequest {
+  phone: string;                    // Số điện thoại người nhận
+  template_id: string;             // ID template được duyệt
+  template_data: Record<string, any>; // Data để fill vào template
+  tracking_id?: string;            // ID để tracking (tùy chọn)
+  mode?: 'development' | 'production'; // Môi trường (mặc định: production)
+}
+```
+
+#### getQuotaInfo()
+```typescript
+async getQuotaInfo(accessToken: string): Promise<ZNSQuotaInfo>
+```
+
+#### getTemplateList()
+```typescript
+async getTemplateList(accessToken: string, params?: ZNSTemplateListParams): Promise<ZNSTemplateListResponse>
+```
+
+#### createTemplate()
+```typescript
+async createTemplate(accessToken: string, template: ZNSTemplateCreate): Promise<ZNSTemplateCreateResponse>
+```
+
+#### updateTemplate()
+```typescript
+async updateTemplate(accessToken: string, templateId: string, template: ZNSTemplateUpdate): Promise<ZNSTemplateUpdateResponse>
+```
+
+#### getTemplateStatus()
+```typescript
+async getTemplateStatus(accessToken: string, templateId: string): Promise<ZNSTemplateStatus>
+```
+
+---
+
+## UserService
+
+Quản lý thông tin người dùng Social API.
+
+### Methods
+
+#### getUserInfo()
+```typescript
+async getUserInfo(accessToken: string, userId: string): Promise<UserInfo>
+```
+
+#### getUserList()
+```typescript
+async getUserList(accessToken: string, request: UserListRequest): Promise<UserListResponse>
+```
+
+#### getFollowers()
+```typescript
+async getFollowers(accessToken: string, params?: FollowersParams): Promise<FollowersResponse>
+```
+
+---
+
+## UserManagementService
+
+Quản lý user profiles và interactions.
+
+### Methods
+
+#### getUserProfile()
+```typescript
+async getUserProfile(accessToken: string, userId: string): Promise<UserManagementProfile>
+```
+
+#### updateUserProfile()
+```typescript
+async updateUserProfile(accessToken: string, userId: string, profile: UserProfileUpdate): Promise<UserManagementProfile>
+```
+
+#### getUserInteractions()
+```typescript
+async getUserInteractions(accessToken: string, userId: string, params?: InteractionParams): Promise<UserInteraction[]>
+```
+
+#### getUserAnalytics()
+```typescript
+async getUserAnalytics(accessToken: string, userId: string): Promise<UserAnalytics>
+```
+
+#### searchUsers()
+```typescript
+async searchUsers(accessToken: string, search: UserSearch): Promise<UserSearchResult>
+```
+
+#### bulkUserOperation()
+```typescript
+async bulkUserOperation(accessToken: string, operation: BulkUserOperation): Promise<BulkOperationResult>
+```
+
+---
+
+## TagService
+
+Quản lý user tags và segmentation.
+
+### Methods
+
+#### createTag()
+```typescript
+async createTag(accessToken: string, tagName: string): Promise<TagCreateResponse>
+```
+
+#### deleteTag()
+```typescript
+async deleteTag(accessToken: string, tagId: string): Promise<TagDeleteResponse>
+```
+
+#### tagUser()
+```typescript
+async tagUser(accessToken: string, userId: string, tags: string[]): Promise<TagUserResponse>
+```
+
+#### untagUser()
+```typescript
+async untagUser(accessToken: string, userId: string, tags: string[]): Promise<UntagUserResponse>
+```
+
+#### getUserTags()
+```typescript
+async getUserTags(accessToken: string, userId: string): Promise<UserTag[]>
+```
+
+#### getTagList()
+```typescript
+async getTagList(accessToken: string): Promise<UserTagList>
+```
+
+#### getUsersByTag()
+```typescript
+async getUsersByTag(accessToken: string, tagId: string, params?: TagUsersParams): Promise<TagUsersResponse>
+```
+
+---
+
+## GroupManagementService
+
+Quản lý groups và members.
+
+### Methods
+
+#### getGroupsOfOA()
+```typescript
+async getGroupsOfOA(accessToken: string, params?: GroupsParams): Promise<GroupsOfOAResponse>
+```
+
+#### getGroupDetail()
+```typescript
+async getGroupDetail(accessToken: string, groupId: string): Promise<GroupDetailResponse>
+```
+
+#### getGroupMembers()
+```typescript
+async getGroupMembers(accessToken: string, groupId: string, params?: GroupMembersParams): Promise<GroupMembersResponse>
+```
+
+#### getPendingMembers()
+```typescript
+async getPendingMembers(accessToken: string, groupId: string): Promise<GroupPendingMembersResponse>
+```
+
+#### acceptPendingMembers()
+```typescript
+async acceptPendingMembers(accessToken: string, request: GroupAcceptPendingMembersRequest): Promise<GroupAcceptPendingMembersResponse>
+```
+
+#### removeMembers()
+```typescript
+async removeMembers(accessToken: string, request: GroupRemoveMembersRequest): Promise<GroupRemoveMembersResponse>
+```
+
+---
+
+## GroupMessageService
+
+Gửi tin nhắn đến groups.
+
+### Methods
+
+#### sendTextMessage()
+```typescript
+async sendTextMessage(accessToken: string, groupId: string, message: GroupTextMessage): Promise<GroupMessageResult>
+```
+
+#### sendImageMessage()
+```typescript
+async sendImageMessage(accessToken: string, groupId: string, message: GroupImageMessage): Promise<GroupMessageResult>
+```
+
+#### sendFileMessage()
+```typescript
+async sendFileMessage(accessToken: string, groupId: string, message: GroupFileMessage): Promise<GroupMessageResult>
+```
+
+#### getQuotaMessage()
+```typescript
+async getQuotaMessage(accessToken: string, request: GroupQuotaMessageRequest): Promise<GroupQuotaMessageResponse>
+```
+
+---
+
+## ArticleService
+
+Quản lý articles và content.
+
+### Methods
+
+#### createArticle()
+```typescript
+async createArticle(accessToken: string, article: ArticleCreateRequest): Promise<ArticleCreateResponse>
+```
+
+#### updateArticle()
+```typescript
+async updateArticle(accessToken: string, articleId: string, article: ArticleUpdateRequest): Promise<ArticleUpdateResponse>
+```
+
+#### deleteArticle()
+```typescript
+async deleteArticle(accessToken: string, articleId: string): Promise<ArticleDeleteResponse>
+```
+
+#### getArticle()
+```typescript
+async getArticle(accessToken: string, articleId: string): Promise<Article>
+```
+
+#### getArticleList()
+```typescript
+async getArticleList(accessToken: string, params?: ArticleListParams): Promise<ArticleListResponse>
+```
+
+#### shareArticle()
+```typescript
+async shareArticle(accessToken: string, userId: string, articleId: string): Promise<ShareArticleResponse>
+```
+
+#### uploadImage()
+```typescript
+async uploadImage(accessToken: string, image: Buffer): Promise<ImageUploadResponse>
+```
+
+---
+
+## VideoUploadService
+
+Upload và quản lý video content.
+
+### Methods
+
+#### uploadVideo()
+```typescript
+async uploadVideo(accessToken: string, video: Buffer, filename: string): Promise<VideoUploadResponse>
+```
+
+#### getUploadStatus()
+```typescript
+async getUploadStatus(accessToken: string, token: string): Promise<VideoUploadStatus>
+```
+
+#### waitForUploadCompletion()
+```typescript
+async waitForUploadCompletion(accessToken: string, token: string, maxAttempts?: number): Promise<VideoUploadComplete>
+```
+
+#### sendVideoMessage()
+```typescript
+async sendVideoMessage(accessToken: string, userId: string, attachmentId: string, message?: string): Promise<SendMessageResponse>
+```
+
+---
+
+## TransactionService
+
+Gửi tin nhắn transaction (thanh toán, đơn hàng).
+
+### Methods
+
+#### sendTransactionMessage()
+```typescript
+async sendTransactionMessage(
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: TransactionMessage
+): Promise<SendMessageResponse>
+```
+
+---
+
+## PromotionService
+
+Gửi tin nhắn khuyến mại.
+
+### Methods
+
+#### sendPromotionMessage()
+```typescript
+async sendPromotionMessage(
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: PromotionMessage
+): Promise<SendMessageResponse>
+```
+
+---
+
+## GeneralMessageService
+
+Gửi tin nhắn general purpose.
+
+### Methods
+
+#### sendResponseMessage()
+```typescript
+async sendResponseMessage(
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: Message
+): Promise<SendMessageResponse>
+```
+
+#### sendAnonymousMessage()
+```typescript
+async sendAnonymousMessage(
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: AnonymousMessage
+): Promise<SendMessageResponse>
+```
+
+---
+
+## MessageManagementService
+
+Quản lý tin nhắn và analytics.
+
+### Methods
+
+#### getMessageHistory()
+```typescript
+async getMessageHistory(accessToken: string, params: MessageHistoryParams): Promise<MessageHistoryResponse>
+```
+
+#### getMessageAnalytics()
+```typescript
+async getMessageAnalytics(accessToken: string, params: MessageAnalyticsParams): Promise<MessageAnalytics>
+```
+
+#### getMessageStatus()
+```typescript
+async getMessageStatus(accessToken: string, messageId: string): Promise<MessageStatus>
+```
+
+---
+
+## Error Handling
+
+Tất cả methods có thể throw `ZaloSDKError`:
+
+```typescript
+class ZaloSDKError extends Error {
+  code: number;         // Mã lỗi từ Zalo API
+  details?: any;        // Chi tiết lỗi
+  statusCode?: number;  // HTTP status code
+}
+```
+
+### Common Error Codes
+
+| Code | Description | Giải pháp |
+|------|-------------|-----------|
+| -216 | Invalid access token | Refresh token hoặc re-authenticate |
+| -201 | Invalid parameters | Kiểm tra tham số đầu vào |
+| -223 | Quota exceeded | Chờ reset quota hoặc nâng cấp gói |
+| -204 | User not found | Kiểm tra user_id |
+| -207 | Template not found | Kiểm tra template_id |
+
+---
+
+## Rate Limiting
+
+- **OA Messages**: Theo quota package
+- **ZNS Messages**: Theo quota mua
+- **API Calls**: Không giới hạn cụ thể, nhưng nên có throttling
+
+---
+
+## Authentication Requirements
+
+| Service | Required Token Type | Scope |
+|---------|-------------------|--------|
+| AuthService | N/A | N/A |
+| OAService | OA Access Token | Official Account |
+| ConsultationService | OA Access Token | Official Account |
+| ZNSService | OA Access Token | Official Account |
+| UserService | Social Access Token | Social API |
+| GroupServices | OA Access Token | Official Account |
+| All Message Services | OA Access Token | Official Account |
+
+---
+
+## Best Practices
+
+1. **Token Management**: Luôn refresh token trước khi hết hạn
+2. **Error Handling**: Implement retry logic với exponential backoff
+3. **Rate Limiting**: Implement throttling để tránh hit limit
+4. **Logging**: Enable debug mode trong development
+5. **Security**: Không log access token hoặc sensitive data
+6. **Testing**: Sử dụng development mode cho ZNS khi test
+
+---
+
+## Migration Notes
+
+### From v1.1.x to v1.2.x
+- Added new message services (Consultation, Transaction, Promotion)
+- Deprecated MessageService, use specialized services instead
+- Added VideoUploadService
+- Enhanced error handling
+
+Xem [CHANGELOG.md](../CHANGELOG.md) để biết chi tiết về các thay đổi.