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

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

@@ -0,0 +1,61 @@
+import { type Backend, type QueueName } from './db.js';
+import type { Dict, QueueItem, TrackingStatus } from '../types.js';
+/** Opens storage, migrates 1.x data and loads settings into memory. Shared by all callers. */
+export declare function storageReady(): Promise<Backend | null>;
+export interface Queue {
+    readonly name: QueueName;
+    all(): Promise<QueueItem[]>;
+    payload(): Promise<QueueItem[]>;
+    add(item: QueueItem): Promise<void>;
+    update(item: QueueItem): Promise<void>;
+    remove(items?: QueueItem[]): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Sessions, screens, events and api calls waiting to be sent. */
+export declare const engagement_transactions: Queue;
+/** Errors waiting to be sent. */
+export declare const error_transactions: Queue;
+/**
+ * Feedback log lines and diagnostics entries, from addFeedbackLog() and addDiagnosticsInfo().
+ * These are not sent on their own: feedback/logs.ts renders them into the files that
+ * feedback/add carries, and removes the ones a submission took with it.
+ */
+export declare const feedbacklog_transactions: Queue;
+/** Clicks and scrolls waiting for heatmap/add. */
+export declare const heatmap_transactions: Queue;
+/**
+ * Remote log lines waiting for log/add. Stored rather than sent straight out because the
+ * endpoint takes one line per call and counts retries (`attempt`), so a line has to outlive a
+ * failed send — and a reload.
+ */
+export declare const remotelog_transactions: Queue;
+/**
+ * Sets one key of the stored device_info, and of this tab's copy: the uuid the device is
+ * registered under, whether it has had a session. Its other keys stay as they are.
+ */
+export declare function setDeviceInfoKey(key: string, value: unknown): void;
+/** device_info (uuid included), app_version_info, trackinfo (tracking_status included), users, user_info, and the rest. */
+export declare const user_defaults: {
+    all(): Dict;
+    item(key: string): any;
+    add(key: string, value: unknown): void;
+    /** As add(), and resolves once the value is in storage, where other tabs can read it. */
+    save(key: string, value: unknown): Promise<void>;
+    clear(): void;
+};
+/**
+ * Re-reads `keys` from storage. Settings are loaded into memory once, when a tab starts, so a value
+ * another tab of this site wrote since then — the device ids it registered — is only in storage.
+ * A key storage doesn't hold keeps this tab's value.
+ */
+export declare function reloadSettings(keys: string[]): Promise<void>;
+/** The visitor's tracking status, stored in trackinfo as tracking_status. */
+export declare function storedTrackingStatus(): TrackingStatus | undefined;
+/** Opt-in status, stored in the trackinfo setting as tracking_status. */
+export declare const tracking_preference: {
+    _tracking_status: string;
+    all(): Dict;
+    opt_in_status(): TrackingStatus;
+    update_status(tracking_status: TrackingStatus): void;
+};
+export declare function getKeyFromDeviceInfo(key: string): any;

package/dist/esm/core/storage.js

@@ -0,0 +1,314 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { AP_TRACKING_STATUS } from './constants.js';
+import { _ZAP, isExpired, getConfig } from './state.js';
+import { Console } from './logger.js';
+import { cloneObject, getNewUUID, isEmpty, sizeof } from './utils.js';
+import { openBackend, LEGACY_KEYS, asList, renameFeedbackType, asDict } from './db.js';
+
+var readyPromise = null;
+var settings = {};
+/** Runs `op` once storage is ready, in call order. Never rejects. */
+function withBackend(label, fallback, op) {
+    return storageReady().then(function (b) {
+        return b ? op(b) : fallback;
+    }).catch(function (err) {
+        Console.warn('apptics: storage ' + label + ' failed: ' + String(err)); // no i18n
+        return fallback;
+    });
+}
+function migrateLegacy(b) {
+    if (b.kind !== 'indexeddb' || !b.importAll) { // no i18n
+        return Promise.resolve();
+    }
+    var raw;
+    try {
+        raw = {
+            settings: localStorage.getItem(LEGACY_KEYS.settings),
+            engagements: localStorage.getItem(LEGACY_KEYS.engagements),
+            errors: localStorage.getItem(LEGACY_KEYS.errors),
+            logs: localStorage.getItem(LEGACY_KEYS.logs),
+            consolelogs: localStorage.getItem(LEGACY_KEYS.consolelogs),
+        };
+    }
+    catch (err) {
+        return Promise.resolve();
+    }
+    if (raw.settings === null && raw.engagements === null && raw.errors === null && raw.logs === null
+        && raw.consolelogs === null) {
+        return Promise.resolve();
+    }
+    var parse = function (text) {
+        try {
+            return text === null ? null : JSON.parse(text);
+        }
+        catch (err) {
+            return null;
+        }
+    };
+    // 1.x's keys are logs and consolelogs; they are feedbacklogs and remotelogs now, and a
+    // feedback entry's type is feedbacklog or feedbackdiagnostics instead of log or diagnostics
+    var queues = {
+        engagements: asList(parse(raw.engagements)),
+        errors: asList(parse(raw.errors)),
+        feedbacklogs: asList(parse(raw.logs)).map(renameFeedbackType),
+        remotelogs: asList(parse(raw.consolelogs)),
+        // nothing to migrate: 1.x had no heatmaps
+        heatmaps: [],
+    };
+    queues.engagements.concat(queues.errors, queues.feedbacklogs, queues.remotelogs).forEach(function (item) {
+        if (!item.id)
+            item.id = getNewUUID();
+    });
+    var importAll = b.importAll.bind(b);
+    // Promise.resolve().then(...) turns a synchronous throw inside importAll into a rejection
+    return Promise.resolve().then(function () {
+        return importAll(asDict(parse(raw.settings)), queues);
+    }).then(function () {
+        Object.values(LEGACY_KEYS).forEach(function (key) {
+            try {
+                localStorage.removeItem(key);
+            }
+            catch (err) {
+                // keys stay; the import is idempotent
+            }
+        });
+        Console.log('apptics: moved 1.x data from localStorage to IndexedDB'); // no i18n
+    }).catch(function (err) {
+        Console.warn('apptics: 1.x data migration failed, will retry next load: ' + String(err)); // no i18n
+    });
+}
+/** Opens storage, migrates 1.x data and loads settings into memory. Shared by all callers. */
+function storageReady() {
+    if (!readyPromise) {
+        readyPromise = openBackend().then(function (b) {
+            if (!b) {
+                return null;
+            }
+            return migrateLegacy(b).then(function () {
+                return b.loadSettings();
+            }).then(function (loaded) {
+                // writes made before loading finished win over stored values
+                settings = Object.assign({}, loaded, settings);
+                moveRetiredSettings();
+                return b;
+            });
+        }).catch(function (err) {
+            Console.warn('apptics: storage unavailable: ' + String(err)); // no i18n
+            return null;
+        });
+    }
+    return readyPromise;
+}
+/** When an item happened: engagements carry starttime, errors and logs happenedat. */
+function itemTime(item) {
+    return item.starttime !== undefined ? item.starttime : item.happenedat;
+}
+/** First batch_size items, capped at 1 MB. */
+function takeBatch(items) {
+    const targetSize = 1024 * 1024; // 1 MB in bytes
+    let dataSize = 0;
+    const result = [];
+    for (const item of items.slice(0, getConfig('batch_size'))) { // no i18n
+        const size = sizeof(JSON.stringify(item));
+        if (dataSize + size > targetSize) {
+            break;
+        }
+        result.push(item);
+        dataSize += size;
+    }
+    return result;
+}
+function createQueue(name) {
+    const queue = {
+        name: name,
+        all() {
+            return withBackend('read ' + name, [], function (b) { return b.queueAll(name); }); // no i18n
+        },
+        payload() {
+            return queue.all().then(takeBatch);
+        },
+        add(item) {
+            if (!item.id) {
+                item.id = getNewUUID();
+            }
+            // a week-old item would only be dropped at send time, so don't store it at all
+            if (isExpired(itemTime(item))) {
+                Console.warn('apptics: dropping a ' + name + ' item older than ' + getConfig('batch_request_timeout') + ' days'); // no i18n
+                return Promise.resolve();
+            }
+            return withBackend('add ' + name, undefined, function (b) { return b.queuePut(name, [item]); }); // no i18n
+        },
+        update(item) {
+            return withBackend('update ' + name, undefined, function (b) { return b.queuePut(name, [item]); }); // no i18n
+        },
+        remove(itemsToRemove) {
+            const ids = (itemsToRemove || []).map(function (item) { return String(item.id); });
+            return withBackend('remove ' + name, undefined, function (b) { return b.queueDelete(name, ids); }); // no i18n
+        },
+        clear() {
+            return withBackend('clear ' + name, undefined, function (b) { return b.queueClear(name); }); // no i18n
+        },
+    };
+    return queue;
+}
+/** Sessions, screens, events and api calls waiting to be sent. */
+const engagement_transactions = createQueue('engagements'); // no i18n
+/** Errors waiting to be sent. */
+const error_transactions = createQueue('errors'); // no i18n
+/**
+ * Feedback log lines and diagnostics entries, from addFeedbackLog() and addDiagnosticsInfo().
+ * These are not sent on their own: feedback/logs.ts renders them into the files that
+ * feedback/add carries, and removes the ones a submission took with it.
+ */
+const feedbacklog_transactions = createQueue('feedbacklogs'); // no i18n
+/** Clicks and scrolls waiting for heatmap/add. */
+const heatmap_transactions = createQueue('heatmaps'); // no i18n
+/**
+ * Remote log lines waiting for log/add. Stored rather than sent straight out because the
+ * endpoint takes one line per call and counts retries (`attempt`), so a line has to outlive a
+ * failed send — and a reload.
+ */
+const remotelog_transactions = createQueue('remotelogs'); // no i18n
+/* ---------------- settings (sync reads, background writes) ---------------- */
+/** Writes `key`, or removes it from storage altogether when `value` is undefined. */
+function writeSetting(b, key) {
+    return settings[key] === undefined ? b.deleteSetting(key) : b.putSetting(key, settings[key]);
+}
+function setSetting(key, value) {
+    if (value === undefined) {
+        delete settings[key];
+    }
+    else {
+        settings[key] = cloneObject(value);
+    }
+    withBackend('save ' + key, undefined, function (b) { return writeSetting(b, key); }); // no i18n
+}
+/**
+ * Settings 2.0.0-beta kept as keys of their own, now kept inside device_info and trackinfo.
+ * Moved once, on the first load after an upgrade, before anything reads them: the uuid is the one
+ * the device is registered under, and the tracking status is the visitor's own choice, so losing
+ * either would register a new device or forget a consent. token was never read, and goes.
+ * appkey and appversion are read and removed by init(), which compares them with this visit's app.
+ */
+function moveRetiredSettings() {
+    var device = settings.device_info && typeof settings.device_info === 'object' ? settings.device_info : null; // no i18n
+    if (settings.uuid !== undefined || settings.hadsession !== undefined) {
+        device = Object.assign({}, device || {});
+        if (isEmpty(device.uuid) && !isEmpty(settings.uuid)) {
+            device.uuid = settings.uuid;
+        }
+        if (settings.hadsession === true) {
+            device.hadsession = true;
+        }
+        setSetting('device_info', device); // no i18n
+        setSetting('uuid', undefined); // no i18n
+        setSetting('hadsession', undefined); // no i18n
+    }
+    if (settings.tracking_status !== undefined) {
+        var track = Object.assign({}, settings.trackinfo && typeof settings.trackinfo === 'object' ? settings.trackinfo : {}); // no i18n
+        if (track.tracking_status === undefined) {
+            track.tracking_status = settings.tracking_status;
+        }
+        setSetting('trackinfo', track); // no i18n
+        setSetting('tracking_status', undefined); // no i18n
+    }
+    if (settings.token !== undefined) {
+        setSetting('token', undefined); // no i18n
+    }
+}
+/**
+ * Sets one key of the stored device_info, and of this tab's copy: the uuid the device is
+ * registered under, whether it has had a session. Its other keys stay as they are.
+ */
+function setDeviceInfoKey(key, value) {
+    var device = Object.assign({}, settings.device_info && typeof settings.device_info === 'object' ? settings.device_info : {}); // no i18n
+    device[key] = value;
+    if (_ZAP._device_info && typeof _ZAP._device_info === 'object') { // no i18n
+        _ZAP._device_info[key] = value;
+    }
+    setSetting('device_info', device); // no i18n
+}
+/** device_info (uuid included), app_version_info, trackinfo (tracking_status included), users, user_info, and the rest. */
+const user_defaults = {
+    all() {
+        return cloneObject(settings);
+    },
+    item(key) {
+        const value = settings[key];
+        return value === undefined ? undefined : cloneObject(value);
+    },
+    add(key, value) {
+        setSetting(key, value);
+    },
+    /** As add(), and resolves once the value is in storage, where other tabs can read it. */
+    save(key, value) {
+        if (value === undefined) {
+            delete settings[key];
+        }
+        else {
+            settings[key] = cloneObject(value);
+        }
+        return withBackend('save ' + key, undefined, function (b) { return writeSetting(b, key); }); // no i18n
+    },
+    clear() {
+        settings = {};
+        withBackend('clear settings', undefined, function (b) { return b.clearSettings(); }); // no i18n
+    },
+};
+/**
+ * Re-reads `keys` from storage. Settings are loaded into memory once, when a tab starts, so a value
+ * another tab of this site wrote since then — the device ids it registered — is only in storage.
+ * A key storage doesn't hold keeps this tab's value.
+ */
+function reloadSettings(keys) {
+    return withBackend('reload settings', undefined, function (b) {
+        return b.loadSettings().then(function (loaded) {
+            keys.forEach(function (key) {
+                if (loaded[key] !== undefined) {
+                    settings[key] = loaded[key];
+                }
+            });
+        });
+    });
+}
+/** The visitor's tracking status, stored in trackinfo as tracking_status. */
+function storedTrackingStatus() {
+    var track = settings.trackinfo;
+    var status = track && typeof track === 'object' ? track.tracking_status : undefined; // no i18n
+    // a status only: getsdkconfig's own answer uses the same key for its per-module flags, and
+    // one stored by mistake must not read as a consent and stop all tracking
+    return status === AP_TRACKING_STATUS.USAGE_TRACKING_WITH_PII || status === AP_TRACKING_STATUS.USAGE_TRACKING_WITHOUT_PII
+        || status === AP_TRACKING_STATUS.NO_TRACKING ? status : undefined;
+}
+/** Opt-in status, stored in the trackinfo setting as tracking_status. */
+const tracking_preference = {
+    _tracking_status: 'tracking_status', // no i18n
+    all() {
+        return user_defaults.all();
+    },
+    opt_in_status() {
+        return (storedTrackingStatus() || AP_TRACKING_STATUS.USAGE_TRACKING_WITHOUT_PII);
+    },
+    update_status(tracking_status) {
+        _ZAP._devicestatus = tracking_status;
+        // Legacy order kept: this reads the status *before* the write below (setTrackingStatus recomputes it after).
+        _ZAP._isanonrequired =
+            tracking_preference.opt_in_status() == AP_TRACKING_STATUS.USAGE_TRACKING_WITH_PII ? false : _ZAP._isanonrequired;
+        var track = Object.assign({}, settings.trackinfo && typeof settings.trackinfo === 'object' ? settings.trackinfo : {}); // no i18n
+        track.tracking_status = tracking_status;
+        if (_ZAP._trackinfo && typeof _ZAP._trackinfo === 'object') { // no i18n
+            _ZAP._trackinfo.tracking_status = tracking_status;
+        }
+        setSetting('trackinfo', track); // no i18n
+    },
+};
+function getKeyFromDeviceInfo(key) {
+    var current_device_info = settings['device_info']; // no i18n
+    if (current_device_info !== undefined && current_device_info !== null && current_device_info !== '' &&
+        current_device_info[key] !== undefined && current_device_info[key] !== null && current_device_info[key] !== '') {
+        return cloneObject(current_device_info[key]);
+    }
+    return null;
+}
+
+export { engagement_transactions, error_transactions, feedbacklog_transactions, getKeyFromDeviceInfo, heatmap_transactions, reloadSettings, remotelog_transactions, setDeviceInfoKey, storageReady, storedTrackingStatus, tracking_preference, user_defaults };

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

@@ -0,0 +1,8 @@
+/**
+ * Adds the feedback form's styles to the page, once, as a <style> element, so no app imports or
+ * links a stylesheet: the css is carried in the JavaScript, for npm and the CDN builds alike.
+ *
+ * Nothing happens when `css` is empty (running from source, as the tests do) or when the page
+ * already has the styles (the element is marked data-apptics="style"). Never throws.
+ */
+export declare function injectStylesheet(css: string): void;

package/dist/esm/core/stylesheet.js

@@ -0,0 +1,27 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+/**
+ * Adds the feedback form's styles to the page, once, as a <style> element, so no app imports or
+ * links a stylesheet: the css is carried in the JavaScript, for npm and the CDN builds alike.
+ *
+ * Nothing happens when `css` is empty (running from source, as the tests do) or when the page
+ * already has the styles (the element is marked data-apptics="style"). Never throws.
+ */
+function injectStylesheet(css) {
+    try {
+        if (!css || typeof document === 'undefined') { // no i18n
+            return;
+        }
+        if (document.querySelector('[data-apptics="style"]')) { // no i18n
+            return;
+        }
+        var style = document.createElement('style'); // no i18n
+        style.setAttribute('data-apptics', 'style'); // no i18n
+        style.textContent = css;
+        (document.head || document.documentElement).appendChild(style);
+    }
+    catch (err) {
+        // the form still works unstyled; the app must not break over a stylesheet
+    }
+}
+
+export { injectStylesheet };

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

@@ -0,0 +1,85 @@
+import { DEFAULT_API_PATHS } from './constants.js';
+import type { Dict, ServerResult } from '../types.js';
+export type ApiPath = keyof typeof DEFAULT_API_PATHS;
+export type RequestHeaders = Record<string, string>;
+export type RequestBody = XMLHttpRequestBodyInit | null;
+/**
+ * How long a request may take before it counts as failed. Without a limit a request the network
+ * never answers keeps its caller waiting for good, and with it the queue it was sending.
+ */
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export declare function makeRequest(url: string, method: string, payload: RequestBody, headers?: RequestHeaders): Promise<string>;
+export declare function getHeaderParams(key: string): string;
+export declare function getParameters(path: ApiPath): string;
+/**
+ * `extra` appends params the path needs per call rather than per state, which console/addlog does
+ * (happenedtime and module change with every line). Values are encoded; the keys are our own.
+ */
+export declare function getUrlWithParams(path: ApiPath, extra?: Dict): string;
+/** Whether this path should go to its debug twin. */
+export declare function usesDebugApi(path: ApiPath): boolean;
+/**
+ * Headers for every call made after device registration.
+ *
+ * apid and mapid are the only two, because they are the only two every url allows: the v2
+ * endpoints declare Access-Control-Allow-Headers as exactly "apid,mapid", and a browser drops
+ * any header outside that list at the preflight. Asking for the debug twin is done with the url
+ * alone, which needs no permission to send.
+ */
+export declare function apiHeaders(): RequestHeaders;
+/**
+ * A rejection that carries the server's own answer, so a caller can tell *why* it failed.
+ * Without this the reason is flattened into a string and a permanent refusal is indistinguishable
+ * from a dropped connection.
+ */
+export interface ServerRejection extends Error {
+    serverResult?: ServerResult;
+}
+/**
+ * Whether a rejection is the server saying "never": the batch is malformed and keeping it would
+ * block every later batch behind it, for good. Anything else — a 5xx, a timeout, no network — is
+ * worth retrying and must not be treated this way.
+ */
+export declare function isPermanentRefusal(err: unknown): boolean;
+/**
+ * Sends one request. Resolves with the parsed response when it reports success; otherwise
+ * rejects with an Error carrying the server's answer. Requests are independent of each other:
+ * nothing orders one behind another.
+ */
+export declare function postToApptics(path: ApiPath, payload: RequestBody, headers: RequestHeaders, label: string, extra?: Dict): Promise<ServerResult>;
+/**
+ * The most a page may have in flight as keepalive bodies at once. Browsers refuse a keepalive
+ * request once the bodies still in flight would pass 64 KiB; this stays under that with room for
+ * the url and headers.
+ */
+export declare const KEEPALIVE_BUDGET: number;
+/**
+ * Sends as the page goes away, where a normal XHR would be cancelled with the document.
+ *
+ * `keepalive` is what lets the request outlive the page. fetch is used rather than sendBeacon
+ * because sendBeacon cannot carry the apid and mapid headers these urls require.
+ *
+ * The request leaves before this returns, so a caller never has to wait on it to send the next
+ * thing. The promise settles when the answer arrives, if the page is still there to see it: a
+ * caller removes what it sent only then. Data whose answer never comes stays stored and goes
+ * again on the next visit as attempt 2, which `attempt` and `firstattempttime` let the server
+ * recognise as a copy rather than store twice.
+ *
+ * A body that would take the page past the keepalive budget is not sent at all: the browser would
+ * refuse it, and it is better kept for the next visit than lost.
+ */
+export declare function postKeepalive(path: ApiPath, payload: RequestBody, headers: RequestHeaders, label: string, extra?: Dict): Promise<ServerResult>;
+/** A labelled rejection for crawlers (the SDK does nothing for them), otherwise null. */
+export declare function rejectIfDisabled(label: string): Promise<never> | null;
+/** A labelled rejection when the browser is offline, otherwise null. */
+export declare function rejectIfOffline(label: string): Promise<never> | null;
+/** Device ids sent alongside every payload. */
+export declare function getMetaObj(): Dict;
+/**
+ * Calls made after registration need apid/mapid. Without them this asks device.ts to
+ * refresh device info (which registers) and returns a labelled rejection; otherwise null. Shared by sender, user
+ * and feedback (P11).
+ */
+export declare function rejectIfNoDeviceIds(label: string): Promise<never> | null;
+/** Whether device/add has given this browser its deviceid. */
+export declare function hasDeviceId(): boolean;