@guardian/ophan-tracker-js 2.1.1-next.1 → 2.1.2-next.0

package/package.json

@@ -1,33 +1,40 @@
 {
 	"name": "@guardian/ophan-tracker-js",
-	"version": "2.1.1-next.1",
+	"version": "2.1.2-next.0",
 	"type": "module",
 	"engines": {
 		"node": ">=16"
 	},
 	"files": [
-		"dist/**/*.js",
-		"dist/**/*.d.ts"
+		"NPM-dist/**/*.js",
+		"NPM-dist/**/*.d.ts"
 	],
-	"main": "dist/assets/ng.js",
+	"main": "NPM-dist/ng.js",
+	"types": "NPM-dist/types/ng.d.ts",
 	"devDependencies": {
-		"@babel/preset-env": "7.22.10",
+		"@babel/preset-env": "^7.22.10",
+		"@babel/preset-typescript": "^7.24.7",
 		"@changesets/cli": "^2.26.2",
 		"@guardian/prettier": "^7.0.0",
 		"@rollup/plugin-babel": "6.0.3",
 		"@rollup/plugin-terser": "0.4.3",
 		"@rollup/plugin-typescript": "^11.1.6",
+		"@types/jest": "^29.5.12",
+		"babel-jest": "^29.7.0",
 		"jest": "^29.7.0",
 		"jest-environment-jsdom": "^29.7.0",
 		"rollup": "3.28.0",
 		"rollup-jest": "^3.1.0",
+		"ts-jest": "^29.1.4",
 		"typescript": "^5.4.4"
 	},
 	"scripts": {
-		"build": "NODE_ENV=production npx rollup -c",
-		"build:test": "NODE_ENV=test npx rollup -c",
-		"build-types": "tsc",
+		"build-for-cdn": "NODE_ENV=production npx rollup -c",
+		"build-for-npm": "tsc",
 		"test": "jest",
 		"format": "npx prettier --write ."
+	},
+	"dependencies": {
+		"@guardian/tsconfig": "^1.0.0"
 	}
 }

package/readme.md

@@ -42,15 +42,15 @@ You can see example usage of the library on theguardian.com [here](https://githu
 
 ### Usage with Typescript
 
-Refer to the type definitions within the library for the structure of valid tracking events.  The `ophan.record()` function accepts a type of `EventPayload` found [here](linktotypes). 
+Refer to the type definitions within the library for the structure of valid tracking events.  The `ophan.record()` function accepts a type of `EventPayload` found [here]("./types/event.ts#L95"). 
 
 #### Example Usage
 
 ```typescript
-import ophan, { Product, ComponentEvent, ComponentType } from '@guardian/ophan-tracker-js';
-import type { TProduct, AbTest } from '@guardian/ophan-tracker-js';
+import ophan, { Product, ComponentEvent } from '@guardian/ophan-tracker-js';
+import type { AbTest } from '@guardian/ophan-tracker-js';
 
-const exampleProduct: TProduct = Product.APP_PREMIUM_TIER;
+const exampleProduct: TProduct = "APP_PREMIUM_TIER";
 const exampleAbTest: AbTest = {
    name: "myAbTest",
    variant: "variant",
@@ -58,7 +58,7 @@ const exampleAbTest: AbTest = {
 };
 
 const componentV2 = {
-   componentType: ComponentType.ACQUISITIONS_BUTTON,
+   componentType: "ACQUISITIONS_BUTTON",
    id: "component-id",
    products: new Set([exampleProduct]),
    campaignCode: "campaign-code",
@@ -89,16 +89,16 @@ The backend of tracker exposes two endpoints, `img/1` which takes in page view e
 
 # Developing Ophan Tracker JS
 
-The library is implemented using both Javascript and TypeScript, with the source code located in the `assets` directory and its subdirectories. The project is set up to include both TypeScript (.ts) and JavaScript (.js) files, allowing for a mix of both languages in the library's implementation.
+The library is implemented using both Javascript and TypeScript, with the source code located in the `src` directory and its subdirectories. The project is set up to include both TypeScript (.ts) and JavaScript (.js) files, allowing for a mix of both languages in the library's implementation.
 
-Typescript interfaces and types can be developed in the `types` folder. These can then be imported into the Javascript source code and used to type certain functions or re-exported for consumers. This means we don't have to maintain separate types for each function in the JS source code. Please refer to `ng.js` for an example of how to do this.
+Typescript interfaces and types are developed in the `types` folder.
 
 The TypeScript compiler is configured to generate compiled JavaScript files and corresponding declaration files (.d.ts) in the ./dist directory. The declaration files provide type information for the library's public API. The compiler also generates source map files for the declaration files.
 
 ## Compile
 
 ```
-    .../ophan/tracker-js $ npm run build-types
+    .../ophan/tracker-js $ npm run build-for-npm
 ```
 
 #### Proxy tracker-js:
@@ -153,4 +153,4 @@ We use `changesets` for automated publishing of the NPM package:
 
 ##### Rollup
 
-The generated files from Rollup (using the `build` script in `package.json`) are only used for publishing to the CDN to use SystemJS / AMD
+The generated files from Rollup (using the `build-for-cdn` script in `package.json`) are only used for publishing to the CDN to use SystemJS / AMD

package/dist/assets/adblock-detection.d.ts

@@ -1,5 +0,0 @@
-declare namespace _default {
-    function run(): Promise<any>;
-}
-export default _default;
-//# sourceMappingURL=adblock-detection.d.ts.map

package/dist/assets/adblock-detection.js

@@ -1,20 +0,0 @@
-import abd from './vendor/adBlockDetectionLib.js';
-export default {
-    run() {
-        return new Promise((resolve, reject) => {
-            if (abd.init) {
-                try {
-                    abd.init({
-                        complete: resolve,
-                    });
-                }
-                catch (error) {
-                    reject(error);
-                }
-            }
-            else {
-                reject(new Error('Failed to initialise adblock detection'));
-            }
-        });
-    },
-};

package/dist/assets/attention.d.ts

@@ -1,10 +0,0 @@
-declare namespace _default {
-    export { initAttention as init };
-    export { initComponent };
-    export { setEventEmitter };
-}
-export default _default;
-declare function initAttention(visibility: any): void;
-declare function initComponent(name: any, el: any, visibilityThreshold?: number): void;
-declare function setEventEmitter(emitter: any): void;
-//# sourceMappingURL=attention.d.ts.map

package/dist/assets/attention.js

@@ -1,126 +0,0 @@
-// Generated by CoffeeScript 2.7.0
-import transmit from './transmit.js';
-import components from './components.js';
-// The upworthy definition of attention minutes, from
-// http://upworthy.github.io/2014/06/implementing-attention-minutes-part-1/ :
-// "We consider the page to have the user’s attention if
-//  1. some activity is happening on the page. For our purposes this means:
-//     1. the page currently has focus
-//     2. and the user has interacted with the page within a certain timeout
-//  2. or a video is playing on the page
-//  Attention Minutes, then, are the total number of minutes that a user has spent on
-//  a page where the above conditions have held true."
-// our definition of "within a certain timeout" above:
-const ATTENTIONDECAY = 5000;
-// our definition of "the user has interacted with the page"
-const EVENTS = [
-    'focus',
-    'click',
-    'scroll',
-    'mousemove',
-    'touchstart',
-    'touchend',
-    'touchcancel',
-    'touchleave',
-    'touchmove',
-    'keyup',
-    'keydown',
-];
-const REPORTINGINTERVAL = 10000;
-// total attention time so far on this page
-let totalAttentionMs = 0;
-// the time elapsed since the time origin (https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#the_time_origin)
-// when the most recent period of attention (that is, attention
-// which we haven't yet added to totalAttentionMs) began.
-// null if we don't have attention.
-let unrecordedAttentionStarted = null;
-// the attention time we last reported to ophan
-let reportedTotalAttentionMs = null; // setting null here forces a first report of attention time, even if it's only 0ms
-// the decay timer if we've set one
-let decayTimerId = null;
-// is video currently playing?
-let videoPlaying = false;
-const cancelDecayTimer = () => {
-    if (decayTimerId != null) {
-        window.clearTimeout(decayTimerId);
-    }
-    decayTimerId = null;
-};
-const makeActive = () => {
-    if (unrecordedAttentionStarted == null) {
-        unrecordedAttentionStarted = performance.now();
-    }
-    components.startMonitoring();
-    cancelDecayTimer();
-    decayTimerId = window.setTimeout(() => {
-        if (!videoPlaying) {
-            makeInactive();
-        }
-    }, ATTENTIONDECAY);
-};
-const incrementTotalAttentionTimeByUnrecordedAmount = () => {
-    if (unrecordedAttentionStarted != null) {
-        const now = performance.now();
-        const unrecordedMs = Math.min(now - unrecordedAttentionStarted, REPORTINGINTERVAL);
-        totalAttentionMs += unrecordedMs;
-        unrecordedAttentionStarted = now;
-    }
-};
-const makeInactive = () => {
-    cancelDecayTimer();
-    components.stopMonitoring();
-    incrementTotalAttentionTimeByUnrecordedAmount();
-    unrecordedAttentionStarted = null;
-};
-const reporter = () => {
-    incrementTotalAttentionTimeByUnrecordedAmount();
-    if (totalAttentionMs !== reportedTotalAttentionMs) {
-        const report = {
-            attentionMs: Math.round(totalAttentionMs),
-        };
-        const componentAttentionTimes = components.getAttentionTimes();
-        if (Object.keys(componentAttentionTimes).length) {
-            report.componentAttentionMs = componentAttentionTimes;
-        }
-        transmit.sendMore(report);
-        reportedTotalAttentionMs = totalAttentionMs;
-    }
-};
-const initComponent = (name, el, visibilityThreshold = 0.5) => {
-    components.registerComponent(name, el, visibilityThreshold, REPORTINGINTERVAL);
-};
-const initAttention = (visibility) => {
-    EVENTS.forEach((event) => {
-        window.addEventListener(event, makeActive);
-    });
-    document.addEventListener(visibility.changeEvent, () => {
-        if (visibility.state() === 'visible') {
-            makeActive();
-        }
-        else {
-            makeInactive();
-        }
-    }, false);
-    document.addEventListener('videoPlaying', () => {
-        videoPlaying = true;
-        makeActive();
-    });
-    document.addEventListener('videoEnded', () => {
-        videoPlaying = false;
-        makeInactive();
-    });
-    document.addEventListener('videoPause', () => {
-        videoPlaying = false;
-        makeInactive();
-    });
-    window.setTimeout(reporter, 100);
-    window.setInterval(reporter, REPORTINGINTERVAL);
-};
-const setEventEmitter = (emitter) => {
-    components.setEventEmitter(emitter);
-};
-export default {
-    init: initAttention,
-    initComponent: initComponent,
-    setEventEmitter: setEventEmitter,
-};

package/dist/assets/campaign.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=campaign.d.ts.map

package/dist/assets/campaign.js

@@ -1,23 +0,0 @@
-// Generated by CoffeeScript 2.7.0
-import transmit from './transmit.js';
-import perf from './perf.js';
-const start = perf?.timing?.domComplete ?? performance.now();
-// DFP ads
-if (typeof googletag !== 'undefined' && googletag !== null) {
-    googletag.cmd.push(() => {
-        googletag.pubads().addEventListener('slotRenderEnded', (event) => {
-            const slotId = event.slot.getSlotId().getDomId();
-            transmit.sendMore({
-                ads: [
-                    {
-                        slot: slotId,
-                        campaignId: event.isEmpty ? '__empty__' : event.lineItemId,
-                        creativeId: event.creativeId,
-                        timeToRenderEnded: Math.round(performance.now() - start),
-                        adServer: 'DFP',
-                    },
-                ],
-            });
-        });
-    });
-}

package/dist/assets/click-path-capture.d.ts

@@ -1,15 +0,0 @@
-export function validAncestorAnchorElement(el: Element): Element | null;
-export function getContainingComponent(el: Element): string | null;
-declare namespace _default {
-    export { getDataLinkNames };
-}
-export default _default;
-/**
- * Collects all `data-link-name` attribute values from the ancestor elements.
- *
- * @param {Element} el - The element to start searching from.
- * @param {string[]} dataLinkNames - Initial array of data link names (optional).
- * @returns {string[]} Array of `data-link-name` values.
- */
-declare function getDataLinkNames(el: Element, dataLinkNames?: string[]): string[];
-//# sourceMappingURL=click-path-capture.d.ts.map

package/dist/assets/click-path-capture.js

@@ -1,68 +0,0 @@
-import ophan from './core.js';
-import transmit from './transmit.js';
-/**
- * Finds the closest ancestor anchor (`<a>`) element of the given element.
- *
- * @param {Element} el - The element to start searching from.
- * @returns {Element|null} The closest ancestor anchor element or null if none found.
- */
-export const validAncestorAnchorElement = (el) => {
-    if (!el || el.nodeName?.toLowerCase() === 'body')
-        return null;
-    return el.nodeName.toLowerCase() === 'a'
-        ? el
-        : validAncestorAnchorElement(el.parentNode);
-};
-/**
- * Retrieves the value of the `data-component` attribute from the closest ancestor.
- *
- * @param {Element} el - The element to start searching from.
- * @returns {string|null} The `data-component` attribute value or null if not found.
- */
-export const getContainingComponent = (el) => {
-    if (!el || el.nodeName?.toLowerCase() === 'body')
-        return null;
-    return (el.getAttribute('data-component') || getContainingComponent(el.parentNode));
-};
-/**
- * Collects all `data-link-name` attribute values from the ancestor elements.
- *
- * @param {Element} el - The element to start searching from.
- * @param {string[]} dataLinkNames - Initial array of data link names (optional).
- * @returns {string[]} Array of `data-link-name` values.
- */
-const getDataLinkNames = (el, dataLinkNames = []) => {
-    if (!el || el === document.body || el === document)
-        return dataLinkNames;
-    const dataLinkName = el.getAttribute('data-link-name');
-    if (dataLinkName)
-        dataLinkNames.push(dataLinkName);
-    return getDataLinkNames(el.parentNode, dataLinkNames);
-};
-if (typeof document.addEventListener === 'function') {
-    document.addEventListener('click', function (e) {
-        let anchorTarget, info;
-        anchorTarget = validAncestorAnchorElement(e.target);
-        info = {
-            from: [location.protocol, '//', location.host, location.pathname].join(''),
-            to: anchorTarget ? anchorTarget.href : void 0,
-            referringComponent: getContainingComponent(e.target),
-            referringDataLinkNames: getDataLinkNames(e.target),
-            refPlatform: ophan.servingPlatform(),
-            refViewId: ophan.viewId,
-        };
-        if (info.referringDataLinkNames != null) {
-            transmit.sendMore({
-                clickComponent: info.referringComponent,
-                clickLinkNames: info.referringDataLinkNames,
-            });
-        }
-        if (anchorTarget != null) {
-            // then we may be about to navigate away from this page, so store to send on next request
-            return ophan.storeDataToSendOnNextEvent(info);
-        }
-    }, false);
-}
-export default {
-    getDataLinkNames: getDataLinkNames,
-};

package/dist/assets/components.d.ts

@@ -1,61 +0,0 @@
-/**
- * @type {Component[]}
- */
-export const components: Component[];
-declare namespace _default {
-    export function setEventEmitter(emitter: Object): Object;
-    export { startMonitoring };
-    export { stopMonitoring };
-    export { getAttentionTimes };
-    export let registerComponent: (...args: [name: string, element: HTMLElement, visibilityThreshold1: number, reportingInterval1: number]) => void;
-}
-export default _default;
-declare class Component {
-    /**
-     * Component constructor.
-     * @param {string} name - The name of the component.
-     * @param {HTMLElement} element - The DOM element of the component.
-     * @param {number} visibilityThreshold1 -
-     *    visibilityThreshold represents the fraction of each component that must
-     *    be in the viewport before it is considered visible.
-     *    e.g. 0.5 means that half the height or width must be in the viewport
-     *    1 means that the entire element must be in the viewport
-     * @param {number} reportingInterval1 - ??
-     */
-    constructor(name: string, element: HTMLElement, visibilityThreshold1: number, reportingInterval1: number);
-    name: string;
-    element: HTMLElement;
-    visibilityThreshold: number;
-    reportingInterval: number;
-    visible: boolean;
-    totalAttentionMs: number;
-    unrecordedAttentionStarted: number | null;
-    reportedTotalAttentionMs: number;
-    usingEmitter: boolean;
-    visCheck: () => number | null | undefined;
-    isVisible(threshold?: number): boolean;
-    visibilityHasChanged(): boolean;
-    rebindToEventEmitter(): any;
-    checkVisibility(): number | null | undefined;
-    makeActive(): number;
-    makeInactive(): null;
-    hadAttentionSinceLastGet(): boolean;
-    getAttentionTime(): number;
-    incrementTotalAttentionTimeByUnrecordedAmount(): number | undefined;
-}
-/**
- * Begins monitoring the components on the page for attention time.
- * @returns {Array} Array of results from makeActive() for each visible component.
- */
-declare function startMonitoring(): any[];
-/**
- * Stops monitoring the components on the page for attention time.
- * @returns {Array} Array of results from makeInactive() for each component.
- */
-declare function stopMonitoring(): any[];
-/**
- * Retrieves the attention times for all components.
- * @returns {Object}
- */
-declare function getAttentionTimes(): Object;
-//# sourceMappingURL=components.d.ts.map

package/dist/assets/components.js

@@ -1,168 +0,0 @@
-/**
- * @type {Component[]}
- */
-export const components = [];
-/**
- * theguardian.com uses a custom scroll event for performance reasons.
- * We pass in the event emitter so that we can listen to this custom scroll event.
- * If not on theguardian.com, we default to the native scroll event
- * @type {Object|null}
- */
-let eventEmitter = null;
-// Tracks attention time of elements on the page with data-component attributes.
-// This should always be less than or equal to the page attention time.
-// If the page does not have attention, no component has attention.
-// If the page does have attention, a given component *may* also have
-// attention, if it is within the viewport and not hidden.
-class Component {
-    /**
-     * Component constructor.
-     * @param {string} name - The name of the component.
-     * @param {HTMLElement} element - The DOM element of the component.
-     * @param {number} visibilityThreshold1 -
-     *    visibilityThreshold represents the fraction of each component that must
-     *    be in the viewport before it is considered visible.
-     *    e.g. 0.5 means that half the height or width must be in the viewport
-     *    1 means that the entire element must be in the viewport
-     * @param {number} reportingInterval1 - ??
-     */
-    constructor(name, element, visibilityThreshold1, reportingInterval1) {
-        this.name = name;
-        this.element = element;
-        this.visibilityThreshold = visibilityThreshold1;
-        this.reportingInterval = reportingInterval1;
-        this.visible = false;
-        // total attention time so far for this element
-        this.totalAttentionMs = 0;
-        // the time elapsed since the time origin (https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#the_time_origin)
-        // when the most recent period of attention (that is, attention
-        // which we haven't yet added to totalAttentionMs) began.
-        // null if we don't have attention.
-        this.unrecordedAttentionStarted = null;
-        // the attention time when getAttentionTime() was last called
-        this.reportedTotalAttentionMs = 0;
-        this.usingEmitter = false;
-        this.visCheck = this.checkVisibility.bind(this);
-        if (eventEmitter != null) {
-            this.usingEmitter = true;
-            eventEmitter.on('window:throttledScroll', this.visCheck);
-        }
-        else {
-            window.addEventListener('scroll', this.visCheck);
-        }
-        window.addEventListener('resize', this.visCheck);
-    }
-    isVisible(threshold = 1) {
-        if (!this.element.offsetParent) {
-            // exclude hidden elements
-            // will also exclude position: fixed elements but we don't care about these
-            // (because their attention time would always be the same as the whole page)
-            // https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetParent
-            return false;
-        }
-        const box = this.element.getBoundingClientRect();
-        const width = box.width;
-        const height = box.height;
-        const windowHeight = window.innerHeight || document.documentElement.clientHeight;
-        const windowWidth = window.innerWidth || document.documentElement.clientWidth;
-        return (box.left >= -(width * (1 - threshold)) &&
-            box.top >= -(height * (1 - threshold)) &&
-            box.right <= windowWidth + width * (1 - threshold) &&
-            box.bottom <= windowHeight + height * (1 - threshold));
-    }
-    visibilityHasChanged() {
-        const wasVisible = this.visible;
-        this.visible = this.isVisible(this.visibilityThreshold);
-        return wasVisible !== this.visible;
-    }
-    rebindToEventEmitter() {
-        if (!this.usingEmitter && eventEmitter != null) {
-            window.removeEventListener('scroll', this.visCheck);
-            this.usingEmitter = true;
-            return eventEmitter.on('window:throttledScroll', this.visCheck);
-        }
-    }
-    checkVisibility() {
-        this.rebindToEventEmitter();
-        if (this.visibilityHasChanged()) {
-            return this.visible ? this.makeActive() : this.makeInactive();
-        }
-    }
-    makeActive() {
-        // mark when the latest period of attention began,
-        // if we're not already in an attention period
-        return this.unrecordedAttentionStarted != null
-            ? this.unrecordedAttentionStarted
-            : (this.unrecordedAttentionStarted = performance.now());
-    }
-    makeInactive() {
-        this.incrementTotalAttentionTimeByUnrecordedAmount();
-        return (this.unrecordedAttentionStarted = null);
-    }
-    hadAttentionSinceLastGet() {
-        this.incrementTotalAttentionTimeByUnrecordedAmount();
-        return this.totalAttentionMs !== this.reportedTotalAttentionMs;
-    }
-    getAttentionTime() {
-        this.incrementTotalAttentionTimeByUnrecordedAmount();
-        this.reportedTotalAttentionMs = this.totalAttentionMs;
-        return this.totalAttentionMs;
-    }
-    incrementTotalAttentionTimeByUnrecordedAmount() {
-        if (this.unrecordedAttentionStarted != null) {
-            const now = performance.now();
-            // the Math.min here is to deal with occasions where we don't get an event indicating that the user
-            // has become inactive - this can happen e.g. due to users suspending their phone. Never send
-            // crazy big values!
-            const unrecordedMs = Math.min(now - this.unrecordedAttentionStarted, this.reportingInterval);
-            this.totalAttentionMs += unrecordedMs;
-            return (this.unrecordedAttentionStarted = now);
-        }
-    }
-}
-/**
- * Begins monitoring the components on the page for attention time.
- * @returns {Array} Array of results from makeActive() for each visible component.
- */
-const startMonitoring = () => {
-    return components
-        .filter((component) => component.isVisible())
-        .map((component) => component.makeActive());
-};
-/**
- * Stops monitoring the components on the page for attention time.
- * @returns {Array} Array of results from makeInactive() for each component.
- */
-const stopMonitoring = () => {
-    return components.map((component) => component.makeInactive());
-};
-/**
- * Retrieves the attention times for all components.
- * @returns {Object}
- */
-const getAttentionTimes = () => {
-    const obj = {};
-    for (const component of components) {
-        if (component.hadAttentionSinceLastGet()) {
-            // if there are duplicate component names, only the last one survives
-            obj[component.name] = Math.round(component.getAttentionTime());
-        }
-    }
-    return obj;
-};
-export default {
-    /**
-     * @param {Object} emitter - The event emitter to set.
-     * @returns {Object}
-     */
-    setEventEmitter: function (emitter) {
-        return (eventEmitter = emitter);
-    },
-    startMonitoring,
-    stopMonitoring,
-    getAttentionTimes,
-    /** @type {(...args: ConstructorParameters<typeof Component>) => void} */
-    registerComponent: function (name, el, visibilityThreshold, reportingInterval) {
-        return components.push(new Component(name, el, visibilityThreshold, reportingInterval));
-    },
-};

package/dist/assets/contribution.d.ts

@@ -1,6 +0,0 @@
-declare namespace _default {
-    let record: (obj: import("../types/event.js").EventPayload, f?: Function | undefined) => void;
-    let viewId: any;
-}
-export default _default;
-//# sourceMappingURL=contribution.d.ts.map

package/dist/assets/contribution.js

@@ -1,16 +0,0 @@
-// Generated by CoffeeScript 2.7.0
-import core from './core.js';
-import transmit from './transmit.js';
-import attention from './attention.js';
-import visibility from './visibility.js';
-import './click-path-capture.js';
-import './perf.js';
-import './campaign.js';
-core.init('contribution');
-if (window.addEventListener != null) {
-    attention.init(visibility);
-}
-export default {
-    record: transmit.sendMore,
-    viewId: transmit.viewId,
-};