@macroui/event-tracker 1.3.0

package/dist/plugin/session-event.cjs

@@ -0,0 +1,142 @@
+'use strict';
+
+/**
+ * 浏览器端辅助方法
+ */
+function isBrowser() {
+    return typeof window !== 'undefined' && typeof window.document !== 'undefined';
+}
+
+/**
+ * SDK 预置事件名与预置属性 key（v1.1：完整对齐神策）
+ * 命名风格对齐神策，方便跨平台对接
+ */
+/** 预置事件名 */
+/** 预置属性 key */
+var PresetProperty = {
+    // 会话
+    EventSessionId: '$event_session_id'};
+
+/**
+ * UUID v4 生成（无依赖，使用 crypto.getRandomValues）
+ */
+function uuidv4() {
+    if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+        var arr = new Uint8Array(16);
+        crypto.getRandomValues(arr);
+        // RFC 4122 v4
+        arr[6] = (arr[6] & 0x0f) | 0x40;
+        arr[8] = (arr[8] & 0x3f) | 0x80;
+        var hex = Array.from(arr, function (b) { return b.toString(16).padStart(2, '0'); });
+        return (hex.slice(0, 4).join('') +
+            '-' +
+            hex.slice(4, 6).join('') +
+            '-' +
+            hex.slice(6, 8).join('') +
+            '-' +
+            hex.slice(8, 10).join('') +
+            '-' +
+            hex.slice(10, 16).join(''));
+    }
+    // 退化实现
+    var d = Date.now();
+    var d2 = (typeof performance !== 'undefined' && performance.now && performance.now() * 1000) || 0;
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        var r = Math.random() * 16;
+        if (d > 0) {
+            r = (d + r) % 16 | 0;
+            d = Math.floor(d / 16);
+        }
+        else {
+            r = (d2 + r) % 16 | 0;
+            d2 = Math.floor(d2 / 16);
+        }
+        return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+
+/**
+ * session-event 插件：会话管理
+ *  - 每条事件附 $event_session_id（首次访问生成，存 storage）
+ *  - $session_start / $session_end 事件
+ *  - 超时（默认 30 分钟）则重开会话
+ */
+var SESSION_KEY = 'et_session_id';
+var SESSION_LAST_KEY = 'et_session_last_active';
+var DEFAULT_TIMEOUT = 30 * 60 * 1000; // 30 分钟
+function sessionEvent(opts) {
+    var _a;
+    if (opts === void 0) { opts = {}; }
+    var timeout = (_a = opts.timeout) !== null && _a !== void 0 ? _a : DEFAULT_TIMEOUT;
+    var sdkRef = null;
+    var storeRef = null;
+    var sessionId = '';
+    var lastActive = 0;
+    function newSession(reason) {
+        sessionId = uuidv4();
+        lastActive = Date.now();
+        if (storeRef) {
+            storeRef.set(SESSION_KEY, sessionId);
+            storeRef.set(SESSION_LAST_KEY, String(lastActive));
+        }
+        if (sdkRef && reason === 'start') {
+            sdkRef.track('$session_start', { $event_session_id: sessionId });
+        }
+    }
+    function check() {
+        var now = Date.now();
+        if (!sessionId || (lastActive && now - lastActive > timeout)) {
+            newSession(now - lastActive > timeout ? 'timeout' : 'start');
+        }
+        lastActive = now;
+        if (storeRef)
+            storeRef.set(SESSION_LAST_KEY, String(lastActive));
+    }
+    var interceptor = {
+        name: 'session-event',
+        priority: 10, // 早于业务拦截器
+        entry: function (ctx) {
+            if (ctx.meta.stage !== 'buildDataStage')
+                return;
+            check();
+            var ev = ctx.data;
+            if (ev && ev.properties) {
+                ev.properties[PresetProperty.EventSessionId] = sessionId;
+            }
+        },
+    };
+    return {
+        name: 'session-event',
+        install: function (_a) {
+            var sdk = _a.sdk, stages = _a.stages, store = _a.store;
+            if (!isBrowser())
+                return;
+            sdkRef = sdk;
+            storeRef = store;
+            // 读已有
+            var existing = store.get(SESSION_KEY);
+            var last = Number(store.get(SESSION_LAST_KEY) || '0');
+            if (existing && last && Date.now() - last < timeout) {
+                sessionId = existing;
+                lastActive = last;
+            }
+            else {
+                newSession('start');
+            }
+            stages.buildDataStage.register(interceptor);
+            // 跨 tab 同步：通过 storage 事件检测其它 tab 关闭
+            window.addEventListener('storage', function (ev) {
+                if (ev.key === SESSION_KEY && !ev.newValue) {
+                    // 其它 tab 关闭了会话，本地也清掉
+                    sessionId = '';
+                }
+            });
+        },
+        uninstall: function () {
+            sdkRef = null;
+            storeRef = null;
+        },
+    };
+}
+
+exports.sessionEvent = sessionEvent;

package/dist/plugin/session-event.mjs

@@ -0,0 +1,140 @@
+/**
+ * 浏览器端辅助方法
+ */
+function isBrowser() {
+    return typeof window !== 'undefined' && typeof window.document !== 'undefined';
+}
+
+/**
+ * SDK 预置事件名与预置属性 key（v1.1：完整对齐神策）
+ * 命名风格对齐神策，方便跨平台对接
+ */
+/** 预置事件名 */
+/** 预置属性 key */
+var PresetProperty = {
+    // 会话
+    EventSessionId: '$event_session_id'};
+
+/**
+ * UUID v4 生成（无依赖，使用 crypto.getRandomValues）
+ */
+function uuidv4() {
+    if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+        var arr = new Uint8Array(16);
+        crypto.getRandomValues(arr);
+        // RFC 4122 v4
+        arr[6] = (arr[6] & 0x0f) | 0x40;
+        arr[8] = (arr[8] & 0x3f) | 0x80;
+        var hex = Array.from(arr, function (b) { return b.toString(16).padStart(2, '0'); });
+        return (hex.slice(0, 4).join('') +
+            '-' +
+            hex.slice(4, 6).join('') +
+            '-' +
+            hex.slice(6, 8).join('') +
+            '-' +
+            hex.slice(8, 10).join('') +
+            '-' +
+            hex.slice(10, 16).join(''));
+    }
+    // 退化实现
+    var d = Date.now();
+    var d2 = (typeof performance !== 'undefined' && performance.now && performance.now() * 1000) || 0;
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        var r = Math.random() * 16;
+        if (d > 0) {
+            r = (d + r) % 16 | 0;
+            d = Math.floor(d / 16);
+        }
+        else {
+            r = (d2 + r) % 16 | 0;
+            d2 = Math.floor(d2 / 16);
+        }
+        return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+
+/**
+ * session-event 插件：会话管理
+ *  - 每条事件附 $event_session_id（首次访问生成，存 storage）
+ *  - $session_start / $session_end 事件
+ *  - 超时（默认 30 分钟）则重开会话
+ */
+var SESSION_KEY = 'et_session_id';
+var SESSION_LAST_KEY = 'et_session_last_active';
+var DEFAULT_TIMEOUT = 30 * 60 * 1000; // 30 分钟
+function sessionEvent(opts) {
+    var _a;
+    if (opts === void 0) { opts = {}; }
+    var timeout = (_a = opts.timeout) !== null && _a !== void 0 ? _a : DEFAULT_TIMEOUT;
+    var sdkRef = null;
+    var storeRef = null;
+    var sessionId = '';
+    var lastActive = 0;
+    function newSession(reason) {
+        sessionId = uuidv4();
+        lastActive = Date.now();
+        if (storeRef) {
+            storeRef.set(SESSION_KEY, sessionId);
+            storeRef.set(SESSION_LAST_KEY, String(lastActive));
+        }
+        if (sdkRef && reason === 'start') {
+            sdkRef.track('$session_start', { $event_session_id: sessionId });
+        }
+    }
+    function check() {
+        var now = Date.now();
+        if (!sessionId || (lastActive && now - lastActive > timeout)) {
+            newSession(now - lastActive > timeout ? 'timeout' : 'start');
+        }
+        lastActive = now;
+        if (storeRef)
+            storeRef.set(SESSION_LAST_KEY, String(lastActive));
+    }
+    var interceptor = {
+        name: 'session-event',
+        priority: 10, // 早于业务拦截器
+        entry: function (ctx) {
+            if (ctx.meta.stage !== 'buildDataStage')
+                return;
+            check();
+            var ev = ctx.data;
+            if (ev && ev.properties) {
+                ev.properties[PresetProperty.EventSessionId] = sessionId;
+            }
+        },
+    };
+    return {
+        name: 'session-event',
+        install: function (_a) {
+            var sdk = _a.sdk, stages = _a.stages, store = _a.store;
+            if (!isBrowser())
+                return;
+            sdkRef = sdk;
+            storeRef = store;
+            // 读已有
+            var existing = store.get(SESSION_KEY);
+            var last = Number(store.get(SESSION_LAST_KEY) || '0');
+            if (existing && last && Date.now() - last < timeout) {
+                sessionId = existing;
+                lastActive = last;
+            }
+            else {
+                newSession('start');
+            }
+            stages.buildDataStage.register(interceptor);
+            // 跨 tab 同步：通过 storage 事件检测其它 tab 关闭
+            window.addEventListener('storage', function (ev) {
+                if (ev.key === SESSION_KEY && !ev.newValue) {
+                    // 其它 tab 关闭了会话，本地也清掉
+                    sessionId = '';
+                }
+            });
+        },
+        uninstall: function () {
+            sdkRef = null;
+            storeRef = null;
+        },
+    };
+}
+
+export { sessionEvent };

package/dist/plugin/webview-bridge.cjs

@@ -0,0 +1,111 @@
+'use strict';
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+function __spreadArray(to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+/**
+ * 浏览器端辅助方法
+ */
+function isBrowser() {
+    return typeof window !== 'undefined' && typeof window.document !== 'undefined';
+}
+
+/**
+ * WebView 桥（vapph5 协议）
+ *  - 客户端（iOS/Android）注入 window.vapph5define 对象
+ *  - H5 通过 vapph5define.call(name, args) 调用客户端方法
+ *  - 客户端通过 vapph5define.handle(name, fn) 监听 H5 调用
+ *
+ * 本插件负责：
+ *  1. 探测 WebView 标识
+ *  2. 在 SDK 启动时调用 vapph5define.call('getAppInfo')，把 app_version/app_id/...
+ *     注入到 config 与公共属性
+ *  3. 暴露 helper：bridge.call(name, args) 与 bridge.on(name, fn)
+ */
+function webviewBridge(opts) {
+    if (opts === void 0) { opts = {}; }
+    return {
+        name: 'webview-bridge',
+        install: function (_a) {
+            var sdk = _a.sdk, config = _a.config;
+            if (!isBrowser())
+                return;
+            var win = window;
+            var defineName = opts.defineName || 'vapph5define';
+            var define = win[defineName];
+            if (!define || typeof define.call !== 'function') {
+                return; // 不在 WebView 中
+            }
+            // 暴露 SDK 内部调用的便捷方法
+            var bridge = {
+                call: function (name) {
+                    var args = [];
+                    for (var _i = 1; _i < arguments.length; _i++) {
+                        args[_i - 1] = arguments[_i];
+                    }
+                    return define.call.apply(define, __spreadArray([name], args, false));
+                },
+                on: function (name, fn) { return define.handle(name, fn); },
+                isInApp: function () { return define.isInApp === true || define.call('isInApp') === true; },
+            };
+            sdk.bridge = bridge;
+            config.is_webview = true;
+            if (opts.fetchOnInit !== false) {
+                try {
+                    var protocolName = opts.protocolName || 'getAppInfo';
+                    var result = define.call(protocolName);
+                    if (result && typeof result === 'object') {
+                        var fm = opts.fieldMap || {};
+                        for (var _i = 0, _b = Object.entries(fm); _i < _b.length; _i++) {
+                            var _c = _b[_i], sdkKey = _c[0], resultKey = _c[1];
+                            var v = result[resultKey];
+                            if (v !== undefined && v !== null) {
+                                config[sdkKey] = v;
+                            }
+                        }
+                        sdk.register({
+                            $app_version: result.app_version || result.appVersion,
+                            $app_id: result.app_id || result.appId,
+                            $channel: result.channel,
+                            $lib: result.lib || result.lib_name || result.libName,
+                        });
+                    }
+                }
+                catch (_d) {
+                    /* ignore */
+                }
+            }
+        },
+    };
+}
+
+exports.webviewBridge = webviewBridge;

package/dist/plugin/webview-bridge.mjs

@@ -0,0 +1,109 @@
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+function __spreadArray(to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+/**
+ * 浏览器端辅助方法
+ */
+function isBrowser() {
+    return typeof window !== 'undefined' && typeof window.document !== 'undefined';
+}
+
+/**
+ * WebView 桥（vapph5 协议）
+ *  - 客户端（iOS/Android）注入 window.vapph5define 对象
+ *  - H5 通过 vapph5define.call(name, args) 调用客户端方法
+ *  - 客户端通过 vapph5define.handle(name, fn) 监听 H5 调用
+ *
+ * 本插件负责：
+ *  1. 探测 WebView 标识
+ *  2. 在 SDK 启动时调用 vapph5define.call('getAppInfo')，把 app_version/app_id/...
+ *     注入到 config 与公共属性
+ *  3. 暴露 helper：bridge.call(name, args) 与 bridge.on(name, fn)
+ */
+function webviewBridge(opts) {
+    if (opts === void 0) { opts = {}; }
+    return {
+        name: 'webview-bridge',
+        install: function (_a) {
+            var sdk = _a.sdk, config = _a.config;
+            if (!isBrowser())
+                return;
+            var win = window;
+            var defineName = opts.defineName || 'vapph5define';
+            var define = win[defineName];
+            if (!define || typeof define.call !== 'function') {
+                return; // 不在 WebView 中
+            }
+            // 暴露 SDK 内部调用的便捷方法
+            var bridge = {
+                call: function (name) {
+                    var args = [];
+                    for (var _i = 1; _i < arguments.length; _i++) {
+                        args[_i - 1] = arguments[_i];
+                    }
+                    return define.call.apply(define, __spreadArray([name], args, false));
+                },
+                on: function (name, fn) { return define.handle(name, fn); },
+                isInApp: function () { return define.isInApp === true || define.call('isInApp') === true; },
+            };
+            sdk.bridge = bridge;
+            config.is_webview = true;
+            if (opts.fetchOnInit !== false) {
+                try {
+                    var protocolName = opts.protocolName || 'getAppInfo';
+                    var result = define.call(protocolName);
+                    if (result && typeof result === 'object') {
+                        var fm = opts.fieldMap || {};
+                        for (var _i = 0, _b = Object.entries(fm); _i < _b.length; _i++) {
+                            var _c = _b[_i], sdkKey = _c[0], resultKey = _c[1];
+                            var v = result[resultKey];
+                            if (v !== undefined && v !== null) {
+                                config[sdkKey] = v;
+                            }
+                        }
+                        sdk.register({
+                            $app_version: result.app_version || result.appVersion,
+                            $app_id: result.app_id || result.appId,
+                            $channel: result.channel,
+                            $lib: result.lib || result.lib_name || result.libName,
+                        });
+                    }
+                }
+                catch (_d) {
+                    /* ignore */
+                }
+            }
+        },
+    };
+}
+
+export { webviewBridge };

package/dist/types/core/env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 浏览器端辅助方法
+ */
+export declare function isBrowser(): boolean;
+export declare function hasLocalStorage(): boolean;
+export declare function hasSessionStorage(): boolean;
+export declare function hasCookie(): boolean;
+export declare function hasBeacon(): boolean;
+export declare function hasFetch(): boolean;
+export declare function hasImage(): boolean;

package/dist/types/core/errors.d.ts

@@ -0,0 +1,76 @@
+/**
+ * SDK 统一错误类型（v1.1）
+ *
+ * 所有内部 / 暴露给用户的错误都继承 SDKError，带 code 字段方便用户处理：
+ *   - SDKError
+ *     ├── InitError        配置错误（缺 server_url 等）
+ *     ├── SendError        发送失败
+ *     ├── EncryptError     加密 / 解密失败
+ *     ├── IdentityError    身份 / ID 操作失败
+ *     ├── StorageError     存储读写失败
+ *     ├── PluginError      插件 install / uninstall 失败
+ *     └── ConfigError      配置校验失败
+ */
+/** 基类 */
+export declare class SDKError extends Error {
+    /** 错误码 */
+    readonly code: string;
+    /** 原始错误 */
+    readonly cause?: unknown;
+    /** 出错时间戳 */
+    readonly timestamp: number;
+    /** 上下文（带最少 1KB 容量） */
+    readonly context?: Record<string, unknown>;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+    /** 序列化为对象（方便日志） */
+    toJSON(): Record<string, unknown>;
+}
+export declare class InitError extends SDKError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+export declare class SendError extends SDKError {
+    readonly attempts: number;
+    constructor(message: string, attempts: number, options?: {
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+export declare class EncryptError extends SDKError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+export declare class IdentityError extends SDKError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+export declare class StorageError extends SDKError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+export declare class PluginError extends SDKError {
+    readonly plugin: string;
+    constructor(plugin: string, message: string, options?: {
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+export declare class ConfigError extends SDKError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+/** 判断是否是 SDKError */
+export declare function isSDKError(e: unknown): e is SDKError;

package/dist/types/core/failed-queue.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 失败队列
+ *  - 失败事件写入 localStorage（et_failed_queue）
+ *  - 下次启动时优先 flush
+ *  - 上限 50 条
+ */
+import type { EventData } from '../types/index.js';
+import { encodeBatch } from '../send/encode.js';
+export declare class FailedQueue {
+    private config;
+    constructor(config?: {
+        max?: number;
+        encryptor?: (s: string) => string | Promise<string>;
+    });
+    /** 读队列 */
+    read(): EventData[];
+    /** 写一条 */
+    enqueue(event: EventData): void;
+    /** 清空 */
+    clear(): void;
+    /** 取走全部（同时清空） */
+    takeAll(): EventData[];
+}
+export { encodeBatch };

package/dist/types/core/identity-api.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 身份 API（v1.1.1）
+ */
+import type { EventTracker } from '../core/tracker.js';
+import type { IdentityManager } from '../core/identity.js';
+export declare function attachIdentityApi(sdk: EventTracker, identity: IdentityManager): void;

package/dist/types/core/identity.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 用户身份管理
+ *  - distinct_id   业务用户 ID
+ *  - anonymous_id  匿名 ID（首次访问生成，永不重置）
+ *  - first_id      首次访问 ID
+ */
+import type { KVStore } from '../storage/store.js';
+export declare class IdentityManager {
+    private store;
+    private opts;
+    private distinctId;
+    private anonymousId;
+    private firstId;
+    private loginId;
+    private originalId;
+    constructor(store: KVStore, opts?: {
+        getDistinctId?: () => string;
+        setDistinctId?: (id: string) => void;
+        getAnonymousId?: () => string;
+        setAnonymousId?: (id: string) => void;
+        getFirstId?: () => string;
+        setFirstId?: (id: string) => void;
+    });
+    private readOrCreate;
+    private persist;
+    getDistinctId(): string;
+    getAnonymousId(): string;
+    getFirstId(): string;
+    getLoginId(): string;
+    getOriginalId(): string;
+    /** 设置业务用户 ID（保留 anonymous/first 关系） */
+    identify(distinctId: string, isSave?: boolean): void;
+    /** 重置：业务用户登出，回到匿名 */
+    resetAnonymousIdentity(newAnonymousId?: string): void;
+    /** 登入：等价 identify */
+    login(loginId: string): void;
+    /** 登出：保留 anonymous，重置 distinct */
+    logout(): void;
+}