@v-miniapp/apis 1.0.15 → 1.0.20

package/dist/types/api/report-analytics.d.ts

@@ -1,8 +1,172 @@
 import { IVsfOptionsWithCallback } from '../common';
 /**
- * Tham số cho API reportAnalytics (dữ liệu analytics tùy ý)
+ * Item ecommerce dùng chung cho các event như view_item, add_to_cart, ...
  */
-export type IVsfReportAnalyticsOptions = Record<string, any>;
-export type IVsfReportAnalyticsOptionsWithCallback = IVsfOptionsWithCallback<IVsfReportAnalyticsOptions, void>;
-export type IVsfReportAnalytics = (name: string, options?: IVsfReportAnalyticsOptionsWithCallback) => void;
-export type IVsfReportAnalyticsAsync = (name: string, options?: IVsfReportAnalyticsOptions) => Promise<void>;
+export type IVsfReportAnalyticsItem = {
+    /** Mã định danh sản phẩm */
+    item_id: string;
+    /** Tên của sản phẩm */
+    item_name: string;
+    /** Giá sản phẩm */
+    item_price?: number;
+    /** Phiên bản của sản phẩm (vd: green) */
+    item_variant?: string;
+    /** Thương hiệu của sản phẩm */
+    item_brand?: string;
+    /** Danh mục của sản phẩm */
+    item_category?: string;
+    /** Danh mục cấp 2 */
+    item_category2?: string;
+    /** Danh mục cấp 3 */
+    item_category3?: string;
+    /** Danh mục cấp 4 */
+    item_category4?: string;
+    /** Danh mục cấp 5 */
+    item_category5?: string;
+    /** Số lượng của sản phẩm */
+    quantity?: number;
+    /** Cho phép developer truyền thêm các trường tuỳ ý */
+    [key: string]: any;
+};
+/**
+ * Bộ tham số ecommerce dùng chung cho view_item, add_to_cart, remove_from_cart,
+ * begin_checkout.
+ */
+export type IVsfReportAnalyticsEcommerceProperties = {
+    /** Đơn vị tiền tệ (vd: VND) */
+    currency?: string;
+    /** Tổng giá trị các sản phẩm trong sự kiện */
+    value?: number;
+    /** Danh sách các sản phẩm liên quan đến sự kiện */
+    items?: IVsfReportAnalyticsItem[];
+    /** Cho phép developer truyền thêm các trường tuỳ ý */
+    [key: string]: any;
+};
+/**
+ * Map giữa event name (đã được hệ thống định nghĩa) với cấu trúc properties
+ * tương ứng. Khi truyền event name nằm trong map, properties sẽ được type-check
+ * theo cấu trúc tương ứng. Khi truyền event name khác, properties sẽ rơi về
+ * `Record<string, any> | undefined`.
+ */
+export type IVsfReportAnalyticsEventMap = {
+    /**
+     * SDK tự bắn khi user mở Mini App thành công (first page loaded).
+     */
+    miniapp_open: {
+        page_path?: string;
+        page_title?: string;
+        referrer?: 'home_screen' | 'notification' | 'deeplink' | 'qr_code' | (string & {});
+        is_first_open?: boolean;
+        /** Mini app params/query */
+        app_query?: string;
+        utm_source?: string;
+        /** Cho phép developer truyền thêm các trường tuỳ ý */
+        [key: string]: any;
+    };
+    /**
+     * SDK tự bắn khi mini app đóng.
+     */
+    miniapp_close: {
+        page_path?: string;
+        page_title?: string;
+        /** Cho phép developer truyền thêm các trường tuỳ ý */
+        [key: string]: any;
+    };
+    /**
+     * SDK tự bắn khi user navigate đến một page mới (kể cả first page).
+     */
+    page_view: {
+        page_path: string;
+        page_title?: string;
+        /** Page trước đó */
+        referrer_page?: string;
+        /** Có phải trang đầu tiên trong session hay không */
+        is_first_page_in_session?: boolean;
+        app_query?: string;
+        /** Cho phép developer truyền thêm các trường tuỳ ý */
+        [key: string]: any;
+    };
+    /**
+     * SDK tự bắn khi user trả lời permission prompt.
+     */
+    permission_request: {
+        permission_type: string;
+        permission_result: 'accept' | 'reject';
+        /** Page nơi request permission xảy ra */
+        trigger_page?: string;
+        /** Cho phép developer truyền thêm các trường tuỳ ý */
+        [key: string]: any;
+    };
+    /**
+     * SDK tự bắn khi user cấp quyền (vd: trong Quản lý riêng tư).
+     */
+    permission_grant: {
+        permission_type: string;
+        trigger_source?: 'privacy_page' | (string & {});
+        /** Cho phép developer truyền thêm các trường tuỳ ý */
+        [key: string]: any;
+    };
+    /**
+     * SDK tự bắn khi user thu hồi quyền (vd: trong Quản lý riêng tư).
+     */
+    permission_revoke: {
+        permission_type: string;
+        trigger_source?: 'privacy_page' | (string & {});
+        /** Cho phép developer truyền thêm các trường tuỳ ý */
+        [key: string]: any;
+    };
+    /** User xem chi tiết danh sách sản phẩm/nội dung */
+    view_item: IVsfReportAnalyticsEcommerceProperties;
+    /** User thêm sản phẩm vào giỏ */
+    add_to_cart: IVsfReportAnalyticsEcommerceProperties;
+    /** User xóa 1 mặt hàng khỏi giỏ hàng */
+    remove_from_cart: IVsfReportAnalyticsEcommerceProperties;
+    /** User bắt đầu checkout */
+    begin_checkout: IVsfReportAnalyticsEcommerceProperties;
+    /** User áp dụng voucher / promotion */
+    apply_promotion: IVsfReportAnalyticsEcommerceProperties & {
+        /** Coupon name hoặc id */
+        coupon?: string;
+        /** Phương thức thanh toán đơn hàng */
+        payment_method?: string;
+    };
+};
+export type IVsfReportAnalyticsKnownEvent = keyof IVsfReportAnalyticsEventMap;
+/**
+ * Loại bỏ các event name đã được khai báo trong `IVsfReportAnalyticsEventMap`
+ * khỏi tham số `name`. Khi developer truyền một known event như `'view_item'`,
+ * type này sẽ thành `never`, buộc TypeScript chuyển sang overload có
+ * type-checking theo properties tương ứng.
+ *
+ * Lưu ý: với biến `name: string` (không phải literal), `S` là `string` nên
+ * `string extends IVsfReportAnalyticsKnownEvent` là `false`, kết quả vẫn là
+ * `string` — fallback vẫn hoạt động bình thường.
+ */
+export type IVsfReportAnalyticsUnknownEvent<S extends string = string> = S extends IVsfReportAnalyticsKnownEvent ? never : S;
+/**
+ * Properties cho các event name không nằm trong `IVsfReportAnalyticsEventMap`.
+ */
+export type IVsfReportAnalyticsCustomProperties = Record<string, any>;
+/**
+ * Tham số properties cho `reportAnalytics` đã hợp nhất theo event name.
+ */
+export type IVsfReportAnalyticsOptions<K extends string = string> = K extends IVsfReportAnalyticsKnownEvent ? IVsfReportAnalyticsEventMap[K] : IVsfReportAnalyticsCustomProperties | undefined;
+export type IVsfReportAnalyticsOptionsWithCallback<K extends string = string> = IVsfOptionsWithCallback<IVsfReportAnalyticsOptions<K>, void>;
+/**
+ * Callback-style signature.
+ *
+ * - Với event name nằm trong `IVsfReportAnalyticsEventMap`, `options` được
+ *   type-check theo properties tương ứng.
+ * - Với event name khác, properties có type là `Record<string, any> | undefined`.
+ */
+export interface IVsfReportAnalytics {
+    <K extends IVsfReportAnalyticsKnownEvent>(name: K, options?: IVsfOptionsWithCallback<IVsfReportAnalyticsEventMap[K], void>): void;
+    <S extends string>(name: IVsfReportAnalyticsUnknownEvent<S>, options?: IVsfOptionsWithCallback<IVsfReportAnalyticsCustomProperties | undefined, void>): void;
+}
+/**
+ * Promise-style signature (tương tự `IVsfReportAnalytics` nhưng trả về Promise).
+ */
+export interface IVsfReportAnalyticsAsync {
+    <K extends IVsfReportAnalyticsKnownEvent>(name: K, options?: IVsfReportAnalyticsEventMap[K]): Promise<void>;
+    <S extends string>(name: IVsfReportAnalyticsUnknownEvent<S>, options?: IVsfReportAnalyticsCustomProperties | undefined): Promise<void>;
+}

package/dist/types/api/show-payment-method.d.ts

@@ -25,7 +25,7 @@ export type IVsfPaymentMethod = {
 /**
  * Kết quả trả về khi người dùng chọn phương thức thanh toán (mảng các phương thức)
  */
-export type IVsfShowPaymentMethodData = IVsfPaymentMethod[];
+export type IVsfShowPaymentMethodData = IVsfPaymentMethod;
 /**
  * Tham số để hiển thị danh sách phương thức thanh toán
  */

package/dist/types/vsf.d.ts

@@ -281,12 +281,38 @@ export type IVsf = {
      */
     removeStorage: IVsfRemoveStorage;
     /**
-     * Gửi dữ liệu analytics (báo cáo sự kiện/tùy chỉnh).
-     *
-     * @param options - Tham số: object key-value tùy ý (Record<string, any>)
-     * @param options.success - `() => void` - Callback khi thành công
-     * @param options.fail - `(error) => void` - Callback khi thất bại
-     * @param options.complete - `() => void` - Callback khi hoàn tất
+     * Gửi dữ liệu analytics tùy chỉnh.
+     *
+     * Các event đã được định nghĩa sẵn (type-checked):
+     * - **Auto-tracked** (SDK tự bắn, developer không cần code):
+     *   `miniapp_open`, `miniapp_close`, `page_view`, `permission_request`,
+     *   `permission_grant`, `permission_revoke`.
+     * - **Custom** (developer chủ động bắn):
+     *   `view_item`, `add_to_cart`, `remove_from_cart`, `begin_checkout`,
+     *   `apply_promotion`.
+     *
+     * Event name nằm ngoài danh sách trên vẫn được chấp nhận, nhưng `properties`
+     * sẽ có type là `Record<string, any> | undefined`.
+     *
+     * @param name - Tên event
+     * @param options - Properties của event (theo schema tương ứng) cộng với
+     *   `success` / `fail` / `complete` callbacks.
+     *
+     * @example
+     * ```ts
+     * apis.reportAnalytics('view_item', {
+     *   currency: 'VND',
+     *   value: 150000,
+     *   items: [
+     *     {
+     *       item_id: 'SKU_12345',
+     *       item_name: 'Stan and Friends Tee',
+     *       item_price: 50000,
+     *       quantity: 3,
+     *     },
+     *   ],
+     * })
+     * ```
      */
     reportAnalytics: IVsfReportAnalytics;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-miniapp/apis",
-  "version": "1.0.15",
+  "version": "1.0.20",
   "type": "module",
   "files": [
     "dist",
@@ -22,5 +22,6 @@
   "peerDependencies": {},
   "engines": {
     "node": ">=22"
-  }
+  },
+  "sideEffects": false
 }