@yunzhimao/telemetry 0.2.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @yunzhimao/telemetry
 
-通用行为采集 SDK，当前 `0.2.0` 是待联调版本，尚未发布到 npm。只采集显式行为，不自动捕获 DOM、URL、请求内容或异常。
+通用行为采集 SDK，源码统一维护在 CRM 仓库的 `packages/telemetry-sdk`，宿主安装 npm 精确版本。只采集显式行为，不自动捕获 DOM、URL、请求内容或异常。
 
 ## 浏览器
 
@@ -47,13 +47,13 @@ void tracker.flush();
 - Token 只在内存中，不进入离线队列；事件重试保持 eventId 和原始时间。安装标识不是设备指纹，行为不是可信业务结算依据。
 - `track()` 不等待网络且不向业务抛采集错误；存储失败退回内存。`onDiagnostic(code, count)` 不含原始事件或 Token。
 - `destroy()` 卸载监听/定时器并保留队列；退出登录必须先 `reset()` 清队列。关页发送仅尽力而为，关闭标签页的未发送快照不承诺由其他标签页补发，过期后清理。
-- 默认入口仅依赖现代运行时的 fetch、TextEncoder、crypto.randomUUID；浏览器子路径要求 DOM 和 IndexedDB，插件 storage 由调用方注入；无 Vue/Pinia/CRM 商业依赖。
+- 默认入口依赖现代运行时的 fetch、TextEncoder 和安全随机能力；`0.2.1` 起优先使用 crypto.randomUUID，HTTP 环境缺少该方法时使用 crypto.getRandomValues 生成标准 UUID v4，不使用 Math.random。两者都不可用时初始化报 secure_random_unavailable；浏览器子路径要求 DOM，IndexedDB 不可用时降级内存，插件 storage 由调用方注入；无 Vue/Pinia/CRM 商业依赖。此兼容不替代生产环境的 HTTPS 传输保护。
 
 ## 验证与发布
 
 在仓库根目录运行 `pnpm --filter @yunzhimao/telemetry test`。`pnpm --filter @yunzhimao/telemetry pack --pack-destination .tmp` 只生成本地包，不发布。包内容限定为 ESM dist、CommonJS cjs、类型声明和本说明。
 
-发布前确认 npm scope 所属、公开/私有可见性，三个宿主安装同一 tarball 验证后再使用固定版本号。不要把私钥、环境配置、内部服务端包或其他仓库打入包。
+发布时同时更新 package.json 与 src/index.ts 的版本号，测试通过后进入 `packages/telemetry-sdk` 执行 `npm publish --access public --registry=https://registry.npmjs.org`。宿主使用新版本前需更新依赖、重新构建和部署；仅发布 npm 不会更新已部署页面。不要删除源码目录，也不要把私钥、环境配置、内部服务端包或其他仓库打入包。
 
 ## ERP 后端 / Node
 

package/cjs/browser.js

@@ -4,6 +4,7 @@ exports.browserDevice = browserDevice;
 exports.indexedDbStorage = indexedDbStorage;
 exports.createBrowserTracker = createBrowserTracker;
 const index_js_1 = require("./index.js");
+const uuid_js_1 = require("./uuid.js");
 /** 只采集基础设备属性；不读取 URL、DOM 内容、Token 或指纹。 */
 function browserDevice() {
     if (typeof navigator === 'undefined')
@@ -22,7 +23,7 @@ function browserDevice() {
 }
 function indexedDbStorage(namespace = 'yzm-telemetry') {
     // 每个标签页独立队列，避免多个页面读改写同一个快照导致相互覆盖。
-    let tab = globalThis.crypto.randomUUID();
+    let tab = (0, uuid_js_1.randomUuid)();
     try {
         const tabKey = `${namespace}:tab`;
         tab = sessionStorage.getItem(tabKey) ?? tab;
@@ -78,7 +79,7 @@ function indexedDbStorage(namespace = 'yzm-telemetry') {
 function createBrowserTracker(options) {
     let anonymousId = options.anonymousId;
     try {
-        anonymousId ??= localStorage.getItem('yzm-telemetry:installation') ?? globalThis.crypto.randomUUID();
+        anonymousId ??= localStorage.getItem('yzm-telemetry:installation') ?? (0, uuid_js_1.randomUuid)();
         localStorage.setItem('yzm-telemetry:installation', anonymousId);
     }
     catch { /* 不支持持久化时使用本次会话随机标识。 */ }

package/cjs/index.d.ts

@@ -1,6 +1,6 @@
 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 SDK_VERSION = "0.2.1";
 export declare const identityKey: (identity: TelemetryIdentity) => string;
 /** 与宿主登录解耦；先绑定身份，异步请求只负责采集授权，不能改变队列归属。 */
 export declare function createTracker(options: TrackerOptions): {

package/cjs/index.js

@@ -2,7 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.identityKey = exports.SDK_VERSION = void 0;
 exports.createTracker = createTracker;
-exports.SDK_VERSION = '0.2.0';
+const uuid_js_1 = require("./uuid.js");
+exports.SDK_VERSION = '0.2.1';
 /** 至少“领域.行为.动作”三段；活跃为协议保留名，不再接受旧通用事件名。 */
 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));
@@ -13,7 +14,7 @@ exports.identityKey = identityKey;
 /** 与宿主登录解耦；先绑定身份，异步请求只负责采集授权，不能改变队列归属。 */
 function createTracker(options) {
     const now = options.now ?? Date.now;
-    const randomId = options.randomId ?? (() => globalThis.crypto.randomUUID());
+    const randomId = options.randomId ?? uuid_js_1.randomUuid;
     const fetcher = options.fetch ?? globalThis.fetch;
     const anonymousId = options.anonymousId ?? randomId();
     const sessionId = randomId();

package/cjs/uuid.d.ts

@@ -0,0 +1,2 @@
+/** HTTPS 优先使用原生 UUID；HTTP 环境用安全随机字节兼容，不降级为 Math.random。 */
+export declare function randomUuid(): string;

package/cjs/uuid.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.randomUuid = randomUuid;
+/** HTTPS 优先使用原生 UUID；HTTP 环境用安全随机字节兼容，不降级为 Math.random。 */
+function randomUuid() {
+    const crypto = globalThis.crypto;
+    if (typeof crypto?.randomUUID === 'function')
+        return crypto.randomUUID();
+    if (typeof crypto?.getRandomValues !== 'function')
+        throw new Error('secure_random_unavailable');
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    // UUID v4 的版本位固定为 0100，变体位固定为 10，其他位保留随机性。
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/dist/browser.js

@@ -1,4 +1,5 @@
 import { createTracker } from './index.js';
+import { randomUuid } from './uuid.js';
 /** 只采集基础设备属性；不读取 URL、DOM 内容、Token 或指纹。 */
 export function browserDevice() {
     if (typeof navigator === 'undefined')
@@ -17,7 +18,7 @@ export function browserDevice() {
 }
 export function indexedDbStorage(namespace = 'yzm-telemetry') {
     // 每个标签页独立队列，避免多个页面读改写同一个快照导致相互覆盖。
-    let tab = globalThis.crypto.randomUUID();
+    let tab = randomUuid();
     try {
         const tabKey = `${namespace}:tab`;
         tab = sessionStorage.getItem(tabKey) ?? tab;
@@ -73,7 +74,7 @@ export function indexedDbStorage(namespace = 'yzm-telemetry') {
 export function createBrowserTracker(options) {
     let anonymousId = options.anonymousId;
     try {
-        anonymousId ??= localStorage.getItem('yzm-telemetry:installation') ?? globalThis.crypto.randomUUID();
+        anonymousId ??= localStorage.getItem('yzm-telemetry:installation') ?? randomUuid();
         localStorage.setItem('yzm-telemetry:installation', anonymousId);
     }
     catch { /* 不支持持久化时使用本次会话随机标识。 */ }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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 SDK_VERSION = "0.2.1";
 export declare const identityKey: (identity: TelemetryIdentity) => string;
 /** 与宿主登录解耦；先绑定身份，异步请求只负责采集授权，不能改变队列归属。 */
 export declare function createTracker(options: TrackerOptions): {

package/dist/index.js

@@ -1,4 +1,5 @@
-export const SDK_VERSION = '0.2.0';
+import { randomUuid } from './uuid.js';
+export const SDK_VERSION = '0.2.1';
 /** 至少“领域.行为.动作”三段；活跃为协议保留名，不再接受旧通用事件名。 */
 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));
@@ -8,7 +9,7 @@ export const identityKey = (identity) => JSON.stringify([
 /** 与宿主登录解耦；先绑定身份，异步请求只负责采集授权，不能改变队列归属。 */
 export function createTracker(options) {
     const now = options.now ?? Date.now;
-    const randomId = options.randomId ?? (() => globalThis.crypto.randomUUID());
+    const randomId = options.randomId ?? randomUuid;
     const fetcher = options.fetch ?? globalThis.fetch;
     const anonymousId = options.anonymousId ?? randomId();
     const sessionId = randomId();

package/dist/uuid.d.ts

@@ -0,0 +1,2 @@
+/** HTTPS 优先使用原生 UUID；HTTP 环境用安全随机字节兼容，不降级为 Math.random。 */
+export declare function randomUuid(): string;

package/dist/uuid.js

@@ -0,0 +1,14 @@
+/** HTTPS 优先使用原生 UUID；HTTP 环境用安全随机字节兼容，不降级为 Math.random。 */
+export function randomUuid() {
+    const crypto = globalThis.crypto;
+    if (typeof crypto?.randomUUID === 'function')
+        return crypto.randomUUID();
+    if (typeof crypto?.getRandomValues !== 'function')
+        throw new Error('secure_random_unavailable');
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    // UUID v4 的版本位固定为 0100，变体位固定为 10，其他位保留随机性。
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunzhimao/telemetry",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "云智猫跨项目行为采集 SDK",
   "type": "module",
   "files": [