From 71a11089be7267e1c3744675dab486f06b0c22e1 Mon Sep 17 00:00:00 2001 From: Jethro Nederhof Date: Wed, 31 Jan 2024 09:07:49 +1100 Subject: [PATCH] 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. --- .../browser-tracker/browser-tracker.api.md | 25 +++++++++++++---- .../bt-typedefs_2024-01-25-02-58.json | 10 +++++++ .../bt-typedefs_2024-01-30-01-31.json | 10 +++++++ .../bt-typedefs_2024-01-30-01-31.json | 10 +++++++ .../src/tracker/id_cookie.ts | 16 +---------- .../browser-tracker-core/src/tracker/index.ts | 2 +- .../browser-tracker-core/src/tracker/types.ts | 27 +++++++++++++++---- trackers/browser-tracker/src/index.ts | 2 ++ 8 files changed, 76 insertions(+), 26 deletions(-) create mode 100644 common/changes/@snowplow/browser-tracker-core/bt-typedefs_2024-01-25-02-58.json create mode 100644 common/changes/@snowplow/browser-tracker-core/bt-typedefs_2024-01-30-01-31.json create mode 100644 common/changes/@snowplow/browser-tracker/bt-typedefs_2024-01-30-01-31.json diff --git a/api-docs/docs/browser-tracker/browser-tracker.api.md b/api-docs/docs/browser-tracker/browser-tracker.api.md index 2936496d3..12d8b1a63 100644 --- a/api-docs/docs/browser-tracker/browser-tracker.api.md +++ b/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"; diff --git a/common/changes/@snowplow/browser-tracker-core/bt-typedefs_2024-01-25-02-58.json b/common/changes/@snowplow/browser-tracker-core/bt-typedefs_2024-01-25-02-58.json new file mode 100644 index 000000000..e3664a871 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/common/changes/@snowplow/browser-tracker-core/bt-typedefs_2024-01-30-01-31.json b/common/changes/@snowplow/browser-tracker-core/bt-typedefs_2024-01-30-01-31.json new file mode 100644 index 000000000..d9bb8cd2b --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/common/changes/@snowplow/browser-tracker/bt-typedefs_2024-01-30-01-31.json b/common/changes/@snowplow/browser-tracker/bt-typedefs_2024-01-30-01-31.json new file mode 100644 index 000000000..5665ac7f0 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/libraries/browser-tracker-core/src/tracker/id_cookie.ts b/libraries/browser-tracker-core/src/tracker/id_cookie.ts index 4bf7502e6..9dee95792 100644 --- a/libraries/browser-tracker-core/src/tracker/id_cookie.ts +++ b/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; diff --git a/libraries/browser-tracker-core/src/tracker/index.ts b/libraries/browser-tracker-core/src/tracker/index.ts index 0f339fda7..37e504fa2 100755 --- a/libraries/browser-tracker-core/src/tracker/index.ts +++ b/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, diff --git a/libraries/browser-tracker-core/src/tracker/types.ts b/libraries/browser-tracker-core/src/tracker/types.ts index 922e6af90..d6ce73c0f 100755 --- a/libraries/browser-tracker-core/src/tracker/types.ts +++ b/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 diff --git a/trackers/browser-tracker/src/index.ts b/trackers/browser-tracker/src/index.ts index 92b88c628..874cb58d5 100644 --- a/trackers/browser-tracker/src/index.ts +++ b/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';