@guomain/monitor-types 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @gm Monitor SDK
+
+前端错误监控：运行时错误、Promise、资源加载、接口异常、Vue/React、手动上报、catch 自动采集（需 Vite 插件）。
+
+## 安装
+
+```sh
+pnpm add @guomain/monitor-web
+pnpm add -D @guomain/monitor-plugins @guomain/monitor-types
+```
+
+## 快速开始
+
+```ts
+import { createWebMonitor } from '@guomain/monitor-web'
+
+const monitor = createWebMonitor({
+  appId: 'your-app',
+  dsn: '/api/monitor',
+  vue: { app }
+})
+
+globalThis.__GM_MONITOR__ = monitor
+monitor.start()
+```
+
+完整说明见仓库内 `SDK.md` 与 `PUBLISH.md`。

package/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 监控事件类型。
+ * 用于区分错误来源，方便后端按运行时、Promise、资源、请求、框架、SDK 自身等维度统计。
+ */
+export type MonitorEventType = 'runtime-error' | 'promise-error' | 'resource-error' | 'request-error' | 'vue-error' | 'react-error' | 'sdk-error' | 'caught-error' | 'manual-error';
+/**
+ * 业务上下文字段值。
+ * 只允许简单可序列化值，避免上报复杂对象或敏感运行时引用。
+ */
+export type MonitorContextValue = string | number | boolean | null;
+/**
+ * 业务上下文。
+ * 由宿主应用决定包含哪些字段，例如用户、租户、页面、业务场景等。
+ */
+export type MonitorContext = Record<string, MonitorContextValue>;
+/**
+ * 上下文提供方式。
+ * - 对象：初始化后固定不变的静态上下文。
+ * - 函数：每次上报前动态读取运行时上下文。
+ */
+export type MonitorContextProvider = MonitorContext | (() => MonitorContext | Promise<MonitorContext>);
+/**
+ * 事件附加信息。
+ * @property tags 用于筛选、聚合的低基数字段。
+ * @property extra 用于排查问题的补充数据。
+ */
+export interface MonitorEventMeta {
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+}
+/**
+ * SDK 内部统一事件结构。
+ * @property type 错误来源类型。
+ * @property message 错误摘要。
+ * @property timestamp 事件发生时间戳；未传时由 SDK 自动补齐。
+ * @property url 资源或请求地址。
+ * @property stack 错误堆栈。
+ * @property filename 运行时错误文件名。
+ * @property lineno 运行时错误行号。
+ * @property colno 运行时错误列号。
+ */
+export interface MonitorEvent extends MonitorEventMeta {
+    type: MonitorEventType;
+    message: string;
+    timestamp?: number;
+    url?: string;
+    stack?: string;
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+}
+/**
+ * 最终发送给 transport 的载荷。
+ * @property appId 应用标识。
+ * @property release 应用发布版本。
+ * @property context 上报时的业务上下文。
+ */
+export interface MonitorPayload extends MonitorEvent {
+    appId: string;
+    release?: string;
+    context?: MonitorContext;
+}
+/**
+ * 自定义发送函数。
+ * @param payloads SDK 归一化后的批量上报数据。
+ */
+export type MonitorTransport = (payloads: MonitorPayload[]) => void | Promise<void>;
+/**
+ * 采集阈值。
+ * @property maxQueueSize 最大待发送队列长度。
+ */
+export interface MonitorLimits {
+    maxQueueSize: number;
+}
+export type PartialMonitorLimits = Partial<MonitorLimits>;
+/**
+ * Vue 错误适配配置。
+ * @property app Vue 应用实例，SDK 会接入 app.config.errorHandler。
+ */
+export interface VueMonitorOptions {
+    app: {
+        config: {
+            errorHandler?: (err: unknown, instance: unknown, info: string) => void;
+        };
+    };
+}
+/**
+ * SDK 初始化配置。
+ * @property appId 应用标识，必填。
+ * @property dsn 默认上报地址；未提供 transport 时使用。
+ * @property release 发布版本，用于定位错误属于哪次构建。
+ * @property error 是否启用 Web 错误监控，默认开启。
+ * @property context 业务上下文，可静态传入，也可运行时动态计算。
+ * @property limits 队列、限流、重试阈值。
+ * @property transport 自定义发送函数，优先级高于 dsn。
+ * @property vue Vue 错误适配配置。
+ */
+export interface MonitorConfig {
+    appId: string;
+    dsn?: string;
+    release?: string;
+    error?: boolean;
+    context?: MonitorContextProvider;
+    limits?: PartialMonitorLimits;
+    transport?: MonitorTransport;
+    vue?: VueMonitorOptions;
+}
+/**
+ * SDK 插件协议。
+ * @property name 插件名称，用于 SDK 自身错误定位。
+ * @property setup 插件安装函数；返回函数时会在 stop 阶段执行清理。
+ */
+export interface MonitorPlugin {
+    name: string;
+    setup: (monitor: MonitorInstance) => void | (() => void);
+}
+/**
+ * React 渲染根节点的最小接口。
+ * @property render React root.render 方法。
+ */
+export interface ReactRenderRoot {
+    render: (node: unknown) => void;
+}
+export type ReactElementLike = unknown;
+/**
+ * SDK 实例 API。
+ * @property config 初始化配置。
+ * @property limits 合并默认值后的阈值配置。
+ * @property start 启动监听和插件。
+ * @property stop 停止监听并清理插件。
+ * @property use 注册插件。
+ * @property capture SDK 对外唯一上报入口，接收已归一化事件。
+ * @property flush 等待当前队列中的发送任务完成。
+ */
+export interface MonitorInstance {
+    readonly config: MonitorConfig;
+    readonly limits: MonitorLimits;
+    start: () => void;
+    stop: () => void;
+    use: (plugin: MonitorPlugin) => MonitorInstance;
+    capture: (event: MonitorEvent) => void;
+    flush: () => Promise<void>;
+    renderReact?: (root: ReactRenderRoot, element: ReactElementLike) => void;
+}
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/index.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+http://192.168.200.220/GomainFE/stamp.git",
+    "directory": "monitor/packages/monitor-types"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "name": "@guomain/monitor-types",
+  "description": "Type definitions for @gm monitor SDK",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "**/*"
+  ]
+}