# 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.