@yunzhimao/telemetry 0.2.0

package/README.md

@@ -0,0 +1,60 @@
+# @yunzhimao/telemetry
+
+通用行为采集 SDK，当前 `0.2.0` 是待联调版本，尚未发布到 npm。只采集显式行为，不自动捕获 DOM、URL、请求内容或异常。
+
+## 浏览器
+
+```ts
+import { createBrowserTracker } from '@yunzhimao/telemetry/browser';
+
+// 宿主使用自己的登录态访问自己的后端；返回 TokenSession + endpoint。
+const session = await getHostTelemetrySession();
+const tracker = createBrowserTracker({
+  identity: session.identity,
+  endpoint: session.endpoint,
+  appVersion: 'example-1.0.0',
+  getToken: () => getHostTelemetrySession(),
+});
+void tracker.active(); // 仅在已登录用户实际可见访问时调用。
+void tracker.track('listing.collect.opened', { });
+void tracker.track('listing.collect.submitted');
+```
+
+`identity` 必须来自宿主后端登录上下文。收到不同身份的 Token 时 SDK 清空队列并暂停，不能用新账号补发旧事件。退出、账号/主体/实例切换先 `await tracker.reset()` 再 `await tracker.destroy()`，之后创建新实例；宿主应在网络结果回来后再次核对登录身份，避免异步初始化串号。
+
+## 插件 / 无 DOM 环境
+
+```ts
+import { createTracker, extensionStorage } from '@yunzhimao/telemetry/extension';
+const tracker = createTracker({
+  identity: session.identity, endpoint: session.endpoint, appVersion: 'example-1.0.0',
+  getToken: getHostTelemetrySession,
+  storage: extensionStorage(chrome.storage.local),
+  flushIntervalMs: 0,
+});
+await tracker.ready;
+await tracker.track('listing.collect.submitted', { });
+void tracker.flush();
+```
+
+只有 background 获取 Token、创建 SDK 和发送。content script / popup 通过受控内部消息提交固定 eventName和基础设备信息，不能得到 Token；后台验证 sender 和字段。新事件或唤醒时恢复队列并 flush，不能靠 `setInterval` 保证 MV3 常驻。安装标识可由宿主持久化后通过 `anonymousId` 注入。业务流程不要等待 `flush()`；内部消息在 `track()` 持久化完成后可确认接收。
+
+## 行为与边界
+
+- `eventName` 是唯一点位 key，例如 `listing.collect.opened` / `listing.collect.submitted`；保留 `app.active`。业务目录由宿主与 Collector 维护，SDK 不携带 ERP 字典。属性只能发送该点位目录声明的字段，不传用户对象或任意业务数据。
+- 默认 20 条 / 10 秒，最多 500 条 / 1 MiB / 24 小时；溢出丢最旧项。只收到 `200` 且 `accepted` 等于批次条数后出队。
+- 401 最多立即续取一次，429 遵守 Retry-After，网络/5xx 有界退避；413 拆批，422 按索引丢弃坏事件。
+- Token 只在内存中，不进入离线队列；事件重试保持 eventId 和原始时间。安装标识不是设备指纹，行为不是可信业务结算依据。
+- `track()` 不等待网络且不向业务抛采集错误；存储失败退回内存。`onDiagnostic(code, count)` 不含原始事件或 Token。
+- `destroy()` 卸载监听/定时器并保留队列；退出登录必须先 `reset()` 清队列。关页发送仅尽力而为，关闭标签页的未发送快照不承诺由其他标签页补发，过期后清理。
+- 默认入口仅依赖现代运行时的 fetch、TextEncoder、crypto.randomUUID；浏览器子路径要求 DOM 和 IndexedDB，插件 storage 由调用方注入；无 Vue/Pinia/CRM 商业依赖。
+
+## 验证与发布
+
+在仓库根目录运行 `pnpm --filter @yunzhimao/telemetry test`。`pnpm --filter @yunzhimao/telemetry pack --pack-destination .tmp` 只生成本地包，不发布。包内容限定为 ESM dist、CommonJS cjs、类型声明和本说明。
+
+发布前确认 npm scope 所属、公开/私有可见性，三个宿主安装同一 tarball 验证后再使用固定版本号。不要把私钥、环境配置、内部服务端包或其他仓库打入包。
+
+## ERP 后端 / Node
+
+默认入口同时提供 ESM import 和 CommonJS require，要求 Node 22.12+，使用同一个 `createTracker`；按可信登录账号隔离队列，禁止跨账号共享 tracker。后端只报告目录中的处理结果，不调用 `active()`、不带用户设备，不把服务器出口当用户地域。ERP 适配层最多 100 个账号队列，每账号 50 条 / 64 KiB，闲置 5 分钟销毁；无磁盘队列，不保证零丢失。

package/cjs/browser.d.ts

@@ -0,0 +1,12 @@
+import type { DeviceInfo, QueueStorage, TrackerOptions } from './types.js';
+/** 只采集基础设备属性；不读取 URL、DOM 内容、Token 或指纹。 */
+export declare function browserDevice(): DeviceInfo;
+export declare function indexedDbStorage(namespace?: string): QueueStorage;
+export declare function createBrowserTracker(options: TrackerOptions): {
+    destroy(): Promise<void>;
+    ready: Promise<void>;
+    track: (eventName: import("./types.js").EventName, input?: import("./types.js").TrackInput) => Promise<void>;
+    flush: () => Promise<void>;
+    active(): Promise<void>;
+    reset(identity?: import("./types.js").TelemetryIdentity): Promise<void>;
+};

package/cjs/browser.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserDevice = browserDevice;
+exports.indexedDbStorage = indexedDbStorage;
+exports.createBrowserTracker = createBrowserTracker;
+const index_js_1 = require("./index.js");
+/** 只采集基础设备属性；不读取 URL、DOM 内容、Token 或指纹。 */
+function browserDevice() {
+    if (typeof navigator === 'undefined')
+        return {};
+    const ua = navigator.userAgent;
+    const browser = /Edg\/([\d.]+)/.exec(ua) ?? /Firefox\/([\d.]+)/.exec(ua) ?? /Chrome\/([\d.]+)/.exec(ua) ?? /Version\/([\d.]+).*Safari/.exec(ua);
+    const os = /Windows NT ([\d.]+)/.exec(ua) ?? /Android ([\d.]+)/.exec(ua) ?? /(?:iPhone OS|CPU OS) ([\d_]+)/.exec(ua) ?? /Mac OS X ([\d_]+)/.exec(ua);
+    return {
+        type: /iPad|Tablet/i.test(ua) ? 'tablet' : /Mobile|iPhone/i.test(ua) ? 'mobile' : 'desktop',
+        browser: /Edg\//.test(ua) ? 'Edge' : /Firefox\//.test(ua) ? 'Firefox' : /Chrome\//.test(ua) ? 'Chrome' : /Safari\//.test(ua) ? 'Safari' : 'unknown',
+        browserVersion: browser?.[1] ?? '',
+        os: /Windows/.test(ua) ? 'Windows' : /Android/.test(ua) ? 'Android' : /iPhone|iPad/.test(ua) ? 'iOS' : /Mac OS/.test(ua) ? 'macOS' : /Linux/.test(ua) ? 'Linux' : 'unknown',
+        osVersion: os?.[1]?.replaceAll('_', '.') ?? '', language: navigator.language,
+        ...(typeof screen === 'undefined' ? {} : { screenWidth: screen.width, screenHeight: screen.height }),
+    };
+}
+function indexedDbStorage(namespace = 'yzm-telemetry') {
+    // 每个标签页独立队列，避免多个页面读改写同一个快照导致相互覆盖。
+    let tab = globalThis.crypto.randomUUID();
+    try {
+        const tabKey = `${namespace}:tab`;
+        tab = sessionStorage.getItem(tabKey) ?? tab;
+        sessionStorage.setItem(tabKey, tab);
+    }
+    catch { /* 隐私模式由存储失败诊断和内存队列降级。 */ }
+    const open = () => new Promise((resolve, reject) => {
+        const request = indexedDB.open(namespace, 1);
+        request.onupgradeneeded = () => request.result.createObjectStore('queues');
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(new Error('storage_failed'));
+    });
+    async function run(mode, action) {
+        const db = await open();
+        try {
+            return await new Promise((resolve, reject) => {
+                const tx = db.transaction('queues', mode);
+                const request = action(tx.objectStore('queues'));
+                tx.oncomplete = () => resolve(request.result);
+                tx.onabort = tx.onerror = () => reject(new Error('storage_failed'));
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    return {
+        load: async () => {
+            // 清除关闭标签页遗留的过期快照，避免长期使用积累无界的离线记录。
+            await run('readwrite', (store) => {
+                const cursor = store.openCursor();
+                cursor.onsuccess = () => {
+                    const row = cursor.result;
+                    if (!row)
+                        return;
+                    const saved = row.value;
+                    if (!saved.events?.some((event) => Date.parse(event.occurredAt) >= Date.now() - 86400000))
+                        row.delete();
+                    row.continue();
+                };
+                return cursor;
+            });
+            return (await run('readonly', (store) => store.get(tab)));
+        },
+        save: async (value) => {
+            if (value.events.length)
+                await run('readwrite', (store) => store.put(value, tab));
+            else
+                await run('readwrite', (store) => store.delete(tab));
+        },
+    };
+}
+function createBrowserTracker(options) {
+    let anonymousId = options.anonymousId;
+    try {
+        anonymousId ??= localStorage.getItem('yzm-telemetry:installation') ?? globalThis.crypto.randomUUID();
+        localStorage.setItem('yzm-telemetry:installation', anonymousId);
+    }
+    catch { /* 不支持持久化时使用本次会话随机标识。 */ }
+    const tracker = (0, index_js_1.createTracker)({ ...options, anonymousId, device: options.device ?? browserDevice(), storage: options.storage ?? indexedDbStorage() });
+    const flush = () => { void tracker.flush(); };
+    document.addEventListener('visibilitychange', flush);
+    window.addEventListener('pagehide', flush);
+    window.addEventListener('online', flush);
+    return {
+        ...tracker,
+        destroy() {
+            document.removeEventListener('visibilitychange', flush);
+            window.removeEventListener('pagehide', flush);
+            window.removeEventListener('online', flush);
+            return tracker.destroy();
+        },
+    };
+}

package/cjs/extension.d.ts

@@ -0,0 +1,8 @@
+import type { QueueStorage } from './types.js';
+export { createTracker } from './index.js';
+export type * from './types.js';
+/** 在插件 background 注入 chrome.storage.local，不在公共入口绑定 Chrome 全局对象。 */
+export declare function extensionStorage(storage: {
+    get(key: string): Promise<Record<string, unknown>>;
+    set(items: Record<string, unknown>): Promise<void>;
+}, namespace?: string): QueueStorage;

package/cjs/extension.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTracker = void 0;
+exports.extensionStorage = extensionStorage;
+var index_js_1 = require("./index.js");
+Object.defineProperty(exports, "createTracker", { enumerable: true, get: function () { return index_js_1.createTracker; } });
+/** 在插件 background 注入 chrome.storage.local，不在公共入口绑定 Chrome 全局对象。 */
+function extensionStorage(storage, namespace = 'yzm-telemetry-queue') {
+    return {
+        load: async () => (await storage.get(namespace))[namespace],
+        save: async (queue) => { await storage.set({ [namespace]: queue }); },
+    };
+}

package/cjs/index.d.ts

@@ -0,0 +1,14 @@
+import type { EventName, TelemetryIdentity, TrackInput, TrackerOptions } from './types.js';
+export type { BehaviorEvent, DeviceInfo, EventName, QueueStorage, SourceApp, StoredQueue, TelemetryIdentity, TokenSession, TrackInput, TrackerOptions } from './types.js';
+export declare const SDK_VERSION = "0.2.0";
+export declare const identityKey: (identity: TelemetryIdentity) => string;
+/** 与宿主登录解耦；先绑定身份，异步请求只负责采集授权，不能改变队列归属。 */
+export declare function createTracker(options: TrackerOptions): {
+    ready: Promise<void>;
+    track: (eventName: EventName, input?: TrackInput) => Promise<void>;
+    flush: () => Promise<void>;
+    /** 只由宿主真实可见访问/交互调用，不自动通过心跳制造日活。 */
+    active(): Promise<void>;
+    reset(identity?: TelemetryIdentity): Promise<void>;
+    destroy(): Promise<void>;
+};

package/cjs/index.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identityKey = exports.SDK_VERSION = void 0;
+exports.createTracker = createTracker;
+exports.SDK_VERSION = '0.2.0';
+/** 至少“领域.行为.动作”三段；活跃为协议保留名，不再接受旧通用事件名。 */
+const validEventName = (name) => typeof name === 'string' &&
+    name.length <= 100 && (name === 'app.active' || /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,}$/.test(name));
+const identityKey = (identity) => JSON.stringify([
+    identity.applicationId, identity.instanceId, identity.sourceApp, identity.actorId, identity.externalOrganizationId,
+]);
+exports.identityKey = identityKey;
+/** 与宿主登录解耦；先绑定身份，异步请求只负责采集授权，不能改变队列归属。 */
+function createTracker(options) {
+    const now = options.now ?? Date.now;
+    const randomId = options.randomId ?? (() => globalThis.crypto.randomUUID());
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const anonymousId = options.anonymousId ?? randomId();
+    const sessionId = randomId();
+    let key = (0, exports.identityKey)(options.identity);
+    let events = [];
+    let session;
+    let generation = 0;
+    let destroyed = false;
+    let blocked = false;
+    let pending;
+    let storageWrites = Promise.resolve();
+    let abort;
+    let failures = 0;
+    let nextAttemptAt = 0;
+    let activeDay = '';
+    let batchSize = Math.max(1, Math.min(options.batchSize ?? 20, 100));
+    const maxAge = Math.min(options.maxAgeMs ?? 86_400_000, 86_400_000);
+    const diagnose = (code, count = 1) => {
+        try {
+            options.onDiagnostic?.(code, count);
+        }
+        catch { /* 诊断回调不能干扰宿主业务。 */ }
+    };
+    const bytes = (value) => new TextEncoder().encode(JSON.stringify(value)).length;
+    function trim() {
+        const before = events.length;
+        events = events.filter((event) => Date.parse(event.occurredAt) >= now() - maxAge);
+        const limit = Math.max(1, Math.min(options.maxQueueEvents ?? 500, 500));
+        const byteLimit = Math.max(8192, Math.min(options.maxQueueBytes ?? 1048576, 1048576));
+        while (events.length > limit || (events.length && bytes(events) > byteLimit))
+            events.shift();
+        if (before > events.length)
+            diagnose('queue_dropped', before - events.length);
+    }
+    function persist() {
+        const snapshot = JSON.parse(JSON.stringify({ identityKey: key, events }));
+        // 串行落盘，防止旧快照晚于 reset 完成而把旧账号队列恢复回来。
+        storageWrites = storageWrites.then(() => options.storage?.save(snapshot)).catch(() => diagnose('storage_failed'));
+        return storageWrites;
+    }
+    const ready = (async () => {
+        try {
+            const saved = await options.storage?.load();
+            if (destroyed || generation !== 0)
+                return;
+            if (saved?.identityKey === key && Array.isArray(saved.events)) {
+                events = saved.events.filter((item) => item && typeof item.eventId === 'string' && typeof item.occurredAt === 'string' && validEventName(item.eventName));
+                trim();
+            }
+        }
+        catch {
+            diagnose('storage_failed');
+        }
+    })();
+    async function token(force, version) {
+        if (force || !session || Date.parse(session.expiresAt) <= now() + 10_000) {
+            const fresh = await options.getToken(force);
+            if (version !== generation || destroyed)
+                return null;
+            if ((0, exports.identityKey)(fresh.identity) !== key) {
+                blocked = true;
+                events = [];
+                await persist();
+                diagnose('identity_changed');
+                return null;
+            }
+            if (!fresh.token || !Number.isFinite(Date.parse(fresh.expiresAt)) || Date.parse(fresh.expiresAt) <= now()) {
+                throw new Error('invalid_session');
+            }
+            session = fresh;
+        }
+        return session.token;
+    }
+    function backoff(retryAfter = 0) {
+        failures++;
+        nextAttemptAt = now() + Math.max(retryAfter, Math.min(60_000, 1000 * 2 ** Math.min(failures, 6)) * (0.8 + Math.random() * 0.4));
+    }
+    async function sendLoop() {
+        await ready;
+        const version = generation;
+        if (destroyed || blocked || now() < nextAttemptAt)
+            return;
+        trim();
+        await persist();
+        while (events.length && version === generation && !destroyed && !blocked) {
+            const batch = events.slice(0, batchSize);
+            const ids = new Set(batch.map((event) => event.eventId));
+            try {
+                let bearer = await token(false, version);
+                if (!bearer)
+                    return;
+                let response;
+                for (let attempt = 0; attempt < 2; attempt++) {
+                    if (version !== generation || destroyed)
+                        return;
+                    abort = new AbortController();
+                    const timeout = setTimeout(() => abort?.abort(), 20_000);
+                    try {
+                        response = await fetcher(options.endpoint, {
+                            method: 'POST', credentials: 'omit',
+                            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${bearer}` },
+                            body: JSON.stringify({ events: batch }), signal: abort.signal,
+                        });
+                    }
+                    finally {
+                        clearTimeout(timeout);
+                    }
+                    if (response.status !== 401 || attempt === 1)
+                        break;
+                    bearer = await token(true, version);
+                    if (!bearer)
+                        return;
+                }
+                if (version !== generation || destroyed || !response)
+                    return;
+                if (response.status === 200) {
+                    const result = await response.json();
+                    if (version !== generation || destroyed)
+                        return;
+                    if (result.accepted !== batch.length)
+                        throw new Error('invalid_ack');
+                    events = events.filter((event) => !ids.has(event.eventId));
+                    failures = 0;
+                    nextAttemptAt = 0;
+                }
+                else if (response.status === 413 && batch.length > 1) {
+                    batchSize = Math.max(1, Math.floor(batch.length / 2));
+                    continue;
+                }
+                else if ([400, 413, 422].includes(response.status)) {
+                    const result = await response.json().catch(() => ({}));
+                    if (version !== generation || destroyed)
+                        return;
+                    const indices = Array.isArray(result.invalidIndices)
+                        ? result.invalidIndices.filter((i) => Number.isInteger(i) && i >= 0 && i < batch.length) : [];
+                    const invalid = indices.length ? new Set(indices.map((i) => batch[i].eventId)) : ids;
+                    events = events.filter((event) => !invalid.has(event.eventId));
+                    diagnose('invalid_event', invalid.size);
+                }
+                else if (response.status === 403) {
+                    blocked = true;
+                    diagnose('forbidden');
+                    return;
+                }
+                else {
+                    const retryHeader = response.headers.get('Retry-After');
+                    const retryAfter = retryHeader && /^\d+$/.test(retryHeader)
+                        ? Number(retryHeader) * 1000 : Math.max(0, Date.parse(retryHeader ?? '') - now()) || 0;
+                    backoff(retryAfter);
+                    diagnose(`http_${response.status}`);
+                    return;
+                }
+                await persist();
+            }
+            catch {
+                if (version === generation && !destroyed) {
+                    backoff();
+                    diagnose('send_failed');
+                }
+                return;
+            }
+        }
+    }
+    function flush() {
+        if (!pending)
+            pending = sendLoop().catch(() => diagnose('send_failed')).finally(() => { pending = undefined; });
+        return pending;
+    }
+    async function track(eventName, input = {}) {
+        const version = generation;
+        try {
+            await ready;
+            if (destroyed || blocked || version !== generation)
+                return;
+            if (!validEventName(eventName)) {
+                diagnose('invalid_event_name');
+                return;
+            }
+            const event = {
+                eventId: randomId(), recordType: 'event', eventName, eventVersion: 1,
+                occurredAt: new Date(now()).toISOString(), anonymousId, sessionId,
+                appVersion: options.appVersion, sdkVersion: exports.SDK_VERSION,
+                ...(input.device ?? options.device ? { device: input.device ?? options.device } : {}),
+                ...(input.properties ? { properties: input.properties } : {}),
+            };
+            // 拷贝调用方对象，避免业务代码在入队后修改已产生事件。
+            if (bytes(event) > 8192) {
+                diagnose('event_too_large');
+                return;
+            }
+            events.push(JSON.parse(JSON.stringify(event)));
+            trim();
+            await persist();
+            if (events.length >= batchSize)
+                void flush();
+        }
+        catch {
+            diagnose('track_failed');
+        }
+    }
+    const interval = options.flushIntervalMs === 0 ? undefined : setInterval(() => { void flush(); }, Math.max(100, options.flushIntervalMs ?? 10000));
+    return {
+        ready, track, flush,
+        /** 只由宿主真实可见访问/交互调用，不自动通过心跳制造日活。 */
+        active() {
+            if (options.identity.sourceApp === 'erp_backend')
+                return Promise.resolve();
+            const day = new Date(now() + 8 * 3600_000).toISOString().slice(0, 10);
+            if (day === activeDay)
+                return Promise.resolve();
+            activeDay = day;
+            return track('app.active');
+        },
+        async reset(identity) {
+            generation++;
+            abort?.abort();
+            session = undefined;
+            events = [];
+            activeDay = '';
+            blocked = false;
+            failures = 0;
+            nextAttemptAt = 0;
+            if (identity)
+                key = (0, exports.identityKey)(identity);
+            await ready;
+            await persist();
+        },
+        async destroy() {
+            destroyed = true;
+            generation++;
+            abort?.abort();
+            if (interval !== undefined)
+                clearInterval(interval);
+            await ready;
+            await persist();
+        },
+    };
+}

package/cjs/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/cjs/types.d.ts

@@ -0,0 +1,69 @@
+export type SourceApp = 'erp_web' | 'erp_backend' | 'plugin';
+/** 事件名就是唯一点位 key；具体业务目录由宿主与 Collector 维护。 */
+export type EventName = string;
+export interface TelemetryIdentity {
+    applicationId: string;
+    instanceId: string;
+    sourceApp: SourceApp;
+    actorId: string;
+    externalOrganizationId: string;
+}
+export interface DeviceInfo {
+    type?: string;
+    os?: string;
+    osVersion?: string;
+    browser?: string;
+    browserVersion?: string;
+    language?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+}
+export interface BehaviorEvent {
+    eventId: string;
+    recordType: 'event';
+    eventName: EventName;
+    eventVersion: 1;
+    occurredAt: string;
+    anonymousId: string;
+    sessionId: string;
+    appVersion: string;
+    sdkVersion: string;
+    device?: DeviceInfo;
+    properties?: Record<string, string | number | boolean>;
+}
+export interface TokenSession {
+    token: string;
+    expiresAt: string;
+    identity: TelemetryIdentity;
+}
+export interface StoredQueue {
+    identityKey: string;
+    events: BehaviorEvent[];
+}
+/** 存储只保存事件和非敏感身份键，不允许保存采集 Token。 */
+export interface QueueStorage {
+    load(): Promise<StoredQueue | null>;
+    save(queue: StoredQueue): Promise<void>;
+}
+export interface TrackInput {
+    properties?: BehaviorEvent['properties'];
+    device?: DeviceInfo;
+}
+export interface TrackerOptions {
+    endpoint: string;
+    identity: TelemetryIdentity;
+    getToken: (forceRefresh: boolean) => Promise<TokenSession>;
+    storage?: QueueStorage;
+    appVersion: string;
+    anonymousId?: string;
+    device?: DeviceInfo;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    maxQueueEvents?: number;
+    maxQueueBytes?: number;
+    maxAgeMs?: number;
+    fetch?: typeof globalThis.fetch;
+    now?: () => number;
+    randomId?: () => string;
+    onDiagnostic?: (code: string, count: number) => void;
+}

package/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/browser.d.ts

@@ -0,0 +1,12 @@
+import type { DeviceInfo, QueueStorage, TrackerOptions } from './types.js';
+/** 只采集基础设备属性；不读取 URL、DOM 内容、Token 或指纹。 */
+export declare function browserDevice(): DeviceInfo;
+export declare function indexedDbStorage(namespace?: string): QueueStorage;
+export declare function createBrowserTracker(options: TrackerOptions): {
+    destroy(): Promise<void>;
+    ready: Promise<void>;
+    track: (eventName: import("./types.js").EventName, input?: import("./types.js").TrackInput) => Promise<void>;
+    flush: () => Promise<void>;
+    active(): Promise<void>;
+    reset(identity?: import("./types.js").TelemetryIdentity): Promise<void>;
+};

package/dist/browser.js

@@ -0,0 +1,94 @@
+import { createTracker } from './index.js';
+/** 只采集基础设备属性；不读取 URL、DOM 内容、Token 或指纹。 */
+export function browserDevice() {
+    if (typeof navigator === 'undefined')
+        return {};
+    const ua = navigator.userAgent;
+    const browser = /Edg\/([\d.]+)/.exec(ua) ?? /Firefox\/([\d.]+)/.exec(ua) ?? /Chrome\/([\d.]+)/.exec(ua) ?? /Version\/([\d.]+).*Safari/.exec(ua);
+    const os = /Windows NT ([\d.]+)/.exec(ua) ?? /Android ([\d.]+)/.exec(ua) ?? /(?:iPhone OS|CPU OS) ([\d_]+)/.exec(ua) ?? /Mac OS X ([\d_]+)/.exec(ua);
+    return {
+        type: /iPad|Tablet/i.test(ua) ? 'tablet' : /Mobile|iPhone/i.test(ua) ? 'mobile' : 'desktop',
+        browser: /Edg\//.test(ua) ? 'Edge' : /Firefox\//.test(ua) ? 'Firefox' : /Chrome\//.test(ua) ? 'Chrome' : /Safari\//.test(ua) ? 'Safari' : 'unknown',
+        browserVersion: browser?.[1] ?? '',
+        os: /Windows/.test(ua) ? 'Windows' : /Android/.test(ua) ? 'Android' : /iPhone|iPad/.test(ua) ? 'iOS' : /Mac OS/.test(ua) ? 'macOS' : /Linux/.test(ua) ? 'Linux' : 'unknown',
+        osVersion: os?.[1]?.replaceAll('_', '.') ?? '', language: navigator.language,
+        ...(typeof screen === 'undefined' ? {} : { screenWidth: screen.width, screenHeight: screen.height }),
+    };
+}
+export function indexedDbStorage(namespace = 'yzm-telemetry') {
+    // 每个标签页独立队列，避免多个页面读改写同一个快照导致相互覆盖。
+    let tab = globalThis.crypto.randomUUID();
+    try {
+        const tabKey = `${namespace}:tab`;
+        tab = sessionStorage.getItem(tabKey) ?? tab;
+        sessionStorage.setItem(tabKey, tab);
+    }
+    catch { /* 隐私模式由存储失败诊断和内存队列降级。 */ }
+    const open = () => new Promise((resolve, reject) => {
+        const request = indexedDB.open(namespace, 1);
+        request.onupgradeneeded = () => request.result.createObjectStore('queues');
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(new Error('storage_failed'));
+    });
+    async function run(mode, action) {
+        const db = await open();
+        try {
+            return await new Promise((resolve, reject) => {
+                const tx = db.transaction('queues', mode);
+                const request = action(tx.objectStore('queues'));
+                tx.oncomplete = () => resolve(request.result);
+                tx.onabort = tx.onerror = () => reject(new Error('storage_failed'));
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    return {
+        load: async () => {
+            // 清除关闭标签页遗留的过期快照，避免长期使用积累无界的离线记录。
+            await run('readwrite', (store) => {
+                const cursor = store.openCursor();
+                cursor.onsuccess = () => {
+                    const row = cursor.result;
+                    if (!row)
+                        return;
+                    const saved = row.value;
+                    if (!saved.events?.some((event) => Date.parse(event.occurredAt) >= Date.now() - 86400000))
+                        row.delete();
+                    row.continue();
+                };
+                return cursor;
+            });
+            return (await run('readonly', (store) => store.get(tab)));
+        },
+        save: async (value) => {
+            if (value.events.length)
+                await run('readwrite', (store) => store.put(value, tab));
+            else
+                await run('readwrite', (store) => store.delete(tab));
+        },
+    };
+}
+export function createBrowserTracker(options) {
+    let anonymousId = options.anonymousId;
+    try {
+        anonymousId ??= localStorage.getItem('yzm-telemetry:installation') ?? globalThis.crypto.randomUUID();
+        localStorage.setItem('yzm-telemetry:installation', anonymousId);
+    }
+    catch { /* 不支持持久化时使用本次会话随机标识。 */ }
+    const tracker = createTracker({ ...options, anonymousId, device: options.device ?? browserDevice(), storage: options.storage ?? indexedDbStorage() });
+    const flush = () => { void tracker.flush(); };
+    document.addEventListener('visibilitychange', flush);
+    window.addEventListener('pagehide', flush);
+    window.addEventListener('online', flush);
+    return {
+        ...tracker,
+        destroy() {
+            document.removeEventListener('visibilitychange', flush);
+            window.removeEventListener('pagehide', flush);
+            window.removeEventListener('online', flush);
+            return tracker.destroy();
+        },
+    };
+}

package/dist/extension.d.ts

@@ -0,0 +1,8 @@
+import type { QueueStorage } from './types.js';
+export { createTracker } from './index.js';
+export type * from './types.js';
+/** 在插件 background 注入 chrome.storage.local，不在公共入口绑定 Chrome 全局对象。 */
+export declare function extensionStorage(storage: {
+    get(key: string): Promise<Record<string, unknown>>;
+    set(items: Record<string, unknown>): Promise<void>;
+}, namespace?: string): QueueStorage;

package/dist/extension.js

@@ -0,0 +1,8 @@
+export { createTracker } from './index.js';
+/** 在插件 background 注入 chrome.storage.local，不在公共入口绑定 Chrome 全局对象。 */
+export function extensionStorage(storage, namespace = 'yzm-telemetry-queue') {
+    return {
+        load: async () => (await storage.get(namespace))[namespace],
+        save: async (queue) => { await storage.set({ [namespace]: queue }); },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import type { EventName, TelemetryIdentity, TrackInput, TrackerOptions } from './types.js';
+export type { BehaviorEvent, DeviceInfo, EventName, QueueStorage, SourceApp, StoredQueue, TelemetryIdentity, TokenSession, TrackInput, TrackerOptions } from './types.js';
+export declare const SDK_VERSION = "0.2.0";
+export declare const identityKey: (identity: TelemetryIdentity) => string;
+/** 与宿主登录解耦；先绑定身份，异步请求只负责采集授权，不能改变队列归属。 */
+export declare function createTracker(options: TrackerOptions): {
+    ready: Promise<void>;
+    track: (eventName: EventName, input?: TrackInput) => Promise<void>;
+    flush: () => Promise<void>;
+    /** 只由宿主真实可见访问/交互调用，不自动通过心跳制造日活。 */
+    active(): Promise<void>;
+    reset(identity?: TelemetryIdentity): Promise<void>;
+    destroy(): Promise<void>;
+};

package/dist/index.js

@@ -0,0 +1,249 @@
+export const SDK_VERSION = '0.2.0';
+/** 至少“领域.行为.动作”三段；活跃为协议保留名，不再接受旧通用事件名。 */
+const validEventName = (name) => typeof name === 'string' &&
+    name.length <= 100 && (name === 'app.active' || /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,}$/.test(name));
+export const identityKey = (identity) => JSON.stringify([
+    identity.applicationId, identity.instanceId, identity.sourceApp, identity.actorId, identity.externalOrganizationId,
+]);
+/** 与宿主登录解耦；先绑定身份，异步请求只负责采集授权，不能改变队列归属。 */
+export function createTracker(options) {
+    const now = options.now ?? Date.now;
+    const randomId = options.randomId ?? (() => globalThis.crypto.randomUUID());
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const anonymousId = options.anonymousId ?? randomId();
+    const sessionId = randomId();
+    let key = identityKey(options.identity);
+    let events = [];
+    let session;
+    let generation = 0;
+    let destroyed = false;
+    let blocked = false;
+    let pending;
+    let storageWrites = Promise.resolve();
+    let abort;
+    let failures = 0;
+    let nextAttemptAt = 0;
+    let activeDay = '';
+    let batchSize = Math.max(1, Math.min(options.batchSize ?? 20, 100));
+    const maxAge = Math.min(options.maxAgeMs ?? 86_400_000, 86_400_000);
+    const diagnose = (code, count = 1) => {
+        try {
+            options.onDiagnostic?.(code, count);
+        }
+        catch { /* 诊断回调不能干扰宿主业务。 */ }
+    };
+    const bytes = (value) => new TextEncoder().encode(JSON.stringify(value)).length;
+    function trim() {
+        const before = events.length;
+        events = events.filter((event) => Date.parse(event.occurredAt) >= now() - maxAge);
+        const limit = Math.max(1, Math.min(options.maxQueueEvents ?? 500, 500));
+        const byteLimit = Math.max(8192, Math.min(options.maxQueueBytes ?? 1048576, 1048576));
+        while (events.length > limit || (events.length && bytes(events) > byteLimit))
+            events.shift();
+        if (before > events.length)
+            diagnose('queue_dropped', before - events.length);
+    }
+    function persist() {
+        const snapshot = JSON.parse(JSON.stringify({ identityKey: key, events }));
+        // 串行落盘，防止旧快照晚于 reset 完成而把旧账号队列恢复回来。
+        storageWrites = storageWrites.then(() => options.storage?.save(snapshot)).catch(() => diagnose('storage_failed'));
+        return storageWrites;
+    }
+    const ready = (async () => {
+        try {
+            const saved = await options.storage?.load();
+            if (destroyed || generation !== 0)
+                return;
+            if (saved?.identityKey === key && Array.isArray(saved.events)) {
+                events = saved.events.filter((item) => item && typeof item.eventId === 'string' && typeof item.occurredAt === 'string' && validEventName(item.eventName));
+                trim();
+            }
+        }
+        catch {
+            diagnose('storage_failed');
+        }
+    })();
+    async function token(force, version) {
+        if (force || !session || Date.parse(session.expiresAt) <= now() + 10_000) {
+            const fresh = await options.getToken(force);
+            if (version !== generation || destroyed)
+                return null;
+            if (identityKey(fresh.identity) !== key) {
+                blocked = true;
+                events = [];
+                await persist();
+                diagnose('identity_changed');
+                return null;
+            }
+            if (!fresh.token || !Number.isFinite(Date.parse(fresh.expiresAt)) || Date.parse(fresh.expiresAt) <= now()) {
+                throw new Error('invalid_session');
+            }
+            session = fresh;
+        }
+        return session.token;
+    }
+    function backoff(retryAfter = 0) {
+        failures++;
+        nextAttemptAt = now() + Math.max(retryAfter, Math.min(60_000, 1000 * 2 ** Math.min(failures, 6)) * (0.8 + Math.random() * 0.4));
+    }
+    async function sendLoop() {
+        await ready;
+        const version = generation;
+        if (destroyed || blocked || now() < nextAttemptAt)
+            return;
+        trim();
+        await persist();
+        while (events.length && version === generation && !destroyed && !blocked) {
+            const batch = events.slice(0, batchSize);
+            const ids = new Set(batch.map((event) => event.eventId));
+            try {
+                let bearer = await token(false, version);
+                if (!bearer)
+                    return;
+                let response;
+                for (let attempt = 0; attempt < 2; attempt++) {
+                    if (version !== generation || destroyed)
+                        return;
+                    abort = new AbortController();
+                    const timeout = setTimeout(() => abort?.abort(), 20_000);
+                    try {
+                        response = await fetcher(options.endpoint, {
+                            method: 'POST', credentials: 'omit',
+                            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${bearer}` },
+                            body: JSON.stringify({ events: batch }), signal: abort.signal,
+                        });
+                    }
+                    finally {
+                        clearTimeout(timeout);
+                    }
+                    if (response.status !== 401 || attempt === 1)
+                        break;
+                    bearer = await token(true, version);
+                    if (!bearer)
+                        return;
+                }
+                if (version !== generation || destroyed || !response)
+                    return;
+                if (response.status === 200) {
+                    const result = await response.json();
+                    if (version !== generation || destroyed)
+                        return;
+                    if (result.accepted !== batch.length)
+                        throw new Error('invalid_ack');
+                    events = events.filter((event) => !ids.has(event.eventId));
+                    failures = 0;
+                    nextAttemptAt = 0;
+                }
+                else if (response.status === 413 && batch.length > 1) {
+                    batchSize = Math.max(1, Math.floor(batch.length / 2));
+                    continue;
+                }
+                else if ([400, 413, 422].includes(response.status)) {
+                    const result = await response.json().catch(() => ({}));
+                    if (version !== generation || destroyed)
+                        return;
+                    const indices = Array.isArray(result.invalidIndices)
+                        ? result.invalidIndices.filter((i) => Number.isInteger(i) && i >= 0 && i < batch.length) : [];
+                    const invalid = indices.length ? new Set(indices.map((i) => batch[i].eventId)) : ids;
+                    events = events.filter((event) => !invalid.has(event.eventId));
+                    diagnose('invalid_event', invalid.size);
+                }
+                else if (response.status === 403) {
+                    blocked = true;
+                    diagnose('forbidden');
+                    return;
+                }
+                else {
+                    const retryHeader = response.headers.get('Retry-After');
+                    const retryAfter = retryHeader && /^\d+$/.test(retryHeader)
+                        ? Number(retryHeader) * 1000 : Math.max(0, Date.parse(retryHeader ?? '') - now()) || 0;
+                    backoff(retryAfter);
+                    diagnose(`http_${response.status}`);
+                    return;
+                }
+                await persist();
+            }
+            catch {
+                if (version === generation && !destroyed) {
+                    backoff();
+                    diagnose('send_failed');
+                }
+                return;
+            }
+        }
+    }
+    function flush() {
+        if (!pending)
+            pending = sendLoop().catch(() => diagnose('send_failed')).finally(() => { pending = undefined; });
+        return pending;
+    }
+    async function track(eventName, input = {}) {
+        const version = generation;
+        try {
+            await ready;
+            if (destroyed || blocked || version !== generation)
+                return;
+            if (!validEventName(eventName)) {
+                diagnose('invalid_event_name');
+                return;
+            }
+            const event = {
+                eventId: randomId(), recordType: 'event', eventName, eventVersion: 1,
+                occurredAt: new Date(now()).toISOString(), anonymousId, sessionId,
+                appVersion: options.appVersion, sdkVersion: SDK_VERSION,
+                ...(input.device ?? options.device ? { device: input.device ?? options.device } : {}),
+                ...(input.properties ? { properties: input.properties } : {}),
+            };
+            // 拷贝调用方对象，避免业务代码在入队后修改已产生事件。
+            if (bytes(event) > 8192) {
+                diagnose('event_too_large');
+                return;
+            }
+            events.push(JSON.parse(JSON.stringify(event)));
+            trim();
+            await persist();
+            if (events.length >= batchSize)
+                void flush();
+        }
+        catch {
+            diagnose('track_failed');
+        }
+    }
+    const interval = options.flushIntervalMs === 0 ? undefined : setInterval(() => { void flush(); }, Math.max(100, options.flushIntervalMs ?? 10000));
+    return {
+        ready, track, flush,
+        /** 只由宿主真实可见访问/交互调用，不自动通过心跳制造日活。 */
+        active() {
+            if (options.identity.sourceApp === 'erp_backend')
+                return Promise.resolve();
+            const day = new Date(now() + 8 * 3600_000).toISOString().slice(0, 10);
+            if (day === activeDay)
+                return Promise.resolve();
+            activeDay = day;
+            return track('app.active');
+        },
+        async reset(identity) {
+            generation++;
+            abort?.abort();
+            session = undefined;
+            events = [];
+            activeDay = '';
+            blocked = false;
+            failures = 0;
+            nextAttemptAt = 0;
+            if (identity)
+                key = identityKey(identity);
+            await ready;
+            await persist();
+        },
+        async destroy() {
+            destroyed = true;
+            generation++;
+            abort?.abort();
+            if (interval !== undefined)
+                clearInterval(interval);
+            await ready;
+            await persist();
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+export type SourceApp = 'erp_web' | 'erp_backend' | 'plugin';
+/** 事件名就是唯一点位 key；具体业务目录由宿主与 Collector 维护。 */
+export type EventName = string;
+export interface TelemetryIdentity {
+    applicationId: string;
+    instanceId: string;
+    sourceApp: SourceApp;
+    actorId: string;
+    externalOrganizationId: string;
+}
+export interface DeviceInfo {
+    type?: string;
+    os?: string;
+    osVersion?: string;
+    browser?: string;
+    browserVersion?: string;
+    language?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+}
+export interface BehaviorEvent {
+    eventId: string;
+    recordType: 'event';
+    eventName: EventName;
+    eventVersion: 1;
+    occurredAt: string;
+    anonymousId: string;
+    sessionId: string;
+    appVersion: string;
+    sdkVersion: string;
+    device?: DeviceInfo;
+    properties?: Record<string, string | number | boolean>;
+}
+export interface TokenSession {
+    token: string;
+    expiresAt: string;
+    identity: TelemetryIdentity;
+}
+export interface StoredQueue {
+    identityKey: string;
+    events: BehaviorEvent[];
+}
+/** 存储只保存事件和非敏感身份键，不允许保存采集 Token。 */
+export interface QueueStorage {
+    load(): Promise<StoredQueue | null>;
+    save(queue: StoredQueue): Promise<void>;
+}
+export interface TrackInput {
+    properties?: BehaviorEvent['properties'];
+    device?: DeviceInfo;
+}
+export interface TrackerOptions {
+    endpoint: string;
+    identity: TelemetryIdentity;
+    getToken: (forceRefresh: boolean) => Promise<TokenSession>;
+    storage?: QueueStorage;
+    appVersion: string;
+    anonymousId?: string;
+    device?: DeviceInfo;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    maxQueueEvents?: number;
+    maxQueueBytes?: number;
+    maxAgeMs?: number;
+    fetch?: typeof globalThis.fetch;
+    now?: () => number;
+    randomId?: () => string;
+    onDiagnostic?: (code: string, count: number) => void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@yunzhimao/telemetry",
+  "version": "0.2.0",
+  "description": "云智猫跨项目行为采集 SDK",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "cjs"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./cjs/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./extension": {
+      "types": "./dist/extension.d.ts",
+      "import": "./dist/extension.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node --test test/*.test.mjs",
+    "prepack": "pnpm build"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  }
+}