@macroui/event-tracker 1.3.0 → 1.3.1

package/dist/types/plugins/webview-bridge/index.d.ts

@@ -1,22 +1,34 @@
 /**
- * WebView 桥（vapph5 协议）
- *  - 客户端（iOS/Android）注入 window.vapph5define 对象
- *  - H5 通过 vapph5define.call(name, args) 调用客户端方法
- *  - 客户端通过 vapph5define.handle(name, fn) 监听 H5 调用
+ * WebView 桥（v2 RPC）
  *
- * 本插件负责：
- *  1. 探测 WebView 标识
- *  2. 在 SDK 启动时调用 vapph5define.call('getAppInfo')，把 app_version/app_id/...
- *     注入到 config 与公共属性
- *  3. 暴露 helper：bridge.call(name, args) 与 bridge.on(name, fn)
+ *  v1: vapph5define.call(name, args) 同步返回，缺点：
+ *    - 没法 timeout
+ *    - 没法传 callback-style
+ *    - 没法识别 native async
+ *
+ *  v2:
+ *    - RPC 协议：call(name, args, cbId) → native 通过 vapph5define.rpc.response(cbId, result)
+ *    - 自动超时（默认 5s）→ reject
+ *    - 自动探测：window.vapph5define.rpc / window.vapph5define.call 任一可用
+ *    - SDK 暴露 sdk.bridge.callAsync(name, args) 返回 Promise
+ *    - 兼容旧 sdk.bridge.call(name, args)
+ *    - install 时 fetch app info 可 await
  */
 import type { Plugin } from '../../core/plugin.js';
 declare global {
     interface Window {
         vapph5define?: {
+            /** v1 同步调用 */
             call: (name: string, ...args: unknown[]) => unknown;
+            /** v1 监听 */
             handle: (name: string, fn: (...args: unknown[]) => unknown) => void;
+            /** 是否在 app 中 */
             isInApp?: boolean;
+            /** v2 RPC */
+            rpc?: {
+                call: (name: string, cbId: string, args: unknown) => void;
+                response: (cbId: string, result: unknown, err?: string) => void;
+            };
         };
     }
 }
@@ -27,7 +39,19 @@ export interface WebViewBridgeOptions {
     fetchOnInit?: boolean;
     /** 自定义取 app 信息的协议名（默认 'getAppInfo'） */
     protocolName?: string;
+    /** RPC 默认超时（ms） */
+    timeout?: number;
     /** 取回的应用信息合并到 SDK 的字段映射 */
     fieldMap?: Partial<Record<'app_version' | 'app_id' | 'app_state' | 'channel' | 'lib', string>>;
 }
+export interface BridgeAPI {
+    /** 同步调用（v1 风格） */
+    call: <T = unknown>(name: string, ...args: unknown[]) => T | undefined;
+    /** 异步 RPC 调用（v2） */
+    callAsync: <T = unknown>(name: string, args?: unknown, timeoutMs?: number) => Promise<T>;
+    /** 注册 native handler */
+    on: (name: string, fn: (...args: unknown[]) => unknown) => void;
+    /** 检测是否在 webview 中 */
+    isInApp: () => boolean;
+}
 export declare function webviewBridge(opts?: WebViewBridgeOptions): Plugin;

package/dist/types/send/ajax-sender.d.ts

@@ -1,11 +1,16 @@
 /**
- * Ajax 发送器（fetch + keepalive）
+ * Ajax 发送器（fetch + keepalive + gzip）
+ *
+ *  - 支持 gzip（v1.2.0 #6）：通过 CompressionStream('gzip')
+ *  - keepalive: true 支持 unload 后继续发送
+ *  - Content-Encoding: gzip 用于告诉服务端解码
  */
 import type { SendContext, Sender } from './sender.js';
 import type { EventData } from '../types/index.js';
 export declare class AjaxSender implements Sender {
     name: "ajax";
     canUse(): boolean;
+    private getGzipEnabled;
     send(event: EventData, ctx: SendContext): Promise<void>;
     sendBatch(events: EventData[], ctx: SendContext): Promise<void>;
 }

package/dist/types/send/batch-sender.d.ts

@@ -1,15 +1,26 @@
 /**
- * Batch 发送器：事件先入队到 localStorage，定时或达上限时一次性 POST
+ * Batch 发送器：事件先入队到 localStorage，链式 setTimeout 调度
+ *
+ *  - 不使用 setInterval，改为每次 flush 完后再排下一次（chain）
+ *  - 队列满 / 显式 flush 时立即发送
+ *  - 支持 gzip（v1.2.0 #6）+ CompressionStream
+ *  - 链式调度避免 setInterval 在页面隐藏时仍在跑
  */
 import type { SendContext, Sender } from './sender.js';
 import type { EventData } from '../types/index.js';
 export declare class BatchSender implements Sender {
     name: "batch";
     private timer;
+    private running;
+    private ctx?;
     canUse(): boolean;
     start(ctx: SendContext): void;
     stop(): void;
     send(event: EventData, ctx: SendContext): Promise<void>;
+    /** 链式调度：flush 完后再排下一次 */
+    private scheduleNext;
+    /** 窥探当前队列长度（pipeline.flush 用于 onFlush 计数） */
+    peekQueueSize(): number;
     private enqueue;
     private read;
     private write;

package/dist/types/send/encode.d.ts

@@ -1,8 +1,20 @@
 /**
- * 序列化 & 编码
+ * 序列化 & 编码（v1.2.0 性能优化）
+ *
+ *  - TextEncoder / URLSearchParams 单例
+ *  - payload cache（同一 event 短时间内不重复编码）
+ *  - 提供 base64url safe encode
  */
 import type { EventData } from '../types/index.js';
 export type EncryptFn = (data: string) => string | Promise<string>;
+export declare function getTextEncoder(): TextEncoder;
+export declare function getTextDecoder(): TextDecoder;
 export declare function encodeEvent(event: EventData, encryptor?: EncryptFn): string | Promise<string>;
 export declare function encodeBatch(events: EventData[], encryptor?: EncryptFn): string | Promise<string>;
 export declare function buildUrl(serverUrl: string | string[], payload: string, contentType?: 'json' | 'form'): string;
+export declare function strToBytes(s: string): Uint8Array;
+export declare function bytesToStr(b: Uint8Array): string;
+export declare function toBase64Url(bytes: Uint8Array): string;
+export declare function _clearPayloadCache(): void;
+/** 反序列化（带缓存） */
+export declare function decodeEvent<T = unknown>(json: string): T;

package/dist/types/send/offscreen-sender.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OffscreenSender (v1.3.0)
+ *
+ * 把 send/gzip/encrypt 全部挪到 Web Worker，主线程零阻塞
+ *
+ *  - 使用专用 Worker（postMessage 协议）
+ *  - 主线程仅保留外壳：encodeEvent + postMessage
+ *  - 支持 batch send（同 worker 内聚合 + 单次 flush）
+ *  - 不可用时（Safari 14 之前 / Node）自动 fallback 到 ajax
+ */
+import type { Sender, SendContext } from './sender.js';
+import type { EventData } from '../types/index.js';
+export declare class OffscreenSender implements Sender {
+    name: "offscreen";
+    private worker;
+    private fallback?;
+    private queue;
+    canUse(): boolean;
+    private getWorker;
+    send(event: EventData, ctx: SendContext): Promise<void>;
+    /** 批量发送（worker 内聚合） */
+    sendBatch(events: EventData[], ctx: SendContext): Promise<void>;
+    /** 关闭 worker */
+    destroy(): void;
+}

package/dist/types/send/sender.d.ts

@@ -3,18 +3,35 @@
  */
 import type { EventData, TrackerConfig, SendType } from '../types/index.js';
 import type { Logger } from '../core/logger.js';
+import type { StatsCollector } from '../core/stats.js';
 export interface SendContext {
     config: TrackerConfig;
     logger: Logger;
+    /** 可选的 stats 收集器，未提供时退化为无统计模式 */
+    stats?: StatsCollector;
 }
 export interface Sender {
     /** 此发送器是否适用于当前上下文 */
     canUse(): boolean;
+    /** 发送器名称，用于 pickSender/stats 聚合 */
+    name: SendType | string;
     /** 发送单条事件 */
     send(event: EventData, ctx: SendContext): Promise<void> | void;
-    /** 批量发送（batch 模式） */
+}
+/**
+ * 带 stats 计时 + onSendSuccess / onSendError 钩子的发送包装。
+ * 由 SendPipeline 调用，统一埋点失败统计与可观测性。
+ *
+ * 不作为 Sender 接口成员，由 SendPipeline 显式调用本函数包一层，
+ * 这样所有 Sender 子类都不必各自实现。
+ * @internal
+ */
+export declare function sendWithStats(sender: Sender, event: EventData, ctx: SendContext): Promise<void>;
+/**
+ * 支持批量发送的发送器（image/beacon 不支持，ajax/batch 支持）
+ */
+export interface BatchCapableSender extends Sender {
+    /** 批量发送 */
     sendBatch?(events: EventData[], ctx: SendContext): Promise<void> | void;
-    /** 名称 */
-    name: SendType | string;
 }
 export declare function pickSender(type: SendType | undefined, candidates: Sender[]): Sender;

package/dist/types/send/ws-sender.d.ts

@@ -0,0 +1,38 @@
+/**
+ * WebSocket Sender（v1.3.0）
+ *
+ *  - 长连接上报，适合实时数据
+ *  - 支持服务端反向下发配置（dynamic config）
+ *  - 自动重连（指数退避）
+ *  - 离线时本地缓冲
+ */
+import type { Sender, SendContext } from './sender.js';
+import type { EventData, TrackerConfig } from '../types/index.js';
+export interface WebSocketSenderOptions {
+    /** WS 服务地址 */
+    url: string;
+    /** 鉴权 token（首条消息携带） */
+    authToken?: string;
+    /** 重连延迟上限（ms） */
+    maxReconnectMs?: number;
+    /** 离线缓冲上限 */
+    maxBuffer?: number;
+}
+export declare class WebSocketSender implements Sender {
+    private opts;
+    name: "ws";
+    private ws;
+    private buffer;
+    private reconnectDelay;
+    private reconnectTimer;
+    private configCb;
+    constructor(opts: WebSocketSenderOptions);
+    canUse(): boolean;
+    connect(): void;
+    onConfig(cb: (cfg: Partial<TrackerConfig>) => void): void;
+    send(event: EventData, _ctx: SendContext): Promise<void>;
+    sendBatch(events: EventData[], _ctx: SendContext): Promise<void>;
+    close(): void;
+    private safeSend;
+    private scheduleReconnect;
+}

package/dist/types/types/config.d.ts

@@ -89,8 +89,24 @@ export interface DebugConfig {
     debug?: 0 | 1 | 2;
     /** 是否显示日志 */
     show_log?: boolean;
+    /** 自动打印 stats（默认 debug >= 1 时启用） */
+    show_stats?: boolean;
+    /** stats 打印间隔（ms，默认 60000） */
+    stats_interval?: number;
 }
-export type TrackerConfig = BaseConfig & SendConfig & StorageConfig & IdentityConfig & EncryptConfig & PresetConfig & DebugConfig & JsAppConfig & ClientConfig & DebugSenderConfig;
+export interface ObservabilityConfig {
+    /** 发送成功（事件 + 耗时） */
+    onSendSuccess?: (event: Record<string, unknown>, durationMs: number) => void;
+    /** 发送失败 */
+    onSendError?: (err: Error, event: Record<string, unknown>) => void;
+    /** 每次 flush 完成 */
+    onFlush?: (count: number, durationMs: number) => void;
+    /** 进入失败队列 */
+    onFailedEnqueue?: (event: Record<string, unknown>, reason: string) => void;
+    /** 即将重试 */
+    onRetry?: (event: Record<string, unknown>, attempt: number) => void;
+}
+export type TrackerConfig = BaseConfig & SendConfig & StorageConfig & IdentityConfig & EncryptConfig & PresetConfig & DebugConfig & ObservabilityConfig & JsAppConfig & ClientConfig & DebugSenderConfig;
 export interface JsAppConfig {
     /** 应用版本（JS） */
     app_version?: string;

package/dist/types/types/index.d.ts

@@ -2,7 +2,7 @@
  * 类型总入口（v1.1.1）
  */
 export type { SendType, StorageType, LogLevel, Callback, JSONValue, JSONObject, JSONArray, PropertyMap, ServerURL, StageName, HookName, } from './common.js';
-export type { BaseConfig, SendConfig, StorageConfig, IdentityConfig, EncryptConfig, PresetConfig, DebugConfig, JsAppConfig, ClientConfig, DebugSenderConfig, TrackerConfig, } from './config.js';
+export type { BaseConfig, SendConfig, StorageConfig, IdentityConfig, EncryptConfig, PresetConfig, DebugConfig, ObservabilityConfig, JsAppConfig, ClientConfig, DebugSenderConfig, TrackerConfig, } from './config.js';
 /** 待发送事件结构 */
 export interface EventData {
     type: 'track' | 'track_signup' | 'track_id_bind' | 'track_id_unbind' | 'profile_set' | 'profile_set_once' | 'profile_increment' | 'profile_append' | 'profile_unset' | 'profile_delete' | 'item_set' | 'item_delete';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macroui/event-tracker",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "A self-developed web event tracking SDK, inspired by Sensors Analytics. Supports image/beacon/ajax/batch send, full auto-tracking, WebView bridge, and pluggable encryption.",
   "keywords": [
     "analytics",

package/dist/types/types.test-d.d.ts

@@ -1,5 +0,0 @@
-/**
- * 公共 API 类型测试（tsd）
- * 验证公开类型签名稳定
- */
-export {};

package/dist/types.test-d.ts

@@ -1,103 +0,0 @@
-/**
- * 公共 API 类型测试（tsd）
- * 验证公开类型签名稳定
- */
-
-import { expectType, expectAssignable, expectNotAssignable } from 'tsd';
-import { EventTracker } from './types/index.js';
-import type { TrackerConfig, EventData, Callback, SendType, StorageType, ServerURL, StageName, HookName, Plugin, InstallContext, StageInterceptor, Lifecycle, SDKError } from './types/index.js';
-import type { SignedIdentity } from './types/core/signed-identity.js';
-
-// ============ EventTracker ============
-expectType<EventTracker>(new EventTracker());
-expectAssignable<{ track: Function }>(new EventTracker());
-expectNotAssignable<EventTracker>({});
-
-// ============ TrackerConfig ============
-const cfg: TrackerConfig = {
-  app_id: 'demo',
-  server_url: 'https://api.test/sa',
-  send_type: 'image',
-  storage_type: 'memory',
-  debug: 1,
-};
-expectAssignable<TrackerConfig>(cfg);
-expectAssignable<TrackerConfig>({ app_id: 'a', server_url: 'https://x' });
-
-const single: ServerURL = 'https://api.test';
-const multi: ServerURL = ['https://a.test', 'https://b.test'];
-expectAssignable<ServerURL>(single);
-expectAssignable<ServerURL>(multi);
-
-// ============ EventData ============
-const ev: EventData = {
-  type: 'track',
-  event: 'demo',
-  time: Date.now(),
-  distinct_id: 'd',
-  properties: { x: 1 },
-};
-expectAssignable<EventData>(ev);
-expectAssignable<EventData>({
-  type: 'profile_set',
-  time: 1,
-  distinct_id: 'd',
-  properties: { name: 'Alice' },
-});
-
-// ============ Callback ============
-const cb: Callback = (err: Error | null) => { void err; };
-expectAssignable<Callback>(cb);
-
-// ============ SendType / StorageType ============
-const st: SendType = 'beacon';
-expectAssignable<SendType>(st);
-const sto: StorageType = 'localStorage';
-expectAssignable<StorageType>(sto);
-
-// ============ StageName / HookName ============
-expectAssignable<StageName>('buildDataStage');
-expectAssignable<StageName>('businessStage');
-expectAssignable<StageName>('sendDataStage');
-expectAssignable<HookName>('sdkReady');
-expectAssignable<HookName>('sdkAfterInitPara');
-
-// ============ Plugin / InstallContext ============
-const plugin: Plugin = {
-  name: 'demo',
-  install(ctx: InstallContext) {
-    expectAssignable<TrackerConfig>(ctx.config);
-    expectAssignable<EventTracker>(ctx.sdk);
-  },
-};
-expectAssignable<Plugin>(plugin);
-
-// ============ StageInterceptor ============
-const interceptor: StageInterceptor<unknown> = {
-  name: 'demo',
-  priority: 10,
-  entry(ctx: { data: unknown; meta: any; cancellationToken: any; owner?: unknown }) {
-    expectAssignable<unknown>(ctx.data);
-    return undefined;
-  },
-};
-expectAssignable<StageInterceptor<unknown>>(interceptor);
-
-// ============ Lifecycle（type-only） ============
-expectAssignable<Lifecycle>({} as Lifecycle);
-
-// ============ Errors ============
-expectAssignable<SDKError>({} as SDKError);
-
-// ============ SignedIdentity ============
-const si: SignedIdentity = {
-  sign: (v: string) => v,
-  verify: (v: string, sig: string) => v === sig,
-  encode: (v: string) => v,
-  decode: (v: string) => v,
-  signAsync: async (v: string) => v,
-  verifyAsync: async (v: string, s: string) => v === s,
-  encodeAsync: async (v: string) => v,
-  decodeAsync: async (v: string) => v,
-};
-expectAssignable<SignedIdentity>(si);