@zhaogyna/types

Monitor SDK 的共享 TypeScript 类型定义包，零运行时代码，仅供其他包引用类型。

安装

npm install @zhaogyna/types

本包为内部依赖层，终端用户通常无需单独安装。框架包（@zhaogyna/browser / @zhaogyna/react 等）已自动包含。

导出类型

事件模型

| 类型 | 说明 | |------|------| | Severity | 错误严重级别枚举 | | EventType | 事件类型联合：'error' \| 'transaction' \| 'track' \| 'resource' \| 'custom' | | BaseEvent | 所有事件的基类形状 | | MonitorErrorEvent | 错误事件（含 exception values） | | TransactionEvent | 事务/追踪事件 | | TrackEvent | 自定义埋点事件 | | ResourceEvent | 资源时序事件 | | MonitorCustomEvent | 自定义事件 | | Event | 以上 5 种事件的联合类型 |

MonitorErrorEvent 和 MonitorCustomEvent 已重命名，避免与浏览器原生 ErrorEvent / CustomEvent 冲突。

辅助类型

| 类型 | 说明 | |------|------| | SdkInfo | SDK 版本信息 | | User | 用户标识（id, email, username, ip_address） | | Contexts | 上下文容器（app, device, os, browser, trace 等） | | RequestContext | 请求上下文（url, headers, cookies） | | TraceContext | 追踪上下文（traceId, spanId, parentSpanId, sampled） | | Span | Span 数据模型 | | StackFrame | 堆栈帧（filename, function, lineno, colno 等） | | Mechanism | 错误机制标识（type, handled, data） | | Exception | 异常数据（type, value, stacktrace） | | Breadcrumb | 面包屑记录（6 种类型 + 级别） | | PageViewProperties | PV 事件属性 |

核心接口

Options — SDK 完整配置

interface Options {
  // 必填
  dsn: string                          // 数据上报地址

  // 采样
  sampleRate?: number                  // 错误采样率（0~1，默认 1）
  tracesSampleRate?: number            // 链路追踪采样率（0~1，默认 0）
  tracesSampler?: TracesSamplerCallback // 动态链路采样函数
  trackSampleRate?: number             // Track 事件采样率（0~1，默认 1）
  replaysSessionSampleRate?: number    // 会话回放-会话级采样率（0~1，默认 0）
  replaysOnErrorSampleRate?: number    // 会话回放-错误触发采样率（0~1，默认 0）

  // 环境
  release?: string                     // 应用版本号（用于 SourceMap 关联）
  environment?: string                 // 环境标识
  initialScope?: {                     // 初始作用域
    user?: User
    tags?: Record<string, string>
    extra?: Record<string, any>
    level?: Severity
  }

  // 钩子
  beforeSend?: BeforeSendCallback       // 事件发送前，返回 null 丢弃
  beforeSendTransaction?: BeforeSendTransactionCallback // 事务事件发送前
  beforeBreadcrumb?: BeforeBreadcrumbCallback           // 面包屑添加前
  beforeTrack?: BeforeTrackCallback                    // Track 事件发送前

  // 过滤
  ignoreErrors?: (string | RegExp)[]    // 忽略的错误
  denyUrls?: (string | RegExp)[]       // 拒绝采集的脚本 URL
  allowUrls?: (string | RegExp)[]      // 允许采集的脚本 URL

  // 序列化
  normalizeDepth?: number               // 递归 normalize 深度（默认 3）
  normalizeMaxSize?: number             // 最大规范化条目数（默认 1000）
  normalizeMaxStringLength?: number     // 字符串截断长度（默认 250）

  // 传输
  transport?: (options: any) => Transport // 自定义 Transport 工厂
  tunnel?: string                       // 代理隧道（绕过 CORS）
  sendClientReports?: boolean           // 发送客户端报告（默认 true）
  maxQueueSize?: number                 // 发送队列最大容量（默认 30）

  // 集成
  integrations?: Integration[]          // 自定义集成列表
  defaultIntegrations?: boolean | Integration[] // 默认集成控制
  enableTracing?: boolean               // 启用追踪（默认 false）

  // 栈追踪
  attachStacktrace?: boolean            // 非异常事件附加调用栈（默认 true）
  maxStackFrames?: number               // 最大堆栈帧数（默认 50）

  // 采集
  sendCookies?: boolean                 // 采集 Cookie（默认 false）
  collectModules?: boolean              // 采集 Webpack 模块列表（默认 false）
  maxBreadcrumbs?: number              // 面包屑上限（默认 100）

  // 埋点
  maxTrackPerSecond?: number            // 每秒最大 Track 数（默认 10）
  maxTrackProperties?: number           // Track 属性上限（默认 20）
  exposureBatchSize?: number            // 曝光批量上报数（默认 10）
  exposureBatchInterval?: number        // 曝光批量间隔 ms（默认 3000）
  clickDebounceMs?: number             // 点击去重窗口 ms（默认 300）
  trackDedupeInterval?: number          // Track 去重窗口 ms（默认 1000）
  minStayDuration?: number             // 停留最短时长 ms（默认 1000）
  stripTrackKeys?: string[]            // Track 属性脱敏键名
  stripUrlParams?: string[]            // URL 脱敏参数名

  // 调试
  debug?: boolean                       // 调试日志（默认 false）
  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none'
}

Integration — 集成接口

interface Integration {
  name: string
  setupOnce?: (addGlobalEventProcessor: Function) => void
  setup?: (client: Client) => void
  afterAllSetup?: (client: Client) => void
  preprocessEvent?: (event: Event, hint: any) => Event | null | Promise<Event | null>
  processEvent?: (event: Event, hint: any) => Event | null | Promise<Event | null>
  teardown?: () => void
  onBfcacheRestore?: () => void
}

Client — 客户端接口

interface Client {
  getOptions(): Options
  getDsn(): string
  captureEvent(event: Event, hint?: any): string
  destroy(): void
  getSession(): Session | undefined
  setSession(session: Session): void
  flush(timeout?: number): Promise<boolean>
  close(timeout?: number): Promise<boolean>
  getIntegrations(): Integration[]
  getTransport(): Transport
  getScopeStack(): Scope[]
  getScopeData(): ScopeData
  isInitialized(): boolean
}

Transport — 传输接口

interface Transport {
  send(request: TransportRequest): Promise<void>
  flush(timeout?: number): Promise<boolean>
  close?(timeout?: number): Promise<boolean>
}

interface TransportRequest {
  body: string
  type: 'event' | 'transaction' | 'track' | 'attachment' | 'session' | 'client_report'
}

License

MIT