@warriorteam/zalo-personal

# Tài Liệu Tham Khảo Types - Zalo Personal SDK ## Mục lục - [Core Types](#core-types) - [Message Types](#message-types) - [Authentication Types](#authentication-types) - [User & Friend Types](#user--friend-types) - [Group Types](#group-types) - [Attachment Types](#attachment-types) - [Event Types](#event-types) - [Utility Types](#utility-types) - [API Response Types](#api-response-types) - [Enum Types](#enum-types) ## Core Types ### ThreadType Định nghĩa loại thread (cuộc trò chuyện) ```typescript enum ThreadType { User = 0, // Tin nhắn cá nhân Group = 1 // Tin nhắn nhóm } ``` ### DestType Định nghĩa loại đích đến ```typescript enum DestType { User = 3, // Người dùng Page = 5 // Trang } ``` ### Gender Định nghĩa giới tính ```typescript enum Gender { Male = 0, // Nam Female = 1 // Nữ } ``` ## Message Types ### MessageContent Nội dung tin nhắn chính ```typescript type MessageContent = { msg: string; // Nội dung văn bản styles?: Style[]; // Định dạng văn bản urgency?: Urgency; // Mức độ ưu tiên quote?: SendMessageQuote; // Tin nhắn được trả lời mentions?: Mention[]; // Mention người dùng attachments?: AttachmentSource | AttachmentSource[]; // File đính kèm ttl?: number; // Thời gian tự hủy (ms) } ``` ### Style Định dạng văn bản ```typescript type Style = | { start: number; // Vị trí bắt đầu len: number; // Độ dài st: Exclude<TextStyle, TextStyle.Indent>; // Kiểu định dạng } | { start: number; len: number; st: TextStyle.Indent; indentSize?: number; // Số lượng khoảng trắng thụt lề } ``` ### TextStyle Các kiểu định dạng văn bản ```typescript enum TextStyle { Bold = "b", // In đậm Italic = "i", // In nghiêng Underline = "u", // Gạch chân StrikeThrough = "s", // Gạch ngang Red = "c_db342e", // Màu đỏ Orange = "c_f27806", // Màu cam Yellow = "c_f7b503", // Màu vàng Green = "c_15a85f", // Màu xanh lá Small = "f_13", // Font nhỏ (13px) Big = "f_18", // Font lớn (18px) UnorderedList = "lst_1", // Danh sách không có thứ tự OrderedList = "lst_2", // Danh sách có thứ tự Indent = "ind_$" // Thụt lề } ``` ### Urgency Mức độ ưu tiên tin nhắn ```typescript enum Urgency { Default = 0, // Bình thường Important = 1, // Quan trọng Urgent = 2 // Khẩn cấp } ``` ### Mention Mention người dùng trong tin nhắn ```typescript type Mention = { pos: number; // Vị trí mention trong tin nhắn uid: string; // ID người được mention len: number; // Độ dài text mention } ``` ### SendMessageQuote Tin nhắn được trả lời/quote ```typescript type SendMessageQuote = { content: TMessage["content"]; // Nội dung tin nhắn gốc msgType: TMessage["msgType"]; // Loại tin nhắn propertyExt: TMessage["propertyExt"]; // Thuộc tính mở rộng uidFrom: TMessage["uidFrom"]; // ID người gửi msgId: TMessage["msgId"]; // ID tin nhắn cliMsgId: TMessage["cliMsgId"]; // Client message ID ts: TMessage["ts"]; // Timestamp ttl: TMessage["ttl"]; // Time to live } ``` ### SendMessageResult Kết quả gửi tin nhắn ```typescript type SendMessageResult = { msgId: number; // ID tin nhắn đã gửi } ``` ### SendMessageResponse Response khi gửi tin nhắn ```typescript type SendMessageResponse = { message: SendMessageResult | null; // Kết quả tin nhắn văn bản attachment: SendMessageResult[]; // Kết quả các file đính kèm } ``` ## Authentication Types ### Credentials Thông tin đăng nhập ```typescript type Credentials = { imei: string; // IMEI thiết bị cookie: Cookie[] | toughCookie.SerializedCookie[] | { url: string; cookies: Cookie[] }; userAgent: string; // User agent language?: string; // Ngôn ngữ (mặc định: 'vi') } ``` ### Cookie Cookie đăng nhập ```typescript type Cookie = { domain: string; // Domain cookie expirationDate: number; // Thời gian hết hạn hostOnly: boolean; // Chỉ áp dụng cho host httpOnly: boolean; // Chỉ HTTP name: string; // Tên cookie path: string; // Đường dẫn sameSite: string; // SameSite policy secure: boolean; // HTTPS only session: boolean; // Cookie session storeId: string; // Store ID value: string; // Giá trị cookie } ``` ### LoginQRCallback Callback cho đăng nhập QR ```typescript type LoginQRCallback = (event: LoginQRCallbackEvent) => void; type LoginQRCallbackEvent = { type: LoginQRCallbackEventType; data: any; actions: any; } enum LoginQRCallbackEventType { QrCodeGenerated = "qr_code_generated", LoggedIn = "logged_in", GotLoginInfo = "got_login_info" } ``` ## User & Friend Types ### ProfileInfo Thông tin profile người dùng ```typescript type ProfileInfo = { userId: string; // ID người dùng displayName: string; // Tên hiển thị avatar: string; // URL avatar cover: string; // URL ảnh bìa gender: Gender; // Giới tính // ... các thuộc tính khác } ``` ### UserInfoResponse Response thông tin người dùng ```typescript type UserInfoResponse = { data: ProfileInfo[]; // Danh sách thông tin người dùng error_code: number; // Mã lỗi error_message: string; // Thông báo lỗi } ``` ### GetAllFriendsResponse Response danh sách bạn bè ```typescript type GetAllFriendsResponse = { data: { friends: ProfileInfo[]; // Danh sách bạn bè }; error_code: number; error_message: string; } ``` ### FindUserResponse Response tìm kiếm người dùng ```typescript type FindUserResponse = { data: ProfileInfo[]; // Kết quả tìm kiếm error_code: number; error_message: string; } ``` ## Group Types ### GroupInfo Thông tin nhóm ```typescript type GroupInfo = { id: string; // ID nhóm name: string; // Tên nhóm avatar: string; // Avatar nhóm creatorId: string; // ID người tạo adminIds: string[]; // Danh sách admin memberIds: string[]; // Danh sách thành viên totalMember: number; // Tổng số thành viên // ... các thuộc tính khác } ``` ### GroupInfoResponse Response thông tin nhóm ```typescript type GroupInfoResponse = { data: GroupInfo; error_code: number; error_message: string; } ``` ### CreateGroupOptions Tùy chọn tạo nhóm ```typescript type CreateGroupOptions = { name: string; // Tên nhóm members: string[]; // Danh sách thành viên avatar?: string; // Avatar nhóm (optional) } ``` ### CreateGroupResponse Response tạo nhóm ```typescript type CreateGroupResponse = { data: { groupId: string; // ID nhóm vừa tạo }; error_code: number; error_message: string; } ``` ### GroupMemberProfile Thông tin thành viên nhóm ```typescript type GroupMemberProfile = { userId: string; // ID thành viên displayName: string; // Tên hiển thị avatar: string; // Avatar role: string; // Vai trò (admin, member, etc.) joinTime: number; // Thời gian tham gia } ``` ### GetGroupMembersInfoResponse Response thông tin thành viên nhóm ```typescript type GetGroupMembersInfoResponse = { data: GroupMemberProfile[]; error_code: number; error_message: string; } ``` ## Attachment Types ### AttachmentSource Nguồn file đính kèm ```typescript type AttachmentSource = | string // Đường dẫn file local | { url: string; // URL download file filename?: `${string}.${string}`; // Tên file tùy chỉnh headers?: Record<string, string>; // HTTP headers } | { data: Buffer; // Dữ liệu file dạng Buffer filename: `${string}.${string}`; // Tên file (bắt buộc) metadata: { totalSize: number; // Kích thước file width?: number; // Chiều rộng (cho ảnh/video) height?: number; // Chiều cao (cho ảnh/video) }; } ``` ### UploadAttachmentResponse Response upload file đính kèm ```typescript type UploadAttachmentResponse = UploadAttachmentType[]; type UploadAttachmentType = ImageData | FileData; ``` ### ImageData Dữ liệu ảnh đã upload ```typescript type ImageData = { fileType: "image"; photoId: string; // ID ảnh normalUrl: string; // URL ảnh bình thường hdUrl: string; // URL ảnh HD thumbUrl: string; // URL thumbnail width: number; // Chiều rộng height: number; // Chiều cao totalSize: number; // Kích thước file } ``` ### FileData Dữ liệu file đã upload ```typescript type FileData = { fileType: "video" | "others"; fileId: string; // ID file fileName: string; // Tên file fileUrl: string; // URL file totalSize: number; // Kích thước file checksum: string; // Checksum file clientFileId: string; // Client file ID } ``` ## Event Types ### Message Event Sự kiện tin nhắn mới ```typescript type MessageEvent = { threadId: string; // ID cuộc trò chuyện threadType: ThreadType; // Loại cuộc trò chuyện messageId: string; // ID tin nhắn senderId: string; // ID người gửi content: string; // Nội dung tin nhắn timestamp: number; // Thời gian gửi attachments?: any[]; // File đính kèm mentions?: Mention[]; // Mentions quote?: any; // Tin nhắn được trả lời } ``` ### FriendEvent Sự kiện bạn bè ```typescript type FriendEvent = { type: string; // Loại sự kiện fromId: string; // ID người gửi toId: string; // ID người nhận timestamp: number; // Thời gian data: any; // Dữ liệu sự kiện } ``` ### GroupEvent Sự kiện nhóm ```typescript type GroupEvent = { type: string; // Loại sự kiện groupId: string; // ID nhóm actorId: string; // ID người thực hiện targetId?: string; // ID đối tượng (nếu có) timestamp: number; // Thời gian data: any; // Dữ liệu sự kiện } ``` ## Utility Types ### ZaloApiError Lớp lỗi API Zalo ```typescript class ZaloApiError extends Error { constructor(message: string); } ``` ### CloseReason Lý do đóng kết nối listener ```typescript enum CloseReason { Normal = "normal", Error = "error", Reconnect = "reconnect" } ``` ## API Response Types ### Mẫu Response chung ```typescript type BaseResponse<T = any> = { data: T; // Dữ liệu response error_code: number; // Mã lỗi (0 = thành công) error_message: string; // Thông báo lỗi } ``` ### Một số Response Types phổ biến #### AcceptFriendRequestResponse ```typescript type AcceptFriendRequestResponse = BaseResponse<{ success: boolean; }> ``` #### SendStickerResponse ```typescript type SendStickerResponse = BaseResponse<{ msgId: number; }> ``` #### CreatePollResponse ```typescript type CreatePollResponse = BaseResponse<{ pollId: string; boardId: string; }> ``` #### GetStickersResponse ```typescript type GetStickersResponse = BaseResponse<{ categories: StickerCategory[]; }> type StickerCategory = { id: string; name: string; stickers: Sticker[]; } type Sticker = { id: string; url: string; type: string; } ``` ## Enum Types ### BoardType Loại bảng tin nhóm ```typescript enum BoardType { Note = 1, // Ghi chú PinnedMessage = 2, // Tin nhắn ghim Poll = 3 // Bình chọn } ``` ### ReminderRepeatMode Chế độ lặp lại reminder ```typescript enum ReminderRepeatMode { None = 0, // Không lặp Daily = 1, // Hàng ngày Weekly = 2, // Hàng tuần Monthly = 3 // Hàng tháng } ``` ### MuteAction Hành động tắt thông báo ```typescript enum MuteAction { Mute = 1, // Tắt thông báo Unmute = 2 // Bật thông báo } ``` ### MuteDuration Thời gian tắt thông báo ```typescript enum MuteDuration { OneHour = 3600, // 1 giờ EightHours = 28800, // 8 giờ OneDay = 86400, // 1 ngày Forever = -1 // Vĩnh viễn } ``` ### ReportReason Lý do báo cáo ```typescript enum ReportReason { Spam = 1, // Spam Violence = 2, // Bạo lực Harassment = 3, // Quấy rối Inappropriate = 4 // Không phù hợp } ``` ### ChatTTL Thời gian tự hủy chat ```typescript enum ChatTTL { Off = 0, // Tắt OneDay = 86400, // 1 ngày ThreeDays = 259200, // 3 ngày OneWeek = 604800 // 1 tuần } ``` ### UpdateLangAvailableLanguages Ngôn ngữ có sẵn ```typescript enum UpdateLangAvailableLanguages { Vietnamese = "vi", English = "en" } ``` ## Ghi Chú Quan Trọng 1. **Type Safety**: Tất cả types đều được định nghĩa chặt chẽ để đảm bảo type safety 2. **Optional Properties**: Thuộc tính có dấu `?` là optional 3. **Union Types**: Sử dụng `|` để định nghĩa multiple types 4. **Generic Types**: Một số types sử dụng generic `<T>` để tái sử dụng 5. **Enum vs String Literal**: Enum được sử dụng cho values cố định, string literal cho flexibility ## Ví Dụ Sử Dụng Types ```typescript import { MessageContent, ThreadType, TextStyle, Urgency, AttachmentSource } from 'zalo-personal-sdk'; // Tin nhắn với định dạng const messageContent: MessageContent = { msg: 'Hello World!', styles: [ { start: 0, len: 5, st: TextStyle.Bold } ], urgency: Urgency.Important, attachments: '/path/to/image.jpg' as AttachmentSource }; // Gửi tin nhắn await api.sendMessage(messageContent, 'user-id', ThreadType.User); ``` Tài liệu này cung cấp tham khảo đầy đủ về tất cả types trong Zalo Personal SDK. Sử dụng TypeScript sẽ giúp bạn có code completion và type checking tốt hơn.