coveo.analytics 2.25.3 → 2.26.1

package/src/coveoua/simpleanalytics.spec.ts

@@ -19,10 +19,19 @@ class TestPluginWithSpy extends TestPlugin {
         super({client, uuidGenerator});
         TestPluginWithSpy.spy = jest.fn();
     }
+
+    public getApi(name: string): Function | null {
+        switch (name) {
+            case 'testMethod':
+                return this.testMethod;
+            default:
+                return null;
+        }
+    }
+
     testMethod(...args: any[]) {
         TestPluginWithSpy.spy(args);
     }
-    someProperty: string = 'foo';
 }
 
 describe('simpleanalytics', () => {
@@ -122,21 +131,24 @@ describe('simpleanalytics', () => {
             expect(fetchMock.lastUrl()).toMatch(/^https:\/\/someendpoint\.com/);
         });
 
-        it('uses EC and SVC plugins by default', () => {
+        it('uses EC, SVC and Link plugins by default', () => {
             coveoua('init', 'SOME TOKEN');
             expect(() => coveoua('callPlugin', 'ec', 'nosuchfunction')).toThrow(/does not exist/);
             expect(() => coveoua('callPlugin', 'svc', 'nosuchfunction')).toThrow(/does not exist/);
+            expect(() => coveoua('callPlugin', 'link', 'nosuchfunction')).toThrow(/does not exist/);
         });
 
         it('can accept no plugins', () => {
             coveoua('init', 'SOME TOKEN', {plugins: []});
             expect(() => coveoua('callPlugin', 'ec', 'nosuchfunction')).toThrow(/is not required/);
             expect(() => coveoua('callPlugin', 'svc', 'nosuchfunction')).toThrow(/is not required/);
+            expect(() => coveoua('callPlugin', 'link', 'nosuchfunction')).toThrow(/is not required/);
         });
 
         it('can accept one plugin', () => {
             coveoua('init', 'SOME TOKEN', {plugins: ['svc']});
             expect(() => coveoua('callPlugin', 'ec', 'nosuchfunction')).toThrow(/is not required/);
+            expect(() => coveoua('callPlugin', 'link', 'nosuchfunction')).toThrow(/is not required/);
             expect(() => coveoua('callPlugin', 'svc', 'nosuchfunction')).toThrow(/does not exist/);
         });
 
@@ -151,7 +163,7 @@ describe('simpleanalytics', () => {
             expect(() => coveoua('initForProxy')).toThrow(`You must pass your endpoint when you call 'initForProxy'`);
         });
 
-        it(`throw if the initForProxy receive an endpoint that's is not a string`, () => {
+        it(`throw if the initForProxy receive an endpoint that is not a string`, () => {
             expect(() => coveoua('initForProxy', {})).toThrow(
                 `You must pass a string as the endpoint parameter when you call 'initForProxy'`
             );
@@ -404,13 +416,6 @@ describe('simpleanalytics', () => {
 
             expect(() => coveoua('callPlugin', 'svc', 'fooBarBaz')).toThrow(/does not exist/);
         });
-
-        it('throws when a namespaced action is called and that this action is not a function on the plugin', () => {
-            coveoua('provide', 'test', TestPluginWithSpy);
-
-            coveoua('init', 'SOME TOKEN', {plugins: ['test']});
-            expect(() => coveoua('callPlugin', 'test', 'someProperty')).toThrow(/is not a function/);
-        });
     });
 
     describe('require', () => {

package/src/coveoua/simpleanalytics.ts

@@ -129,8 +129,8 @@ export class CoveoUA {
         this.plugins.require(name, {...options, client: this.client});
     }
 
-    callPlugin(pluginName: string, fn: string, ...args: any): void {
-        this.plugins.execute(pluginName, fn, ...args);
+    callPlugin(pluginName: string, fn: string, ...args: any): any {
+        return this.plugins.execute(pluginName, fn, ...args);
     }
 
     reset() {

package/src/plugins/BasePlugin.ts

@@ -7,8 +7,7 @@ type PluginWithId = {
     readonly Id: string;
 };
 
-export type PluginClass = typeof BasePlugin & PluginWithId;
-
+export type PluginClass = typeof Plugin & PluginWithId;
 export const BasePluginEventTypes = {
     pageview: 'pageview',
     event: 'event',
@@ -16,9 +15,17 @@ export const BasePluginEventTypes = {
 
 export type PluginOptions = {client: AnalyticsClient; uuidGenerator?: typeof uuidv4};
 
-export abstract class BasePlugin {
+export abstract class Plugin {
     protected client: AnalyticsClient;
     protected uuidGenerator: typeof uuidv4;
+    constructor({client, uuidGenerator = uuidv4}: PluginOptions) {
+        this.client = client;
+        this.uuidGenerator = uuidGenerator;
+    }
+    public abstract getApi(name: string): any;
+}
+
+export abstract class BasePlugin extends Plugin {
     protected action?: string;
     protected actionData: {[name: string]: string} = {};
     private pageViewId: string;
@@ -28,8 +35,7 @@ export abstract class BasePlugin {
     private lastReferrer: string;
 
     constructor({client, uuidGenerator = uuidv4}: PluginOptions) {
-        this.client = client;
-        this.uuidGenerator = uuidGenerator;
+        super({client, uuidGenerator});
         this.pageViewId = uuidGenerator();
         this.nextPageViewId = this.pageViewId;
         this.currentLocation = getFormattedLocation(window.location);
@@ -37,10 +43,18 @@ export abstract class BasePlugin {
 
         this.addHooks();
     }
-
     protected abstract addHooks(): void;
     protected abstract clearPluginData(): void;
 
+    public getApi(name: string): Function | null {
+        switch (name) {
+            case 'setAction':
+                return this.setAction;
+            default:
+                return null;
+        }
+    }
+
     public setAction(action: string, options?: any) {
         this.action = action;
         this.actionData = options;
@@ -59,7 +73,7 @@ export abstract class BasePlugin {
         };
     }
 
-    public updateLocationInformation(eventType: string, payload: any) {
+    protected updateLocationInformation(eventType: string, payload: any) {
         this.updateLocationForNextPageView(eventType, payload);
     }
 

package/src/plugins/ec.ts

@@ -71,6 +71,19 @@ export class ECPlugin extends BasePlugin {
         super({client, uuidGenerator});
     }
 
+    public getApi(name: string): Function | null {
+        const superCall: Function | null = super.getApi(name);
+        if (superCall !== null) return superCall;
+        switch (name) {
+            case 'addProduct':
+                return this.addProduct;
+            case 'addImpression':
+                return this.addImpression;
+            default:
+                return null;
+        }
+    }
+
     protected addHooks(): void {
         this.addHooksForPageView();
         this.addHooksForEvent();

package/src/plugins/link.spec.ts

@@ -0,0 +1,171 @@
+import {CoveoLinkParam, LinkPlugin} from './link';
+import {createAnalyticsClientMock} from '../../tests/analyticsClientMock';
+import {v4 as uuidv4} from 'uuid';
+
+function currentSecsSinceEpoch() {
+    return Math.floor(Date.now() / 1000);
+}
+
+describe('CoveoLinkParam class', () => {
+    it('can create a new link using a uuid', () => {
+        const uuid = uuidv4();
+        const link: CoveoLinkParam = new CoveoLinkParam(uuid, Date.now());
+        expect(link.clientId).toBe(uuid);
+        expect(link.creationDate).toBe(currentSecsSinceEpoch());
+    });
+
+    it('can create a new link using a uuid and timestamp', () => {
+        const uuid = uuidv4();
+        const link: CoveoLinkParam = new CoveoLinkParam(uuid, 1676298678329);
+        expect(link.clientId).toBe(uuid);
+        expect(link.creationDate).toBe(1676298678);
+    });
+
+    it('can not create a new link using a non uuid', () => {
+        const uuid = 'Not_a_uuid';
+        expect(() => new CoveoLinkParam(uuid, Date.now())).toThrow('Not a valid uuid');
+    });
+
+    it('can parse a link from a string', () => {
+        const link = 'c0b48880743e484f8044d7c37910c55b.1676298678';
+        const coveoLinkParam: CoveoLinkParam | null = CoveoLinkParam.fromString(link);
+        expect(coveoLinkParam).not.toBeNull;
+        expect(coveoLinkParam?.clientId).toBe('c0b48880-743e-484f-8044-d7c37910c55b');
+        expect(coveoLinkParam?.creationDate).toBe(1676298678);
+    });
+
+    it('will not parse links without a valid uuid', () => {
+        const link = 'a0c56830743d46537f703.1676298678';
+        const coveoLinkParam: CoveoLinkParam | null = CoveoLinkParam.fromString(link);
+        expect(coveoLinkParam).toBe(null);
+    });
+
+    it('will not parse links with an invalid structure', () => {
+        const link = 'a0c56830743d46537f703.1676298678.353673463';
+        const coveoLinkParam: CoveoLinkParam | null = CoveoLinkParam.fromString(link);
+        expect(coveoLinkParam).toBe(null);
+    });
+
+    it('will not parse links with invalid timestamps', () => {
+        const link = 'a0c56830743d46537f703.invalidtimestamp';
+        const coveoLinkParam: CoveoLinkParam | null = CoveoLinkParam.fromString(link);
+        expect(coveoLinkParam).toBe(null);
+    });
+
+    it('can serialize a link to a string', () => {
+        const coveoLink: CoveoLinkParam = new CoveoLinkParam('074af291-224b-4705-9dc5-a47bd80a8db9', Date.now());
+        const link = coveoLink.toString();
+        const parts = link.split('.');
+        expect(parts[0]).toBe('074af291224b47059dc5a47bd80a8db9');
+        expect(Number.parseInt(parts[1])).toBe(currentSecsSinceEpoch());
+    });
+
+    it('checks for expiration on a link', () => {
+        const coveoLink1: CoveoLinkParam = new CoveoLinkParam('074af291-224b-4705-9dc5-a47bd80a8db9', Date.now());
+        expect(coveoLink1.expired).toBe(false);
+        const coveoLink2: CoveoLinkParam = new CoveoLinkParam(
+            '074af291-224b-4705-9dc5-a47bd80a8db9',
+            Date.now() - 180000
+        );
+        expect(coveoLink2.expired).toBe(true);
+    });
+
+    it('checks for expiration on a link if the timestamp is in the future', () => {
+        const coveoLink1: CoveoLinkParam = new CoveoLinkParam('074af291-224b-4705-9dc5-a47bd80a8db9', Date.now());
+        expect(coveoLink1.expired).toBe(false);
+        const coveoLink2: CoveoLinkParam = new CoveoLinkParam(
+            '074af291-224b-4705-9dc5-a47bd80a8db9',
+            Date.now() + 5000
+        );
+        expect(coveoLink2.expired).toBe(true);
+    });
+
+    it('checks validation on referrers', () => {
+        const coveoLink1: CoveoLinkParam = new CoveoLinkParam('074af291-224b-4705-9dc5-a47bd80a8db9', Date.now());
+        expect(coveoLink1.validate('http://sub.mysite.com', ['*'])).toBe(true);
+        expect(coveoLink1.validate('http://sub.mysite.com', ['*.mysite.com', '*'])).toBe(true);
+        expect(coveoLink1.validate('http://sub.mysite.com', ['*.mysite.com'])).toBe(true);
+        expect(coveoLink1.validate('http://sub.notmysite.com', ['*.mysite.com'])).toBe(false);
+        expect(coveoLink1.validate('http://sub.mysite.com', [])).toBe(false);
+    });
+
+    it('escapes backslash correctly', () => {
+        const coveoLink1: CoveoLinkParam = new CoveoLinkParam('074af291-224b-4705-9dc5-a47bd80a8db9', Date.now());
+        expect(coveoLink1.validate('http://sub.mysite.com', ['\\w'])).toBe(false); // This should not be treated as a \w regexp!
+    });
+});
+
+describe('CoveoLinkPlugin', () => {
+    let link: LinkPlugin;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        const analyticsClient = createAnalyticsClientMock();
+        analyticsClient.getCurrentVisitorId = jest.fn(() => Promise.resolve('85698661-efdf-4c6d-9cad-c4632bf81ce3'));
+        link = new LinkPlugin({client: analyticsClient});
+    });
+
+    it('decorates links with valid urls and no params', async () => {
+        const url: string = 'https://coveo.com';
+        const result: string = await link.decorate(url);
+        expect(result).toBe('https://coveo.com/?cvo_cid=85698661efdf4c6d9cadc4632bf81ce3.' + currentSecsSinceEpoch());
+    });
+
+    it('decorates links with valid urls and no params', async () => {
+        const url: string = 'https://coveo.com/some/path/';
+        const result: string = await link.decorate(url);
+        expect(result).toBe(
+            'https://coveo.com/some/path/?cvo_cid=85698661efdf4c6d9cadc4632bf81ce3.' + currentSecsSinceEpoch()
+        );
+    });
+
+    it('decorates links with valid urls and existing params', async () => {
+        const url: string = 'https://coveo.com/query?q=something&p=param';
+        const result: string = await link.decorate(url);
+        expect(result).toBe(
+            'https://coveo.com/query?q=something&p=param&cvo_cid=85698661efdf4c6d9cadc4632bf81ce3.' +
+                currentSecsSinceEpoch()
+        );
+    });
+
+    it('decorates links with valid urls, existing params and fragments', async () => {
+        const url: string = 'https://coveo.com/?q=something#frag';
+        const result: string = await link.decorate(url);
+        expect(result).toBe(
+            'https://coveo.com/?q=something&cvo_cid=85698661efdf4c6d9cadc4632bf81ce3.' +
+                currentSecsSinceEpoch() +
+                '#frag'
+        );
+    });
+
+    it('updates an existing decoration links with valid urls and no params', async () => {
+        const url: string = 'https://coveo.com/?cvo_cid=c0b48880743e484f8044d7c37910c55b.1676298678';
+        const result: string = await link.decorate(url);
+        expect(result).toBe('https://coveo.com/?cvo_cid=85698661efdf4c6d9cadc4632bf81ce3.' + currentSecsSinceEpoch());
+    });
+
+    it('errors on invalid urls', async () => {
+        const url: string = 'somethingthatisobviouslynotaurl';
+        await expect(link.decorate(url)).rejects.toThrow('Invalid URL provided');
+    });
+
+    it('errors when there is no current clientId', async () => {
+        // initialize with missing clientId method
+        const analyticsClient = createAnalyticsClientMock();
+        analyticsClient.getCurrentVisitorId = undefined;
+        link = new LinkPlugin({client: analyticsClient});
+
+        const url: string = 'https://coveo.com/';
+        await expect(link.decorate(url)).rejects.toThrow('Could not retrieve current clientId');
+    });
+
+    it('can set a list of referrers on the client', () => {
+        const analyticsClient = createAnalyticsClientMock();
+        const mock: jest.Mock = jest.fn();
+        analyticsClient.setAcceptedLinkReferrers = mock;
+        link = new LinkPlugin({client: analyticsClient});
+        link.acceptFrom(['*.somedomain.com', 'www.coveo.com']);
+
+        expect(mock).toHaveBeenCalledTimes(1);
+    });
+});

package/src/plugins/link.ts

@@ -0,0 +1,109 @@
+import {validate as uuidvalidate, v4 as uuidv4} from 'uuid';
+import {Plugin, PluginOptions, PluginClass} from './BasePlugin';
+
+export class CoveoLinkParam {
+    public static readonly cvo_cid: string = 'cvo_cid'; // name of the url parameter
+    private static readonly expirationTime: number = 120; // expirationTime in secs
+    public readonly clientId: string; //uuid
+    public readonly creationDate: number; //seconds since epoch to save space in serialized param
+
+    constructor(clientId: string, timestamp: number) {
+        if (!uuidvalidate(clientId)) throw Error('Not a valid uuid');
+        this.clientId = clientId;
+        this.creationDate = Math.floor(timestamp / 1000);
+    }
+
+    public toString(): string {
+        // strips the dashes and uses second granularity to save on url length.
+        return this.clientId.replace(/-/g, '') + '.' + this.creationDate.toString();
+    }
+
+    public get expired(): boolean {
+        const age = Math.floor(Date.now() / 1000) - this.creationDate;
+        return age < 0 || age > CoveoLinkParam.expirationTime;
+    }
+
+    public validate(referrerString: string, referrerList: string[]): boolean {
+        return !this.expired && this.matchReferrer(referrerString, referrerList);
+    }
+
+    private matchReferrer(referrerString: string, referrerList: string[]): boolean {
+        try {
+            const url: URL = new URL(referrerString);
+            return referrerList.some((value: string) => {
+                const hostRegExp: RegExp = new RegExp(
+                    value.replace(/\\/g, '\\\\').replace(/\./g, '\\.').replace(/\*/g, '.*') + '$'
+                );
+                return hostRegExp.test(url.host);
+            });
+        } catch (error) {
+            return false;
+        }
+    }
+
+    public static fromString(input: string): CoveoLinkParam | null {
+        const parts = input.split('.');
+        if (parts.length !== 2) {
+            return null;
+        }
+        const [clientIdPart, creationDate] = parts;
+        if (clientIdPart.length !== 32 || isNaN(parseInt(creationDate))) {
+            return null;
+        }
+        const clientId =
+            clientIdPart.substring(0, 8) +
+            '-' +
+            clientIdPart.substring(8, 12) +
+            '-' +
+            clientIdPart.substring(12, 16) +
+            '-' +
+            clientIdPart.substring(16, 20) +
+            '-' +
+            clientIdPart.substring(20, 32);
+        if (uuidvalidate(clientId)) {
+            return new CoveoLinkParam(clientId, Number.parseInt(creationDate) * 1000);
+        } else {
+            return null;
+        }
+    }
+}
+
+export class LinkPlugin extends Plugin {
+    public static readonly Id = 'link';
+
+    constructor({client, uuidGenerator = uuidv4}: PluginOptions) {
+        super({client, uuidGenerator});
+    }
+
+    public getApi(name: string): Function | null {
+        switch (name) {
+            case 'decorate':
+                return this.decorate;
+            case 'acceptFrom':
+                return this.acceptFrom;
+            default:
+                return null;
+        }
+    }
+
+    public async decorate(urlString: string): Promise<string> {
+        // Note: clientId retrieval function is marked as optional
+        if (!this.client.getCurrentVisitorId) {
+            throw new Error('Could not retrieve current clientId');
+        }
+        try {
+            const url = new URL(urlString);
+            const clientId: string = await this.client.getCurrentVisitorId!();
+            url.searchParams.set(CoveoLinkParam.cvo_cid, new CoveoLinkParam(clientId, Date.now()).toString());
+            return url.toString();
+        } catch (error) {
+            throw new Error('Invalid URL provided');
+        }
+    }
+
+    public acceptFrom(acceptedReferrers: string[]) {
+        this.client.setAcceptedLinkReferrers!(acceptedReferrers);
+    }
+}
+
+export const Link: PluginClass = LinkPlugin;

package/src/plugins/svc.ts

@@ -34,6 +34,17 @@ export class SVCPlugin extends BasePlugin {
         super({client, uuidGenerator});
     }
 
+    public getApi(name: string): Function | null {
+        const superCall: Function | null = super.getApi(name);
+        if (superCall !== null) return superCall;
+        switch (name) {
+            case 'setTicket':
+                return this.setTicket;
+            default:
+                return null;
+        }
+    }
+
     protected addHooks(): void {
         this.addHooksForEvent();
         this.addHooksForPageView();

package/dist/definitions/src/client/location.d.ts

@@ -1 +0,0 @@
-export declare const getFormattedLocation: (location: Location) => string;