@warriorteam/redai-zalo-sdk 1.21.0 → 1.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/CHANGELOG.md +109 -0
  2. package/dist/services/promotion.service.d.ts +62 -4
  3. package/dist/services/promotion.service.d.ts.map +1 -1
  4. package/dist/services/promotion.service.js +391 -44
  5. package/dist/services/promotion.service.js.map +1 -1
  6. package/dist/types/message.d.ts +78 -22
  7. package/dist/types/message.d.ts.map +1 -1
  8. package/docs/MULTIPLE_USERS_PROMOTION.md +210 -0
  9. package/docs/PROMOTION_API_V3_MIGRATION.md +320 -0
  10. package/examples/promotion-examples.ts +407 -0
  11. package/package.json +18 -3
package/CHANGELOG.md CHANGED
@@ -5,6 +5,115 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.23.0] - 2025-08-29
9
+
10
+ ### 🚀 NEW FEATURE - Multiple Users Promotion với Real-time Tracking
11
+
12
+ #### 🎯 Multiple Users Support
13
+ - **ADDED**: `sendCustomPromotionToMultipleUsers()` - Gửi promotion đến nhiều user IDs cùng lúc
14
+ - **DUAL MODES**: Sequential (tuần tự) và Parallel (song song) sending modes
15
+ - **SMART DEDUPLICATION**: Tự động loại bỏ user IDs trùng lặp
16
+ - **ERROR ISOLATION**: Lỗi của 1 user không ảnh hưởng các user khác
17
+
18
+ #### 📊 Real-time Tracking & Callbacks
19
+ - **PROGRESS TRACKING**: `onProgress` callback với real-time statistics
20
+ - **USER COMPLETION**: `onUserComplete` callback cho từng user hoàn thành
21
+ - **ESTIMATED TIME**: Tính toán thời gian còn lại (ETA) cho sequential mode
22
+ - **DETAILED METRICS**: Success rate, execution time, start/end timestamps
23
+
24
+ #### ⚡ Performance Optimization
25
+ - **SEQUENTIAL MODE**: Gửi tuần tự với delay tùy chỉnh để tránh rate limit
26
+ - **PARALLEL MODE**: Gửi song song để tối ưu tốc độ cho urgent campaigns
27
+ - **CONFIGURABLE DELAY**: Tùy chỉnh delay giữa các tin nhắn (default: 1000ms)
28
+ - **CONTINUE ON ERROR**: Option để tiếp tục khi gặp lỗi (default: true)
29
+
30
+ #### 🛡️ Enhanced Error Handling
31
+ - **INDIVIDUAL RESULTS**: Chi tiết kết quả success/failure cho từng user
32
+ - **ERROR DETAILS**: Thông tin lỗi cụ thể cho từng user thất bại
33
+ - **RESILIENT PROCESSING**: Campaign không bị dừng khi 1 user lỗi
34
+ - **COMPREHENSIVE LOGGING**: Detailed logging cho debugging và monitoring
35
+
36
+ ### 📊 NEW INTERFACES & TYPES
37
+
38
+ #### Multiple Promotion Types
39
+ - **ADDED**: `PromotionUserResult` - Kết quả cho từng user riêng biệt
40
+ - **ADDED**: `MultiplePromotionProgress` - Interface cho progress tracking
41
+ - **ADDED**: `MultiplePromotionResult` - Kết quả tổng thể campaign
42
+ - **ENHANCED**: Progress callback với detailed metrics và ETA
43
+
44
+ ### 📚 COMPREHENSIVE DOCUMENTATION & EXAMPLES
45
+
46
+ #### New Documentation
47
+ - **ADDED**: `docs/MULTIPLE_USERS_PROMOTION.md` - Hướng dẫn chi tiết multiple users
48
+ - **UPDATED**: `docs/PROMOTION_API_V3_MIGRATION.md` - Thêm multiple users examples
49
+ - **BEST PRACTICES**: Guidelines cho sequential vs parallel modes
50
+
51
+ #### Enhanced Examples
52
+ - **ADDED**: `sendPromotionToMultipleUsers()` - Sequential mode với full tracking
53
+ - **ADDED**: `sendPromotionParallel()` - Parallel mode example
54
+ - **EXAMPLES**: Real-time progress monitoring và error handling
55
+ - **EXAMPLES**: Performance metrics và success rate tracking
56
+
57
+ ### 🎯 USE CASES
58
+ - **Marketing Campaigns**: Gửi promotion đến danh sách khách hàng VIP
59
+ - **Flash Sales**: Thông báo urgent đến nhiều users cùng lúc
60
+ - **Event Notifications**: Gửi thông báo sự kiện đến attendees
61
+ - **Customer Segmentation**: Targeted promotions cho từng nhóm khách hàng
62
+
63
+ ---
64
+
65
+ ## [1.22.0] - 2025-08-29
66
+
67
+ ### 🚀 MAJOR UPDATE - Promotion Service v3.0
68
+
69
+ #### ⬆️ API Version Upgrade
70
+ - **UPGRADED**: Promotion Service từ v2.0 lên **v3.0** API
71
+ - **URL**: Cập nhật endpoint từ `/v2.0/oa/message/promotion` lên `/v3.0/oa/message/promotion`
72
+ - **BREAKING**: Cấu trúc message elements hoàn toàn mới, không tương thích ngược
73
+
74
+ #### 🏗️ New Message Elements Structure
75
+ - **BANNER**: Element với `attachment_id` hoặc `image_url`, type="banner"
76
+ - **HEADER**: Element với `content` và `align`, type="header" (tối đa 100 ký tự)
77
+ - **TEXT**: Element với `content` và `align`, type="text" (tối đa 1000 ký tự, tối đa 2 đoạn)
78
+ - **TABLE**: Element với `content` array, type="table" (tối đa 5 items, key ≤ 25 chars, value ≤ 100 chars)
79
+
80
+ #### 🔘 Enhanced Button System
81
+ - **PAYLOAD**: Hỗ trợ cả object và string tùy theo button type
82
+ - **TYPES**: `oa.open.url`, `oa.query.show`, `oa.query.hide`, `oa.open.sms`, `oa.open.phone`
83
+ - **VALIDATION**: Title tối đa 35 ký tự, tối đa 4 buttons
84
+ - **ICONS**: Hỗ trợ `image_icon` với URL/attachment_id/"default"
85
+
86
+ #### 🌐 Multi-language Support
87
+ - **LANGUAGE**: Thêm thuộc tính `language: "VI" | "EN"`
88
+ - **LOCALIZATION**: Nội dung mặc định tự động chuyển ngôn ngữ
89
+
90
+ #### 🆕 New Methods & Features
91
+ - **ADDED**: `sendCustomPromotion()` - Gửi promotion theo format chuẩn docs v3.0
92
+ - **ENHANCED**: `sendProductPromotion()` - Cập nhật với elements structure mới
93
+ - **ENHANCED**: `sendEventNotification()` - Cập nhật với table và text elements
94
+ - **ENHANCED**: `sendNewsletter()` - Cập nhật với banner và table elements
95
+ - **VALIDATION**: Nâng cao validation cho elements và buttons
96
+
97
+ #### 📚 Comprehensive Documentation & Examples
98
+ - **ADDED**: `docs/PROMOTION_API_V3_MIGRATION.md` - Hướng dẫn migration chi tiết
99
+ - **ADDED**: `examples/promotion-examples.ts` - Examples đầy đủ cho tất cả tính năng
100
+ - **EXAMPLES**: Demo 5 button types với payload format đúng
101
+ - **MIGRATION**: Breaking changes và checklist migration
102
+
103
+ #### 🛡️ Enhanced Validation & Error Handling
104
+ - **TIME**: Kiểm tra sending time (8:00-22:00)
105
+ - **ELEMENTS**: Validate structure và content length
106
+ - **BUTTONS**: Validate payload format theo từng type
107
+ - **ERRORS**: Error codes cụ thể cho từng violation
108
+
109
+ ### 🔧 BREAKING CHANGES
110
+ - **Elements Structure**: Hoàn toàn khác v2.0, cần migration
111
+ - **Button Payload**: Từ string thành object/string tùy type
112
+ - **Image Handling**: Ưu tiên `attachment_id` thay vì `image_url`
113
+ - **API URL**: Phải cập nhật từ v2.0 lên v3.0
114
+
115
+ ---
116
+
8
117
  ## [1.21.0] - 2025-08-29
9
118
 
10
119
  ### 🚀 NEW FEATURES
package/dist/services/promotion.service.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { ZaloClient } from "../clients/zalo-client";
2
- import { SendMessageResponse, PromotionMessage, MessageRecipient } from "../types/message";
2
+ import { SendMessageResponse, PromotionMessage, MessageRecipient, PromotionUserResult, MultiplePromotionProgress, MultiplePromotionResult } from "../types/message";
3
3
  /**
4
4
  * Service xử lý các API tin nhắn truyền thông/quảng cáo của Zalo Official Account
5
5
  *
@@ -62,7 +62,8 @@ export declare class PromotionService {
62
62
  sendProductPromotion(accessToken: string, recipient: MessageRecipient, promotionInfo: {
63
63
  title: string;
64
64
  description: string;
65
- imageUrl: string;
65
+ imageUrl?: string;
66
+ attachmentId?: string;
66
67
  originalPrice: number;
67
68
  discountPrice: number;
68
69
  discountPercent: number;
@@ -79,7 +80,8 @@ export declare class PromotionService {
79
80
  sendEventNotification(accessToken: string, recipient: MessageRecipient, eventInfo: {
80
81
  title: string;
81
82
  description: string;
82
- imageUrl: string;
83
+ imageUrl?: string;
84
+ attachmentId?: string;
83
85
  eventDate: string;
84
86
  location: string;
85
87
  registrationUrl: string;
@@ -94,18 +96,74 @@ export declare class PromotionService {
94
96
  sendNewsletter(accessToken: string, recipient: MessageRecipient, newsletterInfo: {
95
97
  title: string;
96
98
  summary: string;
97
- imageUrl: string;
99
+ imageUrl?: string;
100
+ attachmentId?: string;
98
101
  articles: Array<{
99
102
  title: string;
100
103
  url: string;
101
104
  }>;
102
105
  unsubscribeUrl: string;
103
106
  }): Promise<SendMessageResponse>;
107
+ /**
108
+ * Tạo promotion message theo format chuẩn v3.0 (như trong docs)
109
+ * @param accessToken Access token của Official Account
110
+ * @param recipient Thông tin người nhận
111
+ * @param promotionData Dữ liệu promotion
112
+ * @returns Thông tin tin nhắn đã gửi
113
+ */
114
+ sendCustomPromotion(accessToken: string, recipient: MessageRecipient, promotionData: {
115
+ attachmentId: string;
116
+ headerContent: string;
117
+ textContent: string;
118
+ tableData: Array<{
119
+ key: string;
120
+ value: string;
121
+ }>;
122
+ footerText?: string;
123
+ buttons: Array<{
124
+ title: string;
125
+ imageIcon?: string;
126
+ type: string;
127
+ payload: Record<string, any> | string;
128
+ }>;
129
+ language?: "VI" | "EN";
130
+ }): Promise<SendMessageResponse>;
104
131
  /**
105
132
  * Validate promotion message format
106
133
  * @param message Promotion message to validate
107
134
  */
108
135
  private validatePromotionMessage;
136
+ /**
137
+ * Gửi promotion message đến nhiều user_ids với callback tracking
138
+ * @param accessToken Access token của Official Account
139
+ * @param userIds Danh sách user IDs cần gửi
140
+ * @param promotionData Dữ liệu promotion
141
+ * @param options Tùy chọn gửi và tracking
142
+ * @returns Kết quả gửi đến tất cả users
143
+ */
144
+ sendCustomPromotionToMultipleUsers(accessToken: string, userIds: string[], promotionData: {
145
+ attachmentId: string;
146
+ headerContent: string;
147
+ textContent: string;
148
+ tableData: Array<{
149
+ key: string;
150
+ value: string;
151
+ }>;
152
+ footerText?: string;
153
+ buttons: Array<{
154
+ title: string;
155
+ imageIcon?: string;
156
+ type: string;
157
+ payload: Record<string, any> | string;
158
+ }>;
159
+ language?: "VI" | "EN";
160
+ }, options?: {
161
+ mode?: "sequential" | "parallel";
162
+ delayMs?: number;
163
+ onProgress?: (progress: MultiplePromotionProgress) => void;
164
+ onUserComplete?: (result: PromotionUserResult) => void;
165
+ continueOnError?: boolean;
166
+ }): Promise<MultiplePromotionResult>;
109
167
  /**
110
168
  * Validate sending time (8:00 - 22:00)
111
169
  */
package/dist/services/promotion.service.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"promotion.service.d.ts","sourceRoot":"","sources":["../../src/services/promotion.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,gBAAgB;IAIf,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CACsB;gBAEzB,MAAM,EAAE,UAAU;IAE/C;;;;;;OAMG;IACU,oBAAoB,CAC/B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,mBAAmB,CAAC;IAyC/B;;;;;;OAMG;IACU,oBAAoB,CAC/B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,gBAAgB,EAC3B,aAAa,EAAE;QACb,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;KACpB,GACA,OAAO,CAAC,mBAAmB,CAAC;IA6C/B;;;;;;OAMG;IACU,qBAAqB,CAChC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,gBAAgB,EAC3B,SAAS,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,MAAM,CAAC;KACzB,GACA,OAAO,CAAC,mBAAmB,CAAC;IA6C/B;;;;;;OAMG;IACU,cAAc,CACzB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,gBAAgB,EAC3B,cAAc,EAAE;QACd,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,KAAK,CAAC;YACd,KAAK,EAAE,MAAM,CAAC;YACd,GAAG,EAAE,MAAM,CAAC;SACb,CAAC,CAAC;QACH,cAAc,EAAE,MAAM,CAAC;KACxB,GACA,OAAO,CAAC,mBAAmB,CAAC;IAyC/B;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAoBhC;;OAEG;IACH,OAAO,CAAC,mBAAmB;CAW5B"}
1
+ {"version":3,"file":"promotion.service.d.ts","sourceRoot":"","sources":["../../src/services/promotion.service.ts"],"names":[],"mappings":"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"}