zmp-sdk 2.52.2 → 2.53.1

package/index.d.ts

@@ -1426,6 +1426,84 @@ type GetZPITokenReturns = {
     zpp: string;
     zpt: string;
 };
+type VoucherDisplayType = "qr_code" | "bar_code";
+type VoucherActionType = "url" | "phone";
+type VoucherAction = {
+    /**
+     * Loại CTA hiển thị trên thẻ voucher.
+     */
+    type: VoucherActionType;
+    /**
+     * URL khi `type=url`, hoặc số điện thoại khi `type=phone`.
+     */
+    value: string;
+    /**
+     * Nội dung hiển thị trên button CTA; tối đa 15 ký tự.
+     */
+    cta: string;
+};
+type AddVoucherData = {
+    /**
+     * Tên voucher / ưu đãi.
+     */
+    name: string;
+    /**
+     * Điều kiện áp dụng (chính), hiển thị trên chi tiết vé; tối đa 75 ký tự.
+     */
+    condition: string;
+    /**
+     * Điều kiện áp dụng chi tiết (phụ).
+     */
+    conditionDetail?: string;
+    /**
+     * Thời gian bắt đầu hiệu lực, epoch milliseconds.
+     */
+    validAt?: number;
+    /**
+     * Hạn sử dụng, epoch milliseconds.
+     */
+    expiredAt: number;
+    /**
+     * Mã voucher; không truyền thì tự sinh QR OA của merchant.
+     */
+    code?: string;
+    /**
+     * Loại mã hiển thị. Mặc định là `qr_code`.
+     */
+    display?: VoucherDisplayType;
+    /**
+     * Token để merchant gửi tin nhắn không tốn phí. Lấy từ callback
+     * `onDataReceived` của `showFunctionButtonWidget`.
+     */
+    interactToken?: string;
+    /**
+     * Tên khách hàng sở hữu; không truyền thì không hiển thị trên vé.
+     */
+    ownerName?: string;
+    /**
+     * OA ID của merchant trên Zalo.
+     */
+    merchantOaId: string;
+    /**
+     * Tên OA / thương hiệu phát hành voucher.
+     */
+    merchantName: string;
+    /**
+     * Logo OA, dùng làm logo hiển thị trên voucher.
+     */
+    merchantLogoUrl: string;
+    /**
+     * Danh sách CTA hiển thị trên thẻ (tối đa 2).
+     */
+    actions?: VoucherAction[];
+};
+type AddVoucherReturns = {
+    /**
+     * Token để merchant gửi tin nhắn OA cho người dùng; chuỗi rỗng nếu server
+     * không trả về.
+     */
+    oaMessageToken: string;
+};
 type TempFile = {
     /**
      * Đường dẫn các temp file đã chọn.
@@ -3319,16 +3397,20 @@ declare const openProfileArgs: ZodOptional<ZodObject<{
 /**
  * API cho phép ứng dụng mở profile của User hoặc Official Account.
  *
+ * Với `oa` và `aliasOA`, màn hình được mở phụ thuộc trạng thái quan tâm của
+ * người dùng với OA đó: chưa quan tâm thì mở profile OA, đã quan tâm thì mở
+ * cửa sổ chat.
+ *
  * @minimumVersion 2.5.3
  * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
  *
  * @param {"user" | "oa" | "aliasOA"} type Nhận các giá trị sau:
  * - `user`: Mở profile User.
- * - `oa`: Mở profile OA.
- * - `aliasOA`: Mở profile OA bằng Alias (field id truyền lên là alias của OA).
+ * - `oa`: Mở profile OA, hoặc cửa sổ chat nếu người dùng đã quan tâm OA.
+ * - `aliasOA`: Như `oa`, nhưng field id truyền lên là alias của OA.
  * @param {string} id Id của User hoặc OA.
  *
- * @example Mở cửa sổ chat với người dùng:
+ * @example Mở profile của người dùng:
  * ```ts
  * await openProfile({
  *   type: "user",
@@ -3336,7 +3418,7 @@ declare const openProfileArgs: ZodOptional<ZodObject<{
  * });
  * ```
  *
- * @example Mở profile của Official Account:
+ * @example Mở Official Account (profile hoặc cửa sổ chat, tuỳ trạng thái user có quan tâm hay chưa):
  * ```tsx
  * await openProfile({
  *   type: "oa",
@@ -3500,7 +3582,7 @@ declare const openPostFeedArgs: ZodUnion<[ZodObject<{
  * const { status, shareType, numberOfUser } = await openPostFeed({
  *   type: "image",
  *   data: {
- *     imageUrls: ["link-to-image"],
+ *     imageUrls: ["https://example.com/image.jpg"],
  *   },
  * });
  * ```
@@ -3512,7 +3594,7 @@ declare const openPostFeedArgs: ZodUnion<[ZodObject<{
  *   data: {
  *     link: "http://news.zing.vn/Trung-uong-quyet-dinh-phuong-an-nhan-su-cap-cao-post632739.html",
  *     title: "Trung ương quyết định phương án nhân sự cấp cao",
- *     thumb: "link-to-thumb",
+ *     thumb: "https://example.com/thumbnail.jpg",
  *     description: "description",
  *   },
  * });
@@ -5271,6 +5353,73 @@ declare function requestSendNotification(args?: AsyncVoidCallback): Promise<void
  */
 declare function addRating(args?: AsyncVoidCallback): Promise<void>;
 
+/**
+ * Lưu voucher vào Ví QR của người dùng.
+ *
+ * API này gửi dữ liệu voucher từ Mini App về server trung gian. Server trung gian
+ * chịu trách nhiệm đăng nhập Ví QR, mã hoá dữ liệu bằng `secureKey`, sau đó trả về
+ * deeplink thêm thẻ vào Ví QR. SDK sẽ tự mở deeplink này bằng `openWebview` để đưa
+ * người dùng tới màn hình thêm thẻ; deeplink không được trả về cho bên gọi, chỉ
+ * trả về `oaMessageToken`.
+ *
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {string} name Tên voucher / ưu đãi.
+ * @param {string} condition Điều kiện áp dụng (chính), hiển thị trên chi tiết vé;
+ * tối đa 75 ký tự.
+ * @param {number} expiredAt Hạn sử dụng, epoch milliseconds.
+ * @param {string} merchantOaId OA ID của merchant trên Zalo.
+ * @param {string} merchantName Tên OA / thương hiệu phát hành voucher.
+ * @param {string} merchantLogoUrl Logo OA, dùng làm logo hiển thị trên voucher.
+ * @param {string} [conditionDetail] Điều kiện áp dụng chi tiết (phụ).
+ * @param {number} [validAt] Thời gian bắt đầu hiệu lực, epoch milliseconds.
+ * @param {string} [code] Mã voucher; không truyền thì tự sinh QR OA của merchant.
+ * @param {"qr_code" | "bar_code"} [display="qr_code"] Loại mã hiển thị.
+ * @param {string} [ownerName] Tên khách hàng sở hữu; không truyền thì không hiển thị trên vé.
+ * @param {string} [interactToken] Token để merchant gửi tin nhắn không tốn phí.
+ * Lấy từ callback `onDataReceived` của {@link showFunctionButtonWidget} khi
+ * người dùng nhấn vào Function Button Widget.
+ * @param {VoucherAction[]} [actions] Danh sách CTA hiển thị trên thẻ (tối đa 2);
+ * nội dung button (`cta`) tối đa 15 ký tự.
+ *
+ * @returns {Promise<AddVoucherReturns>} Promise resolve khi tạo thẻ thành công và
+ * deeplink đã được mở, trả về `oaMessageToken` (chuỗi rỗng nếu server không
+ * trả về); reject kèm mã lỗi từ server nếu thất bại.
+ *
+ * @example Thêm voucher vào Ví QR:
+ * ```ts
+ * await addVoucher({
+ *   name: "Giảm 50% giá trị đơn hàng",
+ *   condition: "Áp dụng cho hóa đơn trên 200.000đ",
+ *   expiredAt: 1743440399000,
+ *   merchantOaId: "2646373759294038927",
+ *   merchantName: "The Face Shop",
+ *   merchantLogoUrl: "https://static.example.com/logo.png",
+ * });
+ * ```
+ *
+ * @example Gửi kèm `interactToken` lấy từ Function Button Widget:
+ * ```ts
+ * showFunctionButtonWidget({
+ *   id: "orderButton",
+ *   type: "ORDER",
+ *   text: "Tạo đơn hàng",
+ *   onDataReceived: async (interactToken) => {
+ *     await addVoucher({
+ *       name: "Giảm 50% giá trị đơn hàng",
+ *       condition: "Áp dụng cho hóa đơn trên 200.000đ",
+ *       expiredAt: 1743440399000,
+ *       merchantOaId: "2646373759294038927",
+ *       merchantName: "The Face Shop",
+ *       merchantLogoUrl: "https://static.example.com/logo.png",
+ *       interactToken,
+ *     });
+ *   },
+ * });
+ * ```
+ */
+declare function addVoucher(args: AsyncCallback<AddVoucherReturns> & AddVoucherData): Promise<AddVoucherReturns>;
+
 declare const interactOAArgs$1: ZodObject<{
     oaId: ZodString;
 }, "strip", ZodTypeAny, {
@@ -5789,7 +5938,8 @@ type ShowFunctionButtonWidgetArgs = Omit<ShowFunctionButtonWidgetValidatedArgs,
     onError?: FunctionButtonWidgetOnError;
 };
 /**
- * Widget Function Button: Khi người dùng nhấn vào button này, Mini App sẽ nhận được 1 interact token để Merchant Server gửi kèm khi gọi Checkout SDK updateOrderStatus (https://mini.zalo.me/documents/checkout-sdk/updateOrderStatus/).
+ * Widget Function Button: Khi người dùng nhấn vào button này, Mini App sẽ nhận được 1 interact token (có giá trị trong 1 giờ).
+ * Từ phiên bản `2.52.2` trở lên, `showFunctionButtonWidget` hỗ trợ hiển thị nhiều Widget Function Button trên cùng một trang; mỗi widget cần một element có `id` riêng biệt.
  *
  * @minimumVersion 2.39.0
  * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
@@ -5814,7 +5964,7 @@ type ShowFunctionButtonWidgetArgs = Omit<ShowFunctionButtonWidgetValidatedArgs,
  * @param {string} [color="#0068FF"] Màu chủ đạo của widget. Giá trị phải là chuỗi hex.
  * @param {string} [textColor="#FFFFFF"] Màu chữ trong button. Giá trị phải là chuỗi hex.
  * @param {string} [borderRadius="48px"] Bo góc (bo tròn các góc của button).
- * @param {(interactToken: string, type: string, context: { callAction: (actionName: string, actionData: any) => void }) => void} [onDataReceived] Callback được gọi khi người dùng nhấn vào widget. Callback này chứa `interactToken` để Merchant Server gửi kèm khi gọi Checkout SDK updateOrderStatus (https://mini.zalo.me/documents/checkout-sdk/updateOrderStatus/).
+ * @param {(interactToken: string, type: string, context: { callAction: (actionName: string, actionData: any) => void }) => void} [onDataReceived] Callback được gọi khi người dùng nhấn vào widget. Callback nhận `interactToken` có giá trị trong 1 giờ, loại widget `type` và `context` chứa hàm `callAction(actionName, actionData)`.
  * @param {(error: AppError) => void} [onError] Callback được gọi khi có lỗi xảy ra khi người dùng nhấn vào widget. Callback này chứa `error` là thông tin về lỗi.
  *
  * @example Hiển thị Widget Function Button:
@@ -5831,7 +5981,7 @@ type ShowFunctionButtonWidgetArgs = Omit<ShowFunctionButtonWidgetValidatedArgs,
  *       color: "#0068FF",
  *       textColor: "#FFFFFF",
  *       borderRadius: "48px",
- *       onDataReceived: (interactToken, type) => {
+ *       onDataReceived: (interactToken) => {
  *         console.log(interactToken);
  *       },
  *       onError: (error) => {
@@ -6221,6 +6371,7 @@ declare const otherApis: {
     openGroupList: typeof openGroupList;
     requestSendNotification: typeof requestSendNotification;
     addRating: typeof addRating;
+    addVoucher: typeof addVoucher;
     interactOA: typeof interactOA;
     interactOa: typeof interactOA;
     isAllowedInteractWithOA: typeof checkIsAllowedInteractWithOA;
@@ -6287,4 +6438,4 @@ declare const otherApis: {
     ZMACameraImp: typeof ZMACameraImp;
 };
 
-export { Action, AndroidBottomNavigationBarType, AppError, AsyncCallback, AsyncCallbackFailObject, AsyncProgressCallback, AsyncVoidCallback, AuthorizeType, CameraEvents, CameraParams, ChatType, CheckStateBioAuthenticationReturns, CheckTransactionReturns, CheckZaloCameraPermissionReturns, CheckoutKit, CheckoutPopupOpenParams, CheckoutPopupResponseData, CheckoutSDK, ChooseImageReturns, Common, ContextInfo, CreateOrderIAPReturns, CreateOrderReturns, Events as EventName, Events, FacingMode, FileInfo, FunctionProps, GetAppInfoReturns, GetAuthCodeReturns, GetBeaconDiscoveryReturns, GetDeviceInfoReturn, GetFileInfoReturns, GetLocationReturns, GetNetworkTypeReturns, GetPhoneNumberReturns, GetSettingReturn, GetStorageReturns, GetUserInfoReturns, GetZPITokenReturns, IAPMethodType, IAPPayType, IAPPayTypeType, IOSSafeAreaBottomType, IsSupportReturns, JumpStatus, KeepScreenReturns, LFSStorage, ListFile, LogData, MediaConstraints, MediaDevice, MediaPickerType, NativeCallBackData, NetworkType, OpenBioAuthenticationReturns, OpenMediaPickerReturns, OpenPostFeedReturns, OpenProfilePickerReturns, OpenProfilePickerType, OpenShareSheetReturns, OpenWebviewReturns, OrientationType, Payment, PhotoConstraint, PhotoFormat, PhotoFrame, PhotoQuality, PickAttr, PickedProfile, PlatformType, PostFeedType, ProfileInfo, ProfileType, ProrationMode, ProrationModeType, RemoveStorageReturns, RequestCameraPermissionReturns, SaveFileReturns, ScanNFCType, ScanQRCodeReturns, SelectPaymentMethodReturns, SetStorageReturns, ShareSheetType, StatusBarType, StorageInfo, StreamType, SystemInfo, TempFile, TextAlignType, UserInfo, VibrateType, ZMACamera, ZMACameraImp, addRating, authorize, checkNFC, checkStateBioAuthentication, checkTransaction, checkZaloCameraPermission, chooseImage, clearStorage, closeApp, closeLoading, configAppView, connectWifi, createCameraContext, createOrder, createOrderIAP, createShortcut, otherApis as default, displayAd, downloadFile, events, favoriteApp, followOA, getAccessToken, getAppInfo, getAuthCode, getBeacons, getContext, getContextAsync, getDeviceId, getDeviceIdAsync, getDeviceInfo, getEntrySource, getIDToken, getLocation, getNetworkType, getPhoneNumber, getRouteParams, getSetting, getShareableLink, getStorage, getStorageInfo, getSystemInfo, getUserID, getUserInfo, getVersion, getZPIToken, hideKeyboard, iBeaconInfo, interactOA, interactOA as interactOa, checkIsAllowedInteractWithOA as isAllowedInteractWithOA, keepScreen, loadAd, login, minimizeApp, nativeStorage, offConfirmToExit, offKeepScreen, onCallbackData, onConfirmToExit, onKeepScreen, onNetworkStatusChange, openBioAuthentication, openChat, openDocument, openGroupList, openMediaPicker, openMiniApp, openOutApp, openPermissionSetting, openPhone, openPostFeed, openProfile, openProfilePicker, openSMS, openShareSheet, openWebview, purchase, refreshAd, removeStorage, requestCameraPermission, requestSendNotification, requestUpdateZalo, saveImageToGallery, saveVideoToGallery, scanNFC, scanQRCode, selectPaymentMethod, sendDataToPreviousMiniApp, setAccessToken, setAndroidBottomNavigationBar, setIOSBottomSafeArea, setNavigationBarColor, setNavigationBarLeftButton, setNavigationBarTitle, setStatusBar, setStorage, setupAd, showCustomOAWidget, showFunctionButtonWidget, showOAWidget, showToast, startBeaconDiscovery, stopBeaconDiscovery, trackingManager, unfollowOA, vibrate, viewOAQr };
+export { Action, AddVoucherData, AddVoucherReturns, AndroidBottomNavigationBarType, AppError, AsyncCallback, AsyncCallbackFailObject, AsyncProgressCallback, AsyncVoidCallback, AuthorizeType, CameraEvents, CameraParams, ChatType, CheckStateBioAuthenticationReturns, CheckTransactionReturns, CheckZaloCameraPermissionReturns, CheckoutKit, CheckoutPopupOpenParams, CheckoutPopupResponseData, CheckoutSDK, ChooseImageReturns, Common, ContextInfo, CreateOrderIAPReturns, CreateOrderReturns, Events as EventName, Events, FacingMode, FileInfo, FunctionProps, GetAppInfoReturns, GetAuthCodeReturns, GetBeaconDiscoveryReturns, GetDeviceInfoReturn, GetFileInfoReturns, GetLocationReturns, GetNetworkTypeReturns, GetPhoneNumberReturns, GetSettingReturn, GetStorageReturns, GetUserInfoReturns, GetZPITokenReturns, IAPMethodType, IAPPayType, IAPPayTypeType, IOSSafeAreaBottomType, IsSupportReturns, JumpStatus, KeepScreenReturns, LFSStorage, ListFile, LogData, MediaConstraints, MediaDevice, MediaPickerType, NativeCallBackData, NetworkType, OpenBioAuthenticationReturns, OpenMediaPickerReturns, OpenPostFeedReturns, OpenProfilePickerReturns, OpenProfilePickerType, OpenShareSheetReturns, OpenWebviewReturns, OrientationType, Payment, PhotoConstraint, PhotoFormat, PhotoFrame, PhotoQuality, PickAttr, PickedProfile, PlatformType, PostFeedType, ProfileInfo, ProfileType, ProrationMode, ProrationModeType, RemoveStorageReturns, RequestCameraPermissionReturns, SaveFileReturns, ScanNFCType, ScanQRCodeReturns, SelectPaymentMethodReturns, SetStorageReturns, ShareSheetType, StatusBarType, StorageInfo, StreamType, SystemInfo, TempFile, TextAlignType, UserInfo, VibrateType, VoucherAction, VoucherActionType, VoucherDisplayType, ZMACamera, ZMACameraImp, addRating, addVoucher, authorize, checkNFC, checkStateBioAuthentication, checkTransaction, checkZaloCameraPermission, chooseImage, clearStorage, closeApp, closeLoading, configAppView, connectWifi, createCameraContext, createOrder, createOrderIAP, createShortcut, otherApis as default, displayAd, downloadFile, events, favoriteApp, followOA, getAccessToken, getAppInfo, getAuthCode, getBeacons, getContext, getContextAsync, getDeviceId, getDeviceIdAsync, getDeviceInfo, getEntrySource, getIDToken, getLocation, getNetworkType, getPhoneNumber, getRouteParams, getSetting, getShareableLink, getStorage, getStorageInfo, getSystemInfo, getUserID, getUserInfo, getVersion, getZPIToken, hideKeyboard, iBeaconInfo, interactOA, interactOA as interactOa, checkIsAllowedInteractWithOA as isAllowedInteractWithOA, keepScreen, loadAd, login, minimizeApp, nativeStorage, offConfirmToExit, offKeepScreen, onCallbackData, onConfirmToExit, onKeepScreen, onNetworkStatusChange, openBioAuthentication, openChat, openDocument, openGroupList, openMediaPicker, openMiniApp, openOutApp, openPermissionSetting, openPhone, openPostFeed, openProfile, openProfilePicker, openSMS, openShareSheet, openWebview, purchase, refreshAd, removeStorage, requestCameraPermission, requestSendNotification, requestUpdateZalo, saveImageToGallery, saveVideoToGallery, scanNFC, scanQRCode, selectPaymentMethod, sendDataToPreviousMiniApp, setAccessToken, setAndroidBottomNavigationBar, setIOSBottomSafeArea, setNavigationBarColor, setNavigationBarLeftButton, setNavigationBarTitle, setStatusBar, setStorage, setupAd, showCustomOAWidget, showFunctionButtonWidget, showOAWidget, showToast, startBeaconDiscovery, stopBeaconDiscovery, trackingManager, unfollowOA, vibrate, viewOAQr };