@gctrack/protocol 0.1.2 → 0.2.0

package/dist/index.cjs

@@ -1,4 +1,4 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+
 //#region src/index.ts
 /**
 * @gctrack/protocol — 前后端共享的事件协议与类型（唯一真相源）
@@ -66,8 +66,8 @@ const Platform = {
 	ToutiaoMp: "toutiao_mp",
 	KuaishouMp: "kuaishou_mp"
 };
+
 //#endregion
 exports.EventType = EventType;
 exports.Platform = Platform;
-
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @gctrack/protocol — 前后端共享的事件协议与类型（唯一真相源）\n *\n * SDK（packages/*）与后端（apps/collector、apps/bff）共用本文件，\n * 杜绝 EventData 等结构在前后端漂移。\n */\n\n/** 事件类型常量（见 design.md 附录 A） */\nexport const EventType = {\n  // 性能\n  PagePerformance: 'page_performance',\n  SlowResource: 'slow_resource',\n  LongTask: 'long_task',\n  FirstInputDelay: 'first_input_delay',\n  CumulativeLayoutShift: 'cumulative_layout_shift',\n  LargestContentfulPaint: 'largest_contentful_paint',\n  RouteChange: 'route_change',\n  CustomPerformance: 'custom_performance',\n  MpFirstRender: 'mp_first_render',\n  // 错误\n  JsError: 'js_error',\n  CrossOriginError: 'cross_origin_error',\n  PromiseError: 'promise_error',\n  ResourceError: 'resource_error',\n  ConsoleError: 'console_error',\n  ManualError: 'manual_error',\n  MemoryWarning: 'memory_warning',\n  VueError: 'vue_error',\n  MpScriptError: 'mp_script_error',\n  // 接口\n  ApiPerformance: 'api_performance',\n  ApiError: 'api_error',\n  // 行为\n  PageView: 'page_view',\n  PageStay: 'page_stay',\n  Click: 'click',\n  ScrollDepth: 'scroll_depth',\n  VisibilityChange: 'visibility_change',\n  UserInactive: 'user_inactive',\n  FormStart: 'form_start',\n  FormSubmit: 'form_submit',\n  FormAbandon: 'form_abandon',\n  Search: 'search',\n  VideoAction: 'video_action',\n  // 业务\n  UserRegister: 'user_register',\n  UserLogin: 'user_login',\n  SearchConversion: 'search_conversion',\n  OrderFunnel: 'order_funnel',\n  PaymentResult: 'payment_result',\n  CouponAction: 'coupon_action',\n  Share: 'share',\n  Review: 'review',\n  CustomerService: 'customer_service',\n  AbTest: 'ab_test',\n  FunnelStep: 'funnel_step',\n  FunnelLeave: 'funnel_leave',\n  FunnelComplete: 'funnel_complete',\n} as const\nexport type EventTypeValue = (typeof EventType)[keyof typeof EventType]\n\n/** 平台标识（写入 EventData.context.platform 与 ClickHouse platform 列） */\nexport const Platform = {\n  Web: 'web',\n  H5: 'h5',\n  WeixinMp: 'wx_mp',\n  AlipayMp: 'alipay_mp',\n  JdMp: 'jd_mp',\n  XhsMp: 'xhs_mp',\n  BaiduMp: 'baidu_mp',\n  QqMp: 'qq_mp',\n  ToutiaoMp: 'toutiao_mp',\n  KuaishouMp: 'kuaishou_mp',\n} as const\nexport type PlatformValue = (typeof Platform)[keyof typeof Platform]\n\n/**\n * 事件数据 —— 一条监控记录的统一结构。\n * 后端 ClickHouse monitor_event 表、SDK 上报 body 均以此为准。\n */\nexport interface EventData {\n  /** 事件类型，取 EventType 常量或业务自定义字符串 */\n  eventType: string\n  /** 事件 payload（错误堆栈 / 性能指标 / 接口信息等），自由结构 */\n  data?: Record<string, any>\n  /** 事件发生时间（毫秒） */\n  timestamp: number\n  /** 用户 ID（可能为空） */\n  userId?: string | null\n  /** 会话 ID */\n  sessionId: string\n  /** 页面 URL */\n  url?: string\n  /** 页面路径 */\n  pathname?: string\n  /** 页面标题 */\n  title?: string\n  /** 来源 URL */\n  referrer?: string\n  /** User-Agent（小程序端拼装） */\n  userAgent?: string\n  /** 自定义上下文（含 appName/appVersion/platform/environment/userProperties） */\n  context?: Record<string, any>\n}\n\n/** 上报鉴权方式 */\nexport type SignMode = 'hmac' | 'token' | 'none'\n\n/**\n * 追踪器配置。\n * 标注「增强」的字段为 core 通用增强新增项，详见 design.md 5.2。\n */\nexport interface TrackerConfig {\n  /** 上报地址（POST 目标） */\n  reportUrl: string\n  /** 应用标识（增强，collector 鉴权用） */\n  appKey?: string\n  /** 应用名称 */\n  appName?: string\n  /** 应用版本 */\n  appVersion?: string\n  /** 平台，见 Platform */\n  platform?: string\n  /** 环境：production | staging | dev */\n  environment?: string\n  /** 批量上报条数（默认 10） */\n  batchSize?: number\n  /** 定时上报间隔，毫秒（默认 5000） */\n  flushInterval?: number\n  /** 调试模式 */\n  debug?: boolean\n  /** 自定义上报函数（小程序适配用，包 uni.request） */\n  sendFn?: (data: EventData[]) => Promise<void>\n  /** 自定义上下文 */\n  context?: Record<string, any>\n  /** 自动收集设备信息 */\n  autoCollectDeviceInfo?: boolean\n  /** 自动收集页面信息 */\n  autoCollectPageInfo?: boolean\n  // ===== 以下为通用增强字段（core 增强阶段实现消费） =====\n  /** 签名密钥（增强） */\n  appSecret?: string\n  /** 采样率 0-1（增强，按 sessionId 哈希稳定采样） */\n  sampleRate?: number\n  /** 队列上限（增强，默认 100，超限丢最旧） */\n  maxQueueSize?: number\n  /** 离线持久化方式（增强） */\n  persistence?: 'none' | 'local' | 'session' | 'mp'\n  /** 鉴权方式（增强，小程序默认 none） */\n  signMode?: SignMode\n  /** 自定义脱敏函数；传 null 关闭脱敏，默认用内置 defaultSanitize */\n  sanitize?: ((event: EventData) => EventData) | null\n}\n\n/**\n * 插件接口。\n * 注意：beforeSend/afterSend 当前 core 未触发，core 增强阶段补齐。\n */\nexport interface TrackerPlugin {\n  name: string\n  install?: (tracker: any) => void\n  beforeTrack?: (eventType: string, data?: Record<string, any>) => void | false\n  afterTrack?: (eventType: string, data?: Record<string, any>) => void\n  /** flush 前处理（过滤/脱敏/采样），返回 false 丢弃整批 */\n  beforeSend?: (events: EventData[]) => EventData[] | false\n  /** flush 成功后回调 */\n  afterSend?: (events: EventData[]) => void\n}\n\n/** 接口监控事件 data 字段结构（api_performance / api_error） */\nexport interface ApiEventData {\n  url: string\n  method: string\n  status: number\n  duration: number\n  requestBodySize?: number\n  responseBodySize?: number\n  reason?: string // api_error 时的失败原因\n}\n"],"mappings":";;;;;;;;;AAQA,MAAa,YAAY;CAEvB,iBAAiB;CACjB,cAAc;CACd,UAAU;CACV,iBAAiB;CACjB,uBAAuB;CACvB,wBAAwB;CACxB,aAAa;CACb,mBAAmB;CACnB,eAAe;CAEf,SAAS;CACT,kBAAkB;CAClB,cAAc;CACd,eAAe;CACf,cAAc;CACd,aAAa;CACb,eAAe;CACf,UAAU;CACV,eAAe;CAEf,gBAAgB;CAChB,UAAU;CAEV,UAAU;CACV,UAAU;CACV,OAAO;CACP,aAAa;CACb,kBAAkB;CAClB,cAAc;CACd,WAAW;CACX,YAAY;CACZ,aAAa;CACb,QAAQ;CACR,aAAa;CAEb,cAAc;CACd,WAAW;CACX,kBAAkB;CAClB,aAAa;CACb,eAAe;CACf,cAAc;CACd,OAAO;CACP,QAAQ;CACR,iBAAiB;CACjB,QAAQ;CACR,YAAY;CACZ,aAAa;CACb,gBAAgB;CACjB;;AAID,MAAa,WAAW;CACtB,KAAK;CACL,IAAI;CACJ,UAAU;CACV,UAAU;CACV,MAAM;CACN,OAAO;CACP,SAAS;CACT,MAAM;CACN,WAAW;CACX,YAAY;CACb"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @gctrack/protocol — 前后端共享的事件协议与类型（唯一真相源）\n *\n * SDK（packages/*）与后端（apps/collector、apps/bff）共用本文件，\n * 杜绝 EventData 等结构在前后端漂移。\n */\n\n/** 事件类型常量（见 design.md 附录 A） */\nexport const EventType = {\n  // 性能\n  PagePerformance: 'page_performance',\n  SlowResource: 'slow_resource',\n  LongTask: 'long_task',\n  FirstInputDelay: 'first_input_delay',\n  CumulativeLayoutShift: 'cumulative_layout_shift',\n  LargestContentfulPaint: 'largest_contentful_paint',\n  RouteChange: 'route_change',\n  CustomPerformance: 'custom_performance',\n  MpFirstRender: 'mp_first_render',\n  // 错误\n  JsError: 'js_error',\n  CrossOriginError: 'cross_origin_error',\n  PromiseError: 'promise_error',\n  ResourceError: 'resource_error',\n  ConsoleError: 'console_error',\n  ManualError: 'manual_error',\n  MemoryWarning: 'memory_warning',\n  VueError: 'vue_error',\n  MpScriptError: 'mp_script_error',\n  // 接口\n  ApiPerformance: 'api_performance',\n  ApiError: 'api_error',\n  // 行为\n  PageView: 'page_view',\n  PageStay: 'page_stay',\n  Click: 'click',\n  ScrollDepth: 'scroll_depth',\n  VisibilityChange: 'visibility_change',\n  UserInactive: 'user_inactive',\n  FormStart: 'form_start',\n  FormSubmit: 'form_submit',\n  FormAbandon: 'form_abandon',\n  Search: 'search',\n  VideoAction: 'video_action',\n  // 业务\n  UserRegister: 'user_register',\n  UserLogin: 'user_login',\n  SearchConversion: 'search_conversion',\n  OrderFunnel: 'order_funnel',\n  PaymentResult: 'payment_result',\n  CouponAction: 'coupon_action',\n  Share: 'share',\n  Review: 'review',\n  CustomerService: 'customer_service',\n  AbTest: 'ab_test',\n  FunnelStep: 'funnel_step',\n  FunnelLeave: 'funnel_leave',\n  FunnelComplete: 'funnel_complete',\n} as const\nexport type EventTypeValue = (typeof EventType)[keyof typeof EventType]\n\n/** 平台标识（写入 EventData.context.platform 与 ClickHouse platform 列） */\nexport const Platform = {\n  Web: 'web',\n  H5: 'h5',\n  WeixinMp: 'wx_mp',\n  AlipayMp: 'alipay_mp',\n  JdMp: 'jd_mp',\n  XhsMp: 'xhs_mp',\n  BaiduMp: 'baidu_mp',\n  QqMp: 'qq_mp',\n  ToutiaoMp: 'toutiao_mp',\n  KuaishouMp: 'kuaishou_mp',\n} as const\nexport type PlatformValue = (typeof Platform)[keyof typeof Platform]\n\n/**\n * 事件数据 —— 一条监控记录的统一结构。\n * 后端 ClickHouse monitor_event 表、SDK 上报 body 均以此为准。\n */\nexport interface EventData {\n  /** 事件类型，取 EventType 常量或业务自定义字符串 */\n  eventType: string\n  /** 事件 payload（错误堆栈 / 性能指标 / 接口信息等），自由结构 */\n  data?: Record<string, any>\n  /** 事件发生时间（毫秒） */\n  timestamp: number\n  /** 用户 ID（可能为空） */\n  userId?: string | null\n  /** 会话 ID */\n  sessionId: string\n  /** 匿名访客 ID（跨会话稳定，UV 去重依据；非 PII，可配置关闭） */\n  visitorId?: string\n  /** 页面 URL */\n  url?: string\n  /** 页面路径 */\n  pathname?: string\n  /** 页面标题 */\n  title?: string\n  /** 来源 URL */\n  referrer?: string\n  /** User-Agent（小程序端拼装） */\n  userAgent?: string\n  /** 自定义上下文（含 appName/appVersion/platform/environment/userProperties） */\n  context?: Record<string, any>\n}\n\n/** 上报鉴权方式 */\nexport type SignMode = 'hmac' | 'token' | 'none'\n\n/**\n * 离线持久化适配器:存取未成功上报的事件,断网/刷新后补发。\n * core 提供 Web localStorage/sessionStorage 版;小程序端经 createTracker({ persistenceAdapter }) 注入 storage 版。\n */\nexport interface PersistenceAdapter {\n  /** 读出待发事件(读后由实现清空存储,防重复补发) */\n  load(): Promise<EventData[]>\n  /** 覆盖存储为当前未发事件全量快照 */\n  save(events: EventData[]): Promise<void>\n  /** 清空存储 */\n  clear(): Promise<void>\n}\n\n/**\n * 追踪器配置。\n * 标注「增强」的字段为 core 通用增强新增项，详见 design.md 5.2。\n */\nexport interface TrackerConfig {\n  /** 上报地址（POST 目标） */\n  reportUrl: string\n  /** 应用标识（增强，collector 鉴权用） */\n  appKey?: string\n  /** 应用名称 */\n  appName?: string\n  /** 应用版本 */\n  appVersion?: string\n  /** 平台，见 Platform */\n  platform?: string\n  /** 环境：production | staging | dev */\n  environment?: string\n  /** 批量上报条数（默认 10） */\n  batchSize?: number\n  /** 定时上报间隔，毫秒（默认 5000） */\n  flushInterval?: number\n  /** 调试模式 */\n  debug?: boolean\n  /** 自定义上报函数（小程序适配用，包 uni.request） */\n  sendFn?: (data: EventData[]) => Promise<void>\n  /** 自定义上下文 */\n  context?: Record<string, any>\n  /** 自动收集设备信息 */\n  autoCollectDeviceInfo?: boolean\n  /** 自动收集页面信息 */\n  autoCollectPageInfo?: boolean\n  // ===== 以下为通用增强字段（core 增强阶段实现消费） =====\n  /** 签名密钥（增强） */\n  appSecret?: string\n  /** 采样率 0-1（增强，按 sessionId 哈希稳定采样） */\n  sampleRate?: number\n  /** 队列上限（增强，默认 100，超限丢最旧） */\n  maxQueueSize?: number\n  /** 离线持久化方式（增强） */\n  persistence?: 'none' | 'local' | 'session' | 'mp'\n  /** 访客 ID 取值函数（增强；默认用 core 的 localStorage 版，小程序端注入 storage 版） */\n  getVisitorId?: () => string\n  /** 持久化适配器（增强；persistence='mp' 时由小程序端注入 storage 版） */\n  persistenceAdapter?: PersistenceAdapter\n  /** 鉴权方式（增强，小程序默认 none） */\n  signMode?: SignMode\n  /** 自定义脱敏函数；传 null 关闭脱敏，默认用内置 defaultSanitize */\n  sanitize?: ((event: EventData) => EventData) | null\n}\n\n/**\n * 插件接口。\n * beforeSend/afterSend 由 Tracker 装配进 EventQueue 钩子触发（见 tracker.ts）。\n */\nexport interface TrackerPlugin {\n  name: string\n  install?: (tracker: any) => void\n  beforeTrack?: (eventType: string, data?: Record<string, any>) => void | false\n  afterTrack?: (eventType: string, data?: Record<string, any>) => void\n  /** flush 前处理（过滤/脱敏/采样），返回 false 丢弃整批 */\n  beforeSend?: (events: EventData[]) => EventData[] | false\n  /** flush 成功后回调 */\n  afterSend?: (events: EventData[]) => void\n}\n\n/** 接口监控事件 data 字段结构（api_performance / api_error） */\nexport interface ApiEventData {\n  url: string\n  method: string\n  status: number\n  duration: number\n  requestBodySize?: number\n  responseBodySize?: number\n  reason?: string // api_error 时的失败原因\n}\n"],"mappings":";;;;;;;;;AAQA,MAAa,YAAY;CAEvB,iBAAiB;CACjB,cAAc;CACd,UAAU;CACV,iBAAiB;CACjB,uBAAuB;CACvB,wBAAwB;CACxB,aAAa;CACb,mBAAmB;CACnB,eAAe;CAEf,SAAS;CACT,kBAAkB;CAClB,cAAc;CACd,eAAe;CACf,cAAc;CACd,aAAa;CACb,eAAe;CACf,UAAU;CACV,eAAe;CAEf,gBAAgB;CAChB,UAAU;CAEV,UAAU;CACV,UAAU;CACV,OAAO;CACP,aAAa;CACb,kBAAkB;CAClB,cAAc;CACd,WAAW;CACX,YAAY;CACZ,aAAa;CACb,QAAQ;CACR,aAAa;CAEb,cAAc;CACd,WAAW;CACX,kBAAkB;CAClB,aAAa;CACb,eAAe;CACf,cAAc;CACd,OAAO;CACP,QAAQ;CACR,iBAAiB;CACjB,QAAQ;CACR,YAAY;CACZ,aAAa;CACb,gBAAgB;AACjB;;AAID,MAAa,WAAW;CACtB,KAAK;CACL,IAAI;CACJ,UAAU;CACV,UAAU;CACV,MAAM;CACN,OAAO;CACP,SAAS;CACT,MAAM;CACN,WAAW;CACX,YAAY;AACb"}

package/dist/index.d.cts

@@ -64,6 +64,7 @@ export interface EventData {
 	timestamp: number;
 	userId?: string | null;
 	sessionId: string;
+	visitorId?: string;
 	url?: string;
 	pathname?: string;
 	title?: string;
@@ -72,6 +73,11 @@ export interface EventData {
 	context?: Record<string, any>;
 }
 export type SignMode = "hmac" | "token" | "none";
+export interface PersistenceAdapter {
+	load(): Promise<EventData[]>;
+	save(events: EventData[]): Promise<void>;
+	clear(): Promise<void>;
+}
 export interface TrackerConfig {
 	reportUrl: string;
 	appKey?: string;
@@ -90,6 +96,8 @@ export interface TrackerConfig {
 	sampleRate?: number;
 	maxQueueSize?: number;
 	persistence?: "none" | "local" | "session" | "mp";
+	getVisitorId?: () => string;
+	persistenceAdapter?: PersistenceAdapter;
 	signMode?: SignMode;
 	sanitize?: ((event: EventData) => EventData) | null;
 }

package/dist/index.d.ts

@@ -64,6 +64,7 @@ export interface EventData {
 	timestamp: number;
 	userId?: string | null;
 	sessionId: string;
+	visitorId?: string;
 	url?: string;
 	pathname?: string;
 	title?: string;
@@ -72,6 +73,11 @@ export interface EventData {
 	context?: Record<string, any>;
 }
 export type SignMode = "hmac" | "token" | "none";
+export interface PersistenceAdapter {
+	load(): Promise<EventData[]>;
+	save(events: EventData[]): Promise<void>;
+	clear(): Promise<void>;
+}
 export interface TrackerConfig {
 	reportUrl: string;
 	appKey?: string;
@@ -90,6 +96,8 @@ export interface TrackerConfig {
 	sampleRate?: number;
 	maxQueueSize?: number;
 	persistence?: "none" | "local" | "session" | "mp";
+	getVisitorId?: () => string;
+	persistenceAdapter?: PersistenceAdapter;
 	signMode?: SignMode;
 	sanitize?: ((event: EventData) => EventData) | null;
 }

package/dist/index.js

@@ -65,7 +65,7 @@ const Platform = {
 	ToutiaoMp: "toutiao_mp",
 	KuaishouMp: "kuaishou_mp"
 };
+
 //#endregion
 export { EventType, Platform };
-
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @gctrack/protocol — 前后端共享的事件协议与类型（唯一真相源）\n *\n * SDK（packages/*）与后端（apps/collector、apps/bff）共用本文件，\n * 杜绝 EventData 等结构在前后端漂移。\n */\n\n/** 事件类型常量（见 design.md 附录 A） */\nexport const EventType = {\n  // 性能\n  PagePerformance: 'page_performance',\n  SlowResource: 'slow_resource',\n  LongTask: 'long_task',\n  FirstInputDelay: 'first_input_delay',\n  CumulativeLayoutShift: 'cumulative_layout_shift',\n  LargestContentfulPaint: 'largest_contentful_paint',\n  RouteChange: 'route_change',\n  CustomPerformance: 'custom_performance',\n  MpFirstRender: 'mp_first_render',\n  // 错误\n  JsError: 'js_error',\n  CrossOriginError: 'cross_origin_error',\n  PromiseError: 'promise_error',\n  ResourceError: 'resource_error',\n  ConsoleError: 'console_error',\n  ManualError: 'manual_error',\n  MemoryWarning: 'memory_warning',\n  VueError: 'vue_error',\n  MpScriptError: 'mp_script_error',\n  // 接口\n  ApiPerformance: 'api_performance',\n  ApiError: 'api_error',\n  // 行为\n  PageView: 'page_view',\n  PageStay: 'page_stay',\n  Click: 'click',\n  ScrollDepth: 'scroll_depth',\n  VisibilityChange: 'visibility_change',\n  UserInactive: 'user_inactive',\n  FormStart: 'form_start',\n  FormSubmit: 'form_submit',\n  FormAbandon: 'form_abandon',\n  Search: 'search',\n  VideoAction: 'video_action',\n  // 业务\n  UserRegister: 'user_register',\n  UserLogin: 'user_login',\n  SearchConversion: 'search_conversion',\n  OrderFunnel: 'order_funnel',\n  PaymentResult: 'payment_result',\n  CouponAction: 'coupon_action',\n  Share: 'share',\n  Review: 'review',\n  CustomerService: 'customer_service',\n  AbTest: 'ab_test',\n  FunnelStep: 'funnel_step',\n  FunnelLeave: 'funnel_leave',\n  FunnelComplete: 'funnel_complete',\n} as const\nexport type EventTypeValue = (typeof EventType)[keyof typeof EventType]\n\n/** 平台标识（写入 EventData.context.platform 与 ClickHouse platform 列） */\nexport const Platform = {\n  Web: 'web',\n  H5: 'h5',\n  WeixinMp: 'wx_mp',\n  AlipayMp: 'alipay_mp',\n  JdMp: 'jd_mp',\n  XhsMp: 'xhs_mp',\n  BaiduMp: 'baidu_mp',\n  QqMp: 'qq_mp',\n  ToutiaoMp: 'toutiao_mp',\n  KuaishouMp: 'kuaishou_mp',\n} as const\nexport type PlatformValue = (typeof Platform)[keyof typeof Platform]\n\n/**\n * 事件数据 —— 一条监控记录的统一结构。\n * 后端 ClickHouse monitor_event 表、SDK 上报 body 均以此为准。\n */\nexport interface EventData {\n  /** 事件类型，取 EventType 常量或业务自定义字符串 */\n  eventType: string\n  /** 事件 payload（错误堆栈 / 性能指标 / 接口信息等），自由结构 */\n  data?: Record<string, any>\n  /** 事件发生时间（毫秒） */\n  timestamp: number\n  /** 用户 ID（可能为空） */\n  userId?: string | null\n  /** 会话 ID */\n  sessionId: string\n  /** 页面 URL */\n  url?: string\n  /** 页面路径 */\n  pathname?: string\n  /** 页面标题 */\n  title?: string\n  /** 来源 URL */\n  referrer?: string\n  /** User-Agent（小程序端拼装） */\n  userAgent?: string\n  /** 自定义上下文（含 appName/appVersion/platform/environment/userProperties） */\n  context?: Record<string, any>\n}\n\n/** 上报鉴权方式 */\nexport type SignMode = 'hmac' | 'token' | 'none'\n\n/**\n * 追踪器配置。\n * 标注「增强」的字段为 core 通用增强新增项，详见 design.md 5.2。\n */\nexport interface TrackerConfig {\n  /** 上报地址（POST 目标） */\n  reportUrl: string\n  /** 应用标识（增强，collector 鉴权用） */\n  appKey?: string\n  /** 应用名称 */\n  appName?: string\n  /** 应用版本 */\n  appVersion?: string\n  /** 平台，见 Platform */\n  platform?: string\n  /** 环境：production | staging | dev */\n  environment?: string\n  /** 批量上报条数（默认 10） */\n  batchSize?: number\n  /** 定时上报间隔，毫秒（默认 5000） */\n  flushInterval?: number\n  /** 调试模式 */\n  debug?: boolean\n  /** 自定义上报函数（小程序适配用，包 uni.request） */\n  sendFn?: (data: EventData[]) => Promise<void>\n  /** 自定义上下文 */\n  context?: Record<string, any>\n  /** 自动收集设备信息 */\n  autoCollectDeviceInfo?: boolean\n  /** 自动收集页面信息 */\n  autoCollectPageInfo?: boolean\n  // ===== 以下为通用增强字段（core 增强阶段实现消费） =====\n  /** 签名密钥（增强） */\n  appSecret?: string\n  /** 采样率 0-1（增强，按 sessionId 哈希稳定采样） */\n  sampleRate?: number\n  /** 队列上限（增强，默认 100，超限丢最旧） */\n  maxQueueSize?: number\n  /** 离线持久化方式（增强） */\n  persistence?: 'none' | 'local' | 'session' | 'mp'\n  /** 鉴权方式（增强，小程序默认 none） */\n  signMode?: SignMode\n  /** 自定义脱敏函数；传 null 关闭脱敏，默认用内置 defaultSanitize */\n  sanitize?: ((event: EventData) => EventData) | null\n}\n\n/**\n * 插件接口。\n * 注意：beforeSend/afterSend 当前 core 未触发，core 增强阶段补齐。\n */\nexport interface TrackerPlugin {\n  name: string\n  install?: (tracker: any) => void\n  beforeTrack?: (eventType: string, data?: Record<string, any>) => void | false\n  afterTrack?: (eventType: string, data?: Record<string, any>) => void\n  /** flush 前处理（过滤/脱敏/采样），返回 false 丢弃整批 */\n  beforeSend?: (events: EventData[]) => EventData[] | false\n  /** flush 成功后回调 */\n  afterSend?: (events: EventData[]) => void\n}\n\n/** 接口监控事件 data 字段结构（api_performance / api_error） */\nexport interface ApiEventData {\n  url: string\n  method: string\n  status: number\n  duration: number\n  requestBodySize?: number\n  responseBodySize?: number\n  reason?: string // api_error 时的失败原因\n}\n"],"mappings":";;;;;;;;AAQA,MAAa,YAAY;CAEvB,iBAAiB;CACjB,cAAc;CACd,UAAU;CACV,iBAAiB;CACjB,uBAAuB;CACvB,wBAAwB;CACxB,aAAa;CACb,mBAAmB;CACnB,eAAe;CAEf,SAAS;CACT,kBAAkB;CAClB,cAAc;CACd,eAAe;CACf,cAAc;CACd,aAAa;CACb,eAAe;CACf,UAAU;CACV,eAAe;CAEf,gBAAgB;CAChB,UAAU;CAEV,UAAU;CACV,UAAU;CACV,OAAO;CACP,aAAa;CACb,kBAAkB;CAClB,cAAc;CACd,WAAW;CACX,YAAY;CACZ,aAAa;CACb,QAAQ;CACR,aAAa;CAEb,cAAc;CACd,WAAW;CACX,kBAAkB;CAClB,aAAa;CACb,eAAe;CACf,cAAc;CACd,OAAO;CACP,QAAQ;CACR,iBAAiB;CACjB,QAAQ;CACR,YAAY;CACZ,aAAa;CACb,gBAAgB;CACjB;;AAID,MAAa,WAAW;CACtB,KAAK;CACL,IAAI;CACJ,UAAU;CACV,UAAU;CACV,MAAM;CACN,OAAO;CACP,SAAS;CACT,MAAM;CACN,WAAW;CACX,YAAY;CACb"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @gctrack/protocol — 前后端共享的事件协议与类型（唯一真相源）\n *\n * SDK（packages/*）与后端（apps/collector、apps/bff）共用本文件，\n * 杜绝 EventData 等结构在前后端漂移。\n */\n\n/** 事件类型常量（见 design.md 附录 A） */\nexport const EventType = {\n  // 性能\n  PagePerformance: 'page_performance',\n  SlowResource: 'slow_resource',\n  LongTask: 'long_task',\n  FirstInputDelay: 'first_input_delay',\n  CumulativeLayoutShift: 'cumulative_layout_shift',\n  LargestContentfulPaint: 'largest_contentful_paint',\n  RouteChange: 'route_change',\n  CustomPerformance: 'custom_performance',\n  MpFirstRender: 'mp_first_render',\n  // 错误\n  JsError: 'js_error',\n  CrossOriginError: 'cross_origin_error',\n  PromiseError: 'promise_error',\n  ResourceError: 'resource_error',\n  ConsoleError: 'console_error',\n  ManualError: 'manual_error',\n  MemoryWarning: 'memory_warning',\n  VueError: 'vue_error',\n  MpScriptError: 'mp_script_error',\n  // 接口\n  ApiPerformance: 'api_performance',\n  ApiError: 'api_error',\n  // 行为\n  PageView: 'page_view',\n  PageStay: 'page_stay',\n  Click: 'click',\n  ScrollDepth: 'scroll_depth',\n  VisibilityChange: 'visibility_change',\n  UserInactive: 'user_inactive',\n  FormStart: 'form_start',\n  FormSubmit: 'form_submit',\n  FormAbandon: 'form_abandon',\n  Search: 'search',\n  VideoAction: 'video_action',\n  // 业务\n  UserRegister: 'user_register',\n  UserLogin: 'user_login',\n  SearchConversion: 'search_conversion',\n  OrderFunnel: 'order_funnel',\n  PaymentResult: 'payment_result',\n  CouponAction: 'coupon_action',\n  Share: 'share',\n  Review: 'review',\n  CustomerService: 'customer_service',\n  AbTest: 'ab_test',\n  FunnelStep: 'funnel_step',\n  FunnelLeave: 'funnel_leave',\n  FunnelComplete: 'funnel_complete',\n} as const\nexport type EventTypeValue = (typeof EventType)[keyof typeof EventType]\n\n/** 平台标识（写入 EventData.context.platform 与 ClickHouse platform 列） */\nexport const Platform = {\n  Web: 'web',\n  H5: 'h5',\n  WeixinMp: 'wx_mp',\n  AlipayMp: 'alipay_mp',\n  JdMp: 'jd_mp',\n  XhsMp: 'xhs_mp',\n  BaiduMp: 'baidu_mp',\n  QqMp: 'qq_mp',\n  ToutiaoMp: 'toutiao_mp',\n  KuaishouMp: 'kuaishou_mp',\n} as const\nexport type PlatformValue = (typeof Platform)[keyof typeof Platform]\n\n/**\n * 事件数据 —— 一条监控记录的统一结构。\n * 后端 ClickHouse monitor_event 表、SDK 上报 body 均以此为准。\n */\nexport interface EventData {\n  /** 事件类型，取 EventType 常量或业务自定义字符串 */\n  eventType: string\n  /** 事件 payload（错误堆栈 / 性能指标 / 接口信息等），自由结构 */\n  data?: Record<string, any>\n  /** 事件发生时间（毫秒） */\n  timestamp: number\n  /** 用户 ID（可能为空） */\n  userId?: string | null\n  /** 会话 ID */\n  sessionId: string\n  /** 匿名访客 ID（跨会话稳定，UV 去重依据；非 PII，可配置关闭） */\n  visitorId?: string\n  /** 页面 URL */\n  url?: string\n  /** 页面路径 */\n  pathname?: string\n  /** 页面标题 */\n  title?: string\n  /** 来源 URL */\n  referrer?: string\n  /** User-Agent（小程序端拼装） */\n  userAgent?: string\n  /** 自定义上下文（含 appName/appVersion/platform/environment/userProperties） */\n  context?: Record<string, any>\n}\n\n/** 上报鉴权方式 */\nexport type SignMode = 'hmac' | 'token' | 'none'\n\n/**\n * 离线持久化适配器:存取未成功上报的事件,断网/刷新后补发。\n * core 提供 Web localStorage/sessionStorage 版;小程序端经 createTracker({ persistenceAdapter }) 注入 storage 版。\n */\nexport interface PersistenceAdapter {\n  /** 读出待发事件(读后由实现清空存储,防重复补发) */\n  load(): Promise<EventData[]>\n  /** 覆盖存储为当前未发事件全量快照 */\n  save(events: EventData[]): Promise<void>\n  /** 清空存储 */\n  clear(): Promise<void>\n}\n\n/**\n * 追踪器配置。\n * 标注「增强」的字段为 core 通用增强新增项，详见 design.md 5.2。\n */\nexport interface TrackerConfig {\n  /** 上报地址（POST 目标） */\n  reportUrl: string\n  /** 应用标识（增强，collector 鉴权用） */\n  appKey?: string\n  /** 应用名称 */\n  appName?: string\n  /** 应用版本 */\n  appVersion?: string\n  /** 平台，见 Platform */\n  platform?: string\n  /** 环境：production | staging | dev */\n  environment?: string\n  /** 批量上报条数（默认 10） */\n  batchSize?: number\n  /** 定时上报间隔，毫秒（默认 5000） */\n  flushInterval?: number\n  /** 调试模式 */\n  debug?: boolean\n  /** 自定义上报函数（小程序适配用，包 uni.request） */\n  sendFn?: (data: EventData[]) => Promise<void>\n  /** 自定义上下文 */\n  context?: Record<string, any>\n  /** 自动收集设备信息 */\n  autoCollectDeviceInfo?: boolean\n  /** 自动收集页面信息 */\n  autoCollectPageInfo?: boolean\n  // ===== 以下为通用增强字段（core 增强阶段实现消费） =====\n  /** 签名密钥（增强） */\n  appSecret?: string\n  /** 采样率 0-1（增强，按 sessionId 哈希稳定采样） */\n  sampleRate?: number\n  /** 队列上限（增强，默认 100，超限丢最旧） */\n  maxQueueSize?: number\n  /** 离线持久化方式（增强） */\n  persistence?: 'none' | 'local' | 'session' | 'mp'\n  /** 访客 ID 取值函数（增强；默认用 core 的 localStorage 版，小程序端注入 storage 版） */\n  getVisitorId?: () => string\n  /** 持久化适配器（增强；persistence='mp' 时由小程序端注入 storage 版） */\n  persistenceAdapter?: PersistenceAdapter\n  /** 鉴权方式（增强，小程序默认 none） */\n  signMode?: SignMode\n  /** 自定义脱敏函数；传 null 关闭脱敏，默认用内置 defaultSanitize */\n  sanitize?: ((event: EventData) => EventData) | null\n}\n\n/**\n * 插件接口。\n * beforeSend/afterSend 由 Tracker 装配进 EventQueue 钩子触发（见 tracker.ts）。\n */\nexport interface TrackerPlugin {\n  name: string\n  install?: (tracker: any) => void\n  beforeTrack?: (eventType: string, data?: Record<string, any>) => void | false\n  afterTrack?: (eventType: string, data?: Record<string, any>) => void\n  /** flush 前处理（过滤/脱敏/采样），返回 false 丢弃整批 */\n  beforeSend?: (events: EventData[]) => EventData[] | false\n  /** flush 成功后回调 */\n  afterSend?: (events: EventData[]) => void\n}\n\n/** 接口监控事件 data 字段结构（api_performance / api_error） */\nexport interface ApiEventData {\n  url: string\n  method: string\n  status: number\n  duration: number\n  requestBodySize?: number\n  responseBodySize?: number\n  reason?: string // api_error 时的失败原因\n}\n"],"mappings":";;;;;;;;AAQA,MAAa,YAAY;CAEvB,iBAAiB;CACjB,cAAc;CACd,UAAU;CACV,iBAAiB;CACjB,uBAAuB;CACvB,wBAAwB;CACxB,aAAa;CACb,mBAAmB;CACnB,eAAe;CAEf,SAAS;CACT,kBAAkB;CAClB,cAAc;CACd,eAAe;CACf,cAAc;CACd,aAAa;CACb,eAAe;CACf,UAAU;CACV,eAAe;CAEf,gBAAgB;CAChB,UAAU;CAEV,UAAU;CACV,UAAU;CACV,OAAO;CACP,aAAa;CACb,kBAAkB;CAClB,cAAc;CACd,WAAW;CACX,YAAY;CACZ,aAAa;CACb,QAAQ;CACR,aAAa;CAEb,cAAc;CACd,WAAW;CACX,kBAAkB;CAClB,aAAa;CACb,eAAe;CACf,cAAc;CACd,OAAO;CACP,QAAQ;CACR,iBAAiB;CACjB,QAAQ;CACR,YAAY;CACZ,aAAa;CACb,gBAAgB;AACjB;;AAID,MAAa,WAAW;CACtB,KAAK;CACL,IAAI;CACJ,UAAU;CACV,UAAU;CACV,MAAM;CACN,OAAO;CACP,SAAS;CACT,MAAM;CACN,WAAW;CACX,YAAY;AACb"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gctrack/protocol",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "前后端共享的事件协议与类型定义（唯一真相源）",
   "type": "module",
   "main": "./dist/index.cjs",