@warriorteam/redai-zalo-sdk 1.1.0 → 1.2.0

package/ARCHITECTURE.md

@@ -0,0 +1,265 @@
+# RedAI Zalo SDK Architecture
+
+## Overview
+
+RedAI Zalo SDK là một TypeScript SDK hoàn chỉnh cho các API của Zalo, được thiết kế với kiến trúc modular và type-safe.
+
+## Cấu trúc thư mục
+
+```
+redai-zalo-sdk/
+├── src/
+│   ├── types/           # Type definitions
+│   │   ├── common.ts    # Common types và interfaces
+│   │   ├── auth.ts      # Authentication types
+│   │   ├── oa.ts        # Official Account types
+│   │   ├── message.ts   # Message types
+│   │   └── webhook.ts   # Webhook types
+│   ├── clients/         # HTTP clients
+│   │   ├── base-client.ts    # Base HTTP client
+│   │   └── zalo-client.ts    # Zalo-specific client
+│   ├── services/        # Business logic services
+│   │   ├── auth.service.ts     # Authentication service
+│   │   ├── oa.service.ts       # Official Account service
+│   │   └── message.service.ts  # Message service
+│   ├── utils/           # Utility functions
+│   ├── index.ts         # Main export file
+│   └── zalo-sdk.ts      # Main SDK class
+├── examples/            # Usage examples
+├── dist/               # Build output
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Kiến trúc chính
+
+### 1. Layered Architecture
+
+SDK được thiết kế theo kiến trúc phân lớp:
+
+```
+┌─────────────────┐
+│   Main SDK      │  ← ZaloSDK class (public API)
+├─────────────────┤
+│   Services      │  ← Business logic (AuthService, OAService, MessageService)
+├─────────────────┤
+│   Clients       │  ← HTTP communication (BaseClient, ZaloClient)
+├─────────────────┤
+│   Types         │  ← Type definitions và interfaces
+└─────────────────┘
+```
+
+### 2. Core Components
+
+#### ZaloSDK (Main Class)
+- Entry point cho tất cả các chức năng
+- Khởi tạo và quản lý các services
+- Cung cấp quick methods cho các tác vụ phổ biến
+- Quản lý configuration và lifecycle
+
+#### BaseClient
+- HTTP client cơ bản với axios
+- Retry mechanism
+- Error handling
+- Request/response logging
+- File upload support
+
+#### ZaloClient
+- Extends BaseClient
+- Zalo-specific endpoints
+- API versioning support
+- OAuth và ZNS endpoint handling
+
+#### Services
+- **AuthService**: OAuth flows, token management
+- **OAService**: Official Account operations
+- **MessageService**: Message sending và file upload
+
+### 3. Type System
+
+#### Comprehensive Types
+- Tất cả API responses được type-safe
+- Union types cho message types
+- Enum cho constants
+- Generic types cho reusability
+
+#### Error Handling
+- Custom `ZaloSDKError` class
+- Structured error information
+- Error code mapping
+
+### 4. Configuration
+
+```typescript
+interface ZaloSDKConfig {
+  appId: string;
+  appSecret: string;
+  timeout?: number;
+  debug?: boolean;
+  apiBaseUrl?: string;
+  retry?: {
+    attempts?: number;
+    delay?: number;
+  };
+}
+```
+
+## Design Patterns
+
+### 1. Builder Pattern
+SDK configuration với default values và validation.
+
+### 2. Service Pattern
+Mỗi service chịu trách nhiệm cho một domain cụ thể.
+
+### 3. Factory Pattern
+Client creation và service initialization.
+
+### 4. Strategy Pattern
+Different authentication flows (OA vs Social).
+
+### 5. Observer Pattern
+Webhook event handling (planned).
+
+## Key Features
+
+### 1. Type Safety
+- Full TypeScript support
+- Comprehensive type definitions
+- Generic types cho flexibility
+- Union types cho message variants
+
+### 2. Error Handling
+- Structured error responses
+- Retry mechanism
+- Detailed error information
+- Error code mapping
+
+### 3. Authentication
+- OAuth 2.0 flows
+- PKCE support
+- Token refresh
+- Multiple auth scopes
+
+### 4. Extensibility
+- Modular architecture
+- Easy to add new services
+- Plugin-ready design
+- Custom request support
+
+### 5. Developer Experience
+- IntelliSense support
+- Comprehensive documentation
+- Usage examples
+- Debug logging
+
+## API Design Principles
+
+### 1. Consistency
+- Consistent naming conventions
+- Uniform error handling
+- Standard response formats
+
+### 2. Simplicity
+- Easy-to-use public API
+- Quick methods cho common tasks
+- Sensible defaults
+
+### 3. Flexibility
+- Low-level access khi cần
+- Custom request support
+- Configurable behavior
+
+### 4. Reliability
+- Retry mechanisms
+- Error recovery
+- Connection testing
+
+## Future Enhancements
+
+### 1. Additional Services
+- ZNS Service (Zalo Notification Service)
+- User Management Service
+- Group Management Service
+- Webhook Service
+
+### 2. Advanced Features
+- Rate limiting
+- Caching
+- Batch operations
+- Real-time subscriptions
+
+### 3. Developer Tools
+- CLI tools
+- Testing utilities
+- Mock server
+- Documentation generator
+
+## Testing Strategy
+
+### 1. Unit Tests
+- Service logic testing
+- Type validation
+- Error handling
+
+### 2. Integration Tests
+- API endpoint testing
+- Authentication flows
+- File upload/download
+
+### 3. E2E Tests
+- Complete workflows
+- Real API interactions
+- Error scenarios
+
+## Performance Considerations
+
+### 1. HTTP Optimization
+- Connection pooling
+- Request compression
+- Timeout management
+
+### 2. Memory Management
+- Efficient data structures
+- Stream processing cho large files
+- Garbage collection friendly
+
+### 3. Network Efficiency
+- Batch requests
+- Caching strategies
+- Retry with backoff
+
+## Security
+
+### 1. Token Management
+- Secure token storage
+- Automatic refresh
+- Token validation
+
+### 2. Request Security
+- HTTPS only
+- Request signing
+- Parameter validation
+
+### 3. Error Information
+- Sanitized error messages
+- No sensitive data in logs
+- Secure debugging
+
+## Deployment
+
+### 1. Package Distribution
+- NPM package
+- TypeScript declarations
+- Source maps
+
+### 2. Versioning
+- Semantic versioning
+- Backward compatibility
+- Migration guides
+
+### 3. Documentation
+- API documentation
+- Usage examples
+- Migration guides

package/CHANGELOG.md

@@ -0,0 +1,154 @@
+# 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.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

package/README.md

@@ -3,6 +3,7 @@
 A comprehensive TypeScript/JavaScript SDK for Zalo APIs, providing easy-to-use interfaces for:
 
 - **Official Account (OA) API** - Manage your Zalo Official Account
+- **Consultation Service** - Send customer support messages within 48-hour window
 - **Zalo Notification Service (ZNS)** - Send template-based notification messages
 - **Social API** - Access user social information and authentication
 - **Group Message Framework (GMF)** - Send messages to Zalo groups
@@ -25,9 +26,18 @@ A comprehensive TypeScript/JavaScript SDK for Zalo APIs, providing easy-to-use i
 ## Installation
 
 ```bash
-npm install redai-zalo-sdk
+npm install @warriorteam/redai-zalo-sdk
 ```
 
+## 📚 Documentation
+
+- **[Webhook Events Guide](./docs/WEBHOOK_EVENTS.md)** - Complete guide for all 70+ webhook event types
+- **[Architecture Overview](./ARCHITECTURE.md)** - SDK architecture and design patterns
+- **[Services Added](./SERVICES_ADDED.md)** - Detailed breakdown of all services and features
+- **[Group Management](./docs/GROUP_MANAGEMENT.md)** - Group messaging and management
+- **[Article Management](./docs/ARTICLE_MANAGEMENT.md)** - Content and article management
+- **[Consultation Service](./docs/CONSULTATION_SERVICE.md)** - Customer service messaging guide
+
 ## Development
 
 ### Build from source
@@ -52,7 +62,7 @@ npm run dev
 ### Initialize the SDK
 
 ```typescript
-import { ZaloSDK } from "redai-zalo-sdk";
+import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
 
 const zalo = new ZaloSDK({
   appId: "your-app-id",
@@ -311,6 +321,49 @@ For support and questions:
 - Create an issue on GitHub
 - Contact RedAI team
 
+### Consultation Service (Customer Support)
+
+```typescript
+// Send consultation text message
+await zalo.consultation.sendTextMessage(accessToken,
+  { user_id: "user-id" },
+  {
+    type: "text",
+    text: "Xin chào! Tôi có thể hỗ trợ gì cho bạn?"
+  }
+);
+
+// Send consultation image with guide
+await zalo.consultation.sendImageMessage(accessToken,
+  { user_id: "user-id" },
+  {
+    type: "image",
+    attachment: {
+      type: "image",
+      payload: {
+        url: "https://example.com/support-guide.jpg"
+      }
+    }
+  }
+);
+
+// Send file attachment for support
+await zalo.consultation.sendFileMessage(accessToken,
+  { user_id: "user-id" },
+  {
+    type: "file",
+    url: "https://example.com/manual.pdf",
+    filename: "User Manual.pdf",
+    attachment: {
+      type: "file",
+      payload: {
+        url: "https://example.com/manual.pdf"
+      }
+    }
+  }
+);
+```
+
 ### ZNS (Zalo Notification Service)
 
 ```typescript
@@ -430,6 +483,55 @@ const friends = await zalo.social.getFriendsList(accessToken);
 await zalo.social.postToTimeline(accessToken, "Hello from Zalo SDK!");
 ```
 
+## 🔔 Webhook Events
+
+The SDK provides comprehensive webhook event handling with **70+ event types**:
+
+```typescript
+import { WebhookHandlers } from "@warriorteam/redai-zalo-sdk";
+
+const handlers: WebhookHandlers = {
+  // User message events
+  user_send_text: async (event) => {
+    console.log("User sent:", event.message.text);
+  },
+
+  // Group events
+  user_send_group_audio: async (event) => {
+    console.log("Audio in group:", event.message.attachments[0].payload.url);
+  },
+
+  // ZNS events
+  change_template_status: async (event) => {
+    console.log("Template status:", event.status);
+  },
+
+  // Widget events
+  widget_interaction_accepted: async (event) => {
+    console.log("Widget accepted:", event.data.user_external_id);
+  },
+
+  // System events
+  permission_revoked: async (event) => {
+    console.log("Permission revoked by:", event.data.action_by);
+  },
+};
+```
+
+### Event Categories:
+
+- **User Message Events** (11 types): text, image, video, audio, file, sticker, gif, location, link, business card, reaction
+- **OA Message Events** (11 types): All message types + anonymous + template
+- **Group Events** (22 types): Create, join, admin, leave + all message types for both user and OA
+- **ZNS Events** (8 types): Quota, template, journey, delivery, status changes
+- **Widget Events** (2 types): Interaction accepted, sync failures
+- **System Events** (4 types): Permission, extension, user info, tags
+- **Call Events** (2 types): OA call user, user call OA
+- **Anonymous Events** (4 types): Anonymous chat support
+- **Shop Events** (1 type): Order management
+
+For complete webhook documentation, see [Webhook Events Guide](./docs/WEBHOOK_EVENTS.md).
+
 ## Changelog
 
 ### v1.0.0