@clipto/reporter 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 declare class Reporter implements IReporter {
     private readonly opts;
     private readonly platform;
+    private readonly contextFn;
     private readonly flushInterval;
     private readonly maxBatchSize;
     private readonly maxBatchBytes;
@@ -11,9 +12,22 @@ declare class Reporter implements IReporter {
     private readonly flushOnExit;
     private readonly transportPromise;
     private readonly storagePromise;
-    /** 会话 / 设备 id 兜底:enrich 未提供时按实例生成(对齐旧 SDK 格式) */
-    private readonly sessionId;
-    private readonly deviceId;
+    /** 匿名 id:首次生成后持久化(浏览器 localStorage / Node 进程内);对外只读访问见同名 getter */
+    private readonly _anonymousId;
+    /** 设备 / 安装实例 id:Web&PC 读取 google client id(_ga),否则生成并持久化;Node 进程内生成;对外只读访问见同名 getter */
+    private readonly _clientId;
+    /** 会话落盘时间戳(节流用);声明在 session 之前:session 初始化会触发强制落盘 */
+    private sessionSaveAt;
+    /** 会话共享读时间戳(节流用):多 tab 共享会话,活动时定期重读 localStorage 最新值 */
+    private sessionReadAt;
+    /** 会话:visitId 与最近活跃时间(30 分钟无活动轮换);localStorage 持久化,同源多 tab 共享 */
+    private session;
+    /** Node 端设备快照(init 时采集一次,避免每次入队动态加载 os) */
+    private nodeDevice;
+    /** 页面访问跟踪(browser + autoPageView 时启用) */
+    private pageTracker;
+    /** history 补丁的原始引用(dispose 时还原) */
+    private historyPatch;
     /** 待发队列(内存中的事实源,持久化是它的影子) */
     private readonly queue;
     /** init 完成后指向内置 / 注入的持久化实现 */
@@ -26,19 +40,39 @@ declare class Reporter implements IReporter {
     private disposed;
     private readonly onExit;
     private readonly onPageHide;
+    private readonly onPageShow;
     private readonly onVisibilityChange;
+    private readonly onPopState;
+    private readonly onStorage;
     constructor(options: IReporterOptions);
-    track(name: string, properties?: Record<string, unknown>, options?: {
+    track(eventName: EventName, properties?: ReportNode, options?: {
         immediate?: boolean;
-        timestamp?: number;
-        category?: string;
     }): string;
     flush(): Promise<void>;
     get size(): number;
+    /** 匿名 id(只读):首次生成后持久化不变;供外部转化跟踪等场景读取 */
+    get anonymousId(): string;
+    /** 设备 / 安装实例 id(只读):Web&PC 与 google client id 一致;供外部转化跟踪等场景读取 */
+    get clientId(): string;
+    /** 当前会话 id(只读):会话轮换后返回新值;供外部转化跟踪等场景读取 */
+    get visitId(): string;
+    /** 当前登录账号 id(只读):实时调用 userId provider,未提供恒为 null */
+    get userId(): string | null;
     dispose(): Promise<void>;
-    /** 异步初始化:创建内置持久化、恢复上次会话队列、挂载退出兜底 */
+    /** 异步初始化:创建内置持久化、采集 Node 设备快照、恢复上次会话队列、挂载退出兜底 */
     private init;
-    /** 恢复队列入队:历史事件放队头保证先到先发,超限按溢出丢弃 */
+    /** 组装上报事件:身份字段由 SDK 填充,业务节点 = SDK 采集 + context 合并(接入方值优先) */
+    private buildEvent;
+    /** 进行中页面访问的 pageViewId(非访问期返回空) */
+    private pageSnapshot;
+    /** 会话活跃:track 调用与页面交互均触发;超时轮换 visitId 并结束旧页面访问 */
+    private touchSession;
+    /** 结束当前页面访问并上报 pageView 汇总事件(复用进入页面时的 visitId) */
+    private endPageVisit;
+    /** SPA 路由变化检测:pushState / replaceState 视为 routeChange,popstate 视为 back */
+    private patchHistory;
+    private restoreHistory;
+    /** 恢复队列入队:历史事件放队头保证先到先发,超限按溢出丢弃;过滤旧格式(无 eventId)事件 */
     private enqueueRestored;
     private enqueue;
     /** 攒批定时:延迟上报的实现,窗口内事件合并为一批 */
@@ -53,6 +87,22 @@ declare class Reporter implements IReporter {
     /** 持久化节流:窗口内多次变更只落盘一次,避免每次入队全量序列化 */
     private schedulePersist;
     private persistNow;
+    /** 匿名 id:localStorage 持久化,首次匿名访问生成后保留;Node 无持久化介质,进程内生成 */
+    private loadOrCreateAnonymousId;
+    /** clientId:Web&PC 与 google client id(_ga cookie)一致;否则本地生成并持久化 */
+    private loadOrCreateClientId;
+    /** 会话恢复:localStorage(同源多 tab 共享)中 30 分钟窗口内的会话复用,否则新建 */
+    private loadOrCreateSession;
+    /** 会话落盘(localStorage):节流 10s,避免滚动等高频活动频繁写;force 用于轮换 / 退出兜底 */
+    private saveSession;
+    /** 采纳共享会话:visitId 变化视为其他 tab 轮换了会话,结束本 tab 旧页面访问并开启新访问 */
+    private adoptSharedSession;
+    /** 活动时重读共享会话(兜底 storage 事件丢失):storage 事件只在其他 tab 触发 */
+    private refreshSessionFromShared;
+    private readPersistent;
+    private writePersistent;
+    /** 生成带前缀的实例 id(格式对齐旧 SDK session_ / device_) */
+    private newId;
     private log;
     /**
      * Node 进程退出事件句柄:Electron 渲染进程 typings 里 process 只声明了 'loaded'
@@ -64,9 +114,9 @@ declare class Reporter implements IReporter {
 }
 
 /** 浏览器发送:fetch(keepalive)走正常路径;sendBeacon 仅退出兜底(sendSync) */
-declare function createBrowserTransport(endpoint: string, headers?: Record<string, string>): IReportTransport;
+declare function createBrowserTransport(endpoint: string, headers?: Record<string, string>, signer?: IReportSigner): IReportTransport;
 /** Node 发送:动态加载项目现有依赖 axios(仅在 Node 路径执行) */
-declare function createNodeTransport(endpoint: string, headers?: Record<string, string>): Promise<IReportTransport>;
+declare function createNodeTransport(endpoint: string, headers?: Record<string, string>, signer?: IReportSigner): Promise<IReportTransport>;
 /** 降级实现:localStorage(容量有限,仅兜底) */
 declare function createLocalStorageStorage(): IReportStorage;
 /** 浏览器持久化:优先 Dexie(IndexedDB),不可用时降级 localStorage */
@@ -76,42 +126,70 @@ declare function createNodeStorage(persistDir: string): Promise<IReportStorage>;
 
 /** 事件被丢弃的原因 */
 type DropReason = 'max-attempts' | 'overflow' | 'invalid';
-/** 上报事件(track 入队后的形态;顶层字段对齐旧 SDK TrackedEvent) */
+/** 签名函数:对序列化后的上报信封生成签名等附加键值(如 X-Clipto-Timestamp / X-Clipto-Signature),返回值作为请求头随包发送,服务端校验防止伪造数据污染;算法与密钥由接入方决定(如 WebCrypto HMAC);可同步或异步返回 */
+type IReportSigner = (payload: string) => Record<string, string> | Promise<Record<string, string>>;
+/** 业务节点:app / device / page / user / properties 的统一形态;具体字段与取值由接入方埋点方案约束,SDK 不感知语义、原样透传 */
+type ReportNode = Record<string, unknown>;
+/** 业务上下文:统一承载各业务节点;可传静态对象,或传函数在每次入队时实时计算(读取最新登录态 / 页面状态) */
+interface IEventContext {
+    /** 应用信息:产品标识 / 环境 / 平台 / 版本 / 渠道归因等,由接入方配置 */
+    app?: ReportNode;
+    /** 设备信息:与 SDK 自动采集的硬件 / 系统 / 浏览器信息在同一节点内按字段合并,接入方提供的字段值优先;ip / country 等由服务端填充 */
+    device?: ReportNode;
+    /** 页面信息:与 SDK 自动采集的页面快照合并;pageId 等接入方定义字段在此提供 */
+    page?: ReportNode;
+    /** 用户信息:账号 / 订阅 / 权益 / 实验分组等,由接入方账号体系提供 */
+    user?: ReportNode;
+    /** 合并进每个事件 properties 的公共业务字段;track() 传入的 properties 优先级更高 */
+    properties?: ReportNode;
+}
+/** 事件名:接入方埋点方案定义的稳定事件名,同一行为跨 Web、iOS、Android、Mac、Windows 尽量同名;以下为 SDK 预置事件名,业务事件可继续扩展 */
+type EventName = 'pageView' | 'elementExposure' | 'user_action' | (string & {});
+/** 上报事件(网络信封结构:身份字段由 SDK 生成,业务节点由接入方 context 提供或 SDK 自动采集) */
 interface IReportEvent {
-    /** 核心生成的唯一 id */
-    id: string;
-    /** 事件名(上报信封中序列化为 eventName,对齐旧 SDK) */
-    name: string;
-    /** 业务属性(baseProperties 与 context 已合并) */
-    properties: Record<string, unknown>;
-    /** 事件时间(ms) */
+    /** SDK 自动生成:每条事件唯一 ID,用于网络重试与服务端幂等去重;同一事件重试时复用原值 */
+    eventId: string;
+    /** 埋点方案定义的稳定事件名,研发接入;同一行为跨端尽量同名 */
+    eventName: string;
+    /** 登录账号 id:账号系统提供、SDK 自动读取;未登录为 null,登录后携带,退出后恢复 null;接入方不手工填写 */
+    userId: string | null;
+    /** 匿名 id:SDK 自动生成,首次匿名访问 / 安装时生成,登录后继续保留;清浏览器数据、换浏览器或重装 App 后可能生成新值 */
+    anonymousId: string;
+    /** 会话 id:SDK 会话模块生成;页面切换保持不变,同源多 tab 共享一个会话(任一 tab 活动即刷新活跃时间);连续 30 分钟无活动、退出或切换账号后,下一次活动生成新值 */
+    visitId: string;
+    /** 设备 / 安装实例 id:SDK 自动生成并持久化;Web&PC 与 google client id 一致,iOS&Android 为 IDFV */
+    clientId: string;
+    /** 事件实际发生的毫秒时间戳,由客户端时钟产生(SDK 自动生成) */
     timestamp: number;
-    /** 已尝试发送次数(SDK 内部字段,不上报) */
+    /** 应用信息(接入方 context 提供,节点始终存在,内容由埋点方案约束) */
+    app: ReportNode;
+    /** 设备信息(SDK 自动采集 + context 合并) */
+    device?: ReportNode;
+    /** 页面信息(SDK 自动采集 + context 合并) */
+    page?: ReportNode;
+    /** 用户信息(接入方 context 提供) */
+    user?: ReportNode;
+    /** 业务事件属性(context.properties 与 track properties 合并) */
+    properties?: ReportNode;
+}
+/** 队列内部事件:上报事件 + SDK 内部字段(序列化上报前剥离) */
+interface IQueuedEvent extends IReportEvent {
+    /** 已尝试发送次数,达到 maxAttempts 即丢弃 */
     attempts: number;
-    /** 会话 id(enrich 提供,否则核心按实例生成) */
-    sessionId?: string;
-    /** 用户 id(enrich 提供,否则 null) */
-    userId?: string | null;
-    /** 设备 id(enrich 提供,否则核心按实例生成) */
-    deviceId?: string;
-    /** 事件类别(enrich / track options 提供,默认 'custom') */
-    category?: string;
-    /** 采集上下文:页面 / 用户 / 浏览器 / 屏幕 / 视口(enrich 提供,否则空对象) */
-    context?: Record<string, unknown>;
 }
 /** 发送适配器:如何把一批事件发出去(浏览器: sendBeacon → fetch;Node: https / axios) */
 interface IReportTransport {
-    /** 发送一批事件;resolve 视为成功,reject 进入重试 */
+    /** 发送一批事件(纯上报结构,内部字段如 attempts 已由核心剥离);resolve 视为成功,reject 进入重试 */
     send(events: IReportEvent[]): Promise<void>;
     /** 退出兜底时的同步尽力发送(浏览器端为 navigator.sendBeacon);返回是否已受理 */
     sendSync?(events: IReportEvent[]): boolean;
 }
 /** 持久化适配器:待发队列跨页面刷新 / 进程重启存活(浏览器 IndexedDB / Node conf) */
 interface IReportStorage {
-    /** 整体覆盖保存当前待发队列(实现需幂等;写入节流由核心负责) */
-    save(events: IReportEvent[]): void | Promise<void>;
+    /** 整体覆盖保存当前待发队列(含重试计数,恢复后继续计次;实现需幂等;写入节流由核心负责) */
+    save(events: IQueuedEvent[]): void | Promise<void>;
     /** 读取上次保存的待发队列 */
-    load(): IReportEvent[] | Promise<IReportEvent[]>;
+    load(): IQueuedEvent[] | Promise<IQueuedEvent[]>;
     /** 清空 */
     clear(): void | Promise<void>;
 }
@@ -119,6 +197,9 @@ interface IReportStorage {
 interface IReporterOptions {
     /** 上报端点,必填(浏览器与 Node 共用) */
     endpoint: string;
+    /** 业务上下文:统一提供 app / device / page / user / properties 业务节点;静态对象或实时函数(每次入队时调用);
+     *  与 SDK 自动采集的 device / page 在同一节点内按字段合并,接入方提供的字段值优先 */
+    context?: IEventContext | (() => IEventContext);
     /** 运行平台:显式声明,驱动内置发送 / 持久化实现;缺省自动探测(typeof window) */
     platform?: 'browser' | 'node';
     /** 攒批窗口(ms),即延迟上报的固定间隔;0 表示关闭批量,事件即时发送 */
@@ -135,22 +216,23 @@ interface IReporterOptions {
     maxAttempts?: number;
     /** 失败重发退避基础延迟(ms),按 2^n 指数增长 */
     backoffMs?: number;
-    /** 合并进每个事件 properties 的公共业务字段(替代旧 SDK base_properties) */
-    baseProperties?: Record<string, unknown>;
-    /** 上下文采集函数,每次入队时实时调用并合并进 properties(替代旧 SDK 硬编码的页面/浏览器/设备信息) */
-    context?: () => Record<string, unknown>;
-    /** 逐事件顶层字段补充函数(sessionId/userId/deviceId/context),每次入队时实时调用,缺省值由核心兜底 */
-    enrich?: () => Partial<Pick<IReportEvent, 'sessionId' | 'userId' | 'deviceId' | 'context'>>;
+    /** 登录账号 id 提供函数:每次入队时实时读取(由接入方账号体系提供);未提供时恒为 null */
+    userId?: () => string | null;
     /** 页面卸载 / 进程退出时兜底 flush(浏览器端走 sendBeacon) */
     flushOnExit?: boolean;
     /** 浏览器端:队列是否持久化到本地(优先 IndexedDB,不支持时降级 localStorage) */
     persist?: boolean;
     /** Node 端:持久化目录,设置后待发队列落盘(跨进程重启存活);不传仅内存 */
     persistDir?: string;
-    /** 浏览器端:自动上报 page_view(初始化 + 页面重新可见) */
+    /** 浏览器端:自动管理页面访问并上报 pageView(进入页面建立访问上下文,离开页面时汇总上报) */
     autoPageView?: boolean;
     /** 自定义请求头(内置传输实现使用) */
     headers?: Record<string, string>;
+    /** 可选签名:每个批次发送前对序列化信封调用 signer,返回的键值对(通常为 X-Clipto-Timestamp / X-Clipto-Signature 等签名头)作为请求头随包发送,服务端校验防伪造/污染;
+     *  payload 为信封 JSON 序列化(含 metadata.timestamp,可作签名时间戳);
+     *  仅内置 transport 生效(自定义 transport 自行处理);sendBeacon 不支持自定义请求头,
+     *  配置 signer 后退出兜底自动回退为带签名头的异步发送(keepalive fetch) */
+    signer?: IReportSigner;
     /** 打开调试日志 */
     debug?: boolean;
     /** 可选注入:发送适配器;不传按运行环境内置 */
@@ -166,17 +248,22 @@ interface IReporterOptions {
 }
 /** 公共接口 */
 interface IReporter {
-    /** 上报一条事件并返回事件 id(dispose 后或非法事件返回空串);immediate 事件跳过攒批立即发送 */
-    track(name: string, properties?: Record<string, unknown>, options?: {
+    /** 上报一条事件并返回 eventId(dispose 后或非法事件返回空串);immediate 事件跳过攒批立即发送;事件名见 EventName */
+    track(eventName: EventName, properties?: ReportNode, options?: {
         immediate?: boolean;
-        timestamp?: number;
-        /** 事件类别(顶层字段,默认 'custom') */
-        category?: string;
     }): string;
     /** 立即冲刷队列(跳过退避等待),并等待在途批次完成 */
     flush(): Promise<void>;
     /** 队列中待发条数 */
     readonly size: number;
+    /** 当前登录账号 id:实时调用 userId provider;未提供时恒为 null */
+    readonly userId: string | null;
+    /** 匿名 id:首次生成后持久化不变;供外部转化跟踪等场景读取 */
+    readonly anonymousId: string;
+    /** 设备 / 安装实例 id:Web&PC 与 google client id 一致;供外部转化跟踪等场景读取 */
+    readonly clientId: string;
+    /** 当前会话 id:会话轮换后返回新值(同源多 tab 共享);供外部转化跟踪等场景读取 */
+    readonly visitId: string;
     /** 停止并兜底 flush(flushOnExit),之后拒绝新事件 */
     dispose(): Promise<void>;
 }
@@ -185,4 +272,4 @@ interface IReporterConstructor {
     new (options: IReporterOptions): IReporter;
 }
 
-export { type DropReason, type IReportEvent, type IReportStorage, type IReportTransport, type IReporter, type IReporterConstructor, type IReporterOptions, Reporter, createBrowserStorage, createBrowserTransport, createLocalStorageStorage, createNodeStorage, createNodeTransport };
+export { type DropReason, type EventName, type IEventContext, type IQueuedEvent, type IReportEvent, type IReportSigner, type IReportStorage, type IReportTransport, type IReporter, type IReporterConstructor, type IReporterOptions, type ReportNode, Reporter, createBrowserStorage, createBrowserTransport, createLocalStorageStorage, createNodeStorage, createNodeTransport };