@warriorteam/redai-zalo-sdk 1.12.0 → 1.12.1

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

@@ -5,63 +5,6 @@ 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.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
-
-#### Code Organization
-- **ENHANCED**: Exported helper functions từ main index.ts
-- **IMPROVED**: Type safety với proper TypeScript interfaces
-- **ADDED**: Comprehensive test coverage cho all helper functions
-
-#### Supported Event Types
-- **User Message Events** (12 types): `user_send_text`, `user_send_image`, etc.
-- **Group Message Events** (9 types): `user_send_group_text`, `user_send_group_image`, etc.
-- **OA to User Events** (7 types): `oa_send_text`, `oa_send_image`, etc.
-- **OA to Group Events** (10 types): `oa_send_group_text`, `oa_send_group_image`, etc.
-
-## [1.11.1] - 2025-01-11
-
-### 🔧 API IMPROVEMENTS
-
-#### Method Signature Enhancement
-- **IMPROVED**: `createOAAuthUrl()` method signature với better parameter order
-  - Changed from: `(redirectUri, state?, usePkce?, pkce?)`
-  - Changed to: `(redirectUri, state?, pkce?, usePkce?)`
-- **ENHANCED**: More intuitive API design với PKCE config trước usePkce flag
-- **UPDATED**: All examples và documentation để phù hợp với signature mới
-- **ADDED**: Comprehensive test coverage cho new signature
-
-#### Developer Experience
-- **IMPROVED**: Better IntelliSense support với clearer parameter ordering
-- **ENHANCED**: More logical API flow cho PKCE implementation
-
 ## [1.11.0] - 2025-01-11
 
 ### 🔐 SECURITY ENHANCEMENTS

package/README.md

@@ -584,39 +584,7 @@ const handlers: WebhookHandlers = {
 - **Anonymous Events** (4 types): Anonymous chat support
 - **Shop Events** (1 type): Order management
 
-### 🎯 Message Classification Helpers
-
-The SDK provides helper functions to easily classify webhook message events:
-
-```typescript
-import {
-  isUserMessageEvent,
-  isGroupMessageEvent,
-  isOAToUserMessageEvent,
-  isOAToGroupMessageEvent,
-  getMessageDirection,
-} from "@warriorteam/redai-zalo-sdk";
-
-function handleWebhook(event: WebhookEvent) {
-  if (isUserMessageEvent(event)) {
-    console.log("Message from individual user");
-  } else if (isGroupMessageEvent(event)) {
-    console.log("Message from group");
-  } else if (isOAToUserMessageEvent(event)) {
-    console.log("OA sent message to user");
-  } else if (isOAToGroupMessageEvent(event)) {
-    console.log("OA sent message to group");
-  }
-
-  // Or use the unified helper
-  const { direction, target, description } = getMessageDirection(event);
-  console.log(`${direction} message to ${target}: ${description}`);
-}
-```
-
-For complete webhook documentation, see:
-- **[Webhook Events Guide](./docs/WEBHOOK_EVENTS.md)** - Complete guide for all 70+ webhook event types
-- **[Message Classification Helpers](./docs/WEBHOOK_MESSAGE_HELPERS.md)** - Helper functions for message classification
+For complete webhook documentation, see [Webhook Events Guide](./docs/WEBHOOK_EVENTS.md).
 
 ## Changelog