@warriorteam/redai-zalo-sdk 1.28.1 → 1.30.0

package/examples/consultation-template-example.ts

@@ -0,0 +1,324 @@
+/**
+ * Ví dụ sử dụng ConsultationService.sendTemplateMessage()
+ * Gửi tin nhắn template tổng quát với elements và buttons
+ * 
+ * API Endpoint: https://openapi.zalo.me/v3.0/oa/message/cs
+ * Method: POST
+ * Content-Type: application/json
+ */
+
+import { 
+  ConsultationService, 
+  TemplateElement, 
+  TemplateButton,
+  TemplateAction 
+} from '../src/services/consultation.service';
+import { ZaloClient } from '../src/clients/zalo-client';
+
+// Khởi tạo service
+const zaloClient = new ZaloClient();
+const consultationService = new ConsultationService(zaloClient);
+
+const ACCESS_TOKEN = "your_access_token_here";
+const USER_ID = "2468458835296117922";
+
+/**
+ * Ví dụ 1: Template request_user_info cơ bản
+ */
+async function example1_BasicRequestUserInfo() {
+  try {
+    // Tạo elements (tối đa 5 phần tử)
+    const elements: TemplateElement[] = [
+      // Element đầu tiên PHẢI có subtitle
+      consultationService.createTemplateElement(
+        "OA Chatbot (Testing)",
+        "Đang yêu cầu thông tin từ bạn",
+        "https://developers.zalo.me/web/static/zalo.png",
+        consultationService.createUrlAction("https://developers.zalo.me/")
+      ),
+      // Các element sau có thể không có subtitle
+      consultationService.createTemplateElement(
+        "Liên hệ hỗ trợ",
+        undefined, // không có subtitle
+        "https://developers.zalo.me/web/static/zalo.png",
+        consultationService.createPhoneAction("84919018791")
+      )
+    ];
+
+    // Tạo buttons (tối đa 5 phần tử)
+    const buttons: TemplateButton[] = [
+      consultationService.createUrlButton("OPEN URL", "https://developers.zalo.me/"),
+      consultationService.createQueryShowButton("QUERY SHOW", "#callback_data"),
+      consultationService.createQueryHideButton("QUERY HIDE", "#callback_data"),
+      consultationService.createSmsButton("OPEN SMS", "84919018791", "alo"),
+      consultationService.createPhoneButton("OPEN PHONE", "84919018791")
+    ];
+
+    // Gửi template message
+    const result = await consultationService.sendTemplateMessage(
+      ACCESS_TOKEN,
+      USER_ID,
+      "request_user_info",
+      elements,
+      buttons
+    );
+
+    console.log("✅ Template message sent successfully:", result);
+    return result;
+
+  } catch (error) {
+    console.error("❌ Error sending template message:", error);
+    throw error;
+  }
+}
+
+/**
+ * Ví dụ 2: Template đơn giản chỉ có 1 element và 2 buttons
+ */
+async function example2_SimpleTemplate() {
+  try {
+    // Chỉ 1 element
+    const elements: TemplateElement[] = [
+      {
+        title: "Chào mừng bạn đến với dịch vụ của chúng tôi!",
+        subtitle: "Chúng tôi có thể hỗ trợ gì cho bạn?",
+        image_url: "https://example.com/welcome.png"
+      }
+    ];
+
+    // 2 buttons đơn giản
+    const buttons: TemplateButton[] = [
+      consultationService.createQueryShowButton("Tư vấn sản phẩm", "product_consultation"),
+      consultationService.createPhoneButton("Gọi hotline", "84919018791")
+    ];
+
+    const result = await consultationService.sendTemplateMessage(
+      ACCESS_TOKEN,
+      USER_ID,
+      "request_user_info",
+      elements,
+      buttons
+    );
+
+    console.log("✅ Simple template sent successfully:", result);
+    return result;
+
+  } catch (error) {
+    console.error("❌ Error sending simple template:", error);
+    throw error;
+  }
+}
+
+/**
+ * Ví dụ 3: Template không có buttons (chỉ elements)
+ */
+async function example3_ElementsOnly() {
+  try {
+    const elements: TemplateElement[] = [
+      {
+        title: "Thông báo quan trọng",
+        subtitle: "Hệ thống sẽ bảo trì từ 2:00 - 4:00 sáng ngày mai",
+        image_url: "https://example.com/maintenance.png",
+        default_action: {
+          type: "oa.open.url",
+          url: "https://example.com/maintenance-info"
+        }
+      },
+      {
+        title: "Liên hệ hỗ trợ khẩn cấp",
+        // Không có subtitle cho element thứ 2
+        default_action: {
+          type: "oa.open.phone",
+          payload: { phone_code: "84919018791" }
+        }
+      }
+    ];
+
+    // Không có buttons
+    const result = await consultationService.sendTemplateMessage(
+      ACCESS_TOKEN,
+      USER_ID,
+      "request_user_info",
+      elements
+      // buttons parameter bỏ qua
+    );
+
+    console.log("✅ Elements-only template sent successfully:", result);
+    return result;
+
+  } catch (error) {
+    console.error("❌ Error sending elements-only template:", error);
+    throw error;
+  }
+}
+
+/**
+ * Ví dụ 4: Template với tất cả loại buttons
+ */
+async function example4_AllButtonTypes() {
+  try {
+    const elements: TemplateElement[] = [
+      {
+        title: "Trung tâm hỗ trợ khách hàng",
+        subtitle: "Chọn hình thức liên hệ phù hợp với bạn",
+        image_url: "https://example.com/support.png"
+      }
+    ];
+
+    const buttons: TemplateButton[] = [
+      // URL button
+      {
+        title: "Xem FAQ",
+        type: "oa.open.url",
+        payload: { url: "https://example.com/faq" }
+      },
+      // Query show button
+      {
+        title: "Chat với tư vấn viên",
+        type: "oa.query.show",
+        payload: "start_chat_with_agent"
+      },
+      // Query hide button
+      {
+        title: "Gửi phản hồi",
+        type: "oa.query.hide",
+        payload: "send_feedback"
+      },
+      // SMS button
+      {
+        title: "Gửi SMS hỗ trợ",
+        type: "oa.open.sms",
+        payload: {
+          phone_code: "84919018791",
+          content: "Tôi cần hỗ trợ"
+        }
+      },
+      // Phone button
+      {
+        title: "Gọi hotline",
+        type: "oa.open.phone",
+        payload: { phone_code: "84919018791" }
+      }
+    ];
+
+    const result = await consultationService.sendTemplateMessage(
+      ACCESS_TOKEN,
+      USER_ID,
+      "request_user_info",
+      elements,
+      buttons
+    );
+
+    console.log("✅ All button types template sent successfully:", result);
+    return result;
+
+  } catch (error) {
+    console.error("❌ Error sending all button types template:", error);
+    throw error;
+  }
+}
+
+/**
+ * Ví dụ 5: Template với validation errors (để test)
+ */
+async function example5_ValidationErrors() {
+  try {
+    // Element với title quá dài (> 100 ký tự)
+    const invalidElements: TemplateElement[] = [
+      {
+        title: "A".repeat(101), // 101 ký tự - sẽ báo lỗi
+        subtitle: "This will cause validation error"
+      }
+    ];
+
+    await consultationService.sendTemplateMessage(
+      ACCESS_TOKEN,
+      USER_ID,
+      "request_user_info",
+      invalidElements
+    );
+
+  } catch (error) {
+    console.log("✅ Expected validation error caught:", error.message);
+  }
+
+  try {
+    // Element đầu tiên không có subtitle
+    const invalidElements2: TemplateElement[] = [
+      {
+        title: "Valid title",
+        // Thiếu subtitle cho element đầu tiên - sẽ báo lỗi
+      }
+    ];
+
+    await consultationService.sendTemplateMessage(
+      ACCESS_TOKEN,
+      USER_ID,
+      "request_user_info",
+      invalidElements2
+    );
+
+  } catch (error) {
+    console.log("✅ Expected validation error caught:", error.message);
+  }
+
+  try {
+    // Quá nhiều elements (> 5)
+    const tooManyElements: TemplateElement[] = Array(6).fill(null).map((_, i) => ({
+      title: `Element ${i + 1}`,
+      subtitle: i === 0 ? "Required subtitle for first element" : undefined
+    }));
+
+    await consultationService.sendTemplateMessage(
+      ACCESS_TOKEN,
+      USER_ID,
+      "request_user_info",
+      tooManyElements
+    );
+
+  } catch (error) {
+    console.log("✅ Expected validation error caught:", error.message);
+  }
+}
+
+// Chạy các ví dụ
+async function runExamples() {
+  console.log("🚀 Running Consultation Template Examples...\n");
+
+  try {
+    await example1_BasicRequestUserInfo();
+    console.log("\n");
+
+    await example2_SimpleTemplate();
+    console.log("\n");
+
+    await example3_ElementsOnly();
+    console.log("\n");
+
+    await example4_AllButtonTypes();
+    console.log("\n");
+
+    await example5_ValidationErrors();
+    console.log("\n");
+
+    console.log("✅ All examples completed!");
+
+  } catch (error) {
+    console.error("❌ Example failed:", error);
+  }
+}
+
+// Export để có thể import và sử dụng
+export {
+  example1_BasicRequestUserInfo,
+  example2_SimpleTemplate,
+  example3_ElementsOnly,
+  example4_AllButtonTypes,
+  example5_ValidationErrors,
+  runExamples
+};
+
+// Chạy nếu file được execute trực tiếp
+if (require.main === module) {
+  runExamples();
+}

package/examples/zns-validation-example.ts

@@ -0,0 +1,362 @@
+/**
+ * Ví dụ sử dụng ZNS Service với type validation rõ ràng
+ * 
+ * File này minh họa cách sử dụng các type cụ thể thay vì `any`
+ * trong ZNS Service để có type safety tốt hơn.
+ */
+
+import { ZNSService } from "../src/services/zns.service";
+import { ZaloClient } from "../src/clients/zalo-client";
+import {
+  ZNSCreateTemplateRequest,
+  ZNSValidationComponent,
+  ZNSTitleComponent,
+  ZNSParagraphComponent,
+  ZNSLogoComponent,
+  ZNSButtonsComponent,
+  ZNSPaymentComponent,
+  ZNSVoucherComponent,
+  ZNSRatingComponent,
+  ZNSAttachment,
+} from "../src/types/zns";
+
+// Khởi tạo service
+const zaloClient = new ZaloClient("your-app-id", "your-app-secret");
+const znsService = new ZNSService(zaloClient);
+
+// ===== VÍ DỤ 1: ZNS TÙY CHỈNH (Type 1) =====
+async function createCustomTemplate() {
+  // Định nghĩa các component với type cụ thể
+  const logoComponent: ZNSValidationComponent = {
+    LOGO: {
+      light: {
+        type: "IMAGE",
+        media_id: "logo-light-media-id"
+      },
+      dark: {
+        type: "IMAGE", 
+        media_id: "logo-dark-media-id"
+      }
+    }
+  };
+
+  const titleComponent: ZNSValidationComponent = {
+    TITLE: {
+      value: "Xin chào {{customer_name}}, đơn hàng của bạn đã được xác nhận!"
+    }
+  };
+
+  const paragraphComponent: ZNSValidationComponent = {
+    PARAGRAPH: {
+      value: "Cảm ơn bạn đã đặt hàng tại {{shop_name}}. Đơn hàng {{order_id}} sẽ được giao trong {{delivery_time}}."
+    }
+  };
+
+  const buttonsComponent: ZNSValidationComponent = {
+    BUTTONS: {
+      items: [
+        {
+          type: 1, // URL
+          title: "Xem đơn hàng",
+          content: "https://shop.com/orders/{{order_id}}"
+        },
+        {
+          type: 2, // Phone
+          title: "Liên hệ",
+          content: "0123456789"
+        }
+      ]
+    }
+  };
+
+  // Layout với type safety
+  const layout: ZNSValidationComponent[] = [
+    logoComponent,
+    titleComponent,
+    paragraphComponent,
+    buttonsComponent
+  ];
+
+  // Template request với type cụ thể
+  const templateRequest: ZNSCreateTemplateRequest = {
+    template_name: "Thông báo xác nhận đơn hàng",
+    template_type: 1, // ZNS tùy chỉnh
+    tag: "1", // Transaction
+    layout: layout,
+    params: [
+      {
+        name: "customer_name",
+        type: "1", // Tên khách hàng
+        sample_value: "Nguyễn Văn A"
+      },
+      {
+        name: "shop_name", 
+        type: "5", // Nhãn tùy chỉnh
+        sample_value: "Shop ABC"
+      },
+      {
+        name: "order_id",
+        type: "4", // Mã số
+        sample_value: "ORD123456"
+      },
+      {
+        name: "delivery_time",
+        type: "11", // Thời gian
+        sample_value: "2-3 ngày"
+      }
+    ],
+    note: "Template thông báo xác nhận đơn hàng cho khách hàng",
+    tracking_id: "custom-template-001"
+  };
+
+  try {
+    const result = await znsService.createTemplate("access-token", templateRequest);
+    console.log("Template created successfully:", result);
+  } catch (error) {
+    console.error("Error creating template:", error);
+  }
+}
+
+// ===== VÍ DỤ 2: ZNS PAYMENT (Type 3) =====
+async function createPaymentTemplate() {
+  const logoComponent: ZNSValidationComponent = {
+    LOGO: {
+      light: { type: "IMAGE", media_id: "logo-light" },
+      dark: { type: "IMAGE", media_id: "logo-dark" }
+    }
+  };
+
+  const titleComponent: ZNSValidationComponent = {
+    TITLE: {
+      value: "Thông báo thanh toán hóa đơn {{invoice_id}}"
+    }
+  };
+
+  const paymentComponent: ZNSValidationComponent = {
+    PAYMENT: {
+      bank_code: "970425", // VietinBank
+      account_name: "CÔNG TY ABC",
+      bank_account: "1234567890",
+      amount: "{{amount}}",
+      note: "Thanh toan hoa don {{invoice_id}}"
+    }
+  };
+
+  const layout: ZNSValidationComponent[] = [
+    logoComponent,
+    titleComponent,
+    paymentComponent
+  ];
+
+  const templateRequest: ZNSCreateTemplateRequest = {
+    template_name: "Thông báo yêu cầu thanh toán",
+    template_type: 3, // ZNS yêu cầu thanh toán
+    tag: "1", // Transaction
+    layout: layout,
+    params: [
+      {
+        name: "invoice_id",
+        type: "4", // Mã số
+        sample_value: "INV001"
+      },
+      {
+        name: "amount",
+        type: "14", // Tiền tệ VNĐ
+        sample_value: "500000"
+      }
+    ],
+    tracking_id: "payment-template-001"
+  };
+
+  try {
+    const result = await znsService.createTemplate("access-token", templateRequest);
+    console.log("Payment template created:", result);
+  } catch (error) {
+    console.error("Error creating payment template:", error);
+  }
+}
+
+// ===== VÍ DỤ 3: ZNS VOUCHER (Type 4) =====
+async function createVoucherTemplate() {
+  const imageComponent: ZNSValidationComponent = {
+    IMAGES: {
+      items: [
+        {
+          type: "IMAGE",
+          media_id: "voucher-image-media-id"
+        }
+      ]
+    }
+  };
+
+  const titleComponent: ZNSValidationComponent = {
+    TITLE: {
+      value: "🎉 Voucher giảm giá {{discount_percent}}% dành cho bạn!"
+    }
+  };
+
+  const voucherComponent: ZNSValidationComponent = {
+    VOUCHER: {
+      name: "Voucher giảm giá {{discount_percent}}%",
+      condition: "Áp dụng cho đơn hàng từ {{min_order}}đ",
+      end_date: "{{expiry_date}}",
+      voucher_code: "{{voucher_code}}",
+      display_code: 1 // QR code
+    }
+  };
+
+  const buttonsComponent: ZNSValidationComponent = {
+    BUTTONS: {
+      items: [
+        {
+          type: 1, // URL
+          title: "Sử dụng ngay",
+          content: "https://shop.com/voucher/{{voucher_code}}"
+        }
+      ]
+    }
+  };
+
+  const layout: ZNSValidationComponent[] = [
+    imageComponent,
+    titleComponent,
+    voucherComponent,
+    buttonsComponent
+  ];
+
+  const templateRequest: ZNSCreateTemplateRequest = {
+    template_name: "Thông báo voucher giảm giá",
+    template_type: 4, // ZNS voucher
+    tag: "3", // Promotion
+    layout: layout,
+    params: [
+      {
+        name: "discount_percent",
+        type: "10", // Số lượng/Số tiền
+        sample_value: "20"
+      },
+      {
+        name: "min_order",
+        type: "14", // Tiền tệ VNĐ
+        sample_value: "200000"
+      },
+      {
+        name: "expiry_date",
+        type: "11", // Thời gian
+        sample_value: "31/12/2024"
+      },
+      {
+        name: "voucher_code",
+        type: "4", // Mã số
+        sample_value: "SAVE20"
+      }
+    ],
+    tracking_id: "voucher-template-001"
+  };
+
+  try {
+    const result = await znsService.createTemplate("access-token", templateRequest);
+    console.log("Voucher template created:", result);
+  } catch (error) {
+    console.error("Error creating voucher template:", error);
+  }
+}
+
+// ===== VÍ DỤ 4: ZNS RATING (Type 5) =====
+async function createRatingTemplate() {
+  const logoComponent: ZNSValidationComponent = {
+    LOGO: {
+      light: { type: "IMAGE", media_id: "logo-light" },
+      dark: { type: "IMAGE", media_id: "logo-dark" }
+    }
+  };
+
+  const titleComponent: ZNSValidationComponent = {
+    TITLE: {
+      value: "Đánh giá trải nghiệm dịch vụ của {{service_name}}"
+    }
+  };
+
+  const ratingComponent: ZNSValidationComponent = {
+    RATING: {
+      items: [
+        {
+          star: 1,
+          title: "Rất không hài lòng",
+          question: "Chúng tôi có thể cải thiện điều gì?",
+          answers: ["Chất lượng dịch vụ", "Thái độ nhân viên", "Thời gian phục vụ"],
+          thanks: "Cảm ơn bạn đã góp ý!",
+          description: "Chúng tôi sẽ cải thiện dịch vụ tốt hơn"
+        },
+        {
+          star: 2,
+          title: "Không hài lòng", 
+          question: "Điều gì khiến bạn chưa hài lòng?",
+          answers: ["Chất lượng dịch vụ", "Giá cả", "Thời gian chờ"],
+          thanks: "Cảm ơn phản hồi của bạn!",
+          description: "Chúng tôi sẽ khắc phục những vấn đề này"
+        },
+        {
+          star: 3,
+          title: "Bình thường",
+          question: "Bạn mong muốn điều gì tốt hơn?",
+          answers: ["Dịch vụ nhanh hơn", "Chất lượng tốt hơn", "Giá cả hợp lý hơn"],
+          thanks: "Cảm ơn bạn đã đánh giá!",
+          description: "Chúng tôi sẽ nỗ lực cải thiện"
+        },
+        {
+          star: 4,
+          title: "Hài lòng",
+          question: "Điều gì bạn thích nhất?",
+          answers: ["Dịch vụ tốt", "Nhân viên thân thiện", "Chất lượng ổn"],
+          thanks: "Cảm ơn bạn đã tin tưởng!",
+          description: "Chúng tôi sẽ duy trì chất lượng này"
+        },
+        {
+          star: 5,
+          title: "Rất hài lòng",
+          question: "Bạn có muốn giới thiệu cho bạn bè?",
+          answers: ["Có, chắc chắn", "Có thể", "Sẽ suy nghĩ"],
+          thanks: "Cảm ơn bạn rất nhiều!",
+          description: "Chúng tôi rất vui khi được phục vụ bạn"
+        }
+      ]
+    }
+  };
+
+  const layout: ZNSValidationComponent[] = [
+    logoComponent,
+    titleComponent,
+    ratingComponent
+  ];
+
+  const templateRequest: ZNSCreateTemplateRequest = {
+    template_name: "Đánh giá dịch vụ khách hàng",
+    template_type: 5, // ZNS đánh giá dịch vụ
+    tag: "2", // Customer care
+    layout: layout,
+    params: [
+      {
+        name: "service_name",
+        type: "5", // Nhãn tùy chỉnh
+        sample_value: "Dịch vụ giao hàng"
+      }
+    ],
+    tracking_id: "rating-template-001"
+  };
+
+  try {
+    const result = await znsService.createTemplate("access-token", templateRequest);
+    console.log("Rating template created:", result);
+  } catch (error) {
+    console.error("Error creating rating template:", error);
+  }
+}
+
+// Export các function để sử dụng
+export {
+  createCustomTemplate,
+  createPaymentTemplate,
+  createVoucherTemplate,
+  createRatingTemplate
+};