@zoho_apptics/apptics-js-sdk 1.0.2 → 2.0.0-beta

package/dist/esm/core/db.js

@@ -0,0 +1,324 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { Console } from './logger.js';
+import { nowMs } from './utils.js';
+
+const DB_NAME = 'apptics'; // no i18n
+// 3 added the heatmaps store. The upgrade only creates stores that are missing, so an existing
+// database keeps everything already queued in it.
+const DB_VERSION = 3;
+const OPEN_TIMEOUT_MS = 3000;
+const QUEUES = ['engagements', 'errors', 'logs', 'consolelogs', 'heatmaps']; // no i18n
+/** 1.x localStorage keys; also the layout of the localStorage backend. */
+const LEGACY_KEYS = Object.freeze({
+    settings: 'apptics-device-info', // no i18n
+    engagements: 'apptics-engagements-transactions', // no i18n
+    errors: 'apptics-errors-transactions', // no i18n
+    logs: 'apptics-log-transactions', // no i18n
+    consolelogs: 'apptics-consolelog-transactions', // no i18n
+    // not a 1.x key: heatmaps did not exist then. It is here because this map is also the
+    // localStorage backend's layout, so the store needs a name there too
+    heatmaps: 'apptics-heatmap-transactions', // no i18n
+});
+/** Shape guards shared by both backends and the 1.x migration. */
+function asList(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asDict(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+/* ---------------- localStorage backend ---------------- */
+function readJSON(key) {
+    try {
+        const raw = localStorage.getItem(key);
+        return raw === null || raw === '' ? null : JSON.parse(raw); // no i18n
+    }
+    catch (err) {
+        Console.warn('apptics: could not read ' + key + ', treating it as empty'); // no i18n
+        return null;
+    }
+}
+function writeJSON(key, value) {
+    try {
+        localStorage.setItem(key, JSON.stringify(value));
+    }
+    catch (err) {
+        Console.warn('apptics: could not write ' + key + ': ' + String(err)); // no i18n
+    }
+}
+function createLocalStorageBackend() {
+    return {
+        kind: 'localstorage', // no i18n
+        loadSettings() {
+            return Promise.resolve(asDict(readJSON(LEGACY_KEYS.settings)));
+        },
+        putSetting(key, value) {
+            const all = asDict(readJSON(LEGACY_KEYS.settings));
+            all[key] = value;
+            writeJSON(LEGACY_KEYS.settings, all);
+            return Promise.resolve();
+        },
+        clearSettings() {
+            writeJSON(LEGACY_KEYS.settings, {});
+            return Promise.resolve();
+        },
+        queueAll(store) {
+            return Promise.resolve(asList(readJSON(LEGACY_KEYS[store])));
+        },
+        queuePut(store, items) {
+            const list = asList(readJSON(LEGACY_KEYS[store]));
+            items.forEach(function (item) {
+                const index = list.findIndex(function (existing) { return existing.id === item.id; });
+                if (index === -1) {
+                    list.push(item);
+                }
+                else {
+                    list[index] = item;
+                }
+            });
+            writeJSON(LEGACY_KEYS[store], list);
+            return Promise.resolve();
+        },
+        queueDelete(store, ids) {
+            const remaining = asList(readJSON(LEGACY_KEYS[store])).filter(function (item) {
+                return ids.indexOf(item.id) === -1;
+            });
+            writeJSON(LEGACY_KEYS[store], remaining);
+            return Promise.resolve();
+        },
+        queueClear(store) {
+            writeJSON(LEGACY_KEYS[store], []);
+            return Promise.resolve();
+        },
+    };
+}
+let lastSeq = 0;
+/**
+ * Strictly increasing, and time-based so tabs interleave in roughly the right order.
+ * Counting up from the last value rather than a counter that wraps keeps insertion order
+ * even when a chatty caller adds more than a thousand items inside one millisecond.
+ */
+function nextSeq() {
+    const base = nowMs() * 1000;
+    lastSeq = base > lastSeq ? base : lastSeq + 1;
+    return lastSeq;
+}
+function request(req) {
+    return new Promise(function (resolve, reject) {
+        req.onsuccess = function () { resolve(req.result); };
+        req.onerror = function () { reject(req.error); };
+    });
+}
+function completed(tx) {
+    return new Promise(function (resolve, reject) {
+        tx.oncomplete = function () { resolve(); };
+        tx.onerror = function () { reject(tx.error); };
+        tx.onabort = function () { reject(tx.error); };
+    });
+}
+/** Puts `item` unless it exists (keepExisting) or replaces it keeping its seq. Runs inside `store`'s transaction. */
+function putRecord(store, item, keepExisting) {
+    const id = String(item.id);
+    const lookup = store.get(id);
+    lookup.onsuccess = function () {
+        const existing = lookup.result;
+        if (existing && keepExisting) {
+            return;
+        }
+        store.put({ id: id, seq: existing ? existing.seq : nextSeq(), type: item.type, item: item });
+    };
+}
+/** Our stores, as created by onupgradeneeded. */
+function hasAllStores(db) {
+    return db.objectStoreNames.contains('settings') && QUEUES.every(function (name) {
+        return db.objectStoreNames.contains(name);
+    });
+}
+function deleteDatabase(factory) {
+    return new Promise(function (resolve) {
+        var req = factory.deleteDatabase(DB_NAME);
+        req.onsuccess = function () { resolve(); };
+        req.onerror = function () { resolve(); };
+        req.onblocked = function () { resolve(); };
+    });
+}
+/**
+ * Opens the database, and repairs it once if something else created an "apptics" database
+ * without our stores (then onupgradeneeded never fires and every read would fail).
+ */
+function openIndexedDB(factory = indexedDB, timeoutMs = OPEN_TIMEOUT_MS) {
+    return openOnce(factory, timeoutMs).then(function (db) {
+        if (hasAllStores(db)) {
+            return db;
+        }
+        Console.warn('apptics: the "' + DB_NAME + '" database is missing its stores, recreating it'); // no i18n
+        db.close();
+        return deleteDatabase(factory).then(function () {
+            return openOnce(factory, timeoutMs);
+        }).then(function (fresh) {
+            if (!hasAllStores(fresh)) {
+                fresh.close();
+                throw new Error('indexedDB: stores could not be created'); // no i18n
+            }
+            return fresh;
+        });
+    });
+}
+function openOnce(factory, timeoutMs) {
+    return new Promise(function (resolve, reject) {
+        let settled = false;
+        const fail = function (reason) {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                reject(reason);
+            }
+        };
+        const timer = setTimeout(function () {
+            fail(new Error('indexedDB open timed out')); // no i18n
+        }, timeoutMs);
+        let req;
+        try {
+            req = factory.open(DB_NAME, DB_VERSION);
+        }
+        catch (err) {
+            fail(err);
+            return;
+        }
+        req.onupgradeneeded = function () {
+            const db = req.result;
+            if (!db.objectStoreNames.contains('settings')) { // no i18n
+                db.createObjectStore('settings'); // no i18n
+            }
+            QUEUES.forEach(function (name) {
+                if (!db.objectStoreNames.contains(name)) {
+                    db.createObjectStore(name, { keyPath: 'id' }).createIndex('seq', 'seq'); // no i18n
+                }
+            });
+        };
+        req.onsuccess = function () {
+            if (settled) {
+                req.result.close(); // we already gave up (timeout or blocked)
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            // Another tab running a newer build needs to upgrade the schema, and cannot while this
+            // connection is open. Letting go is the only cooperative answer: holding on blocks that
+            // tab's upgrade until this one is closed, and it spends the whole time with no storage.
+            // This tab keeps working from memory and picks the new schema up on its next load.
+            req.result.onversionchange = function () {
+                Console.warn('apptics: another tab is upgrading the database, closing this connection'); // no i18n
+                req.result.close();
+            };
+            resolve(req.result);
+        };
+        req.onerror = function () {
+            fail(req.error);
+        };
+        req.onblocked = function () {
+            // Another tab is holding an older version open. A build that sets onversionchange
+            // (above) lets go by itself, so this resolves on its own in a moment; the open is left
+            // to run until the timeout rather than abandoned, because giving up here would mean
+            // running with no storage for the rest of the visit.
+            Console.warn('apptics: waiting for another tab to release the database'); // no i18n
+        };
+    });
+}
+function createIndexedDBBackend(db) {
+    return {
+        kind: 'indexeddb', // no i18n
+        loadSettings() {
+            const store = db.transaction('settings', 'readonly').objectStore('settings'); // no i18n
+            return Promise.all([request(store.getAllKeys()), request(store.getAll())]).then(function ([keys, values]) {
+                const out = {};
+                keys.forEach(function (key, i) {
+                    out[String(key)] = values[i];
+                });
+                return out;
+            });
+        },
+        putSetting(key, value) {
+            const tx = db.transaction('settings', 'readwrite'); // no i18n
+            tx.objectStore('settings').put(value, key); // no i18n
+            return completed(tx);
+        },
+        clearSettings() {
+            const tx = db.transaction('settings', 'readwrite'); // no i18n
+            tx.objectStore('settings').clear(); // no i18n
+            return completed(tx);
+        },
+        queueAll(store) {
+            const index = db.transaction(store, 'readonly').objectStore(store).index('seq'); // no i18n
+            return request(index.getAll()).then(function (records) {
+                return records.map(function (record) { return record.item; });
+            });
+        },
+        queuePut(store, items) {
+            const tx = db.transaction(store, 'readwrite'); // no i18n
+            const objectStore = tx.objectStore(store);
+            items.forEach(function (item) { putRecord(objectStore, item, false); });
+            return completed(tx);
+        },
+        queueDelete(store, ids) {
+            const tx = db.transaction(store, 'readwrite'); // no i18n
+            const objectStore = tx.objectStore(store);
+            ids.forEach(function (id) { objectStore.delete(id); });
+            return completed(tx);
+        },
+        queueClear(store) {
+            const tx = db.transaction(store, 'readwrite'); // no i18n
+            tx.objectStore(store).clear();
+            return completed(tx);
+        },
+        importAll(settings, queues) {
+            // scope derived from QUEUES, not repeated: the loop below opens every one of them,
+            // and a store left out of the scope throws NotFoundError the moment it is reached
+            const tx = db.transaction(['settings'].concat(QUEUES), 'readwrite'); // no i18n
+            const settingsStore = tx.objectStore('settings'); // no i18n
+            Object.keys(settings).forEach(function (key) {
+                const lookup = settingsStore.get(key);
+                lookup.onsuccess = function () {
+                    if (lookup.result === undefined) {
+                        settingsStore.put(settings[key], key);
+                    }
+                };
+            });
+            QUEUES.forEach(function (name) {
+                const objectStore = tx.objectStore(name);
+                queues[name].forEach(function (item) { putRecord(objectStore, item, true); });
+            });
+            return completed(tx);
+        },
+    };
+}
+function localStorageUsable() {
+    try {
+        const probe = '__apptics_probe__'; // no i18n
+        localStorage.setItem(probe, '1');
+        localStorage.removeItem(probe);
+        return true;
+    }
+    catch (err) {
+        return false;
+    }
+}
+/** IndexedDB when it opens, otherwise localStorage, otherwise null. Never rejects. */
+function openBackend() {
+    const fallback = function (reason) {
+        Console.warn('apptics: IndexedDB unavailable (' + String(reason) + '), using localStorage'); // no i18n
+        return localStorageUsable() ? createLocalStorageBackend() : null;
+    };
+    let factory;
+    try {
+        factory = typeof indexedDB !== 'undefined' ? indexedDB : undefined; // no i18n
+    }
+    catch (err) {
+        factory = undefined; // access can throw in sandboxed frames
+    }
+    if (!factory) {
+        return Promise.resolve(fallback('not supported')); // no i18n
+    }
+    return openIndexedDB(factory).then(createIndexedDBBackend, fallback);
+}
+
+export { DB_NAME, DB_VERSION, LEGACY_KEYS, asDict, asList, createIndexedDBBackend, createLocalStorageBackend, openBackend, openIndexedDB };

package/dist/esm/core/debug.d.ts

@@ -0,0 +1,22 @@
+/** Whether debug mode is on right now, idle hour included. */
+export declare function debugEnabled(): boolean;
+/**
+ * Pushes the idle hour out. Called wherever something is actually tracked, which is the only
+ * evidence the SDK has that a person is still looking — there is no event for "watching".
+ */
+export declare function noteDebugActivity(): void;
+/**
+ * Turns debug mode off if its hour has run out. Called from the flush timer, which ticks whether
+ * or not anything is happening — a check that only ran on the way into a request would never
+ * fire, because an idle SDK makes no requests.
+ */
+export declare function expireDebugIfIdle(): void;
+/**
+ * Turns debug mode on, at any time: before init(), during start-up or while the SDK runs. The
+ * choice holds over `debug` in init() for the rest of the page's life.
+ */
+export declare function enableDebug(): void;
+/** Turns debug mode off, at any time, with the same hold over `debug` as enableDebug(). */
+export declare function disableDebug(): void;
+/** What init() applies for `debug`: the config's value, unless the app has already chosen. */
+export declare function applyDebugConfig(configured: boolean): void;

package/dist/esm/core/debug.js

@@ -0,0 +1,81 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { DEBUG_IDLE_MS } from './constants.js';
+import { _ZAP } from './state.js';
+import { Console } from './logger.js';
+import { nowMs } from './utils.js';
+
+/**
+ * The switch for debug mode, and the hour that closes it.
+ *
+ * Debug mode is not free on either side: every engagement, exception and log call goes to its
+ * `debug/` twin instead of the ordinary endpoint, which makes the server keep a traceable
+ * record of the request. That is worth it while someone is watching, and pure
+ * cost once they have walked away — and walking away is the normal way a debugging session ends,
+ * not a deliberate switch-off. So the SDK closes it: an hour with nothing tracked turns debug
+ * back off by itself, and anything tracked pushes that hour out again.
+ *
+ * It lives in core because every send asks it: `debug: true` in init(), or enableDebug(), is
+ * enough to turn the twins on, and that alone must expire.
+ */
+/** Whether debug mode is on right now, idle hour included. */
+function debugEnabled() {
+    return _ZAP._config.debug_api === true && !debugIdle();
+}
+/** True once the idle hour has run out on a debug session nobody is watching. */
+function debugIdle() {
+    return _ZAP._debugUntil > 0 && nowMs() > _ZAP._debugUntil;
+}
+/**
+ * Pushes the idle hour out. Called wherever something is actually tracked, which is the only
+ * evidence the SDK has that a person is still looking — there is no event for "watching".
+ */
+function noteDebugActivity() {
+    if (_ZAP._config.debug_api !== true) {
+        return;
+    }
+    _ZAP._debugUntil = nowMs() + DEBUG_IDLE_MS;
+}
+/**
+ * Turns debug mode off if its hour has run out. Called from the flush timer, which ticks whether
+ * or not anything is happening — a check that only ran on the way into a request would never
+ * fire, because an idle SDK makes no requests.
+ */
+function expireDebugIfIdle() {
+    if (!debugIdle()) {
+        return;
+    }
+    Console.log('apptics: debug mode has been idle for an hour, switching it off'); // no i18n
+    setDebug(false);
+}
+/**
+ * The app's own choice, from enableDebug() or disableDebug(). It wins over `debug` in init(),
+ * so debug mode can be switched on or off with one call, before init() runs or while the SDK is
+ * running, and an init() or reset() that comes after doesn't switch it back. null until the app
+ * has chosen.
+ */
+var chosen = null;
+/** Turning it on starts the idle hour; turning it off clears it, so the next on gets a whole hour. */
+function setDebug(on) {
+    _ZAP._config.debug_api = on;
+    _ZAP._debugUntil = on ? nowMs() + DEBUG_IDLE_MS : 0;
+    Console.log('apptics: debug mode ' + (on ? 'on' : 'off')); // no i18n
+}
+/**
+ * Turns debug mode on, at any time: before init(), during start-up or while the SDK runs. The
+ * choice holds over `debug` in init() for the rest of the page's life.
+ */
+function enableDebug() {
+    chosen = true;
+    setDebug(true);
+}
+/** Turns debug mode off, at any time, with the same hold over `debug` as enableDebug(). */
+function disableDebug() {
+    chosen = false;
+    setDebug(false);
+}
+/** What init() applies for `debug`: the config's value, unless the app has already chosen. */
+function applyDebugConfig(configured) {
+    setDebug(chosen !== null ? chosen : configured);
+}
+
+export { applyDebugConfig, debugEnabled, disableDebug, enableDebug, expireDebugIfIdle, noteDebugActivity };

package/dist/esm/core/env.d.ts

@@ -0,0 +1,28 @@
+import type { AppticsConfig } from '../types.js';
+export declare function isBlockedWS(ua: string): boolean;
+/** Device RAM as the API wants it ("4 GB"). Chromium only; empty elsewhere. */
+export declare function getRam(): string;
+export declare function getConnectionType(): string;
+export declare function getNetworkStatus(): number;
+/**
+ * The battery as a whole percentage, or null where the browser will not say.
+ *
+ * feedbackWebSDK types `battery` as an int and the console shows it next to a report, which is
+ * what makes "it died while I was filling this in" legible. The Battery Status API is behind a
+ * promise and is absent in Firefox and Safari entirely, so this answers null rather than 0 -
+ * a real 0% and "no answer" are different things, and only one of them belongs in a report.
+ */
+export declare function getBatteryPercent(): Promise<number | null>;
+export declare function getOrientation(): number;
+export declare function getDevice(): string;
+export declare function getOS(): string;
+export declare function getBrowser(): string;
+export declare function getBrowserVersion(): number | string;
+export declare function getReferringURL(): string;
+export declare function getTimeZone(): string;
+/** True for crawlers and non-browser environments; the SDK does nothing for them. */
+export declare function is_apptics_disabled(): boolean;
+/** Pure DNT check (no side effects). consent.hasDoNotTrackEnabled() applies NO_TRACKING. */
+export declare function isDntOn(): boolean;
+/** The console snippet's config (window.appticssettings._defaultoptions), if the page defines one. */
+export declare function getSnippetOptions(): AppticsConfig | undefined;