@aigc-kino/logger-sdk 1.3.0

package/dist/index.d.cts

@@ -0,0 +1,194 @@
+/**
+ * SDK 自带的类型与枚举定义，发布为独立 npm 包后无需额外安装其他依赖即可获得完整类型。
+ *
+ * ⚠️ 维护约定：LogType 枚举的字符串值必须与日志网关 / 服务端的约定保持一致，
+ * 修改此处枚举值需同步通知后端，避免日志 type 字段无法被正确归类。
+ */
+/** 日志类型枚举（运行时值，JSON 上报时序列化为对应字符串） */
+declare enum LogType {
+    JsError = "js-error",
+    PromiseError = "promise-error",
+    VueError = "vue-error",
+    Network = "network",
+    Resource = "resource",
+    Performance = "performance",
+    Behavior = "behavior",
+    Page = "page",
+    Business = "business",
+    Console = "console",
+    Custom = "custom"
+}
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** 微前端上下文信息（自动采集，标识当前所处的微前端应用） */
+interface MicroFrontendInfo {
+    hostApp?: string;
+    microApp?: string;
+    route?: string;
+    container?: string;
+}
+/** 上报到网关的单条日志结构 */
+interface LogEvent extends MicroFrontendInfo {
+    projectId: string;
+    projectName?: string;
+    env: string;
+    version: string;
+    type: LogType;
+    level: LogLevel;
+    message: string;
+    stack?: string;
+    url: string;
+    userId?: string;
+    sessionId: string;
+    traceId: string;
+    browser?: string;
+    device?: string;
+    network?: string;
+    timestamp: number;
+    extra?: Record<string, unknown>;
+}
+/** 后台「SDK 配置中心」下发的动态配置结构 */
+interface SdkConfig {
+    sampleRate: number;
+    ignoreErrors: string[];
+    uploadInterval: number;
+    batchSize: number;
+    enablePerformance: boolean;
+    enableBehavior: boolean;
+}
+
+/** SDK 上报的用户资料补丁，未提供字段由服务端保留，null 用于显式清除。 */
+interface UserProfileInput {
+    nickname?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    avatar?: string | null;
+    custom?: Record<string, unknown> | null;
+}
+interface LoggerOptions {
+    projectId: string;
+    token: string;
+    serverUrl: string;
+    env?: string;
+    version?: string;
+    userId?: string;
+    enableError?: boolean;
+    enablePerformance?: boolean;
+    enableBehavior?: boolean;
+    enableNetwork?: boolean;
+    enableConsole?: boolean;
+    sampleRate?: number;
+    batchSize?: number;
+    uploadInterval?: number;
+    maxRetry?: number;
+    ignoreErrors?: (string | RegExp)[];
+    ignoreUrls?: (string | RegExp)[];
+    microFrontend?: MicroFrontendInfo;
+    remoteConfig?: boolean;
+    debug?: boolean;
+    beforeSend?: (log: LogEvent) => LogEvent | false;
+}
+type ResolvedOptions = Required<Omit<LoggerOptions, 'userId' | 'microFrontend' | 'beforeSend'>> & {
+    userId?: string;
+    microFrontend?: MicroFrontendInfo;
+    beforeSend?: (log: LogEvent) => LogEvent | false;
+};
+interface RawLog {
+    type: LogType;
+    level: LogLevel;
+    message: string;
+    stack?: string;
+    extra?: Record<string, unknown>;
+}
+
+declare class Logger {
+    readonly options: ResolvedOptions;
+    readonly sessionId: string;
+    readonly traceId: string;
+    private transport;
+    private tags;
+    private cleanups;
+    private destroyed;
+    constructor(options: LoggerOptions);
+    isUploadUrl(url: string): boolean;
+    shouldIgnoreUrl(url: string): boolean;
+    setUser(userId: string, profile?: UserProfileInput): void;
+    /** 退出登录时调用，解除当前用户关联，后续日志不再携带 userId */
+    clearUser(): void;
+    setTag(key: string, value: unknown): void;
+    report(raw: RawLog): void;
+    track(event: string, data?: Record<string, unknown>): void;
+    captureError(error: unknown, extra?: Record<string, unknown>): void;
+    captureMessage(message: string, level?: 'info' | 'warn' | 'error'): void;
+    flush(): Promise<void>;
+    addCleanup(fn: () => void): void;
+    destroy(): void;
+    private resolveSessionId;
+    private resolveTraceId;
+    private pullRemoteConfig;
+    /** 上报用户资料；与日志队列隔离，避免资料重试或持久化到 IndexedDB。 */
+    private uploadUserProfile;
+}
+
+interface AxiosLike {
+    interceptors: {
+        request: {
+            use: (fn: (c: AxiosConfigLike) => AxiosConfigLike) => void;
+        };
+        response: {
+            use: (onOk: (r: AxiosResponseLike) => AxiosResponseLike, onErr: (e: AxiosErrorLike) => Promise<never>) => void;
+        };
+    };
+}
+interface AxiosConfigLike {
+    url?: string;
+    method?: string;
+    metadata?: {
+        start: number;
+        requestBody?: string;
+    };
+    data?: unknown;
+}
+interface AxiosResponseLike {
+    status: number;
+    config: AxiosConfigLike;
+}
+interface AxiosErrorLike {
+    message: string;
+    config?: AxiosConfigLike;
+    response?: {
+        status: number;
+    };
+}
+declare function attachAxiosTo(logger: Logger, axios: AxiosLike): void;
+
+/**
+ * 页面地址脱敏：仅掩码敏感查询参数的值，保留非敏感 query 与 hash 路由信息。
+ *
+ * 为什么不全量剥离 query/hash：业务页面的路由参数（如详情页 id、tab）是排查问题的
+ * 关键上下文，全量剥离会导致日志中的页面地址不完整、无法定位页面。
+ * 兼容 hash 内携带查询参数的路由形式（如 #/detail?token=xx）。
+ *
+ * @param url 待脱敏的页面地址（支持相对地址）
+ * @returns 脱敏后的地址；解析失败时原样返回，保证不影响上报
+ */
+declare function scrubUrl(url: string): string;
+
+declare function init(options: LoggerOptions): Logger;
+declare function setUser(userId: string, profile?: UserProfileInput): void;
+/** 退出登录时调用，解除当前用户关联 */
+declare function clearUser(): void;
+declare function setTag(key: string, value: unknown): void;
+declare function track(event: string, data?: Record<string, unknown>): void;
+declare function captureError(error: unknown, extra?: Record<string, unknown>): void;
+declare function captureMessage(message: string, level?: 'info' | 'warn' | 'error'): void;
+declare function getSessionId(): string;
+declare function getTraceId(): string;
+declare function flush(): Promise<void>;
+declare function destroy(): void;
+declare function attachAxios(axios: Parameters<typeof attachAxiosTo>[1]): void;
+
+declare const VuePlugin: {
+    install(app: any): void;
+};
+
+export { type LogEvent, LogType, Logger, type LoggerOptions, type SdkConfig, type UserProfileInput, VuePlugin, attachAxios, captureError, captureMessage, clearUser, destroy, flush, getSessionId, getTraceId, init, scrubUrl, setTag, setUser, track };

package/dist/index.d.ts

@@ -0,0 +1,194 @@
+/**
+ * SDK 自带的类型与枚举定义，发布为独立 npm 包后无需额外安装其他依赖即可获得完整类型。
+ *
+ * ⚠️ 维护约定：LogType 枚举的字符串值必须与日志网关 / 服务端的约定保持一致，
+ * 修改此处枚举值需同步通知后端，避免日志 type 字段无法被正确归类。
+ */
+/** 日志类型枚举（运行时值，JSON 上报时序列化为对应字符串） */
+declare enum LogType {
+    JsError = "js-error",
+    PromiseError = "promise-error",
+    VueError = "vue-error",
+    Network = "network",
+    Resource = "resource",
+    Performance = "performance",
+    Behavior = "behavior",
+    Page = "page",
+    Business = "business",
+    Console = "console",
+    Custom = "custom"
+}
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** 微前端上下文信息（自动采集，标识当前所处的微前端应用） */
+interface MicroFrontendInfo {
+    hostApp?: string;
+    microApp?: string;
+    route?: string;
+    container?: string;
+}
+/** 上报到网关的单条日志结构 */
+interface LogEvent extends MicroFrontendInfo {
+    projectId: string;
+    projectName?: string;
+    env: string;
+    version: string;
+    type: LogType;
+    level: LogLevel;
+    message: string;
+    stack?: string;
+    url: string;
+    userId?: string;
+    sessionId: string;
+    traceId: string;
+    browser?: string;
+    device?: string;
+    network?: string;
+    timestamp: number;
+    extra?: Record<string, unknown>;
+}
+/** 后台「SDK 配置中心」下发的动态配置结构 */
+interface SdkConfig {
+    sampleRate: number;
+    ignoreErrors: string[];
+    uploadInterval: number;
+    batchSize: number;
+    enablePerformance: boolean;
+    enableBehavior: boolean;
+}
+
+/** SDK 上报的用户资料补丁，未提供字段由服务端保留，null 用于显式清除。 */
+interface UserProfileInput {
+    nickname?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    avatar?: string | null;
+    custom?: Record<string, unknown> | null;
+}
+interface LoggerOptions {
+    projectId: string;
+    token: string;
+    serverUrl: string;
+    env?: string;
+    version?: string;
+    userId?: string;
+    enableError?: boolean;
+    enablePerformance?: boolean;
+    enableBehavior?: boolean;
+    enableNetwork?: boolean;
+    enableConsole?: boolean;
+    sampleRate?: number;
+    batchSize?: number;
+    uploadInterval?: number;
+    maxRetry?: number;
+    ignoreErrors?: (string | RegExp)[];
+    ignoreUrls?: (string | RegExp)[];
+    microFrontend?: MicroFrontendInfo;
+    remoteConfig?: boolean;
+    debug?: boolean;
+    beforeSend?: (log: LogEvent) => LogEvent | false;
+}
+type ResolvedOptions = Required<Omit<LoggerOptions, 'userId' | 'microFrontend' | 'beforeSend'>> & {
+    userId?: string;
+    microFrontend?: MicroFrontendInfo;
+    beforeSend?: (log: LogEvent) => LogEvent | false;
+};
+interface RawLog {
+    type: LogType;
+    level: LogLevel;
+    message: string;
+    stack?: string;
+    extra?: Record<string, unknown>;
+}
+
+declare class Logger {
+    readonly options: ResolvedOptions;
+    readonly sessionId: string;
+    readonly traceId: string;
+    private transport;
+    private tags;
+    private cleanups;
+    private destroyed;
+    constructor(options: LoggerOptions);
+    isUploadUrl(url: string): boolean;
+    shouldIgnoreUrl(url: string): boolean;
+    setUser(userId: string, profile?: UserProfileInput): void;
+    /** 退出登录时调用，解除当前用户关联，后续日志不再携带 userId */
+    clearUser(): void;
+    setTag(key: string, value: unknown): void;
+    report(raw: RawLog): void;
+    track(event: string, data?: Record<string, unknown>): void;
+    captureError(error: unknown, extra?: Record<string, unknown>): void;
+    captureMessage(message: string, level?: 'info' | 'warn' | 'error'): void;
+    flush(): Promise<void>;
+    addCleanup(fn: () => void): void;
+    destroy(): void;
+    private resolveSessionId;
+    private resolveTraceId;
+    private pullRemoteConfig;
+    /** 上报用户资料；与日志队列隔离，避免资料重试或持久化到 IndexedDB。 */
+    private uploadUserProfile;
+}
+
+interface AxiosLike {
+    interceptors: {
+        request: {
+            use: (fn: (c: AxiosConfigLike) => AxiosConfigLike) => void;
+        };
+        response: {
+            use: (onOk: (r: AxiosResponseLike) => AxiosResponseLike, onErr: (e: AxiosErrorLike) => Promise<never>) => void;
+        };
+    };
+}
+interface AxiosConfigLike {
+    url?: string;
+    method?: string;
+    metadata?: {
+        start: number;
+        requestBody?: string;
+    };
+    data?: unknown;
+}
+interface AxiosResponseLike {
+    status: number;
+    config: AxiosConfigLike;
+}
+interface AxiosErrorLike {
+    message: string;
+    config?: AxiosConfigLike;
+    response?: {
+        status: number;
+    };
+}
+declare function attachAxiosTo(logger: Logger, axios: AxiosLike): void;
+
+/**
+ * 页面地址脱敏：仅掩码敏感查询参数的值，保留非敏感 query 与 hash 路由信息。
+ *
+ * 为什么不全量剥离 query/hash：业务页面的路由参数（如详情页 id、tab）是排查问题的
+ * 关键上下文，全量剥离会导致日志中的页面地址不完整、无法定位页面。
+ * 兼容 hash 内携带查询参数的路由形式（如 #/detail?token=xx）。
+ *
+ * @param url 待脱敏的页面地址（支持相对地址）
+ * @returns 脱敏后的地址；解析失败时原样返回，保证不影响上报
+ */
+declare function scrubUrl(url: string): string;
+
+declare function init(options: LoggerOptions): Logger;
+declare function setUser(userId: string, profile?: UserProfileInput): void;
+/** 退出登录时调用，解除当前用户关联 */
+declare function clearUser(): void;
+declare function setTag(key: string, value: unknown): void;
+declare function track(event: string, data?: Record<string, unknown>): void;
+declare function captureError(error: unknown, extra?: Record<string, unknown>): void;
+declare function captureMessage(message: string, level?: 'info' | 'warn' | 'error'): void;
+declare function getSessionId(): string;
+declare function getTraceId(): string;
+declare function flush(): Promise<void>;
+declare function destroy(): void;
+declare function attachAxios(axios: Parameters<typeof attachAxiosTo>[1]): void;
+
+declare const VuePlugin: {
+    install(app: any): void;
+};
+
+export { type LogEvent, LogType, Logger, type LoggerOptions, type SdkConfig, type UserProfileInput, VuePlugin, attachAxios, captureError, captureMessage, clearUser, destroy, flush, getSessionId, getTraceId, init, scrubUrl, setTag, setUser, track };