BrowserTracker: fix method type definitions (close #1259) (#1284)

* BrowserTracker: fix method type definitions

Per the [TypeScript
docs](https://www.typescriptlang.org/docs/handbook/2/functions.html#return-type-void),
functions that return values are type-compatible with functions declared
as having void return type; however if you're consuming these type
definitions this becomes annoying as you are required to cast `as
unknown as T` at the call sites to get the correct types actually
returned from these methods.

Author: jethron

api-docs/docs/browser-tracker/browser-tracker.api.md

@@ -72,13 +72,13 @@ export interface BrowserTracker {
     enableActivityTrackingCallback: (configuration: ActivityTrackingConfiguration & ActivityTrackingConfigurationCallback) => void;
     enableAnonymousTracking: (configuration?: EnableAnonymousTrackingConfiguration) => void;
     flushBuffer: (configuration?: FlushBufferConfiguration) => void;
-    getCookieName: (basename: string) => void;
-    getDomainSessionIndex: () => void;
-    getDomainUserId: () => void;
-    getDomainUserInfo: () => void;
+    getCookieName: (basename: string) => string;
+    getDomainSessionIndex: () => number;
+    getDomainUserId: () => string;
+    getDomainUserInfo: () => ParsedIdCookie;
     getPageViewId: () => string;
     getTabId: () => string | null;
-    getUserId: () => void;
+    getUserId: () => string | null | undefined;
     id: string;
     namespace: string;
     newSession: () => void;
@@ -267,6 +267,21 @@ export interface PageViewEvent {
     title?: string | null;
 }
 
+// @public
+export type ParsedIdCookie = [
+cookieDisabled: string,
+domainUserId: string,
+cookieCreateTs: number,
+visitCount: number,
+nowTs: number,
+lastVisitTs: number | undefined,
+sessionId: string,
+previousSessionId: string,
+firstEventId: string,
+firstEventTs: number | undefined,
+eventIndex: number
+];
+
 // @public (undocumented)
 export type Platform = "web" | "mob" | "pc" | "srv" | "app" | "tv" | "cnsl" | "iot";
 

common/changes/@snowplow/browser-tracker-core/bt-typedefs_2024-01-25-02-58.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-tracker-core",
+      "comment": "Update method signatures for BrowserTracker",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-tracker-core"
+}

common/changes/@snowplow/browser-tracker-core/bt-typedefs_2024-01-30-01-31.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-tracker-core",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-tracker-core"
+}

common/changes/@snowplow/browser-tracker/bt-typedefs_2024-01-30-01-31.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@snowplow/browser-tracker",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@snowplow/browser-tracker"
+}

libraries/browser-tracker-core/src/tracker/id_cookie.ts

@@ -30,7 +30,7 @@
 
 import { PayloadBuilder } from '@snowplow/tracker-core';
 import { v4 as uuid } from 'uuid';
-import { ClientSession } from './types';
+import { ClientSession, ParsedIdCookie } from './types';
 
 /**
  * Indices of cookie values
@@ -47,20 +47,6 @@ const cookieDisabledIndex = 0,
   firstEventTsInMsIndex = 9,
   eventIndexIndex = 10;
 
-export type ParsedIdCookie = [
-  string, // cookieDisabled
-  string, // domainUserId
-  number, // cookieCreateTs
-  number, // visitCount
-  number, // nowTs
-  number | undefined, // lastVisitTs
-  string, // sessionId
-  string, // previousSessionId
-  string, // firstEventId
-  number | undefined, // firstEventTs
-  number // eventIndex
-];
-
 export function emptyIdCookie() {
   const idCookie: ParsedIdCookie = ['1', '', 0, 0, 0, undefined, '', '', '', undefined, 0];
   return idCookie;

libraries/browser-tracker-core/src/tracker/index.ts

@@ -47,6 +47,7 @@ import {
   ClearUserDataConfiguration,
   ClientSession,
   ExtendedCrossDomainLinkerOptions,
+  ParsedIdCookie,
 } from './types';
 import {
   parseIdCookie,
@@ -59,7 +60,6 @@ import {
   updateFirstEventInIdCookie,
   visitCountFromIdCookie,
   cookiesEnabledInIdCookie,
-  ParsedIdCookie,
   clientSessionFromIdCookie,
   incrementEventIndexInIdCookie,
   emptyIdCookie,

libraries/browser-tracker-core/src/tracker/types.ts

@@ -365,6 +365,23 @@ export interface BrowserPluginConfiguration extends CorePluginConfiguration {
   plugin: BrowserPlugin;
 }
 
+/**
+ * The format of state elements stored in the `id` cookie.
+ */
+export type ParsedIdCookie = [
+  cookieDisabled: string,
+  domainUserId: string,
+  cookieCreateTs: number,
+  visitCount: number,
+  nowTs: number,
+  lastVisitTs: number | undefined,
+  sessionId: string,
+  previousSessionId: string,
+  firstEventId: string,
+  firstEventTs: number | undefined,
+  eventIndex: number
+];
+
 /**
  * The Browser Tracker
  */
@@ -383,7 +400,7 @@ export interface BrowserTracker {
    *
    * @returns Domain session index
    */
-  getDomainSessionIndex: () => void;
+  getDomainSessionIndex: () => number;
 
   /**
    * Get the current page view ID
@@ -404,28 +421,28 @@ export interface BrowserTracker {
    *
    * @returns Cookie name
    */
-  getCookieName: (basename: string) => void;
+  getCookieName: (basename: string) => string;
 
   /**
    * Get the current user ID (as set previously with setUserId()).
    *
    * @returns Business-defined user ID
    */
-  getUserId: () => void;
+  getUserId: () => string | null | undefined;
 
   /**
    * Get visitor ID (from first party cookie)
    *
    * @returns Visitor ID (or null, if not yet known)
    */
-  getDomainUserId: () => void;
+  getDomainUserId: () => string;
 
   /**
    * Get the visitor information (from first party cookie)
    *
    * @returns The domain user information array
    */
-  getDomainUserInfo: () => void;
+  getDomainUserInfo: () => ParsedIdCookie;
 
   /**
    * Override referrer

trackers/browser-tracker/src/index.ts

@@ -42,6 +42,7 @@ import {
   EventBatch,
   GetBatch,
   PostBatch,
+  ParsedIdCookie,
 } from '@snowplow/browser-tracker-core';
 import { version } from '@snowplow/tracker-core';
 
@@ -89,6 +90,7 @@ export {
   EventBatch,
   GetBatch,
   PostBatch,
+  ParsedIdCookie,
 };
 export { version };
 export * from './api';