swetrix 3.7.1 → 4.0.0

package/src/Lib.ts

@@ -32,6 +32,12 @@ export interface LibOptions {
 
   /** Set a custom URL of the API server (for selfhosted variants of Swetrix). */
   apiURL?: string
+
+  /**
+   * Optional profile ID for long-term user tracking.
+   * If set, it will be used for all pageviews and events unless overridden per-call.
+   */
+  profileId?: string
 }
 
 export interface TrackEventOptions {
@@ -45,6 +51,9 @@ export interface TrackEventOptions {
   meta?: {
     [key: string]: string | number | boolean | null | undefined
   }
+
+  /** Optional profile ID for long-term user tracking. Overrides the global profileId if set. */
+  profileId?: string
 }
 
 // Partial user-editable pageview payload
@@ -63,6 +72,9 @@ export interface IPageViewPayload {
   meta?: {
     [key: string]: string | number | boolean | null | undefined
   }
+
+  /** Optional profile ID for long-term user tracking. Overrides the global profileId if set. */
+  profileId?: string
 }
 
 // Partial user-editable error payload
@@ -95,6 +107,41 @@ interface IPerfPayload {
   ttfb: number
 }
 
+/**
+ * Options for evaluating feature flags.
+ */
+export interface FeatureFlagsOptions {
+  /**
+   * Optional profile ID for long-term user tracking.
+   * If not provided, an anonymous profile ID will be generated server-side based on IP and user agent.
+   * Overrides the global profileId if set.
+   */
+  profileId?: string
+}
+
+/**
+ * Options for evaluating experiments.
+ */
+export interface ExperimentOptions {
+  /**
+   * Optional profile ID for long-term user tracking.
+   * If not provided, an anonymous profile ID will be generated server-side based on IP and user agent.
+   * Overrides the global profileId if set.
+   */
+  profileId?: string
+}
+
+/**
+ * Cached feature flags and experiments with timestamp.
+ */
+interface CachedData {
+  flags: Record<string, boolean>
+  experiments: Record<string, string>
+  timestamp: number
+  /** The profileId used when fetching this cached data */
+  profileId?: string
+}
+
 /**
  * The object returned by `trackPageViews()`, used to stop tracking pages.
  */
@@ -174,14 +221,19 @@ export const defaultActions = {
 }
 
 const DEFAULT_API_HOST = 'https://api.swetrix.com/log'
+const DEFAULT_API_BASE = 'https://api.swetrix.com'
+
+// Default cache duration: 5 minutes
+const DEFAULT_CACHE_DURATION = 5 * 60 * 1000
 
 export class Lib {
   private pageData: PageData | null = null
   private pageViewsOptions?: PageViewsOptions | null = null
   private errorsOptions?: ErrorOptions | null = null
-  private perfStatsCollected: Boolean = false
+  private perfStatsCollected: boolean = false
   private activePage: string | null = null
   private errorListenerExists = false
+  private cachedData: CachedData | null = null
 
   constructor(private projectID: string, private options?: LibOptions) {
     this.trackPathChange = this.trackPathChange.bind(this)
@@ -190,7 +242,7 @@ export class Lib {
   }
 
   captureError(event: ErrorEvent): void {
-    if (typeof this.errorsOptions?.sampleRate === 'number' && this.errorsOptions.sampleRate > Math.random()) {
+    if (typeof this.errorsOptions?.sampleRate === 'number' && this.errorsOptions.sampleRate >= Math.random()) {
       return
     }
 
@@ -233,6 +285,7 @@ export class Lib {
     return {
       stop: () => {
         window.removeEventListener('error', this.captureError)
+        this.errorListenerExists = false
       },
     }
   }
@@ -279,7 +332,12 @@ export class Lib {
     const data = {
       ...event,
       pid: this.projectID,
-      pg: this.activePage,
+      pg:
+        this.activePage ||
+        getPath({
+          hash: this.pageViewsOptions?.hash,
+          search: this.pageViewsOptions?.search,
+        }),
       lc: getLocale(),
       tz: getTimezone(),
       ref: getReferrer(),
@@ -288,6 +346,7 @@ export class Lib {
       ca: getUTMCampaign(),
       te: getUTMTerm(),
       co: getUTMContent(),
+      profileId: event.profileId ?? this.options?.profileId,
     }
     await this.sendRequest('custom', data)
   }
@@ -362,15 +421,304 @@ export class Lib {
     }
   }
 
+  /**
+   * Fetches all feature flags and experiments for the project.
+   * Results are cached for 5 minutes by default.
+   *
+   * @param options - Options for evaluating feature flags.
+   * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
+   * @returns A promise that resolves to a record of flag keys to boolean values.
+   */
+  async getFeatureFlags(options?: FeatureFlagsOptions, forceRefresh?: boolean): Promise<Record<string, boolean>> {
+    if (!isInBrowser()) {
+      return {}
+    }
+
+    const requestedProfileId = options?.profileId ?? this.options?.profileId
+
+    // Check cache first - must match profileId and not be expired
+    if (!forceRefresh && this.cachedData) {
+      const now = Date.now()
+      const isSameProfile = this.cachedData.profileId === requestedProfileId
+      if (isSameProfile && now - this.cachedData.timestamp < DEFAULT_CACHE_DURATION) {
+        return this.cachedData.flags
+      }
+    }
+
+    try {
+      await this.fetchFlagsAndExperiments(options)
+      return this.cachedData?.flags || {}
+    } catch (error) {
+      console.warn('[Swetrix] Error fetching feature flags:', error)
+      return this.cachedData?.flags || {}
+    }
+  }
+
+  /**
+   * Internal method to fetch both feature flags and experiments from the API.
+   */
+  private async fetchFlagsAndExperiments(options?: FeatureFlagsOptions | ExperimentOptions): Promise<void> {
+    const apiBase = this.getApiBase()
+    const body: { pid: string; profileId?: string } = {
+      pid: this.projectID,
+    }
+
+    // Use profileId from options, or fall back to global profileId
+    const profileId = options?.profileId ?? this.options?.profileId
+    if (profileId) {
+      body.profileId = profileId
+    }
+
+    const response = await fetch(`${apiBase}/feature-flag/evaluate`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      console.warn('[Swetrix] Failed to fetch feature flags and experiments:', response.status)
+      return
+    }
+
+    const data = (await response.json()) as {
+      flags: Record<string, boolean>
+      experiments?: Record<string, string>
+    }
+
+    // Use profileId from options, or fall back to global profileId
+    const cachedProfileId = options?.profileId ?? this.options?.profileId
+
+    // Update cache with both flags and experiments
+    this.cachedData = {
+      flags: data.flags || {},
+      experiments: data.experiments || {},
+      timestamp: Date.now(),
+      profileId: cachedProfileId,
+    }
+  }
+
+  /**
+   * Gets the value of a single feature flag.
+   *
+   * @param key - The feature flag key.
+   * @param options - Options for evaluating the feature flag.
+   * @param defaultValue - Default value to return if the flag is not found. Defaults to false.
+   * @returns A promise that resolves to the boolean value of the flag.
+   */
+  async getFeatureFlag(key: string, options?: FeatureFlagsOptions, defaultValue: boolean = false): Promise<boolean> {
+    const flags = await this.getFeatureFlags(options)
+    return flags[key] ?? defaultValue
+  }
+
+  /**
+   * Clears the cached feature flags and experiments, forcing a fresh fetch on the next call.
+   */
+  clearFeatureFlagsCache(): void {
+    this.cachedData = null
+  }
+
+  /**
+   * Fetches all A/B test experiments for the project.
+   * Results are cached for 5 minutes by default (shared cache with feature flags).
+   *
+   * @param options - Options for evaluating experiments.
+   * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
+   * @returns A promise that resolves to a record of experiment IDs to variant keys.
+   *
+   * @example
+   * ```typescript
+   * const experiments = await getExperiments()
+   * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
+   * ```
+   */
+  async getExperiments(options?: ExperimentOptions, forceRefresh?: boolean): Promise<Record<string, string>> {
+    if (!isInBrowser()) {
+      return {}
+    }
+
+    const requestedProfileId = options?.profileId ?? this.options?.profileId
+
+    // Check cache first - must match profileId and not be expired
+    if (!forceRefresh && this.cachedData) {
+      const now = Date.now()
+      const isSameProfile = this.cachedData.profileId === requestedProfileId
+      if (isSameProfile && now - this.cachedData.timestamp < DEFAULT_CACHE_DURATION) {
+        return this.cachedData.experiments
+      }
+    }
+
+    try {
+      await this.fetchFlagsAndExperiments(options)
+      return this.cachedData?.experiments || {}
+    } catch (error) {
+      console.warn('[Swetrix] Error fetching experiments:', error)
+      return this.cachedData?.experiments || {}
+    }
+  }
+
+  /**
+   * Gets the variant key for a specific A/B test experiment.
+   *
+   * @param experimentId - The experiment ID.
+   * @param options - Options for evaluating the experiment.
+   * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+   * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
+   *
+   * @example
+   * ```typescript
+   * const variant = await getExperiment('checkout-redesign')
+   *
+   * if (variant === 'new-checkout') {
+   *   // Show new checkout flow
+   * } else {
+   *   // Show control (original) checkout
+   * }
+   * ```
+   */
+  async getExperiment(
+    experimentId: string,
+    options?: ExperimentOptions,
+    defaultVariant: string | null = null,
+  ): Promise<string | null> {
+    const experiments = await this.getExperiments(options)
+    return experiments[experimentId] ?? defaultVariant
+  }
+
+  /**
+   * Clears the cached experiments (alias for clearFeatureFlagsCache since they share the same cache).
+   */
+  clearExperimentsCache(): void {
+    this.cachedData = null
+  }
+
+  /**
+   * Gets the anonymous profile ID for the current visitor.
+   * If profileId was set via init options, returns that.
+   * Otherwise, requests server to generate one from IP/UA hash.
+   *
+   * This ID can be used for revenue attribution with payment providers.
+   *
+   * @returns A promise that resolves to the profile ID string, or null on error.
+   *
+   * @example
+   * ```typescript
+   * const profileId = await swetrix.getProfileId()
+   *
+   * // Pass to Paddle Checkout for revenue attribution
+   * Paddle.Checkout.open({
+   *   items: [{ priceId: 'pri_01234567890', quantity: 1 }],
+   *   customData: {
+   *     swetrix_profile_id: profileId,
+   *     swetrix_session_id: await swetrix.getSessionId()
+   *   }
+   * })
+   * ```
+   */
+  async getProfileId(): Promise<string | null> {
+    // If profileId is already set in options, return it
+    if (this.options?.profileId) {
+      return this.options.profileId
+    }
+
+    if (!isInBrowser()) {
+      return null
+    }
+
+    try {
+      const apiBase = this.getApiBase()
+      const response = await fetch(`${apiBase}/log/profile-id`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ pid: this.projectID }),
+      })
+
+      if (!response.ok) {
+        return null
+      }
+
+      const data = (await response.json()) as { profileId: string | null }
+      return data.profileId
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Gets the current session ID for the visitor.
+   * Session IDs are generated server-side based on IP and user agent.
+   *
+   * This ID can be used for revenue attribution with payment providers.
+   *
+   * @returns A promise that resolves to the session ID string, or null on error.
+   *
+   * @example
+   * ```typescript
+   * const sessionId = await swetrix.getSessionId()
+   *
+   * // Pass to Paddle Checkout for revenue attribution
+   * Paddle.Checkout.open({
+   *   items: [{ priceId: 'pri_01234567890', quantity: 1 }],
+   *   customData: {
+   *     swetrix_profile_id: await swetrix.getProfileId(),
+   *     swetrix_session_id: sessionId
+   *   }
+   * })
+   * ```
+   */
+  async getSessionId(): Promise<string | null> {
+    if (!isInBrowser()) {
+      return null
+    }
+
+    try {
+      const apiBase = this.getApiBase()
+      const response = await fetch(`${apiBase}/log/session-id`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ pid: this.projectID }),
+      })
+
+      if (!response.ok) {
+        return null
+      }
+
+      const data = (await response.json()) as { sessionId: string | null }
+      return data.sessionId
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Gets the API base URL (without /log suffix).
+   */
+  private getApiBase(): string {
+    if (this.options?.apiURL) {
+      // Remove trailing /log if present
+      return this.options.apiURL.replace(/\/log\/?$/, '')
+    }
+    return DEFAULT_API_BASE
+  }
+
   private heartbeat(): void {
     if (!this.pageViewsOptions?.heartbeatOnBackground && document.visibilityState === 'hidden') {
       return
     }
 
-    const data = {
+    const data: { pid: string; profileId?: string } = {
       pid: this.projectID,
     }
 
+    if (this.options?.profileId) {
+      data.profileId = this.options.profileId
+    }
+
     this.sendRequest('hb', data)
   }
 
@@ -419,6 +767,7 @@ export class Lib {
       ca: getUTMCampaign(),
       te: getUTMTerm(),
       co: getUTMContent(),
+      profileId: this.options?.profileId,
       ...payload,
     }
 

package/src/index.ts

@@ -9,6 +9,8 @@ import {
   defaultActions,
   IErrorEventPayload,
   IPageViewPayload,
+  FeatureFlagsOptions,
+  ExperimentOptions,
 } from './Lib.js'
 
 export let LIB_INSTANCE: Lib | null = null
@@ -120,6 +122,204 @@ export function pageview(options: IPageviewOptions): void {
   LIB_INSTANCE.submitPageView(options.payload, Boolean(options.unique), {})
 }
 
+/**
+ * Fetches all feature flags for the project.
+ * Results are cached for 5 minutes by default.
+ *
+ * @param options - Options for evaluating feature flags (visitorId, attributes).
+ * @param forceRefresh - If true, bypasses the cache and fetches fresh flags.
+ * @returns A promise that resolves to a record of flag keys to boolean values.
+ *
+ * @example
+ * ```typescript
+ * const flags = await getFeatureFlags({
+ *   visitorId: 'user-123',
+ *   attributes: { cc: 'US', dv: 'desktop' }
+ * })
+ *
+ * if (flags['new-checkout']) {
+ *   // Show new checkout flow
+ * }
+ * ```
+ */
+export async function getFeatureFlags(
+  options?: FeatureFlagsOptions,
+  forceRefresh?: boolean,
+): Promise<Record<string, boolean>> {
+  if (!LIB_INSTANCE) return {}
+
+  return LIB_INSTANCE.getFeatureFlags(options, forceRefresh)
+}
+
+/**
+ * Gets the value of a single feature flag.
+ *
+ * @param key - The feature flag key.
+ * @param options - Options for evaluating the feature flag (visitorId, attributes).
+ * @param defaultValue - Default value to return if the flag is not found. Defaults to false.
+ * @returns A promise that resolves to the boolean value of the flag.
+ *
+ * @example
+ * ```typescript
+ * const isEnabled = await getFeatureFlag('dark-mode', { visitorId: 'user-123' })
+ *
+ * if (isEnabled) {
+ *   // Enable dark mode
+ * }
+ * ```
+ */
+export async function getFeatureFlag(
+  key: string,
+  options?: FeatureFlagsOptions,
+  defaultValue: boolean = false,
+): Promise<boolean> {
+  if (!LIB_INSTANCE) return defaultValue
+
+  return LIB_INSTANCE.getFeatureFlag(key, options, defaultValue)
+}
+
+/**
+ * Clears the cached feature flags, forcing a fresh fetch on the next call.
+ * Useful when you know the user's context has changed significantly.
+ */
+export function clearFeatureFlagsCache(): void {
+  if (!LIB_INSTANCE) return
+
+  LIB_INSTANCE.clearFeatureFlagsCache()
+}
+
+/**
+ * Fetches all A/B test experiments for the project.
+ * Results are cached for 5 minutes by default (shared cache with feature flags).
+ *
+ * @param options - Options for evaluating experiments.
+ * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
+ * @returns A promise that resolves to a record of experiment IDs to variant keys.
+ *
+ * @example
+ * ```typescript
+ * const experiments = await getExperiments()
+ * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
+ *
+ * // Use the assigned variant
+ * const checkoutVariant = experiments['checkout-experiment-id']
+ * if (checkoutVariant === 'new-checkout') {
+ *   showNewCheckout()
+ * } else {
+ *   showOriginalCheckout()
+ * }
+ * ```
+ */
+export async function getExperiments(
+  options?: ExperimentOptions,
+  forceRefresh?: boolean,
+): Promise<Record<string, string>> {
+  if (!LIB_INSTANCE) return {}
+
+  return LIB_INSTANCE.getExperiments(options, forceRefresh)
+}
+
+/**
+ * Gets the variant key for a specific A/B test experiment.
+ *
+ * @param experimentId - The experiment ID.
+ * @param options - Options for evaluating the experiment.
+ * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+ * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
+ *
+ * @example
+ * ```typescript
+ * const variant = await getExperiment('checkout-redesign-experiment-id')
+ *
+ * if (variant === 'new-checkout') {
+ *   // Show new checkout flow
+ *   showNewCheckout()
+ * } else if (variant === 'control') {
+ *   // Show original checkout (control group)
+ *   showOriginalCheckout()
+ * } else {
+ *   // Experiment not running or user not included
+ *   showOriginalCheckout()
+ * }
+ * ```
+ */
+export async function getExperiment(
+  experimentId: string,
+  options?: ExperimentOptions,
+  defaultVariant: string | null = null,
+): Promise<string | null> {
+  if (!LIB_INSTANCE) return defaultVariant
+
+  return LIB_INSTANCE.getExperiment(experimentId, options, defaultVariant)
+}
+
+/**
+ * Clears the cached experiments, forcing a fresh fetch on the next call.
+ * This is an alias for clearFeatureFlagsCache since experiments and flags share the same cache.
+ */
+export function clearExperimentsCache(): void {
+  if (!LIB_INSTANCE) return
+
+  LIB_INSTANCE.clearExperimentsCache()
+}
+
+/**
+ * Gets the anonymous profile ID for the current visitor.
+ * If profileId was set via init options, returns that.
+ * Otherwise, requests server to generate one from IP/UA hash.
+ *
+ * This ID can be used for revenue attribution with payment providers like Paddle.
+ *
+ * @returns A promise that resolves to the profile ID string, or null on error.
+ *
+ * @example
+ * ```typescript
+ * const profileId = await getProfileId()
+ *
+ * // Pass to Paddle Checkout for revenue attribution
+ * Paddle.Checkout.open({
+ *   items: [{ priceId: 'pri_01234567890', quantity: 1 }],
+ *   customData: {
+ *     swetrix_profile_id: profileId,
+ *     swetrix_session_id: await getSessionId()
+ *   }
+ * })
+ * ```
+ */
+export async function getProfileId(): Promise<string | null> {
+  if (!LIB_INSTANCE) return null
+
+  return LIB_INSTANCE.getProfileId()
+}
+
+/**
+ * Gets the current session ID for the visitor.
+ * Session IDs are generated server-side based on IP and user agent.
+ *
+ * This ID can be used for revenue attribution with payment providers like Paddle.
+ *
+ * @returns A promise that resolves to the session ID string, or null on error.
+ *
+ * @example
+ * ```typescript
+ * const sessionId = await getSessionId()
+ *
+ * // Pass to Paddle Checkout for revenue attribution
+ * Paddle.Checkout.open({
+ *   items: [{ priceId: 'pri_01234567890', quantity: 1 }],
+ *   customData: {
+ *     swetrix_profile_id: await getProfileId(),
+ *     swetrix_session_id: sessionId
+ *   }
+ * })
+ * ```
+ */
+export async function getSessionId(): Promise<string | null> {
+  if (!LIB_INSTANCE) return null
+
+  return LIB_INSTANCE.getSessionId()
+}
+
 export {
   LibOptions,
   TrackEventOptions,
@@ -129,4 +329,6 @@ export {
   ErrorActions,
   IErrorEventPayload,
   IPageViewPayload,
+  FeatureFlagsOptions,
+  ExperimentOptions,
 }