diff --git a/tracker/index.d.ts b/tracker/index.d.ts new file mode 100644 index 00000000..67cebc08 --- /dev/null +++ b/tracker/index.d.ts @@ -0,0 +1,138 @@ +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 & { [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; +type EventProperties = { + name: string; + data?: EventData; +} & WithRequired +| WithRequired; + +interface Window { + umami: { + track: { + /** + * Track a page view + * + * @example ``` + * umami.track(); + * ``` + */ + (): Promise; + + /** + * Track an event with a given name + * + * @example ``` + * umami.track('signup-button'); + * ``` + */ + (eventName: string): Promise; + + /** + * 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; + + /** + * Tracks a page view with custom properties + * + * @example ``` + * umami.track({ website: 'e676c9b4-11e4-4ef1-a4d7-87001773e9f2', url: '/home', title: 'Home page' }); + * ``` + */ + (properties: WithRequired, 'website'>): Promise; + + /** + * 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; + }; + }; +}