@evertro/monitor-types

Evertro Monitor 共享类型定义包

概述

本包是整个 Evertro Monitor SDK 的类型基础层，定义了所有包共享的 TypeScript 接口、枚举和配置类型。其他所有包都依赖本包，但本包不依赖任何其他 @evertro 包，处于依赖树的最底层。

本包不包含任何运行时逻辑，构建产物仅包含类型声明（.d.ts）和枚举/常量的最小 JS 代码。

安装

pnpm add @evertro/monitor-types

模块说明

events.ts — 事件类型定义

SDK 的核心数据模型，定义了所有监控事件的结构。

事件 ID 枚举

对齐旧版 @tracking-sdk/apm 的 EventName 表，保持后端兼容性：

import { EventId, EventNameMap } from '@evertro/monitor-types';

// 事件 ID 枚举（E100000xxx 格式）
EventId.LOGIN            // 'E100000001' — 登陆
EventId.LOGOUT           // 'E100000002' — 退出登陆
EventId.STARTUP          // 'E100000006' — 应用启动
EventId.SHOW             // 'E100000007' — 显示（从后台恢复）
EventId.HIDE             // 'E100000008' — 进入后台
EventId.PAGE_VIEW        // 'E100000010' — 页面浏览
EventId.CLICK            // 'E100000011' — 元素点击
EventId.ERROR            // 'E100000015' — JS 错误
EventId.SEARCH           // 'E100000018' — 搜索点击
EventId.WHITE_SCREEN     // 'E100000020' — 白屏事件
EventId.PERFORMANCE      // 'E100000021' — 性能事件
EventId.NETWORK_ERROR    // 'E100000022' — 网络错误
EventId.PROMISE_REJECTION// 'E100000023' — Promise 拒绝
EventId.RESOURCE_ERROR   // 'E100000024' — 资源加载错误
EventId.REACT_ERROR      // 'E100000025' — React 错误边界
EventId.CUSTOM_MESSAGE   // 'E100000030' — 自定义消息

// 获取事件中文名
EventNameMap[EventId.ERROR] // '错误事件'

内部事件接口

SDK 管道内部使用的结构化事件类型：

| 接口 | 描述 | type 值 | |------|------|---------| | ErrorEvent | 错误事件 | js_error / promise_rejection / network_error / resource_error / react_error | | WhiteScreenEvent | 白屏事件 | white_screen | | PerformanceEvent | 性能事件 | page_load / api_call / fcp / lcp / fp / memory_warning / long_task | | MonitorEvent | 以上三者的联合类型 | — |

每个事件接口都包含以下由引擎自动填充的可选字段：

interface ErrorEvent {
  eventId?: EventId;    // 由 enrichEventFields() 自动计算
  eventName?: string;   // 由 enrichEventFields() 自动计算
  eventCode?: string;   // 由 enrichEventFields() 自动计算
  // ... 其他必填字段
}

事件优先级

enum EventPriority {
  IMMEDIATE = 0, // P0 - 即时上报：白屏、崩溃
  BATCH     = 1, // P1 - 批量上报：JS 错误、Promise 拒绝
  SCHEDULED = 2, // P2 - 定时上报：性能数据、操作链路
}

上报载荷（对齐旧 APM SDK）

ReportPayload 采用旧 @tracking-sdk/apm 的扁平结构，设备/用户信息打平到外层：

interface ReportPayload {
  screenHeight: number;  screenWidth: number;
  source: string | number;  terminal: string;
  sessionId: string;  visitorId: string;  env: string;
  appConfig: AppConfig;
  userId: string;  userName: string;  uId: string;  city: string;
  networkType: string;  os: string;  osInfo: string;  osVersion: string;
  deviceModel: string;  browserName: string;  browserVersion: string;
  collectSource: string;
  events: ReportEvent[];
}

interface ReportEvent {
  eventId: EventId;        // E100000015
  eventName: string;       // '错误事件'
  eventCode: string;       // 'ERROR-/pages/index'
  eventTime: number;       // 时间戳
  attr: Record<string, unknown>; // 事件属性
}

breadcrumb.ts — 操作链路类型

type BreadcrumbType = 'navigation' | 'click' | 'input' | 'request' | 'lifecycle' | 'console' | 'custom';
type BreadcrumbLevel = 'info' | 'warning' | 'error';

interface Breadcrumb {
  type: BreadcrumbType;
  category: string;    // 如 'navigateTo', 'xhr', 'fetch'
  message: string;     // 如 '跳转到 /pages/index'
  data?: Record<string, unknown>;
  timestamp: number;
  level: BreadcrumbLevel;
}

context.ts — 上下文类型

interface UserContext {
  userId?: string;
  userType?: number;
  projectId?: string;
  sessionId: string;
  isLogin: boolean;
  [key: string]: unknown; // 自定义扩展
}

interface DeviceContext {
  platform: PlatformType;   // 'weapp' | 'tt' | 'h5' | 'pc'
  sdkVersion?: string;      // 小程序基础库版本
  appVersion?: string;
  envVersion?: 'develop' | 'trial' | 'release';
  brand?: string;  model?: string;  system?: string;
  browserName?: string;  browserVersion?: string;
  screenWidth: number;  screenHeight: number;  pixelRatio: number;
  networkType?: string;
}

interface MonitorContext {
  user: UserContext;
  device: DeviceContext;
}

config.ts — 配置类型

interface MonitorConfig {
  appId: string;                // 应用标识（必填）
  dsn: string;                  // 上报地址（必填）
  environment?: string;         // production / development / test / uat
  release?: string;             // 版本号
  sampleRate?: number;          // 采样率 0~1，默认 1.0
  debug?: boolean;              // 调试模式

  // 功能开关（默认全部 true）
  enableErrorCapture?: boolean;
  enableWhiteScreen?: boolean;
  enableBreadcrumbs?: boolean;
  enablePerformance?: boolean;
  enableNetworkMonitor?: boolean;

  // 高级配置
  breadcrumbsLimit?: number;     // 操作链路上限，默认 30
  whiteScreenTimeout?: number;   // 白屏检测超时 ms，默认 5000
  reportBatchSize?: number;      // 批量上报条数，默认 10
  reportInterval?: number;       // 定时上报间隔 ms，默认 10000
  maxRetries?: number;           // 上报重试次数，默认 3
  maxCacheSize?: number;         // 离线缓存上限条数，默认 100

  // 过滤 & 脱敏
  beforeSend?: (event: MonitorEvent) => MonitorEvent | null;
  sensitiveFields?: string[];    // 默认 ['token','password','phone','idCard']
  ignoreErrors?: (string | RegExp)[];
}

plugin.ts — 插件接口

interface MonitorPlugin {
  name: string;
  setup(ctx: PluginContext): void;
  teardown?(): void;
}

interface PluginContext {
  config: MonitorConfig;
  eventHub: IEventHub;
  contextManager: IContextManager;
  breadcrumbs: IRingBuffer<Breadcrumb>;
  report: (event: MonitorEvent) => void;
  addBreadcrumb: (crumb: BreadcrumbInput) => void;
}

依赖关系

本包无外部依赖，是整个 SDK 的依赖树根节点。

@evertro/monitor-types  ←  core  ←  transport
                        ←  miniapp
                        ←  web
                        ←  taro  ←  browser

导出一览

// 枚举 & 常量
export { EventPriority, EventId, EventNameMap } from './events';
export { DEFAULT_CONFIG } from './config';

// 类型
export type {
  ErrorEventType, PerformanceEventType, WhiteScreenCheckMethod,
  ErrorEvent, WhiteScreenEvent, PerformanceEvent,
  MonitorEvent, ReportPayload, ReportEvent, AppConfig,
  BreadcrumbType, BreadcrumbLevel, Breadcrumb, BreadcrumbInput,
  UserContext, PlatformType, DeviceContext, MonitorContext,
  MonitorConfig,
  IEventHub, IRingBuffer, IContextManager, PluginContext, MonitorPlugin,
};