@macroui/event-tracker 1.3.0 → 1.3.1

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

@@ -0,0 +1,77 @@
+/**
+ * Sender 失败统计（v1.2.0）
+ *
+ *  - 每个 sender 维护 attempts / success / failure / total_duration
+ *  - SDK 全局汇总
+ *  - 用户可 sdk.getStats() 查
+ *  - 自动每 60s 输出到 console（debug 模式）
+ */
+export interface SenderStat {
+    /** sender 名称（image / beacon / ajax / batch） */
+    name: string;
+    /** 尝试次数 */
+    attempts: number;
+    /** 成功次数 */
+    success: number;
+    /** 失败次数 */
+    failure: number;
+    /** 累计耗时（ms） */
+    total_duration: number;
+    /** 平均耗时（ms） */
+    avg_duration: number;
+    /** 最大单次耗时（ms） */
+    max_duration: number;
+    /** 最近一次失败原因 */
+    last_error?: string;
+    /** 最近一次失败时间戳 */
+    last_error_at?: number;
+}
+export interface StatsSnapshot {
+    /** SDK 启动后累计发送次数 */
+    total: number;
+    /** 成功累计 */
+    success: number;
+    /** 失败累计 */
+    failure: number;
+    /** 重试累计 */
+    retry: number;
+    /** in-flight（当前未完成） */
+    in_flight: number;
+    /** flush 累计 */
+    flush_count: number;
+    /** 上次 flush 时间 */
+    last_flush_at?: number;
+    /** 每个 sender 统计 */
+    by_sender: Record<string, SenderStat>;
+    /** 时间戳 */
+    taken_at: number;
+}
+export declare class StatsCollector {
+    private total;
+    private success;
+    private failure;
+    private retry;
+    private in_flight;
+    private flushCount;
+    private lastFlushAt?;
+    private bySender;
+    /** 记录一次发送开始 */
+    recordStart(senderName: string): number;
+    /** 记录一次发送成功 */
+    recordSuccess(senderName: string, startTs: number): void;
+    /** 记录一次发送失败 */
+    recordFailure(senderName: string, startTs: number, err: Error): void;
+    /** 记录一次重试 */
+    recordRetry(): void;
+    /** 记录一次 flush */
+    recordFlush(): void;
+    /** 拍快照 */
+    snapshot(): StatsSnapshot;
+    /** 重置 */
+    reset(): void;
+    /** 列出所有 sender 名 */
+    listSenders(): string[];
+    private getOrCreate;
+}
+/** 全局单例 */
+export declare const GLOBAL_STATS: StatsCollector;

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

@@ -32,6 +32,8 @@ export declare class EventTracker {
     private _channel;
     private _pipeline;
     private _signedIdentity?;
+    private _stats;
+    private _statsTimer;
     private _inited;
     readonly instanceId: string;
     constructor();
@@ -103,7 +105,7 @@ export declare class EventTracker {
     waitUntilIdle(): Promise<void>;
     /** Abort 所有挂起任务 */
     abort(reason?: string): void;
-    /** 完整关闭（batch stop + channel close） */
+    /** 完整关闭：channel close + pipeline abort + batch stop */
     close(): void;
     /** 工具 */
     uuid(): string;
@@ -119,6 +121,10 @@ export declare class EventTracker {
     getChannel(): InstanceChannel;
     getPipeline(): SendPipeline;
     getSignedIdentity(): SignedIdentity | undefined;
+    /** 获取 sender 失败统计快照（v1.2.0） */
+    getStats(): import("./stats.js").StatsSnapshot;
+    /** 重置 sender 统计 */
+    resetStats(): void;
     isBrowser(): boolean;
     isInitialized(): boolean;
 }

package/dist/types/core/wasm-crypto.d.ts

@@ -0,0 +1,28 @@
+/**
+ * WASM 加密（v1.2.0 可选）
+ *
+ *  - 把常见 HMAC-SHA256 / AES-GCM 操作抽到 wasm（性能 5-10x）
+ *  - 通过 dynamic import('./crypto-wasm.js') 按需加载
+ *  - wasm 未提供时 fallback 到 js
+ *  - 提供 `getWasmCrypto()` lazy 工厂
+ *
+ * 注意：本目录仅含 runtime glue；实际 wasm binary 由用户在构建期注入
+ * （如：npm i @macroui/crypto-wasm 并在 init 时传入）
+ */
+export interface WasmCrypto {
+    hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array;
+    aesGcmEncrypt(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Uint8Array;
+    aesGcmDecrypt(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Uint8Array;
+    available: boolean;
+}
+/**
+ * 加载 wasm crypto
+ *  - 优先尝试 globalThis.__ET_WASM_CRYPTO__（用户注入）
+ *  - 否则尝试 import('@macroui/crypto-wasm') peer dep
+ *  - 失败时 fallback 到 JS 实现
+ */
+export declare function getWasmCrypto(): Promise<WasmCrypto>;
+/** 同步 hash 工具（用于 cache key，fallback） */
+export declare function fastHash(s: string): number;
+/** 注入自定义 wasm crypto（advanced 用） */
+export declare function setWasmCrypto(c: WasmCrypto): void;

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

@@ -0,0 +1,41 @@
+/**
+ * Edge Worker Adapter (v1.3.0)
+ *
+ *  - 适配 Cloudflare Workers / D1
+ *  - 不依赖 DOM，用 globalThis.fetch / crypto
+ *  - KV 存储用 Map（运行时）
+ *  - 暴露 init() 工厂
+ */
+import type { TrackerConfig } from '../types/index.js';
+export interface EdgeEnv {
+    /** 转发到真实 server_url 的可选 fetcher */
+    fetch?: typeof fetch;
+    /** D1 binding（可选，用于去重 / 缓冲） */
+    DB?: {
+        prepare: (sql: string) => {
+            bind: (...args: unknown[]) => {
+                run: () => Promise<unknown>;
+                all: () => Promise<{
+                    results?: unknown[];
+                }>;
+            };
+        };
+    };
+}
+export interface EdgeInitOptions extends Partial<TrackerConfig> {
+    /** Cloudflare env */
+    env?: EdgeEnv;
+    /** 队列缓冲上限 */
+    maxQueue?: number;
+    /** flush 间隔（ms） */
+    flushIntervalMs?: number;
+}
+export interface EdgeTracker {
+    track: (event: string, properties?: Record<string, unknown>) => Promise<void>;
+    flush: () => Promise<void>;
+    size: () => number;
+    close: () => void;
+}
+export declare function initEdge(options: EdgeInitOptions): EdgeTracker;
+/** 单事件便捷方法（不缓冲，立即发送） */
+export declare function trackOnce(event: string, properties: Record<string, unknown>, options: EdgeInitOptions): Promise<void>;

package/dist/types/federation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Module Federation 入口 (v1.3.0)
+ *
+ *  - 通过 @macroui/event-tracker/federation 暴露
+ *  - 暴露 named exports 让 host 应用可选择性加载
+ *  - 输出格式 ESM
+ */
+export * from '../core/tracker.js';
+export { EventTracker, initPara, registerAppid, listInstances } from '../core/tracker.js';
+export { SendPipeline } from '../core/send-pipeline.js';
+export { RetryPolicy } from '../core/retry-policy.js';
+export { FailedQueue } from '../core/failed-queue.js';
+export { StatsCollector, GLOBAL_STATS } from '../core/stats.js';
+export type { StatsSnapshot, SenderStat } from '../core/stats.js';
+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, aesGcmEncryptAsync } from '../plugins/encrypt/index.js';
+export { otelBridge } from '../plugins/otel-bridge/index.js';
+export { otelExporter } from '../plugins/otel-exporter/index.js';
+export { experiment, createExperiment } from '../plugins/experiment/index.js';
+export { predictiveBatcher } from '../plugins/predictive-batcher/index.js';
+export { piiDetector } from '../plugins/pii-detector/index.js';
+export { privacy } from '../plugins/privacy/index.js';
+export { crossDomainStitching } from '../plugins/cross-domain/index.js';
+export { schemaRegistry } from '../plugins/schema-registry/index.js';
+export { rateLimiter } from '../plugins/rate-limiter/index.js';
+export { cspCompliant } from '../plugins/csp-compliant/index.js';
+export { audienceSync } from '../plugins/audience-sync/index.js';

package/dist/types/index.d.ts

@@ -13,7 +13,7 @@ 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 { TrackerConfig, BaseConfig, SendConfig, StorageConfig, IdentityConfig, EncryptConfig, PresetConfig, DebugConfig, ObservabilityConfig, 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';
@@ -28,6 +28,27 @@ 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 { StatsCollector, GLOBAL_STATS } from './core/stats.js';
+export type { StatsSnapshot, SenderStat } from './core/stats.js';
+export { detectPlatform, platformStore, isPlatformSenderEnabled } from './core/platform.js';
+export type { Platform } from './core/platform.js';
+export { getWasmCrypto, fastHash, setWasmCrypto } from './core/wasm-crypto.js';
+export type { WasmCrypto } from './core/wasm-crypto.js';
+export { hmacSign, hmacSignSync, hmacVerify, signPayload } from './core/payload-signer.js';
+export type { SignOptions } from './core/payload-signer.js';
+export { PiiDetector, fnv1a, maskValue, DEFAULT_PATTERNS } from './core/pii.js';
+export type { PiiOptions, PiiAction, PiiPattern } from './core/pii.js';
+export { PrivacyManager } from './core/privacy.js';
+export type { PrivacyMode, ConsentScope, PrivacyState } from './core/privacy.js';
+export { createReplay } from './core/replay.js';
+export type { ReplayEvent, ReplayOptions, ReplayHandle } from './core/replay.js';
+export { createIdleScheduler, whenIdle, globalIdleScheduler } from './core/idle.js';
+export type { IdleScheduler, IdleCallback } from './core/idle.js';
+export { OffscreenSender } from './send/offscreen-sender.js';
+export { WebSocketSender } from './send/ws-sender.js';
+export type { WebSocketSenderOptions } from './send/ws-sender.js';
+export { initEdge, trackOnce } from './edge/index.js';
+export type { EdgeTracker, EdgeInitOptions, EdgeEnv } from './edge/index.js';
 export { PresetEvent, PresetProperty, LIB_NAME, LIB_VERSION };
 export { autoTrack } from './plugins/auto-track/index.js';
 export { pageLoad } from './plugins/pageload/index.js';
@@ -37,4 +58,24 @@ 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 type { BridgeAPI, WebViewBridgeOptions } from './plugins/webview-bridge/index.js';
 export { encryptor, xorEncryptor, defaultEncryptor, defaultDecryptor, aesGcmEncryptAsync, aesGcmDecryptAsync } from './plugins/encrypt/index.js';
+export { otelBridge } from './plugins/otel-bridge/index.js';
+export { otelExporter } from './plugins/otel-exporter/index.js';
+export type { OtlpHttpOptions, SpanData, OtelEvent, OtelExporterOptions } from './plugins/otel-exporter/index.js';
+export { experiment, createExperiment } from './plugins/experiment/index.js';
+export type { ExperimentVariant, ExperimentOptions, ExperimentContext } from './plugins/experiment/index.js';
+export { predictiveBatcher, makeIntervalPredictor } from './plugins/predictive-batcher/index.js';
+export { piiDetector } from './plugins/pii-detector/index.js';
+export { privacy } from './plugins/privacy/index.js';
+export type { PrivacyOptions } from './plugins/privacy/index.js';
+export { crossDomainStitching } from './plugins/cross-domain/index.js';
+export type { CrossDomainOptions } from './plugins/cross-domain/index.js';
+export { schemaRegistry, SchemaRegistry } from './plugins/schema-registry/index.js';
+export type { SchemaEntry, SchemaOptions } from './plugins/schema-registry/index.js';
+export { rateLimiter, RateLimiter } from './plugins/rate-limiter/index.js';
+export type { RateLimiterOptions, RateLimitRule } from './plugins/rate-limiter/index.js';
+export { cspCompliant } from './plugins/csp-compliant/index.js';
+export type { CspOptions } from './plugins/csp-compliant/index.js';
+export { audienceSync, AudienceSync } from './plugins/audience-sync/index.js';
+export type { AudienceDestination, AudienceSyncOptions, AudienceContext } from './plugins/audience-sync/index.js';

package/dist/types/plugins/audience-sync/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Audience Sync（v1.3.0）
+ *
+ *  - 用户登录/属性变更后，把 distinct_id 同步到外部平台（Mailchimp / Braze / 自定义 webhook）
+ *  - 订阅式：sdk.on('identify', cb)
+ *  - 支持多 destination
+ */
+export interface AudienceDestination {
+    name: string;
+    endpoint: string;
+    method?: 'POST' | 'PUT';
+    headers?: Record<string, string>;
+    /** 转换器：把 distinctId + props 转成目标平台格式 */
+    transform?: (data: {
+        distinct_id: string;
+        properties: Record<string, unknown>;
+        traits?: Record<string, unknown>;
+    }) => unknown;
+}
+export interface AudienceSyncOptions {
+    destinations: AudienceDestination[];
+    /** 触发条件：'identify' | 'login' | 'all' */
+    triggerOn?: 'identify' | 'login' | 'all';
+    /** 失败重试次数 */
+    maxRetry?: number;
+}
+export interface AudienceContext {
+    subscribe(fn: (data: {
+        distinct_id: string;
+        properties?: Record<string, unknown>;
+        traits?: Record<string, unknown>;
+        trigger: string;
+    }) => void): () => void;
+    flush(): Promise<void>;
+    queueSize(): number;
+}
+export declare class AudienceSync {
+    options: AudienceSyncOptions;
+    private listeners;
+    private pending;
+    constructor(options: AudienceSyncOptions);
+    subscribe(fn: (data: {
+        distinct_id: string;
+        properties?: Record<string, unknown>;
+        traits?: Record<string, unknown>;
+        trigger: string;
+    }) => void): () => void;
+    emit(data: {
+        distinct_id: string;
+        properties?: Record<string, unknown>;
+        traits?: Record<string, unknown>;
+        trigger: string;
+    }): void;
+    /** 缓存到队列（用于晚点批量） */
+    enqueue(data: {
+        distinct_id: string;
+        properties?: Record<string, unknown>;
+        traits?: Record<string, unknown>;
+        trigger: string;
+    }): void;
+    queueSize(): number;
+    /** 手动 flush：把队列里的事件推到所有 destination */
+    flush(): Promise<void>;
+    private send;
+}
+import type { Plugin } from '../../core/plugin.js';
+export declare function audienceSync(options: AudienceSyncOptions): Plugin;

package/dist/types/plugins/cross-domain/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cross-domain Stitching（v1.3.0）
+ *
+ *  - 在 cookie 写入 _sa_link_id（同根域跨子域共享）
+ *  - 客户端初始化时检测：当前 distinct_id 是否与 _sa_link_id 绑定
+ *  - 未登录用户跨子域跳转时，session 连续
+ *  - 不依赖登录态
+ */
+import type { Plugin } from '../../core/plugin.js';
+export interface CrossDomainOptions {
+    /** cookie 名，默认 _sa_link_id */
+    cookieName?: string;
+    /** 共享域（如 .example.com），自动加 . */
+    domain?: string;
+    /** 过期天数，默认 365 */
+    expiresDays?: number;
+    /** 是否把 _sa_link_id 注入到 register / event properties */
+    injectProperty?: boolean;
+}
+export declare function crossDomainStitching(opts?: CrossDomainOptions): Plugin;

package/dist/types/plugins/csp-compliant/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CSP Nonce 支持（v1.3.0）
+ *
+ *  - 从 meta[name=csp-nonce] 或 config.csp_nonce 读 nonce
+ *  - 在 sendDataStage 给所有事件加 $csp_nonce 属性
+ *  - 业务侧可以用它把数据通过合法 CSP 通道回传到自家 server
+ */
+import type { Plugin } from '../../core/plugin.js';
+export interface CspOptions {
+    /** 直接传 nonce 字符串 */
+    nonce?: string;
+    /** 从 meta[name=csp-nonce] 读 */
+    metaSelector?: string;
+    /** 是否自动注册为 event property */
+    injectProperty?: boolean;
+}
+export declare function cspCompliant(opts?: CspOptions): Plugin;

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

@@ -0,0 +1,43 @@
+/**
+ * A/B Test / 实验埋点 helper（v1.2.0）
+ *
+ * 提供：
+ *  - sdk.experiment(key, variants): 根据 variants 配置确定分组，sticky（localStorage）
+ *  - 每次 track 时自动注入 $experiment_key / $variant_id
+ *  - 支持曝光事件：exposure(key, variant)
+ *  - 不依赖外部实验平台 SDK
+ */
+import type { Plugin } from '../../core/plugin.js';
+import type { StorageType } from '../../types/index.js';
+export interface ExperimentVariant {
+    /** 实验分组 id */
+    id: string;
+    /** 权重（数字，绝对值或 0-100 百分比） */
+    weight?: number;
+    /** 默认附加的 properties（会 merge 到事件 properties） */
+    properties?: Record<string, unknown>;
+}
+export interface ExperimentOptions {
+    /** 自定义存储前缀 */
+    storagePrefix?: string;
+    /** 存储类型（默认 localStorage） */
+    storage?: StorageType;
+}
+export interface ExperimentContext {
+    /** 拉取指定实验的分组（无配置返回 null） */
+    variantOf: (key: string) => ExperimentVariant | null;
+    /** 直接获取 variant id */
+    variantIdOf: (key: string) => string | null;
+    /** 上报曝光（一次会话只上报一次） */
+    exposure: (key: string, properties?: Record<string, unknown>) => void;
+    /** 强制设置（debug 用） */
+    forceSet: (key: string, variantId: string) => void;
+    /** 列出当前所有已分配 */
+    list: () => Record<string, string>;
+}
+/**
+ * 创建实验上下文（不依赖 SDK，可单独用）
+ */
+export declare function createExperiment(experiments: Record<string, ExperimentVariant[]>, opts?: ExperimentOptions): ExperimentContext;
+/** 插件形态：把 experiment 注入到事件 properties */
+export declare function experiment(experiments: Record<string, ExperimentVariant[]>, opts?: ExperimentOptions): Plugin;

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

@@ -0,0 +1,22 @@
+/**
+ * OpenTelemetry Bridge Plugin (v1.2.0)
+ *
+ * 把 SDK 事件转发到 OTel：
+ *   - track → otel tracer.startActiveSpan
+ *   - 用 @opentelemetry/api 作为可选 peer dependency
+ *   - 通过 dynamic import 兼容未安装 OTel 的场景
+ *   - 属性透传：event 类型 / properties → span attributes
+ *   - 支持自定义 mapper
+ */
+import type { Plugin } from '../../core/plugin.js';
+export interface OtelBridgeOptions {
+    /** tracer 名（默认 '@macroui/event-tracker'） */
+    tracerName?: string;
+    /** span 名映射：(eventName) => spanName，默认 = eventName */
+    spanName?: (event: string) => string;
+    /** 属性过滤：返回 false 的属性不上报 */
+    filterAttr?: (key: string, value: unknown) => boolean;
+    /** 全局关闭 */
+    enabled?: boolean;
+}
+export declare function otelBridge(opts?: OtelBridgeOptions): Plugin;

package/dist/types/plugins/otel-exporter/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * OpenTelemetry Exporter (v1.3.0)
+ *
+ *  - OTLP/HTTP + OTLP/gRPC 两种协议
+ *  - 把 EventTracker 事件 → OTel Span
+ *  - 不依赖 @opentelemetry/api（内部实现）
+ *  - 可独立 import：@macroui/event-tracker/plugin/otel-exporter
+ */
+export interface OtlpHttpOptions {
+    endpoint: string;
+    headers?: Record<string, string>;
+    /** gzip */
+    gzip?: boolean;
+    /** timeout (ms) */
+    timeoutMs?: number;
+}
+export interface SpanData {
+    name: string;
+    kind?: 'SPAN_KIND_INTERNAL' | 'SPAN_KIND_CLIENT' | 'SPAN_KIND_SERVER';
+    startTimeUnixNano: bigint | number;
+    endTimeUnixNano: bigint | number;
+    attributes: Array<{
+        key: string;
+        value: {
+            stringValue?: string;
+            intValue?: number | bigint;
+            boolValue?: boolean;
+        };
+    }>;
+    traceId: string;
+    spanId: string;
+}
+export interface OtelEvent {
+    name: string;
+    properties?: Record<string, unknown>;
+    time: number;
+    distinctId?: string;
+}
+export declare function eventToSpan(ev: OtelEvent): SpanData;
+export declare function exportOtlpHttp(events: OtelEvent[], opts: OtlpHttpOptions): Promise<void>;
+/** OTel Exporter Plugin 形态 */
+export interface OtelExporterOptions extends OtlpHttpOptions {
+    /** 上报前过滤 */
+    filter?: (ev: OtelEvent) => boolean;
+    /** 批量上报：攒够 N 条 / T ms 触发 */
+    batchSize?: number;
+    batchIntervalMs?: number;
+}
+import type { Plugin } from '../../core/plugin.js';
+export declare function otelExporter(opts: OtelExporterOptions): Plugin;

package/dist/types/plugins/pii-detector/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PII Detection Plugin (v1.3.0)
+ *
+ * 在 sendDataStage 拦截所有事件 properties，扫描 PII 并做脱敏
+ */
+import type { Plugin } from '../../core/plugin.js';
+import type { PiiOptions } from '../../core/pii.js';
+export declare function piiDetector(opts?: PiiOptions): Plugin;

package/dist/types/plugins/predictive-batcher/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Predictive Batching（v1.2.0）
+ *
+ *  - 监听 user activity（click/scroll/keypress/mousemove 节流）
+ *  - 高活动期：缩短 batch flush 间隔
+ *  - 低活动期：拉长间隔，省电 / 省流量
+ *  - 通过 SDK config.batch_send.dynamic_interval 启用
+ *
+ * 不属于 SDK 强耦合：作为可选插件
+ */
+import type { Plugin } from '../../core/plugin.js';
+export interface PredictiveBatchOptions {
+    /** 最小间隔（活动期） */
+    minInterval?: number;
+    /** 最大间隔（静默期） */
+    maxInterval?: number;
+    /** 活动统计窗口（ms） */
+    windowMs?: number;
+    /** 活动阈值（窗口内事件 > 此数视为活动期） */
+    activityThreshold?: number;
+    /** 是否监听这些事件类型 */
+    events?: ('click' | 'scroll' | 'keypress' | 'mousemove' | 'touchstart')[];
+}
+/**
+ * 不修改 SDK 内部，而是提供一个工具函数 getInterval(opts)
+ * 业务侧在 BatchSender.flush interval 决策时调用
+ */
+export declare function makeIntervalPredictor(opts?: PredictiveBatchOptions): () => number;
+export declare function predictiveBatcher(opts?: PredictiveBatchOptions): Plugin;

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

@@ -0,0 +1,19 @@
+/**
+ * Privacy & Consent Plugin (v1.3.0)
+ *
+ *  - 接入 PrivacyManager 到 SDK
+ *  - sendDataStage 拦截：
+ *      1. 未授权 scope → drop
+ *      2. 按 privacy_mode 脱敏
+ *  - 在 sdk 上挂 sdk.privacy / sdk.consent API
+ */
+import type { Plugin } from '../../core/plugin.js';
+import type { ConsentScope, PrivacyMode } from '../../core/privacy.js';
+export interface PrivacyOptions {
+    mode?: PrivacyMode;
+    /** 缺哪些 scope 时不 track？默认 ['analytics'] */
+    requireScopes?: ConsentScope[];
+    /** 是否在 init 时打印授权 banner */
+    showBanner?: boolean;
+}
+export declare function privacy(opts?: PrivacyOptions): Plugin;

package/dist/types/plugins/rate-limiter/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Rate Limiter（v1.3.0）
+ *
+ *  - 三档限流：
+ *      1. 全局（global）：每秒最多 N 条
+ *      2. 用户级（user）：每用户每秒最多 M 条
+ *      3. per-event（event）：每个事件名每秒最多 K 条
+ *  - 超出 drop + 触发 onDrop 回调
+ *  - 用滑动窗口（100ms bucket）实现
+ */
+export interface RateLimitRule {
+    /** 时间窗口（ms） */
+    windowMs: number;
+    /** 窗口内最大条数 */
+    max: number;
+}
+export interface RateLimiterOptions {
+    global?: RateLimitRule;
+    user?: RateLimitRule;
+    perEvent?: RateLimitRule;
+    /** 触发 drop 回调 */
+    onDrop?: (info: {
+        scope: 'global' | 'user' | 'event';
+        key?: string;
+        event?: string;
+    }) => void;
+}
+export declare class RateLimiter {
+    private opts;
+    private globalBuckets;
+    private userBuckets;
+    private eventBuckets;
+    constructor(opts: RateLimiterOptions);
+    /** 是否允许 */
+    allow(event: string, userId?: string): boolean;
+    private checkBucket;
+    /** 清空所有 bucket */
+    reset(): void;
+}
+import type { Plugin } from '../../core/plugin.js';
+export declare function rateLimiter(opts: RateLimiterOptions): Plugin;

package/dist/types/plugins/schema-registry/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Schema Registry 校验（v1.3.0）
+ *
+ *  - 内置默认 schemas：pageview / track / profile_set
+ *  - 支持自定义 schemas：schema({eventName, jsonSchema})
+ *  - 远程 schema URL：服务端可下发（带 ETag 缓存）
+ *  - 校验失败：默认 warn + 仍上报（可配置 drop）
+ *  - 动态 import ajv，未安装时 noop
+ */
+import type { Plugin } from '../../core/plugin.js';
+export interface SchemaEntry {
+    /** 事件名 */
+    event: string;
+    /** JSON Schema（Draft-07 兼容） */
+    schema: Record<string, unknown>;
+}
+export interface SchemaOptions {
+    /** 自定义 schemas */
+    schemas?: SchemaEntry[];
+    /** 远程 schema URL（HTTP 拉取，带 ETag） */
+    remoteUrl?: string;
+    /** 校验失败处理 */
+    onInvalid?: 'warn' | 'drop' | 'pass';
+    /** 远程 schema TTL（ms），默认 1h */
+    remoteTtlMs?: number;
+}
+export declare class SchemaRegistry {
+    private opts;
+    private ajv;
+    private entries;
+    private remoteCache;
+    constructor(opts: SchemaOptions);
+    init(): Promise<void>;
+    add(entry: SchemaEntry): void;
+    private fetchRemote;
+    validate(event: string, data: unknown): {
+        ok: boolean;
+        errors?: unknown[];
+    };
+}
+export declare function schemaRegistry(opts?: SchemaOptions): Plugin;