@macroui/event-tracker 1.3.0

package/dist/types/core/instance-channel.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 跨实例 channel
+ *  - 用 BroadcastChannel 实现，浏览器跨 tab 通信
+ *  - 降级到 localStorage（无 BroadcastChannel 时）
+ *  - 主要用于：
+ *    - 共享 disabled 状态
+ *    - 共享 changeDistinctId
+ *    - 共享 session_id
+ */
+export interface ChannelMessage {
+    type: 'state' | 'distinct' | 'session' | 'custom';
+    source: string;
+    payload: unknown;
+}
+type Listener = (msg: ChannelMessage) => void;
+export declare class InstanceChannel {
+    private bc;
+    private listeners;
+    private sourceId;
+    private localStorageKey;
+    private pollTimer;
+    constructor();
+    private initBroadcastChannel;
+    private initLocalStoragePolling;
+    /** 发送消息 */
+    post(type: ChannelMessage['type'], payload: unknown): void;
+    /** 监听消息，返回取消函数 */
+    on(fn: Listener): () => void;
+    /** 关闭 */
+    close(): void;
+    /** 实例 id（用于调试 / 验证） */
+    getSourceId(): string;
+}
+export {};

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

@@ -0,0 +1,26 @@
+/**
+ * 7 个生命周期钩子
+ *  - sdkReady          SDK 加载完成，init 之前
+ *  - sdkInitPara       init 处理参数时（合并前）
+ *  - sdkAfterInitPara  init 处理参数后
+ *  - sdkInitAPI        API 挂到 window 之前
+ *  - sdkAfterInitAPI   API 挂到 window 之后
+ *  - changeDistinctId  distinct 变化时
+ *  - switch            配置切换（多实例）
+ */
+export type HookName = 'sdkReady' | 'sdkInitPara' | 'sdkAfterInitPara' | 'sdkInitAPI' | 'sdkAfterInitAPI' | 'changeDistinctId' | 'switch';
+export declare const ALL_HOOKS: readonly HookName[];
+export type HookFn = (...args: unknown[]) => void | Promise<void>;
+export declare class Lifecycle {
+    private hooks;
+    /** 注册钩子，返回取消函数 */
+    on(name: HookName, fn: HookFn): () => void;
+    /** 取消钩子 */
+    off(name: HookName, fn: HookFn): void;
+    /** 同步触发钩子（catch 内部错误，不向外抛） */
+    emit(name: HookName, ...args: unknown[]): void;
+    /** 移除全部钩子 */
+    clear(): void;
+    /** 调试用 */
+    inspect(): Record<HookName, number>;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * 简易 logger
+ */
+import type { TrackerConfig } from '../types/index.js';
+export declare class Logger {
+    private config;
+    constructor(config: Pick<TrackerConfig, 'debug' | 'show_log'>);
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    private shouldLog;
+    private out;
+}

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

@@ -0,0 +1,60 @@
+import { StageChain, type StageInterceptor, type StageName } from './stage.js';
+import { Lifecycle, type HookName, type HookFn } from './lifecycle.js';
+import type { TrackerConfig } from '../types/index.js';
+export interface InstallContext {
+    /** 当前配置（reference，mutate 会影响 SDK） */
+    config: TrackerConfig;
+    /** 钩子系统 */
+    registry: PluginRegistry;
+    /** 3 个 stage 注入点 */
+    stages: {
+        buildDataStage: StageChain<unknown>;
+        businessStage: StageChain<unknown>;
+        sendDataStage: StageChain<unknown>;
+    };
+    /** SDK 自身引用（提供 track / identify / use / quick 等 API） */
+    sdk: import('./tracker.js').EventTracker;
+    /** 给插件使用的命名空间（每个 plugin 可写入自己的子对象） */
+    kit: Record<string, unknown>;
+    /** 跨实例 channel */
+    channel: import('./instance-channel.js').InstanceChannel;
+    /** 持久化 store */
+    store: import('../storage/store.js').KVStore;
+    /** 卸载 */
+    uninstall: () => void;
+}
+export interface Plugin {
+    /** 唯一名（同名重复 install 会先卸载旧的） */
+    name: string;
+    install?(ctx: InstallContext): void;
+    uninstall?(ctx?: InstallContext): void;
+}
+export declare class PluginRegistry {
+    /** 3 个 stage */
+    readonly stages: {
+        buildDataStage: StageChain<unknown>;
+        businessStage: StageChain<unknown>;
+        sendDataStage: StageChain<unknown>;
+    };
+    /** 7 个生命周期钩子 */
+    readonly lifecycle: Lifecycle;
+    /** 已安装的 plugin 列表 */
+    private plugins;
+    /** commonWays：quick() 调用入口 */
+    readonly commonWays: Record<string, (...args: unknown[]) => unknown>;
+    /** hook 注册快捷方法（向后兼容 + 简化插件作者） */
+    on(name: HookName, fn: HookFn): () => void;
+    off(name: HookName, fn: HookFn): void;
+    emit(name: HookName, ...args: unknown[]): void;
+    /** stage 注册拦截器 */
+    intercept<T = unknown>(stage: StageName, spec: StageInterceptor<T>): void;
+    /** 兼容旧 API：invoke(name, ...args) = emit(name, ...args) */
+    invoke(name: HookName, ...args: unknown[]): void;
+    constructor();
+    /** 安装 plugin */
+    install(plugin: Plugin, ctx: Omit<InstallContext, 'registry' | 'stages'>): void;
+    /** 卸载 plugin */
+    uninstall(plugin: Plugin, ctx?: InstallContext): void;
+    /** 列出已安装 */
+    list(): string[];
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Profile API（v1.1.1）
+ */
+import type { EventTracker } from '../core/tracker.js';
+import type { SendPipeline } from './send-pipeline.js';
+export declare function attachProfileApi(sdk: EventTracker, pipeline: SendPipeline): void;

package/dist/types/core/profile-store.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ProfileStore：用户属性持久化
+ *  - setOnce / append / increment / unset / delete
+ *  - 落到 KVStore（cookie/localStorage/...）
+ *  - SDK 启动时读入缓存
+ */
+import type { KVStore } from '../storage/store.js';
+import { uuidv4 } from './uuid.js';
+export declare class ProfileStore {
+    private store;
+    private cache;
+    constructor(store: KVStore);
+    private persist;
+    get(key: string): unknown;
+    getAll(): Record<string, unknown>;
+    set(props: Record<string, unknown>): void;
+    setOnce(props: Record<string, unknown>): void;
+    append(props: Record<string, unknown>): void;
+    increment(props: Record<string, number>): void;
+    unset(key: string): void;
+    delete(): void;
+}
+export declare const _uuid: typeof uuidv4;

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

@@ -0,0 +1,22 @@
+/**
+ * 公共属性注册 API（v1.1.1）
+ */
+import type { EventTracker } from '../core/tracker.js';
+import type { PresetPropertyBuilder } from '../presets/preset-properties.js';
+export interface RegisterApi {
+    /** 注册永久属性（每次事件附带） */
+    register(props: Record<string, unknown>): this;
+    /** 注册一次性属性（首次读取后清除） */
+    registerOnce(props: Record<string, unknown>): this;
+    /** 清空所有永久属性 */
+    clearAllRegister(): this;
+    /** 移除单个属性 */
+    unsetRegister(key: string): this;
+    /** 注册一次性属性（神策 registerPage 别名） */
+    registerPage(props: Record<string, unknown>): this;
+    /** 注册会话属性（每次会话唯一；等同 registerOnce） */
+    registerSession(props: Record<string, unknown>): this;
+    /** 注册会话一次性属性 */
+    registerSessionOnce(props: Record<string, unknown>): this;
+}
+export declare function attachRegisterApi(sdk: EventTracker, builder: PresetPropertyBuilder): void;

package/dist/types/core/retry-policy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 失败重试 + 退避
+ *  - 包装单个 send 调用
+ *  - 退避: 1s → 2s → 4s
+ *  - 超过 max_retry_duration 放弃
+ *  - 失败事件可写入失败队列（待用）
+ */
+import type { TrackerConfig } from '../types/index.js';
+import type { Logger } from './logger.js';
+export interface RetryConfig {
+    max_retry_count: number;
+    max_retry_duration: number;
+}
+/** 重试执行结果 */
+export interface RetryResult {
+    ok: boolean;
+    attempts: number;
+    finalErr: Error | null;
+}
+export declare class RetryPolicy {
+    private config;
+    private logger;
+    constructor(config: TrackerConfig, logger: Logger);
+    /** 计算本次重试要 sleep 多久（指数退避） */
+    private backoff;
+    /**
+     * 带重试执行 send 函数
+     * @param send 单次发送
+     * @param shouldRetry 判断失败是否重试
+     */
+    execute(send: () => Promise<void> | void, shouldRetry?: (err: Error | null) => boolean, onFailed?: (err: Error, attempt: number) => void): Promise<RetryResult>;
+    private sleep;
+}

package/dist/types/core/send-pipeline.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 发送管线（v1.1.1）
+ *  - 集中管理 build / encrypt / send / failed-queue / batch flush
+ *  - flush() / waitUntilIdle() 让上层能主动等待
+ */
+import type { TrackerConfig, EventData, Callback } from '../types/index.js';
+import type { PluginRegistry } from './plugin.js';
+import type { IdentityManager } from './identity.js';
+import type { PresetPropertyBuilder } from '../presets/preset-properties.js';
+import type { RetryPolicy } from './retry-policy.js';
+import type { FailedQueue } from './failed-queue.js';
+import type { BatchSender } from '../send/batch-sender.js';
+import type { Sender } from '../send/sender.js';
+import { Logger } from './logger.js';
+export declare class SendPipeline {
+    private config;
+    private registry;
+    private identity;
+    private presetProps;
+    private retryPolicy;
+    private failedQueue;
+    private logger;
+    private pending;
+    private senders;
+    private batchSender?;
+    private abortControllers;
+    constructor(config: TrackerConfig, registry: PluginRegistry, identity: IdentityManager, presetProps: PresetPropertyBuilder, retryPolicy: RetryPolicy, failedQueue: FailedQueue, logger: Logger);
+    setSenders(senders: Sender[]): void;
+    setBatchSender(b: BatchSender): void;
+    /** 构造事件对象 */
+    buildEvent(type: EventData['type'], opts?: {
+        event?: string;
+        properties?: Record<string, unknown>;
+    }): EventData;
+    /** 异步发送 */
+    send(data: EventData, callback?: Callback): void;
+    /** 加密后真正下发 */
+    private dispatchAfterEncrypt;
+    private pickSender;
+    private trackPending;
+    /**
+     * 强制 flush：
+     *  - batch 模式：立即触发 batch sender 的 flush
+     *  - failed queue：把残留队列重发
+     *  - 所有 pending：等完成
+     */
+    flush(): Promise<void>;
+    /** 等待所有 in-flight 任务结束 */
+    waitUntilIdle(): Promise<void>;
+    /** Abort 所有挂起 / in-flight 任务 */
+    abortAll(reason?: string): void;
+    /** 给 sender 用：申请一个 AbortSignal，发送完成 / abort 时自动释放 */
+    takeAbortController(key: Symbol): AbortController;
+    releaseAbortController(key: Symbol): void;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 签名 Identity（HMAC-SHA256）
+ *  - 把 cookie / localStorage 中的 distinct_id / first_id 加密 + 签名
+ *  - 防止用户篡改身份
+ *  - 基于 Web Crypto API（jsdom + Node 18+）
+ */
+/** 异步 HMAC-SHA256（推荐使用） */
+export declare function hmacSignAsync(data: string, secret: string): Promise<string>;
+/** 异步验证签名 */
+export declare function hmacVerifyAsync(data: string, secret: string, signature: string): Promise<boolean>;
+export interface SignedIdentity {
+    /** 同步签名 */
+    sign(value: string): string;
+    /** 异步签名（HMAC-SHA256） */
+    signAsync(value: string): Promise<string>;
+    /** 同步校验 */
+    verify(value: string, signed: string): boolean;
+    /** 异步校验 */
+    verifyAsync(value: string, signed: string): Promise<boolean>;
+    /** 给 KV 写入用的编码（`${value}|${sig}`） */
+    encode(value: string): string;
+    /** 从 KV 读取后还原（失败返回 null） */
+    decode(raw: string): string | null;
+    /** 异步版本 */
+    encodeAsync(value: string): Promise<string>;
+    decodeAsync(raw: string): Promise<string | null>;
+}
+/** 创建签名器 */
+export declare function createSignedIdentity(secret: string): SignedIdentity;

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

@@ -0,0 +1,48 @@
+/**
+ * 事件数据拦截 Stage
+ *  - 3 个 Stage: buildDataStage / businessStage / sendDataStage
+ *  - 按 priority 升序执行
+ *  - cancellationToken 可中断后续
+ *
+ * 灵感来自神策 sa-sdk-javascript 内部实现
+ */
+export type StageName = 'buildDataStage' | 'businessStage' | 'sendDataStage';
+export interface StageContext<T> {
+    data: T;
+    /** 阶段元信息 */
+    meta: {
+        stage: StageName;
+        [key: string]: unknown;
+    };
+    /** 取消令牌：调 stop() 后后续 interceptor 跳过 */
+    cancellationToken: {
+        stop: () => void;
+    };
+    /** SDK 引用，供 interceptor 使用 */
+    owner?: unknown;
+}
+export interface StageInterceptor<T> {
+    /** 唯一名（同名注册会覆盖） */
+    name: string;
+    /** 数字越小越先执行，默认 100 */
+    priority?: number;
+    /** 拦截处理，返回新数据或直接改 ctx.data */
+    entry: (ctx: StageContext<T>) => T | void;
+}
+export declare class StageChain<T = unknown> {
+    private stage;
+    private list;
+    private stopped;
+    private stopFlag;
+    constructor(stage: StageName);
+    /** 注册一个拦截器（同名覆盖） */
+    register(spec: StageInterceptor<T>): void;
+    /** 移除一个拦截器 */
+    unregister(name: string): void;
+    /** 获取所有拦截器名（调试用） */
+    list2(): string[];
+    /** 重置 stage（含清除停止标志） */
+    reset(): void;
+    /** 主入口：顺序执行 */
+    run(input: T, owner?: unknown): T;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Track API（v1.1.1）
+ */
+import type { EventTracker } from '../core/tracker.js';
+import type { SendPipeline } from './send-pipeline.js';
+export declare function attachTrackApi(sdk: EventTracker, pipeline: SendPipeline): void;

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

@@ -0,0 +1,130 @@
+/**
+ * SDK 主类（v1.1.1）
+ *
+ * 通过 attachXxxApi 模块化挂载所有方法，主类只负责：
+ *  - 初始化（init）
+ *  - 装配管线（Pipeline）
+ *  - 提供公共 getter / setter
+ *  - 提供 flush / waitUntilIdle / abort / close
+ */
+import { Logger } from './logger.js';
+import { PluginRegistry, type Plugin } from './plugin.js';
+import { InstanceChannel } from './instance-channel.js';
+import { RetryPolicy } from './retry-policy.js';
+import { FailedQueue } from './failed-queue.js';
+import { SignedIdentity } from './signed-identity.js';
+import { SendPipeline } from './send-pipeline.js';
+import type { TrackerConfig, Callback, SendType, ServerURL } from '../types/index.js';
+export declare class EventTracker {
+    readonly lib_name = "event-tracker";
+    readonly lib_version = "1.1.0";
+    readonly DEFAULT_SEND_TYPE: SendType;
+    private _config;
+    private _store;
+    private _identity;
+    private _presetProps;
+    private _logger;
+    private _registry;
+    private _senders;
+    private _batchSender?;
+    private _retryPolicy;
+    private _failedQueue;
+    private _channel;
+    private _pipeline;
+    private _signedIdentity?;
+    private _inited;
+    readonly instanceId: string;
+    constructor();
+    /**
+     * 初始化 SDK（只可调用一次；重复调用会被忽略）
+     * @param config 完整配置项；详见 TrackerConfig
+     * @throws InitError 当 server_url / app_id 缺失时
+     * @example
+     * ```ts
+     * sdk.init({
+     *   app_id: 'demo',
+     *   server_url: 'https://api.example.com/sa',
+     *   send_type: 'beacon',
+     *   debug: 1,
+     * });
+     * ```
+     */
+    init(config: TrackerConfig): void;
+    use(plugin: Plugin): this;
+    /** @internal */
+    __noop: () => void;
+    track(event: string, properties?: Record<string, unknown>, _callback?: Callback): void;
+    trackSignup(userId: string, properties?: Record<string, unknown>, _callback?: Callback): void;
+    trackLinkage(properties: Record<string, unknown>, _callback?: Callback): void;
+    trackLink(element: HTMLElement | string, properties?: Record<string, unknown>, _callback?: Callback): void;
+    trackLinks(elements: HTMLElement[] | NodeListOf<Element> | string, properties?: Record<string, unknown>, _callback?: Callback): void;
+    trackHeatMap(properties: Record<string, unknown>, _callback?: Callback): void;
+    trackWebClick(properties: Record<string, unknown>, _callback?: Callback): void;
+    trackWebStay(properties: Record<string, unknown>, _callback?: Callback): void;
+    identify(_distinctId: string, _isSave?: boolean): this;
+    login(_loginId: string): this;
+    logout(_resetAnonymousId?: string): this;
+    resetAnonymousIdentity(_newAnonymousId?: string): this;
+    alias(_newId: string, _originalId?: string): void;
+    getDistinctId(): string;
+    getAnonymousId(): string;
+    getFirstId(): string;
+    getLoginId(): string;
+    getOriginalId(): string;
+    register(_props: Record<string, unknown>): this;
+    registerOnce(_props: Record<string, unknown>): this;
+    clearAllRegister(): this;
+    unsetRegister(_key: string): this;
+    registerPage(_props: Record<string, unknown>): this;
+    registerSession(_props: Record<string, unknown>): this;
+    registerSessionOnce(_props: Record<string, unknown>): this;
+    setProfile(_props: Record<string, unknown>, _callback?: Callback): void;
+    setOnceProfile(_props: Record<string, unknown>, _callback?: Callback): void;
+    incrementProfile(_props: Record<string, number>, _callback?: Callback): void;
+    appendProfile(_props: Record<string, unknown>, _callback?: Callback): void;
+    unsetProfile(_prop: string, _callback?: Callback): void;
+    deleteProfile(_callback?: Callback): void;
+    /** 关闭 SDK（track noop） */
+    disable(): this;
+    /** 启用 SDK */
+    enable(): this;
+    /** 切换 server_url（多 sink / 灰度 / 主备切换）
+     * @param url 单个 URL 或 URL 数组
+     */
+    setServerURL(url: ServerURL): this;
+    switchServer(url: ServerURL): this;
+    /**
+     * 强制 flush batch sender + failed queue + 等待所有 in-flight 完成
+     */
+    flush(): Promise<void>;
+    /**
+     * 等待所有 in-flight 任务结束（发送、加密、queue 处理）
+     */
+    waitUntilIdle(): Promise<void>;
+    /** Abort 所有挂起任务 */
+    abort(reason?: string): void;
+    /** 完整关闭（batch stop + channel close） */
+    close(): void;
+    /** 工具 */
+    uuid(): string;
+    /** 预置属性（手动计算） */
+    getPresetProperties(): Record<string, unknown>;
+    /** 完整关闭：channel close + pipeline abort + batch stop */
+    shutdown(): void;
+    getConfig(): TrackerConfig;
+    getLogger(): Logger;
+    getRegistry(): PluginRegistry;
+    getRetryPolicy(): RetryPolicy;
+    getFailedQueue(): FailedQueue;
+    getChannel(): InstanceChannel;
+    getPipeline(): SendPipeline;
+    getSignedIdentity(): SignedIdentity | undefined;
+    isBrowser(): boolean;
+    isInitialized(): boolean;
+}
+/** 创建 / 切换实例 */
+export declare function initPara(config: TrackerConfig): EventTracker;
+/** 通过 client_id 取已有实例 */
+export declare function registerAppid(instanceId: string): EventTracker | undefined;
+/** 列出所有实例 */
+export declare function listInstances(): EventTracker[];

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

@@ -0,0 +1,4 @@
+/**
+ * UUID v4 生成（无依赖，使用 crypto.getRandomValues）
+ */
+export declare function uuidv4(): string;

package/dist/types/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 主入口：构造一个默认 SDK 实例（兼容神策风格的全局对象）
+ *
+ * 暴露：
+ *   - default export: 已经 attach 了所有 API 的全局单例
+ *   - EventTracker: 类，可以多实例
+ *   - named exports: 所有插件 / 工具
+ */
+import { EventTracker } from './core/tracker.js';
+import { PresetEvent, PresetProperty, LIB_NAME, LIB_VERSION } from './types/constants.js';
+declare const tracker: EventTracker;
+export default tracker;
+export { tracker };
+export { EventTracker };
+export { initPara, registerAppid, listInstances } from './core/tracker.js';
+export type { TrackerConfig, BaseConfig, SendConfig, StorageConfig, IdentityConfig, EncryptConfig, PresetConfig, DebugConfig, JsAppConfig, ClientConfig, DebugSenderConfig, EventData, SendType, StorageType, Callback, LogLevel, JSONValue, JSONObject, JSONArray, PropertyMap, ServerURL, StageName, HookName, } from './types/index.js';
+export type { Plugin, InstallContext } from './core/plugin.js';
+export type { StageInterceptor, StageContext, StageChain } from './core/stage.js';
+export type { Lifecycle, HookFn } from './core/lifecycle.js';
+export { SDKError, InitError, SendError, EncryptError, IdentityError, StorageError, PluginError, ConfigError, isSDKError, } from './core/errors.js';
+export { createSignedIdentity, hmacSignAsync, hmacVerifyAsync, } from './core/signed-identity.js';
+export type { SignedIdentity } from './core/signed-identity.js';
+export { SendPipeline } from './core/send-pipeline.js';
+export { PluginRegistry } from './core/plugin.js';
+export { RetryPolicy } from './core/retry-policy.js';
+export { FailedQueue } from './core/failed-queue.js';
+export { InstanceChannel } from './core/instance-channel.js';
+export { Logger } from './core/logger.js';
+export { IdentityManager } from './core/identity.js';
+export { PresetPropertyBuilder } from './presets/preset-properties.js';
+export { PresetEvent, PresetProperty, LIB_NAME, LIB_VERSION };
+export { autoTrack } from './plugins/auto-track/index.js';
+export { pageLoad } from './plugins/pageload/index.js';
+export { pageLeave } from './plugins/pageleave/index.js';
+export { exposure } from './plugins/exposure/index.js';
+export { sessionEvent } from './plugins/session-event/index.js';
+export { debugSender } from './plugins/debug-sender/index.js';
+export { indexedDBSender } from './plugins/indexeddb-sender/index.js';
+export { webviewBridge } from './plugins/webview-bridge/index.js';
+export { encryptor, xorEncryptor, defaultEncryptor, defaultDecryptor, aesGcmEncryptAsync, aesGcmDecryptAsync } from './plugins/encrypt/index.js';

package/dist/types/plugins/auto-track/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * auto-track 插件
+ *  - $pageview:   路由变化时自动 track
+ *  - $WebClick:   监听 click，自动 track
+ *  - $WebStay:    页面离开时上报停留时长
+ *  - $scrolldepth: 25/50/75/100% 触发
+ */
+import type { Plugin } from '../../core/plugin.js';
+export interface AutoTrackOptions {
+    pageview?: boolean;
+    webclick?: boolean;
+    webstay?: boolean;
+    scrolldepth?: boolean;
+    /** webclick 元素选择器过滤，匹配才上报 */
+    webclickSelector?: string;
+    /** 上报时附带的元素属性（attribute 名单） */
+    webclickAttrs?: string[];
+    /** scroll 触发阈值（百分比数组） */
+    scrollThresholds?: number[];
+}
+export declare function autoTrack(opts?: AutoTrackOptions): Plugin;

package/dist/types/plugins/debug-sender/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Debug 发送器（独立 plugin）
+ *  - 启用后走 GET 请求到 debug_mode_url（默认从 server_url 推导 ?debug）
+ *  - 成功后 alert("debug数据发送成功" + data)
+ *  - 失败时 alert("debug失败" + JSON.stringify(err))
+ *  - 优先级最高（先于其它 senders 执行）
+ */
+import { PresetProperty } from '../../types/constants.js';
+import type { Plugin } from '../../core/plugin.js';
+import type { EventData } from '../../types/index.js';
+export interface DebugOptions {
+    /** 是否启用（默认从 config.debug_mode 取） */
+    enable?: boolean;
+    /** 调试接收端 URL（默认从 config.server_url 推导 ?debug） */
+    url?: string;
+    /** 调试上传标记（出现在 Dry-Run header） */
+    upload?: string;
+    /** 成功回调（默认 alert） */
+    onSuccess?: (event: EventData) => void;
+    /** 失败回调（默认 alert） */
+    onError?: (err: Error, event: EventData) => void;
+}
+export declare function debugSender(opts?: DebugOptions): Plugin;
+export { PresetProperty };

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

@@ -0,0 +1,56 @@
+/**
+ * encrypt 插件（v1.1 增强版）
+ *
+ * 三个能力：
+ *   1. 加密 + 解密配对（神策风格）
+ *      - config.encryptor / config.decoder
+ *      - 加密函数接收 JSON 字符串返回字符串；解密函数反向
+ *
+ *   2. Web Crypto AES-GCM
+ *      - aesGcmEncrypt / aesGcmDecrypt
+ *      - 基于 Web Crypto API，256-bit key，输出 base64(iv||ciphertext)
+ *
+ *   3. 钩子：encryptEvent / decryptEvent
+ *      - 用于在事件被发送前/接收后做二次处理（脱敏、补字段等）
+ *
+ * 用法示例：
+ *   import { encryptor, aesGcmEncrypt, aesGcmDecrypt } from '@macroui/event-tracker/plugin/encrypt';
+ *   const key = 'my-32-byte-secret-key-1234567890ab';
+ *   sdk.use(encryptor({
+ *     encrypt: aesGcmEncrypt(key),
+ *     decrypt: aesGcmDecrypt(key),
+ *     encryptEvent: (e) => scrubPII(e),
+ *     decryptEvent: (e) => e,
+ *   }));
+ */
+import type { Plugin } from '../../core/plugin.js';
+import type { EventData } from '../../types/index.js';
+export type EncryptFn = (data: string) => string;
+export type DecryptFn = (data: string) => string;
+export type EventTransform = (event: EventData) => EventData | unknown;
+export interface EncryptorOptions {
+    /** 加密：JSON 字符串 -> 字符串 */
+    encrypt: EncryptFn;
+    /** 解密：字符串 -> JSON 字符串（可选；多数场景 SDK 不下行） */
+    decrypt?: DecryptFn;
+    /** 事件级加密前钩子（脱敏、补字段） */
+    encryptEvent?: EventTransform;
+    /** 事件级解密后钩子（一般用于 debug 拉回来的事件） */
+    decryptEvent?: EventTransform;
+}
+declare function xorBase64(input: string, key: string): string;
+export declare function defaultEncryptor(key: string): EncryptFn;
+export declare function defaultDecryptor(key: string): DecryptFn;
+export { xorBase64 };
+/** AES-GCM 加密（同步 API 抛错；改用 Async 版本）
+ *  @deprecated Web Crypto API 是异步的，同步签名不现实；
+ *  改用 aesGcmEncryptAsync + asyncSend helper，或预计算密文。
+ */
+export declare function aesGcmEncrypt(_rawKey: string): EncryptFn;
+/** AES-GCM 加密（异步版）：返回 Promise<string> */
+export declare function aesGcmEncryptAsync(rawKey: string): (data: string) => Promise<string>;
+/** AES-GCM 解密（异步版） */
+export declare function aesGcmDecryptAsync(rawKey: string): (data: string) => Promise<string>;
+export declare function encryptor(opts: EncryptorOptions): Plugin;
+/** 便捷工厂：XOR 配对 */
+export declare function xorEncryptor(key: string): Plugin;