@warriorteam/redai-zalo-sdk/dist/services/zns.service.d.ts

Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account v3.0, ZNS with Full Type Safety, Consultation Service, Broadcast Service, Group Messaging with List APIs, Social APIs, Enhanced Article Management, Promotion Service v3.0 with Multip

import { ZaloClient } from "../clients/zalo-client";
import { ZNSMessage, ZNSSendResult, ZNSTemplateList, ZNSTemplateDetails, ZNSCreateTemplateRequest, ZNSUpdateTemplateRequest, ZNSTemplateCreateEditResponse, ZNSUploadImageResult, ZNSHashPhoneMessage, ZNSDevModeMessage, ZNSRsaMessage, ZNSJourneyMessage, ZNSMessageStatusInfo, ZNSBatchMessageStatusResponse, ZNSQuotaInfo, ZNSAllowedContentTypes, ZNSTemplateSampleData, ZNSCustomerRatingResponse, ZNSOAQualityInfo } from "../types/zns";
export interface ZNSAllTemplateDetailsResult {
    error: number;
    message: string;
    data: Array<ZNSTemplateDetails["data"]>;
    metadata: {
        total: number;
    };
}
export interface ZNSOAGroupedTemplateDetails {
    accessToken: string;
    templates: Array<ZNSTemplateDetails["data"]>;
    total: number;
}
export interface ZNSMultiOAAllTemplateDetailsResult {
    error: number;
    message: string;
    data: ZNSOAGroupedTemplateDetails[];
}
/**
 * Service for Zalo Notification Service (ZNS)
 *
 * Requirements for using ZNS API:
 * - Official Account must be approved and have ZNS sending permission
 * - Valid Official Account access token
 * - ZNS template must be approved before use
 * - Recipient phone number must be in correct format and valid
 * - Template data must match defined parameters
 * - Comply with message quantity limits according to service package
 *
 * Reference: https://developers.zalo.me/docs/zalo-notification-service/
 */
export declare class ZNSService {
    private readonly client;
    private readonly endpoints;
    constructor(client: ZaloClient);
    /**
     * Send ZNS message
     * @param accessToken OA access token
     * @param message ZNS message data
     * @returns Send result
     */
    sendMessage(accessToken: string, message: ZNSMessage): Promise<ZNSSendResult>;
    /**
     * Send ZNS message with phone hash
     * @param accessToken OA access token
     * @param message ZNS message with hashed phone
     * @returns Send result
     */
    sendHashPhoneMessage(accessToken: string, message: ZNSHashPhoneMessage): Promise<ZNSSendResult>;
    /**
     * Send ZNS message in development mode
     * @param accessToken OA access token
     * @param message ZNS dev mode message
     * @returns Send result
     */
    sendDevModeMessage(accessToken: string, message: ZNSDevModeMessage): Promise<ZNSSendResult>;
    /**
     * Send ZNS message with RSA encryption
     * @param accessToken OA access token
     * @param message ZNS RSA message
     * @returns Send result
     */
    sendRsaMessage(accessToken: string, message: ZNSRsaMessage): Promise<ZNSSendResult>;
    /**
     * Send ZNS journey message
     * @param accessToken OA access token
     * @param message ZNS journey message
     * @returns Send result
     */
    sendJourneyMessage(accessToken: string, message: ZNSJourneyMessage): Promise<ZNSSendResult>;
    /**
     * Get ZNS message status
     * @param accessToken OA access token
     * @param messageId Message ID
     * @returns Message status info
     *
     * Response data:
     * - delivery_time: Thời gian thiết bị nhận được thông báo
     * - status: Trạng thái thông báo
     *   * -1: The message does not exist
     *   * 0: The message is pushed successfully to Zalo server but has not yet delivered to user's phone
     *   * 1: The message was delivered to the user's phone
     * - message: Mô tả trạng thái thông báo
     */
    getMessageStatus(accessToken: string, messageId: string): Promise<ZNSMessageStatusInfo>;
    /**
     * Get ZNS batch message status (custom implementation)
     * @param accessToken OA access token
     * @param messageIds Array of message IDs
     * @returns Batch message status info
     *
     * This is a custom implementation that calls the single message status API
     * multiple times to get status for multiple messages. Since Zalo API doesn't
     * provide a native batch endpoint, this method provides convenience by:
     * - Making concurrent API calls for better performance
     * - Handling errors gracefully (failed requests return error status)
     * - Returning consistent response format
     */
    getBatchMessageStatus(accessToken: string, messageIds: string[]): Promise<ZNSBatchMessageStatusResponse>;
    /**
     * Get ZNS quota information
     * @param accessToken OA access token
     * @returns Quota information
     *
     * Response data:
     * - dailyQuota: Số thông báo ZNS OA được gửi trong 1 ngày
     * - remainingQuota: Số thông báo ZNS OA được gửi trong ngày còn lại
     * - dailyQuotaPromotion: Số tin ZNS hậu mãi OA được gửi trong ngày (null từ 1/11)
     * - remainingQuotaPromotion: Số tin ZNS hậu mãi còn lại OA được gửi trong ngày (null từ 1/11)
     * - monthlyPromotionQuota: Số tin ZNS hậu mãi OA được gửi trong tháng
     * - remainingMonthlyPromotionQuota: Số tin ZNS hậu mãi còn lại OA được gửi trong tháng
     * - estimatedNextMonthPromotionQuota: Số tin ZNS hậu mãi dự kiến mà OA có thể gửi trong tháng tiếp theo
     */
    getQuotaInfo(accessToken: string): Promise<ZNSQuotaInfo>;
    /**
     * Get ZNS allowed content types
     * @param accessToken OA access token
     * @returns Allowed content types
     *
     * Response data:
     * - Mảng các loại nội dung mà OA có thể gửi:
     *   * "TRANSACTION": Giao dịch (cấp độ 1)
     *   * "CUSTOMER_CARE": Chăm sóc khách hàng (cấp độ 2)
     *   * "PROMOTION": Hậu mãi (cấp độ 3)
     * - Dựa theo chất lượng gửi ZNS của OA, Zalo sẽ tự động điều chỉnh loại nội dung OA được gửi
     */
    getAllowedContentTypes(accessToken: string): Promise<ZNSAllowedContentTypes>;
    /**
     * Get ZNS template list
     * @param accessToken OA access token
     * @param offset Offset for pagination (template được tạo gần nhất có thứ tự 0)
     * @param limit Limit for pagination (tối đa 100)
     * @param status Template status filter (optional)
     * @returns Template list
     *
     * Status values:
     * - 1: ENABLE templates
     * - 2: PENDING_REVIEW templates
     * - 3: REJECT templates
     * - 4: DISABLE templates
     * - undefined: All templates
     */
    getTemplateList(accessToken: string, offset?: number, limit?: number, status?: 1 | 2 | 3 | 4): Promise<ZNSTemplateList>;
    /**
     * Get ZNS template details
     * @param accessToken OA access token
     * @param templateId Template ID
     * @returns Template details
     *
     * Response data:
     * - templateId: ID của template
     * - templateName: Tên của template
     * - status: Trạng thái template (ENABLE, PENDING_REVIEW, DELETE, REJECT, DISABLE)
     * - reason: Lý do template có trạng thái hiện tại
     * - listParams: Danh sách các thuộc tính của template
     * - listButtons: Danh sách các buttons/CTAs của template
     * - timeout: Thời gian timeout của template
     * - previewUrl: Đường dẫn đến bản xem trước của template
     * - templateQuality: Chất lượng template (null từ 10/12)
     * - templateTag: Loại nội dung (TRANSACTION, CUSTOMER_CARE, PROMOTION)
     * - price: Đơn giá của template
     */
    getTemplateDetails(accessToken: string, templateId: string): Promise<ZNSTemplateDetails>;
    /**
     * Custom: Lấy tất cả template kèm thông tin chi tiết cho 1 accessToken
     * - Tự động phân trang để lấy đủ tổng số template
     * - Lấy chi tiết song song theo batch để tối ưu thời gian
     */
    getAllTemplatesWithDetails(accessToken: string, status?: 1 | 2 | 3 | 4): Promise<ZNSAllTemplateDetailsResult>;
    /**
     * Custom: Lấy tất cả template chi tiết cho nhiều accessToken (nhiều OA)
     * Đầu ra nhóm theo từng accessToken
     */
    getAllTemplatesWithDetailsByTokens(accessTokens: string[], status?: 1 | 2 | 3 | 4): Promise<ZNSMultiOAAllTemplateDetailsResult>;
    /**
     * Get ZNS template sample data
     * @param accessToken OA access token
     * @param templateId Template ID
     * @returns Template sample data
     *
     * Response data:
     * - Chứa tham số và dữ liệu mẫu của template
     * - Ví dụ: { "balance_debt": 2000, "due_date": "01/01/1970", "customer_name": "customer_name_sample" }
     */
    getTemplateSampleData(accessToken: string, templateId: string): Promise<ZNSTemplateSampleData>;
    /**
     * Get customer rating information
     * @param accessToken OA access token
     * @param templateId Template ID
     * @param fromTime Start time (timestamp in milliseconds)
     * @param toTime End time (timestamp in milliseconds)
     * @param offset Position of first rating to return
     * @param limit Maximum number of ratings to return
     * @returns Customer rating information
     *
     * Lưu ý:
     * - Chỉ có thể lấy thông tin đánh giá từ template đánh giá dịch vụ được tạo bởi ứng dụng
     * - Access token phải ứng với template ID được tạo bởi app và OA
     * - Thời gian theo định dạng timestamp (millisecond)
     */
    getCustomerRating(accessToken: string, templateId: string, fromTime: number, toTime: number, offset: number, limit: number): Promise<ZNSCustomerRatingResponse>;
    /**
     * Get OA ZNS sending quality information
     * @param accessToken OA access token
     * @returns OA quality information
     *
     * Response data:
     * - oaCurrentQuality: Chất lượng gửi ZNS trong 48 giờ gần nhất
     * - oa7dayQuality: Chất lượng gửi ZNS trong 7 ngày gần nhất
     *
     * Quality levels:
     * - HIGH: Mức độ chất lượng tốt
     * - MEDIUM: Mức độ chất lượng trung bình
     * - LOW: Mức độ chất lượng kém
     * - UNDEFINED: Chưa được xác định (OA không gửi ZNS trong khung thời gian đánh giá)
     */
    getOAQuality(accessToken: string): Promise<ZNSOAQualityInfo>;
    /**
     * Create ZNS template
     * @param accessToken OA access token
     * @param templateData Template creation data theo chuẩn Zalo API
     * @returns Created template response
     *
     * API: POST https://business.openapi.zalo.me/template/create
     */
    createTemplate(accessToken: string, templateData: ZNSCreateTemplateRequest): Promise<ZNSTemplateCreateEditResponse>;
    /**
     * Edit ZNS template (chỉnh sửa template có trạng thái REJECT)
     * @param accessToken OA access token
     * @param templateData Template edit data theo chuẩn Zalo API
     * @returns Edited template response
     *
     * Lưu ý:
     * - Chỉ có thể chỉnh sửa template có trạng thái REJECT
     * - Template sau khi chỉnh sửa sẽ chuyển về trạng thái PENDING_REVIEW
     * - Daily quota: 100 requests/ngày
     * - Cần quyền "Quản lý tài sản"
     *
     * API: POST https://business.openapi.zalo.me/template/edit
     */
    updateTemplate(accessToken: string, templateData: ZNSUpdateTemplateRequest): Promise<ZNSTemplateCreateEditResponse>;
    /**
     * Upload image for ZNS template
     * @param accessToken OA access token
     * @param imageFile Image file (Buffer or ReadableStream)
     * @param filename Filename with extension
     * @returns Upload result with media_id
     *
     * Lưu ý:
     * - Định dạng hỗ trợ: JPG, PNG
     * - Dung lượng tối đa: 500KB
     * - Hạn mức: 5000 ảnh/tháng/app
     * - Logo: PNG, 400x96px
     * - Hình ảnh: JPG/PNG, tỉ lệ 16:9
     * - Cần quyền "Quản lý tài sản"
     */
    uploadImage(accessToken: string, imageFile: Buffer | NodeJS.ReadableStream, filename?: string): Promise<ZNSUploadImageResult>;
    /**
     * Comprehensive validation for ZNS template request
     */
    private validateZNSTemplateRequest;
    /**
     * Validate basic required fields
     */
    private validateBasicFields;
    /**
     * Validate template_type and tag compatibility
     */
    private validateTemplateTypeTagCompatibility;
    /**
     * Validate layout structure based on template type
     */
    private validateLayoutStructure;
    /**
     * Check if component belongs to header
     */
    private isHeaderComponent;
    /**
     * Check if component belongs to body
     */
    private isBodyComponent;
    /**
     * Check if component belongs to footer
     */
    private isFooterComponent;
    /**
     * Validate custom template layout (type 1)
     */
    private validateCustomTemplateLayout;
    /**
     * Validate auth template layout (type 2)
     */
    private validateAuthTemplateLayout;
    /**
     * Validate payment template layout (type 3)
     */
    private validatePaymentTemplateLayout;
    /**
     * Validate voucher template layout (type 4)
     */
    private validateVoucherTemplateLayout;
    /**
     * Validate rating template layout (type 5)
     */
    private validateRatingTemplateLayout;
    /**
     * Validate individual component content
     */
    private validateComponent;
    /**
     * Validate TITLE component
     */
    private validateTitleComponent;
    /**
     * Validate PARAGRAPH component
     */
    private validateParagraphComponent;
    /**
     * Validate OTP component
     */
    private validateOTPComponent;
    /**
     * Validate TABLE component
     */
    private validateTableComponent;
    /**
     * Validate LOGO component
     */
    private validateLogoComponent;
    /**
     * Validate IMAGES component
     */
    private validateImagesComponent;
    /**
     * Validate BUTTONS component
     */
    private validateButtonsComponent;
    /**
     * Validate PAYMENT component
     */
    private validatePaymentComponent;
    /**
     * Validate VOUCHER component
     */
    private validateVoucherComponent;
    /**
     * Validate RATING component
     */
    private validateRatingComponent;
    /**
     * Validate attachment object
     */
    private validateAttachment;
    /**
     * Validate params array
     */
    private validateParams;
    private handleZNSError;
}
//# sourceMappingURL=zns.service.d.ts.map