@cnv-vn/track 0.3.0-beta.15 → 0.3.0-beta.17

package/dist/types/index.d.ts

@@ -665,12 +665,14 @@ interface PanelShapes {
  * Lý do `loginWithZalo()` thất bại (`ZaloQrLoginError.reason`). LƯU Ý phạm vi
  * reject khác nhau:
  * - `'not-initialized' | 'disabled' | 'consent-required' | 'invalid-project-key'
- *   | 'project-suspended' | 'network'`: reject ngay lời gọi `loginWithZalo(...)`
+ *   | 'project-suspended' | 'origin-required' | 'zalo-login-not-configured'
+ *   | 'zalo-login-unavailable' | 'network'`: reject ngay lời gọi `loginWithZalo(...)`
  *   (trước khi có {@link ZaloQrLoginSession}) — lỗi thiết lập phiên, không có
  *   `session`/`session.result` nào để bắt.
- * - `'expired' | 'denied' | 'cancelled' | 'agent-registration-required' | 'login-blocked'`:
- *   reject {@link ZaloQrLoginSession.result} — xảy ra SAU khi đã có `session` (QR đã hiển
- *   thị), khi chờ kết quả quét.
+ * - `'expired' | 'denied' | 'consent-declined' | 'zalo-permission-denied'
+ *   | 'underage-self-declared' | 'cancelled' | 'agent-registration-required'
+ *   | 'requester-not-ready' | 'login-blocked'`: reject {@link ZaloQrLoginSession.result} —
+ *   xảy ra SAU khi đã có `session` (QR đã hiển thị), khi chờ kết quả quét.
  *
  * Bọc `try/catch` quanh CẢ hai điểm `await` (xem ví dụ ở `loginWithZalo` JSDoc)
  * để không bỏ sót nhóm đầu.
@@ -686,14 +688,57 @@ interface PanelShapes {
  * làm gì sai và bấm "Thử lại" cũng vô nghĩa: việc cần làm là mở Mini App của shop để đăng ký
  * đại lý trước. `'login-blocked'` là ca shop chặn vì lý do khác (backend gửi mã lạ) — dùng câu
  * thông báo chung, vẫn cho thử lại.
+ *
+ * Lỗi tạo phiên theo HTTP status của `POST /zalo-qr/session`: `'zalo-login-not-configured'` (422 —
+ * project chưa cấu hình Mini App nhận QR, và cũng không được dùng Mini App CNV dùng chung),
+ * `'zalo-login-unavailable'` (503 — Mini App chưa ACTIVE/chưa xác minh được, tạm thời),
+ * `'origin-required'` (403 `origin_required` — request không có header `Origin`, tức không gọi
+ * từ trình duyệt; KHÁC `'project-suspended'`, cũng là 403).
+ *
+ * Khách TỰ từ chối ở Mini App — `denied` kèm lý do từ server: `'consent-declined'` (bấm Huỷ ở
+ * màn xin quyền của Mini App CNV dùng chung; KHÁC `'consent-required'`, vốn là đồng ý tracking
+ * trên website), `'zalo-permission-denied'` (từ chối popup quyền số điện thoại của Zalo),
+ * `'underage-self-declared'` (tự khai chưa đủ 16 tuổi). Không có lý do (Mini App riêng của shop,
+ * backend cũ) vẫn là `'denied'`.
+ *
+ * `'requester-not-ready'`: shop CHƯA sẵn sàng nhận xác thực qua Mini App CNV dùng chung (hồ sơ
+ * chưa được duyệt, website chưa khai báo…) — việc của shop, khách thử lại ngay cũng vậy.
  */
-type ZaloQrLoginErrorReason = 'not-initialized' | 'disabled' | 'consent-required' | 'invalid-project-key' | 'project-suspended' | 'network' | 'expired' | 'denied' | 'cancelled' | 'agent-registration-required' | 'login-blocked';
+type ZaloQrLoginErrorReason = 'not-initialized' | 'disabled' | 'consent-required' | 'invalid-project-key' | 'project-suspended' | 'origin-required' | 'zalo-login-not-configured' | 'zalo-login-unavailable' | 'network' | 'expired' | 'denied' | 'consent-declined' | 'zalo-permission-denied' | 'underage-self-declared' | 'cancelled' | 'agent-registration-required' | 'requester-not-ready' | 'login-blocked';
+/**
+ * Mã QR mở Mini App NÀO: `'SHOP'` = Mini App riêng của shop; `'CNV_SHARED'` = Mini App CNV dùng chung
+ * (shop không có Mini App riêng), nơi khách thấy màn xin quyền rồi mới chia sẻ thông tin. Server chọn,
+ * SDK chỉ đọc — dùng để nói đúng câu với khách (vd "liên hệ shop" thay vì "mở Mini App của shop").
+ */
+type ZaloQrMiniAppKind = 'SHOP' | 'CNV_SHARED';
 /** Tuỳ chọn cho `loginWithZalo()`. */
 interface ZaloQrLoginOptions {
     /** Ưu tiên SSE (mặc định `true`); `false` ⇒ chỉ dùng poll ngay từ đầu. */
     preferSse?: boolean;
     /** Khoảng poll fallback (ms). Mặc định 2000. */
     pollIntervalMs?: number;
+    /**
+     * Báo tiến trình của phiên TRƯỚC khi có kết cục — để host đổi màn QR khi khách đã quét mã, thay
+     * vì để họ nhìn một mã QR đứng im trong lúc bước tiếp theo nằm trên điện thoại (màn xin quyền
+     * của Mini App).
+     *
+     * Gọi tối đa MỘT lần mỗi phiên (server báo lại "đã quét" ở mỗi nhịp poll và mỗi lần SSE nối lại
+     * — SDK lọc hộ). Không phải kết cục: `result` vẫn chờ tiếp như thường. Lỗi ném ra từ callback bị
+     * nuốt, không làm hỏng phiên. Server cũ không báo "đã quét" ⇒ không bao giờ được gọi.
+     */
+    onProgress?: (progress: ZaloQrLoginProgress) => void;
+}
+/** Tiến trình của một phiên QR chưa kết thúc — xem {@link ZaloQrLoginOptions.onProgress}. */
+interface ZaloQrLoginProgress {
+    /** `'scanned'`: khách đã quét mã, Mini App đang chờ khách xác nhận trên điện thoại. */
+    stage: 'scanned';
+    /**
+     * Số giây phiên còn sống theo server lúc báo. Server gia hạn phiên khi khách quét (đọc màn xin
+     * quyền cần thời gian); SDK đã tự nới hạn chờ của `result` theo đó (chỉ nới, không rút) — host
+     * chỉ cần đếm ngược lại từ số này. Thiếu (server không đọc được hạn, hoặc số không hợp lệ) ⇒ hạn
+     * cũ vẫn đúng, cứ đếm tiếp.
+     */
+    expiresInSeconds?: number;
 }
 /**
  * Kết quả khi người dùng quét QR và xác thực Zalo thành công.
@@ -743,12 +788,18 @@ interface ZaloQrLoginResult {
  */
 interface ZaloQrLoginSession {
     sessionToken: string;
-    /** Deep-link Mini App Zalo — host tự vẽ thành mã QR. */
+    /**
+     * Deep-link Mini App Zalo — host tự vẽ thành mã QR. Trên ĐIỆN THOẠI khách không quét được màn hình
+     * của chính mình: dùng chuỗi này làm `href` của một nút "Mở Zalo" (link `https://zalo.me/...` mở
+     * thẳng app Zalo), QR chỉ còn là phương án quét bằng máy khác.
+     */
     qrPayload: string;
     expiresInSeconds: number;
+    /** Mini App mà mã QR mở — xem {@link ZaloQrMiniAppKind}. Server cũ không gửi ⇒ `'SHOP'`. */
+    miniAppKind: ZaloQrMiniAppKind;
     /**
      * Resolve khi quét xong & backend xác nhận; reject với {@link ZaloQrLoginError}
-     * có `reason` là `'expired' | 'denied' | 'cancelled'` (xem {@link ZaloQrLoginErrorReason}
+     * có `reason` là `'expired' | 'denied' | 'cancelled'`… (xem {@link ZaloQrLoginErrorReason}
      * để phân biệt với lỗi thiết lập phiên, vốn reject lời gọi `loginWithZalo()` chứ
      * không phải field này).
      */
@@ -773,6 +824,64 @@ interface ZaloQrLoginSession {
  */
 type QueuedCommand = readonly ['init', string, SDKOptions?] | readonly ['pageview', string?, Record<string, JSONValue>?] | readonly ['page', string?, Record<string, JSONValue>?] | readonly ['screen', string?, Record<string, JSONValue>?] | readonly ['track', string, Record<string, JSONValue>?] | readonly ['identify', string, UserTraits?] | readonly ['alias', string, string?] | readonly ['group', string, Record<string, JSONValue>?] | readonly ['reset'] | readonly ['flush'] | readonly ['consent', Partial<ContextConsent>] | readonly ['set', Partial<SDKOptions>];
 
+/**
+ * ============================================================================
+ *  zaloQrLogin — đăng nhập bằng Zalo qua QR cho website nhúng SDK
+ * ============================================================================
+ *
+ *  `loginWithZalo()` là API ĐẦU TIÊN của SDK không theo hợp đồng "never throw,
+ *  fire-and-forget" của các method khác (track/identify/...) — nó trả Promise
+ *  thật, và có THỂ REJECT Ở 2 ĐIỂM khác nhau (xem `ZaloQrLoginErrorReason` ở
+ *  types.ts để biết chi tiết từng reason):
+ *    1. Lời gọi `loginWithZalo()` chính nó — lỗi thiết lập phiên (chưa init,
+ *       dashboard tắt, thiếu consent, lỗi mạng khi tạo phiên).
+ *    2. `session.result` — lỗi xảy ra SAU khi đã có phiên/đã hiển thị QR
+ *       (hết hạn, bị từ chối, bị huỷ).
+ *  Consumer cần bọc try/catch quanh CẢ HAI điểm await. Vì cần tương tác 2
+ *  chiều thực sự (đăng ký phiên → chờ QR được quét), hàm này KHÔNG đi qua
+ *  queue protocol `window.cnvQ` — chỉ dùng được qua ES-module import.
+ *
+ *  SDK không tự vẽ QR: trả `qrPayload` (deep-link Mini App) để host page tự
+ *  render `<img>`/canvas, đúng vai trò "tracker" chứ không phải "auth widget"
+ *  (xem cách `demo/index.html` tự vẽ modal login cho `identify()`).
+ *
+ *  Kênh nhận kết quả: SSE (`GET {endpoint}/zalo-qr/stream`) làm chính, tự
+ *  fallback sang poll (`GET {endpoint}/zalo-qr/status`) nếu `EventSource`
+ *  không tồn tại hoặc báo lỗi kéo dài — cùng triết lý "luôn có phương án dự
+ *  phòng" mà `transport.ts` áp dụng (sendBeacon → fetch).
+ *
+ *  Làm mới QR hết hạn: `session.retry()` — tự huỷ phiên hiện tại (an toàn dù đã
+ *  hết hạn/bị từ chối/thành công từ trước) rồi tạo phiên MỚI với cùng host/options
+ *  ban đầu, trả về `ZaloQrLoginSession` mới để host render lại QR + await `result`
+ *  mới. Không cần tự lưu lại `host`/`opts` hay gọi lại `loginWithZalo()` thủ công.
+ * ============================================================================
+ */
+
+/** Phần SDK `loginWithZalo()` cần từ runtime — tách nhỏ để test không phải mock cả module runtime. */
+interface ZaloQrLoginHost {
+    readonly projectId: string | null;
+    readonly endpoint: string | null;
+    readonly zaloQrLoginEnabled: boolean;
+    readonly consentGranted: boolean;
+    /**
+     * Nguồn đưa khách tới lần đầu, ĐÃ ở dạng wire (`utm_*`) — xem `core/attribution.ts`. `null` khi
+     * chưa ghi được tín hiệu nào.
+     *
+     * Host trả về bản đã ánh xạ, KHÔNG phải `FirstTouch` thô, là cố ý: việc ánh xạ còn phải gác
+     * `allowAdTracking` (không gửi click-id khi shop tắt) và chỉ `runtime` biết cấu hình đó. Để
+     * zaloQrLogin tự gọi `toAttributionWire` là mở ra một chỗ thứ hai có thể quên mất cái gác.
+     */
+    getAttribution?(): ContextFirstTouch | null;
+    /** anonymousId (`_cnv_cid`) — để server nối phiên QR này với hành vi ẩn danh trước đó. */
+    getAnonymousId?(): string;
+    getSessionId?(): string;
+}
+/** Lỗi nghiệp vụ của `loginWithZalo()` — xem {@link ZaloQrLoginErrorReason} cho phạm vi reject của từng reason. */
+declare class ZaloQrLoginError extends Error {
+    readonly reason: ZaloQrLoginErrorReason;
+    constructor(reason: ZaloQrLoginErrorReason);
+}
+
 /**
  * ============================================================================
  *  queue — Queue Processor (Sub-task 3.5)
@@ -872,49 +981,15 @@ interface Runtime extends Dispatcher {
     isZaloQrLoginEnabled(): boolean;
     /** `true` khi cả `analytics` và `marketing` đều được đồng ý — ngưỡng `loginWithZalo()` yêu cầu vì thu thập SĐT. */
     readonly consentGranted: boolean;
+    /**
+     * Host cho `loginWithZalo()` (nội bộ) — MỘT chỗ dựng cho cả Panel lẫn wrapper public ở `index.ts`, kèm
+     * đủ 3 getter nguồn khách + định danh ẩn danh.
+     */
+    zaloQrLoginHost(): ZaloQrLoginHost;
     /** Tear down timers + listeners. Test-only in production. */
     destroy(): void;
 }
 
-/**
- * ============================================================================
- *  zaloQrLogin — đăng nhập bằng Zalo qua QR cho website nhúng SDK
- * ============================================================================
- *
- *  `loginWithZalo()` là API ĐẦU TIÊN của SDK không theo hợp đồng "never throw,
- *  fire-and-forget" của các method khác (track/identify/...) — nó trả Promise
- *  thật, và có THỂ REJECT Ở 2 ĐIỂM khác nhau (xem `ZaloQrLoginErrorReason` ở
- *  types.ts để biết chi tiết từng reason):
- *    1. Lời gọi `loginWithZalo()` chính nó — lỗi thiết lập phiên (chưa init,
- *       dashboard tắt, thiếu consent, lỗi mạng khi tạo phiên).
- *    2. `session.result` — lỗi xảy ra SAU khi đã có phiên/đã hiển thị QR
- *       (hết hạn, bị từ chối, bị huỷ).
- *  Consumer cần bọc try/catch quanh CẢ HAI điểm await. Vì cần tương tác 2
- *  chiều thực sự (đăng ký phiên → chờ QR được quét), hàm này KHÔNG đi qua
- *  queue protocol `window.cnvQ` — chỉ dùng được qua ES-module import.
- *
- *  SDK không tự vẽ QR: trả `qrPayload` (deep-link Mini App) để host page tự
- *  render `<img>`/canvas, đúng vai trò "tracker" chứ không phải "auth widget"
- *  (xem cách `demo/index.html` tự vẽ modal login cho `identify()`).
- *
- *  Kênh nhận kết quả: SSE (`GET {endpoint}/zalo-qr/stream`) làm chính, tự
- *  fallback sang poll (`GET {endpoint}/zalo-qr/status`) nếu `EventSource`
- *  không tồn tại hoặc báo lỗi kéo dài — cùng triết lý "luôn có phương án dự
- *  phòng" mà `transport.ts` áp dụng (sendBeacon → fetch).
- *
- *  Làm mới QR hết hạn: `session.retry()` — tự huỷ phiên hiện tại (an toàn dù đã
- *  hết hạn/bị từ chối/thành công từ trước) rồi tạo phiên MỚI với cùng host/options
- *  ban đầu, trả về `ZaloQrLoginSession` mới để host render lại QR + await `result`
- *  mới. Không cần tự lưu lại `host`/`opts` hay gọi lại `loginWithZalo()` thủ công.
- * ============================================================================
- */
-
-/** Lỗi nghiệp vụ của `loginWithZalo()` — xem {@link ZaloQrLoginErrorReason} cho phạm vi reject của từng reason. */
-declare class ZaloQrLoginError extends Error {
-    readonly reason: ZaloQrLoginErrorReason;
-    constructor(reason: ZaloQrLoginErrorReason);
-}
-
 /**
  * ============================================================================
  *  cnv-track.js — public entry point
@@ -986,4 +1061,4 @@ declare const cnvTrack: Runtime & {
 };
 
 export { NAME, SCHEMA_VERSION, VERSION, ZaloQrLoginError, cnvTrack as default, loginWithZalo };
-export type { AutotrackOptions, ButtonTrackingOptions, CaptureSpec, ClickEventSpec, ClickMatch, ClickRule, ContextCampaign, ContextConsent, ContextLibrary, ContextPage, ContextScreen, DataAttrMatch, DestinationMatch, JSONValue, MessageType, PayloadContext, QueuedCommand, RemoteConfigEnvelope, RemoteConfigOptions, SDKOptions, SegmentBatchRequest, SegmentMessage, TextMatch, ThrottleSpec, UrlMatch, UserTraits, ZaloQrLoginErrorReason, ZaloQrLoginOptions, ZaloQrLoginResult, ZaloQrLoginSession };
+export type { AutotrackOptions, ButtonTrackingOptions, CaptureSpec, ClickEventSpec, ClickMatch, ClickRule, ContextCampaign, ContextConsent, ContextLibrary, ContextPage, ContextScreen, DataAttrMatch, DestinationMatch, JSONValue, MessageType, PayloadContext, QueuedCommand, RemoteConfigEnvelope, RemoteConfigOptions, SDKOptions, SegmentBatchRequest, SegmentMessage, TextMatch, ThrottleSpec, UrlMatch, UserTraits, ZaloQrLoginErrorReason, ZaloQrLoginOptions, ZaloQrLoginProgress, ZaloQrLoginResult, ZaloQrLoginSession, ZaloQrMiniAppKind };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cnv-vn/track",
-  "version": "0.3.0-beta.15",
+  "version": "0.3.0-beta.17",
   "description": "CNV Tracking SDK — lightweight, async-first web analytics tracker (<30KB gzipped).",
   "keywords": [
     "analytics",