@philcrp/analytics 1.6.3 → 1.6.5

package/dist/server.mjs

@@ -0,0 +1,729 @@
+// src/manager.ts
+var AnalyticsManager = class {
+  constructor(business, debug = false) {
+    this.providers = /* @__PURE__ */ new Map();
+    this.globalContext = {};
+    this.initialized = false;
+    this.business = business;
+    this.debug = debug;
+  }
+  /**
+   * 注册分析工具提供商
+   */
+  registerProvider(name, provider) {
+    this.providers.set(name, provider);
+    this.log(`Registered provider: ${name}`);
+    return this;
+  }
+  /**
+   * 移除分析工具提供商
+   */
+  unregisterProvider(name) {
+    this.providers.delete(name);
+    this.log(`Unregistered provider: ${name}`);
+    return this;
+  }
+  getProvider(name) {
+    return this.providers.get(name);
+  }
+  /**
+   * 获取所有提供商
+   */
+  getAllProviders() {
+    return Array.from(this.providers.values());
+  }
+  /**
+   * 初始化所有提供商
+   */
+  async initialize() {
+    if (this.initialized) {
+      this.log("Already initialized");
+      return;
+    }
+    const results = await this.executeOnAllProviders("initialize");
+    this.initialized = true;
+    this.log(`Initialized ${results.success.length}/${this.providers.size} providers`);
+    if (results.errors.length > 0) {
+      console.warn(`[AnalyticsManager] ${results.errors.length} providers failed to initialize`);
+    }
+  }
+  /**
+   * 追踪事件到所有提供商
+   */
+  async track(event) {
+    if (!this.ensureInitialized()) return;
+    const enrichedEvent = this.enrichEvent(event);
+    await this.executeOnAllProviders("track", enrichedEvent);
+  }
+  /**
+   * 类型安全的事件追踪
+   */
+  async trackEvent(eventName, properties) {
+    await this.track({
+      name: eventName,
+      properties
+    });
+  }
+  /**
+   * 识别用户
+   */
+  async identify(userId, properties) {
+    if (!this.ensureInitialized()) return;
+    const mergedProperties = { ...this.globalContext, ...properties };
+    await this.executeOnAllProviders("identify", userId, mergedProperties);
+  }
+  /**
+   * 追踪页面浏览
+   */
+  async trackPageView(page, properties) {
+    if (!this.ensureInitialized()) return;
+    const mergedProperties = { ...this.globalContext, ...properties };
+    await this.executeOnAllProviders("trackPageView", page, mergedProperties);
+  }
+  /**
+   * 重置用户身份
+   */
+  async reset() {
+    if (!this.ensureInitialized()) return;
+    await this.executeOnAllProviders("reset");
+  }
+  /**
+   * 设置全局上下文
+   */
+  setGlobalContext(context) {
+    this.globalContext = { ...this.globalContext, ...context };
+    this.log("Updated global context", this.globalContext);
+    return this;
+  }
+  /**
+   * 获取全局上下文
+   */
+  getGlobalContext() {
+    return { ...this.globalContext };
+  }
+  /**
+   * 获取管理器状态
+   */
+  getStatus() {
+    return {
+      initialized: this.initialized,
+      providersCount: this.providers.size
+    };
+  }
+  /**
+   * 检查是否已初始化
+   */
+  ensureInitialized() {
+    if (!this.initialized) {
+      console.warn("[AnalyticsManager] Not initialized. Call initialize() first.");
+      return false;
+    }
+    return true;
+  }
+  /**
+   * 在所有提供商上执行操作
+   */
+  async executeOnAllProviders(method, ...args) {
+    const results = {
+      errors: [],
+      success: []
+    };
+    const promises = Array.from(this.providers.entries()).map(async ([name, provider]) => {
+      try {
+        await provider[method](...args);
+        results.success.push(name);
+      } catch (error) {
+        results.errors.push({ error, provider: name });
+        console.error(
+          `[AnalyticsManager] ${method} failed for ${provider.getProviderName()}:`,
+          error
+        );
+      }
+    });
+    await Promise.allSettled(promises);
+    return results;
+  }
+  /**
+   * 丰富事件数据
+   */
+  enrichEvent(event) {
+    return {
+      ...event,
+      properties: {
+        ...this.globalContext,
+        ...event.properties
+      },
+      timestamp: event.timestamp || /* @__PURE__ */ new Date()
+    };
+  }
+  /**
+   * 记录日志
+   */
+  log(message, data) {
+    if (this.debug) {
+      console.log(`[AnalyticsManager] ${message}`, data || "");
+    }
+  }
+};
+
+// src/providers/posthog.ts
+import { posthog } from "posthog-js";
+
+// src/base.ts
+var BaseAnalytics = class {
+  constructor(config) {
+    var _a, _b;
+    this.debug = (_a = config.debug) != null ? _a : false;
+    this.enabled = (_b = config.enabled) != null ? _b : true;
+    this.business = config.business;
+  }
+  /**
+   * Check if provider is enabled
+   */
+  isEnabled() {
+    if (!this.enabled) {
+      this.log("Provider is disabled");
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Validate event data
+   */
+  validateEvent(event) {
+    if (!event.name) {
+      this.logError("Event name is required");
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Log debug message
+   */
+  log(message, data) {
+    if (this.debug) {
+      console.log(`[${this.getProviderName()}] ${message}`, data || "");
+    }
+  }
+  /**
+   * Log error message
+   */
+  logError(message, error) {
+    console.error(`[${this.getProviderName()}] ${message}`, error || "");
+  }
+  /**
+   * 丰富属性数据，自动处理 spm 前缀
+   * 确保无论通过哪种方式调用都会添加 business 前缀
+   */
+  enrichProperties(properties) {
+    const enriched = { ...properties };
+    enriched.business = this.business;
+    if (enriched.spm && typeof enriched.spm === "string" && enriched.spm.trim()) {
+      if (enriched.spm !== this.business && !enriched.spm.startsWith(`${this.business}.`)) {
+        enriched.spm = `${this.business}.${enriched.spm}`;
+      }
+    } else {
+      enriched.spm = this.business;
+    }
+    return enriched;
+  }
+};
+
+// src/providers/posthog.ts
+var PostHogAnalyticsProvider = class extends BaseAnalytics {
+  constructor(config, business) {
+    super({ business, debug: config.debug, enabled: config.enabled });
+    this.initialized = false;
+    this.config = config;
+  }
+  getProviderName() {
+    return "PostHog";
+  }
+  async initialize() {
+    if (!this.isEnabled() || this.initialized) {
+      return;
+    }
+    try {
+      const { key, host, ...posthogConfig } = this.config;
+      const initConfig = {
+        ...posthogConfig,
+        // User's posthog-js config options
+        api_host: host || posthogConfig.api_host || "https://app.posthog.com",
+        // Use before_send to dynamically add business context to all events
+        before_send: this.createBeforeSendHandler(posthogConfig.before_send),
+        debug: this.debug,
+        loaded: () => this.log("PostHog loaded and ready")
+      };
+      posthog.init(key, initConfig);
+      this.initialized = true;
+      this.log("PostHog initialized successfully");
+      this.log(`Using before_send to add business context: ${this.business}`);
+    } catch (error) {
+      this.logError("Failed to initialize PostHog", error);
+      throw error;
+    }
+  }
+  async track(event) {
+    if (!this.isEnabled() || !this.initialized || !this.validateEvent(event)) {
+      return;
+    }
+    try {
+      const enrichedProperties = this.enrichProperties(event.properties);
+      posthog.capture(event.name, {
+        ...enrichedProperties,
+        ...event.userId && { distinct_id: event.userId }
+      });
+      this.log(`Tracked event: ${event.name}`, { ...event, properties: enrichedProperties });
+    } catch (error) {
+      this.logError(`Failed to track event: ${event.name}`, error);
+    }
+  }
+  async identify(userId, properties) {
+    if (!this.isEnabled() || !this.initialized) {
+      return;
+    }
+    try {
+      const enrichedProperties = this.enrichProperties(properties);
+      posthog.identify(userId, enrichedProperties);
+      this.log(`Identified user: ${userId}`, enrichedProperties);
+    } catch (error) {
+      this.logError(`Failed to identify user: ${userId}`, error);
+    }
+  }
+  async trackPageView(page, properties) {
+    if (!this.isEnabled() || !this.initialized) {
+      return;
+    }
+    try {
+      const enrichedProperties = this.enrichProperties(properties);
+      await this.track({
+        name: "$pageview",
+        properties: { page, ...enrichedProperties }
+      });
+      this.log(`Tracked page view: ${page}`, enrichedProperties);
+    } catch (error) {
+      this.logError(`Failed to track page view: ${page}`, error);
+    }
+  }
+  async reset() {
+    if (!this.isEnabled() || !this.initialized) {
+      return;
+    }
+    try {
+      posthog.reset();
+      this.log("Reset user identity");
+    } catch (error) {
+      this.logError("Failed to reset user identity", error);
+    }
+  }
+  /**
+   * Check if feature flag is enabled
+   */
+  isFeatureEnabled(flag) {
+    if (!this.initialized) {
+      return false;
+    }
+    try {
+      return Boolean(posthog.isFeatureEnabled(flag));
+    } catch (error) {
+      this.logError(`Failed to check feature flag: ${flag}`, error);
+      return false;
+    }
+  }
+  /**
+   * 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() {
+    if (!this.isEnabled() || !this.initialized) {
+      this.log("Cannot get native instance: provider not enabled or not initialized");
+      return null;
+    }
+    return posthog;
+  }
+  /**
+   * Create a before_send handler that adds business context to all events
+   * This ensures both wrapper calls and direct PostHog calls include business information
+   */
+  createBeforeSendHandler(userBeforeSend) {
+    return (event) => {
+      var _a;
+      if (!event) {
+        return null;
+      }
+      const originallyHadSpm = ((_a = event.properties) == null ? void 0 : _a.spm) !== void 0;
+      let processedEvent = event;
+      if (userBeforeSend) {
+        if (Array.isArray(userBeforeSend)) {
+          for (const fn of userBeforeSend) {
+            processedEvent = fn(processedEvent);
+            if (!processedEvent) {
+              return null;
+            }
+          }
+        } else if (typeof userBeforeSend === "function") {
+          processedEvent = userBeforeSend(processedEvent);
+          if (!processedEvent) {
+            return null;
+          }
+        }
+      }
+      if (!processedEvent.properties) {
+        processedEvent.properties = {};
+      }
+      processedEvent.properties.business = this.business;
+      const currentSpm = processedEvent.properties.spm;
+      const shouldSetDefaultSpm = !originallyHadSpm && (!currentSpm || typeof currentSpm === "string" && !currentSpm.trim());
+      if (shouldSetDefaultSpm) {
+        processedEvent.properties.spm = this.business;
+      }
+      return processedEvent;
+    };
+  }
+  /**
+   * Update the business context dynamically
+   * This will affect all future events
+   */
+  updateBusiness(newBusiness) {
+    if (!this.isEnabled() || !this.initialized) {
+      this.log("Cannot update business: provider not enabled or not initialized");
+      return;
+    }
+    this.log(`Business update requested: ${newBusiness} (current: ${this.business})`);
+    this.log("Note: Dynamic business updates require storing business in a mutable field");
+  }
+  /**
+   * Get current business context
+   */
+  getCurrentBusiness() {
+    return this.business;
+  }
+};
+
+// src/providers/posthog-node.ts
+import { PostHog } from "posthog-node";
+var PostHogNodeAnalyticsProvider = class extends BaseAnalytics {
+  constructor(config, business) {
+    super({ business, debug: config.debug, enabled: config.enabled });
+    this.client = null;
+    this.initialized = false;
+    this.config = config;
+  }
+  getProviderName() {
+    return "PostHogNode";
+  }
+  async initialize() {
+    if (!this.isEnabled() || this.initialized) {
+      return;
+    }
+    try {
+      const { key, debug, enabled, ...posthogNodeConfig } = this.config;
+      void debug;
+      void enabled;
+      this.client = new PostHog(key, {
+        flushAt: 20,
+        flushInterval: 1e4,
+        host: "https://app.posthog.com",
+        ...posthogNodeConfig
+        // Apply user's posthog-node config options
+      });
+      this.initialized = true;
+      this.log("PostHog Node.js initialized successfully");
+      this.log(`Using business context: ${this.business}`);
+    } catch (error) {
+      this.logError("Failed to initialize PostHog Node.js", error);
+      throw error;
+    }
+  }
+  async track(event) {
+    if (!this.isEnabled() || !this.initialized || !this.client || !this.validateEvent(event)) {
+      return;
+    }
+    try {
+      const enrichedProperties = this.enrichProperties(event.properties);
+      this.client.capture({
+        distinctId: event.userId || event.anonymousId || "anonymous",
+        event: event.name,
+        properties: enrichedProperties,
+        timestamp: event.timestamp
+      });
+      this.log(`Tracked event: ${event.name}`, { ...event, properties: enrichedProperties });
+    } catch (error) {
+      this.logError(`Failed to track event: ${event.name}`, error);
+    }
+  }
+  async identify(userId, properties) {
+    if (!this.isEnabled() || !this.initialized || !this.client) {
+      return;
+    }
+    try {
+      const enrichedProperties = this.enrichProperties(properties);
+      this.client.identify({
+        distinctId: userId,
+        properties: enrichedProperties
+      });
+      this.log(`Identified user: ${userId}`, enrichedProperties);
+    } catch (error) {
+      this.logError(`Failed to identify user: ${userId}`, error);
+    }
+  }
+  async trackPageView(page, properties) {
+    if (!this.isEnabled() || !this.initialized || !this.client) {
+      return;
+    }
+    try {
+      const enrichedProperties = this.enrichProperties({ page, ...properties });
+      await this.track({
+        name: "$pageview",
+        properties: enrichedProperties
+      });
+      this.log(`Tracked page view: ${page}`, enrichedProperties);
+    } catch (error) {
+      this.logError(`Failed to track page view: ${page}`, error);
+    }
+  }
+  async reset() {
+    if (!this.isEnabled() || !this.initialized) {
+      return;
+    }
+    try {
+      await this.flush();
+      this.log("Reset user identity (flushed pending events)");
+    } catch (error) {
+      this.logError("Failed to reset user identity", error);
+    }
+  }
+  /**
+   * Check if feature flag is enabled for a user
+   */
+  async isFeatureEnabled(flag, distinctId, groups) {
+    if (!this.initialized || !this.client) {
+      return false;
+    }
+    try {
+      const result = await this.client.isFeatureEnabled(flag, distinctId, groups);
+      return Boolean(result);
+    } catch (error) {
+      this.logError(`Failed to check feature flag: ${flag}`, error);
+      return false;
+    }
+  }
+  /**
+   * Get feature flag payload for a user
+   */
+  async getFeatureFlag(flag, distinctId, groups) {
+    if (!this.initialized || !this.client) {
+      return void 0;
+    }
+    try {
+      return await this.client.getFeatureFlag(flag, distinctId, groups);
+    } catch (error) {
+      this.logError(`Failed to get feature flag: ${flag}`, error);
+      return void 0;
+    }
+  }
+  /**
+   * Get all feature flags for a user
+   */
+  async getAllFlags(distinctId, groups) {
+    if (!this.initialized || !this.client) {
+      return {};
+    }
+    try {
+      const flags = await this.client.getAllFlags(distinctId, groups);
+      return flags || {};
+    } catch (error) {
+      this.logError("Failed to get all feature flags", error);
+      return {};
+    }
+  }
+  /**
+   * Flush pending events
+   */
+  async flush() {
+    if (!this.initialized || !this.client) {
+      return;
+    }
+    try {
+      await this.client.flush();
+      this.log("Flushed pending events");
+    } catch (error) {
+      this.logError("Failed to flush events", error);
+    }
+  }
+  /**
+   * Shutdown the client and flush remaining events
+   */
+  async shutdown() {
+    if (!this.initialized || !this.client) {
+      return;
+    }
+    try {
+      await this.client.shutdown();
+      this.initialized = false;
+      this.log("PostHog Node.js client shut down");
+    } catch (error) {
+      this.logError("Failed to shutdown PostHog Node.js client", error);
+    }
+  }
+  /**
+   * Get the native PostHog Node instance for direct access to PostHog APIs
+   */
+  getNativeInstance() {
+    if (!this.isEnabled() || !this.initialized) {
+      this.log("Cannot get native instance: provider not enabled or not initialized");
+      return null;
+    }
+    return this.client;
+  }
+  /**
+   * Group identify - associate user with a group
+   */
+  async groupIdentify(groupType, groupKey, properties) {
+    if (!this.isEnabled() || !this.initialized || !this.client) {
+      return;
+    }
+    try {
+      const enrichedProperties = this.enrichProperties(properties);
+      this.client.groupIdentify({
+        groupKey,
+        groupType,
+        properties: enrichedProperties
+      });
+      this.log(`Group identified: ${groupType}:${groupKey}`, enrichedProperties);
+    } catch (error) {
+      this.logError(`Failed to identify group: ${groupType}:${groupKey}`, error);
+    }
+  }
+  /**
+   * Create alias between user IDs
+   */
+  async alias(distinctId, alias) {
+    if (!this.isEnabled() || !this.initialized || !this.client) {
+      return;
+    }
+    try {
+      this.client.alias({
+        alias,
+        distinctId
+      });
+      this.log(`Created alias: ${distinctId} -> ${alias}`);
+    } catch (error) {
+      this.logError(`Failed to create alias: ${distinctId} -> ${alias}`, error);
+    }
+  }
+  /**
+   * Update the business context dynamically
+   * This will affect all future events
+   */
+  updateBusiness(newBusiness) {
+    if (!this.isEnabled() || !this.initialized) {
+      this.log("Cannot update business: provider not enabled or not initialized");
+      return;
+    }
+    this.log(`Business update requested: ${newBusiness} (current: ${this.business})`);
+    this.log("Note: Dynamic business updates require storing business in a mutable field");
+  }
+  /**
+   * Get current business context
+   */
+  getCurrentBusiness() {
+    return this.business;
+  }
+};
+
+// src/global.ts
+var GLOBAL_STATE_KEY = "__LOBE_ANALYTICS_GLOBAL_STATE__";
+function getGlobalState() {
+  if (!globalThis[GLOBAL_STATE_KEY]) {
+    globalThis[GLOBAL_STATE_KEY] = {
+      instances: /* @__PURE__ */ new Map(),
+      singletonConfig: null,
+      singletonInstance: null
+    };
+  }
+  return globalThis[GLOBAL_STATE_KEY];
+}
+var DEFAULT_INSTANCE_NAME = "__default__";
+function setGlobalAnalytics(instance, name = DEFAULT_INSTANCE_NAME) {
+  const state = getGlobalState();
+  state.instances.set(name, instance);
+}
+function getGlobalAnalytics(name = DEFAULT_INSTANCE_NAME) {
+  const state = getGlobalState();
+  const instance = state.instances.get(name);
+  if (!instance) {
+    throw new Error(
+      `Global analytics instance "${name}" not found. Make sure to register it first using setGlobalAnalytics() or use AnalyticsProvider.`
+    );
+  }
+  return instance;
+}
+function getGlobalAnalyticsOptional(name = DEFAULT_INSTANCE_NAME) {
+  const state = getGlobalState();
+  return state.instances.get(name) || null;
+}
+function hasGlobalAnalytics(name = DEFAULT_INSTANCE_NAME) {
+  const state = getGlobalState();
+  return state.instances.has(name);
+}
+function removeGlobalAnalytics(name = DEFAULT_INSTANCE_NAME) {
+  const state = getGlobalState();
+  return state.instances.delete(name);
+}
+function clearGlobalAnalytics() {
+  const state = getGlobalState();
+  state.instances.clear();
+}
+function getGlobalAnalyticsNames() {
+  const state = getGlobalState();
+  return Array.from(state.instances.keys());
+}
+
+// src/server.ts
+function createServerAnalytics(config) {
+  var _a, _b;
+  const manager = new AnalyticsManager(config.business, config.debug);
+  if ((_a = config.providers.posthog) == null ? void 0 : _a.enabled) {
+    const provider = new PostHogAnalyticsProvider(config.providers.posthog, config.business);
+    manager.registerProvider("posthog", provider);
+  }
+  if ((_b = config.providers.posthogNode) == null ? void 0 : _b.enabled) {
+    const provider = new PostHogNodeAnalyticsProvider(
+      config.providers.posthogNode,
+      config.business
+    );
+    manager.registerProvider("posthogNode", provider);
+  }
+  return manager;
+}
+export {
+  AnalyticsManager,
+  PostHogAnalyticsProvider,
+  PostHogNodeAnalyticsProvider,
+  clearGlobalAnalytics,
+  createServerAnalytics,
+  getGlobalAnalytics,
+  getGlobalAnalyticsNames,
+  getGlobalAnalyticsOptional,
+  hasGlobalAnalytics,
+  removeGlobalAnalytics,
+  setGlobalAnalytics
+};
+//# sourceMappingURL=server.mjs.map