@warriorteam/redai-zalo-sdk 1.6.0 → 1.6.2

package/CHANGELOG.md

@@ -1,304 +1,304 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-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.6.0] - 2025-01-09
-
-### Added
-
-#### 🆕 POST Method for User List Retrieval
-- **New Method**: `postUserList()` in UserService for POST-based user list retrieval
-- **Same Endpoint**: Uses identical URL as `getUserList()` but with POST method
-- **Request Body**: Sends data via request body instead of URL parameters
-- **Full Feature Parity**: Supports all same parameters as GET method
-- **Type Safety**: Same TypeScript interfaces and response types
-
-#### 📚 Enhanced Documentation & Examples
-- **Comprehensive Example**: New `examples/user-list-post-example.ts` with detailed usage scenarios
-- **Method Comparison**: Examples comparing GET vs POST approaches
-- **Pagination Support**: Complete pagination examples using POST method
-- **Filter Demonstrations**: Examples with tags, followers, and interaction periods
-
-### Technical Details
-
-#### POST Method Features
-- **Endpoint**: `https://openapi.zalo.me/v3.0/oa/user/getlist` (same as GET)
-- **Method**: POST with JSON body data
-- **Parameters Support**:
-  - `offset`: Starting position for pagination
-  - `count`: Number of users to retrieve (max 50)
-  - `tag_name`: Filter by specific tag
-  - `last_interaction_period`: Filter by interaction timeframe
-  - `is_follower`: Filter by follower status
-- **Response Format**: Identical to GET method (`UserListResponse`)
-- **Error Handling**: Same comprehensive error handling as GET method
-
-#### Use Cases for POST Method
-- **Large Parameter Sets**: Better handling of complex filter combinations
-- **Request Body Preference**: When POST body is preferred over URL parameters
-- **API Consistency**: Matching backend API patterns that expect POST
-- **Future Extensibility**: Easier to extend with additional body parameters
-
-### Usage Examples
-
-#### Basic POST Method Usage
-```typescript
-import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
-
-const zalo = new ZaloSDK({
-  appId: "your-app-id",
-  appSecret: "your-app-secret"
-});
-
-// POST method for user list
-const result = await zalo.user.postUserList(accessToken, {
-  offset: 0,
-  count: 20,
-  tag_name: "VIP_CUSTOMER",
-  is_follower: true
-});
-```
-
-#### Comparing GET vs POST Methods
-```typescript
-// GET method (existing)
-const getResult = await zalo.user.getUserList(accessToken, request);
-
-// POST method (new)
-const postResult = await zalo.user.postUserList(accessToken, request);
-
-// Results are identical
-console.log(getResult.total === postResult.total); // true
-```
-
-### Files Added/Modified
-
-#### New Files
-- `examples/user-list-post-example.ts` - Comprehensive POST method examples
-
-#### Modified Files
-- `src/services/user.service.ts` - Added `postUserList()` method and `postList` endpoint
-
-### Breaking Changes
-None. This release maintains full backward compatibility.
-
-### Migration Guide
-No migration required. The new `postUserList()` method is an additional option alongside the existing `getUserList()` method.
-
-Both methods provide identical functionality:
-- Use `getUserList()` for GET-based requests (existing behavior)
-- Use `postUserList()` for POST-based requests (new option)
-
----
-
-## [1.5.0] - 2025-01-09
-
-### Added
-
-#### 🆕 OA Quality Information API
-- **New Method**: `getOAQuality()` in ZNSService for retrieving OA ZNS sending quality information
-- **Quality Metrics**: Support for current (48-hour) and 7-day quality assessment periods
-- **Quality Levels**: HIGH, MEDIUM, LOW, UNDEFINED quality level indicators
-- **Type Safety**: New `ZNSOAQualityInfo` interface for comprehensive type support
-
-#### 🔧 Enhanced URL Encoding
-- **Improved Encoding**: Added `encodeURIComponent` for JSON data in UserService API calls
-- **Better Compatibility**: Enhanced URL parameter handling for special characters
-- **API Reliability**: Improved data transmission reliability for complex JSON structures
-
-### Technical Details
-
-#### OA Quality Information Features
-- **Real-time Quality**: Get current OA ZNS sending quality (48-hour window)
-- **Historical Quality**: Get 7-day quality assessment for trend analysis
-- **Quality Indicators**:
-  - `HIGH`: Excellent sending quality
-  - `MEDIUM`: Average sending quality
-  - `LOW`: Poor sending quality
-  - `UNDEFINED`: Quality not determined (no ZNS sent in assessment period)
-
-#### URL Encoding Improvements
-- **JSON Parameter Encoding**: Proper encoding of JSON data in URL parameters
-- **Special Character Support**: Enhanced handling of special characters in API requests
-- **Cross-platform Compatibility**: Improved compatibility across different environments
-
-### Usage Examples
-
-#### OA Quality Information
-```typescript
-import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
-
-const zalo = new ZaloSDK({
-  appId: "your-app-id",
-  appSecret: "your-app-secret"
-});
-
-// Get OA quality information
-const qualityInfo = await zalo.zns.getOAQuality(accessToken);
-console.log('Current Quality:', qualityInfo.data.oaCurrentQuality);
-console.log('7-day Quality:', qualityInfo.data.oa7dayQuality);
-```
-
-### Files Modified
-- `src/services/zns.service.ts` - Added getOAQuality() method
-- `src/types/zns.ts` - Added ZNSOAQualityInfo interface, updated quality types
-- `src/services/user.service.ts` - Enhanced URL encoding with encodeURIComponent
-
-### Breaking Changes
-None. This release maintains full backward compatibility.
-
-### Migration Guide
-No migration required. All existing code will continue to work unchanged.
-
----
-
-## [1.2.0] - 2025-01-08
-
-### Added
-
-#### 🆕 ConsultationService - Customer Support Messaging
-- **New Service**: `ConsultationService` for sending customer support messages within 48-hour interaction window
-- **Text Messages**: Send consultation text messages with automatic validation (max 2000 characters)
-- **Image Messages**: Send consultation images for visual support and guides
-- **File Messages**: Send consultation file attachments (manuals, guides, documents)
-- **Sticker Messages**: Send consultation sticker messages for friendly interactions
-- **General Messages**: Send any type of consultation message with unified interface
-
-#### 📚 Documentation & Examples
-- **Comprehensive Guide**: New `docs/CONSULTATION_SERVICE.md` with detailed usage instructions
-- **Practical Examples**: New `examples/consultation-service-example.ts` with 6 real-world scenarios
-- **Smart Customer Support**: Example implementation of intelligent customer support bot
-- **Webhook Integration**: Complete webhook integration examples for consultation service
-- **Error Handling**: Detailed error handling and retry mechanism examples
-
-#### 🔧 SDK Integration
-- **Quick Access**: Available via `zalo.consultation` property
-- **Quick Methods**: Added `zalo.sendConsultationText()` and `zalo.sendConsultationImage()` convenience methods
-- **Type Safety**: Full TypeScript support with comprehensive type definitions
-- **Error Handling**: Enhanced error handling with `ZaloSDKError` for consultation-specific errors
-
-#### 📖 Documentation Updates
-- **README.md**: Updated with ConsultationService examples and documentation links
-- **SERVICES_ADDED.md**: Added detailed ConsultationService documentation
-- **Keywords**: Enhanced package keywords for better discoverability
-
-### Technical Details
-
-#### Consultation Service Features
-- **48-Hour Window**: Enforces Zalo's 48-hour interaction window for consultation messages
-- **Content Validation**: Automatic validation of message content and format
-- **Quota Management**: Built-in quota tracking and management
-- **Anti-Spam**: Follows Zalo's anti-spam guidelines and best practices
-- **Retry Logic**: Built-in retry mechanism for failed requests
-
-#### Usage Conditions
-- Messages must be sent within 48 hours of last user interaction
-- Content must be consultation/support related (no direct advertising)
-- User must have followed the OA and not blocked it
-- No daily limit but must follow anti-spam guidelines
-
-#### Integration Points
-- Seamless integration with existing webhook system
-- Compatible with all existing SDK features
-- Follows established SDK patterns and conventions
-- Full backward compatibility maintained
-
-### Examples Added
-
-1. **Basic Consultation**: Simple text message consultation
-2. **Image Support**: Sending images for visual guidance
-3. **File Attachments**: Sending documents and manuals
-4. **Smart Customer Support**: AI-powered customer support bot
-5. **Retry Mechanism**: Robust error handling and retry logic
-6. **Webhook Integration**: Complete webhook event handling
-
-### Files Added/Modified
-
-#### New Files
-- `src/services/consultation.service.ts` - Main ConsultationService implementation
-- `docs/CONSULTATION_SERVICE.md` - Comprehensive documentation
-- `examples/consultation-service-example.ts` - Practical examples
-- `CHANGELOG.md` - This changelog file
-
-#### Modified Files
-- `README.md` - Added ConsultationService documentation and examples
-- `SERVICES_ADDED.md` - Added ConsultationService details
-- `package.json` - Updated version, description, keywords, and scripts
-- `src/index.ts` - Export ConsultationService types and classes
-- `src/zalo-sdk.ts` - Integrated ConsultationService into main SDK
-
-### Breaking Changes
-None. This release maintains full backward compatibility.
-
-### Migration Guide
-No migration required. All existing code will continue to work unchanged.
-
-To use the new ConsultationService:
-
-```typescript
-import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
-
-const zalo = new ZaloSDK({
-  appId: "your-app-id",
-  appSecret: "your-app-secret"
-});
-
-// Use consultation service
-await zalo.consultation.sendTextMessage(
-  accessToken,
-  { user_id: "user-id" },
-  { type: "text", text: "How can I help you?" }
-);
-
-// Or use quick methods
-await zalo.sendConsultationText(accessToken, "user-id", "Hello!");
-```
-
----
-
-## [1.1.1] - 2024-12-XX
-
-### Fixed
-- Bug fixes and stability improvements
-- Enhanced error handling
-- Documentation updates
-
-### Added
-- Additional webhook event types
-- Improved TypeScript definitions
-
----
-
-## [1.1.0] - 2024-11-XX
-
-### Added
-- Group Management Service
-- Article Management Service
-- Video Upload Service
-- Enhanced webhook handling
-- Comprehensive documentation
-
----
-
-## [1.0.0] - 2024-10-XX
-
-### Added
-- Initial release
-- Official Account API support
-- ZNS (Zalo Notification Service) support
-- Social API support
-- Authentication flow
-- Basic messaging capabilities
-- TypeScript support
-- Comprehensive error handling
-
-### Features
-- OAuth 2.0 authentication
-- Message sending (text, image, file, sticker)
-- User management
-- Template management
-- Quota monitoring
-- Webhook event handling
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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.6.0] - 2025-01-09
+
+### Added
+
+#### 🆕 POST Method for User List Retrieval
+- **New Method**: `postUserList()` in UserService for POST-based user list retrieval
+- **Same Endpoint**: Uses identical URL as `getUserList()` but with POST method
+- **Request Body**: Sends data via request body instead of URL parameters
+- **Full Feature Parity**: Supports all same parameters as GET method
+- **Type Safety**: Same TypeScript interfaces and response types
+
+#### 📚 Enhanced Documentation & Examples
+- **Comprehensive Example**: New `examples/user-list-post-example.ts` with detailed usage scenarios
+- **Method Comparison**: Examples comparing GET vs POST approaches
+- **Pagination Support**: Complete pagination examples using POST method
+- **Filter Demonstrations**: Examples with tags, followers, and interaction periods
+
+### Technical Details
+
+#### POST Method Features
+- **Endpoint**: `https://openapi.zalo.me/v3.0/oa/user/getlist` (same as GET)
+- **Method**: POST with JSON body data
+- **Parameters Support**:
+  - `offset`: Starting position for pagination
+  - `count`: Number of users to retrieve (max 50)
+  - `tag_name`: Filter by specific tag
+  - `last_interaction_period`: Filter by interaction timeframe
+  - `is_follower`: Filter by follower status
+- **Response Format**: Identical to GET method (`UserListResponse`)
+- **Error Handling**: Same comprehensive error handling as GET method
+
+#### Use Cases for POST Method
+- **Large Parameter Sets**: Better handling of complex filter combinations
+- **Request Body Preference**: When POST body is preferred over URL parameters
+- **API Consistency**: Matching backend API patterns that expect POST
+- **Future Extensibility**: Easier to extend with additional body parameters
+
+### Usage Examples
+
+#### Basic POST Method Usage
+```typescript
+import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
+
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret"
+});
+
+// POST method for user list
+const result = await zalo.user.postUserList(accessToken, {
+  offset: 0,
+  count: 20,
+  tag_name: "VIP_CUSTOMER",
+  is_follower: true
+});
+```
+
+#### Comparing GET vs POST Methods
+```typescript
+// GET method (existing)
+const getResult = await zalo.user.getUserList(accessToken, request);
+
+// POST method (new)
+const postResult = await zalo.user.postUserList(accessToken, request);
+
+// Results are identical
+console.log(getResult.total === postResult.total); // true
+```
+
+### Files Added/Modified
+
+#### New Files
+- `examples/user-list-post-example.ts` - Comprehensive POST method examples
+
+#### Modified Files
+- `src/services/user.service.ts` - Added `postUserList()` method and `postList` endpoint
+
+### Breaking Changes
+None. This release maintains full backward compatibility.
+
+### Migration Guide
+No migration required. The new `postUserList()` method is an additional option alongside the existing `getUserList()` method.
+
+Both methods provide identical functionality:
+- Use `getUserList()` for GET-based requests (existing behavior)
+- Use `postUserList()` for POST-based requests (new option)
+
+---
+
+## [1.5.0] - 2025-01-09
+
+### Added
+
+#### 🆕 OA Quality Information API
+- **New Method**: `getOAQuality()` in ZNSService for retrieving OA ZNS sending quality information
+- **Quality Metrics**: Support for current (48-hour) and 7-day quality assessment periods
+- **Quality Levels**: HIGH, MEDIUM, LOW, UNDEFINED quality level indicators
+- **Type Safety**: New `ZNSOAQualityInfo` interface for comprehensive type support
+
+#### 🔧 Enhanced URL Encoding
+- **Improved Encoding**: Added `encodeURIComponent` for JSON data in UserService API calls
+- **Better Compatibility**: Enhanced URL parameter handling for special characters
+- **API Reliability**: Improved data transmission reliability for complex JSON structures
+
+### Technical Details
+
+#### OA Quality Information Features
+- **Real-time Quality**: Get current OA ZNS sending quality (48-hour window)
+- **Historical Quality**: Get 7-day quality assessment for trend analysis
+- **Quality Indicators**:
+  - `HIGH`: Excellent sending quality
+  - `MEDIUM`: Average sending quality
+  - `LOW`: Poor sending quality
+  - `UNDEFINED`: Quality not determined (no ZNS sent in assessment period)
+
+#### URL Encoding Improvements
+- **JSON Parameter Encoding**: Proper encoding of JSON data in URL parameters
+- **Special Character Support**: Enhanced handling of special characters in API requests
+- **Cross-platform Compatibility**: Improved compatibility across different environments
+
+### Usage Examples
+
+#### OA Quality Information
+```typescript
+import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
+
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret"
+});
+
+// Get OA quality information
+const qualityInfo = await zalo.zns.getOAQuality(accessToken);
+console.log('Current Quality:', qualityInfo.data.oaCurrentQuality);
+console.log('7-day Quality:', qualityInfo.data.oa7dayQuality);
+```
+
+### Files Modified
+- `src/services/zns.service.ts` - Added getOAQuality() method
+- `src/types/zns.ts` - Added ZNSOAQualityInfo interface, updated quality types
+- `src/services/user.service.ts` - Enhanced URL encoding with encodeURIComponent
+
+### Breaking Changes
+None. This release maintains full backward compatibility.
+
+### Migration Guide
+No migration required. All existing code will continue to work unchanged.
+
+---
+
+## [1.2.0] - 2025-01-08
+
+### Added
+
+#### 🆕 ConsultationService - Customer Support Messaging
+- **New Service**: `ConsultationService` for sending customer support messages within 48-hour interaction window
+- **Text Messages**: Send consultation text messages with automatic validation (max 2000 characters)
+- **Image Messages**: Send consultation images for visual support and guides
+- **File Messages**: Send consultation file attachments (manuals, guides, documents)
+- **Sticker Messages**: Send consultation sticker messages for friendly interactions
+- **General Messages**: Send any type of consultation message with unified interface
+
+#### 📚 Documentation & Examples
+- **Comprehensive Guide**: New `docs/CONSULTATION_SERVICE.md` with detailed usage instructions
+- **Practical Examples**: New `examples/consultation-service-example.ts` with 6 real-world scenarios
+- **Smart Customer Support**: Example implementation of intelligent customer support bot
+- **Webhook Integration**: Complete webhook integration examples for consultation service
+- **Error Handling**: Detailed error handling and retry mechanism examples
+
+#### 🔧 SDK Integration
+- **Quick Access**: Available via `zalo.consultation` property
+- **Quick Methods**: Added `zalo.sendConsultationText()` and `zalo.sendConsultationImage()` convenience methods
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+- **Error Handling**: Enhanced error handling with `ZaloSDKError` for consultation-specific errors
+
+#### 📖 Documentation Updates
+- **README.md**: Updated with ConsultationService examples and documentation links
+- **SERVICES_ADDED.md**: Added detailed ConsultationService documentation
+- **Keywords**: Enhanced package keywords for better discoverability
+
+### Technical Details
+
+#### Consultation Service Features
+- **48-Hour Window**: Enforces Zalo's 48-hour interaction window for consultation messages
+- **Content Validation**: Automatic validation of message content and format
+- **Quota Management**: Built-in quota tracking and management
+- **Anti-Spam**: Follows Zalo's anti-spam guidelines and best practices
+- **Retry Logic**: Built-in retry mechanism for failed requests
+
+#### Usage Conditions
+- Messages must be sent within 48 hours of last user interaction
+- Content must be consultation/support related (no direct advertising)
+- User must have followed the OA and not blocked it
+- No daily limit but must follow anti-spam guidelines
+
+#### Integration Points
+- Seamless integration with existing webhook system
+- Compatible with all existing SDK features
+- Follows established SDK patterns and conventions
+- Full backward compatibility maintained
+
+### Examples Added
+
+1. **Basic Consultation**: Simple text message consultation
+2. **Image Support**: Sending images for visual guidance
+3. **File Attachments**: Sending documents and manuals
+4. **Smart Customer Support**: AI-powered customer support bot
+5. **Retry Mechanism**: Robust error handling and retry logic
+6. **Webhook Integration**: Complete webhook event handling
+
+### Files Added/Modified
+
+#### New Files
+- `src/services/consultation.service.ts` - Main ConsultationService implementation
+- `docs/CONSULTATION_SERVICE.md` - Comprehensive documentation
+- `examples/consultation-service-example.ts` - Practical examples
+- `CHANGELOG.md` - This changelog file
+
+#### Modified Files
+- `README.md` - Added ConsultationService documentation and examples
+- `SERVICES_ADDED.md` - Added ConsultationService details
+- `package.json` - Updated version, description, keywords, and scripts
+- `src/index.ts` - Export ConsultationService types and classes
+- `src/zalo-sdk.ts` - Integrated ConsultationService into main SDK
+
+### Breaking Changes
+None. This release maintains full backward compatibility.
+
+### Migration Guide
+No migration required. All existing code will continue to work unchanged.
+
+To use the new ConsultationService:
+
+```typescript
+import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
+
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret"
+});
+
+// Use consultation service
+await zalo.consultation.sendTextMessage(
+  accessToken,
+  { user_id: "user-id" },
+  { type: "text", text: "How can I help you?" }
+);
+
+// Or use quick methods
+await zalo.sendConsultationText(accessToken, "user-id", "Hello!");
+```
+
+---
+
+## [1.1.1] - 2024-12-XX
+
+### Fixed
+- Bug fixes and stability improvements
+- Enhanced error handling
+- Documentation updates
+
+### Added
+- Additional webhook event types
+- Improved TypeScript definitions
+
+---
+
+## [1.1.0] - 2024-11-XX
+
+### Added
+- Group Management Service
+- Article Management Service
+- Video Upload Service
+- Enhanced webhook handling
+- Comprehensive documentation
+
+---
+
+## [1.0.0] - 2024-10-XX
+
+### Added
+- Initial release
+- Official Account API support
+- ZNS (Zalo Notification Service) support
+- Social API support
+- Authentication flow
+- Basic messaging capabilities
+- TypeScript support
+- Comprehensive error handling
+
+### Features
+- OAuth 2.0 authentication
+- Message sending (text, image, file, sticker)
+- User management
+- Template management
+- Quota monitoring
+- Webhook event handling