umami/tracker/index.d.ts

type TrackedProperties = {
  /**
   * Hostname of server
   *
   * @description extracted from `window.location.hostname`
   * @example 'analytics.umami.is'
   */
  hostname: string;

  /**
   * Browser language
   *
   * @description extracted from `window.navigator.language`
   * @example 'en-US', 'fr-FR'
   */
  language: string;

  /**
   * Page referrer
   *
   * @description extracted from `window.navigator.language`
   * @example 'https://analytics.umami.is/docs/getting-started'
   */
  referrer: string;

  /**
   * Screen dimensions
   *
   * @description extracted from `window.screen.width` and `window.screen.height`
   * @example '1920x1080', '2560x1440'
   */
  screen: string;

  /**
   * Page title
   *
   * @description extracted from `document.querySelector('head > title')`
   * @example 'umami'
   */
  title: string;

  /**
   * Page url
   *
   * @description built from `${window.location.pathname}${window.location.search}`
   * @example 'docs/getting-started'
   */
  url: string;

  /**
   * Website ID (required)
   *
   * @example 'b59e9c65-ae32-47f1-8400-119fcf4861c4'
   */
  website: string;
};

type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] }

/**
 *
 * Event Data can work with any JSON data. There are a few rules in place to maintain performance.
 * - Numbers have a max precision of 4.
 * - Strings have a max length of 500.
 * - Arrays are converted to a String, with the same max length of 500.
 * - Objects have a max of 50 properties. Arrays are considered 1 property.
 */
type EventData = Record<string, object>;
type EventProperties = {
  name: string;
  data?: EventData;
} & WithRequired<TrackedProperties, 'website'>
| WithRequired<TrackedProperties, 'website'>;

interface Window {
  umami: {
    track: {
      /**
       * Track a page view
       *
       * @example ```
       * umami.track();
       * ```
       */
      (): Promise<string>;

      /**
       * Track an event with a given name
       *
       * @example ```
       * umami.track('signup-button');
       * ```
       */
      (eventName: string): Promise<string>;

      /**
       * Tracks an event with dynamic data.
       *
       * When tracking events, the default properties are included in the payload. This is equivalent to running:
       *
       * ```js
       * umami.track(props => ({
       *   ...props,
       *   name: 'signup-button',
       *   data: {
       *     name: 'newsletter',
       *     id: 123
       *   }
       * }));
       * ```
       *
       * @example ```
       * umami.track('signup-button', { name: 'newsletter', id: 123 });
       * ```
       */
      (eventName: string, obj: EventData): Promise<string>;

      /**
       * Tracks a page view with custom properties
       *
       * @example ```
       * umami.track({ website: 'e676c9b4-11e4-4ef1-a4d7-87001773e9f2', url: '/home', title: 'Home page' });
       * ```
       */
      (properties: WithRequired<Partial<TrackedProperties>, 'website'>): Promise<string>;

      /**
       * Tracks an event with fully customizable dynamic data
       * Ilf you don't specify any `name` and/or `data`, it will be treated as a page view
       *
       * @example ```
       * umami.track((props) => ({ ...props, url: path }));
       * ```
       */
      (eventFunction: (prop: TrackedProperties) => EventProperties): Promise<string>;
    };
  };
}