Skip to content

📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

21.8 KB
Raw Blame
import fetch from 'node-fetch'
import { isInBrowser } from './utils'

export interface LibOptions {
  /**
   * When set to `true`, all tracking logs will be printed to console.
   */
  devMode?: boolean

  /**
   * When set to `true`, the tracking library won't send any data to server.
   * Useful for development purposes when this value is set based on `.env` var.
   */
  disabled?: boolean

  /**
   * Set a custom URL of the API server (for selfhosted variants of Swetrix).
   */
  apiURL?: string

  /**
   * If set to `true`, only unique events will be saved.
   * This param is useful when tracking single-page landing websites.
   */
  unique?: boolean

  /**
   * 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 {
  /**
   * An event identifier you want to track. This has to be a string, which:
   * 1. Contains only English letters (a-Z A-Z), numbers (0-9), underscores (_) and dots (.).
   * 2. Is fewer than 64 characters.
   * 3. Starts with an English letter.
   */
  ev: string

  /** If set to true, only 1 custom event will be saved per session */
  unique?: boolean

  /** A page that user sent data from (e.g. /home) */
  page?: string

  /** A locale of the user (e.g. en-US or uk-UA) */
  lc?: string

  /** A referrer URL (e.g. https://example.com/) */
  ref?: string

  /** A source of the event (e.g. ref, source or utm_source GET parameter) */
  so?: string

  /** A medium of the event (e.g. utm_medium GET parameter) */
  me?: string

  /** A campaign of the event (e.g. utm_campaign GET parameter) */
  ca?: string

  /**
   * Raw URL query string of the landing page (without the leading `?`).
   * Used server-side to recover the traffic source from ad/social click
   * IDs (gclid, fbclid, msclkid, ttclid, etc.) when the browser stripped
   * the referrer. UTM parameters always take precedence over click IDs.
   */
  qs?: string

  /** Event-related metadata object with string values. */
  meta?: {
    [key: string]: string | number | boolean | null | undefined
  }

  /** Optional profile ID for long-term user tracking. Overrides the global profileId if set. */
  profileId?: string
}

export interface PerformanceMetrics {
  /* DNS Resolution time */
  dns?: number

  /* TLS handshake time */
  tls?: number

  /* Connection time */
  conn?: number

  /* Response Time (Download) */
  response?: number

  /* Browser rendering the HTML page time */
  render?: number

  /* DOM loading timing */
  dom_load?: number

  /* Page load timing */
  page_load?: number

  /* Time to first byte */
  ttfb?: number
}

export interface TrackPageViewOptions {
  /**
   * Visitor's timezone (used as a backup in case IP geolocation fails). I.e. if it's set to Europe/Kiev and IP geolocation fails, we will set the country of this entry to Ukraine)
   */
  tz?: string

  /** A page to record the pageview event for (e.g. /home). All our scripts send the pg string with a slash (/) at the beginning, it's not a requirement but it's best to do the same so the data would be consistent when used together with our official scripts */
  pg?: string
  title?: string | null

  /** A locale of the user (e.g. en-US or uk-UA) */
  lc?: string

  /** A referrer URL (e.g. https://example.com/) */
  ref?: string

  /** A source of the pageview (e.g. ref, source or utm_source GET parameter) */
  so?: string

  /** A medium of the pageview (e.g. utm_medium GET parameter) */
  me?: string

  /** A campaign of the pageview (e.g. utm_campaign GET parameter) */
  ca?: string

  /**
   * Raw URL query string of the landing page (without the leading `?`).
   * Used server-side to recover the traffic source from ad/social click
   * IDs (gclid, fbclid, msclkid, ttclid, etc.) when the browser stripped
   * the referrer. UTM parameters always take precedence over click IDs.
   */
  qs?: string

  /** If set to true, only unique visits will be saved */
  unique?: boolean

  /** An object with performance metrics related to the page load. See Performance metrics for more details */
  perf?: PerformanceMetrics

  /** Pageview-related metadata object with string values. */
  meta?: {
    [key: string]: string | number | boolean | null | undefined
  }

  /** Optional profile ID for long-term user tracking. Overrides the global profileId if set. */
  profileId?: string
}

export interface TrackErrorOptions {
  /**
   * Error name (e.g. ParseError).
   */
  name: string

  /**
   * Error message (e.g. Malformed input).
   */
  message?: string | null

  /**
   * On what line in your code did the error occur (e.g. 1520)
   */
  lineno?: number | null

  /**
   * On what column in your code did the error occur (e.g. 26)
   */
  colno?: number | null

  /**
   * In what file did the error occur (e.g. https://example.com/broken.js)
   */
  filename?: string | null

  /**
   * Stack trace of the error, up to 64,000 characters.
   */
  stackTrace?: string | null

  /**
   * Visitor's timezone (used as a backup in case IP geolocation fails).
   */
  tz?: string

  /** A locale of the user (e.g. en-US or uk-UA) */
  lc?: string

  /** A page to record the error event for (e.g. /home) */
  pg?: string

  /** Error-related metadata object with string values. */
  meta?: {
    [key: string]: string | number | boolean | null | undefined
  }
}

/**
 * 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
}

/**
 * Key / value metadata describing an identified user (email, plan, signup
 * date, ...). Values are stored as strings; `null` removes a trait.
 */
export type Traits = Record<string, string | number | boolean | null>

const DEFAULT_API_HOST = 'https://api.swetrix.com/log'
const DEFAULT_API_BASE = 'https://api.swetrix.com'

/**
 * Events carry the raw, site-supplied profileId; the server stores them behind
 * this prefix. Mirrored here so getProfileId() can report the ID events are
 * actually stored under without an extra round trip.
 */
const USER_PROFILE_PREFIX = 'usr_'

const toStoredProfileId = (profileId: string) => `${USER_PROFILE_PREFIX}${profileId.trim()}`

/**
 * Server-side implementation of Swetrix tracking library.
 *
 * @param projectID Your project ID (you can find it in the project settings)
 * @param options LibOptions
 */
export class Swetrix {
  constructor(
    private projectID: string,
    private options?: LibOptions,
  ) {
    this.heartbeat = this.heartbeat.bind(this)
  }

  /**
   * This function is used to send custom events (implements https://swetrix.com/docs/events-api#post-logcustom).
   *
   * @param ip IP address of the visitor
   * @param userAgent User agent of the visitor
   * @param event TrackEventOptions
   * @returns Promise<void>
   */
  public async track(ip: string, userAgent: string, event: TrackEventOptions): Promise<void> {
    if (!this.canTrack()) {
      return
    }

    const data = {
      pid: this.projectID,
      profileId: event.profileId ?? this.options?.profileId,
      ...event,
    }
    await this.sendRequest('custom', ip, userAgent, data)
  }

  /**
   * This function is used to send pageview events (implements https://swetrix.com/docs/events-api#post-log).
   *
   * @param ip IP address of the visitor
   * @param userAgent User agent of the visitor
   * @param pageview TrackPageViewOptions
   * @returns Promise<void>
   */
  public async trackPageView(ip: string, userAgent: string, pageview?: TrackPageViewOptions): Promise<void> {
    if (!this.canTrack()) {
      return
    }

    const data = {
      pid: this.projectID,
      profileId: pageview?.profileId ?? this.options?.profileId,
      ...pageview,
    }

    if (typeof data.title === 'string') {
      data.title = data.title.slice(0, 2048)
    }

    await this.sendRequest('', ip, userAgent, data)
  }

  /**
   * This function is used to track an error event.
   * It's useful if you want to track specific errors in your application.
   *
   * @param ip IP address of the visitor
   * @param userAgent User agent of the visitor
   * @param error TrackErrorOptions
   * @returns Promise<void>
   */
  public async trackError(ip: string, userAgent: string, error?: TrackErrorOptions): Promise<void> {
    if (!this.canTrack()) {
      return
    }

    const data = {
      pid: this.projectID,
      ...error,
    }

    await this.sendRequest('error', ip, userAgent, data)
  }

  /**
   * This function is used to send heartbeat events (implements https://swetrix.com/docs/events-api#post-loghb).
   * Heartbeat events are used to determine if the user session is still active.
   * This allows you to see the 'Live Visitors' counter in the Dashboard panel.
   * It's recommended to send heartbeat events every 30 seconds.
   * We also extend the session lifetime after receiving a pageview or custom event.
   *
   * @param ip IP address of the visitor
   * @param userAgent User agent of the visitor
   * @returns Promise<void>
   */
  public async heartbeat(ip: string, userAgent: string): Promise<void> {
    if (!this.canTrack()) {
      return
    }

    const data: { pid: string; profileId?: string } = {
      pid: this.projectID,
    }

    if (this.options?.profileId) {
      data.profileId = this.options.profileId
    }

    await this.sendRequest('hb', ip, userAgent, data)
  }

  /**
   * Fetches all feature flags for the project.
   *
   * @param ip IP address of the visitor
   * @param userAgent User agent of the visitor
   * @param options Options for evaluating feature flags (profileId).
   * @returns A promise that resolves to a record of flag keys to boolean values.
   *
   * @example
   * ```typescript
   * const flags = await swetrix.getFeatureFlags('192.155.52.12', 'Mozilla/5.0...', {
   *   profileId: 'user-123'
   * })
   *
   * if (flags['new-checkout']) {
   *   // Show new checkout flow
   * }
   * ```
   */
  public async getFeatureFlags(
    ip: string,
    userAgent: string,
    options?: FeatureFlagsOptions,
  ): Promise<Record<string, boolean>> {
    try {
      const data = await this.fetchFlagsAndExperiments(ip, userAgent, options)
      return data.flags
    } catch (error) {
      this.debug(`Error fetching feature flags: ${error}`, true)
      return {}
    }
  }

  /**
   * Gets the value of a single feature flag.
   *
   * @param key The feature flag key.
   * @param ip IP address of the visitor
   * @param userAgent User agent of the visitor
   * @param options Options for evaluating the feature flag (profileId).
   * @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 swetrix.getFeatureFlag('dark-mode', '192.155.52.12', 'Mozilla/5.0...', { profileId: 'user-123' })
   *
   * if (isEnabled) {
   *   // Enable dark mode
   * }
   * ```
   */
  public async getFeatureFlag(
    key: string,
    ip: string,
    userAgent: string,
    options?: FeatureFlagsOptions,
    defaultValue: boolean = false,
  ): Promise<boolean> {
    const flags = await this.getFeatureFlags(ip, userAgent, options)
    return flags[key] ?? defaultValue
  }

  /**
   * Fetches all A/B test experiments for the project.
   *
   * @param ip IP address of the visitor
   * @param userAgent User agent of the visitor
   * @param options Options for evaluating experiments.
   * @returns A promise that resolves to a record of experiment IDs to variant keys.
   *
   * @example
   * ```typescript
   * const experiments = await swetrix.getExperiments('192.155.52.12', 'Mozilla/5.0...')
   * // 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()
   * }
   * ```
   */
  public async getExperiments(
    ip: string,
    userAgent: string,
    options?: ExperimentOptions,
  ): Promise<Record<string, string>> {
    try {
      const data = await this.fetchFlagsAndExperiments(ip, userAgent, options)
      return data.experiments
    } catch (error) {
      this.debug(`Error fetching experiments: ${error}`, true)
      return {}
    }
  }

  /**
   * Gets the variant key for a specific A/B test experiment.
   *
   * @param experimentId The experiment ID.
   * @param ip IP address of the visitor
   * @param userAgent User agent of the visitor
   * @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 swetrix.getExperiment('checkout-redesign-experiment-id', '192.155.52.12', 'Mozilla/5.0...')
   *
   * 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()
   * }
   * ```
   */
  public async getExperiment(
    experimentId: string,
    ip: string,
    userAgent: string,
    options?: ExperimentOptions,
    defaultVariant: string | null = null,
  ): Promise<string | null> {
    const experiments = await this.getExperiments(ip, userAgent, options)
    return experiments[experimentId] ?? defaultVariant
  }

  /**
   * Gets the profile ID a visitor's events are stored under.
   * If profileId was set via constructor options, returns the identified
   * (usr_-prefixed) form of it. Otherwise, requests server to generate an
   * anonymous one from IP/UA hash.
   *
   * This ID can be used for revenue attribution with payment providers like Paddle.
   *
   * @param ip IP address of the visitor
   * @param userAgent User agent of the visitor
   * @returns A promise that resolves to the profile ID string, or null on error.
   *
   * @example
   * ```typescript
   * const profileId = await swetrix.getProfileId('192.155.52.12', 'Mozilla/5.0...')
   *
   * // Pass to Paddle Checkout for revenue attribution
   * // customData: { swetrix_profile_id: profileId }
   * ```
   */
  public async getProfileId(ip: string, userAgent: string): Promise<string | null> {
    // A profileId set via the constructor is sent raw on events and prefixed
    // server-side, so return the prefixed form here too - returning the raw
    // value would not match anything in the dashboard
    if (this.options?.profileId) {
      return toStoredProfileId(this.options.profileId)
    }

    try {
      const apiBase = this.getApiBase()
      const response = await fetch(`${apiBase}/log/profile-id`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Client-IP-Address': ip,
          'User-Agent': userAgent,
        },
        body: JSON.stringify({ pid: this.projectID }),
      })

      if (!response.ok) {
        return null
      }

      const data = (await response.json()) as { profileId: string | null }
      return data.profileId
    } catch (error) {
      this.debug(`Error fetching profile ID: ${error}`, true)
      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 like Paddle.
   *
   * @param ip IP address of the visitor
   * @param userAgent User agent of the visitor
   * @returns A promise that resolves to the session ID string, or null on error.
   *
   * @example
   * ```typescript
   * const sessionId = await swetrix.getSessionId('192.155.52.12', 'Mozilla/5.0...')
   *
   * // Pass to Paddle Checkout for revenue attribution
   * // customData: { swetrix_session_id: sessionId }
   * ```
   */
  public async getSessionId(ip: string, userAgent: string): Promise<string | null> {
    try {
      const apiBase = this.getApiBase()
      const response = await fetch(`${apiBase}/log/session-id`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Client-IP-Address': ip,
          'User-Agent': userAgent,
        },
        body: JSON.stringify({ pid: this.projectID }),
      })

      if (!response.ok) {
        return null
      }

      const data = (await response.json()) as { sessionId: string | null }
      return data.sessionId
    } catch (error) {
      this.debug(`Error fetching session ID: ${error}`, true)
      return null
    }
  }

  /**
   * Identify a visitor with your own user ID (e.g. after they log in),
   * implements https://swetrix.com/docs/events-api#post-logidentify.
   *
   * The visitor's current anonymous profile (derived from their IP and user
   * agent) gets linked to the identified profile server-side, so their
   * pre-login activity is attributed to it.
   *
   * Note: unlike the browser tracker, this does NOT set a default profileId
   * for subsequent calls - a Swetrix instance is shared across all visitors
   * of your server. Keep passing `profileId` per track / trackPageView call.
   *
   * @param ip IP address of the visitor
   * @param userAgent User agent of the visitor
   * @param profileId A unique, stable identifier of the user, e.g. an internal
   * user ID. It's stored as you provide it, so don't pass values you wouldn't
   * want to see in your dashboard.
   * @param traits Optional key / value metadata to show on the user's profile,
   * e.g. their email, plan or signup date. Traits are merged with the ones
   * already stored; pass `null` to remove one.
   * @returns A promise that resolves to the identified (usr_-prefixed) profile
   * ID events are stored under, or null on error.
   */
  public async identify(ip: string, userAgent: string, profileId: string, traits?: Traits): Promise<string | null> {
    if (!this.canTrack()) {
      return null
    }

    if (typeof profileId !== 'string' || !profileId.trim()) {
      this.debug('identify() expects a non-empty string profileId', true)
      return null
    }

    try {
      const apiBase = this.getApiBase()
      const response = await fetch(`${apiBase}/log/identify`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Client-IP-Address': ip,
          'User-Agent': userAgent,
        },
        body: JSON.stringify({ pid: this.projectID, profileId: profileId.trim(), traits }),
      })

      if (!response.ok) {
        return null
      }

      const data = (await response.json()) as { profileId: string | null }
      return data.profileId
    } catch (error) {
      this.debug(`Error identifying profile: ${error}`, true)
      return null
    }
  }

  private async fetchFlagsAndExperiments(
    ip: string,
    userAgent: string,
    options?: FeatureFlagsOptions | ExperimentOptions,
  ): Promise<{ flags: Record<string, boolean>; experiments: Record<string, string> }> {
    const apiBase = this.getApiBase()
    const body: { pid: string; profileId?: string } = {
      pid: this.projectID,
    }

    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',
        'X-Client-IP-Address': ip,
        'User-Agent': userAgent,
      },
      body: JSON.stringify(body),
    })

    if (!response.ok) {
      this.debug(`Failed to fetch feature flags and experiments: ${response.status}`, true)
      return { flags: {}, experiments: {} }
    }

    const data = (await response.json()) as {
      flags: Record<string, boolean>
      experiments?: Record<string, string>
    }

    return {
      flags: data.flags || {},
      experiments: data.experiments || {},
    }
  }

  /**
   * 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 debug(message: string, force?: boolean): void {
    if (this.options?.devMode || force) {
      console.log('[Swetrix]', message)
    }
  }

  private canTrack(): boolean {
    if (this.options?.disabled) {
      this.debug("Tracking disabled: the 'disabled' setting is set to true.")
      return false
    }

    if (isInBrowser()) {
      this.debug('Tracking disabled: script runs in browser environment.')
      return false
    }

    return true
  }

  private async sendRequest(path: string, ip: string, userAgent: string, body: object): Promise<void> {
    const link = this.options?.apiURL || DEFAULT_API_HOST
    const postData = JSON.stringify(body)

    const headers = {
      'Content-Type': 'application/json',
      'X-Client-IP-Address': ip,
      'User-Agent': userAgent,
    }

    try {
      const response = await fetch(`${link}/${path}`, {
        method: 'POST',
        headers,
        body: postData,
      })

      if (!response.ok) {
        throw new Error(`Request failed with status ${response.status}`)
      }
    } catch (reason) {
      this.debug(`Error while sending request: ${reason}`, true)
      this.debug(`Request link: ${link}`, true)
      this.debug(`Request path: /${path}`, true)
      this.debug(`Request body: ${JSON.stringify(body, null, 2)}`, true)
    }
  }
}