@arms/rum-core 0.1.3 → 0.1.5

package/README.md

@@ -1,3 +1,27 @@
-## @arms/rum-core
+# @arms/rum-core
 
-Core 为 SDK 上报提供核心流程角色抽象
+ARMS RUM SDK 多端方案的核心抽象层，为各平台 shell（`browser` / `uniapp` / `miniapp` / `minigame` / `electron` / `reactnative` 等）提供统一的角色模型、事件协议与跨运行时工具。
+
+## 角色模型
+
+- **Client**：装载并编排 `Collector` / `Processor` / `Reporter`，串联事件管线。
+- **Context**：运行时上下文，承载 `config` / `session` / `views` / `emitter`。
+- **Shell**：对外 API 入口，提供 `sendCustom` / `sendView` / `sendException` / `sendResource`。
+- **ConfigManager**：本地+远端配置编排，支持 `launch-first` / `remote-first` 两种模式。
+- **Collector / Processor / Reporter**：平台扩展点，分别负责数据采集、加工、上报。
+
+事件流：`Collector → sendEvent → Processor 链 → Reporter（队列 / 合并 / 重试） → Transport`。
+
+## 支持运行时
+
+浏览器（ES2017+，不含 IE）、Node.js 16+、Deno、Bun、Electron、React Native 0.68+、微信/支付宝/字节小程序（基础库 2.10+ 同等能力）、uni-app 3.x。
+
+`core` 自身不依赖任何浏览器或 Node 专属 API（`window` / `document` / `fetch` / `localStorage` / `XMLHttpRequest` 等）；host API 通过 `env/` 抽象由 shell 注入。
+
+
+## 开发
+
+```bash
+npm run build    # 产出 lib/ (CJS) + es/ (ESM)
+npm test         # 单元测试（先 build 后 test，重构后改为直接跑 ts 源码）
+```

package/es/model/configManager.js

@@ -3,8 +3,15 @@ import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
 import _regeneratorRuntime from "@babel/runtime/regenerator";
 function parseRemoteConfig(config) {
   var remoteConfig = config.remoteConfig || {};
+  var enable = false;
+  if ('enable' in remoteConfig) {
+    enable = !!remoteConfig.enable;
+  } else if (remoteConfig.region || remoteConfig.url) {
+    enable = true;
+  }
   return {
-    enable: remoteConfig.enable !== false && !!(remoteConfig.url || remoteConfig.region),
+    enable: enable,
+    // remoteConfig.enable !== false && !!(remoteConfig.url || remoteConfig.region),
     url: remoteConfig.url || '',
     mode: remoteConfig.mode || 'launch-first',
     cacheTimeout: remoteConfig.cacheTimeout || 3600000,
@@ -94,7 +101,7 @@ export var ConfigManager = /*#__PURE__*/function () {
    * 获取配置
    * @returns 配置数据
    */
-  ;
+;
   _proto.getConfig = function getConfig() {
     if (!this.currentConfig) {
       throw new Error('Config not initialized');
@@ -136,7 +143,7 @@ export var ConfigManager = /*#__PURE__*/function () {
    * @param cachedData 缓存数据
    * @param cacheTimeout 缓存超时时间
    */
-  ;
+;
   _proto.isCacheValid = function isCacheValid(cachedData, cacheTimeout) {
     if (!cachedData || !cachedData.timestamp) {
       return false;

package/es/model/reporter.js

@@ -232,7 +232,7 @@ var Reporter = /*#__PURE__*/function () {
   /**
    * 接口请求由各平台 sdk reporter 实现
    */
-  ;
+;
   /**
    * 初始化时
    */

package/es/types/client.d.ts

@@ -33,7 +33,15 @@ export interface IContext {
     [key: string]: any;
 }
 export interface SessionConfig {
+    /**
+     * Session 采样率，取值范围 0 - 1 的小数
+     * @deprecated 该字段将在未来版本下线，请使用 {@link SessionConfig.sampling} 替代
+     */
     sampleRate?: number;
+    /**
+     * Session 采样率，取值范围 0 - 100，支持小数（如 50.5 表示 50.5%）
+     */
+    sampling?: number;
     maxDuration?: number;
     overtime?: number;
     storage?: string;

package/es/types/rum-event.d.ts

@@ -17,7 +17,102 @@ export interface IViewData extends BaseObject {
     loading_type?: loading_type;
 }
 export type BaseObjectPrimitiveValue = string | number | boolean | null | undefined;
-export type BaseObjectValue = BaseObjectPrimitiveValue | BaseObject | BaseObjectPrimitiveValue[] | IViewData;
+export type BaseObjectValue = BaseObjectPrimitiveValue | BaseObject | BaseObjectPrimitiveValue[] | IViewData | RumEventContext;
+/** 电池信息 */
+export interface BatteryContext {
+    /** 是否正在充电 */
+    charging?: boolean;
+    /** 电池电量百分比 (0-100) */
+    level?: number;
+    /** 电池温度（摄氏度） */
+    temperature?: number;
+}
+/** 设备信息 */
+export interface DeviceContext {
+    /** 设备 CPU 架构，如 'arm64', 'x86_64' */
+    architecture?: string;
+    /** 屏幕亮度等级 */
+    brightness_level?: number;
+    /** 芯片组型号 */
+    chipset?: string;
+    /** 当前语言区域，如 'zh-CN' */
+    locale?: string;
+    /** 用户偏好语言列表 */
+    locales?: string[];
+    /** 屏幕方向，如 'portrait', 'landscape' */
+    orientation?: string;
+    /** 是否开启省电模式 */
+    power_saving_mode?: boolean;
+    /** CPU 核心数 */
+    processor_count?: number;
+    /** CPU 主频（Hz） */
+    processor_frequency?: number;
+    /** 屏幕像素密度 */
+    screen_density?: number;
+    /** 屏幕 DPI */
+    screen_dpi?: number;
+    /** 是否为模拟器 */
+    simulator?: boolean;
+    /** 设备时区，如 'Asia/Shanghai' */
+    timezone?: string;
+}
+/** 内存信息 */
+export interface MemoryContext {
+    /** 可用内存（字节） */
+    free?: number;
+    /** 是否处于低内存状态 */
+    low?: boolean;
+    /** 总内存大小（字节） */
+    size?: number;
+}
+/** 网络信息 */
+export interface NetworkContext {
+    /** 可用网络接口列表 */
+    connectivity_interfaces?: string[];
+    /** 网络连接状态，如 'wifi', 'cellular', 'none' */
+    connectivity_status?: string;
+    /** 网络是否受限（如防火墙限制） */
+    is_constrained?: boolean;
+    /** 网络是否为计费网络（如蜂窝数据） */
+    is_expensive?: boolean;
+    /** 信号强度 */
+    signal_strength?: number;
+    /** 是否支持 IPv6 */
+    supports_ipv6?: boolean;
+}
+/** 操作系统信息 */
+export interface OsContext {
+    /** 系统构建号 */
+    build?: string;
+    /** 内核版本 */
+    kernel_version?: string;
+    /** 是否已 root / 越狱 */
+    rooted?: boolean;
+    /** 系统主版本号 */
+    version_major?: string;
+}
+/** 存储信息 */
+export interface StorageContext {
+    /** 可用存储（字节） */
+    free?: number;
+    /** 总存储大小（字节） */
+    size?: number;
+}
+/**
+ * RUM 事件上下文，描述设备运行时的环境快照。
+ * 字段命名与 DataDog / Sentry 的 context 协议对齐，
+ * 各端（Android / iOS / Electron）按能力选择性填充。
+ *
+ * @see docs/内存信息采集方案.md
+ */
+export interface RumEventContext {
+    battery?: BatteryContext;
+    device?: DeviceContext;
+    memory?: MemoryContext;
+    network?: NetworkContext;
+    os?: OsContext;
+    storage?: StorageContext;
+}
 export interface RumBaseEvent extends BaseObject {
     event_type?: RumEventType;
     event_id?: string;
@@ -25,6 +120,7 @@ export interface RumBaseEvent extends BaseObject {
     timestamp?: number;
     times?: number;
     view?: IViewData;
+    context?: RumEventContext;
     snapshots?: string;
     properties?: BaseObject;
 }
@@ -112,7 +208,7 @@ export interface RumResourceEvent extends RumBaseEvent {
     download_duration?: number;
     url?: string;
     timing_data?: string;
-    tracing_data?: string;
+    trace_data?: string;
 }
 export interface RumExceptionEvent extends RumBaseEvent {
     source?: string;
@@ -192,62 +288,154 @@ export declare enum AppType {
     uniapp = "uniapp",
     reactnative = "reactnative"
 }
+/**
+ * 上报包中的应用信息
+ *
+ * @see {@link AppType} 应用类型枚举
+ */
+export interface RumApp {
+    /** 应用唯一标识（由平台分配） */
+    id: string;
+    /** 应用类型，如 {@link AppType.browser}、{@link AppType.miniapp} */
+    type: AppType | string;
+    /** 应用名称 */
+    name?: string;
+    /** 应用版本号，如 '1.2.3' */
+    version?: string;
+    /** 发布渠道，如 'official'、'appstore' */
+    channel?: string;
+    /** 运行环境，如 'production'、'staging'、'development' */
+    env?: string;
+    /** 包名 / Bundle Identifier */
+    package?: string;
+    /** 宿主框架，如 'react'、'vue'、'uniapp' */
+    framework?: string;
+}
+/**
+ * 上报包中的用户信息
+ *
+ * @see {@link RumEventBundle} 上报数据包结构
+ */
+export interface RumUser {
+    /** 用户唯一标识（匿名 ID 或登录 ID） */
+    id: string;
+    /** 用户名称 */
+    name?: string;
+    /** 用户标签，多个标签以逗号分隔 */
+    tags?: string;
+}
+/** 上报包中的会话信息 */
+export interface RumSession {
+    /** 会话唯一标识，同一用户在同一会话周期内保持不变 */
+    id: string;
+}
+/**
+ * 上报包中的页面信息
+ *
+ * @see {@link IViewData} 事件级页面数据结构
+ */
+export interface RumView {
+    /** 页面唯一标识 */
+    id: string;
+    /** 页面名称 */
+    name: string;
+}
+/**
+ * 上报包中的设备信息
+ *
+ * @see {@link DeviceContext} 运行时设备详细上下文
+ */
+export interface RumDevice {
+    /** 设备唯一标识（如 IDFV、Android ID） */
+    id?: string;
+    /** 设备类型，如 'mobile'、'tablet'、'desktop' */
+    type?: string;
+    /** 设备品牌，如 'Apple'、'Huawei' */
+    brand?: string;
+    /** 设备型号，如 'iPhone 15'、'Mate 60' */
+    model?: string;
+    /** 设备名称 */
+    name?: string;
+}
+/**
+ * 上报包中的操作系统信息
+ *
+ * @see {@link OsContext} 运行时操作系统详细上下文
+ */
+export interface RumOS {
+    /** 操作系统类型，如 'iOS'、'Android'、'Windows' */
+    type?: string;
+    /** 操作系统完整版本号，如 '17.4.1' */
+    version?: string;
+    /** 容器环境，如 'WeChat'、'DingTalk'、'Chrome' */
+    container?: string;
+    /** 容器版本号 */
+    container_version?: string;
+}
+/** 上报包中的地理位置信息（由服务端根据 IP 解析填充） */
+export interface RumGeo {
+    /** 国家名称 */
+    country?: string;
+    /** 国家编码，如 ISO 3166-1 alpha-2 */
+    country_id?: string;
+    /** 省份 / 州名称 */
+    province?: string;
+    /** 省份编码 */
+    province_id?: string;
+    /** 城市名称 */
+    city?: string;
+    /** 城市编码 */
+    city_id?: string;
+}
+/** 上报包中的运营商信息（由服务端根据 IP 解析填充） */
+export interface RumISP {
+    /** 运营商编码 */
+    id?: string;
+    /** 运营商名称，如 '中国移动'、'中国联通' */
+    name?: string;
+}
+/** 上报包中的网络信息 */
+export interface RumNet {
+    /** 网络接入模型，如 '4G'、'5G'、'WiFi' */
+    model?: string;
+    /** 网络名称（如 SSID 或运营商 APN 名称） */
+    name?: string;
+    /** 客户端出口 IP 地址 */
+    ip?: string;
+}
+/**
+ * RUM 上报数据包，将一批事件与公共上下文打包后发送至服务端。
+ *
+ * @see {@link RumEvent} 包内携带的事件列表
+ * @see {@link RumApp} 应用信息
+ * @see {@link RumUser} 用户信息
+ */
 export interface RumEventBundle {
-    app: {
-        id: string;
-        type: AppType | string;
-        name?: string;
-        version?: string;
-        channel?: string;
-        env?: string;
-        package?: string;
-        framework?: string;
-    };
-    user: {
-        id: string;
-        name?: string;
-        tags?: string;
-    };
-    session: {
-        id: string;
-    };
-    view: {
-        id: string;
-        name: string;
-    };
-    device?: {
-        id?: string;
-        type?: string;
-        brand?: string;
-        model?: string;
-        name?: string;
-    };
-    os?: {
-        type?: string;
-        version?: string;
-        container?: string;
-        container_version?: string;
-    };
-    geo?: {
-        country?: string;
-        country_id?: string;
-        province?: string;
-        province_id?: string;
-        city?: string;
-        city_id?: string;
-    };
-    isp?: {
-        id?: string;
-        name?: string;
-    };
-    net?: {
-        model?: string;
-        name?: string;
-        ip?: string;
-    };
+    /** 应用信息 */
+    app: RumApp;
+    /** 用户信息 */
+    user: RumUser;
+    /** 会话信息 */
+    session: RumSession;
+    /** 当前页面信息 */
+    view: RumView;
+    /** 设备信息 */
+    device?: RumDevice;
+    /** 操作系统信息 */
+    os?: RumOS;
+    /** 地理位置信息 */
+    geo?: RumGeo;
+    /** 运营商信息 */
+    isp?: RumISP;
+    /** 网络信息 */
+    net?: RumNet;
+    /** 本次上报携带的事件列表 */
     events: Array<RumEvent>;
+    /** 全局自定义属性，附加到上报包级别 */
     properties?: BaseObject;
+    /** SDK 协议版本号 */
     _v?: string;
+    /** 重试次数（内部使用，首次上报为 undefined） */
     _retry?: number;
     [key: string]: unknown;
 }

package/es/types/rum-event.js

@@ -9,6 +9,26 @@ export var RumEventType = /*#__PURE__*/function (RumEventType) {
   return RumEventType;
 }({});
 
+/** 电池信息 */
+
+/** 设备信息 */
+
+/** 内存信息 */
+
+/** 网络信息 */
+
+/** 操作系统信息 */
+
+/** 存储信息 */
+
+/**
+ * RUM 事件上下文，描述设备运行时的环境快照。
+ * 字段命名与 DataDog / Sentry 的 context 协议对齐，
+ * 各端（Android / iOS / Electron）按能力选择性填充。
+ *
+ * @see docs/内存信息采集方案.md
+ */
+
 /** 事件类型：页面浏览、性能指标、Web Vitals、自定义指标、会话回放 */
 
 /**
@@ -27,4 +47,50 @@ export var AppType = /*#__PURE__*/function (AppType) {
   AppType["uniapp"] = "uniapp";
   AppType["reactnative"] = "reactnative";
   return AppType;
-}({});
+}({});
+
+/**
+ * 上报包中的应用信息
+ *
+ * @see {@link AppType} 应用类型枚举
+ */
+
+/**
+ * 上报包中的用户信息
+ *
+ * @see {@link RumEventBundle} 上报数据包结构
+ */
+
+/** 上报包中的会话信息 */
+
+/**
+ * 上报包中的页面信息
+ *
+ * @see {@link IViewData} 事件级页面数据结构
+ */
+
+/**
+ * 上报包中的设备信息
+ *
+ * @see {@link DeviceContext} 运行时设备详细上下文
+ */
+
+/**
+ * 上报包中的操作系统信息
+ *
+ * @see {@link OsContext} 运行时操作系统详细上下文
+ */
+
+/** 上报包中的地理位置信息（由服务端根据 IP 解析填充） */
+
+/** 上报包中的运营商信息（由服务端根据 IP 解析填充） */
+
+/** 上报包中的网络信息 */
+
+/**
+ * RUM 上报数据包，将一批事件与公共上下文打包后发送至服务端。
+ *
+ * @see {@link RumEvent} 包内携带的事件列表
+ * @see {@link RumApp} 应用信息
+ * @see {@link RumUser} 用户信息
+ */

package/lib/model/configManager.js

@@ -8,8 +8,15 @@ var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends")
 var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
 function parseRemoteConfig(config) {
   var remoteConfig = config.remoteConfig || {};
+  var enable = false;
+  if ('enable' in remoteConfig) {
+    enable = !!remoteConfig.enable;
+  } else if (remoteConfig.region || remoteConfig.url) {
+    enable = true;
+  }
   return {
-    enable: remoteConfig.enable !== false && !!(remoteConfig.url || remoteConfig.region),
+    enable: enable,
+    // remoteConfig.enable !== false && !!(remoteConfig.url || remoteConfig.region),
     url: remoteConfig.url || '',
     mode: remoteConfig.mode || 'launch-first',
     cacheTimeout: remoteConfig.cacheTimeout || 3600000,
@@ -99,7 +106,7 @@ var ConfigManager = exports.ConfigManager = /*#__PURE__*/function () {
    * 获取配置
    * @returns 配置数据
    */
-  ;
+;
   _proto.getConfig = function getConfig() {
     if (!this.currentConfig) {
       throw new Error('Config not initialized');
@@ -141,7 +148,7 @@ var ConfigManager = exports.ConfigManager = /*#__PURE__*/function () {
    * @param cachedData 缓存数据
    * @param cacheTimeout 缓存超时时间
    */
-  ;
+;
   _proto.isCacheValid = function isCacheValid(cachedData, cacheTimeout) {
     if (!cachedData || !cachedData.timestamp) {
       return false;

package/lib/model/reporter.js

@@ -237,7 +237,7 @@ var Reporter = exports["default"] = /*#__PURE__*/function () {
   /**
    * 接口请求由各平台 sdk reporter 实现
    */
-  ;
+;
   /**
    * 初始化时
    */

package/lib/types/client.d.ts

@@ -33,7 +33,15 @@ export interface IContext {
     [key: string]: any;
 }
 export interface SessionConfig {
+    /**
+     * Session 采样率，取值范围 0 - 1 的小数
+     * @deprecated 该字段将在未来版本下线，请使用 {@link SessionConfig.sampling} 替代
+     */
     sampleRate?: number;
+    /**
+     * Session 采样率，取值范围 0 - 100，支持小数（如 50.5 表示 50.5%）
+     */
+    sampling?: number;
     maxDuration?: number;
     overtime?: number;
     storage?: string;

package/lib/types/rum-event.d.ts

@@ -17,7 +17,102 @@ export interface IViewData extends BaseObject {
     loading_type?: loading_type;
 }
 export type BaseObjectPrimitiveValue = string | number | boolean | null | undefined;
-export type BaseObjectValue = BaseObjectPrimitiveValue | BaseObject | BaseObjectPrimitiveValue[] | IViewData;
+export type BaseObjectValue = BaseObjectPrimitiveValue | BaseObject | BaseObjectPrimitiveValue[] | IViewData | RumEventContext;
+/** 电池信息 */
+export interface BatteryContext {
+    /** 是否正在充电 */
+    charging?: boolean;
+    /** 电池电量百分比 (0-100) */
+    level?: number;
+    /** 电池温度（摄氏度） */
+    temperature?: number;
+}
+/** 设备信息 */
+export interface DeviceContext {
+    /** 设备 CPU 架构，如 'arm64', 'x86_64' */
+    architecture?: string;
+    /** 屏幕亮度等级 */
+    brightness_level?: number;
+    /** 芯片组型号 */
+    chipset?: string;
+    /** 当前语言区域，如 'zh-CN' */
+    locale?: string;
+    /** 用户偏好语言列表 */
+    locales?: string[];
+    /** 屏幕方向，如 'portrait', 'landscape' */
+    orientation?: string;
+    /** 是否开启省电模式 */
+    power_saving_mode?: boolean;
+    /** CPU 核心数 */
+    processor_count?: number;
+    /** CPU 主频（Hz） */
+    processor_frequency?: number;
+    /** 屏幕像素密度 */
+    screen_density?: number;
+    /** 屏幕 DPI */
+    screen_dpi?: number;
+    /** 是否为模拟器 */
+    simulator?: boolean;
+    /** 设备时区，如 'Asia/Shanghai' */
+    timezone?: string;
+}
+/** 内存信息 */
+export interface MemoryContext {
+    /** 可用内存（字节） */
+    free?: number;
+    /** 是否处于低内存状态 */
+    low?: boolean;
+    /** 总内存大小（字节） */
+    size?: number;
+}
+/** 网络信息 */
+export interface NetworkContext {
+    /** 可用网络接口列表 */
+    connectivity_interfaces?: string[];
+    /** 网络连接状态，如 'wifi', 'cellular', 'none' */
+    connectivity_status?: string;
+    /** 网络是否受限（如防火墙限制） */
+    is_constrained?: boolean;
+    /** 网络是否为计费网络（如蜂窝数据） */
+    is_expensive?: boolean;
+    /** 信号强度 */
+    signal_strength?: number;
+    /** 是否支持 IPv6 */
+    supports_ipv6?: boolean;
+}
+/** 操作系统信息 */
+export interface OsContext {
+    /** 系统构建号 */
+    build?: string;
+    /** 内核版本 */
+    kernel_version?: string;
+    /** 是否已 root / 越狱 */
+    rooted?: boolean;
+    /** 系统主版本号 */
+    version_major?: string;
+}
+/** 存储信息 */
+export interface StorageContext {
+    /** 可用存储（字节） */
+    free?: number;
+    /** 总存储大小（字节） */
+    size?: number;
+}
+/**
+ * RUM 事件上下文，描述设备运行时的环境快照。
+ * 字段命名与 DataDog / Sentry 的 context 协议对齐，
+ * 各端（Android / iOS / Electron）按能力选择性填充。
+ *
+ * @see docs/内存信息采集方案.md
+ */
+export interface RumEventContext {
+    battery?: BatteryContext;
+    device?: DeviceContext;
+    memory?: MemoryContext;
+    network?: NetworkContext;
+    os?: OsContext;
+    storage?: StorageContext;
+}
 export interface RumBaseEvent extends BaseObject {
     event_type?: RumEventType;
     event_id?: string;
@@ -25,6 +120,7 @@ export interface RumBaseEvent extends BaseObject {
     timestamp?: number;
     times?: number;
     view?: IViewData;
+    context?: RumEventContext;
     snapshots?: string;
     properties?: BaseObject;
 }
@@ -112,7 +208,7 @@ export interface RumResourceEvent extends RumBaseEvent {
     download_duration?: number;
     url?: string;
     timing_data?: string;
-    tracing_data?: string;
+    trace_data?: string;
 }
 export interface RumExceptionEvent extends RumBaseEvent {
     source?: string;
@@ -192,62 +288,154 @@ export declare enum AppType {
     uniapp = "uniapp",
     reactnative = "reactnative"
 }
+/**
+ * 上报包中的应用信息
+ *
+ * @see {@link AppType} 应用类型枚举
+ */
+export interface RumApp {
+    /** 应用唯一标识（由平台分配） */
+    id: string;
+    /** 应用类型，如 {@link AppType.browser}、{@link AppType.miniapp} */
+    type: AppType | string;
+    /** 应用名称 */
+    name?: string;
+    /** 应用版本号，如 '1.2.3' */
+    version?: string;
+    /** 发布渠道，如 'official'、'appstore' */
+    channel?: string;
+    /** 运行环境，如 'production'、'staging'、'development' */
+    env?: string;
+    /** 包名 / Bundle Identifier */
+    package?: string;
+    /** 宿主框架，如 'react'、'vue'、'uniapp' */
+    framework?: string;
+}
+/**
+ * 上报包中的用户信息
+ *
+ * @see {@link RumEventBundle} 上报数据包结构
+ */
+export interface RumUser {
+    /** 用户唯一标识（匿名 ID 或登录 ID） */
+    id: string;
+    /** 用户名称 */
+    name?: string;
+    /** 用户标签，多个标签以逗号分隔 */
+    tags?: string;
+}
+/** 上报包中的会话信息 */
+export interface RumSession {
+    /** 会话唯一标识，同一用户在同一会话周期内保持不变 */
+    id: string;
+}
+/**
+ * 上报包中的页面信息
+ *
+ * @see {@link IViewData} 事件级页面数据结构
+ */
+export interface RumView {
+    /** 页面唯一标识 */
+    id: string;
+    /** 页面名称 */
+    name: string;
+}
+/**
+ * 上报包中的设备信息
+ *
+ * @see {@link DeviceContext} 运行时设备详细上下文
+ */
+export interface RumDevice {
+    /** 设备唯一标识（如 IDFV、Android ID） */
+    id?: string;
+    /** 设备类型，如 'mobile'、'tablet'、'desktop' */
+    type?: string;
+    /** 设备品牌，如 'Apple'、'Huawei' */
+    brand?: string;
+    /** 设备型号，如 'iPhone 15'、'Mate 60' */
+    model?: string;
+    /** 设备名称 */
+    name?: string;
+}
+/**
+ * 上报包中的操作系统信息
+ *
+ * @see {@link OsContext} 运行时操作系统详细上下文
+ */
+export interface RumOS {
+    /** 操作系统类型，如 'iOS'、'Android'、'Windows' */
+    type?: string;
+    /** 操作系统完整版本号，如 '17.4.1' */
+    version?: string;
+    /** 容器环境，如 'WeChat'、'DingTalk'、'Chrome' */
+    container?: string;
+    /** 容器版本号 */
+    container_version?: string;
+}
+/** 上报包中的地理位置信息（由服务端根据 IP 解析填充） */
+export interface RumGeo {
+    /** 国家名称 */
+    country?: string;
+    /** 国家编码，如 ISO 3166-1 alpha-2 */
+    country_id?: string;
+    /** 省份 / 州名称 */
+    province?: string;
+    /** 省份编码 */
+    province_id?: string;
+    /** 城市名称 */
+    city?: string;
+    /** 城市编码 */
+    city_id?: string;
+}
+/** 上报包中的运营商信息（由服务端根据 IP 解析填充） */
+export interface RumISP {
+    /** 运营商编码 */
+    id?: string;
+    /** 运营商名称，如 '中国移动'、'中国联通' */
+    name?: string;
+}
+/** 上报包中的网络信息 */
+export interface RumNet {
+    /** 网络接入模型，如 '4G'、'5G'、'WiFi' */
+    model?: string;
+    /** 网络名称（如 SSID 或运营商 APN 名称） */
+    name?: string;
+    /** 客户端出口 IP 地址 */
+    ip?: string;
+}
+/**
+ * RUM 上报数据包，将一批事件与公共上下文打包后发送至服务端。
+ *
+ * @see {@link RumEvent} 包内携带的事件列表
+ * @see {@link RumApp} 应用信息
+ * @see {@link RumUser} 用户信息
+ */
 export interface RumEventBundle {
-    app: {
-        id: string;
-        type: AppType | string;
-        name?: string;
-        version?: string;
-        channel?: string;
-        env?: string;
-        package?: string;
-        framework?: string;
-    };
-    user: {
-        id: string;
-        name?: string;
-        tags?: string;
-    };
-    session: {
-        id: string;
-    };
-    view: {
-        id: string;
-        name: string;
-    };
-    device?: {
-        id?: string;
-        type?: string;
-        brand?: string;
-        model?: string;
-        name?: string;
-    };
-    os?: {
-        type?: string;
-        version?: string;
-        container?: string;
-        container_version?: string;
-    };
-    geo?: {
-        country?: string;
-        country_id?: string;
-        province?: string;
-        province_id?: string;
-        city?: string;
-        city_id?: string;
-    };
-    isp?: {
-        id?: string;
-        name?: string;
-    };
-    net?: {
-        model?: string;
-        name?: string;
-        ip?: string;
-    };
+    /** 应用信息 */
+    app: RumApp;
+    /** 用户信息 */
+    user: RumUser;
+    /** 会话信息 */
+    session: RumSession;
+    /** 当前页面信息 */
+    view: RumView;
+    /** 设备信息 */
+    device?: RumDevice;
+    /** 操作系统信息 */
+    os?: RumOS;
+    /** 地理位置信息 */
+    geo?: RumGeo;
+    /** 运营商信息 */
+    isp?: RumISP;
+    /** 网络信息 */
+    net?: RumNet;
+    /** 本次上报携带的事件列表 */
     events: Array<RumEvent>;
+    /** 全局自定义属性，附加到上报包级别 */
     properties?: BaseObject;
+    /** SDK 协议版本号 */
     _v?: string;
+    /** 重试次数（内部使用，首次上报为 undefined） */
     _retry?: number;
     [key: string]: unknown;
 }

package/lib/types/rum-event.js

@@ -12,6 +12,19 @@ var RumEventType = exports.RumEventType = /*#__PURE__*/function (RumEventType) {
   RumEventType["APPLICATION"] = "application";
   return RumEventType;
 }({});
+/** 电池信息 */
+/** 设备信息 */
+/** 内存信息 */
+/** 网络信息 */
+/** 操作系统信息 */
+/** 存储信息 */
+/**
+ * RUM 事件上下文，描述设备运行时的环境快照。
+ * 字段命名与 DataDog / Sentry 的 context 协议对齐，
+ * 各端（Android / iOS / Electron）按能力选择性填充。
+ *
+ * @see docs/内存信息采集方案.md
+ */
 /** 事件类型：页面浏览、性能指标、Web Vitals、自定义指标、会话回放 */
 /**
  * 枚举值，表示资源是否加载成功
@@ -29,4 +42,40 @@ var AppType = exports.AppType = /*#__PURE__*/function (AppType) {
   AppType["uniapp"] = "uniapp";
   AppType["reactnative"] = "reactnative";
   return AppType;
-}({});
+}({});
+/**
+ * 上报包中的应用信息
+ *
+ * @see {@link AppType} 应用类型枚举
+ */
+/**
+ * 上报包中的用户信息
+ *
+ * @see {@link RumEventBundle} 上报数据包结构
+ */
+/** 上报包中的会话信息 */
+/**
+ * 上报包中的页面信息
+ *
+ * @see {@link IViewData} 事件级页面数据结构
+ */
+/**
+ * 上报包中的设备信息
+ *
+ * @see {@link DeviceContext} 运行时设备详细上下文
+ */
+/**
+ * 上报包中的操作系统信息
+ *
+ * @see {@link OsContext} 运行时操作系统详细上下文
+ */
+/** 上报包中的地理位置信息（由服务端根据 IP 解析填充） */
+/** 上报包中的运营商信息（由服务端根据 IP 解析填充） */
+/** 上报包中的网络信息 */
+/**
+ * RUM 上报数据包，将一批事件与公共上下文打包后发送至服务端。
+ *
+ * @see {@link RumEvent} 包内携带的事件列表
+ * @see {@link RumApp} 应用信息
+ * @see {@link RumUser} 用户信息
+ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arms/rum-core",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "arms rum javascript sdk core",
   "author": "guangli.fj <guangli.fj@alibaba-inc.com>",
   "license": "ISC",