@warriorteam/redai-zalo-sdk 1.21.0 → 1.23.0

package/examples/promotion-examples.ts

@@ -0,0 +1,407 @@
+import { PromotionService } from "../src/services/promotion.service";
+import { ZaloClient } from "../src/clients/zalo-client";
+
+/**
+ * Examples sử dụng Promotion Service với API v3.0
+ */
+
+// Khởi tạo service
+const client = new ZaloClient();
+const promotionService = new PromotionService(client);
+
+const ACCESS_TOKEN = "your_access_token_here";
+const USER_ID = "4356639876691778517";
+
+/**
+ * Example 1: Gửi promotion message theo format chuẩn docs v3.0
+ */
+export async function sendStandardPromotion() {
+  try {
+    const result = await promotionService.sendCustomPromotion(
+      ACCESS_TOKEN,
+      { user_id: USER_ID },
+      {
+        attachmentId: "aERC3A0iYGgQxim8fYIK6fxzsXkaFfq7ZFRB3RCyZH6RyziRis3RNydebK3iSPCJX_cJ3k1nW1EQufjN_pUL1f6Ypq3rTef5nxp6H_HnXKFDiyD5y762HS-baqRpQe5FdA376lTfq1sRyPr8ypd74ecbaLyA-tGmuJ-97W",
+        headerContent: "💥💥Ưu đãi thành viên Platinum💥💥",
+        textContent: "Ưu đãi dành riêng cho khách hàng Nguyen Van A hạng thẻ Platinum<br>Voucher trị giá 150$",
+        tableData: [
+          {
+            key: "Voucher",
+            value: "VC09279222"
+          },
+          {
+            key: "Hạn sử dụng", 
+            value: "30/12/2023"
+          }
+        ],
+        footerText: "Áp dụng tất cả cửa hàng trên toàn quốc",
+        buttons: [
+          {
+            title: "Tham khảo chương trình",
+            imageIcon: "",
+            type: "oa.open.url",
+            payload: {
+              url: "https://oa.zalo.me/home"
+            }
+          },
+          {
+            title: "Liên hệ chăm sóc viên",
+            imageIcon: "aeqg9SYn3nIUYYeWohGI1fYRF3V9f0GHceig8Ckq4WQVcpmWb-9SL8JLPt-6gX0QbTCfSuQv40UEst1imAm53CwFPsQ1jq9MsOnlQe6rIrZOYcrlWBTAKy_UQsV9vnfGozCuOvFfIbN5rcXddFKM4sSYVM0D50I9eWy3",
+            type: "oa.query.hide",
+            payload: "#tuvan" // String trực tiếp theo docs
+          }
+        ],
+        language: "VI"
+      }
+    );
+
+    console.log("Promotion sent successfully:", result);
+    return result;
+  } catch (error) {
+    console.error("Failed to send promotion:", error);
+    throw error;
+  }
+}
+
+/**
+ * Example 2: Gửi product promotion
+ */
+export async function sendProductPromotion() {
+  try {
+    const result = await promotionService.sendProductPromotion(
+      ACCESS_TOKEN,
+      { user_id: USER_ID },
+      {
+        title: "iPhone 15 Pro Max",
+        description: "Siêu phẩm công nghệ mới nhất từ Apple với chip A17 Pro mạnh mẽ",
+        attachmentId: "your_product_image_attachment_id",
+        originalPrice: 34990000,
+        discountPrice: 29990000,
+        discountPercent: 14,
+        validUntil: "31/12/2024",
+        productUrl: "https://example.com/iphone-15-pro-max"
+      }
+    );
+
+    console.log("Product promotion sent successfully:", result);
+    return result;
+  } catch (error) {
+    console.error("Failed to send product promotion:", error);
+    throw error;
+  }
+}
+
+/**
+ * Example 3: Gửi event notification
+ */
+export async function sendEventNotification() {
+  try {
+    const result = await promotionService.sendEventNotification(
+      ACCESS_TOKEN,
+      { user_id: USER_ID },
+      {
+        title: "Hội thảo Digital Marketing 2024",
+        description: "Khám phá xu hướng marketing số mới nhất và chiến lược tăng trưởng bền vững",
+        attachmentId: "your_event_image_attachment_id",
+        eventDate: "15/01/2024 - 9:00 AM",
+        location: "Trung tâm Hội nghị Quốc gia, Hà Nội",
+        registrationUrl: "https://example.com/register-event"
+      }
+    );
+
+    console.log("Event notification sent successfully:", result);
+    return result;
+  } catch (error) {
+    console.error("Failed to send event notification:", error);
+    throw error;
+  }
+}
+
+/**
+ * Example 4: Gửi newsletter
+ */
+export async function sendNewsletter() {
+  try {
+    const result = await promotionService.sendNewsletter(
+      ACCESS_TOKEN,
+      { user_id: USER_ID },
+      {
+        title: "Bản tin công nghệ tuần 52/2024",
+        summary: "Cập nhật những tin tức công nghệ hot nhất trong tuần qua",
+        attachmentId: "your_newsletter_image_attachment_id",
+        articles: [
+          {
+            title: "AI và tương lai của lập trình",
+            url: "https://example.com/ai-programming-future"
+          },
+          {
+            title: "Blockchain trong fintech",
+            url: "https://example.com/blockchain-fintech"
+          },
+          {
+            title: "IoT và smart city",
+            url: "https://example.com/iot-smart-city"
+          }
+        ],
+        unsubscribeUrl: "https://example.com/unsubscribe"
+      }
+    );
+
+    console.log("Newsletter sent successfully:", result);
+    return result;
+  } catch (error) {
+    console.error("Failed to send newsletter:", error);
+    throw error;
+  }
+}
+
+/**
+ * Example 5: Demo tất cả button types
+ */
+export async function sendAllButtonTypes() {
+  try {
+    const result = await promotionService.sendCustomPromotion(
+      ACCESS_TOKEN,
+      { user_id: USER_ID },
+      {
+        attachmentId: "your_attachment_id",
+        headerContent: "🔘 Demo tất cả button types",
+        textContent: "Thử nghiệm các loại button được hỗ trợ trong Zalo API v3.0",
+        tableData: [
+          { key: "Button types", value: "5 loại" },
+          { key: "Tính năng", value: "Chỉ trên Mobile" }
+        ],
+        buttons: [
+          {
+            title: "Mở URL",
+            type: "oa.open.url",
+            payload: { url: "https://developers.zalo.me/" }
+          },
+          {
+            title: "Query Show",
+            type: "oa.query.show",
+            payload: "#callback_show"
+          },
+          {
+            title: "Query Hide",
+            type: "oa.query.hide",
+            payload: "#callback_hide"
+          },
+          {
+            title: "Gửi SMS",
+            type: "oa.open.sms",
+            payload: {
+              content: "Xin chào từ Zalo OA",
+              phone_code: "84919018791"
+            }
+          },
+          {
+            title: "Gọi điện",
+            type: "oa.open.phone",
+            payload: { phone_code: "84919018791" }
+          }
+        ],
+        language: "VI"
+      }
+    );
+
+    console.log("All button types demo sent successfully:", result);
+    return result;
+  } catch (error) {
+    console.error("Failed to send all button types demo:", error);
+    throw error;
+  }
+}
+
+/**
+ * Example 6: Gửi promotion đến nhiều users với tracking
+ */
+export async function sendPromotionToMultipleUsers() {
+  try {
+    const userIds = [
+      "4356639876691778517",
+      "1234567890123456789",
+      "9876543210987654321",
+      "5555666677778888999"
+    ];
+
+    console.log(`🚀 Bắt đầu gửi promotion đến ${userIds.length} users...`);
+
+    const result = await promotionService.sendCustomPromotionToMultipleUsers(
+      ACCESS_TOKEN,
+      userIds,
+      {
+        attachmentId: "your_attachment_id",
+        headerContent: "🎉 Khuyến mãi đặc biệt cho bạn!",
+        textContent: "Ưu đãi độc quyền dành riêng cho khách hàng VIP. Nhanh tay đặt hàng để nhận ngay voucher giảm giá!",
+        tableData: [
+          { key: "Mã giảm giá", value: "SAVE50" },
+          { key: "Giảm giá", value: "50%" },
+          { key: "Hạn sử dụng", value: "31/12/2024" },
+          { key: "Áp dụng", value: "Tất cả sản phẩm" }
+        ],
+        footerText: "⏰ Ưu đãi có thời hạn - Đặt hàng ngay!",
+        buttons: [
+          {
+            title: "Mua ngay",
+            type: "oa.open.url",
+            payload: { url: "https://shop.example.com/sale" }
+          },
+          {
+            title: "Xem thêm ưu đãi",
+            type: "oa.query.hide",
+            payload: "#xemthem"
+          }
+        ],
+        language: "VI"
+      },
+      {
+        mode: "sequential", // Gửi tuần tự để tránh rate limit
+        delayMs: 2000, // Delay 2 giây giữa các tin
+        continueOnError: true, // Tiếp tục khi có lỗi
+
+        // Callback tracking progress
+        onProgress: (progress) => {
+          const percent = Math.round((progress.completed / progress.total) * 100);
+          const eta = progress.estimatedTimeRemaining
+            ? Math.round(progress.estimatedTimeRemaining / 1000)
+            : 0;
+
+          console.log(`📊 Progress: ${percent}% (${progress.completed}/${progress.total})`);
+          console.log(`✅ Thành công: ${progress.successful} | ❌ Thất bại: ${progress.failed}`);
+
+          if (progress.currentUserId) {
+            console.log(`🔄 Đang gửi đến user: ${progress.currentUserId}`);
+          }
+
+          if (eta > 0) {
+            console.log(`⏱️ Thời gian còn lại: ~${eta}s`);
+          }
+
+          console.log("---");
+        },
+
+        // Callback cho từng user hoàn thành
+        onUserComplete: (userResult) => {
+          if (userResult.success) {
+            console.log(`✅ Gửi thành công đến user ${userResult.userId}`);
+            console.log(`   Message ID: ${userResult.result?.message_id}`);
+          } else {
+            console.log(`❌ Gửi thất bại đến user ${userResult.userId}`);
+            console.log(`   Lỗi: ${userResult.error?.message}`);
+          }
+        }
+      }
+    );
+
+    // Kết quả cuối cùng
+    console.log("\n🎯 KẾT QUẢ CUỐI CÙNG:");
+    console.log(`📊 Tổng số users: ${result.total}`);
+    console.log(`✅ Thành công: ${result.successful}`);
+    console.log(`❌ Thất bại: ${result.failed}`);
+    console.log(`📈 Tỷ lệ thành công: ${result.successRate.toFixed(1)}%`);
+    console.log(`⏱️ Thời gian thực hiện: ${(result.executionTime / 1000).toFixed(1)}s`);
+    console.log(`🔄 Chế độ gửi: ${result.mode}`);
+
+    // Chi tiết lỗi (nếu có)
+    const failedResults = result.results.filter(r => !r.success);
+    if (failedResults.length > 0) {
+      console.log("\n❌ CHI TIẾT LỖI:");
+      failedResults.forEach(failed => {
+        console.log(`- User ${failed.userId}: ${failed.error?.message}`);
+      });
+    }
+
+    return result;
+  } catch (error) {
+    console.error("Failed to send promotion to multiple users:", error);
+    throw error;
+  }
+}
+
+/**
+ * Example 7: Gửi promotion song song (parallel mode)
+ */
+export async function sendPromotionParallel() {
+  try {
+    const userIds = ["user1", "user2", "user3"];
+
+    const result = await promotionService.sendCustomPromotionToMultipleUsers(
+      ACCESS_TOKEN,
+      userIds,
+      {
+        attachmentId: "your_attachment_id",
+        headerContent: "⚡ Flash Sale - Chỉ 1 giờ!",
+        textContent: "Giảm giá sốc 70% cho 100 khách hàng đầu tiên!",
+        tableData: [
+          { key: "Giảm giá", value: "70%" },
+          { key: "Thời gian", value: "1 giờ" }
+        ],
+        buttons: [
+          {
+            title: "Mua ngay",
+            type: "oa.open.url",
+            payload: { url: "https://flash-sale.example.com" }
+          }
+        ]
+      },
+      {
+        mode: "parallel", // Gửi song song để tối ưu tốc độ
+        continueOnError: true,
+        onProgress: (progress) => {
+          console.log(`⚡ Parallel sending: ${progress.completed}/${progress.total} completed`);
+        }
+      }
+    );
+
+    console.log(`⚡ Parallel sending completed in ${result.executionTime}ms`);
+    return result;
+  } catch (error) {
+    console.error("Failed to send parallel promotion:", error);
+    throw error;
+  }
+}
+
+/**
+ * Chạy tất cả examples
+ */
+export async function runAllExamples() {
+  console.log("=== Zalo Promotion API v3.0 Examples ===\n");
+
+  try {
+    console.log("1. Sending standard promotion...");
+    await sendStandardPromotion();
+    console.log("✅ Standard promotion sent\n");
+
+    console.log("2. Sending product promotion...");
+    await sendProductPromotion();
+    console.log("✅ Product promotion sent\n");
+
+    console.log("3. Sending event notification...");
+    await sendEventNotification();
+    console.log("✅ Event notification sent\n");
+
+    console.log("4. Sending newsletter...");
+    await sendNewsletter();
+    console.log("✅ Newsletter sent\n");
+
+    console.log("5. Sending all button types demo...");
+    await sendAllButtonTypes();
+    console.log("✅ All button types demo sent\n");
+
+    console.log("6. Sending promotion to multiple users...");
+    await sendPromotionToMultipleUsers();
+    console.log("✅ Multiple users promotion sent\n");
+
+    console.log("7. Sending promotion in parallel mode...");
+    await sendPromotionParallel();
+    console.log("✅ Parallel promotion sent\n");
+
+    console.log("🎉 All examples completed successfully!");
+  } catch (error) {
+    console.error("❌ Error running examples:", error);
+  }
+}
+
+// Uncomment để chạy examples
+// runAllExamples();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warriorteam/redai-zalo-sdk",
-  "version": "1.21.0",
-  "description": "Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account, ZNS, Consultation Service, Broadcast Service, Group Messaging with List APIs, Social APIs, Enhanced Article Management, and Message Sequence APIs with Real-time Tracking",
+  "version": "1.23.0",
+  "description": "Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account v3.0, ZNS, Consultation Service, Broadcast Service, Group Messaging with List APIs, Social APIs, Enhanced Article Management, Promotion Service v3.0 with Multiple Users Support, and Message Sequence APIs with Real-time Tracking",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -48,7 +48,22 @@
     "bulk-group-messaging",
     "group-notifications",
     "team-communication",
-    "group-automation"
+    "group-automation",
+    "promotion-service",
+    "promotion-v3",
+    "zalo-v3",
+    "banner-element",
+    "table-element",
+    "multi-language",
+    "button-actions",
+    "multiple-users",
+    "bulk-promotion",
+    "real-time-tracking",
+    "progress-callback",
+    "sequential-sending",
+    "parallel-sending",
+    "campaign-management",
+    "error-isolation"
   ],
   "author": "RedAI Team",
   "license": "MIT",