rsclick-log-sdk-web 0.2.1 → 0.2.2

package/dist/browser.d.ts

@@ -1,4 +1,5 @@
 declare const TrackingAnalyticsSDK: {
+    captureError: (error: unknown, options?: import("./types").CaptureErrorOptions) => Promise<import("./types").TrackingDispatchResult>;
     init: (options: import("./types").TrackingInitOptions) => Promise<void>;
     track: (eventName: string, options?: import("./types").TrackOptions) => Promise<import("./types").TrackingDispatchResult>;
     identify: (userId: string | null) => void;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { getDebugState, identify, init, page, reset, track } from "./sdk";
-export type { PageOptions, TrackOptions, TrackingCollectPayload, TrackingDispatchResult, TrackingEventPayload, TrackingInitOptions, TrackingProperties, TrackingResponse, TrackingScalar, TrackingStateSnapshot, } from "./types";
+export { PREDEFINED_TRACKING_EVENTS, type PredefinedTrackingEventName, } from "./predefined-events";
+export { captureError, getDebugState, identify, init, page, reset, track } from "./sdk";
+export type { CaptureErrorOptions, PageOptions, TrackOptions, TrackingCollectPayload, TrackingDispatchResult, TrackingEventPayload, TrackingInitOptions, TrackingProperties, TrackingResponse, TrackingScalar, TrackingStateSnapshot, } from "./types";

package/dist/index.global.js

@@ -33,6 +33,41 @@
     TrackingAnalyticsSDK: () => TrackingAnalyticsSDK
   });
 
+  // src/predefined-events.ts
+  var PREDEFINED_TRACKING_EVENTS = {
+    pageView: {
+      eventName: "$page_view",
+      displayName: "页面浏览"
+    },
+    elementClick: {
+      eventName: "$element_click",
+      displayName: "元素点击"
+    },
+    formSubmit: {
+      eventName: "$form_submit",
+      displayName: "表单提交"
+    },
+    search: {
+      eventName: "$search",
+      displayName: "发起搜索"
+    },
+    exposure: {
+      eventName: "$exposure",
+      displayName: "内容曝光"
+    },
+    fileDownload: {
+      eventName: "$file_download",
+      displayName: "文件下载"
+    },
+    share: {
+      eventName: "$share",
+      displayName: "分享"
+    },
+    error: {
+      eventName: "$error",
+      displayName: "异常错误"
+    }
+  };
   // src/sdk-core.ts
   var DEFAULT_ENDPOINT = "/track/collect";
   var DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
@@ -52,6 +87,7 @@
       writeKey,
       endpoint: normalizeOptionalString(options.endpoint) ?? DEFAULT_ENDPOINT,
       autoPageview: options.autoPageview ?? true,
+      autoErrorCapture: options.autoErrorCapture ?? false,
       sessionTimeoutMs: Math.max(options.sessionTimeoutMinutes ?? DEFAULT_SESSION_TIMEOUT_MINUTES, 1) * 60000,
       storagePrefix: normalizeOptionalString(options.storagePrefix) ?? DEFAULT_STORAGE_PREFIX
     };
@@ -261,6 +297,157 @@
     return await response.json();
   };
 
+  // src/sdk-error.ts
+  var MAX_ERROR_MESSAGE_LENGTH = 500;
+  var MAX_ERROR_STACK_LENGTH = 2000;
+  var installGlobalErrorListeners = (browser, client) => {
+    const addEventListener = browser.addEventListener?.bind(globalThis);
+    const removeEventListener = browser.removeEventListener?.bind(globalThis);
+    if (!addEventListener || !removeEventListener) {
+      return null;
+    }
+    const runtime = {
+      lastFingerprint: null,
+      lastCapturedAt: 0
+    };
+    const onError = (event) => {
+      captureErrorEvent(client, runtime, toWindowErrorTrackOptions(event));
+    };
+    const onUnhandledRejection = (event) => {
+      captureErrorEvent(client, runtime, toUnhandledRejectionTrackOptions(event));
+    };
+    addEventListener("error", onError);
+    addEventListener("unhandledrejection", onUnhandledRejection);
+    return () => {
+      removeEventListener("error", onError);
+      removeEventListener("unhandledrejection", onUnhandledRejection);
+    };
+  };
+  var captureErrorEvent = async (client, runtime, options) => {
+    const fingerprint = buildFingerprint(options.properties);
+    const now = Date.now();
+    if (fingerprint && runtime.lastFingerprint === fingerprint && now - runtime.lastCapturedAt < 1000) {
+      return;
+    }
+    runtime.lastFingerprint = fingerprint;
+    runtime.lastCapturedAt = now;
+    try {
+      await client.track(PREDEFINED_TRACKING_EVENTS.error.eventName, options);
+    } catch {
+      return;
+    }
+  };
+  var toWindowErrorTrackOptions = (event) => {
+    const record = asRecord(event);
+    const nestedError = record.error;
+    const error = nestedError instanceof Error ? nestedError : null;
+    const message = firstNonEmptyString(asString(record.message), error?.message, "Script error");
+    const properties = {
+      error_kind: "window_error",
+      message: truncate(message, MAX_ERROR_MESSAGE_LENGTH),
+      filename: normalizeOptionalString(asString(record.filename)),
+      lineno: asNumber(record.lineno),
+      colno: asNumber(record.colno),
+      stack: truncate(normalizeOptionalString(error?.stack) ?? message, MAX_ERROR_STACK_LENGTH)
+    };
+    return {
+      properties: compactProperties(properties)
+    };
+  };
+  var toUnhandledRejectionTrackOptions = (event) => {
+    const record = asRecord(event);
+    const reason = record.reason;
+    const normalized = normalizeUnknownError(reason);
+    const properties = {
+      error_kind: "unhandledrejection",
+      message: truncate(normalized.message, MAX_ERROR_MESSAGE_LENGTH),
+      error_name: normalized.name,
+      stack: truncate(normalized.stack ?? normalized.message, MAX_ERROR_STACK_LENGTH)
+    };
+    return {
+      properties: compactProperties(properties)
+    };
+  };
+  var toManualErrorTrackOptions = (error, options = {}) => {
+    const normalized = normalizeUnknownError(error);
+    const source = normalizeOptionalString(options.source) ?? "manual";
+    const properties = {
+      error_kind: "captured_error",
+      error_name: normalized.name,
+      message: truncate(normalized.message, MAX_ERROR_MESSAGE_LENGTH),
+      stack: truncate(normalized.stack ?? normalized.message, MAX_ERROR_STACK_LENGTH),
+      source,
+      ...options.properties
+    };
+    return {
+      eventTime: options.eventTime,
+      page: options.page,
+      properties: compactProperties(properties)
+    };
+  };
+  var normalizeUnknownError = (input) => {
+    if (input instanceof Error) {
+      return {
+        name: normalizeOptionalString(input.name),
+        message: input.message || input.name || "Unknown error",
+        stack: normalizeOptionalString(input.stack)
+      };
+    }
+    const record = asRecord(input);
+    const name = normalizeOptionalString(asString(record.name));
+    const message = firstNonEmptyString(asString(record.message), stringifyUnknown(input), "Unknown error") ?? "Unknown error";
+    return {
+      name,
+      message,
+      stack: normalizeOptionalString(asString(record.stack))
+    };
+  };
+  var buildFingerprint = (properties) => {
+    if (!properties) {
+      return null;
+    }
+    return JSON.stringify(Object.entries(properties).sort(([left], [right]) => left.localeCompare(right)));
+  };
+  var compactProperties = (properties) => Object.entries(properties).reduce((accumulator, [key, value]) => {
+    if (typeof value === "string") {
+      const normalized = normalizeOptionalString(value);
+      if (normalized) {
+        accumulator[key] = normalized;
+      }
+      return accumulator;
+    }
+    if (typeof value === "number" || typeof value === "boolean" || value === null) {
+      accumulator[key] = value;
+    }
+    return accumulator;
+  }, {});
+  var asRecord = (value) => typeof value === "object" && value !== null ? value : {};
+  var asString = (value) => typeof value === "string" ? value : null;
+  var asNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+  var firstNonEmptyString = (...values) => {
+    for (const value of values) {
+      const normalized = normalizeOptionalString(value);
+      if (normalized) {
+        return normalized;
+      }
+    }
+    return null;
+  };
+  var truncate = (value, maxLength) => value && value.length > maxLength ? value.slice(0, maxLength) : value;
+  var stringifyUnknown = (value) => {
+    if (typeof value === "string") {
+      return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean" || value === null) {
+      return String(value);
+    }
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return null;
+    }
+  };
+
   // src/sdk-client.ts
   var createTrackingClient = (options) => {
     const browser = resolveBrowser();
@@ -268,6 +455,7 @@
     const storage = createScopedStorage(browser, config.storagePrefix);
     let state = loadState(browser, storage);
     let routeListenerCleanup = null;
+    let errorListenerCleanup = null;
     const routeRuntime = {
       timer: null,
       lastAutoPageUrl: normalizeOptionalString(browser.location?.href)
@@ -307,7 +495,7 @@
         return null;
       }
       routeRuntime.lastAutoPageUrl = currentUrl;
-      return dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view"));
+      return dispatchCollect(browser, config.endpoint, createCollectPayload(PREDEFINED_TRACKING_EVENTS.pageView.eventName));
     };
     const installRouteListeners = () => {
       const addEventListener = browser.addEventListener?.bind(globalThis);
@@ -351,14 +539,19 @@
     };
     return {
       init: async () => {
-        if (!config.autoPageview) {
-          return;
+        if (config.autoPageview) {
+          await dispatchCollect(browser, config.endpoint, createCollectPayload(PREDEFINED_TRACKING_EVENTS.pageView.eventName));
+          routeRuntime.lastAutoPageUrl = normalizeOptionalString(browser.location?.href);
+          routeListenerCleanup = installRouteListeners();
+        }
+        if (config.autoErrorCapture) {
+          errorListenerCleanup = installGlobalErrorListeners(browser, {
+            track: async (eventName, options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload(eventName, options2))
+          });
         }
-        await dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view"));
-        routeRuntime.lastAutoPageUrl = normalizeOptionalString(browser.location?.href);
-        routeListenerCleanup = installRouteListeners();
       },
       track: async (eventName, options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload(eventName, options2)),
+      captureError: async (error, options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload(PREDEFINED_TRACKING_EVENTS.error.eventName, toManualErrorTrackOptions(error, options2))),
       identify: (userId) => {
         state = {
           ...state,
@@ -366,7 +559,7 @@
         };
         persistState(storage, state);
       },
-      page: async (options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view", {
+      page: async (options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload(PREDEFINED_TRACKING_EVENTS.pageView.eventName, {
         properties: options2.properties,
         page: options2
       })),
@@ -380,6 +573,8 @@
       destroy: () => {
         routeListenerCleanup?.();
         routeListenerCleanup = null;
+        errorListenerCleanup?.();
+        errorListenerCleanup = null;
       }
     };
   };
@@ -392,6 +587,7 @@
     await trackingClient.init();
   };
   var track = async (eventName, options = {}) => getClient().track(eventName, options);
+  var captureError = async (error, options = {}) => getClient().captureError(error, options);
   var identify = (userId) => {
     getClient().identify(userId);
   };
@@ -406,6 +602,7 @@
   };
   // src/browser.ts
   var TrackingAnalyticsSDK = {
+    captureError,
     init,
     track,
     identify,

package/dist/index.js

@@ -1,3 +1,38 @@
+// src/predefined-events.ts
+var PREDEFINED_TRACKING_EVENTS = {
+  pageView: {
+    eventName: "$page_view",
+    displayName: "页面浏览"
+  },
+  elementClick: {
+    eventName: "$element_click",
+    displayName: "元素点击"
+  },
+  formSubmit: {
+    eventName: "$form_submit",
+    displayName: "表单提交"
+  },
+  search: {
+    eventName: "$search",
+    displayName: "发起搜索"
+  },
+  exposure: {
+    eventName: "$exposure",
+    displayName: "内容曝光"
+  },
+  fileDownload: {
+    eventName: "$file_download",
+    displayName: "文件下载"
+  },
+  share: {
+    eventName: "$share",
+    displayName: "分享"
+  },
+  error: {
+    eventName: "$error",
+    displayName: "异常错误"
+  }
+};
 // src/sdk-core.ts
 var DEFAULT_ENDPOINT = "/track/collect";
 var DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
@@ -17,6 +52,7 @@ var normalizeConfig = (options) => {
     writeKey,
     endpoint: normalizeOptionalString(options.endpoint) ?? DEFAULT_ENDPOINT,
     autoPageview: options.autoPageview ?? true,
+    autoErrorCapture: options.autoErrorCapture ?? false,
     sessionTimeoutMs: Math.max(options.sessionTimeoutMinutes ?? DEFAULT_SESSION_TIMEOUT_MINUTES, 1) * 60000,
     storagePrefix: normalizeOptionalString(options.storagePrefix) ?? DEFAULT_STORAGE_PREFIX
   };
@@ -226,6 +262,157 @@ var postWithFetch = async (browser, endpoint, body) => {
   return await response.json();
 };
 
+// src/sdk-error.ts
+var MAX_ERROR_MESSAGE_LENGTH = 500;
+var MAX_ERROR_STACK_LENGTH = 2000;
+var installGlobalErrorListeners = (browser, client) => {
+  const addEventListener = browser.addEventListener?.bind(globalThis);
+  const removeEventListener = browser.removeEventListener?.bind(globalThis);
+  if (!addEventListener || !removeEventListener) {
+    return null;
+  }
+  const runtime = {
+    lastFingerprint: null,
+    lastCapturedAt: 0
+  };
+  const onError = (event) => {
+    captureErrorEvent(client, runtime, toWindowErrorTrackOptions(event));
+  };
+  const onUnhandledRejection = (event) => {
+    captureErrorEvent(client, runtime, toUnhandledRejectionTrackOptions(event));
+  };
+  addEventListener("error", onError);
+  addEventListener("unhandledrejection", onUnhandledRejection);
+  return () => {
+    removeEventListener("error", onError);
+    removeEventListener("unhandledrejection", onUnhandledRejection);
+  };
+};
+var captureErrorEvent = async (client, runtime, options) => {
+  const fingerprint = buildFingerprint(options.properties);
+  const now = Date.now();
+  if (fingerprint && runtime.lastFingerprint === fingerprint && now - runtime.lastCapturedAt < 1000) {
+    return;
+  }
+  runtime.lastFingerprint = fingerprint;
+  runtime.lastCapturedAt = now;
+  try {
+    await client.track(PREDEFINED_TRACKING_EVENTS.error.eventName, options);
+  } catch {
+    return;
+  }
+};
+var toWindowErrorTrackOptions = (event) => {
+  const record = asRecord(event);
+  const nestedError = record.error;
+  const error = nestedError instanceof Error ? nestedError : null;
+  const message = firstNonEmptyString(asString(record.message), error?.message, "Script error");
+  const properties = {
+    error_kind: "window_error",
+    message: truncate(message, MAX_ERROR_MESSAGE_LENGTH),
+    filename: normalizeOptionalString(asString(record.filename)),
+    lineno: asNumber(record.lineno),
+    colno: asNumber(record.colno),
+    stack: truncate(normalizeOptionalString(error?.stack) ?? message, MAX_ERROR_STACK_LENGTH)
+  };
+  return {
+    properties: compactProperties(properties)
+  };
+};
+var toUnhandledRejectionTrackOptions = (event) => {
+  const record = asRecord(event);
+  const reason = record.reason;
+  const normalized = normalizeUnknownError(reason);
+  const properties = {
+    error_kind: "unhandledrejection",
+    message: truncate(normalized.message, MAX_ERROR_MESSAGE_LENGTH),
+    error_name: normalized.name,
+    stack: truncate(normalized.stack ?? normalized.message, MAX_ERROR_STACK_LENGTH)
+  };
+  return {
+    properties: compactProperties(properties)
+  };
+};
+var toManualErrorTrackOptions = (error, options = {}) => {
+  const normalized = normalizeUnknownError(error);
+  const source = normalizeOptionalString(options.source) ?? "manual";
+  const properties = {
+    error_kind: "captured_error",
+    error_name: normalized.name,
+    message: truncate(normalized.message, MAX_ERROR_MESSAGE_LENGTH),
+    stack: truncate(normalized.stack ?? normalized.message, MAX_ERROR_STACK_LENGTH),
+    source,
+    ...options.properties
+  };
+  return {
+    eventTime: options.eventTime,
+    page: options.page,
+    properties: compactProperties(properties)
+  };
+};
+var normalizeUnknownError = (input) => {
+  if (input instanceof Error) {
+    return {
+      name: normalizeOptionalString(input.name),
+      message: input.message || input.name || "Unknown error",
+      stack: normalizeOptionalString(input.stack)
+    };
+  }
+  const record = asRecord(input);
+  const name = normalizeOptionalString(asString(record.name));
+  const message = firstNonEmptyString(asString(record.message), stringifyUnknown(input), "Unknown error") ?? "Unknown error";
+  return {
+    name,
+    message,
+    stack: normalizeOptionalString(asString(record.stack))
+  };
+};
+var buildFingerprint = (properties) => {
+  if (!properties) {
+    return null;
+  }
+  return JSON.stringify(Object.entries(properties).sort(([left], [right]) => left.localeCompare(right)));
+};
+var compactProperties = (properties) => Object.entries(properties).reduce((accumulator, [key, value]) => {
+  if (typeof value === "string") {
+    const normalized = normalizeOptionalString(value);
+    if (normalized) {
+      accumulator[key] = normalized;
+    }
+    return accumulator;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || value === null) {
+    accumulator[key] = value;
+  }
+  return accumulator;
+}, {});
+var asRecord = (value) => typeof value === "object" && value !== null ? value : {};
+var asString = (value) => typeof value === "string" ? value : null;
+var asNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+var firstNonEmptyString = (...values) => {
+  for (const value of values) {
+    const normalized = normalizeOptionalString(value);
+    if (normalized) {
+      return normalized;
+    }
+  }
+  return null;
+};
+var truncate = (value, maxLength) => value && value.length > maxLength ? value.slice(0, maxLength) : value;
+var stringifyUnknown = (value) => {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || value === null) {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return null;
+  }
+};
+
 // src/sdk-client.ts
 var createTrackingClient = (options) => {
   const browser = resolveBrowser();
@@ -233,6 +420,7 @@ var createTrackingClient = (options) => {
   const storage = createScopedStorage(browser, config.storagePrefix);
   let state = loadState(browser, storage);
   let routeListenerCleanup = null;
+  let errorListenerCleanup = null;
   const routeRuntime = {
     timer: null,
     lastAutoPageUrl: normalizeOptionalString(browser.location?.href)
@@ -272,7 +460,7 @@ var createTrackingClient = (options) => {
       return null;
     }
     routeRuntime.lastAutoPageUrl = currentUrl;
-    return dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view"));
+    return dispatchCollect(browser, config.endpoint, createCollectPayload(PREDEFINED_TRACKING_EVENTS.pageView.eventName));
   };
   const installRouteListeners = () => {
     const addEventListener = browser.addEventListener?.bind(globalThis);
@@ -316,14 +504,19 @@ var createTrackingClient = (options) => {
   };
   return {
     init: async () => {
-      if (!config.autoPageview) {
-        return;
+      if (config.autoPageview) {
+        await dispatchCollect(browser, config.endpoint, createCollectPayload(PREDEFINED_TRACKING_EVENTS.pageView.eventName));
+        routeRuntime.lastAutoPageUrl = normalizeOptionalString(browser.location?.href);
+        routeListenerCleanup = installRouteListeners();
+      }
+      if (config.autoErrorCapture) {
+        errorListenerCleanup = installGlobalErrorListeners(browser, {
+          track: async (eventName, options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload(eventName, options2))
+        });
       }
-      await dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view"));
-      routeRuntime.lastAutoPageUrl = normalizeOptionalString(browser.location?.href);
-      routeListenerCleanup = installRouteListeners();
     },
     track: async (eventName, options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload(eventName, options2)),
+    captureError: async (error, options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload(PREDEFINED_TRACKING_EVENTS.error.eventName, toManualErrorTrackOptions(error, options2))),
     identify: (userId) => {
       state = {
         ...state,
@@ -331,7 +524,7 @@ var createTrackingClient = (options) => {
       };
       persistState(storage, state);
     },
-    page: async (options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view", {
+    page: async (options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload(PREDEFINED_TRACKING_EVENTS.pageView.eventName, {
       properties: options2.properties,
       page: options2
     })),
@@ -345,6 +538,8 @@ var createTrackingClient = (options) => {
     destroy: () => {
       routeListenerCleanup?.();
       routeListenerCleanup = null;
+      errorListenerCleanup?.();
+      errorListenerCleanup = null;
     }
   };
 };
@@ -357,6 +552,7 @@ var init = async (options) => {
   await trackingClient.init();
 };
 var track = async (eventName, options = {}) => getClient().track(eventName, options);
+var captureError = async (error, options = {}) => getClient().captureError(error, options);
 var identify = (userId) => {
   getClient().identify(userId);
 };
@@ -375,5 +571,7 @@ export {
   page,
   init,
   identify,
-  getDebugState
+  getDebugState,
+  captureError,
+  PREDEFINED_TRACKING_EVENTS
 };

package/dist/predefined-events.d.ts

@@ -0,0 +1,35 @@
+export declare const PREDEFINED_TRACKING_EVENTS: {
+    readonly pageView: {
+        readonly eventName: "$page_view";
+        readonly displayName: "页面浏览";
+    };
+    readonly elementClick: {
+        readonly eventName: "$element_click";
+        readonly displayName: "元素点击";
+    };
+    readonly formSubmit: {
+        readonly eventName: "$form_submit";
+        readonly displayName: "表单提交";
+    };
+    readonly search: {
+        readonly eventName: "$search";
+        readonly displayName: "发起搜索";
+    };
+    readonly exposure: {
+        readonly eventName: "$exposure";
+        readonly displayName: "内容曝光";
+    };
+    readonly fileDownload: {
+        readonly eventName: "$file_download";
+        readonly displayName: "文件下载";
+    };
+    readonly share: {
+        readonly eventName: "$share";
+        readonly displayName: "分享";
+    };
+    readonly error: {
+        readonly eventName: "$error";
+        readonly displayName: "异常错误";
+    };
+};
+export type PredefinedTrackingEventName = (typeof PREDEFINED_TRACKING_EVENTS)[keyof typeof PREDEFINED_TRACKING_EVENTS]["eventName"];

package/dist/sdk-core.d.ts

@@ -1,4 +1,4 @@
-import type { PageOptions, TrackOptions, TrackingDispatchResult, TrackingInitOptions, TrackingStateSnapshot } from "./types";
+import type { CaptureErrorOptions, PageOptions, TrackOptions, TrackingDispatchResult, TrackingInitOptions, TrackingStateSnapshot } from "./types";
 export declare const DEFAULT_ENDPOINT = "/track/collect";
 export declare const DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
 export declare const DEFAULT_STORAGE_PREFIX = "rs_tracking_sdk";
@@ -52,12 +52,14 @@ export interface NormalizedConfig {
     writeKey: string;
     endpoint: string;
     autoPageview: boolean;
+    autoErrorCapture: boolean;
     sessionTimeoutMs: number;
     storagePrefix: string;
 }
 export interface TrackingClient {
     init: () => Promise<void>;
     track: (eventName: string, options?: TrackOptions) => Promise<TrackingDispatchResult>;
+    captureError: (error: unknown, options?: CaptureErrorOptions) => Promise<TrackingDispatchResult>;
     identify: (userId: string | null) => void;
     page: (options?: PageOptions) => Promise<TrackingDispatchResult>;
     reset: () => TrackingStateSnapshot;

package/dist/sdk-error.d.ts

@@ -0,0 +1,18 @@
+import type { CaptureErrorOptions, TrackOptions } from "./types";
+import { type BrowserLike, type TrackingClient } from "./sdk-core";
+/**
+ * 安装全局错误监听，将浏览器未处理异常统一转成 `$error` 事件。
+ *
+ * @param browser - 浏览器能力对象
+ * @param client - 当前追踪客户端
+ * @returns 返回卸载监听的方法；环境能力不足时返回 null
+ */
+export declare const installGlobalErrorListeners: (browser: BrowserLike, client: Pick<TrackingClient, "track">) => (() => void) | null;
+/**
+ * 将任意错误对象转换为 `$error` 事件参数，供框架级手动上报复用。
+ *
+ * @param error - 任意错误对象
+ * @param options - 额外上下文与自定义属性
+ * @returns 返回 SDK 可直接上报的 track 参数
+ */
+export declare const toManualErrorTrackOptions: (error: unknown, options?: CaptureErrorOptions) => TrackOptions;

package/dist/sdk.d.ts

@@ -1,4 +1,4 @@
-import type { PageOptions, TrackOptions, TrackingDispatchResult, TrackingInitOptions, TrackingStateSnapshot } from "./types";
+import type { CaptureErrorOptions, PageOptions, TrackOptions, TrackingDispatchResult, TrackingInitOptions, TrackingStateSnapshot } from "./types";
 /**
  * 初始化 SDK，并按默认配置发送一次 `$page_view`。
  *
@@ -14,6 +14,14 @@ export declare const init: (options: TrackingInitOptions) => Promise<void>;
  * @returns 返回本次上报的传输结果
  */
 export declare const track: (eventName: string, options?: TrackOptions) => Promise<TrackingDispatchResult>;
+/**
+ * 手动捕获错误并按 `$error` 事件结构上报。
+ *
+ * @param error - 任意错误对象
+ * @param options - 额外页面上下文与业务属性
+ * @returns 返回本次上报的传输结果
+ */
+export declare const captureError: (error: unknown, options?: CaptureErrorOptions) => Promise<TrackingDispatchResult>;
 /**
  * 识别当前登录用户，仅影响后续事件。
  *

package/dist/types.d.ts

@@ -4,6 +4,7 @@ export interface TrackingInitOptions {
     writeKey: string;
     endpoint: string;
     autoPageview?: boolean;
+    autoErrorCapture?: boolean;
     sessionTimeoutMinutes?: number;
     storagePrefix?: string;
 }
@@ -19,6 +20,9 @@ export interface TrackOptions {
     properties?: TrackingProperties;
     page?: PageOptions;
 }
+export interface CaptureErrorOptions extends TrackOptions {
+    source?: string;
+}
 export interface TrackingEventPayload {
     event_name: string;
     event_time?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rsclick-log-sdk-web",
-    "version": "0.2.1",
+    "version": "0.2.2",
     "private": false,
     "type": "module",
     "description": "Lightweight Web tracking SDK for rs-click-log.",