@warriorteam/redai-zalo-sdk 1.1.0 → 1.1.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/README.md

@@ -25,9 +25,17 @@ 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
+
 ## Development
 
 ### Build from source
@@ -52,7 +60,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",
@@ -430,6 +438,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