@warriorteam/redai-zalo-sdk/ZNS-TYPE-IMPROVEMENTS.md

Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account v3.0, ZNS with Full Type Safety, Consultation Service, Broadcast Service, Group Messaging with List APIs, Social APIs, Enhanced Article Management, Promotion Service v3.0 with Multip

# ZNS Service Type Improvements

## Tổng quan

Đã cập nhật ZNS Service để sử dụng các type cụ thể thay vì `any` type, cải thiện type safety và developer experience.

## Những thay đổi chính

### 1. Thêm các interface validation components mới trong `src/types/zns.ts`

```typescript
// Attachment object cho LOGO và IMAGES
export interface ZNSAttachment {
  type: "IMAGE";
  media_id: string;
}

// TITLE component
export interface ZNSTitleComponent {
  value: string; // 9-65 ký tự, tối đa 4 params
}

// PARAGRAPH component  
export interface ZNSParagraphComponent {
  value: string; // 9-400 ký tự, tối đa 10 params
}

// OTP component
export interface ZNSOTPComponent {
  value: string; // 1-10 ký tự
}

// TABLE component
export interface ZNSTableComponent {
  rows: ZNSTableRow[]; // 2-8 rows
}

export interface ZNSTableRow {
  title: string; // 3-36 ký tự, chỉ text cố định
  value: string; // 3-90 ký tự, có thể có params
  row_type?: 0 | 1 | 2 | 3 | 4 | 5; // Hiệu ứng row
}

// LOGO component
export interface ZNSLogoComponent {
  light: ZNSAttachment;
  dark: ZNSAttachment;
}

// IMAGES component
export interface ZNSImagesComponent {
  items: ZNSAttachment[]; // 1-3 attachments
}

// BUTTONS component
export interface ZNSButtonsComponent {
  items: ZNSButtonItem[]; // 1-2 buttons
}

export interface ZNSButtonItem {
  type: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9; // Button types
  title: string; // 5-30 ký tự, chỉ text cố định
  content: string; // URL/phone, có thể có params
}

// PAYMENT component
export interface ZNSPaymentComponent {
  bank_code: string; // Bank code cố định
  account_name: string; // 1-100 ký tự, text cố định
  bank_account: string; // 1-100 ký tự, text cố định
  amount: string | number; // Số tiền hoặc param
  note?: string; // 1-90 ký tự, có thể có params
}

// VOUCHER component
export interface ZNSVoucherComponent {
  name: string; // 1-30 ký tự, có thể có params
  condition: string; // 1-40 ký tự, có thể có params
  start_date?: string; // Có thể có params
  end_date: string; // Có thể có params
  voucher_code: string; // 1-25 ký tự, có thể có params
  display_code?: 1 | 2 | 3; // QR code, Bar code, Text only
}

// RATING component
export interface ZNSRatingComponent {
  items: ZNSRatingItem[]; // Đúng 5 items
}

export interface ZNSRatingItem {
  star: 1 | 2 | 3 | 4 | 5; // Số sao
  title: string; // 1-50 ký tự
  question?: string; // 1-100 ký tự
  answers?: string[]; // 1-5 câu trả lời, mỗi câu 1-50 ký tự
  thanks: string; // 1-100 ký tự
  description: string; // 1-200 ký tự
}

// Union type cho tất cả các component
export type ZNSValidationComponent = 
  | { TITLE: ZNSTitleComponent }
  | { PARAGRAPH: ZNSParagraphComponent }
  | { OTP: ZNSOTPComponent }
  | { TABLE: ZNSTableComponent }
  | { LOGO: ZNSLogoComponent }
  | { IMAGES: ZNSImagesComponent }
  | { BUTTONS: ZNSButtonsComponent }
  | { PAYMENT: ZNSPaymentComponent }
  | { VOUCHER: ZNSVoucherComponent }
  | { RATING: ZNSRatingComponent };
```

### 2. Cập nhật ZNS Service validation functions

Tất cả các function validation trong `src/services/zns.service.ts` đã được cập nhật để sử dụng type cụ thể:

- `validateLayoutStructure()`: Sử dụng `ZNSValidationComponent[]` thay vì `any[]`
- `isHeaderComponent()`, `isBodyComponent()`, `isFooterComponent()`: Sử dụng `ZNSValidationComponent`
- `validateComponent()`: Sử dụng `ZNSValidationComponent`
- `validateTitleComponent()`: Sử dụng `ZNSTitleComponent`
- `validateParagraphComponent()`: Sử dụng `ZNSParagraphComponent`
- `validateOTPComponent()`: Sử dụng `ZNSOTPComponent`
- `validateTableComponent()`: Sử dụng `ZNSTableComponent`
- `validateLogoComponent()`: Sử dụng `ZNSLogoComponent`
- `validateImagesComponent()`: Sử dụng `ZNSImagesComponent`
- `validateButtonsComponent()`: Sử dụng `ZNSButtonsComponent`
- `validatePaymentComponent()`: Sử dụng `ZNSPaymentComponent`
- `validateVoucherComponent()`: Sử dụng `ZNSVoucherComponent`
- `validateRatingComponent()`: Sử dụng `ZNSRatingComponent`
- `validateAttachment()`: Sử dụng `ZNSAttachment`

### 3. Lợi ích của việc cập nhật

#### Type Safety
- Loại bỏ hoàn toàn việc sử dụng `any` type
- IDE có thể detect lỗi type ngay khi code
- Autocomplete tốt hơn khi viết code

#### Developer Experience
- IntelliSense hiển thị đúng các property có sẵn
- Validation tự động khi compile TypeScript
- Dễ dàng refactor code mà không lo lỗi runtime

#### Maintainability
- Code dễ đọc và hiểu hơn
- Ít bug hơn do type checking
- Dễ dàng thêm feature mới

### 4. Ví dụ sử dụng

Xem file `examples/zns-validation-example.ts` để biết cách sử dụng các type mới.

#### Trước khi cập nhật:
```typescript
// Không có type safety
private validateTitleComponent(title: any): void {
  if (!title.value || typeof title.value !== 'string') {
    // Có thể có lỗi runtime nếu title không đúng cấu trúc
  }
}
```

#### Sau khi cập nhật:
```typescript
// Type safety đầy đủ
private validateTitleComponent(title: ZNSTitleComponent): void {
  if (!title.value || typeof title.value !== 'string') {
    // IDE sẽ báo lỗi ngay nếu title không đúng type
  }
}
```

### 5. Cách sử dụng trong dự án

```typescript
import { 
  ZNSValidationComponent,
  ZNSTitleComponent,
  ZNSButtonsComponent 
} from "./src/types/zns";

// Tạo component với type safety
const titleComponent: ZNSValidationComponent = {
  TITLE: {
    value: "Xin chào {{customer_name}}!"
  }
};

const buttonsComponent: ZNSValidationComponent = {
  BUTTONS: {
    items: [
      {
        type: 1, // URL
        title: "Xem chi tiết",
        content: "https://example.com"
      }
    ]
  }
};
```

### 6. Migration Guide

Nếu bạn đang sử dụng code cũ với `any` type:

1. Import các type mới từ `src/types/zns`
2. Thay thế `any` bằng type cụ thể tương ứng
3. TypeScript compiler sẽ báo lỗi nếu có vấn đề về type
4. Fix các lỗi type để đảm bảo code chạy đúng

### 7. Kết luận

Việc cập nhật này giúp:
- ✅ Loại bỏ hoàn toàn `any` type
- ✅ Cải thiện type safety
- ✅ Tăng developer experience
- ✅ Giảm bugs và lỗi runtime
- ✅ Code dễ maintain hơn

Tất cả validation functions trong ZNS Service giờ đây đều có type safety đầy đủ và tuân thủ đúng chuẩn TypeScript best practices.