@gctrack/protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yinuo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @gctrack/protocol
+
+前后端共享的事件协议与 TypeScript 类型 —— `@gctrack` 全家桶的**唯一真相源**。
+
+导出 `EventData`、`TrackerConfig`、`TrackerPlugin`、`ApiEventData` 以及 `EventType` / `Platform` 事件与平台常量。SDK 与 collector / bff 共用，杜绝协议漂移。
+
+## 安装
+
+```bash
+npm i @gctrack/protocol
+```
+
+## 用法
+
+```ts
+import { EventType, Platform, type EventData } from '@gctrack/protocol'
+
+tracker.track(EventType.JsError, { message: 'boom', stack: '...' })
+
+// context.platform 取 Platform 常量
+const platform: string = Platform.Web
+```
+
+## License
+
+MIT (c) yinuo

package/dist/index.cjs

@@ -0,0 +1,73 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/index.ts
+/**
+* @gctrack/protocol — 前后端共享的事件协议与类型（唯一真相源）
+*
+* SDK（packages/*）与后端（apps/collector、apps/bff）共用本文件，
+* 杜绝 EventData 等结构在前后端漂移。
+*/
+/** 事件类型常量（见 design.md 附录 A） */
+const EventType = {
+	PagePerformance: "page_performance",
+	SlowResource: "slow_resource",
+	LongTask: "long_task",
+	FirstInputDelay: "first_input_delay",
+	CumulativeLayoutShift: "cumulative_layout_shift",
+	LargestContentfulPaint: "largest_contentful_paint",
+	RouteChange: "route_change",
+	CustomPerformance: "custom_performance",
+	MpFirstRender: "mp_first_render",
+	JsError: "js_error",
+	CrossOriginError: "cross_origin_error",
+	PromiseError: "promise_error",
+	ResourceError: "resource_error",
+	ConsoleError: "console_error",
+	ManualError: "manual_error",
+	MemoryWarning: "memory_warning",
+	VueError: "vue_error",
+	MpScriptError: "mp_script_error",
+	ApiPerformance: "api_performance",
+	ApiError: "api_error",
+	PageView: "page_view",
+	PageStay: "page_stay",
+	Click: "click",
+	ScrollDepth: "scroll_depth",
+	VisibilityChange: "visibility_change",
+	UserInactive: "user_inactive",
+	FormStart: "form_start",
+	FormSubmit: "form_submit",
+	FormAbandon: "form_abandon",
+	Search: "search",
+	VideoAction: "video_action",
+	UserRegister: "user_register",
+	UserLogin: "user_login",
+	SearchConversion: "search_conversion",
+	OrderFunnel: "order_funnel",
+	PaymentResult: "payment_result",
+	CouponAction: "coupon_action",
+	Share: "share",
+	Review: "review",
+	CustomerService: "customer_service",
+	AbTest: "ab_test",
+	FunnelStep: "funnel_step",
+	FunnelLeave: "funnel_leave",
+	FunnelComplete: "funnel_complete"
+};
+/** 平台标识（写入 EventData.context.platform 与 ClickHouse platform 列） */
+const Platform = {
+	Web: "web",
+	H5: "h5",
+	WeixinMp: "wx_mp",
+	AlipayMp: "alipay_mp",
+	JdMp: "jd_mp",
+	XhsMp: "xhs_mp",
+	BaiduMp: "baidu_mp",
+	QqMp: "qq_mp",
+	ToutiaoMp: "toutiao_mp",
+	KuaishouMp: "kuaishou_mp"
+};
+//#endregion
+exports.EventType = EventType;
+exports.Platform = Platform;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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"}

package/dist/index.d.cts

@@ -0,0 +1,112 @@
+export declare const EventType: {
+	readonly PagePerformance: "page_performance";
+	readonly SlowResource: "slow_resource";
+	readonly LongTask: "long_task";
+	readonly FirstInputDelay: "first_input_delay";
+	readonly CumulativeLayoutShift: "cumulative_layout_shift";
+	readonly LargestContentfulPaint: "largest_contentful_paint";
+	readonly RouteChange: "route_change";
+	readonly CustomPerformance: "custom_performance";
+	readonly MpFirstRender: "mp_first_render";
+	readonly JsError: "js_error";
+	readonly CrossOriginError: "cross_origin_error";
+	readonly PromiseError: "promise_error";
+	readonly ResourceError: "resource_error";
+	readonly ConsoleError: "console_error";
+	readonly ManualError: "manual_error";
+	readonly MemoryWarning: "memory_warning";
+	readonly VueError: "vue_error";
+	readonly MpScriptError: "mp_script_error";
+	readonly ApiPerformance: "api_performance";
+	readonly ApiError: "api_error";
+	readonly PageView: "page_view";
+	readonly PageStay: "page_stay";
+	readonly Click: "click";
+	readonly ScrollDepth: "scroll_depth";
+	readonly VisibilityChange: "visibility_change";
+	readonly UserInactive: "user_inactive";
+	readonly FormStart: "form_start";
+	readonly FormSubmit: "form_submit";
+	readonly FormAbandon: "form_abandon";
+	readonly Search: "search";
+	readonly VideoAction: "video_action";
+	readonly UserRegister: "user_register";
+	readonly UserLogin: "user_login";
+	readonly SearchConversion: "search_conversion";
+	readonly OrderFunnel: "order_funnel";
+	readonly PaymentResult: "payment_result";
+	readonly CouponAction: "coupon_action";
+	readonly Share: "share";
+	readonly Review: "review";
+	readonly CustomerService: "customer_service";
+	readonly AbTest: "ab_test";
+	readonly FunnelStep: "funnel_step";
+	readonly FunnelLeave: "funnel_leave";
+	readonly FunnelComplete: "funnel_complete";
+};
+export type EventTypeValue = (typeof EventType)[keyof typeof EventType];
+export declare const Platform: {
+	readonly Web: "web";
+	readonly H5: "h5";
+	readonly WeixinMp: "wx_mp";
+	readonly AlipayMp: "alipay_mp";
+	readonly JdMp: "jd_mp";
+	readonly XhsMp: "xhs_mp";
+	readonly BaiduMp: "baidu_mp";
+	readonly QqMp: "qq_mp";
+	readonly ToutiaoMp: "toutiao_mp";
+	readonly KuaishouMp: "kuaishou_mp";
+};
+export type PlatformValue = (typeof Platform)[keyof typeof Platform];
+export interface EventData {
+	eventType: string;
+	data?: Record<string, any>;
+	timestamp: number;
+	userId?: string | null;
+	sessionId: string;
+	url?: string;
+	pathname?: string;
+	title?: string;
+	referrer?: string;
+	userAgent?: string;
+	context?: Record<string, any>;
+}
+export type SignMode = "hmac" | "token" | "none";
+export interface TrackerConfig {
+	reportUrl: string;
+	appKey?: string;
+	appName?: string;
+	appVersion?: string;
+	platform?: string;
+	environment?: string;
+	batchSize?: number;
+	flushInterval?: number;
+	debug?: boolean;
+	sendFn?: (data: EventData[]) => Promise<void>;
+	context?: Record<string, any>;
+	autoCollectDeviceInfo?: boolean;
+	autoCollectPageInfo?: boolean;
+	appSecret?: string;
+	sampleRate?: number;
+	maxQueueSize?: number;
+	persistence?: "none" | "local" | "session" | "mp";
+	signMode?: SignMode;
+	sanitize?: ((event: EventData) => EventData) | null;
+}
+export interface TrackerPlugin {
+	name: string;
+	install?: (tracker: any) => void;
+	beforeTrack?: (eventType: string, data?: Record<string, any>) => void | false;
+	afterTrack?: (eventType: string, data?: Record<string, any>) => void;
+	beforeSend?: (events: EventData[]) => EventData[] | false;
+	afterSend?: (events: EventData[]) => void;
+}
+export interface ApiEventData {
+	url: string;
+	method: string;
+	status: number;
+	duration: number;
+	requestBodySize?: number;
+	responseBodySize?: number;
+	reason?: string;
+}

package/dist/index.d.ts

@@ -0,0 +1,112 @@
+export declare const EventType: {
+	readonly PagePerformance: "page_performance";
+	readonly SlowResource: "slow_resource";
+	readonly LongTask: "long_task";
+	readonly FirstInputDelay: "first_input_delay";
+	readonly CumulativeLayoutShift: "cumulative_layout_shift";
+	readonly LargestContentfulPaint: "largest_contentful_paint";
+	readonly RouteChange: "route_change";
+	readonly CustomPerformance: "custom_performance";
+	readonly MpFirstRender: "mp_first_render";
+	readonly JsError: "js_error";
+	readonly CrossOriginError: "cross_origin_error";
+	readonly PromiseError: "promise_error";
+	readonly ResourceError: "resource_error";
+	readonly ConsoleError: "console_error";
+	readonly ManualError: "manual_error";
+	readonly MemoryWarning: "memory_warning";
+	readonly VueError: "vue_error";
+	readonly MpScriptError: "mp_script_error";
+	readonly ApiPerformance: "api_performance";
+	readonly ApiError: "api_error";
+	readonly PageView: "page_view";
+	readonly PageStay: "page_stay";
+	readonly Click: "click";
+	readonly ScrollDepth: "scroll_depth";
+	readonly VisibilityChange: "visibility_change";
+	readonly UserInactive: "user_inactive";
+	readonly FormStart: "form_start";
+	readonly FormSubmit: "form_submit";
+	readonly FormAbandon: "form_abandon";
+	readonly Search: "search";
+	readonly VideoAction: "video_action";
+	readonly UserRegister: "user_register";
+	readonly UserLogin: "user_login";
+	readonly SearchConversion: "search_conversion";
+	readonly OrderFunnel: "order_funnel";
+	readonly PaymentResult: "payment_result";
+	readonly CouponAction: "coupon_action";
+	readonly Share: "share";
+	readonly Review: "review";
+	readonly CustomerService: "customer_service";
+	readonly AbTest: "ab_test";
+	readonly FunnelStep: "funnel_step";
+	readonly FunnelLeave: "funnel_leave";
+	readonly FunnelComplete: "funnel_complete";
+};
+export type EventTypeValue = (typeof EventType)[keyof typeof EventType];
+export declare const Platform: {
+	readonly Web: "web";
+	readonly H5: "h5";
+	readonly WeixinMp: "wx_mp";
+	readonly AlipayMp: "alipay_mp";
+	readonly JdMp: "jd_mp";
+	readonly XhsMp: "xhs_mp";
+	readonly BaiduMp: "baidu_mp";
+	readonly QqMp: "qq_mp";
+	readonly ToutiaoMp: "toutiao_mp";
+	readonly KuaishouMp: "kuaishou_mp";
+};
+export type PlatformValue = (typeof Platform)[keyof typeof Platform];
+export interface EventData {
+	eventType: string;
+	data?: Record<string, any>;
+	timestamp: number;
+	userId?: string | null;
+	sessionId: string;
+	url?: string;
+	pathname?: string;
+	title?: string;
+	referrer?: string;
+	userAgent?: string;
+	context?: Record<string, any>;
+}
+export type SignMode = "hmac" | "token" | "none";
+export interface TrackerConfig {
+	reportUrl: string;
+	appKey?: string;
+	appName?: string;
+	appVersion?: string;
+	platform?: string;
+	environment?: string;
+	batchSize?: number;
+	flushInterval?: number;
+	debug?: boolean;
+	sendFn?: (data: EventData[]) => Promise<void>;
+	context?: Record<string, any>;
+	autoCollectDeviceInfo?: boolean;
+	autoCollectPageInfo?: boolean;
+	appSecret?: string;
+	sampleRate?: number;
+	maxQueueSize?: number;
+	persistence?: "none" | "local" | "session" | "mp";
+	signMode?: SignMode;
+	sanitize?: ((event: EventData) => EventData) | null;
+}
+export interface TrackerPlugin {
+	name: string;
+	install?: (tracker: any) => void;
+	beforeTrack?: (eventType: string, data?: Record<string, any>) => void | false;
+	afterTrack?: (eventType: string, data?: Record<string, any>) => void;
+	beforeSend?: (events: EventData[]) => EventData[] | false;
+	afterSend?: (events: EventData[]) => void;
+}
+export interface ApiEventData {
+	url: string;
+	method: string;
+	status: number;
+	duration: number;
+	requestBodySize?: number;
+	responseBodySize?: number;
+	reason?: string;
+}

package/dist/index.js

@@ -0,0 +1,72 @@
+import "node:module";
+//#region src/index.ts
+/**
+* @gctrack/protocol — 前后端共享的事件协议与类型（唯一真相源）
+*
+* SDK（packages/*）与后端（apps/collector、apps/bff）共用本文件，
+* 杜绝 EventData 等结构在前后端漂移。
+*/
+/** 事件类型常量（见 design.md 附录 A） */
+const EventType = {
+	PagePerformance: "page_performance",
+	SlowResource: "slow_resource",
+	LongTask: "long_task",
+	FirstInputDelay: "first_input_delay",
+	CumulativeLayoutShift: "cumulative_layout_shift",
+	LargestContentfulPaint: "largest_contentful_paint",
+	RouteChange: "route_change",
+	CustomPerformance: "custom_performance",
+	MpFirstRender: "mp_first_render",
+	JsError: "js_error",
+	CrossOriginError: "cross_origin_error",
+	PromiseError: "promise_error",
+	ResourceError: "resource_error",
+	ConsoleError: "console_error",
+	ManualError: "manual_error",
+	MemoryWarning: "memory_warning",
+	VueError: "vue_error",
+	MpScriptError: "mp_script_error",
+	ApiPerformance: "api_performance",
+	ApiError: "api_error",
+	PageView: "page_view",
+	PageStay: "page_stay",
+	Click: "click",
+	ScrollDepth: "scroll_depth",
+	VisibilityChange: "visibility_change",
+	UserInactive: "user_inactive",
+	FormStart: "form_start",
+	FormSubmit: "form_submit",
+	FormAbandon: "form_abandon",
+	Search: "search",
+	VideoAction: "video_action",
+	UserRegister: "user_register",
+	UserLogin: "user_login",
+	SearchConversion: "search_conversion",
+	OrderFunnel: "order_funnel",
+	PaymentResult: "payment_result",
+	CouponAction: "coupon_action",
+	Share: "share",
+	Review: "review",
+	CustomerService: "customer_service",
+	AbTest: "ab_test",
+	FunnelStep: "funnel_step",
+	FunnelLeave: "funnel_leave",
+	FunnelComplete: "funnel_complete"
+};
+/** 平台标识（写入 EventData.context.platform 与 ClickHouse platform 列） */
+const Platform = {
+	Web: "web",
+	H5: "h5",
+	WeixinMp: "wx_mp",
+	AlipayMp: "alipay_mp",
+	JdMp: "jd_mp",
+	XhsMp: "xhs_mp",
+	BaiduMp: "baidu_mp",
+	QqMp: "qq_mp",
+	ToutiaoMp: "toutiao_mp",
+	KuaishouMp: "kuaishou_mp"
+};
+//#endregion
+export { EventType, Platform };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@gctrack/protocol",
+  "version": "0.1.0",
+  "description": "前后端共享的事件协议与类型定义（唯一真相源）",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "yinuo",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch"
+  }
+}