@philcrp/analytics 1.6.4 → 1.6.5

package/dist/global-CLXWNSdY.d.ts

@@ -0,0 +1,587 @@
+import { PostHog, PostHogOptions } from 'posthog-node';
+import { posthog, PostHogConfig } from 'posthog-js';
+
+interface XAdsFunction {
+    (...args: unknown[]): void;
+    exe?: (...args: unknown[]) => void;
+    queue?: unknown[][];
+    version?: string;
+}
+interface XAdsGlobalState {
+    configuredPixelIds: Set<string>;
+    scriptRequested: boolean;
+}
+declare global {
+    interface Window {
+        __LOBE_ANALYTICS_X_ADS_STATE__?: XAdsGlobalState;
+        twq?: XAdsFunction;
+    }
+}
+/**
+ * X Ads Analytics Provider
+ * Uses X Pixel (twq + uwt.js) for client-side conversion tracking
+ */
+declare class XAdsAnalyticsProvider extends BaseAnalytics {
+    private readonly config;
+    private initialized;
+    constructor(config: XAdsProviderAnalyticsConfig, business: string);
+    getProviderName(): string;
+    initialize(): Promise<void>;
+    track(event: AnalyticsEvent): Promise<void>;
+    identify(): Promise<void>;
+    trackPageView(): Promise<void>;
+    reset(): Promise<void>;
+    private ensureScript;
+    private ensureTwq;
+    private getGlobalState;
+    private getEventId;
+    private getEventParameters;
+    private mapPurchaseEventParameters;
+    private mapContents;
+    private toFiniteNumber;
+}
+
+/**
+ * PostHog Node.js Analytics Provider
+ * Uses official posthog-node SDK for server-side tracking
+ */
+declare class PostHogNodeAnalyticsProvider extends BaseAnalytics {
+    private readonly config;
+    private client;
+    private initialized;
+    constructor(config: PostHogNodeProviderAnalyticsConfig, business: string);
+    getProviderName(): string;
+    initialize(): Promise<void>;
+    track(event: AnalyticsEvent): Promise<void>;
+    identify(userId: string, properties?: Record<string, any>): Promise<void>;
+    trackPageView(page: string, properties?: Record<string, any>): Promise<void>;
+    reset(): Promise<void>;
+    /**
+     * Check if feature flag is enabled for a user
+     */
+    isFeatureEnabled(flag: string, distinctId: string, groups?: Record<string, any>): Promise<boolean>;
+    /**
+     * Get feature flag payload for a user
+     */
+    getFeatureFlag(flag: string, distinctId: string, groups?: Record<string, any>): Promise<any>;
+    /**
+     * Get all feature flags for a user
+     */
+    getAllFlags(distinctId: string, groups?: Record<string, any>): Promise<Record<string, any>>;
+    /**
+     * Flush pending events
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown the client and flush remaining events
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get the native PostHog Node instance for direct access to PostHog APIs
+     */
+    getNativeInstance(): PostHog | null;
+    /**
+     * Group identify - associate user with a group
+     */
+    groupIdentify(groupType: string, groupKey: string, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Create alias between user IDs
+     */
+    alias(distinctId: string, alias: string): Promise<void>;
+    /**
+     * Update the business context dynamically
+     * This will affect all future events
+     */
+    updateBusiness(newBusiness: string): void;
+    /**
+     * Get current business context
+     */
+    getCurrentBusiness(): string;
+}
+
+/**
+ * PostHog Analytics Provider
+ * Uses official posthog-js SDK
+ */
+declare class PostHogAnalyticsProvider extends BaseAnalytics {
+    private readonly config;
+    private initialized;
+    constructor(config: PostHogProviderAnalyticsConfig, business: string);
+    getProviderName(): string;
+    initialize(): Promise<void>;
+    track(event: AnalyticsEvent): Promise<void>;
+    identify(userId: string, properties?: Record<string, any>): Promise<void>;
+    trackPageView(page: string, properties?: Record<string, any>): Promise<void>;
+    reset(): Promise<void>;
+    /**
+     * Check if feature flag is enabled
+     */
+    isFeatureEnabled(flag: string): boolean;
+    /**
+     * Get the native PostHog instance for direct access to PostHog APIs
+     *
+     * Note: When using the native instance directly, events will still include
+     * the business spm prefix because it's registered as a global property.
+     *
+     * @returns PostHog native instance or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const analytics = createAnalytics({ business: 'myapp', ... });
+     * const posthogProvider = analytics.getProvider('posthog');
+     * const posthog = posthogProvider.getNativeInstance();
+     *
+     * // These calls will automatically include spm: 'myapp'
+     * posthog?.capture('custom_event', { custom: 'data' });
+     * posthog?.isFeatureEnabled('new_feature');
+     * posthog?.group('company', 'company_123');
+     * ```
+     */
+    getNativeInstance(): typeof posthog | null;
+    /**
+     * Create a before_send handler that adds business context to all events
+     * This ensures both wrapper calls and direct PostHog calls include business information
+     */
+    private createBeforeSendHandler;
+    /**
+     * Update the business context dynamically
+     * This will affect all future events
+     */
+    updateBusiness(newBusiness: string): void;
+    /**
+     * Get current business context
+     */
+    getCurrentBusiness(): string;
+}
+
+/**
+ * Google Analytics 4 Provider
+ * Uses gtag.js library for client-side tracking
+ */
+
+/**
+ * Google Analytics 4 Analytics Provider
+ * Uses gtag.js for tracking events, page views, and user identification
+ */
+declare class GoogleAnalyticsProvider extends BaseAnalytics {
+    private readonly config;
+    private initialized;
+    constructor(config: GoogleAnalyticsProviderConfig, business: string);
+    getProviderName(): string;
+    initialize(): Promise<void>;
+    track(event: AnalyticsEvent): Promise<void>;
+    identify(userId: string, properties?: Record<string, any>): Promise<void>;
+    trackPageView(page: string, properties?: Record<string, any>): Promise<void>;
+    reset(): Promise<void>;
+    /**
+     * Check if feature flag is enabled
+     * Note: GA4 doesn't have built-in feature flags like PostHog,
+     * so this always returns false
+     */
+    isFeatureEnabled(flag: string): boolean;
+    /**
+     * Get the native gtag function for direct access to GA4 APIs
+     *
+     * Note: When using the native gtag function directly, events will NOT automatically
+     * include the business and spm properties. You need to add them manually if desired.
+     *
+     * @returns gtag function or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const analytics = createAnalytics({ business: 'myapp', ... });
+     * const ga4Provider = analytics.getProvider('ga4');
+     * const gtag = ga4Provider.getNativeInstance();
+     *
+     * // Manual business context addition required for direct calls
+     * gtag?.('event', 'custom_event', {
+     *   custom: 'data',
+     *   business: 'myapp',
+     *   spm: 'myapp.custom_section'
+     * });
+     * ```
+     */
+    getNativeInstance(): ((...args: any[]) => void) | null;
+    /**
+     * Get current measurement ID
+     */
+    getMeasurementId(): string;
+    /**
+     * Get current business context
+     */
+    getCurrentBusiness(): string;
+}
+
+interface AnalyticsEvent {
+    /** Anonymous ID */
+    anonymousId?: string;
+    /** Event name, recommend using category:action format */
+    name: string;
+    /** Event properties */
+    properties?: Record<string, any>;
+    /** Event timestamp */
+    timestamp?: Date;
+    /** User ID */
+    userId?: string;
+}
+type Platform = 'web' | 'ios' | 'android' | 'desktop';
+interface EventContext {
+    [key: string]: any;
+    page?: string;
+    section?: string;
+    session_id?: string;
+    user_properties?: Record<string, any>;
+}
+interface PredefinedEvents {
+    button_click: {
+        [key: string]: any;
+        button_name: string;
+        spm?: string;
+    };
+    page_view: {
+        [key: string]: any;
+        page: string;
+        spm?: string;
+    };
+    user_login: {
+        [key: string]: any;
+        spm?: string;
+    };
+    user_signup: {
+        [key: string]: any;
+        spm?: string;
+    };
+}
+interface ProviderConfig {
+    debug?: boolean;
+    enabled: boolean;
+}
+interface PostHogProviderAnalyticsConfig extends Partial<Omit<PostHogConfig, 'debug'>>, ProviderConfig {
+    host?: string;
+    key: string;
+}
+interface PostHogNodeProviderAnalyticsConfig extends Partial<PostHogOptions>, ProviderConfig {
+    key: string;
+}
+interface UmamiProviderAnalyticsConfig extends ProviderConfig {
+    scriptUrl?: string;
+    websiteId: string;
+}
+interface GoogleAnalyticsProviderConfig extends ProviderConfig {
+    gtagConfig?: {
+        [key: string]: any;
+        debug_mode?: boolean;
+    };
+    measurementId: string;
+}
+interface XAdsEventIdMap {
+    [eventName: string]: string | undefined;
+}
+interface XAdsProviderAnalyticsConfig extends ProviderConfig {
+    eventIds?: XAdsEventIdMap;
+    pixelId: string;
+    purchaseEventId?: string;
+}
+interface AnalyticsConfig {
+    business: string;
+    debug?: boolean;
+    providers: {
+        ga4?: GoogleAnalyticsProviderConfig;
+        posthog?: PostHogProviderAnalyticsConfig;
+        posthogNode?: PostHogNodeProviderAnalyticsConfig;
+        umami?: UmamiProviderAnalyticsConfig;
+        xAds?: XAdsProviderAnalyticsConfig;
+    };
+}
+interface ProviderTypeMap {
+    ga4: GoogleAnalyticsProvider;
+    posthog: PostHogAnalyticsProvider;
+    posthogNode: PostHogNodeAnalyticsProvider;
+    xAds: XAdsAnalyticsProvider;
+}
+
+/**
+ * Base abstract class for analytics providers
+ * All analytics implementations should extend this class
+ */
+declare abstract class BaseAnalytics {
+    protected readonly debug: boolean;
+    protected readonly enabled: boolean;
+    protected readonly business: string;
+    constructor(config: {
+        business: string;
+        debug?: boolean;
+        enabled?: boolean;
+    });
+    /**
+     * Initialize the analytics provider
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Track a single event
+     */
+    abstract track(event: AnalyticsEvent): Promise<void>;
+    /**
+     * Identify a user
+     */
+    abstract identify(userId: string, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Track page view
+     */
+    abstract trackPageView(page: string, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Reset user identity
+     */
+    abstract reset(): Promise<void>;
+    /**
+     * Get provider name for logging
+     */
+    abstract getProviderName(): string;
+    /**
+     * Check if provider is enabled
+     */
+    protected isEnabled(): boolean;
+    /**
+     * Validate event data
+     */
+    protected validateEvent(event: AnalyticsEvent): boolean;
+    /**
+     * Log debug message
+     */
+    protected log(message: string, data?: any): void;
+    /**
+     * Log error message
+     */
+    protected logError(message: string, error?: any): void;
+    /**
+     * 丰富属性数据，自动处理 spm 前缀
+     * 确保无论通过哪种方式调用都会添加 business 前缀
+     */
+    protected enrichProperties(properties?: Record<string, any>): Record<string, any>;
+}
+
+/**
+ * Analytics 管理器
+ * 统一管理多个分析工具提供商
+ */
+declare class AnalyticsManager {
+    private readonly providers;
+    private readonly business;
+    private globalContext;
+    private initialized;
+    private readonly debug;
+    constructor(business: string, debug?: boolean);
+    /**
+     * 注册分析工具提供商
+     */
+    registerProvider(name: string, provider: BaseAnalytics): this;
+    /**
+     * 移除分析工具提供商
+     */
+    unregisterProvider(name: string): this;
+    /**
+     * 获取指定的提供商
+     */
+    getProvider<T extends keyof ProviderTypeMap>(name: T): ProviderTypeMap[T] | undefined;
+    getProvider(name: string): BaseAnalytics | undefined;
+    /**
+     * 获取所有提供商
+     */
+    getAllProviders(): BaseAnalytics[];
+    /**
+     * 初始化所有提供商
+     */
+    initialize(): Promise<void>;
+    /**
+     * 追踪事件到所有提供商
+     */
+    track(event: AnalyticsEvent): Promise<void>;
+    /**
+     * 类型安全的事件追踪
+     */
+    trackEvent<K extends keyof PredefinedEvents>(eventName: K, properties: PredefinedEvents[K]): Promise<void>;
+    /**
+     * 识别用户
+     */
+    identify(userId: string, properties?: Record<string, any>): Promise<void>;
+    /**
+     * 追踪页面浏览
+     */
+    trackPageView(page: string, properties?: Record<string, any>): Promise<void>;
+    /**
+     * 重置用户身份
+     */
+    reset(): Promise<void>;
+    /**
+     * 设置全局上下文
+     */
+    setGlobalContext(context: EventContext): this;
+    /**
+     * 获取全局上下文
+     */
+    getGlobalContext(): EventContext;
+    /**
+     * 获取管理器状态
+     */
+    getStatus(): {
+        initialized: boolean;
+        providersCount: number;
+    };
+    /**
+     * 检查是否已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 在所有提供商上执行操作
+     */
+    private executeOnAllProviders;
+    /**
+     * 丰富事件数据
+     */
+    private enrichEvent;
+    /**
+     * 记录日志
+     */
+    private log;
+}
+
+/**
+ * 扩展 globalThis 类型
+ */
+declare global {
+    var __LOBE_ANALYTICS_GLOBAL_STATE__: GlobalAnalyticsState | undefined;
+}
+/**
+ * 全局状态接口
+ */
+interface GlobalAnalyticsState {
+    instances: Map<string, AnalyticsManager>;
+    singletonConfig: AnalyticsConfig | null;
+    singletonInstance: AnalyticsManager | null;
+}
+/**
+ * 注册全局 Analytics 实例
+ *
+ * @param instance Analytics 管理器实例
+ * @param name 实例名称，默认为 '__default__'
+ *
+ * @example
+ * ```typescript
+ * const analytics = createAnalytics({ ... });
+ * setGlobalAnalytics(analytics);
+ * ```
+ */
+declare function setGlobalAnalytics(instance: AnalyticsManager, name?: string): void;
+/**
+ * 获取全局 Analytics 实例
+ *
+ * @param name 实例名称，默认为 '__default__'
+ * @returns Analytics 管理器实例
+ * @throws {Error} 如果实例不存在
+ *
+ * @example
+ * ```typescript
+ * // 在任何文件中使用
+ * const analytics = getGlobalAnalytics();
+ * analytics.track({ name: 'some_event' });
+ * ```
+ */
+declare function getGlobalAnalytics(name?: string): AnalyticsManager;
+/**
+ * 获取全局 Analytics 实例（可选，不抛出错误）
+ *
+ * @param name 实例名称，默认为 '__default__'
+ * @returns Analytics 管理器实例或 null
+ *
+ * @example
+ * ```typescript
+ * const analytics = getGlobalAnalyticsOptional();
+ * analytics?.track({ name: 'optional_event' });
+ * ```
+ */
+declare function getGlobalAnalyticsOptional(name?: string): AnalyticsManager | null;
+/**
+ * 检查全局实例是否存在
+ *
+ * @param name 实例名称，默认为 '__default__'
+ * @returns 是否存在
+ */
+declare function hasGlobalAnalytics(name?: string): boolean;
+/**
+ * 移除全局 Analytics 实例
+ *
+ * @param name 实例名称，默认为 '__default__'
+ * @returns 是否成功移除
+ */
+declare function removeGlobalAnalytics(name?: string): boolean;
+/**
+ * 清除所有全局实例
+ */
+declare function clearGlobalAnalytics(): void;
+/**
+ * 获取所有已注册的实例名称
+ *
+ * @returns 实例名称数组
+ */
+declare function getGlobalAnalyticsNames(): string[];
+/**
+ * 创建或获取单例 Analytics 实例
+ *
+ * 单例模式适用于整个应用只需要一个 Analytics 配置的场景。
+ * 如果已存在单例且配置相同，返回现有实例；否则创建新实例。
+ *
+ * @param config Analytics 配置
+ * @returns Analytics 管理器实例
+ *
+ * @example
+ * ```typescript
+ * // 在应用启动时创建
+ * const analytics = createSingletonAnalytics({
+ *   debug: true,
+ *   providers: {
+ *     posthog: {
+ *       enabled: true,
+ *       key: 'your_key',
+ *       host: 'https://app.posthog.com',
+ *     },
+ *   },
+ * });
+ *
+ * // 在其他地方获取同一实例
+ * const sameAnalytics = getSingletonAnalytics();
+ * ```
+ */
+declare function createSingletonAnalytics(config: AnalyticsConfig): AnalyticsManager;
+/**
+ * 获取单例 Analytics 实例
+ *
+ * @returns Analytics 管理器实例
+ * @throws {Error} 如果单例未创建
+ *
+ * @example
+ * ```typescript
+ * const analytics = getSingletonAnalytics();
+ * analytics.track({ name: 'some_event' });
+ * ```
+ */
+declare function getSingletonAnalytics(): AnalyticsManager;
+/**
+ * 获取单例 Analytics 实例（可选，不抛出错误）
+ *
+ * @returns Analytics 管理器实例或 null
+ */
+declare function getSingletonAnalyticsOptional(): AnalyticsManager | null;
+/**
+ * 检查单例是否已创建
+ *
+ * @returns 是否存在单例
+ */
+declare function hasSingletonAnalytics(): boolean;
+/**
+ * 重置单例实例
+ *
+ * 主要用于测试场景
+ */
+declare function resetSingletonAnalytics(): void;
+
+export { type AnalyticsConfig as A, BaseAnalytics as B, type EventContext as E, GoogleAnalyticsProvider as G, PostHogAnalyticsProvider as P, type UmamiProviderAnalyticsConfig as U, XAdsAnalyticsProvider as X, AnalyticsManager as a, type AnalyticsEvent as b, type GoogleAnalyticsProviderConfig as c, type PostHogNodeProviderAnalyticsConfig as d, type PostHogProviderAnalyticsConfig as e, type PredefinedEvents as f, type ProviderConfig as g, type XAdsEventIdMap as h, type XAdsProviderAnalyticsConfig as i, clearGlobalAnalytics as j, createSingletonAnalytics as k, getGlobalAnalytics as l, getGlobalAnalyticsNames as m, getGlobalAnalyticsOptional as n, getSingletonAnalytics as o, getSingletonAnalyticsOptional as p, hasGlobalAnalytics as q, hasSingletonAnalytics as r, removeGlobalAnalytics as s, resetSingletonAnalytics as t, setGlobalAnalytics as u, type Platform as v, PostHogNodeAnalyticsProvider as w, type ProviderTypeMap as x };

package/dist/index.d.mts

@@ -0,0 +1,38 @@
+import { A as AnalyticsConfig, a as AnalyticsManager } from './global-CLXWNSdY.mjs';
+export { b as AnalyticsEvent, B as BaseAnalytics, E as EventContext, G as GoogleAnalyticsProvider, c as GoogleAnalyticsProviderConfig, P as PostHogAnalyticsProvider, d as PostHogNodeProviderAnalyticsConfig, e as PostHogProviderAnalyticsConfig, f as PredefinedEvents, g as ProviderConfig, U as UmamiProviderAnalyticsConfig, X as XAdsAnalyticsProvider, h as XAdsEventIdMap, i as XAdsProviderAnalyticsConfig, j as clearGlobalAnalytics, k as createSingletonAnalytics, l as getGlobalAnalytics, m as getGlobalAnalyticsNames, n as getGlobalAnalyticsOptional, o as getSingletonAnalytics, p as getSingletonAnalyticsOptional, q as hasGlobalAnalytics, r as hasSingletonAnalytics, s as removeGlobalAnalytics, t as resetSingletonAnalytics, u as setGlobalAnalytics } from './global-CLXWNSdY.mjs';
+import 'posthog-node';
+import 'posthog-js';
+
+/**
+ * Create a configured Analytics manager with providers
+ *
+ * @param config Analytics configuration
+ * @returns Configured AnalyticsManager instance
+ *
+ * @example
+ * ```typescript
+ * const analytics = createAnalytics({
+ *   business: 'myapp',
+ *   debug: true,
+ *   providers: {
+ *     posthog: {
+ *       enabled: true,
+ *       key: 'phc_your_key',
+ *       host: 'https://app.posthog.com',
+ *     },
+ *     ga4: {
+ *       enabled: true,
+ *       measurementId: 'G-XXXXXXXXXX',
+ *       gtagConfig: {
+ *         debug_mode: true,
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * await analytics.initialize();
+ * ```
+ */
+declare function createAnalytics(config: AnalyticsConfig): AnalyticsManager;
+
+export { AnalyticsConfig, AnalyticsManager, createAnalytics, AnalyticsManager as default };

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { A as AnalyticsConfig, a as AnalyticsManager } from './global-CLXWNSdY.js';
+export { b as AnalyticsEvent, B as BaseAnalytics, E as EventContext, G as GoogleAnalyticsProvider, c as GoogleAnalyticsProviderConfig, P as PostHogAnalyticsProvider, d as PostHogNodeProviderAnalyticsConfig, e as PostHogProviderAnalyticsConfig, f as PredefinedEvents, g as ProviderConfig, U as UmamiProviderAnalyticsConfig, X as XAdsAnalyticsProvider, h as XAdsEventIdMap, i as XAdsProviderAnalyticsConfig, j as clearGlobalAnalytics, k as createSingletonAnalytics, l as getGlobalAnalytics, m as getGlobalAnalyticsNames, n as getGlobalAnalyticsOptional, o as getSingletonAnalytics, p as getSingletonAnalyticsOptional, q as hasGlobalAnalytics, r as hasSingletonAnalytics, s as removeGlobalAnalytics, t as resetSingletonAnalytics, u as setGlobalAnalytics } from './global-CLXWNSdY.js';
+import 'posthog-node';
+import 'posthog-js';
+
+/**
+ * Create a configured Analytics manager with providers
+ *
+ * @param config Analytics configuration
+ * @returns Configured AnalyticsManager instance
+ *
+ * @example
+ * ```typescript
+ * const analytics = createAnalytics({
+ *   business: 'myapp',
+ *   debug: true,
+ *   providers: {
+ *     posthog: {
+ *       enabled: true,
+ *       key: 'phc_your_key',
+ *       host: 'https://app.posthog.com',
+ *     },
+ *     ga4: {
+ *       enabled: true,
+ *       measurementId: 'G-XXXXXXXXXX',
+ *       gtagConfig: {
+ *         debug_mode: true,
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * await analytics.initialize();
+ * ```
+ */
+declare function createAnalytics(config: AnalyticsConfig): AnalyticsManager;
+
+export { AnalyticsConfig, AnalyticsManager, createAnalytics, AnalyticsManager as default };