@maestro_io/maestro-web-sdk 4.0.0 → 4.0.1

package/dist/src/services/InsightsService/InsightsPayloadBuilder.js

@@ -0,0 +1,386 @@
+import InsightsService from './InsightsService';
+import LocalStorageCacheManager from '@/external/LocalStorageCacheManager';
+import SDK from '@/index';
+export default class InsightsPayloadBuilder {
+    constructor() {
+        Object.defineProperty(this, "currentTime", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "serverOffsetTime", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "insightsService", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "cacheManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pageConfig", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.insightsService = new InsightsService();
+        this.cacheManager = new LocalStorageCacheManager();
+    }
+    async getPayload(event) {
+        this.currentTime = Date.now();
+        this.serverOffsetTime = await this.getDeviceOffset();
+        this.pageConfig = SDK.getPageConfig();
+        return {
+            ...this.getPageInsights(),
+            ...this.getDeviceInsights(),
+            ...this.getInsightsInsights(),
+            ...this.getMetadataInsights(),
+            ...this.getReferrerInsights(),
+            ...this.getSessionInsights(),
+            ...this.getSiteInsights(),
+            ...this.getUserInsights(),
+            ...this.getEventInsights(event),
+        };
+    }
+    getEventInsights(eventData) {
+        const ontology = eventData.ontology;
+        return {
+            /**
+             * @description Event Domain. NAMESPACE env var.
+             * @example maestro
+             */
+            e_d: 'maestro',
+            /**
+             * @description Event stringified metadata. defaults to null.
+             * @example "{\"key\":\"value\"}"
+             */
+            e_m: Object.values(eventData.metadata || {}).length > 0
+                ? JSON.stringify(eventData.metadata)
+                : null,
+            /**
+             * @description Event time accounting for offset.
+             */
+            e_t: this.currentTime + this.serverOffsetTime,
+            /**
+             * @description Event URL. defaults to undefined.
+             */
+            e_u: window.location.href,
+            /**
+             * @description Event ontology kingdom. This is the highest level of the ontology and can be used to identify the event type.
+             * @example 'panel', 'engage', 'espn_key_plays'
+             */
+            e0: ontology.kingdom,
+            /**
+             * @description Event phylum.
+             * @example 'view', 'click', 'play clip'
+             */
+            e1: ontology.phylum,
+            /**
+             * @description Event class.
+             * @example 'panel_type'
+             */
+            e2: ontology.class,
+            /**
+             * @description Event order.
+             * @example 'panel_id'
+             */
+            e3: ontology.order,
+            /**
+             * @description Event family.
+             * @example 'panel_name'
+             */
+            e4: ontology.family,
+            /**
+             * @description Event genus. This is a more specific level of the ontology and can be used to identify the event type.
+             */
+            e5: ontology.genus,
+            /**
+             * @description Event species. This is the most specific level of the ontology and can be used to identify the event type.
+             */
+            e6: ontology.species,
+            /**
+             * @description Current timestamp.
+             */
+            t: this.currentTime,
+        };
+    }
+    getPageInsights() {
+        const config = SDK.getPageConfig();
+        return {
+            /**
+             * @description MongoDB page collection name (e.g. 'pages')
+             * @example object.collection
+             */
+            p_c: 'pages',
+            /**
+             * @description MongoDB page document ID (e.g. 'pageId')
+             * @example object._id
+             */
+            p_id: config?.page._id,
+            /**
+             * @description MongoDB page name (e.g. 'Home', 'Product Page')
+             * @example object.data.name || object.seo.title
+             */
+            p_n: config?.page.name,
+            /**
+             * @description MongoDB page slug (e.g. 'home', 'product-page')
+             * @example object.slug
+             */
+            p_s: config?.page.slug,
+            /**
+             * @description MongoDB page type (e.g. 'landing', 'channel')
+             * @example object.type
+             */
+            p_t: config?.page.type,
+        };
+    }
+    getDevicePermanentID() {
+        const devicePermanentId = localStorage.getItem('mio:device:permanentId');
+        if (devicePermanentId) {
+            return devicePermanentId;
+        }
+        const newDevicePermanentId = this.randomId();
+        localStorage.setItem('mio:device:permanentId', newDevicePermanentId);
+        return newDevicePermanentId;
+    }
+    getDeviceCreated() {
+        const deviceCreated = this.cacheManager.getCache('mio:device:created');
+        if (deviceCreated) {
+            return Number(deviceCreated);
+        }
+        const now = new Date().getTime();
+        this.cacheManager.setCache('mio:device:created', now.toString());
+        return now;
+    }
+    getTabID() {
+        const tabId = sessionStorage.getItem('mio:device:tabId');
+        if (tabId) {
+            return tabId;
+        }
+        const newTabId = this.randomId();
+        sessionStorage.setItem('mio:device:tabId', newTabId);
+        return newTabId;
+    }
+    getDeviceInsights() {
+        return {
+            /**
+             * @description Device created timestamp. You might wanna keep this fixed for the device you're in using a local storage or something related
+             * @example new Date().getTime()
+             */
+            d_ct: this.getDeviceCreated(),
+            /**
+             * @description New device or not. If you want to keep track of new devices, you can use a local storage or something related
+             * @example localStorage.getItem('isNewDevice') === 'true'
+             */
+            d_nd: false,
+            /**
+             * @description Navigator Platform (more Web API specific).
+             * @example 'MacIntel', 'Win32', 'Linux x86_64'
+             * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/platform
+             */
+            d_np: window.navigator.platform,
+            /**
+             * @description A unique identifier for the device, which can be used to track the device across sessions. You might wanna save this into a local storage or something related.
+             * @example localStorage.getItem('devicePermanentId') || generateUniqueId()
+             */
+            d_pid: this.getDevicePermanentID(),
+            /**
+             * @description Device screen height in pixels.
+             * @example window.screen.height
+             */
+            d_sh: window.screen.height,
+            /**
+             * @description Device screen width in pixels.
+             * @example window.screen.width
+             */
+            d_sw: window.screen.width,
+            /**
+             * @description Device tab ID, which can be used to track the device across tabs.
+             */
+            d_tid: this.getTabID(),
+            /**
+             * @description Device time in milliseconds since epoch.
+             */
+            d_tim: this.currentTime,
+            /**
+             * @description Device time offset in milliseconds. You might wanna keep this fixed for the device you're in using a local storage or something related.
+             */
+            d_tof: this.serverOffsetTime,
+            /**
+             * @description Device user agent string.
+             * @example navigator.userAgent ('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3')
+             * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent
+             */
+            d_ua: window.navigator.userAgent,
+        };
+    }
+    randomId() {
+        return (Math.random().toString(36).substring(2, 15) +
+            Math.random().toString(36).substring(2, 15));
+    }
+    async getDeviceOffset() {
+        const responseStart = Date.now();
+        const { diff: serverOffset, time: serverTime, } = await this.insightsService.getServerTime();
+        const responseEnd = Date.now();
+        const queryTime = responseEnd - responseStart;
+        const clientOffset = responseEnd - serverTime;
+        // from NTP algo: https://en.wikipedia.org/wiki/Network_Time_Protocol
+        // JS example: https://stackoverflow.com/questions/1638337
+        // /the-best-way-to-synchronize-client-side-javascript-clock-with-server-date
+        // will account for latent response times back to client
+        return (serverOffset - queryTime - clientOffset) / 2;
+    }
+    getInsightsInsights() {
+        return {
+            /**
+             * @description Unique identifier for the insights ID. Stored in site's document.
+             * @example site.settings.services.insights_id
+             */
+            i_id: this.pageConfig?.insights._id,
+        };
+    }
+    getMetadataInsights() {
+        return {
+            /**
+             * @description Metadata version, used to track changes in the metadata structure.
+             * @example '1.00.0'
+             */
+            m_iv: '1.00.0',
+        };
+    }
+    getReferrerInsights() {
+        return {
+            /**
+             * @description Referrer domain, which can be used to track the domain from which the user came. Defaults to "$direct"
+             * @example 'example.com'.
+             */
+            r_d: '$direct',
+            /**
+             * @description Referrer source, which can be used to track the source from which the user came (queryParam.r). Defaults to null
+             * @example const urlParams = new URLSearchParams(window.location.search);
+             *              urlParams.get('r') || null
+             */
+            r_s: null,
+            /**
+             * @description Referrer URL, which can be used to track the full URL from which the user came. Defaults to "$direct"
+             * @example document.referrer
+             */
+            r_u: '$direct',
+        };
+    }
+    getSessionID() {
+        const sessionId = sessionStorage.getItem('mio:session:id');
+        if (sessionId) {
+            return sessionId;
+        }
+        const newSessionId = this.randomId();
+        sessionStorage.setItem('mio:session:id', newSessionId);
+        return newSessionId;
+    }
+    getSessionInsights() {
+        return {
+            /**
+             * @description Session ID, which can be used to track the session across requests. You might wanna keep this fixed for the session you're in using a local storage or something related.
+             */
+            se_id: this.getSessionID(),
+            /**
+             * @description Session created timestamp. Usually set when the first event is fired
+             * @example new Date().getTime()
+             */
+            se_s: this.currentTime,
+        };
+    }
+    getSiteInsights() {
+        return {
+            /**
+             * @description Site domain.
+             * @example site.settings.domain.url. 'maestro.tv/site_slug'
+             */
+            si_d: this.pageConfig?.site.domainUrl,
+            /**
+             * @description Site ID.
+             * @example site._id
+             */
+            si_id: this.pageConfig?.site._id,
+            /**
+             * @description Site package ID.
+             * @example `${site.package.id}-sapphire`
+             */
+            si_pid: `${this.pageConfig?.site.package.id}-sapphire`,
+            /**
+             * @description Site package version.
+             * @example `${site.package.version}-sapphire`
+             */
+            si_pv: `${this.pageConfig?.site.package.version}-sapphire`,
+            /**
+             * @description Site slug.
+             * @example site.slug
+             */
+            // TODO: grab from page config when available
+            si_s: 'espn',
+        };
+    }
+    getUserInsights() {
+        return {
+            /**
+             * @description User avatar URL. Stored in user profile. defaults to null
+             * @example GET 'https://api.maestro.io/userprofile/v1'
+             */
+            u_a: null,
+            /**
+             * @description User account created date in milliseconds since epoch. defaults to null
+             * @example account.created
+             */
+            u_c: null,
+            /**
+             * @description Logged User email. defaults to null
+             * @example account.email
+             */
+            u_e: null,
+            /**
+             * @description Logged User ID. defaults to null
+             * @example account._id
+             */
+            u_id: null,
+            /**
+             * @description Logged User is logged in or not. defaults to false
+             */
+            u_li: false,
+            /**
+             * @description Logged User name. defaults to null
+             * @example account.name
+             */
+            u_n: null,
+            /**
+             * @description Logged User new user or not. Usually we compare server time and account.created. If it was created less than 1 day ago it's a new user. defaults to false
+             * @example Math.abs((serverTime || Date.now()) - account.created) < msIn.day
+             */
+            u_nu: false,
+            /**
+             * @description Logged User service. defaults to null
+             * @example account.service
+             */
+            u_s: null,
+            /**
+             * @description Logged User UID. defaults to null
+             * @example account.uid
+             */
+            u_u: null,
+            /**
+             * @description Logged User name. defaults to null
+             * @example account.name
+             */
+            u_un: null,
+        };
+    }
+}

package/dist/src/services/InsightsService/InsightsService.d.ts

@@ -0,0 +1,11 @@
+export default class InsightsService {
+    private client;
+    constructor();
+    private isEnabled;
+    action(payload: Record<string, unknown>): Promise<void>;
+    getServerTime(): Promise<{
+        time: number;
+        diff: number;
+    }>;
+    private randomId;
+}

package/dist/src/services/InsightsService/InsightsService.js

@@ -0,0 +1,74 @@
+import AxiosNetworkClient from '@/external/AxiosNetworkClient';
+import SDK from '@/index';
+import { captureException } from '@/sentry';
+const INSIGHTS_BASE_URL = 'https://insights.maestro.io';
+export default class InsightsService {
+    constructor() {
+        Object.defineProperty(this, "client", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.client = new AxiosNetworkClient({
+            baseURL: INSIGHTS_BASE_URL,
+            backoff: 2,
+            delay: 1000,
+            retries: 1,
+        });
+    }
+    isEnabled() {
+        const globalConfig = SDK.getGlobalConfig();
+        const analyticsEnabled = globalConfig?.bbd?.analytics?.enabled ?? true;
+        return analyticsEnabled;
+    }
+    async action(payload) {
+        if (!this.isEnabled()) {
+            console.warn('InsightsService: Analytics is disabled in global config');
+            return;
+        }
+        try {
+            // do like qs.stringify with my payload and send as formData
+            const parsedData = new URLSearchParams();
+            for (const [key, value] of Object.entries(payload)) {
+                if (value !== undefined && value !== null) {
+                    parsedData.append(key, value.toString());
+                }
+            }
+            await this.client.post('/action', parsedData, undefined, {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            });
+        }
+        catch (err) {
+            captureException(err, { payload });
+            console.error('Failed to send insights action:', err);
+        }
+    }
+    async getServerTime() {
+        if (!this.isEnabled()) {
+            return {
+                time: Date.now(),
+                diff: 0,
+            };
+        }
+        const responseStart = Date.now();
+        try {
+            return await this.client.get('/time', {
+                _: `${Date.now()}-${this.randomId()}`,
+                client_time: responseStart,
+            });
+        }
+        catch (err) {
+            captureException(err);
+            console.error('Failed to get server time:', err);
+            return {
+                time: Date.now(),
+                diff: 0,
+            };
+        }
+    }
+    randomId() {
+        return (Math.random().toString(36).substring(2, 15) +
+            Math.random().toString(36).substring(2, 15));
+    }
+}

package/dist/src/services/NetworkManager/NetworkManager.d.ts

@@ -0,0 +1,147 @@
+import { ICacheManager } from '../../external/ports/cacheManager';
+import { INetworkClient } from '../../external/ports/networkClient';
+export declare const MAESTRO_BASE_URL = "https://api.maestro.io";
+export declare const SDK_FLAVOR = "MaestroKit_Web";
+export declare const ENDPOINTS: {
+    CAN_I_PLAY: string;
+    STREAM: string;
+    USER_PROFILE: string;
+    ACTIVE_USER: string;
+};
+export declare const HttpMethod: {
+    readonly GET: "GET";
+    readonly POST: "POST";
+    readonly PUT: "PUT";
+    readonly DELETE: "DELETE";
+};
+export type HttpMethod = typeof HttpMethod[keyof typeof HttpMethod];
+export interface NetworkManagerOptions {
+    networkClient?: INetworkClient;
+    externalNetworkClient?: INetworkClient;
+    externalBaseURL?: string;
+    cacheManager?: ICacheManager;
+    defaultCacheDuration?: number;
+}
+declare class NetworkManager {
+    private cacheManager;
+    private maestroClient;
+    private externalClient;
+    private pollingTasks;
+    private localStorage;
+    constructor(options?: NetworkManagerOptions, localStorageOverride?: Storage);
+    /**
+     * Set authentication for Maestro APIs
+     */
+    setAuthentication(token: string | null, apiKey: string | null): void;
+    /**
+     * Handle errors from network requests
+     */
+    private handleError;
+    /**
+     * Make a request to the Maestro API
+     */
+    maestroApiRequest<T = any>({ endpoint, method, params, data, headers, useCache, maestroDefaultHeaders, skipResponseBodyDeserialization, }: {
+        endpoint: string;
+        method?: HttpMethod;
+        params?: Record<string, any>;
+        data?: any;
+        headers?: Record<string, string>;
+        useCache?: boolean;
+        maestroDefaultHeaders?: {
+            siteId: string;
+            jwt: string;
+        } | null;
+        skipResponseBodyDeserialization?: boolean;
+    }): Promise<T>;
+    /**
+     * Make a request to an external API
+     */
+    externalApiRequest<T = any>({ endpoint, method, params, data, headers, useCache, skipResponseBodyDeserialization, }: {
+        endpoint: string;
+        method?: HttpMethod;
+        params?: Record<string, any>;
+        data?: any;
+        headers?: Record<string, string>;
+        useCache?: boolean;
+        skipResponseBodyDeserialization?: boolean;
+    }): Promise<T>;
+    /**
+     * Make a request to an external API and return both data and headers
+     */
+    externalApiRequestWithHeaders<T = any>({ endpoint, method, params, data, headers, useCache, skipResponseBodyDeserialization, }: {
+        endpoint: string;
+        method?: HttpMethod;
+        params?: Record<string, any>;
+        data?: any;
+        headers?: Record<string, string>;
+        useCache?: boolean;
+        skipResponseBodyDeserialization?: boolean;
+    }): Promise<{
+        data: T;
+        headers: Record<string, string>;
+    }>;
+    /**
+     * Start polling a Maestro API endpoint at specified interval
+     */
+    pollMaestroApiRequest<T = any>({ endpoint, interval, method, params, data, headers, maestroDefaultHeaders, skipResponseBodyDeserialization, onData, onError, }: {
+        endpoint: string;
+        interval: number;
+        method?: HttpMethod;
+        params?: Record<string, any>;
+        data?: any;
+        headers?: Record<string, string>;
+        maestroDefaultHeaders?: {
+            siteId: string;
+            jwt: string;
+        } | null;
+        skipResponseBodyDeserialization?: boolean;
+        onData: (data: T) => void;
+        onError?: (error: Error) => void;
+    }): {
+        stop: () => void;
+    };
+    /**
+     * Start polling an external API endpoint at specified interval
+     */
+    pollExternalApiRequest<T = any>({ endpoint, interval, method, params, data, headers, skipResponseBodyDeserialization, onData, onError, }: {
+        endpoint: string;
+        interval: number;
+        method?: HttpMethod;
+        params?: Record<string, any>;
+        data?: any;
+        headers?: Record<string, string>;
+        skipResponseBodyDeserialization?: boolean;
+        onData: (data: T) => void;
+        onError?: (error: Error) => void;
+    }): {
+        stop: () => void;
+    };
+    /**
+     * Start polling an external API endpoint at specified interval and return both data and headers
+     */
+    pollExternalApiRequestWithHeaders<T = any>({ endpoint, interval, method, params, data, headers, skipResponseBodyDeserialization, onData, onError, }: {
+        endpoint: string;
+        interval: number;
+        method?: HttpMethod;
+        params?: Record<string, any>;
+        data?: any;
+        headers?: Record<string, string>;
+        skipResponseBodyDeserialization?: boolean;
+        onData: (data: {
+            data: T;
+            headers: Record<string, string>;
+        }) => void;
+        onError?: (error: Error) => void;
+    }): {
+        stop: () => void;
+    };
+    /**
+     * Stop all polling tasks
+     */
+    stopAllPolling(): void;
+    /**
+     * Clear all cached data
+     */
+    clearAllCache(): void;
+}
+export default NetworkManager;