@xysfe/bug-tap 0.0.0-stage → 0.1.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 (76) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/LICENSE +21 -0
  3. package/README.md +461 -2
  4. package/THIRD_PARTY_NOTICES.md +39 -0
  5. package/dist/bug-tap-screenshot.min.js +10 -0
  6. package/dist/bug-tap-screenshot.min.js.map +1 -0
  7. package/dist/bug-tap-vue.cjs +2 -0
  8. package/dist/bug-tap-vue.cjs.map +1 -0
  9. package/dist/bug-tap-vue.js +106 -0
  10. package/dist/bug-tap-vue.js.map +1 -0
  11. package/dist/bug-tap-vue.min.js +2 -0
  12. package/dist/bug-tap-vue.min.js.map +1 -0
  13. package/dist/bug-tap.cjs +2 -0
  14. package/dist/bug-tap.cjs.map +1 -0
  15. package/dist/bug-tap.js +13 -0
  16. package/dist/bug-tap.js.map +1 -0
  17. package/dist/bug-tap.min.js +508 -0
  18. package/dist/bug-tap.min.js.map +1 -0
  19. package/dist/config.d.ts +14 -0
  20. package/dist/core/body.d.ts +30 -0
  21. package/dist/core/breadcrumbs.d.ts +85 -0
  22. package/dist/core/browser-api-errors.d.ts +55 -0
  23. package/dist/core/byte-buffer.d.ts +43 -0
  24. package/dist/core/collector.d.ts +34 -0
  25. package/dist/core/console-collector.d.ts +23 -0
  26. package/dist/core/env-collector.d.ts +16 -0
  27. package/dist/core/error-collector.d.ts +48 -0
  28. package/dist/core/error-noise.d.ts +43 -0
  29. package/dist/core/network-collector.d.ts +97 -0
  30. package/dist/core/network-record.d.ts +19 -0
  31. package/dist/core/resource-timing.d.ts +28 -0
  32. package/dist/core/ring-buffer.d.ts +22 -0
  33. package/dist/core/selector.d.ts +3 -0
  34. package/dist/core/serialize.d.ts +5 -0
  35. package/dist/core/tongji.d.ts +14 -0
  36. package/dist/core/user.d.ts +9 -0
  37. package/dist/index-BBRuTNvo.js +4685 -0
  38. package/dist/index-BBRuTNvo.js.map +1 -0
  39. package/dist/index-DCLLRJxX.cjs +488 -0
  40. package/dist/index-DCLLRJxX.cjs.map +1 -0
  41. package/dist/index.d.ts +33 -0
  42. package/dist/integrations.d.ts +26 -0
  43. package/dist/panel-mount-Dia21VuZ.cjs +2 -0
  44. package/dist/panel-mount-Dia21VuZ.cjs.map +1 -0
  45. package/dist/panel-mount-mAOg572s.js +499 -0
  46. package/dist/panel-mount-mAOg572s.js.map +1 -0
  47. package/dist/screenshot-global.d.ts +14 -0
  48. package/dist/sdk.d.ts +76 -0
  49. package/dist/transport/log-item.d.ts +2 -0
  50. package/dist/transport/offline-queue.d.ts +48 -0
  51. package/dist/transport/payload.d.ts +15 -0
  52. package/dist/transport/transport.d.ts +57 -0
  53. package/dist/transport/upload.d.ts +8 -0
  54. package/dist/types.d.ts +459 -0
  55. package/dist/ui/element-picker.d.ts +51 -0
  56. package/dist/ui/floating-button.d.ts +43 -0
  57. package/dist/ui/icons.d.ts +1 -0
  58. package/dist/ui/panel-mount.d.ts +20 -0
  59. package/dist/ui/panel.vue.d.ts +15 -0
  60. package/dist/ui/screenshot-loader-shared.d.ts +2 -0
  61. package/dist/ui/screenshot-loader.d.ts +14 -0
  62. package/dist/ui/screenshot-loader.iife.d.ts +16 -0
  63. package/dist/ui/screenshot.d.ts +20 -0
  64. package/dist/ui/shadow-host.d.ts +16 -0
  65. package/dist/ui/styles.css.d.ts +1 -0
  66. package/dist/ui/visibility.d.ts +25 -0
  67. package/dist/utils/match.d.ts +2 -0
  68. package/dist/utils/ua.d.ts +6 -0
  69. package/dist/utils/url.d.ts +2 -0
  70. package/dist/vue-global.d.ts +21 -0
  71. package/dist/vue.d.ts +49 -0
  72. package/docs/api.md +257 -0
  73. package/docs/backend-api.md +401 -0
  74. package/docs/bundler.md +122 -0
  75. package/docs/config.md +396 -0
  76. package/package.json +97 -4
@@ -0,0 +1,14 @@
1
+ import type { BugTapConfig, ResolvedBugTapConfig, UserInfoInput } from './types';
2
+ export declare const DEFAULT_EXCLUDE_URLS: Array<string | RegExp>;
3
+ export declare const DEFAULT_ENDPOINT = "/go/SupportTools/logreport";
4
+ export declare const DEFAULT_UPLOAD_URL = "/platform/file/uploadPicture";
5
+ export declare const DEFAULT_UPLOAD_BIZ_ID = "1008";
6
+ /**
7
+ * 用户信息只接受单层标量字段:
8
+ * - 嵌套对象 / 数组会被丢弃,避免把整个 store 塞进上报
9
+ * - 传函数时原样透传,由提交阶段求值(见 core/user.ts 的 resolveUser)
10
+ */
11
+ export declare function normalizeUser(input: unknown): UserInfoInput | undefined;
12
+ export declare function mergeConfig(base: BugTapConfig, patch: Partial<BugTapConfig> | undefined): BugTapConfig;
13
+ export declare function normalizeConfig(input: BugTapConfig): ResolvedBugTapConfig;
14
+ export declare function validateConfig(config: BugTapConfig): string[];
@@ -0,0 +1,30 @@
1
+ export declare const SKIP_BODY_TYPE: RegExp;
2
+ export declare const BINARY_TYPE: RegExp;
3
+ /**
4
+ * 按 UTF-8 字节数截断,不会切断代理对。
5
+ * 超限时追加截断标记,便于上报侧识别这是部分内容。
6
+ *
7
+ * 单趟扫描:只统计到「第一个超限字符」为止,不对整个字符串预先算一遍总长。
8
+ * 响应体可能上百 KB,而多数情况是超限,先算全长的开销纯属浪费。
9
+ */
10
+ export declare function truncateUtf8(text: string, maxBytes: number): string;
11
+ export declare function utf8Bytes(text: string): number;
12
+ /**
13
+ * 把 fetch 的 body 转成可上报的字符串。
14
+ * 不支持的类型只记录类型名,FormData 里的文件只记录大小和名字。
15
+ * 注意:这里不做截断,截断交给 ByteBudgetBuffer 按整条记录处理。
16
+ */
17
+ export declare function describeRequestBody(body: unknown): string | undefined;
18
+ /** 对象序列化后的 UTF-8 字节数;序列化失败按超限处理 */
19
+ export declare function jsonByteSize(value: unknown, fallback?: number): number;
20
+ export declare function shouldReadBody(contentType: string | null, contentLength: number, maxCloneBytes: number): boolean;
21
+ /**
22
+ * 有上限地读取一个 ReadableStream 的文本内容。
23
+ * content-length 缺失(chunked / HTTP/2)时不能直接 text(),否则超大 body 会整个读进内存;
24
+ * 这里流式读取,超过 maxBytes 立刻取消并返回已读部分。
25
+ */
26
+ export declare function readStreamText(stream: ReadableStream<Uint8Array>, maxBytes: number): Promise<string>;
27
+ /** 读取 clone 出来的响应文本,最多读 maxBytes。 */
28
+ export declare function readResponseText(response: Response, maxBytes: number): Promise<string>;
29
+ /** XHR 的 response body 只在 text 与 json 两种 responseType 下可读 */
30
+ export declare function readXhrBody(xhr: XMLHttpRequest, maxCloneBytes: number): string | undefined;
@@ -0,0 +1,85 @@
1
+ import type { Breadcrumb } from '../types';
2
+ /**
3
+ * 极简选择器:面包屑只用于人读和 AI 推断,不需要 css-selector-generator 的精确度,
4
+ * 每次点击都跑完整生成器在长列表页会有明显开销。
5
+ */
6
+ export declare function quickSelector(element: Element | null): string | undefined;
7
+ export interface BreadcrumbOptions {
8
+ max: number;
9
+ dom: boolean;
10
+ navigation: boolean;
11
+ network: boolean;
12
+ error: boolean;
13
+ excludeUrls?: Array<string | RegExp>;
14
+ beforeBreadcrumb?: (breadcrumb: Breadcrumb) => Breadcrumb | null;
15
+ }
16
+ /**
17
+ * 记录最近的操作轨迹。
18
+ * 与 Sentry / Rollbar / Bugsnag 一致,点击、路由、网络、异常进入同一条时间线,
19
+ * 按时间排序后可直接还原因果链:点按钮 → 请求 500 → 抛异常。
20
+ */
21
+ export declare class BreadcrumbCollector {
22
+ private readonly options;
23
+ private readonly buffer;
24
+ private started;
25
+ private lastRoute;
26
+ private lastVisibility;
27
+ private navigationDisabled;
28
+ private tailSignature;
29
+ constructor(options: BreadcrumbOptions);
30
+ get limit(): number;
31
+ get size(): number;
32
+ get evicted(): number;
33
+ start(): void;
34
+ stop(): void;
35
+ getBreadcrumbs(): Breadcrumb[];
36
+ /** 业务主动写入一条轨迹(BugTap.addBreadcrumb) */
37
+ add(breadcrumb: Breadcrumb): void;
38
+ /**
39
+ * 交给框架路由接管导航记录(vue-router 集成)。
40
+ *
41
+ * 只摘补丁不够:框架通常在 SDK 之后才创建自己的 history,它会把
42
+ * **我们的包装器** 保存在闭包里,摘掉顶层包装后对方仍会调用到我们。
43
+ * 所以这里同时置一个开关,让 checkRoute / onHistory 直接短路。
44
+ */
45
+ disableNavigationCapture(): void;
46
+ clear(): void;
47
+ /**
48
+ * 网络请求留痕:与 Sentry 的 breadcrumbsIntegration 一致,记录**所有**请求,
49
+ * 完整数据在 network[],这里只放一行摘要并用 ref 关联。
50
+ *
51
+ * 风险是轮询请求会把 100 条容量吃光,导致「点按钮 → 报错」的因果链被挤出时间线。
52
+ * 因此连续的相同请求(method + url + status 相同)折叠成一条并累加 repeat,
53
+ * 轮询变成 `GET /api/heartbeat 200 ×120`,既保留完整视野又不挤占空间。
54
+ */
55
+ addNetwork(item: {
56
+ id: string;
57
+ method: string;
58
+ url: string;
59
+ status?: number;
60
+ ok?: boolean;
61
+ durationMs?: number;
62
+ error?: string;
63
+ }): void;
64
+ /** 异常留痕:与 errors[] 同源,时间线上按发生顺序排列 */
65
+ addError(item: {
66
+ message: string;
67
+ timestamp: number;
68
+ count?: number;
69
+ }): void;
70
+ private push;
71
+ private applyHook;
72
+ private onClick;
73
+ private onChange;
74
+ private onVisibility;
75
+ private checkRoute;
76
+ private onHistory;
77
+ private originalPush;
78
+ private originalReplace;
79
+ private wrappedPush;
80
+ private wrappedReplace;
81
+ private routeHook;
82
+ private wrapHistory;
83
+ private patchHistory;
84
+ private unpatchHistory;
85
+ }
@@ -0,0 +1,55 @@
1
+ /**
2
+ * 对齐 Sentry 的 BrowserApiErrors:
3
+ * 1. 包 setTimeout / setInterval / requestAnimationFrame 的回调
4
+ * 2. 包 EventTarget 原型上的 addEventListener / removeEventListener
5
+ *
6
+ * 为什么要包:这类回调抛错时 window.onerror 只能拿到堆栈,分不清是
7
+ * 定时器、事件监听器还是同步代码里的错误;有了来源标注,排查时不必再猜。
8
+ *
9
+ * removeEventListener 必须同步处理(Sentry 的做法):
10
+ * 我们注册的是包装后的函数,业务拿原函数去移除是移不掉的,
11
+ * 监听器会一直挂在目标上,变成内存泄漏。所以 removeEventListener 里
12
+ * 要先按 `__bugTapWrapped` 找回原函数再移除一次。
13
+ */
14
+ /** 这个抛出的值是否已经被 BrowserApiErrors 记过 */
15
+ export declare function wasCapturedByBrowserApi(value: unknown): boolean;
16
+ /**
17
+ * 消费一次「跳过下一个 onerror」的额度。
18
+ * 用 setTimeout 复位,与 Sentry 一致:onerror 一定在下一个宏任务之前触发,
19
+ * 若这次错误被业务自己 catch 掉了,计数也会在下一个宏任务自动作废,不会误伤后续真实错误。
20
+ */
21
+ export declare function consumeIgnoreOnError(): boolean;
22
+ export interface BrowserApiErrorOptions {
23
+ /** 记录一条带来源标注的异常;调用方负责 message/stack 的归一化 */
24
+ capture(error: unknown, source: string): void;
25
+ /**
26
+ * 是否包装 EventTarget.prototype.addEventListener。
27
+ * 关闭后只保留 setTimeout / setInterval / requestAnimationFrame 的来源标注,
28
+ * 大型页面可以借此避免给全页监听器套一层 try/catch。
29
+ */
30
+ eventListeners?: boolean;
31
+ }
32
+ export declare class BrowserApiErrors {
33
+ private readonly options;
34
+ private readonly patched;
35
+ /**
36
+ * 已包装的监听器登记表:target → 事件 + capture → (原函数 → 包装后函数)。
37
+ *
38
+ * 两个用途,缺一不可:
39
+ * 1. 同一个原函数重复 addEventListener 时必须复用同一个包装器,
40
+ * 否则浏览器会当成两个不同的 listener,回调被触发两次
41
+ * 2. 业务用原函数 removeEventListener 时才能找回包装器一并摘掉,
42
+ * 否则监听器永远挂着,变成内存泄漏
43
+ */
44
+ private readonly registry;
45
+ private started;
46
+ constructor(options: BrowserApiErrorOptions);
47
+ start(): void;
48
+ stop(): void;
49
+ private patchTimer;
50
+ private patchEventTarget;
51
+ /** 同一个 (target, event, capture, 原函数) 始终复用同一个包装器 */
52
+ private listenerFor;
53
+ /** 统一包装:失败时记一条带来源的异常,然后原样抛出 */
54
+ private wrapCallback;
55
+ }
@@ -0,0 +1,43 @@
1
+ /**
2
+ * 按总字节预算保留记录,而不是按条截断。
3
+ * 满了就丢掉最旧的整条记录,保证留下来的每条数据都是完整的。
4
+ */
5
+ export declare class ByteBudgetBuffer<T> {
6
+ private readonly maxItems;
7
+ private readonly maxBytes;
8
+ private readonly sizeOf;
9
+ private items;
10
+ private sizes;
11
+ private head;
12
+ private total;
13
+ private droppedItems;
14
+ private droppedBytes;
15
+ private evictedItems;
16
+ private evictedBytes;
17
+ constructor(maxItems: number, maxBytes: number, sizeOf: (item: T) => number);
18
+ get size(): number;
19
+ get bytes(): number;
20
+ get dropped(): {
21
+ count: number;
22
+ bytes: number;
23
+ };
24
+ get evicted(): {
25
+ count: number;
26
+ bytes: number;
27
+ };
28
+ /**
29
+ * 返回实际写入的条数变化:
30
+ * - 'ok' 正常写入
31
+ * - 'evicted' 为腾空间丢了旧记录
32
+ * - 'dropped' 单条就超过总预算,没写入
33
+ */
34
+ push(item: T): 'ok' | 'evicted' | 'dropped';
35
+ toArray(): T[];
36
+ /**
37
+ * 原地更新一条已写入的记录(例如流式响应稍后拿到 body)。
38
+ * 更新后若超出总预算则保持原样,宁可丢 body 也不丢整条元数据。
39
+ */
40
+ update(match: (item: T) => boolean, next: (item: T) => T): 'ok' | 'dropped' | 'missed';
41
+ clear(): void;
42
+ private shift;
43
+ }
@@ -0,0 +1,34 @@
1
+ import type { Breadcrumb, CollectorHealth, ConsoleLog, JavaScriptError, NetworkDropped, NetworkRecord, ResolvedBugTapConfig } from '../types';
2
+ export interface CollectedData {
3
+ logs: ConsoleLog[];
4
+ errors: JavaScriptError[];
5
+ network: NetworkRecord[];
6
+ networkDropped?: Omit<NetworkDropped, 'totalCount' | 'sentCount'>;
7
+ collector: CollectorHealth;
8
+ breadcrumbs?: Breadcrumb[];
9
+ }
10
+ export declare class Collector {
11
+ private readonly config;
12
+ private consoleCollector;
13
+ private errorCollector;
14
+ private networkCollector;
15
+ private breadcrumbCollector;
16
+ private browserApiErrors;
17
+ private startedAt;
18
+ constructor(config: ResolvedBugTapConfig);
19
+ start(): void;
20
+ stop(): void;
21
+ getData(): CollectedData;
22
+ clear(): void;
23
+ /** 业务主动上报异常,进入下一次反馈的 errors[] */
24
+ captureException(error: unknown, context?: Record<string, unknown>): void;
25
+ /** 业务主动上报消息,进入下一次反馈的 errors[] */
26
+ captureMessage(message: string, context?: Record<string, unknown>): void;
27
+ /** 业务主动写入一条时间线 */
28
+ addBreadcrumb(breadcrumb: Breadcrumb): void;
29
+ /**
30
+ * 交给框架路由接管导航记录,避免与主包的 history 补丁重复。
31
+ * 由 vue-router 插件调用。
32
+ */
33
+ disableRouteCapture(): void;
34
+ }
@@ -0,0 +1,23 @@
1
+ import type { ConsoleLog } from '../types';
2
+ export interface ConsoleCollectorOptions {
3
+ max: number;
4
+ excludePatterns: Array<string | RegExp>;
5
+ }
6
+ export declare class ConsoleCollector {
7
+ private readonly options;
8
+ private readonly buffer;
9
+ private readonly originals;
10
+ private readonly wrapped;
11
+ private originalClear;
12
+ private wrappedClear;
13
+ private started;
14
+ private capturing;
15
+ private dispatching;
16
+ constructor(options: ConsoleCollectorOptions);
17
+ start(): void;
18
+ stop(): void;
19
+ getLogs(): ConsoleLog[];
20
+ getPatchState(): boolean;
21
+ clear(): void;
22
+ private capture;
23
+ }
@@ -0,0 +1,16 @@
1
+ import type { BrowserInfo, PageInfo, ResolvedBugTapConfig } from '../types';
2
+ export declare function collectPageInfo(): PageInfo;
3
+ /** 缩放 / 系统 DPI 会让 devicePixelRatio 变成 1.100000023841858 这类噪声值 */
4
+ export declare function normalizeDpr(value: number): number;
5
+ /**
6
+ * 与 xys-monitor 的 `exadata.device` 对齐:`宽*高 @ Nx`。
7
+ * screen.width 在部分 WebView / 隐私模式下会是 0,按 xys-monitor 的规则回退到 availWidth。
8
+ * dpr 必须归一化:device 是日志平台按机型聚合的键,
9
+ * 浮点噪声会让同一台设备产生多个不同字符串,直接破坏分组。
10
+ */
11
+ export declare function formatDevice(screenWidth: number, screenHeight: number, dpr: number): string;
12
+ export declare function collectBrowserInfo(config: ResolvedBugTapConfig): BrowserInfo;
13
+ export declare function collectEnvironment(config: ResolvedBugTapConfig): {
14
+ page: PageInfo;
15
+ browser: BrowserInfo;
16
+ };
@@ -0,0 +1,48 @@
1
+ import type { JavaScriptError } from '../types';
2
+ export interface ErrorCollectorOptions {
3
+ max: number;
4
+ ignoreErrors?: Array<string | RegExp>;
5
+ allowUrls?: Array<string | RegExp>;
6
+ denyUrls?: Array<string | RegExp>;
7
+ resourceErrors?: boolean;
8
+ }
9
+ export declare class ErrorCollector {
10
+ private readonly options;
11
+ private readonly buffer;
12
+ private readonly signatures;
13
+ private started;
14
+ private previousStackTraceLimit;
15
+ private listener;
16
+ setListener(fn: ((record: JavaScriptError) => void) | null): void;
17
+ private readonly onError;
18
+ /**
19
+ * 资源加载错误的 target 是具体元素,不带 stack。
20
+ * 只保留标签与地址,足够定位「哪张图 / 哪个脚本没加载出来」。
21
+ */
22
+ private pushResourceError;
23
+ private readonly onRejection;
24
+ constructor(options: ErrorCollectorOptions);
25
+ /**
26
+ * 由 BrowserApiErrors 调用:定时器 / 事件监听回调里的异常。
27
+ * 来源写进 message,排查时不用再猜「这是哪类异步错误」。
28
+ */
29
+ captureFromBrowserApi(error: unknown, source: string): void;
30
+ /**
31
+ * 业务主动上报异常。只进本地缓冲,随下一次用户反馈一起提交,
32
+ * 不会单独发请求,避免业务在循环里调用时打爆网关。
33
+ */
34
+ captureException(error: unknown, context?: Record<string, unknown>): void;
35
+ /** 业务主动上报一条消息,语义同 captureException,但不要求是 Error 实例 */
36
+ captureMessage(message: string, context?: Record<string, unknown>): void;
37
+ /** 把任意抛出值归一成一条异常记录 */
38
+ private fromUnknown;
39
+ start(): void;
40
+ stop(): void;
41
+ getErrors(): JavaScriptError[];
42
+ getPatchState(): boolean;
43
+ clear(): void;
44
+ private push;
45
+ private pruneSignatures;
46
+ private shouldDrop;
47
+ private sanitize;
48
+ }
@@ -0,0 +1,43 @@
1
+ /**
2
+ * 已知的低价值 / 不可行动错误。
3
+ * 与 Sentry 的 `DEFAULT_IGNORE_ERRORS`(packages/core/src/integrations/eventFilters.ts)保持一致;
4
+ * Sentry 每条都附了来源链接,判定依据是「这类错误对业务方不可行动」。
5
+ */
6
+ export declare const DEFAULT_IGNORE_ERRORS: Array<string | RegExp>;
7
+ /**
8
+ * 从异常栈里解析出第一个有效业务帧。
9
+ * 栈顶在前;跳过 `[native code]` / `data:` / 扩展等无定位价值的地址。
10
+ * 这是唯一的帧扫描实现,`frameUrlOf` 与结构化位置都基于它。
11
+ */
12
+ export declare function firstFrameOf(stack: string | undefined): {
13
+ url: string;
14
+ line?: number;
15
+ column?: number;
16
+ } | undefined;
17
+ /**
18
+ * 取异常栈里「抛出点」的脚本地址,用于 denyUrls / allowUrls。
19
+ *
20
+ * 与 Sentry 的 `_getEventFilterUrl` 语义一致:按栈帧的脚本地址过滤,
21
+ * 而不是页面地址——同一个页面里第三方 SDK 抛的错可以据此精确命中。
22
+ */
23
+ export declare function frameUrlOf(stack: string | undefined, filename?: string): string | undefined;
24
+ /**
25
+ * 消息的所有等价写法。
26
+ *
27
+ * 记录里的 message 沿用 window.onerror 的写法(`Error: boom`),
28
+ * 而 Sentry 的默认规则是针对原始 `error.message`(不带 `Error: ` 前缀)书写的,
29
+ * 其中不少是锚定的 `^…$`。所以过滤时要把前缀剥掉再比一遍,否则默认表会失效。
30
+ */
31
+ export declare function messageVariants(message: string): string[];
32
+ /** 消息命中任一条即视为应收敛的噪音 */
33
+ export declare function isIgnoredMessage(message: string, patterns: Array<string | RegExp>): boolean;
34
+ /**
35
+ * 与 Sentry 的 `_isUselessError` 一致:既没有消息、也没有栈、也没有非通用错误类型的记录,
36
+ * 排查时无从下手,直接不采。
37
+ */
38
+ export declare function isUselessError(record: {
39
+ message?: string;
40
+ stack?: string;
41
+ }): boolean;
42
+ /** allowUrls 非空时必须命中,denyUrls 命中即丢;都是按脚本地址比 */
43
+ export declare function urlAllowed(url: string | undefined, allowUrls: Array<string | RegExp>, denyUrls: Array<string | RegExp>): boolean;
@@ -0,0 +1,97 @@
1
+ import type { NetworkRecord } from '../types';
2
+ export interface NetworkCollectorOptions {
3
+ max: number;
4
+ excludeUrls: Array<string | RegExp>;
5
+ selfUrls: string[];
6
+ captureBody: boolean;
7
+ realtime?: boolean;
8
+ requestHeaders?: string[] | true;
9
+ responseHeaders?: string[] | true;
10
+ maxBytes: number;
11
+ maxCloneBytes: number;
12
+ }
13
+ export declare class NetworkCollector {
14
+ private readonly options;
15
+ private readonly buffer;
16
+ private readonly timing;
17
+ private readonly pendingXhr;
18
+ private originalFetch;
19
+ private wrappedFetch;
20
+ private originalOpen;
21
+ private wrappedOpen;
22
+ private originalSend;
23
+ private wrappedSend;
24
+ private originalSetRequestHeader;
25
+ private wrappedSetRequestHeader;
26
+ private originalWebSocket;
27
+ private wrappedWebSocket;
28
+ private originalEventSource;
29
+ private wrappedEventSource;
30
+ private started;
31
+ private seq;
32
+ private listener;
33
+ setListener(fn: ((record: NetworkRecord) => void) | null): void;
34
+ constructor(options: NetworkCollectorOptions);
35
+ private readonly selfUrls;
36
+ private readonly matchers;
37
+ private readonly requestHeaderAllow;
38
+ private readonly responseHeaderAllow;
39
+ private skipped;
40
+ private sizeOf;
41
+ start(): void;
42
+ stop(): void;
43
+ getRecords(): NetworkRecord[];
44
+ getPatchState(): {
45
+ fetch: boolean;
46
+ xhr: boolean;
47
+ websocket: boolean;
48
+ eventsource: boolean;
49
+ };
50
+ getDropped(): {
51
+ droppedCount: number;
52
+ droppedBytes: number;
53
+ evictedCount: number;
54
+ evictedBytes: number;
55
+ };
56
+ clear(): void;
57
+ private patchFetch;
58
+ private patchXhr;
59
+ /**
60
+ * 长连接(WebSocket / EventSource)没有 fetch/XHR 那样的请求-响应模型,
61
+ * 但「连接建不上 / 一直断开 / 服务端踢人」同样需要证据。
62
+ *
63
+ * 用「返回原生实例的包装构造函数」而不是改原型:
64
+ * - 业务拿到的仍是原生实例,instanceof、addEventListener、消息回调都不受影响
65
+ * - 静态常量(WebSocket.OPEN 等)通过 setPrototypeOf 继承
66
+ */
67
+ private patchRealtime;
68
+ /**
69
+ * WebSocket 与 EventSource 的包装逐字相同,只差「怎么 new」和记录类型,
70
+ * 收在这里共用;`create` 由调用方给出,保住各自的原生构造签名。
71
+ */
72
+ private wrapRealtime;
73
+ private patchWebSocket;
74
+ private patchEventSource;
75
+ private observeRealtime;
76
+ private bodyOf;
77
+ private requestHeadersOf;
78
+ private xhrResponseHeaders;
79
+ private textOf;
80
+ private observeResponse;
81
+ /**
82
+ * 传 Request 对象时用 clone 异步读 body。
83
+ * 这里必须沿用 maxCloneBytes 限读:clone().text() 会把整个 body 读成字符串,
84
+ * 大请求体(大 Blob / 流式上传)会直接撑爆内存。
85
+ * 读到上限就 cancel 掉这一支,另一支不受影响;失败则留空,不影响业务。
86
+ */
87
+ private requestBodyOf;
88
+ /**
89
+ * 流式响应先写入元数据,等 body 读到(或超限)后再原地补上。
90
+ * 长轮询这类永不结束的流不会阻塞记录提交;补写超预算时只丢 body 不丢记录。
91
+ */
92
+ private recordStreaming;
93
+ private record;
94
+ private recordWithBody;
95
+ private pushRecord;
96
+ private nextId;
97
+ }
@@ -0,0 +1,19 @@
1
+ import type { NetworkDropped, NetworkRecord } from '../types';
2
+ type NetworkOutcome = Pick<NetworkRecord, 'ok' | 'status' | 'error'>;
3
+ /**
4
+ * 请求是否算失败:「失败优先」的所有逻辑(裁剪顺序、时间线标记、分片优先级)
5
+ * 都以这一个判断为准,不要在调用点各写一份 —— 三处曾各写一遍且规则已经漂移。
6
+ */
7
+ export declare function isFailedNetwork(record: NetworkOutcome): boolean;
8
+ /**
9
+ * 明确成功的请求:只有 ok === true 才算。
10
+ * 主动 abort 的记录 ok 为 undefined、没有 error 也没有 status(见 network-collector),
11
+ * 既不进失败分片、也不按成功处理,因此不能写成 !isFailedNetwork。
12
+ */
13
+ export declare function isSucceededNetwork(record: NetworkOutcome): boolean;
14
+ /**
15
+ * 未进入上报的网络记录总数:采集期丢弃 + 淘汰 + 提交期裁剪。
16
+ * 采集阶段(buildDropped)与上报阶段(log-item 的 content 摘要)必须同一口径。
17
+ */
18
+ export declare function networkLost(stats: Pick<NetworkDropped, 'droppedCount' | 'evictedCount' | 'trimmedCount'> | undefined): number;
19
+ export {};
@@ -0,0 +1,28 @@
1
+ import type { NetworkRecord, NetworkTiming } from '../types';
2
+ /**
3
+ * 把 PerformanceResourceTiming 换算成耗时分段。
4
+ *
5
+ * 各段不是简单加减关系:
6
+ * - dns / connect:名字解析、建立连接,复用连接时为 0
7
+ * - ttfb:请求发出到首字节,已包含排队与传输前的等待
8
+ * - download:首字节到响应结束
9
+ * - total:整个 request 的墙钟时长,最贴近用户体感
10
+ */
11
+ export declare function timingOf(entry: PerformanceResourceTiming): NetworkTiming;
12
+ /**
13
+ * 给网络记录补上耗时分解。
14
+ *
15
+ * 为什么不在采集时就算:fetch 的 resource timing 条目要到响应结束才出现,
16
+ * 而记录在响应头返回时就已经写入缓冲区。所以保留「记录 → 发起时刻」的对应关系,
17
+ * 等调用方真正读取记录(提交报告时)再回查,那时条目一定已经完整。
18
+ */
19
+ export declare class ResourceTimingIndex {
20
+ private readonly started;
21
+ private enabled;
22
+ /** @param startAt 请求发起时刻,需与 performance.now() 同一时间基准 */
23
+ remember(id: string, url: string, startAt: number): void;
24
+ /** 回查并返回带 timing 的新记录;查不到时原样返回 */
25
+ attach(record: NetworkRecord): NetworkRecord;
26
+ clear(): void;
27
+ private find;
28
+ }
@@ -0,0 +1,22 @@
1
+ export declare class RingBuffer<T> {
2
+ private readonly capacity;
3
+ private items;
4
+ private start;
5
+ private length;
6
+ private evicted;
7
+ constructor(capacity: number);
8
+ get size(): number;
9
+ get limit(): number;
10
+ get droppedCount(): number;
11
+ push(item: T): void;
12
+ last(): T | undefined;
13
+ toArray(): T[];
14
+ includes(item: T): boolean;
15
+ /**
16
+ * 原地更新第一条命中的记录,保持它在时间线上的位置。
17
+ * 用于把重复事件折叠成一条(如轮询请求),而不是让它挤掉用户操作。
18
+ */
19
+ update(match: (item: T) => boolean, updater: (item: T) => T): boolean;
20
+ updateLast(updater: (item: T) => T): boolean;
21
+ clear(): void;
22
+ }
@@ -0,0 +1,3 @@
1
+ import type { ElementSnapshot } from '../types';
2
+ export declare function generateSelector(element: Element): string;
3
+ export declare function describeElement(element: Element): ElementSnapshot;
@@ -0,0 +1,5 @@
1
+ export declare function safeSerialize(value: unknown, depth?: number, seen?: WeakSet<object>): string;
2
+ export declare function formatLogArgs(args: unknown[]): {
3
+ args: string[];
4
+ text: string;
5
+ };
@@ -0,0 +1,14 @@
1
+ import type { TrackIds } from '../types';
2
+ export type { TrackIds };
3
+ /** 复刻 tongji.getXid:按域名选 cookie 键 */
4
+ export declare function fallbackXid(): string;
5
+ /** 复刻 tongji.getSubId:只有牛保域名有子账号 */
6
+ export declare function fallbackSubId(): string | null;
7
+ /**
8
+ * 复刻 tongji.getSessionId:
9
+ * localStorage 与 cookie 双向同步,都没有才新生成 32 位随机串。
10
+ */
11
+ export declare function fallbackSessionId(): string;
12
+ export declare function collectTrackIds(): TrackIds | undefined;
13
+ /** 供测试或账号切换后手动失效缓存 */
14
+ export declare function resetTrackIdsCache(): void;
@@ -0,0 +1,9 @@
1
+ import type { UserInfo, UserInfoInput } from '../types';
2
+ /**
3
+ * 把配置里的 user 解析成最终要写进报告的对象。
4
+ * - 传函数时在此刻求值,保证拿到登录后的最新身份
5
+ * - 字段过滤复用 config 里的 normalizeUser,避免两套「什么算合法字段」的规则漂移
6
+ * - 值统一转字符串并截断到 200 字符,字段数上限 30
7
+ * - 求值抛错时返回 undefined,绝不影响上报
8
+ */
9
+ export declare function resolveUser(input: UserInfoInput | null | undefined): UserInfo | undefined;