npm - @fz-firefly/shared - Versions diffs - 0.0.0-stage → 0.2.0 - Mend

@fz-firefly/shared 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/index.d.cts ADDED Viewed

@@ -0,0 +1,1583 @@
+import { z } from "zod";
+/**
+ * 全局硬性限制。
+ *
+ * 这组数字同时被三方使用：
+ * - SDK 在采集阶段就按上限裁剪，避免把超大报文发出去；
+ * - 服务端用同一组值做二次校验，防止客户端绕过；
+ * - 后台据此提示「已被截断」。
+ *
+ * 集中定义可以保证三端不会各说各话。修改这里的值等于修改协议，
+ * 必须同时评估已接入的旧版 SDK。
+ */
+export declare const LIMITS: {
+  /** 单个上报信封的最大字节数（256 KB）。服务端超限直接返回 413。 */
+  readonly MAX_BODY_BYTES: number;
+  /** 一个信封最多携带的 item 数（50）。SDK 超限时自动拆成多个信封。 */
+  readonly MAX_ITEMS: 50;
+  /** 单条异常最多保留的堆栈帧数（100）。超出时保留首尾各 50 帧，中间的丢掉。 */
+  readonly MAX_FRAMES: 100;
+  /** 单条事件最多保留的面包屑条数（50）。超出时丢最旧的，保证最近的现场还在。 */
+  readonly MAX_BREADCRUMBS: 50;
+  /** 单个字符串字段的最大长度（16384 字符）。超出截断并打标记。 */
+  readonly MAX_FIELD_CHARS: 16384;
+  /** URL 类字段的最大长度（2048 字符）。 */
+  readonly MAX_URL_CHARS: 2048;
+  /** 原始错误事件的保留天数（90 天）。过期分区整月 DROP，不做逐行删除。 */
+  readonly EVENT_RETENTION_DAYS: 90;
+  /** 每个项目每分钟允许的上报请求数（300）。超出返回 429 + Retry-After。 */
+  readonly INGEST_RATE_LIMIT: 300;
+  /** occurred_at 允许比服务器时间早多少毫秒（7 天）。用于容忍离线补报。 */
+  readonly OCCURRED_AT_PAST_MS: number;
+  /** occurred_at 允许比服务器时间晚多少毫秒（5 分钟）。用于容忍设备时钟漂移。 */
+  readonly OCCURRED_AT_FUTURE_MS: number;
+};
+/**
+ * 错误分类。
+ *
+ * - code：代码错误，包含运行时异常、Promise 拒绝、框架错误等；
+ * - interface：接口错误，包含 HTTP 失败、网络错误、超时和静态资源加载失败。
+ *
+ * 分类由 SDK 在捕获点写入，服务端按上报值存储，不再推断。
+ */
+export declare const ERROR_CATEGORIES: readonly ["code", "interface"];
+/**
+ * 接口错误的来源。
+ *
+ * 代码错误不需要 source；接口错误用它区分 HTTP 失败、静态资源失败和手动消息。
+ */
+export declare const ERROR_SOURCES: readonly ["http", "resource", "message"];
+/**
+ * 事件级别，按严重程度从高到低排列。
+ * 聚合 issue 时取范围内最严重的一级（fatal > error > warning > info），
+ * 所以这个数组的顺序本身就是语义，不能随意调整。
+ */
+export declare const LEVELS: readonly ["fatal", "error", "warning", "info"];
+/**
+ * 运行时平台标识，会写进每条事件，供后台筛选。
+ *
+ * 注意：这是「代码跑在哪」，不是「你用什么写的」。
+ * 一个 uni-app 项目同一份源码在 H5 下是 web，在微信里是 mp-weixin，
+ * 由 SDK 运行时用 uni.getSystemInfoSync().uniPlatform 判定。
+ */
+export declare const PLATFORMS: readonly ["web", "mp-weixin", "mp-alipay", "app"];
+/**
+ * 环境标识。issue 的唯一键是 (项目, 环境, 指纹)，
+ * 所以生产与测试的同类错误会各自聚合成独立 issue，计数互不污染。
+ * 如需新增环境（例如 pre），必须同步服务端 issue 的唯一键与后台筛选项。
+ */
+export declare const ENVIRONMENTS: readonly ["production", "staging", "development"];
+/** 事件级别：fatal | error | warning | info */
+export type Level = (typeof LEVELS)[number];
+/** 运行时平台：web | mp-weixin | mp-alipay | app */
+export type Platform = (typeof PLATFORMS)[number];
+/** 运行环境：production | staging | development */
+export type Environment = (typeof ENVIRONMENTS)[number];
+/** 错误分类：code | interface */
+export type ErrorCategory = (typeof ERROR_CATEGORIES)[number];
+/** 接口错误来源：http | resource | message */
+export type ErrorSource = (typeof ERROR_SOURCES)[number];
+/** 单个堆栈帧。 */
+export type StackFrame = z.infer<typeof StackFrameSchema>;
+/** 异常本体：类型、消息、堆栈。 */
+export type Exception = z.infer<typeof ExceptionSchema>;
+/** 一条面包屑。 */
+export type Breadcrumb = z.infer<typeof BreadcrumbSchema>;
+/** 用户标识（仅 id 与匿名 id）。 */
+export type UserContext = z.infer<typeof UserContextSchema>;
+/** 错误事件。 */
+export type ErrorItem = z.infer<typeof ErrorItemSchema>;
+/** 消息事件。 */
+export type MessageItem = z.infer<typeof MessageItemSchema>;
+/** 业务埋点事件。 */
+export type TrackItem = z.infer<typeof TrackItemSchema>;
+/** 任意一种事件（error | message | track 的联合类型）。 */
+export type EventItem = z.infer<typeof EventItemSchema>;
+/**
+ * 单个堆栈帧。
+ *
+ * 生产构建后的帧来自压缩代码：filename 是构建产物 URL，lineno/colno 是压缩位置。
+ * 服务端拿到 sourcemap 后会把它们改写成源码位置，并保留原始值在 raw_exception 里。
+ */
+export declare const StackFrameSchema: z.ZodObject<{
+  /** 帧所属文件。H5 通常是完整 URL 或 /assets/xxx.js 路径。 */
+  filename: z.ZodString;
+  /** 绝对路径。浏览器给不出时与 filename 相同；用于匹配 sourcemap 时更可靠。 */
+  abs_path: z.ZodOptional<z.ZodString>;
+  /** 函数名。压缩后可能只是一个字母，还原后才是真实函数名。 */
+  function: z.ZodOptional<z.ZodString>;
+  /** 行号（从 1 开始）。压缩代码里通常都是 1。 */
+  lineno: z.ZodOptional<z.ZodNumber>;
+  /** 列号（从 0 开始）。sourcemap 还原靠它定位到具体字符。 */
+  colno: z.ZodOptional<z.ZodNumber>;
+  /**
+   * 该帧是否属于业务代码。
+   * 依赖与框架内部（node_modules、框架运行时）为 false，参与指纹计算时只取 true 的帧。
+   */
+  in_app: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+  filename: string;
+  in_app: boolean;
+  function?: string | undefined;
+  abs_path?: string | undefined;
+  lineno?: number | undefined;
+  colno?: number | undefined;
+}, {
+  filename: string;
+  function?: string | undefined;
+  abs_path?: string | undefined;
+  lineno?: number | undefined;
+  colno?: number | undefined;
+  in_app?: boolean | undefined;
+}>;
+/**
+ * 异常本体。
+ * type/value 用于展示与指纹，stacktrace 用于源码定位。
+ */
+export declare const ExceptionSchema: z.ZodObject<{
+  /** 异常类型，例如 TypeError、ReferenceError。缺省时调用方应回退为 'Error'。 */
+  type: z.ZodString;
+  /** 异常消息原文。展示前会被归一化（数字、UUID、URL 等替换为占位符）。 */
+  value: z.ZodOptional<z.ZodString>;
+  /** 调用栈。没有时无法做源码还原，只能按消息聚合。 */
+  stacktrace: z.ZodOptional<z.ZodObject<{
+    /** 帧数组，顺序为「调用处在前、根因在后」，与 V8 的 stack 字符串顺序一致。 */
+    frames: z.ZodArray<z.ZodObject<{
+      /** 帧所属文件。H5 通常是完整 URL 或 /assets/xxx.js 路径。 */
+      filename: z.ZodString;
+      /** 绝对路径。浏览器给不出时与 filename 相同；用于匹配 sourcemap 时更可靠。 */
+      abs_path: z.ZodOptional<z.ZodString>;
+      /** 函数名。压缩后可能只是一个字母，还原后才是真实函数名。 */
+      function: z.ZodOptional<z.ZodString>;
+      /** 行号（从 1 开始）。压缩代码里通常都是 1。 */
+      lineno: z.ZodOptional<z.ZodNumber>;
+      /** 列号（从 0 开始）。sourcemap 还原靠它定位到具体字符。 */
+      colno: z.ZodOptional<z.ZodNumber>;
+      /**
+       * 该帧是否属于业务代码。
+       * 依赖与框架内部（node_modules、框架运行时）为 false，参与指纹计算时只取 true 的帧。
+       */
+      in_app: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+      filename: string;
+      in_app: boolean;
+      function?: string | undefined;
+      abs_path?: string | undefined;
+      lineno?: number | undefined;
+      colno?: number | undefined;
+    }, {
+      filename: string;
+      function?: string | undefined;
+      abs_path?: string | undefined;
+      lineno?: number | undefined;
+      colno?: number | undefined;
+      in_app?: boolean | undefined;
+    }>, "many">;
+  }, "strip", z.ZodTypeAny, {
+    frames: {
+      filename: string;
+      in_app: boolean;
+      function?: string | undefined;
+      abs_path?: string | undefined;
+      lineno?: number | undefined;
+      colno?: number | undefined;
+    }[];
+  }, {
+    frames: {
+      filename: string;
+      function?: string | undefined;
+      abs_path?: string | undefined;
+      lineno?: number | undefined;
+      colno?: number | undefined;
+      in_app?: boolean | undefined;
+    }[];
+  }>>;
+}, "strip", z.ZodTypeAny, {
+  type: string;
+  value?: string | undefined;
+  stacktrace?: {
+    frames: {
+      filename: string;
+      in_app: boolean;
+      function?: string | undefined;
+      abs_path?: string | undefined;
+      lineno?: number | undefined;
+      colno?: number | undefined;
+    }[];
+  } | undefined;
+}, {
+  type: string;
+  value?: string | undefined;
+  stacktrace?: {
+    frames: {
+      filename: string;
+      function?: string | undefined;
+      abs_path?: string | undefined;
+      lineno?: number | undefined;
+      colno?: number | undefined;
+      in_app?: boolean | undefined;
+    }[];
+  } | undefined;
+}>;
+/**
+ * 面包屑：错误发生前的关键动作。
+ * 用来回答「用户点了什么、发了什么请求、跳了哪个页面」，是定位白屏类问题的核心线索。
+ */
+export declare const BreadcrumbSchema: z.ZodObject<{
+  /** 类别，例如 http / navigation / ui / console。决定后台时间线如何渲染。 */
+  type: z.ZodString;
+  /** 更细的分类，例如 fetch / xhr / route / click。可选。 */
+  category: z.ZodOptional<z.ZodString>;
+  /** 该面包屑自身的级别，用于在时间线上高亮异常项。 */
+  level: z.ZodOptional<z.ZodEnum<["fatal", "error", "warning", "info"]>>;
+  /** 事件发生时间，Unix 毫秒时间戳。面包屑按它升序展示。 */
+  timestamp: z.ZodNumber;
+  /**
+   * 页面会话 id。
+   *
+   * 同一次页面进入（包括 SPA 路由切换）产生的面包屑共享一个 id，
+   * 后台可以据此把「进入页面 → 发请求 → 点击 → 报错」串成一条时间线。
+   */
+  session_id: z.ZodOptional<z.ZodString>;
+  /** 页面会话内的单调递增序号。时间戳相同毫秒时仍能保持稳定顺序。 */
+  seq: z.ZodOptional<z.ZodNumber>;
+  /** 相对页面进入时刻的毫秒数。后台展示为 +1.2s 更容易判断现场。 */
+  t_rel_ms: z.ZodOptional<z.ZodNumber>;
+  /** 简短描述，例如「提交订单」。后台直接展示这一行。 */
+  message: z.ZodOptional<z.ZodString>;
+  /** 结构化细节，例如 { method, url, status_code, duration_ms }。 */
+  data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+  type: string;
+  timestamp: number;
+  message?: string | undefined;
+  category?: string | undefined;
+  level?: "fatal" | "error" | "warning" | "info" | undefined;
+  session_id?: string | undefined;
+  seq?: number | undefined;
+  t_rel_ms?: number | undefined;
+  data?: Record<string, unknown> | undefined;
+}, {
+  type: string;
+  timestamp: number;
+  message?: string | undefined;
+  category?: string | undefined;
+  level?: "fatal" | "error" | "warning" | "info" | undefined;
+  session_id?: string | undefined;
+  seq?: number | undefined;
+  t_rel_ms?: number | undefined;
+  data?: Record<string, unknown> | undefined;
+}>;
+/**
+ * 用户标识。
+ * 只允许放 id 与匿名 id，手机号、姓名等 PII 一律不允许上报。
+ */
+export declare const UserContextSchema: z.ZodObject<{
+  /** 业务系统里的用户 id。登录后由 setUser 注入。 */
+  id: z.ZodOptional<z.ZodString>;
+  /** SDK 首次启动生成的持久匿名 id，用于未登录用户的影响面统计。 */
+  anonymous_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  id?: string | undefined;
+  anonymous_id?: string | undefined;
+}, {
+  id?: string | undefined;
+  anonymous_id?: string | undefined;
+}>;
+/**
+ * 运行环境上下文，按类别分组：device / os / browser / network / app。
+ * 每个类别的字段由平台适配层自行决定，服务端只做透传与展示。
+ */
+export declare const ContextsSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+/**
+ * 自定义标签。键值都必须是标量，便于后台做聚合与筛选。
+ * 与 contexts 的区别：tags 用于索引与分组，contexts 用于展示完整现场。
+ */
+export declare const TagsSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+/**
+ * 错误事件。
+ * SDK 捕获未处理异常或手动 captureException 时产生。
+ */
+export declare const ErrorItemSchema: z.ZodObject<{
+  /**
+   * 客户端生成的事件 uuid，是服务端的幂等键。
+   * 同一条事件重试多次时，服务端靠它去重，不会重复计数。
+   */
+  event_id: z.ZodString;
+  /**
+   * 客户端节流窗口内的累计次数。
+   *
+   * 例如同一签名错误在 5 秒内触发 100 次，SDK 只发一个包，
+   * occurrences 就是 100。issue 的 event_count 按它累加，
+   * 否则「报错 100 次」会被记成 1 次。
+   */
+  occurrences: z.ZodDefault<z.ZodNumber>;
+  /** 事件发生时间，ISO8601 UTC 字符串。服务端会把它钳制到允许窗口内。 */
+  timestamp: z.ZodString;
+  /** 运行时平台。见 constants.ts 中 PLATFORMS 的说明。 */
+  platform: z.ZodEnum<["web", "mp-weixin", "mp-alipay", "app"]>;
+  /** 运行环境。issue 按环境隔离聚合。 */
+  environment: z.ZodEnum<["production", "staging", "development"]>;
+  /** 版本号，必须与上传 sourcemap 时的 release 完全一致，否则无法还原。 */
+  release: z.ZodOptional<z.ZodString>;
+  /** 分发标识，用于同一版本多包场景（例如 h5 / mp-weixin / app）。 */
+  dist: z.ZodOptional<z.ZodString>;
+  /** 错误发生前的面包屑，最多 50 条，按时间升序。 */
+  breadcrumbs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    /** 类别，例如 http / navigation / ui / console。决定后台时间线如何渲染。 */
+    type: z.ZodString;
+    /** 更细的分类，例如 fetch / xhr / route / click。可选。 */
+    category: z.ZodOptional<z.ZodString>;
+    /** 该面包屑自身的级别，用于在时间线上高亮异常项。 */
+    level: z.ZodOptional<z.ZodEnum<["fatal", "error", "warning", "info"]>>;
+    /** 事件发生时间，Unix 毫秒时间戳。面包屑按它升序展示。 */
+    timestamp: z.ZodNumber;
+    /**
+     * 页面会话 id。
+     *
+     * 同一次页面进入（包括 SPA 路由切换）产生的面包屑共享一个 id，
+     * 后台可以据此把「进入页面 → 发请求 → 点击 → 报错」串成一条时间线。
+     */
+    session_id: z.ZodOptional<z.ZodString>;
+    /** 页面会话内的单调递增序号。时间戳相同毫秒时仍能保持稳定顺序。 */
+    seq: z.ZodOptional<z.ZodNumber>;
+    /** 相对页面进入时刻的毫秒数。后台展示为 +1.2s 更容易判断现场。 */
+    t_rel_ms: z.ZodOptional<z.ZodNumber>;
+    /** 简短描述，例如「提交订单」。后台直接展示这一行。 */
+    message: z.ZodOptional<z.ZodString>;
+    /** 结构化细节，例如 { method, url, status_code, duration_ms }。 */
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, "strip", z.ZodTypeAny, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }>, "many">>;
+  /** 设备、系统、浏览器、网络等上下文。 */
+  contexts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+  /** 自定义标签。 */
+  tags: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+  /** 用户标识。不传时服务端按匿名 id 统计影响用户。 */
+  user: z.ZodOptional<z.ZodObject<{
+    /** 业务系统里的用户 id。登录后由 setUser 注入。 */
+    id: z.ZodOptional<z.ZodString>;
+    /** SDK 首次启动生成的持久匿名 id，用于未登录用户的影响面统计。 */
+    anonymous_id: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }>>;
+  /** 出错页面的完整 URL。 */
+  url: z.ZodOptional<z.ZodString>;
+  /** 出错页面的路由路径，例如 /order/detail。用于按页面聚合。 */
+  route: z.ZodOptional<z.ZodString>;
+  /** 事件类型判别字段。 */
+  type: z.ZodLiteral<"error">;
+  /** 代码错误固定为 code。 */
+  category: z.ZodLiteral<"code">;
+  /** 严重级别。 */
+  level: z.ZodEnum<["fatal", "error", "warning", "info"]>;
+  /** 冗余的异常消息，便于不解析 exception 时直接展示。 */
+  message: z.ZodOptional<z.ZodString>;
+  /** 异常本体，包含类型、消息与堆栈。 */
+  exception: z.ZodObject<{
+    /** 异常类型，例如 TypeError、ReferenceError。缺省时调用方应回退为 'Error'。 */
+    type: z.ZodString;
+    /** 异常消息原文。展示前会被归一化（数字、UUID、URL 等替换为占位符）。 */
+    value: z.ZodOptional<z.ZodString>;
+    /** 调用栈。没有时无法做源码还原，只能按消息聚合。 */
+    stacktrace: z.ZodOptional<z.ZodObject<{
+      /** 帧数组，顺序为「调用处在前、根因在后」，与 V8 的 stack 字符串顺序一致。 */
+      frames: z.ZodArray<z.ZodObject<{
+        /** 帧所属文件。H5 通常是完整 URL 或 /assets/xxx.js 路径。 */
+        filename: z.ZodString;
+        /** 绝对路径。浏览器给不出时与 filename 相同；用于匹配 sourcemap 时更可靠。 */
+        abs_path: z.ZodOptional<z.ZodString>;
+        /** 函数名。压缩后可能只是一个字母，还原后才是真实函数名。 */
+        function: z.ZodOptional<z.ZodString>;
+        /** 行号（从 1 开始）。压缩代码里通常都是 1。 */
+        lineno: z.ZodOptional<z.ZodNumber>;
+        /** 列号（从 0 开始）。sourcemap 还原靠它定位到具体字符。 */
+        colno: z.ZodOptional<z.ZodNumber>;
+        /**
+         * 该帧是否属于业务代码。
+         * 依赖与框架内部（node_modules、框架运行时）为 false，参与指纹计算时只取 true 的帧。
+         */
+        in_app: z.ZodDefault<z.ZodBoolean>;
+      }, "strip", z.ZodTypeAny, {
+        filename: string;
+        in_app: boolean;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+      }, {
+        filename: string;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+        in_app?: boolean | undefined;
+      }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+      frames: {
+        filename: string;
+        in_app: boolean;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+      }[];
+    }, {
+      frames: {
+        filename: string;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+        in_app?: boolean | undefined;
+      }[];
+    }>>;
+  }, "strip", z.ZodTypeAny, {
+    type: string;
+    value?: string | undefined;
+    stacktrace?: {
+      frames: {
+        filename: string;
+        in_app: boolean;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+      }[];
+    } | undefined;
+  }, {
+    type: string;
+    value?: string | undefined;
+    stacktrace?: {
+      frames: {
+        filename: string;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+        in_app?: boolean | undefined;
+      }[];
+    } | undefined;
+  }>;
+}, "strip", z.ZodTypeAny, {
+  type: "error";
+  category: "code";
+  level: "fatal" | "error" | "warning" | "info";
+  timestamp: string;
+  exception: {
+    type: string;
+    value?: string | undefined;
+    stacktrace?: {
+      frames: {
+        filename: string;
+        in_app: boolean;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+      }[];
+    } | undefined;
+  };
+  event_id: string;
+  occurrences: number;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  breadcrumbs: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[];
+  contexts: Record<string, Record<string, unknown>>;
+  tags: Record<string, string | number | boolean>;
+  message?: string | undefined;
+  release?: string | undefined;
+  dist?: string | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+}, {
+  type: "error";
+  category: "code";
+  level: "fatal" | "error" | "warning" | "info";
+  timestamp: string;
+  exception: {
+    type: string;
+    value?: string | undefined;
+    stacktrace?: {
+      frames: {
+        filename: string;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+        in_app?: boolean | undefined;
+      }[];
+    } | undefined;
+  };
+  event_id: string;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  message?: string | undefined;
+  occurrences?: number | undefined;
+  release?: string | undefined;
+  dist?: string | undefined;
+  breadcrumbs?: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[] | undefined;
+  contexts?: Record<string, Record<string, unknown>> | undefined;
+  tags?: Record<string, string | number | boolean> | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+}>;
+/**
+ * 消息事件。
+ * 用于 captureMessage 上报「不是异常但需要记录」的信息。
+ */
+export declare const MessageItemSchema: z.ZodObject<{
+  /**
+   * 客户端生成的事件 uuid，是服务端的幂等键。
+   * 同一条事件重试多次时，服务端靠它去重，不会重复计数。
+   */
+  event_id: z.ZodString;
+  /**
+   * 客户端节流窗口内的累计次数。
+   *
+   * 例如同一签名错误在 5 秒内触发 100 次，SDK 只发一个包，
+   * occurrences 就是 100。issue 的 event_count 按它累加，
+   * 否则「报错 100 次」会被记成 1 次。
+   */
+  occurrences: z.ZodDefault<z.ZodNumber>;
+  /** 事件发生时间，ISO8601 UTC 字符串。服务端会把它钳制到允许窗口内。 */
+  timestamp: z.ZodString;
+  /** 运行时平台。见 constants.ts 中 PLATFORMS 的说明。 */
+  platform: z.ZodEnum<["web", "mp-weixin", "mp-alipay", "app"]>;
+  /** 运行环境。issue 按环境隔离聚合。 */
+  environment: z.ZodEnum<["production", "staging", "development"]>;
+  /** 版本号，必须与上传 sourcemap 时的 release 完全一致，否则无法还原。 */
+  release: z.ZodOptional<z.ZodString>;
+  /** 分发标识，用于同一版本多包场景（例如 h5 / mp-weixin / app）。 */
+  dist: z.ZodOptional<z.ZodString>;
+  /** 错误发生前的面包屑，最多 50 条，按时间升序。 */
+  breadcrumbs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    /** 类别，例如 http / navigation / ui / console。决定后台时间线如何渲染。 */
+    type: z.ZodString;
+    /** 更细的分类，例如 fetch / xhr / route / click。可选。 */
+    category: z.ZodOptional<z.ZodString>;
+    /** 该面包屑自身的级别，用于在时间线上高亮异常项。 */
+    level: z.ZodOptional<z.ZodEnum<["fatal", "error", "warning", "info"]>>;
+    /** 事件发生时间，Unix 毫秒时间戳。面包屑按它升序展示。 */
+    timestamp: z.ZodNumber;
+    /**
+     * 页面会话 id。
+     *
+     * 同一次页面进入（包括 SPA 路由切换）产生的面包屑共享一个 id，
+     * 后台可以据此把「进入页面 → 发请求 → 点击 → 报错」串成一条时间线。
+     */
+    session_id: z.ZodOptional<z.ZodString>;
+    /** 页面会话内的单调递增序号。时间戳相同毫秒时仍能保持稳定顺序。 */
+    seq: z.ZodOptional<z.ZodNumber>;
+    /** 相对页面进入时刻的毫秒数。后台展示为 +1.2s 更容易判断现场。 */
+    t_rel_ms: z.ZodOptional<z.ZodNumber>;
+    /** 简短描述，例如「提交订单」。后台直接展示这一行。 */
+    message: z.ZodOptional<z.ZodString>;
+    /** 结构化细节，例如 { method, url, status_code, duration_ms }。 */
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, "strip", z.ZodTypeAny, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }>, "many">>;
+  /** 设备、系统、浏览器、网络等上下文。 */
+  contexts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+  /** 自定义标签。 */
+  tags: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+  /** 用户标识。不传时服务端按匿名 id 统计影响用户。 */
+  user: z.ZodOptional<z.ZodObject<{
+    /** 业务系统里的用户 id。登录后由 setUser 注入。 */
+    id: z.ZodOptional<z.ZodString>;
+    /** SDK 首次启动生成的持久匿名 id，用于未登录用户的影响面统计。 */
+    anonymous_id: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }>>;
+  /** 出错页面的完整 URL。 */
+  url: z.ZodOptional<z.ZodString>;
+  /** 出错页面的路由路径，例如 /order/detail。用于按页面聚合。 */
+  route: z.ZodOptional<z.ZodString>;
+  /** 事件类型判别字段。 */
+  type: z.ZodLiteral<"message">;
+  /** 接口错误固定为 interface。 */
+  category: z.ZodLiteral<"interface">;
+  /** 接口错误来源，必须显式上报。 */
+  source: z.ZodEnum<["http", "resource", "message"]>;
+  /** 严重级别。 */
+  level: z.ZodEnum<["fatal", "error", "warning", "info"]>;
+  /** 消息正文，必填。 */
+  message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  message: string;
+  type: "message";
+  category: "interface";
+  level: "fatal" | "error" | "warning" | "info";
+  timestamp: string;
+  event_id: string;
+  occurrences: number;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  breadcrumbs: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[];
+  contexts: Record<string, Record<string, unknown>>;
+  tags: Record<string, string | number | boolean>;
+  source: "http" | "resource" | "message";
+  release?: string | undefined;
+  dist?: string | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+}, {
+  message: string;
+  type: "message";
+  category: "interface";
+  level: "fatal" | "error" | "warning" | "info";
+  timestamp: string;
+  event_id: string;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  source: "http" | "resource" | "message";
+  occurrences?: number | undefined;
+  release?: string | undefined;
+  dist?: string | undefined;
+  breadcrumbs?: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[] | undefined;
+  contexts?: Record<string, Record<string, unknown>> | undefined;
+  tags?: Record<string, string | number | boolean> | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+}>;
+/**
+ * 业务埋点事件。
+ *
+ * 与错误事件走同一个信封、同一个 ingest 接口，但服务端写入独立的 track_events 表，
+ * 不参与指纹聚合，也不占用 issue 的计数。
+ */
+export declare const TrackItemSchema: z.ZodObject<{
+  /**
+   * 客户端生成的事件 uuid，是服务端的幂等键。
+   * 同一条事件重试多次时，服务端靠它去重，不会重复计数。
+   */
+  event_id: z.ZodString;
+  /**
+   * 客户端节流窗口内的累计次数。
+   *
+   * 例如同一签名错误在 5 秒内触发 100 次，SDK 只发一个包，
+   * occurrences 就是 100。issue 的 event_count 按它累加，
+   * 否则「报错 100 次」会被记成 1 次。
+   */
+  occurrences: z.ZodDefault<z.ZodNumber>;
+  /** 事件发生时间，ISO8601 UTC 字符串。服务端会把它钳制到允许窗口内。 */
+  timestamp: z.ZodString;
+  /** 运行时平台。见 constants.ts 中 PLATFORMS 的说明。 */
+  platform: z.ZodEnum<["web", "mp-weixin", "mp-alipay", "app"]>;
+  /** 运行环境。issue 按环境隔离聚合。 */
+  environment: z.ZodEnum<["production", "staging", "development"]>;
+  /** 版本号，必须与上传 sourcemap 时的 release 完全一致，否则无法还原。 */
+  release: z.ZodOptional<z.ZodString>;
+  /** 分发标识，用于同一版本多包场景（例如 h5 / mp-weixin / app）。 */
+  dist: z.ZodOptional<z.ZodString>;
+  /** 错误发生前的面包屑，最多 50 条，按时间升序。 */
+  breadcrumbs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    /** 类别，例如 http / navigation / ui / console。决定后台时间线如何渲染。 */
+    type: z.ZodString;
+    /** 更细的分类，例如 fetch / xhr / route / click。可选。 */
+    category: z.ZodOptional<z.ZodString>;
+    /** 该面包屑自身的级别，用于在时间线上高亮异常项。 */
+    level: z.ZodOptional<z.ZodEnum<["fatal", "error", "warning", "info"]>>;
+    /** 事件发生时间，Unix 毫秒时间戳。面包屑按它升序展示。 */
+    timestamp: z.ZodNumber;
+    /**
+     * 页面会话 id。
+     *
+     * 同一次页面进入（包括 SPA 路由切换）产生的面包屑共享一个 id，
+     * 后台可以据此把「进入页面 → 发请求 → 点击 → 报错」串成一条时间线。
+     */
+    session_id: z.ZodOptional<z.ZodString>;
+    /** 页面会话内的单调递增序号。时间戳相同毫秒时仍能保持稳定顺序。 */
+    seq: z.ZodOptional<z.ZodNumber>;
+    /** 相对页面进入时刻的毫秒数。后台展示为 +1.2s 更容易判断现场。 */
+    t_rel_ms: z.ZodOptional<z.ZodNumber>;
+    /** 简短描述，例如「提交订单」。后台直接展示这一行。 */
+    message: z.ZodOptional<z.ZodString>;
+    /** 结构化细节，例如 { method, url, status_code, duration_ms }。 */
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, "strip", z.ZodTypeAny, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }>, "many">>;
+  /** 设备、系统、浏览器、网络等上下文。 */
+  contexts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+  /** 自定义标签。 */
+  tags: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+  /** 用户标识。不传时服务端按匿名 id 统计影响用户。 */
+  user: z.ZodOptional<z.ZodObject<{
+    /** 业务系统里的用户 id。登录后由 setUser 注入。 */
+    id: z.ZodOptional<z.ZodString>;
+    /** SDK 首次启动生成的持久匿名 id，用于未登录用户的影响面统计。 */
+    anonymous_id: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }>>;
+  /** 出错页面的完整 URL。 */
+  url: z.ZodOptional<z.ZodString>;
+  /** 出错页面的路由路径，例如 /order/detail。用于按页面聚合。 */
+  route: z.ZodOptional<z.ZodString>;
+  /** 事件类型判别字段。 */
+  type: z.ZodLiteral<"track">;
+  /** 埋点事件名，例如 pay_click。是后台查询的主要筛选条件。 */
+  event_name: z.ZodString;
+  /** 事件属性，任意 JSON 对象。例如 { amount: 99, sku: 'A-1024' }。 */
+  properties: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+  type: "track";
+  timestamp: string;
+  event_id: string;
+  occurrences: number;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  breadcrumbs: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[];
+  contexts: Record<string, Record<string, unknown>>;
+  tags: Record<string, string | number | boolean>;
+  event_name: string;
+  properties: Record<string, unknown>;
+  release?: string | undefined;
+  dist?: string | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+}, {
+  type: "track";
+  timestamp: string;
+  event_id: string;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  event_name: string;
+  occurrences?: number | undefined;
+  release?: string | undefined;
+  dist?: string | undefined;
+  breadcrumbs?: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[] | undefined;
+  contexts?: Record<string, Record<string, unknown>> | undefined;
+  tags?: Record<string, string | number | boolean> | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+  properties?: Record<string, unknown> | undefined;
+}>;
+/**
+ * 单条事件。按 type 判别为 error / message / track。
+ */
+export declare const EventItemSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+  /**
+   * 客户端生成的事件 uuid，是服务端的幂等键。
+   * 同一条事件重试多次时，服务端靠它去重，不会重复计数。
+   */
+  event_id: z.ZodString;
+  /**
+   * 客户端节流窗口内的累计次数。
+   *
+   * 例如同一签名错误在 5 秒内触发 100 次，SDK 只发一个包，
+   * occurrences 就是 100。issue 的 event_count 按它累加，
+   * 否则「报错 100 次」会被记成 1 次。
+   */
+  occurrences: z.ZodDefault<z.ZodNumber>;
+  /** 事件发生时间，ISO8601 UTC 字符串。服务端会把它钳制到允许窗口内。 */
+  timestamp: z.ZodString;
+  /** 运行时平台。见 constants.ts 中 PLATFORMS 的说明。 */
+  platform: z.ZodEnum<["web", "mp-weixin", "mp-alipay", "app"]>;
+  /** 运行环境。issue 按环境隔离聚合。 */
+  environment: z.ZodEnum<["production", "staging", "development"]>;
+  /** 版本号，必须与上传 sourcemap 时的 release 完全一致，否则无法还原。 */
+  release: z.ZodOptional<z.ZodString>;
+  /** 分发标识，用于同一版本多包场景（例如 h5 / mp-weixin / app）。 */
+  dist: z.ZodOptional<z.ZodString>;
+  /** 错误发生前的面包屑，最多 50 条，按时间升序。 */
+  breadcrumbs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    /** 类别，例如 http / navigation / ui / console。决定后台时间线如何渲染。 */
+    type: z.ZodString;
+    /** 更细的分类，例如 fetch / xhr / route / click。可选。 */
+    category: z.ZodOptional<z.ZodString>;
+    /** 该面包屑自身的级别，用于在时间线上高亮异常项。 */
+    level: z.ZodOptional<z.ZodEnum<["fatal", "error", "warning", "info"]>>;
+    /** 事件发生时间，Unix 毫秒时间戳。面包屑按它升序展示。 */
+    timestamp: z.ZodNumber;
+    /**
+     * 页面会话 id。
+     *
+     * 同一次页面进入（包括 SPA 路由切换）产生的面包屑共享一个 id，
+     * 后台可以据此把「进入页面 → 发请求 → 点击 → 报错」串成一条时间线。
+     */
+    session_id: z.ZodOptional<z.ZodString>;
+    /** 页面会话内的单调递增序号。时间戳相同毫秒时仍能保持稳定顺序。 */
+    seq: z.ZodOptional<z.ZodNumber>;
+    /** 相对页面进入时刻的毫秒数。后台展示为 +1.2s 更容易判断现场。 */
+    t_rel_ms: z.ZodOptional<z.ZodNumber>;
+    /** 简短描述，例如「提交订单」。后台直接展示这一行。 */
+    message: z.ZodOptional<z.ZodString>;
+    /** 结构化细节，例如 { method, url, status_code, duration_ms }。 */
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, "strip", z.ZodTypeAny, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }>, "many">>;
+  /** 设备、系统、浏览器、网络等上下文。 */
+  contexts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+  /** 自定义标签。 */
+  tags: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+  /** 用户标识。不传时服务端按匿名 id 统计影响用户。 */
+  user: z.ZodOptional<z.ZodObject<{
+    /** 业务系统里的用户 id。登录后由 setUser 注入。 */
+    id: z.ZodOptional<z.ZodString>;
+    /** SDK 首次启动生成的持久匿名 id，用于未登录用户的影响面统计。 */
+    anonymous_id: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }>>;
+  /** 出错页面的完整 URL。 */
+  url: z.ZodOptional<z.ZodString>;
+  /** 出错页面的路由路径，例如 /order/detail。用于按页面聚合。 */
+  route: z.ZodOptional<z.ZodString>;
+  /** 事件类型判别字段。 */
+  type: z.ZodLiteral<"error">;
+  /** 代码错误固定为 code。 */
+  category: z.ZodLiteral<"code">;
+  /** 严重级别。 */
+  level: z.ZodEnum<["fatal", "error", "warning", "info"]>;
+  /** 冗余的异常消息，便于不解析 exception 时直接展示。 */
+  message: z.ZodOptional<z.ZodString>;
+  /** 异常本体，包含类型、消息与堆栈。 */
+  exception: z.ZodObject<{
+    /** 异常类型，例如 TypeError、ReferenceError。缺省时调用方应回退为 'Error'。 */
+    type: z.ZodString;
+    /** 异常消息原文。展示前会被归一化（数字、UUID、URL 等替换为占位符）。 */
+    value: z.ZodOptional<z.ZodString>;
+    /** 调用栈。没有时无法做源码还原，只能按消息聚合。 */
+    stacktrace: z.ZodOptional<z.ZodObject<{
+      /** 帧数组，顺序为「调用处在前、根因在后」，与 V8 的 stack 字符串顺序一致。 */
+      frames: z.ZodArray<z.ZodObject<{
+        /** 帧所属文件。H5 通常是完整 URL 或 /assets/xxx.js 路径。 */
+        filename: z.ZodString;
+        /** 绝对路径。浏览器给不出时与 filename 相同；用于匹配 sourcemap 时更可靠。 */
+        abs_path: z.ZodOptional<z.ZodString>;
+        /** 函数名。压缩后可能只是一个字母，还原后才是真实函数名。 */
+        function: z.ZodOptional<z.ZodString>;
+        /** 行号（从 1 开始）。压缩代码里通常都是 1。 */
+        lineno: z.ZodOptional<z.ZodNumber>;
+        /** 列号（从 0 开始）。sourcemap 还原靠它定位到具体字符。 */
+        colno: z.ZodOptional<z.ZodNumber>;
+        /**
+         * 该帧是否属于业务代码。
+         * 依赖与框架内部（node_modules、框架运行时）为 false，参与指纹计算时只取 true 的帧。
+         */
+        in_app: z.ZodDefault<z.ZodBoolean>;
+      }, "strip", z.ZodTypeAny, {
+        filename: string;
+        in_app: boolean;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+      }, {
+        filename: string;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+        in_app?: boolean | undefined;
+      }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+      frames: {
+        filename: string;
+        in_app: boolean;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+      }[];
+    }, {
+      frames: {
+        filename: string;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+        in_app?: boolean | undefined;
+      }[];
+    }>>;
+  }, "strip", z.ZodTypeAny, {
+    type: string;
+    value?: string | undefined;
+    stacktrace?: {
+      frames: {
+        filename: string;
+        in_app: boolean;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+      }[];
+    } | undefined;
+  }, {
+    type: string;
+    value?: string | undefined;
+    stacktrace?: {
+      frames: {
+        filename: string;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+        in_app?: boolean | undefined;
+      }[];
+    } | undefined;
+  }>;
+}, "strip", z.ZodTypeAny, {
+  type: "error";
+  category: "code";
+  level: "fatal" | "error" | "warning" | "info";
+  timestamp: string;
+  exception: {
+    type: string;
+    value?: string | undefined;
+    stacktrace?: {
+      frames: {
+        filename: string;
+        in_app: boolean;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+      }[];
+    } | undefined;
+  };
+  event_id: string;
+  occurrences: number;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  breadcrumbs: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[];
+  contexts: Record<string, Record<string, unknown>>;
+  tags: Record<string, string | number | boolean>;
+  message?: string | undefined;
+  release?: string | undefined;
+  dist?: string | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+}, {
+  type: "error";
+  category: "code";
+  level: "fatal" | "error" | "warning" | "info";
+  timestamp: string;
+  exception: {
+    type: string;
+    value?: string | undefined;
+    stacktrace?: {
+      frames: {
+        filename: string;
+        function?: string | undefined;
+        abs_path?: string | undefined;
+        lineno?: number | undefined;
+        colno?: number | undefined;
+        in_app?: boolean | undefined;
+      }[];
+    } | undefined;
+  };
+  event_id: string;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  message?: string | undefined;
+  occurrences?: number | undefined;
+  release?: string | undefined;
+  dist?: string | undefined;
+  breadcrumbs?: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[] | undefined;
+  contexts?: Record<string, Record<string, unknown>> | undefined;
+  tags?: Record<string, string | number | boolean> | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+}>, z.ZodObject<{
+  /**
+   * 客户端生成的事件 uuid，是服务端的幂等键。
+   * 同一条事件重试多次时，服务端靠它去重，不会重复计数。
+   */
+  event_id: z.ZodString;
+  /**
+   * 客户端节流窗口内的累计次数。
+   *
+   * 例如同一签名错误在 5 秒内触发 100 次，SDK 只发一个包，
+   * occurrences 就是 100。issue 的 event_count 按它累加，
+   * 否则「报错 100 次」会被记成 1 次。
+   */
+  occurrences: z.ZodDefault<z.ZodNumber>;
+  /** 事件发生时间，ISO8601 UTC 字符串。服务端会把它钳制到允许窗口内。 */
+  timestamp: z.ZodString;
+  /** 运行时平台。见 constants.ts 中 PLATFORMS 的说明。 */
+  platform: z.ZodEnum<["web", "mp-weixin", "mp-alipay", "app"]>;
+  /** 运行环境。issue 按环境隔离聚合。 */
+  environment: z.ZodEnum<["production", "staging", "development"]>;
+  /** 版本号，必须与上传 sourcemap 时的 release 完全一致，否则无法还原。 */
+  release: z.ZodOptional<z.ZodString>;
+  /** 分发标识，用于同一版本多包场景（例如 h5 / mp-weixin / app）。 */
+  dist: z.ZodOptional<z.ZodString>;
+  /** 错误发生前的面包屑，最多 50 条，按时间升序。 */
+  breadcrumbs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    /** 类别，例如 http / navigation / ui / console。决定后台时间线如何渲染。 */
+    type: z.ZodString;
+    /** 更细的分类，例如 fetch / xhr / route / click。可选。 */
+    category: z.ZodOptional<z.ZodString>;
+    /** 该面包屑自身的级别，用于在时间线上高亮异常项。 */
+    level: z.ZodOptional<z.ZodEnum<["fatal", "error", "warning", "info"]>>;
+    /** 事件发生时间，Unix 毫秒时间戳。面包屑按它升序展示。 */
+    timestamp: z.ZodNumber;
+    /**
+     * 页面会话 id。
+     *
+     * 同一次页面进入（包括 SPA 路由切换）产生的面包屑共享一个 id，
+     * 后台可以据此把「进入页面 → 发请求 → 点击 → 报错」串成一条时间线。
+     */
+    session_id: z.ZodOptional<z.ZodString>;
+    /** 页面会话内的单调递增序号。时间戳相同毫秒时仍能保持稳定顺序。 */
+    seq: z.ZodOptional<z.ZodNumber>;
+    /** 相对页面进入时刻的毫秒数。后台展示为 +1.2s 更容易判断现场。 */
+    t_rel_ms: z.ZodOptional<z.ZodNumber>;
+    /** 简短描述，例如「提交订单」。后台直接展示这一行。 */
+    message: z.ZodOptional<z.ZodString>;
+    /** 结构化细节，例如 { method, url, status_code, duration_ms }。 */
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, "strip", z.ZodTypeAny, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }>, "many">>;
+  /** 设备、系统、浏览器、网络等上下文。 */
+  contexts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+  /** 自定义标签。 */
+  tags: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+  /** 用户标识。不传时服务端按匿名 id 统计影响用户。 */
+  user: z.ZodOptional<z.ZodObject<{
+    /** 业务系统里的用户 id。登录后由 setUser 注入。 */
+    id: z.ZodOptional<z.ZodString>;
+    /** SDK 首次启动生成的持久匿名 id，用于未登录用户的影响面统计。 */
+    anonymous_id: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }>>;
+  /** 出错页面的完整 URL。 */
+  url: z.ZodOptional<z.ZodString>;
+  /** 出错页面的路由路径，例如 /order/detail。用于按页面聚合。 */
+  route: z.ZodOptional<z.ZodString>;
+  /** 事件类型判别字段。 */
+  type: z.ZodLiteral<"message">;
+  /** 接口错误固定为 interface。 */
+  category: z.ZodLiteral<"interface">;
+  /** 接口错误来源，必须显式上报。 */
+  source: z.ZodEnum<["http", "resource", "message"]>;
+  /** 严重级别。 */
+  level: z.ZodEnum<["fatal", "error", "warning", "info"]>;
+  /** 消息正文，必填。 */
+  message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  message: string;
+  type: "message";
+  category: "interface";
+  level: "fatal" | "error" | "warning" | "info";
+  timestamp: string;
+  event_id: string;
+  occurrences: number;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  breadcrumbs: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[];
+  contexts: Record<string, Record<string, unknown>>;
+  tags: Record<string, string | number | boolean>;
+  source: "http" | "resource" | "message";
+  release?: string | undefined;
+  dist?: string | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+}, {
+  message: string;
+  type: "message";
+  category: "interface";
+  level: "fatal" | "error" | "warning" | "info";
+  timestamp: string;
+  event_id: string;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  source: "http" | "resource" | "message";
+  occurrences?: number | undefined;
+  release?: string | undefined;
+  dist?: string | undefined;
+  breadcrumbs?: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[] | undefined;
+  contexts?: Record<string, Record<string, unknown>> | undefined;
+  tags?: Record<string, string | number | boolean> | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+}>, z.ZodObject<{
+  /**
+   * 客户端生成的事件 uuid，是服务端的幂等键。
+   * 同一条事件重试多次时，服务端靠它去重，不会重复计数。
+   */
+  event_id: z.ZodString;
+  /**
+   * 客户端节流窗口内的累计次数。
+   *
+   * 例如同一签名错误在 5 秒内触发 100 次，SDK 只发一个包，
+   * occurrences 就是 100。issue 的 event_count 按它累加，
+   * 否则「报错 100 次」会被记成 1 次。
+   */
+  occurrences: z.ZodDefault<z.ZodNumber>;
+  /** 事件发生时间，ISO8601 UTC 字符串。服务端会把它钳制到允许窗口内。 */
+  timestamp: z.ZodString;
+  /** 运行时平台。见 constants.ts 中 PLATFORMS 的说明。 */
+  platform: z.ZodEnum<["web", "mp-weixin", "mp-alipay", "app"]>;
+  /** 运行环境。issue 按环境隔离聚合。 */
+  environment: z.ZodEnum<["production", "staging", "development"]>;
+  /** 版本号，必须与上传 sourcemap 时的 release 完全一致，否则无法还原。 */
+  release: z.ZodOptional<z.ZodString>;
+  /** 分发标识，用于同一版本多包场景（例如 h5 / mp-weixin / app）。 */
+  dist: z.ZodOptional<z.ZodString>;
+  /** 错误发生前的面包屑，最多 50 条，按时间升序。 */
+  breadcrumbs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    /** 类别，例如 http / navigation / ui / console。决定后台时间线如何渲染。 */
+    type: z.ZodString;
+    /** 更细的分类，例如 fetch / xhr / route / click。可选。 */
+    category: z.ZodOptional<z.ZodString>;
+    /** 该面包屑自身的级别，用于在时间线上高亮异常项。 */
+    level: z.ZodOptional<z.ZodEnum<["fatal", "error", "warning", "info"]>>;
+    /** 事件发生时间，Unix 毫秒时间戳。面包屑按它升序展示。 */
+    timestamp: z.ZodNumber;
+    /**
+     * 页面会话 id。
+     *
+     * 同一次页面进入（包括 SPA 路由切换）产生的面包屑共享一个 id，
+     * 后台可以据此把「进入页面 → 发请求 → 点击 → 报错」串成一条时间线。
+     */
+    session_id: z.ZodOptional<z.ZodString>;
+    /** 页面会话内的单调递增序号。时间戳相同毫秒时仍能保持稳定顺序。 */
+    seq: z.ZodOptional<z.ZodNumber>;
+    /** 相对页面进入时刻的毫秒数。后台展示为 +1.2s 更容易判断现场。 */
+    t_rel_ms: z.ZodOptional<z.ZodNumber>;
+    /** 简短描述，例如「提交订单」。后台直接展示这一行。 */
+    message: z.ZodOptional<z.ZodString>;
+    /** 结构化细节，例如 { method, url, status_code, duration_ms }。 */
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, "strip", z.ZodTypeAny, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }, {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }>, "many">>;
+  /** 设备、系统、浏览器、网络等上下文。 */
+  contexts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+  /** 自定义标签。 */
+  tags: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+  /** 用户标识。不传时服务端按匿名 id 统计影响用户。 */
+  user: z.ZodOptional<z.ZodObject<{
+    /** 业务系统里的用户 id。登录后由 setUser 注入。 */
+    id: z.ZodOptional<z.ZodString>;
+    /** SDK 首次启动生成的持久匿名 id，用于未登录用户的影响面统计。 */
+    anonymous_id: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }, {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  }>>;
+  /** 出错页面的完整 URL。 */
+  url: z.ZodOptional<z.ZodString>;
+  /** 出错页面的路由路径，例如 /order/detail。用于按页面聚合。 */
+  route: z.ZodOptional<z.ZodString>;
+  /** 事件类型判别字段。 */
+  type: z.ZodLiteral<"track">;
+  /** 埋点事件名，例如 pay_click。是后台查询的主要筛选条件。 */
+  event_name: z.ZodString;
+  /** 事件属性，任意 JSON 对象。例如 { amount: 99, sku: 'A-1024' }。 */
+  properties: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+  type: "track";
+  timestamp: string;
+  event_id: string;
+  occurrences: number;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  breadcrumbs: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[];
+  contexts: Record<string, Record<string, unknown>>;
+  tags: Record<string, string | number | boolean>;
+  event_name: string;
+  properties: Record<string, unknown>;
+  release?: string | undefined;
+  dist?: string | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+}, {
+  type: "track";
+  timestamp: string;
+  event_id: string;
+  platform: "web" | "mp-weixin" | "mp-alipay" | "app";
+  environment: "production" | "staging" | "development";
+  event_name: string;
+  occurrences?: number | undefined;
+  release?: string | undefined;
+  dist?: string | undefined;
+  breadcrumbs?: {
+    type: string;
+    timestamp: number;
+    message?: string | undefined;
+    category?: string | undefined;
+    level?: "fatal" | "error" | "warning" | "info" | undefined;
+    session_id?: string | undefined;
+    seq?: number | undefined;
+    t_rel_ms?: number | undefined;
+    data?: Record<string, unknown> | undefined;
+  }[] | undefined;
+  contexts?: Record<string, Record<string, unknown>> | undefined;
+  tags?: Record<string, string | number | boolean> | undefined;
+  user?: {
+    id?: string | undefined;
+    anonymous_id?: string | undefined;
+  } | undefined;
+  url?: string | undefined;
+  route?: string | undefined;
+  properties?: Record<string, unknown> | undefined;
+}>]>;
+/**
+ * 信封级字段。
+ *
+ * 这里刻意把 items 定义为 unknown[]：单个 item 非法时只丢弃它并计数，
+ * 不能因为一条脏数据把整包有效数据一起拒绝。
+ */
+export declare const EnvelopeSchema: z.ZodObject<{
+  /** 上报方 SDK 的名称与版本，用于排查协议兼容问题。 */
+  sdk: z.ZodObject<{
+    /** 包名，例如 @fz-firefly/web。 */
+    name: z.ZodString;
+    /** SDK 版本号，例如 0.2.0。 */
+    version: z.ZodString;
+  }, "strip", z.ZodTypeAny, {
+    name: string;
+    version: string;
+  }, {
+    name: string;
+    version: string;
+  }>;
+  /** 客户端发送时间，ISO8601 UTC。服务端用它判断离线补报的延迟。 */
+  sent_at: z.ZodString;
+  /** 事件数组，至少 1 条、最多 50 条。 */
+  items: z.ZodArray<z.ZodUnknown, "many">;
+}, "strip", z.ZodTypeAny, {
+  sdk: {
+    name: string;
+    version: string;
+  };
+  sent_at: string;
+  items: unknown[];
+}, {
+  sdk: {
+    name: string;
+    version: string;
+  };
+  sent_at: string;
+  items: unknown[];
+}>;
+/** parseEnvelope 的返回值。成功时带解析后的事件与丢弃数量，失败时带可读原因。 */
+export type ParseEnvelopeResult = {
+  ok: true;
+  value: {
+    /** 透传的信封元信息。 */
+    sdk: {
+      name: string;
+      version: string;
+    };
+    /** 透传的发送时间。 */
+    sent_at: string;
+    /** 逐条解析成功的事件。 */
+    items: EventItem[];
+    /** 因字段非法被丢弃的 item 数量。 */
+    dropped: number;
+  };
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * 解析一个上报信封。
+ *
+ * 规则：
+ * - 信封级字段（sdk / sent_at / items 数量）非法 → 整体失败；
+ * - 单个 item 非法 → 只丢这一条，`dropped` 计数，其余照常返回。
+ *
+ * 这样一条脏数据不会拖垮整包，同时调用方能从 `dropped` 看出客户端协议是否需要升级。
+ */
+export declare function parseEnvelope(raw: unknown): ParseEnvelopeResult;
+/** 包名，用于日志与协议兼容性排查。 */
+export declare const PACKAGE_NAME = "@fz-firefly/shared";
+//# sourceMappingURL=index.d.cts.map