@whilesmart/engagement 0.1.0 → 0.2.0

package/README.md

@@ -24,6 +24,43 @@ engagement.track('signup.started', { plan: 'business' })
 
 The client records a random visitor ID in local storage and a random session ID in session storage. It derives source attribution from `utm_source`, then the referrer host, then `direct`. Events are batched, retried after failed requests, and flushed with `sendBeacon` when the page becomes hidden.
 
+Set `autoLinkClicks: true` to record every link click as `link.clicked`, with
+the link's text, where it goes, and whether it leaves the site. Use
+`{ text: false }` where link text can be private, such as inside an app.
+
+## Other analytics services
+
+A destination receives everything the client records: page views, events,
+`identify` on sign-in and `reset` on sign-out. The client still sends its own
+events to the endpoint, so the admin console keeps its figures whichever
+services are added, and one consent check covers them all.
+
+```ts
+import { createEngagementClient } from '@whilesmart/engagement'
+import { posthogDestination } from '@whilesmart/engagement/posthog'
+
+const engagement = createEngagementClient({
+  endpoint,
+  siteKey,
+  autoLinkClicks: true,
+  destinations: [
+    posthogDestination({
+      token: 'your-project-token-here',
+      host: 'https://us.i.posthog.com',
+      config: { session_recording: { maskAllInputs: true } },
+    }),
+  ],
+})
+
+engagement.identify({ id: '42', properties: { email: 'ada@example.com' } })
+```
+
+`posthog-js` is an optional peer dependency, downloaded only once the client
+first has something to send. Any service can be added by passing an object with
+a `name` and whichever of `start`, `page`, `track`, `identify` and `reset` it
+needs. One that throws is reported to `onDestinationError` and never stops the
+others.
+
 The site key identifies a website. It is not a secret. The server must also restrict accepted browser origins.
 
 ## License

package/dist/client.js

@@ -12,15 +12,38 @@ export function createEngagementClient(options) {
     const visitorId = persistentId(localStorage, visitorStorageKey, browserCrypto);
     const sessionId = persistentId(sessionStorage, sessionStorageKey, browserCrypto);
     const queue = [];
+    const destinations = options.destinations ?? [];
+    let started = false;
     let flushing;
+    function deliver(call) {
+        if (!started) {
+            started = true;
+            deliver((destination) => destination.start?.({ visitorId, sessionId }));
+        }
+        for (const destination of destinations) {
+            try {
+                call(destination);
+            }
+            catch (error) {
+                options.onDestinationError?.(destination.name, error);
+            }
+        }
+    }
+    function consented() {
+        return !options.consent || options.consent();
+    }
     const onVisibilityChange = () => {
         if (browserDocument?.visibilityState === 'hidden')
-            void flush(true);
+            background(true);
     };
     browserDocument?.addEventListener('visibilitychange', onVisibilityChange);
-    const timer = globalThis.setInterval(() => void flush(), options.flushInterval ?? 5000);
+    // A failed batch is already back in the queue, so there is nothing to report.
+    function background(urgent = false) {
+        flush(urgent).catch(() => { });
+    }
+    const timer = globalThis.setInterval(() => background(), options.flushInterval ?? 5000);
     function track(name, properties, eventOptions = {}) {
-        if (options.consent && !options.consent())
+        if (!consented())
             return;
         const event = {
             name,
@@ -51,31 +74,62 @@ export function createEngagementClient(options) {
         if (properties && Object.keys(properties).length > 0)
             event.properties = properties;
         queue.push(event);
+        deliver((destination) => (name === 'page.view' ? destination.page?.(event) : destination.track?.(event)));
         if (queue.length >= batchSize)
-            void flush();
+            background();
     }
     function page(properties) {
         track('page.view', properties);
     }
-    async function flush(useBeacon = false) {
-        if (flushing)
+    function identify(person) {
+        if (!consented())
+            return;
+        deliver((destination) => destination.identify?.(person));
+    }
+    function reset() {
+        deliver((destination) => destination.reset?.());
+    }
+    const withText = typeof options.autoLinkClicks !== 'object' || options.autoLinkClicks.text;
+    const onClick = (event) => {
+        const link = event.target instanceof Element ? event.target.closest('a') : null;
+        if (!link?.href)
+            return;
+        const properties = {
+            destination: link.origin + link.pathname,
+            outbound: link.origin !== originOf(browserLocation?.href),
+        };
+        if (withText)
+            properties.label = (link.textContent ?? '').trim().slice(0, 200);
+        track('link.clicked', properties);
+        background(true);
+    };
+    if (options.autoLinkClicks)
+        browserDocument?.addEventListener('click', onClick);
+    /** An urgent flush does not wait for a request in flight: the page may be closing. */
+    async function flush(urgent = false) {
+        if (!options.endpoint) {
+            queue.length = 0;
+            return;
+        }
+        if (flushing && !urgent)
             return flushing;
         if (queue.length === 0)
             return;
+        const endpoint = options.endpoint;
         const events = queue.splice(0, batchSize);
         const body = JSON.stringify({ site_key: options.siteKey, events });
-        if (useBeacon && browserNavigator?.sendBeacon?.(options.endpoint, new Blob([body], { type: 'application/json' }))) {
+        if (urgent && browserNavigator?.sendBeacon?.(endpoint, new Blob([body], { type: 'application/json' }))) {
             return;
         }
         if (!fetcher) {
             queue.unshift(...events);
             throw new Error('No fetch implementation is available');
         }
-        flushing = fetcher(options.endpoint, {
+        const request = fetcher(endpoint, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                'X-Engagement-Site-Key': options.siteKey,
+                'X-Engagement-Site-Key': options.siteKey ?? '',
             },
             body,
             keepalive: true,
@@ -86,18 +140,29 @@ export function createEngagementClient(options) {
             queue.unshift(...events);
             throw error;
         }).finally(() => {
-            flushing = undefined;
+            if (flushing === request)
+                flushing = undefined;
         });
-        return flushing;
+        flushing = request;
+        return request;
     }
     async function destroy() {
         globalThis.clearInterval(timer);
         browserDocument?.removeEventListener('visibilitychange', onVisibilityChange);
+        browserDocument?.removeEventListener('click', onClick);
         await flush();
     }
     if (options.autoPageViews !== false)
         page();
-    return { page, track, flush, destroy };
+    return { page, track, identify, reset, flush, destroy };
+}
+function originOf(href) {
+    try {
+        return href ? new URL(href).origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
 function persistentId(storage, key, crypto) {
     const existing = storage?.getItem(key);

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { createEngagementClient } from './client.js';
-export type { EngagementClient, EngagementClientOptions, EngagementEvent, EngagementProperties, EngagementValue, TrackOptions, } from './types.js';
+export type { DestinationContext, EngagementClient, EngagementDestination, EngagementPerson, EngagementClientOptions, EngagementEvent, EngagementProperties, EngagementValue, TrackOptions, } from './types.js';

package/dist/posthog.d.ts

@@ -0,0 +1,12 @@
+import type { PostHog, PostHogConfig } from 'posthog-js';
+import type { EngagementDestination } from './types.js';
+type PostHogClient = Pick<PostHog, 'init' | 'capture' | 'identify' | 'reset'>;
+export interface PostHogDestinationOptions {
+    token: string;
+    host: string;
+    config?: Partial<PostHogConfig>;
+    load?: () => Promise<PostHogClient>;
+}
+/** PostHog's own page views are off: the engagement client sends them. */
+export declare function posthogDestination(options: PostHogDestinationOptions): EngagementDestination;
+export {};

package/dist/posthog.js

@@ -0,0 +1,39 @@
+/** PostHog's own page views are off: the engagement client sends them. */
+export function posthogDestination(options) {
+    let posthog;
+    const waiting = [];
+    function send(call) {
+        if (posthog)
+            call(posthog);
+        else
+            waiting.push(call);
+    }
+    return {
+        name: 'posthog',
+        start() {
+            const load = options.load ?? (async () => (await import('posthog-js')).posthog);
+            void load()
+                .then((client) => {
+                client.init(options.token, { api_host: options.host, capture_pageview: false, ...options.config });
+                posthog = client;
+                for (const call of waiting.splice(0))
+                    call(client);
+            })
+                .catch(() => {
+                waiting.length = 0;
+            });
+        },
+        page(event) {
+            send((client) => client.capture('$pageview', event.properties));
+        },
+        track(event) {
+            send((client) => client.capture(event.name, event.properties));
+        },
+        identify(person) {
+            send((client) => client.identify(person.id, person.properties));
+        },
+        reset() {
+            send((client) => client.reset());
+        },
+    };
+}

package/dist/types.d.ts

@@ -20,11 +20,34 @@ export interface TrackOptions {
     referrer?: string;
     source?: string;
 }
+export interface EngagementPerson {
+    id: string;
+    properties?: EngagementProperties;
+}
+export interface DestinationContext {
+    visitorId: string;
+    sessionId: string;
+}
+/** A destination that throws never stops the others. */
+export interface EngagementDestination {
+    name: string;
+    start?(context: DestinationContext): void;
+    page?(event: EngagementEvent): void;
+    track?(event: EngagementEvent): void;
+    identify?(person: EngagementPerson): void;
+    reset?(): void;
+}
 export interface EngagementClientOptions {
-    endpoint: string;
-    siteKey: string;
+    /** Left out, events reach only the destinations. */
+    endpoint?: string;
+    siteKey?: string;
     consent?: () => boolean;
+    destinations?: EngagementDestination[];
     autoPageViews?: boolean;
+    /** `{ text: false }` records where a link goes but not what it says. */
+    autoLinkClicks?: boolean | {
+        text: boolean;
+    };
     batchSize?: number;
     flushInterval?: number;
     fetch?: typeof globalThis.fetch;
@@ -32,12 +55,15 @@ export interface EngagementClientOptions {
     sessionStorage?: Pick<Storage, 'getItem' | 'setItem'>;
     location?: Pick<Location, 'href' | 'search'>;
     document?: Pick<Document, 'referrer' | 'visibilityState' | 'addEventListener' | 'removeEventListener'>;
+    onDestinationError?: (destination: string, error: unknown) => void;
     navigator?: Pick<Navigator, 'sendBeacon'>;
     crypto?: Pick<Crypto, 'randomUUID' | 'getRandomValues'>;
 }
 export interface EngagementClient {
     page(properties?: EngagementProperties): void;
     track(name: string, properties?: EngagementProperties, options?: TrackOptions): void;
+    identify(person: EngagementPerson): void;
+    reset(): void;
     flush(useBeacon?: boolean): Promise<void>;
     destroy(): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whilesmart/engagement",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-independent browser engagement tracking for WhileSmart applications.",
   "type": "module",
   "license": "MIT",
@@ -12,6 +12,18 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./posthog": {
+      "types": "./dist/posthog.d.ts",
+      "import": "./dist/posthog.js"
+    }
+  },
+  "peerDependencies": {
+    "posthog-js": "^1.438.0"
+  },
+  "peerDependenciesMeta": {
+    "posthog-js": {
+      "optional": true
     }
   },
   "scripts": {
@@ -19,6 +31,7 @@
     "test": "npm run build && node --test tests/*.test.js"
   },
   "devDependencies": {
+    "posthog-js": "^1.438.13",
     "typescript": "^5.7.0"
   },
   "repository": {