@warriorteam/redai-zalo-sdk/CHANGELOG.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

# Changelog

All notable changes to this project will be documented in this file.

## [1.32.11] - 2025-10-14

### ✨ Added - POST Method Support for User Info API

#### 🎯 New User Service Method
- **`postUserInfo()`** - New method to get user details using POST request instead of GET
- **Enhanced API compatibility** - Supports latest Zalo API requirements with JSON body format
- **Consistent request format** - Uses `user_id` in request body according to Zalo's updated specification

#### 🔧 Improvements
- **Updated `getAllUsersWithInfo()`** - Now uses `postUserInfo()` instead of `getUserInfo()` for better API compatibility
- **Better error handling** - Proper error messages for POST request failures
- **Full type safety** - Maintains TypeScript support with proper return types

#### 📝 Technical Details
- **UserService.postUserInfo()** method uses POST with JSON body `{ user_id: userId }`
- **Endpoint**: `https://openapi.zalo.me/v3.0/oa/user/detail` with POST method
- **Backward compatible** - Original `getUserInfo()` method still available

#### 🎯 Impact
- Improved compatibility with Zalo's latest API version
- Better reliability when fetching user information
- Seamless integration with existing code using `getAllUsersWithInfo()`

## [1.32.9] - 2025-09-19

### 🐛 Fixed - OAuth Response Format Handling

#### 🔧 Critical Bug Fix
- **Fixed OAuth response format mismatch** - Updated `getOAAccessToken()` method to handle both wrapped and direct response formats
- **Resolved "Failed to get OA access token" error** - Now correctly processes Zalo OAuth API responses that return tokens directly
- **Enhanced response parsing** - Added logic to handle both `result.data` (wrapped) and `result.access_token` (direct) formats
- **Consistent with Social API** - Applied same response handling logic as `getSocialAccessToken()` method

#### 📝 Technical Details
- **AuthService.getOAAccessToken()** method now handles multiple response formats:
  - **Wrapped format**: `{ error: 0, data: { access_token, refresh_token, expires_in } }`
  - **Direct format**: `{ access_token, refresh_token, expires_in }`
- **Type safety maintained** - Ensures `expires_in` is properly converted to number when needed
- **Backward compatible** - No breaking changes to method signatures or response types

#### 🎯 Impact
- **Resolves OAuth token exchange failures** when Zalo API returns direct response format
- **Improves SDK reliability** by handling API response variations
- **Ensures consistent behavior** across different OAuth endpoints

## [1.32.8] - 2025-09-17

### 🐛 Fixed - OA Access Token API URL

#### 🔧 Critical Bug Fix
- **Fixed incorrect OA access token API URL** - Updated from `https://openapi.zalo.me/v2.0/oa/oauth/access_token` to correct `https://oauth.zaloapp.com/v4/oa/access_token`
- **Updated API call format** - Now correctly uses `secret_key` in header instead of `app_secret` in body according to official documentation
- **Simplified request logic** - Removed redundant API calls and streamlined form data creation
- **Enhanced compliance** - Full alignment with Zalo's official OAuth v4.0 API specification

#### 📝 Technical Details
- **AuthService.getOAAccessToken()** method now follows exact API documentation format
- **Header authentication** with `secret_key` instead of body parameter
- **Maintained PKCE support** - `code_verifier` parameter still properly handled when provided
- **Backward compatible** - No breaking changes to method signatures or response types

#### 🎯 Impact
- **Resolves authentication failures** when obtaining OA access tokens
- **Improves API reliability** by using correct endpoints
- **Ensures future compatibility** with Zalo's OAuth v4.0 specification

## [1.32.4] - 2025-09-15

### ✨ Added - Custom Message Sequences for Multiple Users

#### 🎯 New Personalized Messaging API
- **`sendCustomMessageSequenceToMultipleUsers()`** - Send personalized message sequences to multiple users
- **Each user can receive completely different message sequences** instead of same messages for all users
- **Full support for all message types**: text, image, gif, file, sticker, request_user_info
- **Progress tracking with callbacks** for monitoring delivery status per user
- **Comprehensive error handling** with detailed per-user results

#### 📦 New Types Added
- **`UserCustomMessage`** - Interface for per-user custom message sequences
- **`SendCustomMessageSequenceToMultipleUsersRequest`** - Request type for custom messaging
- **`SendCustomMessageSequenceToMultipleUsersResponse`** - Response type with detailed results

#### 🚀 Usage Example
```typescript
import { ZaloSDK } from '@warriorteam/redai-zalo-sdk';

const zalo = new ZaloSDK({ appId: 'your_app_id', appSecret: 'your_secret' });

const result = await zalo.consultation.sendCustomMessageSequenceToMultipleUsers({
  accessToken: 'your_token',
  userCustomMessages: [
    {
      userId: 'user1',
      messages: [
        { type: 'text', text: 'Personalized message for user1' },
        { type: 'image', imageUrl: 'custom_image_for_user1.jpg' }
      ]
    },
    {
      userId: 'user2',
      messages: [
        { type: 'text', text: 'Different message for user2' },
        { type: 'sticker', stickerAttachmentId: 'sticker_id' }
      ]
    }
  ],
  defaultDelay: 1000,
  delayBetweenUsers: 2000,
  onProgress: (progress) => console.log(`${progress.userId}: ${progress.status}`)
});
```

#### 🎯 Perfect For
- **Personalized marketing campaigns** with user-specific content
- **VIP customer communications** with tailored messaging
- **Segmented notifications** based on user preferences
- **A/B testing** with different message variations per user

#### 📝 Documentation
- Added comprehensive example in `examples/consultation-custom-messages.js`
- Detailed JSDoc comments with usage patterns
- Type-safe implementation with full TypeScript support

## [1.32.0] - 2025-01-06

### ✨ Added - Complete Social API Types Export

#### 🔧 Fixed Export Issues
- **Fixed missing Social API types export** - All social types now properly exported from main package
- **Added selective export for social types** - Resolved naming conflicts with auth types
- **Improved TypeScript support** - Better IntelliSense and type safety for Social API

#### 📦 New Exported Social Types
- **`SocialProfile`** - Extended user profile with cover, about, location, education, work
- **`SocialFriend`** - Friend information with mutual friends data
- **`SocialFriendsList`** - Paginated friends list with cursors
- **`SocialPost`** - Social posts with likes, comments, shares
- **`SocialFeed`** - Timeline feed with pagination
- **`SocialMessage`** - Social messages with attachments
- **`SocialConversation`** - Conversation metadata and participants
- **`SocialAlbum`** - Photo albums with privacy settings
- **`SocialPhoto`** - Photos with tags, likes, comments
- **`SocialVideo`** - Video content with formats and privacy
- **`SocialEvent`** - Events with venue, attendance, privacy
- **`SocialGroup`** - Group information with members and settings
- **`OAuthConfig`** - OAuth configuration for Social API
- **`AuthorizationRequest`** - Authorization request parameters
- **`TokenRequest`** - Token exchange request
- **`RefreshTokenRequest`** - Token refresh request
- **`SocialApiError`** - Social API error responses
- **`CursorPagination`** - Cursor-based pagination
- **`OffsetPagination`** - Offset-based pagination

#### 🚀 Usage Improvements
**Before (v1.31.0):**
```typescript
// Had to import from dist path
import { SendMessageSequenceToMultipleUsersRequest } from '@warriorteam/redai-zalo-sdk/dist/services/consultation.service';
```

**Now (v1.32.0):**
```typescript
// Clean import from main package
import {
  SendMessageSequenceToMultipleUsersRequest,
  SocialProfile,
  SocialPost,
  OAuthConfig
} from '@warriorteam/redai-zalo-sdk';
```

#### 🔍 Export Status Summary
- ✅ All 15 type files now properly exported
- ✅ 20+ new Social API types available
- ✅ Zero naming conflicts resolved
- ✅ Full TypeScript IntelliSense support

## [1.31.0] - 2025-01-05

### ✨ Added - Complete Purchase API Support

#### 🛒 New Purchase Service
- **`PurchaseService`** - Complete service for Zalo OA Purchase API v3.0
- Full support for creating and confirming orders for OA products and services
- Type-safe order management with comprehensive validation

#### 🎯 Core Purchase Functions
- **`createOrder()`** - Create orders with product_id or redeem_code
- **`confirmOrder()`** - Confirm order payment with OTT (One Time Token)
- **`createOrderWithProduct()`** - Create order with specific product ID
- **`createOrderWithRedeemCode()`** - Create order with gift/redeem code
- **`confirmOrderById()`** - Confirm order with separate order ID and token

#### 🏷️ Specialized Product APIs
- **`createOASubscriptionOrder()`** - Create OA subscription orders (Advanced/Premium 6m/12m)
- **`createGMFOrder()`** - Create Group Message Framework orders (10/50/100/1000 members)
- **`createTransactionQuotaOrder()`** - Create transaction message quota orders (5k/50k/500k)

#### 📦 Batch & Combo Operations
- **`createMultipleOrders()`** - Create multiple orders in batch with error isolation
- **`createOAPremiumGMFCombo()`** - Create Premium + GMF combo packages
- **`recommendProducts()`** - Smart product recommendation system

#### 🗂️ Product Management
- **`getProductInfo()`** - Get detailed product information by ID
- **`getAllProducts()`** - Get all available products
- **`getProductsByCategory()`** - Filter products by category (subscription/gmf/quota)
- **`getProductsByBeneficiary()`** - Filter products by beneficiary (OA/APP)
- **`isProductCompatibleWithBeneficiary()`** - Validate product compatibility

#### 🕐 Order Timing & Validation
- **`isOrderCreationTimeValid()`** - Check if current time allows order creation (00:01-23:54)
- **`calculateOTTExpiration()`** - Calculate OTT expiration time (5 minutes)
- **`isOTTValid()`** - Check if OTT is still valid

#### 📋 TypeScript Interfaces & Types
- **`CreateOrderRequest`** - Union type for product_id or redeem_code orders
- **`CreateOrderWithProductRequest`** - Interface for product-based orders
- **`CreateOrderWithRedeemRequest`** - Interface for redeem code orders
- **`ConfirmOrderRequest`** - Interface for order confirmation
- **`OrderData`** - Complete order data with verified_token (OTT)
- **`ConfirmedOrderData`** - Confirmed order data (without OTT)
- **`ProductInfo`** - Product information interface
- **`BeneficiaryType`** - Type for OA/APP beneficiaries

#### 🏪 Complete Product Catalog
- **OA Subscription Products**:
  - OA Advanced 6/12 months
  - OA Premium 6/12 months
- **GMF Products**:
  - GMF 10/50/100/1000 members
- **Transaction Quota Products**:
  - 5k/50k/500k transaction messages (1 month)

#### ✅ Advanced Features
- **Automatic Validation**: Product-beneficiary compatibility checking
- **Error Isolation**: Batch operations continue on individual failures
- **Smart Recommendations**: AI-powered product suggestions based on requirements
- **Time Validation**: Automatic order creation time window checking
- **OTT Management**: Complete One Time Token lifecycle management
- **Type Safety**: Full TypeScript support with compile-time validation

#### 🔧 Error Handling & Validation
- Comprehensive error codes for all purchase scenarios
- Detailed validation for all request parameters
- Graceful error handling in batch operations
- Clear error messages with context information

## [1.30.0] - 2025-01-05

### ✨ Added - Template Message Support for ConsultationService

#### 🎯 New Core Function
- **`sendTemplateMessage()`** - Comprehensive template message function with full elements and buttons support
- Support for all Zalo OA template types with complete API specification compliance
- Type-safe template creation with comprehensive validation

#### 🛠️ Helper Functions (12 new functions)
- **Template Elements**: `createTemplateElement()` - Create template elements with validation
- **Template Buttons**:
  - `createUrlButton()` - Create URL buttons (oa.open.url)
  - `createQueryShowButton()` - Create query show buttons (oa.query.show)
  - `createQueryHideButton()` - Create query hide buttons (oa.query.hide)
  - `createSmsButton()` - Create SMS buttons (oa.open.sms)
  - `createPhoneButton()` - Create phone call buttons (oa.open.phone)
- **Template Actions**:
  - `createUrlAction()` - Create URL actions for elements
  - `createQueryShowAction()` - Create query show actions
  - `createQueryHideAction()` - Create query hide actions
  - `createSmsAction()` - Create SMS actions
  - `createPhoneAction()` - Create phone call actions

#### 📋 TypeScript Interfaces
- **`TemplateElement`** - Interface for template elements with validation rules
- **`TemplateButton`** - Interface for template buttons with type-specific payloads
- **`TemplateAction`** - Interface for template actions (default_action in elements)
- **`ConsultationTemplatePayload`** - Union type for all payload types
- **`UrlPayload`**, **`SmsPayload`**, **`PhonePayload`** - Specific payload interfaces

#### ✅ API Specification Compliance
- **Elements**: Maximum 5 elements, first element must have subtitle
- **Buttons**: Maximum 5 buttons with comprehensive validation
- **Title**: ≤ 100 characters validation
- **Subtitle**: ≤ 500 characters validation (required for first element)
- **Payload**: ≤ 1000 characters for string payloads
- **SMS Content**: ≤ 160 characters validation
- **Action Types**: Full support for all Zalo OA action types

#### 🔧 Validation & Error Handling
- Comprehensive input validation before API calls
- Detailed error messages with context information
- Type-safe development experience with TypeScript
- Runtime validation for all API specification rules

#### 📁 New Files
- `src/types/consultation.ts` - Complete TypeScript interfaces for consultation service
- `examples/consultation-template-example.ts` - Comprehensive usage examples
- `CONSULTATION-TEMPLATE-ENHANCEMENT.md` - Detailed documentation

#### 🔄 Updated Files
- `src/services/consultation.service.ts` - Added template message functions
- `src/index.ts` - Export new consultation types

### 🎯 Use Cases Supported
- **Customer Support Templates** - Multi-element templates with various action buttons
- **Information Request Templates** - Templates requesting user information with callbacks
- **Interactive Templates** - Templates with URL, SMS, phone, and query actions
- **Marketing Templates** - Templates with multiple call-to-action buttons
- **Service Templates** - Templates for service interactions and support

### 💡 Developer Experience Improvements
- **Type Safety**: Full TypeScript support with comprehensive interfaces
- **IntelliSense**: Complete autocomplete support for all template properties
- **Validation**: Automatic validation with clear error messages
- **Helper Functions**: Easy-to-use functions for creating template components
- **Documentation**: Comprehensive examples and API documentation

## [1.29.0] - 2025-01-05

### 🚀 Major Type Safety Improvements

#### ZNS Service Type Safety Enhancement
- **Feature**: Completely removed `any` types from ZNS Service validation functions
- **Impact**: Full type safety for all ZNS template components and validation
- **Benefits**: Better IDE support, compile-time error detection, improved developer experience

#### New Type Definitions Added
- `ZNSValidationComponent` - Union type for all ZNS components
- `ZNSTitleComponent` - Type-safe TITLE component (9-65 chars, max 4 params)
- `ZNSParagraphComponent` - Type-safe PARAGRAPH component (9-400 chars, max 10 params)
- `ZNSOTPComponent` - Type-safe OTP component (1-10 chars)
- `ZNSTableComponent` & `ZNSTableRow` - Type-safe TABLE component (2-8 rows)
- `ZNSLogoComponent` - Type-safe LOGO component with light/dark attachments
- `ZNSImagesComponent` - Type-safe IMAGES component (1-3 attachments)
- `ZNSButtonsComponent` & `ZNSButtonItem` - Type-safe BUTTONS component (1-2 buttons)
- `ZNSPaymentComponent` - Type-safe PAYMENT component with bank details
- `ZNSVoucherComponent` - Type-safe VOUCHER component with display options
- `ZNSRatingComponent` & `ZNSRatingItem` - Type-safe RATING component (exactly 5 items)
- `ZNSAttachment` - Type-safe attachment object for images

#### Updated Validation Functions
All validation functions now use specific types instead of `any`:
- `validateLayoutStructure()` - Uses `ZNSValidationComponent[]`
- `validateTitleComponent()` - Uses `ZNSTitleComponent`
- `validateParagraphComponent()` - Uses `ZNSParagraphComponent`
- `validateOTPComponent()` - Uses `ZNSOTPComponent`
- `validateTableComponent()` - Uses `ZNSTableComponent`
- `validateLogoComponent()` - Uses `ZNSLogoComponent`
- `validateImagesComponent()` - Uses `ZNSImagesComponent`
- `validateButtonsComponent()` - Uses `ZNSButtonsComponent`
- `validatePaymentComponent()` - Uses `ZNSPaymentComponent`
- `validateVoucherComponent()` - Uses `ZNSVoucherComponent`
- `validateRatingComponent()` - Uses `ZNSRatingComponent`
- `validateAttachment()` - Uses `ZNSAttachment`

#### Developer Experience Improvements
- **IntelliSense**: Full autocomplete support for all ZNS components
- **Error Detection**: Compile-time validation of component structures
- **Type Safety**: Eliminated runtime errors from incorrect component usage
- **Documentation**: Type definitions serve as inline documentation

#### Files Added/Modified
- `src/types/zns.ts` - Added comprehensive component type definitions
- `src/services/zns.service.ts` - Updated all validation functions with proper types
- `examples/zns-validation-example.ts` - Complete usage examples for all template types
- `ZNS-TYPE-IMPROVEMENTS.md` - Detailed documentation of improvements

#### Migration Guide
Existing code continues to work, but developers can now benefit from:
```typescript
// Before: No type safety
const component: any = { TITLE: { value: "Hello" } };

// After: Full type safety
const component: ZNSValidationComponent = {
  TITLE: { value: "Hello {{customer_name}}!" }
};
```

## [1.27.3] - 2025-08-31

### 🐛 Critical Bug Fixes

#### Fixed Video Upload Service - Direct API Implementation
- **Issue**: Video upload still failing even after base-client fix
- **Root Cause**: VideoUploadService was using complex client wrapper instead of direct API call
- **Solution**: Implemented direct axios call with FormData (same as successful manual upload)
- **Impact**: Video upload now works exactly like successful direct API calls
- **Files Changed**: `src/services/video-upload.service.ts`

#### Technical Implementation
```typescript
// New direct implementation (WORKING)
const formData = new FormData();
formData.append('file', bufferToUpload, {
  filename: actualFilename,
  contentType: this.getMimeTypeFromFilename(actualFilename),
});

const response = await axios.post(this.endpoints.video.upload, formData, {
  headers: {
    ...formData.getHeaders(),
    'access_token': accessToken,
  },
  timeout: 300000, // 5 minutes
  maxContentLength: Infinity,
  maxBodyLength: Infinity,
});
```

## [1.27.2] - 2025-08-31

### 🐛 Critical Bug Fixes

#### Fixed File Upload Content-Type Header Conflict
- **Issue**: Video upload and other file uploads were failing due to Content-Type header conflict
- **Root Cause**: SDK was setting `"Content-Type": "multipart/form-data"` without boundary, conflicting with `formData.getHeaders()`
- **Fix**: Removed hardcoded Content-Type, let form-data package set proper Content-Type with boundary
- **Impact**: All file upload APIs now work correctly (video upload, image upload, etc.)
- **Files Changed**: `src/clients/base-client.ts`

#### Technical Details
```typescript
// Before (BROKEN)
headers: {
  access_token: accessToken,
  "Content-Type": "multipart/form-data", // ❌ No boundary
  ...formData.getHeaders(),
}

// After (FIXED)
headers: {
  access_token: accessToken,
  ...formData.getHeaders(), // ✅ Proper Content-Type with boundary
}
```

#### Affected Services
- ✅ **VideoUploadService**: Video upload now works correctly
- ✅ **MessageManagementService**: File/image uploads fixed
- ✅ **All file upload endpoints**: Proper multipart/form-data handling

## [1.27.0] - 2025-01-30

### 🎨 Enhanced Banner Configuration

#### New Features
- **BannerConfig Type**: Introduced new `BannerConfig` type for flexible banner configuration
- **Dual Banner Support**: Support both `attachment_id` and `image_url` for banner images
- **Type Safety**: Enforced exclusive properties using TypeScript discriminated unions
- **Automatic Validation**: Built-in validation to prevent invalid banner configurations

#### Breaking Changes
- **sendCustomPromotion**: Changed `attachmentId: string` to `banner: BannerConfig`
- **sendCustomPromotionToMultipleUsers**: Changed `attachmentId: string` to `banner: BannerConfig`

#### Migration Guide
```typescript
// Before (v1.26.2)
await promotionService.sendCustomPromotion(accessToken, recipient, {
  attachmentId: "your_attachment_id",
  headerContent: "Header",
  // ...
});

// After (v1.27.0)
await promotionService.sendCustomPromotion(accessToken, recipient, {
  banner: { attachment_id: "your_attachment_id" }, // or { image_url: "https://..." }
  headerContent: "Header",
  // ...
});
```

#### New Validation Rules
- Banner must have either `attachment_id` OR `image_url`, not both
- Banner cannot be empty (must have at least one property)
- SDK throws `ZaloSDKError` with descriptive messages for invalid configurations

#### Documentation Updates
- Updated `PROMOTION_API_V3_MIGRATION.md` with banner configuration examples
- Updated `MULTIPLE_USERS_PROMOTION.md` with new usage patterns
- Added comprehensive examples in `examples/banner-config-example.ts`
- Added unit tests in `tests/banner-config.test.ts`

#### Benefits
- **Flexibility**: Choose between pre-uploaded attachments or direct image URLs
- **Performance**: Attachment IDs provide faster loading (recommended)
- **Type Safety**: TypeScript prevents invalid configurations at compile time
- **Runtime Validation**: Clear error messages for invalid configurations
- **Zalo Compliance**: Follows official Zalo API documentation exactly

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.24.0] - 2025-08-29

### 🎯 ENHANCED BUTTON TYPES SYSTEM - Complete TypeScript Support

#### 🔧 Comprehensive Button Type System
- **ADDED**: 5 specific button interfaces với proper TypeScript typing
- **ADDED**: `OpenUrlButton`, `QueryShowButton`, `QueryHideButton`, `OpenSmsButton`, `OpenPhoneButton`
- **UNION TYPE**: `PromotionButton` union type cho strict typing
- **FLEXIBLE INPUT**: `PromotionButtonInput` interface cho easy usage

#### ⚙️ Auto-Conversion System
- **ADDED**: `convertToTypedButton()` helper function
- **SMART CONVERSION**: Tự động convert từ flexible input sang proper API format
- **PAYLOAD VALIDATION**: Validate payload format theo từng button type
- **BACKWARD COMPATIBLE**: Hỗ trợ cả old và new button formats

#### 📊 Button Type Specifications
- **oa.open.url**: `{ url: string }` payload format
- **oa.query.show**: `string` payload (max 1000 chars) - tin nhắn HIỂN THỊ
- **oa.query.hide**: `string` payload (max 1000 chars) - tin nhắn ẨN
- **oa.open.sms**: `{ content: string, phone_code: string }` (content max 160 chars)
- **oa.open.phone**: `{ phone_code: string }` payload format

#### 🛡️ Enhanced Validation & Limits
- **TITLE LIMIT**: Max 100 characters per button title
- **PAYLOAD LIMITS**: Specific limits cho từng button type
- **BUTTON COUNT**: Max 4 buttons per message
- **TYPE SAFETY**: Full TypeScript support với proper type checking

#### 🎨 Developer Experience Improvements
- **INTELLISENSE**: Full autocomplete support cho button types
- **TYPE HINTS**: Clear type hints cho payload structures
- **ERROR PREVENTION**: Compile-time error checking
- **FLEXIBLE API**: Support both strict typing và flexible input

### 📚 COMPREHENSIVE DOCUMENTATION

#### New Documentation
- **ADDED**: `docs/BUTTON_TYPES_GUIDE.md` - Complete button types reference
- **DETAILED**: All 5 button types với examples và specifications
- **BEST PRACTICES**: Guidelines cho button usage và optimization

#### Enhanced Documentation
- **UPDATED**: `docs/PROMOTION_API_V3_MIGRATION.md` - TypeScript support section
- **UPDATED**: `examples/promotion-examples.ts` - Proper typed examples
- **TYPE EXAMPLES**: Comprehensive examples cho tất cả button types

### 🔄 Migration & Compatibility

#### Backward Compatibility
- **MAINTAINED**: Existing code continues to work without changes
- **AUTO-CONVERT**: Old button formats automatically converted
- **GRADUAL MIGRATION**: Developers có thể migrate từ từ

#### TypeScript Migration
```typescript
// Old (still works)
buttons: Array<{ title: string; type: string; payload: any }>

// New (recommended)
buttons: PromotionButtonInput[]
```

### 🎯 USE CASES ENHANCED
- **E-COMMERCE**: Product purchase buttons với proper URL handling
- **CUSTOMER SERVICE**: Query buttons cho automated responses
- **COMMUNICATION**: SMS và phone buttons cho direct contact
- **ENGAGEMENT**: Mixed button types cho comprehensive user interaction

---

## [1.23.0] - 2025-08-29

### 🚀 NEW FEATURE - Multiple Users Promotion với Real-time Tracking

#### 🎯 Multiple Users Support
- **ADDED**: `sendCustomPromotionToMultipleUsers()` - Gửi promotion đến nhiều user IDs cùng lúc
- **DUAL MODES**: Sequential (tuần tự) và Parallel (song song) sending modes
- **SMART DEDUPLICATION**: Tự động loại bỏ user IDs trùng lặp
- **ERROR ISOLATION**: Lỗi của 1 user không ảnh hưởng các user khác

#### 📊 Real-time Tracking & Callbacks
- **PROGRESS TRACKING**: `onProgress` callback với real-time statistics
- **USER COMPLETION**: `onUserComplete` callback cho từng user hoàn thành
- **ESTIMATED TIME**: Tính toán thời gian còn lại (ETA) cho sequential mode
- **DETAILED METRICS**: Success rate, execution time, start/end timestamps

#### ⚡ Performance Optimization
- **SEQUENTIAL MODE**: Gửi tuần tự với delay tùy chỉnh để tránh rate limit
- **PARALLEL MODE**: Gửi song song để tối ưu tốc độ cho urgent campaigns
- **CONFIGURABLE DELAY**: Tùy chỉnh delay giữa các tin nhắn (default: 1000ms)
- **CONTINUE ON ERROR**: Option để tiếp tục khi gặp lỗi (default: true)

#### 🛡️ Enhanced Error Handling
- **INDIVIDUAL RESULTS**: Chi tiết kết quả success/failure cho từng user
- **ERROR DETAILS**: Thông tin lỗi cụ thể cho từng user thất bại
- **RESILIENT PROCESSING**: Campaign không bị dừng khi 1 user lỗi
- **COMPREHENSIVE LOGGING**: Detailed logging cho debugging và monitoring

### 📊 NEW INTERFACES & TYPES

#### Multiple Promotion Types
- **ADDED**: `PromotionUserResult` - Kết quả cho từng user riêng biệt
- **ADDED**: `MultiplePromotionProgress` - Interface cho progress tracking
- **ADDED**: `MultiplePromotionResult` - Kết quả tổng thể campaign
- **ENHANCED**: Progress callback với detailed metrics và ETA

### 📚 COMPREHENSIVE DOCUMENTATION & EXAMPLES

#### New Documentation
- **ADDED**: `docs/MULTIPLE_USERS_PROMOTION.md` - Hướng dẫn chi tiết multiple users
- **UPDATED**: `docs/PROMOTION_API_V3_MIGRATION.md` - Thêm multiple users examples
- **BEST PRACTICES**: Guidelines cho sequential vs parallel modes

#### Enhanced Examples
- **ADDED**: `sendPromotionToMultipleUsers()` - Sequential mode với full tracking
- **ADDED**: `sendPromotionParallel()` - Parallel mode example
- **EXAMPLES**: Real-time progress monitoring và error handling
- **EXAMPLES**: Performance metrics và success rate tracking

### 🎯 USE CASES
- **Marketing Campaigns**: Gửi promotion đến danh sách khách hàng VIP
- **Flash Sales**: Thông báo urgent đến nhiều users cùng lúc
- **Event Notifications**: Gửi thông báo sự kiện đến attendees
- **Customer Segmentation**: Targeted promotions cho từng nhóm khách hàng

---

## [1.22.0] - 2025-08-29

### 🚀 MAJOR UPDATE - Promotion Service v3.0

#### ⬆️ API Version Upgrade
- **UPGRADED**: Promotion Service từ v2.0 lên **v3.0** API
- **URL**: Cập nhật endpoint từ `/v2.0/oa/message/promotion` lên `/v3.0/oa/message/promotion`
- **BREAKING**: Cấu trúc message elements hoàn toàn mới, không tương thích ngược

#### 🏗️ New Message Elements Structure
- **BANNER**: Element với `attachment_id` hoặc `image_url`, type="banner"
- **HEADER**: Element với `content` và `align`, type="header" (tối đa 100 ký tự)
- **TEXT**: Element với `content` và `align`, type="text" (tối đa 1000 ký tự, tối đa 2 đoạn)
- **TABLE**: Element với `content` array, type="table" (tối đa 5 items, key ≤ 25 chars, value ≤ 100 chars)

#### 🔘 Enhanced Button System
- **PAYLOAD**: Hỗ trợ cả object và string tùy theo button type
- **TYPES**: `oa.open.url`, `oa.query.show`, `oa.query.hide`, `oa.open.sms`, `oa.open.phone`
- **VALIDATION**: Title tối đa 35 ký tự, tối đa 4 buttons
- **ICONS**: Hỗ trợ `image_icon` với URL/attachment_id/"default"

#### 🌐 Multi-language Support
- **LANGUAGE**: Thêm thuộc tính `language: "VI" | "EN"`
- **LOCALIZATION**: Nội dung mặc định tự động chuyển ngôn ngữ

#### 🆕 New Methods & Features
- **ADDED**: `sendCustomPromotion()` - Gửi promotion theo format chuẩn docs v3.0
- **ENHANCED**: `sendProductPromotion()` - Cập nhật với elements structure mới
- **ENHANCED**: `sendEventNotification()` - Cập nhật với table và text elements
- **ENHANCED**: `sendNewsletter()` - Cập nhật với banner và table elements
- **VALIDATION**: Nâng cao validation cho elements và buttons

#### 📚 Comprehensive Documentation & Examples
- **ADDED**: `docs/PROMOTION_API_V3_MIGRATION.md` - Hướng dẫn migration chi tiết
- **ADDED**: `examples/promotion-examples.ts` - Examples đầy đủ cho tất cả tính năng
- **EXAMPLES**: Demo 5 button types với payload format đúng
- **MIGRATION**: Breaking changes và checklist migration

#### 🛡️ Enhanced Validation & Error Handling
- **TIME**: Kiểm tra sending time (8:00-22:00)
- **ELEMENTS**: Validate structure và content length
- **BUTTONS**: Validate payload format theo từng type
- **ERRORS**: Error codes cụ thể cho từng violation

### 🔧 BREAKING CHANGES
- **Elements Structure**: Hoàn toàn khác v2.0, cần migration
- **Button Payload**: Từ string thành object/string tùy type
- **Image Handling**: Ưu tiên `attachment_id` thay vì `image_url`
- **API URL**: Phải cập nhật từ v2.0 lên v3.0

---

## [1.21.0] - 2025-08-29

### 🚀 NEW FEATURES

#### Enhanced Broadcast Service - Multiple Messages Support
- **ADDED**: `sendMultipleBroadcastMessages()` - Gửi nhiều broadcast messages với nhiều attachment IDs
- **MODES**: Hỗ trợ 2 chế độ gửi: `sequential` (tuần tự) và `parallel` (song song)
- **DELAY**: Tùy chỉnh delay giữa các tin nhắn cho sequential mode
- **PROGRESS**: Real-time progress tracking với callback `onProgress`
- **RESILIENT**: Error isolation - lỗi của 1 tin không ảnh hưởng các tin khác
- **SMART**: Tự động loại bỏ attachment IDs trùng lặp

#### Advanced Campaign Management
- **SEQUENTIAL**: Gửi tuần tự với delay tùy chỉnh để tránh rate limit
- **PARALLEL**: Gửi song song để tối ưu tốc độ
- **MONITORING**: Theo dõi real-time số tin thành công/thất bại
- **STATISTICS**: Thống kê chi tiết thời gian thực hiện và success rate

### 📊 NEW INTERFACES

#### Multiple Broadcast Types
- **ADDED**: `BroadcastMessageResult` - Kết quả từng tin nhắn broadcast
- **ADDED**: `MultipleBroadcastProgress` - Interface cho progress tracking
- **ADDED**: `MultipleBroadcastResult` - Kết quả tổng thể campaign
- **ENHANCED**: Progress callback với detailed metrics

### 🛡️ ENHANCED ERROR HANDLING
- **ISOLATION**: Lỗi của 1 attachment không làm dừng campaign
- **DETAILED**: Chi tiết lỗi cho từng tin nhắn riêng biệt
- **VALIDATION**: Kiểm tra attachment IDs array không rỗng
- **DEDUPLICATION**: Tự động loại bỏ attachment IDs trùng lặp

### 📚 UPDATED DOCUMENTATION & EXAMPLES

#### Enhanced Documentation
- **UPDATED**: `docs/BROADCAST_SERVICE.md` - Thêm multiple messages examples
- **UPDATED**: `docs/API_REFERENCE.md` - Thêm sendMultipleBroadcastMessages method
- **UPDATED**: `README.md` - Thêm ví dụ multiple broadcast

#### Enhanced Examples
- **UPDATED**: `examples/broadcast-example.ts` - Thêm sequential và parallel examples
- **EXAMPLES**: Progress tracking và error handling
- **EXAMPLES**: Campaign management với statistics

#### Enhanced Tests
- **UPDATED**: `tests/broadcast.test.ts` - Comprehensive tests cho multiple messages
- **COVERAGE**: Test sequential và parallel modes
- **COVERAGE**: Test progress callback và error handling
- **COVERAGE**: Test duplicate removal và validation

### 🔧 API ENHANCEMENTS
- **FLEXIBLE**: Chọn mode phù hợp với use case (sequential vs parallel)
- **CONFIGURABLE**: Delay tùy chỉnh cho rate limiting
- **OBSERVABLE**: Progress tracking cho campaign monitoring
- **ROBUST**: Comprehensive error handling và validation

## [1.20.0] - 2025-08-29

### 🚀 NEW FEATURES

#### Broadcast Service - Gửi Tin Truyền Thông Broadcast
- **ADDED**: `BroadcastService` - Service mới để gửi tin truyền thông broadcast đến nhiều người dùng
- **ADDED**: `sendBroadcastMessage()` - API gửi broadcast với targeting criteria
- **ADDED**: `createBroadcastTarget()` - Helper tạo targeting criteria dễ dàng
- **SUPPORT**: Targeting theo tuổi, giới tính, tỉnh thành, miền, platform
- **COMPLIANCE**: Tuân thủ 100% Zalo API specification

#### Advanced Targeting System
- **AGES**: 8 nhóm tuổi (0-12, 13-17, 18-24, 25-34, 35-44, 45-54, 55-64, 65+)
- **GENDER**: 3 lựa chọn (All, Male, Female)
- **CITIES**: 63 tỉnh thành Việt Nam với mapping chính xác
- **LOCATIONS**: 3 miền (North, Central, South)
- **PLATFORMS**: 3 hệ điều hành (iOS, Android, Windows Phone)

#### Helper Methods & Constants
- **ADDED**: `getCityCodes()` - Lấy mapping tỉnh thành
- **ADDED**: `getAgeGroupCodes()` - Lấy mã nhóm tuổi
- **ADDED**: `getGenderCodes()` - Lấy mã giới tính
- **ADDED**: `getLocationCodes()` - Lấy mã miền
- **ADDED**: `getPlatformCodes()` - Lấy mã platform
- **CONSTANTS**: Đầy đủ constants cho tất cả targeting criteria

### 📊 NEW INTERFACES

#### Broadcast Types
- **ADDED**: `BroadcastTarget` - Interface cho targeting criteria
- **ADDED**: `BroadcastRecipient` - Interface cho thông tin người nhận
- **ADDED**: `BroadcastMessage` - Interface cho tin nhắn broadcast
- **ADDED**: `BroadcastRequest` - Request payload structure
- **ADDED**: `BroadcastResponse` - Response structure với message_id
- **ADDED**: `BroadcastMessageElement` - Element structure cho article attachment

### 🛡️ VALIDATION & ERROR HANDLING
- **VALIDATION**: Kiểm tra targeting criteria hợp lệ
- **VALIDATION**: Kiểm tra attachment_id bắt buộc
- **ERROR**: Comprehensive error messages cho từng trường hợp
- **TYPE SAFETY**: Full TypeScript support với IntelliSense

### 📚 DOCUMENTATION & EXAMPLES

#### New Documentation
- **ADDED**: `docs/BROADCAST_SERVICE.md` - Hướng dẫn chi tiết BroadcastService
- **UPDATED**: `docs/API_REFERENCE.md` - Thêm BroadcastService methods
- **UPDATED**: `README.md` - Thêm Broadcast Service examples

#### New Examples
- **ADDED**: `examples/broadcast-example.ts` - Ví dụ sử dụng BroadcastService
- **EXAMPLES**: Targeting đơn giản và phức tạp
- **EXAMPLES**: Error handling và best practices

#### New Tests
- **ADDED**: `tests/broadcast.test.ts` - Unit tests cho BroadcastService
- **COVERAGE**: Test targeting criteria creation
- **COVERAGE**: Test broadcast message sending
- **COVERAGE**: Test validation logic

### 🔧 SDK INTEGRATION
- **INTEGRATION**: Tích hợp BroadcastService vào main ZaloSDK class
- **ACCESS**: Sử dụng qua `zalo.broadcast`
- **EXPORT**: Export tất cả types và service từ main index

### 📋 API SPECIFICATION COMPLIANCE
- **ENDPOINT**: `https://openapi.zalo.me/v2.0/oa/message` ✅
- **METHOD**: POST với JSON payload ✅
- **HEADERS**: access_token authentication ✅
- **TARGETING**: recipient.target với đầy đủ criteria ✅
- **MESSAGE**: Template type "media" với article attachment ✅
- **RESPONSE**: message_id, error, message structure ✅

## [1.19.0] - 2025-08-29

### 🚀 NEW FEATURES

#### Group Message List APIs - Gửi Danh Sách Tin Nhắn Group
- **ADDED**: `sendMessageListToGroup()` - Gửi danh sách tin nhắn tới 1 group với delay tùy chỉnh
- **ADDED**: `sendMessageListToMultipleGroups()` - Gửi danh sách tin nhắn tới nhiều groups cùng lúc
- **SUPPORT**: Hỗ trợ đầy đủ 5 loại tin nhắn group: text, image, file, sticker, mention
- **FLEXIBLE**: Delay riêng cho từng tin nhắn + delay giữa groups để tránh rate limit
- **SMART**: Tự động loại bỏ group IDs trùng lặp và validation đầy đủ

#### Real-time Progress Tracking cho Groups
- **CALLBACK**: `onProgress` callback để tracking real-time từng tin nhắn và group
- **DETAILED**: Thống kê chi tiết thành công/thất bại cho từng tin nhắn và group
- **ISOLATION**: Error của 1 tin nhắn/group không ảnh hưởng phần còn lại
- **METRICS**: Tracking thời gian thực hiện, success rate, và message statistics

#### Advanced Group Messaging Features
- **MENTION**: Hỗ trợ mention members với offset và length chính xác
- **CAPTION**: Image messages với caption tối đa 2000 ký tự
- **FILE**: File attachments với token từ upload API
- **SEQUENTIAL**: Gửi tuần tự để đảm bảo thứ tự và tránh rate limit

### 📊 NEW INTERFACES

#### Group Message List Types
- **ADDED**: `GroupMessageItem` - Interface cho từng tin nhắn trong danh sách
- **ADDED**: `SendMessageListToGroupRequest` - Request cho single group
- **ADDED**: `SendMessageListToGroupResponse` - Response với detailed results
- **ADDED**: `SendMessageListToMultipleGroupsRequest` - Request cho multiple groups
- **ADDED**: `SendMessageListToMultipleGroupsResponse` - Response với group statistics
- **ADDED**: `GroupMessageProgressInfo` - Interface cho message progress tracking
- **ADDED**: `MultipleGroupsProgressInfo` - Interface cho multiple groups progress tracking

### 📚 DOCUMENTATION & EXAMPLES

#### New Documentation
- **ADDED**: `docs/group-message-list-api.md` - Comprehensive guide cho Group Message List APIs
- **UPDATED**: Hướng dẫn chi tiết từng loại tin nhắn group và use cases
- **ADDED**: So sánh API cũ vs mới với feature comparison table

#### New Examples
- **ADDED**: `examples/group-message-list.ts` - Ví dụ gửi danh sách tin nhắn group
- **INCLUDED**: System notifications, marketing campaigns, meeting notifications examples
- **DEMO**: Mention messages, image captions, file attachments usage

### 🎯 USE CASES

#### System Administration
- **MAINTENANCE**: Thông báo bảo trì hệ thống tới tất cả groups
- **ALERTS**: Emergency alerts với hình ảnh và file đính kèm
- **UPDATES**: System updates với mention admins

#### Marketing & Business
- **CAMPAIGNS**: Flash sales, khuyến mãi tới customer groups
- **PROMOTIONS**: Product launches với hình ảnh và stickers
- **ANNOUNCEMENTS**: Company announcements với professional formatting

#### Team Communication
- **MEETINGS**: Meeting notifications với mention participants
- **PROJECTS**: Project updates tới multiple team groups
- **REPORTS**: Regular reports với file attachments

### 🔧 TECHNICAL IMPROVEMENTS

#### Enhanced Error Handling
- **ROBUST**: Comprehensive error handling cho từng tin nhắn và group
- **CONTINUE**: Tiếp tục gửi khi gặp lỗi thay vì dừng toàn bộ process
- **DETAILED**: Error messages chi tiết với context information
- **ISOLATION**: Error isolation giữa tin nhắn và giữa groups

#### Performance Optimizations
- **SEQUENTIAL**: Sequential processing để tránh overwhelming Zalo servers
- **MEMORY**: Optimized memory usage cho large group lists
- **RATE-LIMIT**: Built-in rate limiting protection với configurable delays
- **TIMEOUT**: Proper timeout handling và cleanup

#### Type Safety & Validation
- **TYPESCRIPT**: Full TypeScript support với strict typing
- **VALIDATION**: Runtime validation cho tất cả input parameters
- **INTELLISENSE**: Complete IDE support với detailed JSDoc comments
- **CONSTRAINTS**: Proper validation cho message constraints (text length, etc.)

## [1.18.0] - 2025-08-29

### 🚀 NEW FEATURES

#### Message Sequence APIs - Gửi Chuỗi Tin Nhắn Tự Động
- **ADDED**: `sendMessageSequence()` - Gửi chuỗi tin nhắn tư vấn với delay tùy chỉnh
- **ADDED**: `sendMessageSequenceToMultipleUsers()` - Gửi chuỗi tin nhắn tới nhiều users cùng lúc
- **SUPPORT**: Hỗ trợ đầy đủ 6 loại tin nhắn: text, image, gif, file, sticker, request_user_info
- **FLEXIBLE**: Delay riêng cho từng tin nhắn + delay mặc định cho toàn bộ chuỗi
- **SMART**: Tự động loại bỏ user IDs trùng lặp và validation đầy đủ

#### Real-time Progress Tracking
- **CALLBACK**: `onProgress` callback để tracking real-time từng user
- **DETAILED**: Thống kê chi tiết thành công/thất bại cho từng tin nhắn và user
- **ISOLATION**: Error của 1 user không ảnh hưởng đến users khác
- **METRICS**: Tracking thời gian thực hiện, success rate, và message statistics

#### Rate Limiting Protection
- **PROTECTION**: `delayBetweenUsers` để tránh hit rate limit của Zalo
- **SEQUENTIAL**: Gửi tuần tự từng user để đảm bảo stability
- **CONFIGURABLE**: Delay linh hoạt theo từng use case

### 📊 NEW INTERFACES

#### Message Sequence Types
- **ADDED**: `MessageItem` - Interface cho từng tin nhắn trong chuỗi
- **ADDED**: `SendMessageSequenceRequest` - Request cho single user
- **ADDED**: `SendMessageSequenceResponse` - Response với detailed results
- **ADDED**: `SendMessageSequenceToMultipleUsersRequest` - Request cho multiple users
- **ADDED**: `SendMessageSequenceToMultipleUsersResponse` - Response với user statistics
- **ADDED**: `UserProgressInfo` - Interface cho progress tracking callback

### 📚 DOCUMENTATION & EXAMPLES

#### New Documentation
- **ADDED**: `docs/message-sequence-api.md` - Comprehensive guide cho Message Sequence APIs
- **UPDATED**: Hướng dẫn chi tiết từng loại tin nhắn và use cases
- **ADDED**: So sánh API đơn user vs nhiều users với bảng feature comparison

#### New Examples
- **ADDED**: `examples/send-message-sequence.ts` - Ví dụ gửi chuỗi tin nhắn cho 1 user
- **ADDED**: `examples/send-message-sequence-multiple-users.ts` - Ví dụ gửi cho nhiều users
- **INCLUDED**: Marketing campaigns, customer support, VIP customer care examples

### 🎯 USE CASES

#### Marketing & Campaigns
- **CAMPAIGN**: Gửi chuỗi tin nhắn marketing tới danh sách khách hàng
- **PROMOTION**: Flash sales, khuyến mãi với hình ảnh và call-to-action
- **TRACKING**: Real-time tracking delivery success rate

#### Customer Support
- **NOTIFICATION**: Thông báo hệ thống, bảo trì tới tất cả users
- **SUPPORT**: Gửi hướng dẫn, tài liệu hỗ trợ với file attachments
- **CARE**: Chăm sóc khách hàng VIP với tin nhắn cá nhân hóa

#### Business Automation
- **ONBOARDING**: Chuỗi tin nhắn chào mừng khách hàng mới
- **FOLLOW-UP**: Theo dõi sau bán hàng với stickers và images
- **SURVEY**: Thu thập feedback với request user info messages

### 🔧 TECHNICAL IMPROVEMENTS

#### Error Handling
- **ROBUST**: Comprehensive error handling cho từng tin nhắn và user
- **CONTINUE**: Tiếp tục gửi khi gặp lỗi thay vì dừng toàn bộ process
- **DETAILED**: Error messages chi tiết với context information

#### Performance
- **EFFICIENT**: Sequential processing để tránh overwhelming Zalo servers
- **MEMORY**: Optimized memory usage cho large user lists
- **TIMEOUT**: Proper timeout handling và cleanup

#### Type Safety
- **TYPESCRIPT**: Full TypeScript support với strict typing
- **VALIDATION**: Runtime validation cho tất cả input parameters
- **INTELLISENSE**: Complete IDE support với detailed JSDoc comments

## [1.17.2] - 2025-08-29

### 🐛 BUG FIXES

#### Article API Limit Fix
- **FIXED**: Updated `ARTICLE_CONSTRAINTS.LIST_MAX_LIMIT` from 100 to 10 to comply with Zalo API requirements
- **FIXED**: Updated default `batchSize` from 50 to 10 in `getAllArticles()` method
- **FIXED**: Updated default `batchSize` from 50 to 10 in `getAllArticlesCombined()` method
- **FIXED**: Updated default `batch_size` from 50 to 10 in `getAllArticlesWithDetails()` method
- **FIXED**: Updated documentation comments to reflect correct API limits (max 10 items per request)

#### Impact
- **RESOLVED**: "limit is invalid: maximum limit is 10" error when syncing articles
- **IMPROVED**: Better compliance with Zalo API rate limits and constraints
- **MAINTAINED**: All existing functionality while respecting API limits through automatic batching

## [1.13.0] - 2025-01-17

### 🚀 NEW FEATURES

#### Enhanced Article API - Get All Articles
- **ADDED**: `getAllArticles()` - Lấy tất cả bài viết theo loại với tự động pagination
- **ADDED**: `getAllArticlesCombined()` - Lấy tất cả bài viết cả 2 loại (normal + video) kết hợp
- **ENHANCED**: Automatic pagination handling - không cần xử lý offset/limit thủ công
- **ADDED**: Progress tracking với callback `onProgress` để theo dõi tiến trình real-time
- **ADDED**: Flexible configuration với `batchSize`, `maxArticles`, và safety limits

#### Advanced Features
- **SAFETY**: Built-in safety checks để tránh infinite loops (max 100 batches)
- **PERFORMANCE**: Configurable batch sizes (1-100 articles per request)
- **CONTROL**: Giới hạn tổng số articles (`maxArticles`, 0 = unlimited)
- **MONITORING**: Real-time progress callbacks với detailed metrics
- **TYPE-SAFE**: Full TypeScript support với `ArticleListItem[]` return types

#### Smart Response Handling
- **ROBUST**: Handles both `ZaloResponse<T>` và direct response formats
- **FLEXIBLE**: Supports cả `response.data.medias` và `response.medias` structures
- **ERROR-SAFE**: Comprehensive error handling với `ZaloSDKError` integration

### 📚 DOCUMENTATION

#### New Documentation Files
- **ADDED**: `docs/enhanced-article-api.md` - Comprehensive guide cho enhanced article APIs
- **ADDED**: `examples/get-all-articles-example.ts` - Practical usage examples với 4 scenarios
- **DETAILED**: API reference với parameters, return types, và best practices
- **EXAMPLES**: Real-world usage patterns và performance recommendations

#### Developer Experience
- **ENHANCED**: Detailed JSDoc comments với @example blocks
- **IMPROVED**: IntelliSense support với comprehensive type definitions
- **ADDED**: Progress tracking examples và error handling patterns
- **GUIDES**: Performance tuning và rate limiting recommendations

### 🔧 TECHNICAL IMPROVEMENTS

#### Code Quality
- **TYPE-SAFE**: Full TypeScript compliance với proper interface definitions
- **VALIDATED**: Input validation với `ARTICLE_CONSTRAINTS` integration
- **OPTIMIZED**: Efficient pagination logic với smart batch management
- **TESTED**: Comprehensive error scenarios và edge case handling

#### API Design
- **CONSISTENT**: Follows existing SDK patterns và naming conventions
- **EXTENSIBLE**: Modular design cho future enhancements
- **BACKWARD-COMPATIBLE**: Không breaking changes cho existing `getArticleList()`
- **PERFORMANCE**: Optimized cho large datasets với configurable limits

### 💡 USAGE EXAMPLES

```typescript
// Simple: Get all normal articles
const result = await articleService.getAllArticles(accessToken, "normal");

// Advanced: With progress tracking và limits
const result = await articleService.getAllArticles(accessToken, "normal", {
  batchSize: 50,
  maxArticles: 1000,
  onProgress: (progress) => console.log(`${progress.totalFetched} articles`)
});

// Combined: Get both normal và video articles
const combined = await articleService.getAllArticlesCombined(accessToken, {
  maxArticlesPerType: 500
});
```

## [1.12.1] - 2025-01-17

### 🔧 MAINTENANCE

- **Cập nhật**: Tối ưu tài liệu, ví dụ và xuất bản bản vá nhỏ.
- **Cải thiện**: Đồng bộ hoá typings và mô tả package để phát hành ổn định.
- **Build**: Đảm bảo `prepublishOnly` chạy `clean` + `build` trước khi publish.

## [1.12.0] - 2025-01-17

### 🎯 NEW FEATURES

#### Webhook Message Classification Helpers
- **ADDED**: `isUserMessageEvent()` - Phân biệt tin nhắn từ người dùng cá nhân gửi tới OA
- **ADDED**: `isGroupMessageEvent()` - Phân biệt tin nhắn từ người dùng trong group
- **ADDED**: `isOAToUserMessageEvent()` - Phân biệt tin nhắn OA gửi cho người dùng cá nhân
- **ADDED**: `isOAToGroupMessageEvent()` - Phân biệt tin nhắn OA gửi tới group
- **ADDED**: `getMessageDirection()` - Xác định hướng và đích của tin nhắn với mô tả chi tiết

#### Enhanced Type Safety
- **IMPROVED**: Better type guards cho webhook message classification
- **ENHANCED**: Comprehensive support cho 38+ message event types
- **ADDED**: Direction và target classification với Vietnamese descriptions

### 📚 DOCUMENTATION

#### New Documentation Files
- **ADDED**: `docs/WEBHOOK_MESSAGE_HELPERS.md` - Comprehensive guide cho message classification
- **ADDED**: `examples/webhook-message-classification.ts` - Practical usage examples
- **UPDATED**: README.md với message classification helpers section

#### Developer Experience
- **ENHANCED**: IntelliSense support với detailed JSDoc comments
- **ADDED**: 13 comprehensive test cases cho message classification helpers
- **IMPROVED**: Better error handling và unknown event detection

### 🔧 TECHNICAL IMPROVEMENTS