@whilesmart/engagement 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WhileSmart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# WhileSmart Engagement
+
+Framework-independent browser event tracking for `whilesmart/eloquent-engagement`.
+
+## Install
+
+```bash
+npm install @whilesmart/engagement
+```
+
+## Use
+
+```ts
+import { createEngagementClient } from '@whilesmart/engagement'
+
+const engagement = createEngagementClient({
+  endpoint: 'https://api.example.com/api/engagement/events',
+  siteKey: 'public-site-key',
+  consent: () => analyticsConsentGranted(),
+})
+
+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.
+
+The site key identifies a website. It is not a secret. The server must also restrict accepted browser origins.
+
+## License
+
+MIT. WhileSmart LTD.

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+import type { EngagementClient, EngagementClientOptions } from './types.js';
+export declare function createEngagementClient(options: EngagementClientOptions): EngagementClient;

package/dist/client.js

@@ -0,0 +1,148 @@
+const visitorStorageKey = 'whilesmart.engagement.visitor';
+const sessionStorageKey = 'whilesmart.engagement.session';
+export function createEngagementClient(options) {
+    const batchSize = Math.min(Math.max(options.batchSize ?? 10, 1), 20);
+    const fetcher = options.fetch ?? globalThis.fetch?.bind(globalThis);
+    const browserLocation = options.location ?? globalThis.location;
+    const browserDocument = options.document ?? globalThis.document;
+    const browserNavigator = options.navigator ?? globalThis.navigator;
+    const localStorage = options.storage ?? safeStorage('localStorage');
+    const sessionStorage = options.sessionStorage ?? safeStorage('sessionStorage');
+    const browserCrypto = options.crypto ?? globalThis.crypto;
+    const visitorId = persistentId(localStorage, visitorStorageKey, browserCrypto);
+    const sessionId = persistentId(sessionStorage, sessionStorageKey, browserCrypto);
+    const queue = [];
+    let flushing;
+    const onVisibilityChange = () => {
+        if (browserDocument?.visibilityState === 'hidden')
+            void flush(true);
+    };
+    browserDocument?.addEventListener('visibilitychange', onVisibilityChange);
+    const timer = globalThis.setInterval(() => void flush(), options.flushInterval ?? 5000);
+    function track(name, properties, eventOptions = {}) {
+        if (options.consent && !options.consent())
+            return;
+        const event = {
+            name,
+            visitor_id: visitorId,
+            session_id: sessionId,
+            occurred_at: new Date().toISOString(),
+        };
+        const url = eventOptions.url ?? browserLocation?.href;
+        const referrer = eventOptions.referrer ?? browserDocument?.referrer;
+        const attribution = attributionFrom(browserLocation?.search, referrer);
+        const source = eventOptions.source ?? attribution.source;
+        if (url)
+            event.url = url;
+        if (referrer)
+            event.referrer = referrer;
+        if (source)
+            event.source = source;
+        if (attribution.utm_medium)
+            event.utm_medium = attribution.utm_medium;
+        if (attribution.utm_campaign)
+            event.utm_campaign = attribution.utm_campaign;
+        if (attribution.utm_term)
+            event.utm_term = attribution.utm_term;
+        if (attribution.utm_content)
+            event.utm_content = attribution.utm_content;
+        if (attribution.click_id)
+            event.click_id = attribution.click_id;
+        if (properties && Object.keys(properties).length > 0)
+            event.properties = properties;
+        queue.push(event);
+        if (queue.length >= batchSize)
+            void flush();
+    }
+    function page(properties) {
+        track('page.view', properties);
+    }
+    async function flush(useBeacon = false) {
+        if (flushing)
+            return flushing;
+        if (queue.length === 0)
+            return;
+        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' }))) {
+            return;
+        }
+        if (!fetcher) {
+            queue.unshift(...events);
+            throw new Error('No fetch implementation is available');
+        }
+        flushing = fetcher(options.endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Engagement-Site-Key': options.siteKey,
+            },
+            body,
+            keepalive: true,
+        }).then((response) => {
+            if (!response.ok)
+                throw new Error(`Engagement request failed with status ${response.status}`);
+        }).catch((error) => {
+            queue.unshift(...events);
+            throw error;
+        }).finally(() => {
+            flushing = undefined;
+        });
+        return flushing;
+    }
+    async function destroy() {
+        globalThis.clearInterval(timer);
+        browserDocument?.removeEventListener('visibilitychange', onVisibilityChange);
+        await flush();
+    }
+    if (options.autoPageViews !== false)
+        page();
+    return { page, track, flush, destroy };
+}
+function persistentId(storage, key, crypto) {
+    const existing = storage?.getItem(key);
+    if (existing)
+        return existing;
+    const value = createId(crypto);
+    try {
+        storage?.setItem(key, value);
+    }
+    catch { }
+    return value;
+}
+function createId(crypto) {
+    if (crypto?.randomUUID)
+        return crypto.randomUUID();
+    const bytes = new Uint8Array(16);
+    crypto?.getRandomValues?.(bytes);
+    return Array.from(bytes, (value) => value.toString(16).padStart(2, '0')).join('') || `${Date.now()}-${Math.random()}`;
+}
+function safeStorage(name) {
+    try {
+        return globalThis[name];
+    }
+    catch {
+        return undefined;
+    }
+}
+function attributionFrom(search = '', referrer = '') {
+    const params = new URLSearchParams(search);
+    const campaignSource = params.get('utm_source');
+    let source = campaignSource ?? 'direct';
+    if (!campaignSource && referrer) {
+        try {
+            source = new URL(referrer).hostname;
+        }
+        catch {
+            source = referrer;
+        }
+    }
+    return {
+        source,
+        utm_medium: params.get('utm_medium') ?? undefined,
+        utm_campaign: params.get('utm_campaign') ?? undefined,
+        utm_term: params.get('utm_term') ?? undefined,
+        utm_content: params.get('utm_content') ?? undefined,
+        click_id: params.get('gclid') ?? params.get('fbclid') ?? params.get('msclkid') ?? undefined,
+    };
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1 @@
+export { createEngagementClient } from './client.js';

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+export type EngagementValue = string | number | boolean | null;
+export type EngagementProperties = Record<string, EngagementValue | EngagementValue[]>;
+export interface EngagementEvent {
+    name: string;
+    visitor_id: string;
+    session_id: string;
+    url?: string;
+    referrer?: string;
+    source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    click_id?: string;
+    properties?: EngagementProperties;
+    occurred_at: string;
+}
+export interface TrackOptions {
+    url?: string;
+    referrer?: string;
+    source?: string;
+}
+export interface EngagementClientOptions {
+    endpoint: string;
+    siteKey: string;
+    consent?: () => boolean;
+    autoPageViews?: boolean;
+    batchSize?: number;
+    flushInterval?: number;
+    fetch?: typeof globalThis.fetch;
+    storage?: Pick<Storage, 'getItem' | 'setItem'>;
+    sessionStorage?: Pick<Storage, 'getItem' | 'setItem'>;
+    location?: Pick<Location, 'href' | 'search'>;
+    document?: Pick<Document, 'referrer' | 'visibilityState' | 'addEventListener' | 'removeEventListener'>;
+    navigator?: Pick<Navigator, 'sendBeacon'>;
+    crypto?: Pick<Crypto, 'randomUUID' | 'getRandomValues'>;
+}
+export interface EngagementClient {
+    page(properties?: EngagementProperties): void;
+    track(name: string, properties?: EngagementProperties, options?: TrackOptions): void;
+    flush(useBeacon?: boolean): Promise<void>;
+    destroy(): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@whilesmart/engagement",
+  "version": "0.1.0",
+  "description": "Framework-independent browser engagement tracking for WhileSmart applications.",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.js"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/whilesmartjs/engagement.git"
+  }
+}