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

package/dist/esm/core/attempts.js

@@ -0,0 +1,106 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { RETRY_CAPABLE_PATHS } from './constants.js';
+import { user_defaults } from './storage.js';
+import { nowMs } from './utils.js';
+
+/**
+ * Retry bookkeeping: `attempt`, `firstattempttime` and `lst`.
+ *
+ * Every url that carries data declares all three; app/addversion and getsdkconfig declare none,
+ * because they are start-up calls whose answers the SDK needs rather than payloads it is pushing.
+ *
+ * What they are for is the case this SDK cannot see on its own. A send goes out, the server
+ * stores it, and the answer is lost on the way back — a closed tab, a dropped connection, a
+ * proxy that times out. The SDK has no way to tell that from a send that never arrived, so it
+ * sends again. `attempt` and `firstattempttime` are what let the server recognise the second
+ * copy as the same payload rather than storing it twice. Without them, every retry is a
+ * duplicate session.
+ *
+ * `attempt` is declared `regex="[1-5]"`, so five is not a policy choice here — it is the largest
+ * number the proxy will accept. A batch that has not landed in five passes is dropped, because
+ * the sixth would be refused for the param rather than for the payload, which would look like a
+ * different fault entirely.
+ *
+ * State is per path and survives a reload, which is the point: the tab that was closed mid-send
+ * is exactly the one that needs to say "attempt 2" when it comes back.
+ */
+/** The largest value `attempt` may carry, from its own regex. */
+const MAX_ATTEMPTS = 5;
+const STORE_KEY = 'sendstate'; // no i18n
+function allState() {
+    var saved = user_defaults.item(STORE_KEY);
+    return saved && typeof saved === 'object' ? saved : {};
+}
+function stateOf(path) {
+    var state = allState()[path];
+    return state && typeof state === 'object'
+        ? { attempt: Number(state.attempt) || 1, firstattempttime: Number(state.firstattempttime) || 0, lst: Number(state.lst) || 0 }
+        : { attempt: 1, firstattempttime: 0, lst: 0 };
+}
+function save(path, state) {
+    var all = allState();
+    all[path] = state;
+    user_defaults.add(STORE_KEY, all);
+}
+/**
+ * Whether this path has already used its five attempts, so the batch should be dropped rather
+ * than sent a sixth time with a param the proxy will refuse.
+ */
+function attemptsExhausted(path) {
+    return stateOf(path).attempt > MAX_ATTEMPTS;
+}
+/**
+ * Records that a send is going out, and returns the params to put on it.
+ *
+ * Call it once per request, immediately before sending: it is what moves the attempt counter on,
+ * so calling it twice for one request would skip a number and reach five early.
+ */
+function beginAttempt(path) {
+    if (!RETRY_CAPABLE_PATHS[path]) {
+        return {};
+    }
+    var state = stateOf(path);
+    var at = nowMs();
+    if (state.attempt <= 1 || state.firstattempttime === 0) {
+        state.attempt = 1;
+        state.firstattempttime = at;
+    }
+    var params = {
+        attempt: String(Math.min(state.attempt, MAX_ATTEMPTS)),
+        firstattempttime: state.firstattempttime,
+    };
+    // lst is the last send this path had accepted. There is none before the first one lands, and
+    // an optional param is better absent than present and meaningless
+    if (state.lst > 0) {
+        params.lst = state.lst; // no i18n
+    }
+    // the next send for this path is the next attempt, unless this one is confirmed first
+    save(path, { attempt: state.attempt + 1, firstattempttime: state.firstattempttime, lst: state.lst });
+    return params;
+}
+/**
+ * Records that a send was accepted: the counter goes back to 1 and `lst` moves to now.
+ *
+ * For a page-close send the confirmation arrives after the caller has moved on, which is fine —
+ * nothing waits for this, it only decides what the *next* send says about itself.
+ */
+function attemptSucceeded(path) {
+    if (!RETRY_CAPABLE_PATHS[path]) {
+        return;
+    }
+    save(path, { attempt: 1, firstattempttime: 0, lst: nowMs() });
+}
+/** Gives up on the current run of attempts, so the next send starts again at 1. */
+function resetAttempts(path) {
+    if (!RETRY_CAPABLE_PATHS[path]) {
+        return;
+    }
+    var state = stateOf(path);
+    save(path, { attempt: 1, firstattempttime: 0, lst: state.lst });
+}
+/** Forgets every path's bookkeeping. reset() calls it. */
+function clearAttempts() {
+    user_defaults.add(STORE_KEY, undefined);
+}
+
+export { MAX_ATTEMPTS, attemptSucceeded, attemptsExhausted, beginAttempt, clearAttempts, resetAttempts };

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

@@ -0,0 +1,32 @@
+import { type Queue } from './storage.js';
+import { type ApiPath } from './transport.js';
+import type { Dict, QueueItem, ServerResult } from '../types.js';
+/** Retries `send` in 500 ms, replacing any retry already scheduled. */
+export declare function defer(send: () => Promise<void>): void;
+export declare function clearDefer(): void;
+/** Only one tab sends a queue at a time. Without the Web Locks API, runs directly (1.x behaviour). */
+export declare function withSendLock(name: string, run: () => Promise<void>): Promise<void>;
+/**
+ * The batch to send: closed items within batch_request_timeout days.
+ * Expired items are removed from the queue without being sent.
+ */
+export declare function freshItems(queue: Queue, isClosed: (item: QueueItem) => boolean, timeOf: (item: QueueItem) => number): Promise<QueueItem[]>;
+/**
+ * Sends one batch of queued items. Resolves only when the server has accepted it, so the caller
+ * removes the items then and not before: a batch that fails stays queued and goes again on the
+ * next pass, as attempt 2, which `attempt` and `firstattempttime` let the server recognise as a
+ * copy rather than store twice.
+ *
+ * With `forget` (the page is closing) it goes by keepalive, and the promise settles if the answer
+ * arrives before the page is gone. See postKeepalive.
+ *
+ * Five attempts is the cap, because `attempt` is declared regex="[1-5]" and a sixth would be
+ * refused for the param rather than for the payload.
+ */
+export declare function sendBatch(path: ApiPath, label: string, _payload: Dict, forget?: boolean): Promise<ServerResult>;
+/**
+ * Hands a send's outcome back to a sender. Normally the sender waits for it. While the page
+ * closes it does not: the request is already out, and waiting would hold the next queue's send
+ * until after the page has gone. The outcome is still handled whenever it arrives.
+ */
+export declare function awaitUnlessClosing(landed: Promise<unknown>, forget: boolean | undefined, label: string): Promise<void> | undefined;

package/dist/esm/core/batch.js

@@ -0,0 +1,108 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { _ZAP, isExpired } from './state.js';
+import { Console, warnAlways } from './logger.js';
+import { isEmptyObj, sizeof } from './utils.js';
+import './constants.js';
+import { shouldTrackOrSendData } from './consent.js';
+import { attemptsExhausted, MAX_ATTEMPTS, resetAttempts } from './attempts.js';
+import { rejectIfDisabled, rejectIfNoDeviceIds, getMetaObj, postKeepalive, apiHeaders, postToApptics } from './transport.js';
+
+/** Retries `send` in 500 ms, replacing any retry already scheduled. */
+function defer(send) {
+    if (_ZAP._deferSendTimer) {
+        clearTimeout(_ZAP._deferSendTimer);
+    }
+    _ZAP._deferSendTimer = setTimeout(send, 500);
+}
+function clearDefer() {
+    if (_ZAP._deferSendTimer) {
+        clearTimeout(_ZAP._deferSendTimer);
+        _ZAP._deferSendTimer = null;
+    }
+}
+/** Only one tab sends a queue at a time. Without the Web Locks API, runs directly (1.x behaviour). */
+function withSendLock(name, run) {
+    var locks = typeof navigator !== 'undefined' ? navigator.locks : undefined; // no i18n
+    if (!locks || typeof locks.request !== 'function') { // no i18n
+        return run();
+    }
+    return locks.request('apptics-send-' + name, { ifAvailable: true }, function (lock) {
+        return lock ? run() : undefined;
+    }).then(function () { return undefined; });
+}
+/**
+ * The batch to send: closed items within batch_request_timeout days.
+ * Expired items are removed from the queue without being sent.
+ */
+function freshItems(queue, isClosed, timeOf) {
+    return queue.payload().then(function (items) {
+        var fresh = [];
+        var expired = [];
+        items.forEach(function (item) {
+            if (!isClosed(item)) {
+                return;
+            }
+            (isExpired(timeOf(item)) ? expired : fresh).push(item);
+        });
+        return expired.length ? queue.remove(expired).then(function () { return fresh; }) : fresh;
+    });
+}
+/**
+ * Sends one batch of queued items. Resolves only when the server has accepted it, so the caller
+ * removes the items then and not before: a batch that fails stays queued and goes again on the
+ * next pass, as attempt 2, which `attempt` and `firstattempttime` let the server recognise as a
+ * copy rather than store twice.
+ *
+ * With `forget` (the page is closing) it goes by keepalive, and the promise settles if the answer
+ * arrives before the page is gone. See postKeepalive.
+ *
+ * Five attempts is the cap, because `attempt` is declared regex="[1-5]" and a sixth would be
+ * refused for the param rather than for the payload.
+ */
+function sendBatch(path, label, _payload, forget) {
+    var blocked = rejectIfDisabled(label);
+    if (blocked) {
+        return blocked;
+    }
+    if (!shouldTrackOrSendData()) {
+        return Promise.reject(label + ': tracking is off'); // no i18n
+    }
+    if (isEmptyObj(_payload)) {
+        return Promise.reject(label + ': nothing to send'); // no i18n
+    }
+    var missing = rejectIfNoDeviceIds(label);
+    if (missing) {
+        return missing;
+    }
+    if (!_payload.hasOwnProperty('meta')) { // no i18n
+        _payload.meta = getMetaObj();
+    }
+    if (attemptsExhausted(path)) {
+        // five passes without a confirmed landing. Keeping it would block every later batch
+        // behind a payload the proxy will now refuse for its attempt number alone
+        warnAlways('apptics: dropping a ' + label + ' batch after ' + MAX_ATTEMPTS + ' attempts'); // no i18n
+        resetAttempts(path);
+        return Promise.resolve({ result: 'success' }); // no i18n
+    }
+    Console.log(label + ': Payload size : ' + (sizeof(_payload) / 1024)); // no i18n
+    var body = JSON.stringify(_payload);
+    return forget
+        ? postKeepalive(path, body, apiHeaders(), label)
+        : postToApptics(path, body, apiHeaders(), label);
+}
+/**
+ * Hands a send's outcome back to a sender. Normally the sender waits for it. While the page
+ * closes it does not: the request is already out, and waiting would hold the next queue's send
+ * until after the page has gone. The outcome is still handled whenever it arrives.
+ */
+function awaitUnlessClosing(landed, forget, label) {
+    if (!forget) {
+        return landed.then(function () { return undefined; });
+    }
+    landed.catch(function (err) {
+        Console.log(label + ': not confirmed before the page closed, kept for the next send: ' + String(err)); // no i18n
+    });
+    return undefined;
+}
+
+export { awaitUnlessClosing, clearDefer, defer, freshItems, sendBatch, withSendLock };

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

@@ -0,0 +1,28 @@
+/**
+ * Where a log line was raised, for logSDK's `filename` and `linenumber`.
+ *
+ * There is no caller introspection in a browser, so the only way to answer "which line was this"
+ * is to throw an Error nobody catches and read its stack. That is cheap enough for a channel that
+ * only carries the SDK's own failures, but it is never on the app's path: everything here is
+ * wrapped so a stack we cannot parse costs a line its call site and nothing more.
+ */
+export interface CallSite {
+    /** The script's basename, not its url: logSDK caps filename at 100 characters. */
+    filename: string;
+    /** 0 when the stack gave us nothing — see entryFor() for why it is still sent. */
+    linenumber: number;
+    /** The calling function's name, when the frame has one. Anonymous callers have none. */
+    fn?: string;
+}
+export declare const NO_CALL_SITE: CallSite;
+/**
+ * The frame `skip` frames down a stack, counting only the ones that name a file — V8 heads its
+ * stacks with an `Error` line and Firefox does not, so counting raw lines would read a different
+ * frame in each browser.
+ */
+export declare function callSiteFromStack(stack: string | undefined, skip: number): CallSite;
+/**
+ * Where the caller `skip` levels above this call sits. `skip` is 0 for this function's own
+ * caller; each wrapper between that caller and the place worth reporting adds one.
+ */
+export declare function callSite(skip: number): CallSite;

package/dist/esm/core/callsite.js

@@ -0,0 +1,89 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+/**
+ * Where a log line was raised, for logSDK's `filename` and `linenumber`.
+ *
+ * There is no caller introspection in a browser, so the only way to answer "which line was this"
+ * is to throw an Error nobody catches and read its stack. That is cheap enough for a channel that
+ * only carries the SDK's own failures, but it is never on the app's path: everything here is
+ * wrapped so a stack we cannot parse costs a line its call site and nothing more.
+ */
+const NO_CALL_SITE = { filename: '', linenumber: 0, fn: '' };
+/** logSDK declares max-len="100" on filename. */
+const FILENAME_MAX = 100;
+/**
+ * The file and line out of one stack frame, in either shape a browser produces:
+ *   V8:              `    at doThing (https://host/app.js:12:34)`
+ *   Firefox/Safari:  `doThing@https://host/app.js:12:34`
+ * Both end in `:line:column`, which is the only part that is the same everywhere, so the match is
+ * anchored there and the column is read only so that it can be thrown away — without it the
+ * pattern would take the column for the line.
+ */
+const FRAME = /([^\s(@]+):(\d+):(\d+)\)?$/;
+/** `https://host/path/app.js?v=2` -> `app.js`. The url would not fit in 100 characters. */
+function basename(url) {
+    var path = url.split(/[?#]/)[0] || url;
+    var parts = path.split('/');
+    return (parts[parts.length - 1] || path).slice(0, FILENAME_MAX);
+}
+/**
+ * The function a frame names, in either shape:
+ *   V8:              `at doThing (` — or `at async doThing (`
+ *   Firefox/Safari:  `doThing@`
+ * A frame without one (`at https://…` or `@https://…`) is an anonymous caller, and gets ''.
+ */
+const FRAME_FN_V8 = /^at\s+(?:async\s+)?(.+?)\s+\(/;
+const FRAME_FN_OTHER = /^([^@\s]+)@/;
+function frameFunction(frame) {
+    var match = FRAME_FN_V8.exec(frame) || FRAME_FN_OTHER.exec(frame);
+    return match ? (match[1] || '') : ''; // no i18n
+}
+function parseFrame(line) {
+    var trimmed = line.trim();
+    var match = FRAME.exec(trimmed);
+    if (match === null) {
+        return null;
+    }
+    var line_no = Number(match[2]);
+    if (!isFinite(line_no)) {
+        return null;
+    }
+    return { filename: basename(match[1] || ''), linenumber: line_no, fn: frameFunction(trimmed) };
+}
+/**
+ * The frame `skip` frames down a stack, counting only the ones that name a file — V8 heads its
+ * stacks with an `Error` line and Firefox does not, so counting raw lines would read a different
+ * frame in each browser.
+ */
+function callSiteFromStack(stack, skip) {
+    if (!stack) {
+        return NO_CALL_SITE;
+    }
+    var lines = stack.split('\n');
+    var seen = 0;
+    for (var i = 0; i < lines.length; i++) {
+        var frame = parseFrame(lines[i] || '');
+        if (frame === null) {
+            continue;
+        }
+        if (seen++ < skip) {
+            continue;
+        }
+        return frame;
+    }
+    return NO_CALL_SITE;
+}
+/**
+ * Where the caller `skip` levels above this call sits. `skip` is 0 for this function's own
+ * caller; each wrapper between that caller and the place worth reporting adds one.
+ */
+function callSite(skip) {
+    try {
+        // +1 for this function's own frame, which is never the answer
+        return callSiteFromStack(new Error().stack, skip + 1);
+    }
+    catch (err) {
+        return NO_CALL_SITE;
+    }
+}
+
+export { NO_CALL_SITE, callSite, callSiteFromStack };

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

@@ -0,0 +1,23 @@
+import type { TrackingStatus } from '../types.js';
+/** DNT counts only when not ignored; when it counts, tracking switches to NO_TRACKING. */
+export declare function hasDoNotTrackEnabled(): boolean;
+export declare function opt_in_status(): TrackingStatus;
+export declare function shouldTrackOrSendData(): boolean;
+/**
+ * The guard every tracking call starts with: init() has run, the client isn't a crawler,
+ * and consent / server flags allow tracking.
+ */
+export declare function canTrack(caller: string): boolean;
+/** canTrack plus the server's `engagementtracking` flag from getupdates (events, screens, sessions, api calls). */
+export declare function canTrackEngagement(caller: string): boolean;
+/**
+ * canTrack plus the server's heatmap flag (getsdkconfig module 18).
+ *
+ * Heatmap rode the engagement flag until v2 gave it one of its own, which matters: an app may
+ * well want events while declining to have every click's coordinates recorded.
+ */
+export declare function canTrackHeatmap(caller: string): boolean;
+/** canTrack plus the server's `errortracking` flag from getupdates. */
+export declare function canTrackErrors(caller: string): boolean;
+export declare function setTrackingStatus(trackingState: TrackingStatus): void;
+export declare function getTrackingStatus(): TrackingStatus;

package/dist/esm/core/consent.js

@@ -0,0 +1,120 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { AP_TRACKING_STATUS } from './constants.js';
+import { _ZAP } from './state.js';
+import { Console } from './logger.js';
+import { isEmpty, isSuccess } from './utils.js';
+import { tracking_preference } from './storage.js';
+import { isDntOn, is_apptics_disabled } from './env.js';
+import { hooks } from './hooks.js';
+
+/** DNT counts only when not ignored; when it counts, tracking switches to NO_TRACKING. */
+function hasDoNotTrackEnabled() {
+    if (_ZAP._ignoreDnt) {
+        return false;
+    }
+    if (isDntOn()) {
+        Console.warn('hasDoNotTrackEnabled: DoNotTrack is enabled'); // no i18n
+        setTrackingStatus(AP_TRACKING_STATUS.NO_TRACKING);
+        Console.log('hasDoNotTrackEnabled: Setting tracking status to NO_TRACKING'); // no i18n
+        return true;
+    }
+    return false;
+}
+function opt_in_status() {
+    if (hasDoNotTrackEnabled()) {
+        Console.warn('opt_in_status: It seems "Do Not Track" is enabled in this browser. Please enable tracking in the browser settings to continue tracking.'); // no i18n
+        return AP_TRACKING_STATUS.NO_TRACKING;
+    }
+    var status = tracking_preference.opt_in_status();
+    if (status == -1) {
+        Console.warn('opt_in_status: You are opted out of Apptics tracking. This will prevent the our SDK from sending no data to our server.'); // no i18n
+    }
+    return status;
+}
+function shouldTrackOrSendData() {
+    var optInStatus = opt_in_status();
+    return optInStatus > -1 && _ZAP._shouldTrack;
+}
+/**
+ * The guard every tracking call starts with: init() has run, the client isn't a crawler,
+ * and consent / server flags allow tracking.
+ */
+function canTrack(caller) {
+    if (!_ZAP._token) {
+        Console.warn('apptics.' + caller + ': You must call apptics.init() first'); // no i18n
+        return false;
+    }
+    if (is_apptics_disabled()) {
+        return false;
+    }
+    return shouldTrackOrSendData();
+}
+/** canTrack plus the server's `engagementtracking` flag from getupdates (events, screens, sessions, api calls). */
+function canTrackEngagement(caller) {
+    if (!canTrack(caller)) {
+        return false;
+    }
+    if (!_ZAP._engagementTracking) {
+        Console.log('apptics.' + caller + ': engagement tracking is turned off by the server'); // no i18n
+        return false;
+    }
+    return true;
+}
+/**
+ * canTrack plus the server's heatmap flag (getsdkconfig module 18).
+ *
+ * Heatmap rode the engagement flag until v2 gave it one of its own, which matters: an app may
+ * well want events while declining to have every click's coordinates recorded.
+ */
+function canTrackHeatmap(caller) {
+    if (!canTrack(caller)) {
+        return false;
+    }
+    if (!_ZAP._heatmapTracking) {
+        Console.log('apptics.' + caller + ': heatmap tracking is turned off by the server'); // no i18n
+        return false;
+    }
+    return true;
+}
+/** canTrack plus the server's `errortracking` flag from getupdates. */
+function canTrackErrors(caller) {
+    if (!canTrack(caller)) {
+        return false;
+    }
+    if (!_ZAP._errorTracking) {
+        Console.log('apptics.' + caller + ': error tracking is turned off by the server'); // no i18n
+        return false;
+    }
+    return true;
+}
+function setTrackingStatus(trackingState) {
+    if (isEmpty(trackingState)) {
+        Console.warn('setTrackingStatus: trackingStatus is Empty'); // no i18n
+        return;
+    }
+    if (tracking_preference.opt_in_status() == trackingState) {
+        return;
+    }
+    tracking_preference.update_status(trackingState);
+    _ZAP._devicestatus = tracking_preference.opt_in_status();
+    _ZAP._isanonrequired = tracking_preference.opt_in_status() == AP_TRACKING_STATUS.USAGE_TRACKING_WITH_PII ? false : _ZAP._isanonrequired;
+    if (tracking_preference.opt_in_status() != AP_TRACKING_STATUS.NO_TRACKING) {
+        Console.log('setTrackingStatus: Updating device info with new tracking status'); // no i18n
+        hooks.updateDevice(_ZAP._device_info).then(function (result) {
+            if (isSuccess(result)) {
+                Console.log('setTrackingStatus: Device info updated with new tracking status' + JSON.stringify(result.data)); // no i18n
+                Console.dir(result.data);
+            }
+            else {
+                Console.log('setTrackingStatus: Error updating device info with new tracking status: ' + JSON.stringify(result)); // no i18n
+            }
+        }).catch(function (err) {
+            Console.warn('setTrackingStatus: Error updating device info with new tracking status: ' + JSON.stringify(err)); // no i18n
+        });
+    }
+}
+function getTrackingStatus() {
+    return opt_in_status();
+}
+
+export { canTrack, canTrackEngagement, canTrackErrors, canTrackHeatmap, getTrackingStatus, hasDoNotTrackEnabled, opt_in_status, setTrackingStatus, shouldTrackOrSendData };