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

package/dist/cjs/remotelog/gate.js

@@ -0,0 +1,54 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+'use strict';
+
+var state = require('../core/state.js');
+var env = require('../core/env.js');
+var consent = require('../core/consent.js');
+
+/**
+ * The one switch both halves of the remote logger ask: may this line be recorded, and may
+ * what is stored be sent? It lives on its own so recording and sending don't import each other.
+ */
+/** The app logger's switch: off until the app calls logger.enable(), as on Android and iOS. */
+let appLoggerOn = false;
+function setAppLogger(on) {
+    appLoggerOn = on;
+}
+function appLoggerEnabled() {
+    return appLoggerOn;
+}
+/**
+ * What every remote-log line needs, whoever wrote it: a running SDK, a client we send anything
+ * for, the server's remote logger switch, and consent.
+ */
+function remoteLoggerReachable() {
+    if (!state._ZAP._token || env.is_apptics_disabled()) {
+        return false;
+    }
+    // getsdkconfig module 17: the server can switch the remote logger off on its own
+    if (!state._ZAP._remoteLoggerEnabled) {
+        return false;
+    }
+    return consent.shouldTrackOrSendData();
+}
+/** The SDK's own diagnostics may be recorded: `remote_log` is on and the logger is reachable. */
+function remoteLogEnabled() {
+    return state.getConfig('remote_log') && remoteLoggerReachable(); // no i18n
+}
+/** An app's own log line may be recorded: the app enabled the logger and it is reachable. */
+function appLogEnabled() {
+    return appLoggerOn && remoteLoggerReachable();
+}
+/**
+ * What is stored may be sent. Either writer is enough: app logging works with `remote_log`
+ * off, since that switch covers only the SDK's own diagnostics.
+ */
+function remoteLogSendable() {
+    return (state.getConfig('remote_log') || appLoggerOn) && remoteLoggerReachable(); // no i18n
+}
+
+exports.appLogEnabled = appLogEnabled;
+exports.appLoggerEnabled = appLoggerEnabled;
+exports.remoteLogEnabled = remoteLogEnabled;
+exports.remoteLogSendable = remoteLogSendable;
+exports.setAppLogger = setAppLogger;

package/dist/cjs/remotelog/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Remote logger: the SDK's own diagnostics, sent to console/addlog.
+ *
+ * This file is not the app-facing logging API — that is logger.ts, which shares this queue and
+ * delivery but has its own switch. This file answers "this app reports no data — what is the SDK
+ * actually doing on the user's machine?", so what it carries is the SDK's own failures, each
+ * tagged with the module that was mid-flight (Session, Screen, Event, API, Properties).
+ * App errors belong to exception/error, an app's remote log lines to logger.ts, and lines meant
+ * for a feedback report to feedback/logs.ts.
+ *
+ * This file records lines, send.ts delivers them, and gate.ts holds the switch both ask.
+ * Nothing here is exported to apps: the SDK writes these lines itself, through logFailure()
+ * in core/logger.ts.
+ */
+import { AP_LOG_MODULE } from '../core/constants.js';
+import { type CallSite } from '../core/callsite.js';
+/** One of console/addlog's `module` values. */
+export type LogModule = (typeof AP_LOG_MODULE)[keyof typeof AP_LOG_MODULE];
+/**
+ * Records one line about `module` for console/addlog. Never throws and never blocks the caller:
+ * a diagnostics channel that breaks the flow it reports on would be worse than no channel.
+ */
+export declare function remoteLog(module: LogModule, message: unknown, site?: CallSite): void;
+export { remoteLogEnabled } from './gate.js';
+export { forgetStoredLogs, sendStoredLogs } from './send.js';

package/dist/cjs/remotelog/index.js

@@ -0,0 +1,55 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+'use strict';
+
+require('../core/constants.js');
+var callsite = require('../core/callsite.js');
+var storage = require('../core/storage.js');
+var hooks = require('../core/hooks.js');
+var utils = require('../core/utils.js');
+var gate = require('./gate.js');
+var send = require('./send.js');
+
+/**
+ * Remote logger: the SDK's own diagnostics, sent to console/addlog.
+ *
+ * This file is not the app-facing logging API — that is logger.ts, which shares this queue and
+ * delivery but has its own switch. This file answers "this app reports no data — what is the SDK
+ * actually doing on the user's machine?", so what it carries is the SDK's own failures, each
+ * tagged with the module that was mid-flight (Session, Screen, Event, API, Properties).
+ * App errors belong to exception/error, an app's remote log lines to logger.ts, and lines meant
+ * for a feedback report to feedback/logs.ts.
+ *
+ * This file records lines, send.ts delivers them, and gate.ts holds the switch both ask.
+ * Nothing here is exported to apps: the SDK writes these lines itself, through logFailure()
+ * in core/logger.ts.
+ */
+/**
+ * Records one line about `module` for console/addlog. Never throws and never blocks the caller:
+ * a diagnostics channel that breaks the flow it reports on would be worse than no channel.
+ */
+function remoteLog(module, message, site) {
+    try {
+        if (!gate.remoteLogEnabled()) {
+            return;
+        }
+        var where = site || callsite.NO_CALL_SITE;
+        storage.consolelog_transactions.add({
+            module: module,
+            happenedat: utils.nowMs(),
+            exceptionlog: String(message),
+            attempt: 1,
+            filename: where.filename,
+            linenumber: where.linenumber,
+        });
+        send.scheduleSend();
+    }
+    catch (err) {
+        // never let the logger be the thing that fails
+    }
+}
+hooks.hooks.remoteLog = remoteLog;
+
+exports.remoteLogEnabled = gate.remoteLogEnabled;
+exports.forgetStoredLogs = send.forgetStoredLogs;
+exports.sendStoredLogs = send.sendStoredLogs;
+exports.remoteLog = remoteLog;

package/dist/cjs/remotelog/logger.d.ts

@@ -0,0 +1,28 @@
+/** The level numbers log/add takes and the Remote Logger page names, in the native SDKs' order. */
+export declare const LOG_LEVEL: Readonly<{
+    VERBOSE: 1;
+    DEBUG: 2;
+    INFO: 3;
+    WARN: 4;
+    ERROR: 5;
+}>;
+export interface AppticsLogger {
+    /** Starts recording log lines. Off until called. */
+    enable(): void;
+    /** Stops recording log lines. */
+    disable(): void;
+    /** Whether log lines are being recorded. */
+    isEnabled(): boolean;
+    /** Verbose, level 1. The tag leads the message as `[tag]`. */
+    v(tag: string, message: unknown, ...details: unknown[]): void;
+    /** Debug, level 2. */
+    d(tag: string, message: unknown, ...details: unknown[]): void;
+    /** Info, level 3. */
+    i(tag: string, message: unknown, ...details: unknown[]): void;
+    /** Warning, level 4. */
+    w(tag: string, message: unknown, ...details: unknown[]): void;
+    /** Error, level 5. */
+    e(tag: string, message: unknown, ...details: unknown[]): void;
+}
+/** Android's AppticsLogger: enable, disable, isEnabled and v / d / i / w / e(tag, message). */
+export declare const AppticsLogger: AppticsLogger;

package/dist/cjs/remotelog/logger.js

@@ -0,0 +1,139 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+'use strict';
+
+var constants = require('../core/constants.js');
+var callsite = require('../core/callsite.js');
+var storage = require('../core/storage.js');
+var guard = require('../core/guard.js');
+var utils = require('../core/utils.js');
+var state = require('../core/state.js');
+var gate = require('./gate.js');
+var send = require('./send.js');
+
+/**
+ * AppticsLogger, as on Android: lines the app writes, shown on the console's Remote Logger page.
+ *
+ *   AppticsLogger.enable();
+ *   AppticsLogger.i('Checkout', 'Payment started');
+ *   AppticsLogger.e('Checkout', 'Payment failed', err);
+ *
+ * It mirrors the native SDKs so the page reads the same whatever sent the line: off until
+ * enable() (AppticsLogger.enable() on Android, APLog.setShouldLog on iOS), and five levels in
+ * the iOS order — verbose, debug, info, warn, error — sent as 1 to 5, which is the scale the
+ * Remote Logger page reads back.
+ *
+ * Lines share the SDK diagnostics' queue and its log/add delivery, so they are stored before
+ * they are sent and survive a failed send and a reload. They are a separate switch, though:
+ * `remote_log: false` silences the SDK's own failures, not the app's logging.
+ */
+/** The level numbers log/add takes and the Remote Logger page names, in the native SDKs' order. */
+const LOG_LEVEL = Object.freeze({ VERBOSE: 1, DEBUG: 2, INFO: 3, WARN: 4, ERROR: 5 });
+/** What a line's `function` says when the caller had no name to give (an anonymous callback). */
+const ANONYMOUS_CALLER = 'App'; // no i18n
+/**
+ * The caller's name as logSDK's `function` accepts it: safe_string refuses angle brackets and an
+ * empty value, and the field stops at 100 characters.
+ */
+function functionName(site) {
+    var name = String(site.fn || '').replace(/<anonymous>/g, '').replace(/[<>]/g, '').trim(); // no i18n
+    if (name === '' || /^(Object|Module|eval)\.?$/.test(name)) {
+        return ANONYMOUS_CALLER;
+    }
+    return name.slice(0, constants.LOG_FUNCTION_MAX);
+}
+/** One detail as text: an Error as its stack (which leads with name and message), JSON otherwise. */
+function describe(value) {
+    if (value instanceof Error) {
+        var head = value.name + ': ' + value.message; // no i18n
+        return value.stack && value.stack.indexOf(value.message) !== -1 ? value.stack : head;
+    }
+    if (typeof value === 'string') { // no i18n
+        return value;
+    }
+    try {
+        var json = JSON.stringify(value);
+        return json === undefined ? String(value) : json;
+    }
+    catch (err) {
+        return String(value);
+    }
+}
+/**
+ * Stores one line. Reached through guard(), so a line logged before start-up finishes waits for
+ * it — which is why the time and call site are taken by the caller, not here.
+ */
+function record(level, message, details, at, site) {
+    if (!gate.appLogEnabled()) {
+        return;
+    }
+    var text = [message].concat(details).map(describe).join(' '); // no i18n
+    storage.consolelog_transactions.add({
+        module: functionName(site),
+        level: level,
+        happenedat: at,
+        exceptionlog: text,
+        attempt: 1,
+        filename: site.filename,
+        linenumber: site.linenumber,
+    });
+    send.scheduleSend();
+}
+const recordLine = guard.guard('AppticsLogger', record); // no i18n
+/** The browser console method each level prints with under `show_logs`, as Logcat shows them. */
+const CONSOLE_METHOD = Object.freeze({
+    1: 'debug', 2: 'debug', 3: 'info', 4: 'warn', 5: 'error', // no i18n
+});
+/**
+ * `show_logs`: the line in the browser console too, as Android's showLogs prints to Logcat. For
+ * the developer, so it prints whether or not the remote logger is enabled or allowed to record,
+ * and the arguments go over untouched so the console can still expand an object or an Error.
+ */
+function show(level, args) {
+    if (state.getConfig('show_logs') !== true) {
+        return;
+    }
+    var method = CONSOLE_METHOD[level] || 'log'; // no i18n
+    if (typeof console !== 'undefined' && typeof console[method] === 'function') { // no i18n
+        console[method].apply(console, args);
+    }
+}
+/**
+ * A level's Android-style method, `v/d/i/w/e(tag, message, ...details)`. The tag leads the
+ * message as `[tag]`; the function, file and line are still the caller's, as with the long names.
+ */
+function tagged(level) {
+    return function (tag, message, ...details) {
+        try {
+            var label = tag === undefined || tag === null ? '' : String(tag).trim(); // no i18n
+            var parts = label === '' ? [message].concat(details) : ['[' + label + ']', message].concat(details); // no i18n
+            show(level, parts);
+            // skip 1: this function's own frame, so the site is the app's line that logged
+            recordLine(level, parts[0], parts.slice(1), utils.nowMs(), callsite.callSite(1));
+        }
+        catch (err) {
+            // logging must never be the thing that breaks the app
+        }
+    };
+}
+/** Turns the app logger on, or off with `false`. Off by default. */
+function enable(on) {
+    gate.setAppLogger(on !== false);
+}
+/** Turns the app logger off, as AppticsLogger.disable() does; the same as enable(false). */
+function disable() {
+    gate.setAppLogger(false);
+}
+/** Android's AppticsLogger: enable, disable, isEnabled and v / d / i / w / e(tag, message). */
+const AppticsLogger = {
+    enable: guard.guard('AppticsLogger.enable', function () { enable(true); }), // no i18n
+    disable: guard.guard('AppticsLogger.disable', disable), // no i18n
+    isEnabled: guard.guard('AppticsLogger.isEnabled', gate.appLoggerEnabled), // no i18n
+    v: tagged(LOG_LEVEL.VERBOSE),
+    d: tagged(LOG_LEVEL.DEBUG),
+    i: tagged(LOG_LEVEL.INFO),
+    w: tagged(LOG_LEVEL.WARN),
+    e: tagged(LOG_LEVEL.ERROR),
+};
+
+exports.AppticsLogger = AppticsLogger;
+exports.LOG_LEVEL = LOG_LEVEL;

package/dist/cjs/remotelog/send.d.ts

@@ -0,0 +1,13 @@
+/** Queues a pass over the stored lines, coalescing a burst into one. */
+export declare function scheduleSend(): void;
+/**
+ * Sends the stored lines as one batch. A batch the server refuses for its shape is dropped —
+ * retrying it could only fail the same way and would hold every later line behind it.
+ */
+export declare function sendStoredLogs(): Promise<void>;
+/**
+ * Sends what is stored as the page goes away, where a normal request would be cancelled.
+ * One keepalive request for the whole batch, which is what the endpoint now accepts. The lines
+ * stay stored until the server has confirmed them.
+ */
+export declare function forgetStoredLogs(): Promise<void>;

package/dist/cjs/remotelog/send.js

@@ -0,0 +1,153 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+'use strict';
+
+var constants = require('../core/constants.js');
+var state = require('../core/state.js');
+var logger = require('../core/logger.js');
+var utils = require('../core/utils.js');
+var storage = require('../core/storage.js');
+var transport = require('../core/transport.js');
+var gate = require('./gate.js');
+
+/**
+ * Delivery for the remote logger.
+ *
+ * v2 replaced console/addlog, which took one line per call and counted retries in an `attempt`
+ * param, with log/add, which takes a batch: `{ logs: [...], meta }`. A pass over the queue is now
+ * one request however many lines are waiting, so a burst of failures costs one call instead of
+ * twenty, and a line no longer has to carry its own retry bookkeeping — the batch either lands or
+ * stays for the next pass.
+ */
+/**
+ * What the stored lines may take up, as on Android (1 MB): past it the oldest are dropped, so a
+ * failing SDK or a chatty app can't fill storage. Measured in size rather than in lines, since one
+ * line can be a 10,000-character stack and another a word.
+ */
+const MAX_STORED_BYTES = 1024 * 1024;
+/** Sends are grouped, so one broken flow that logs twice makes one pass over the queue. */
+const SEND_DELAY_MS = 1000;
+/** The endpoint takes a 10 MB body; a batch is capped well inside that. */
+const MAX_PER_BATCH = 50;
+const LABEL = 'remoteLog'; // no i18n
+let sendScheduled = false;
+let sending = false;
+/**
+ * One stored line as logSDK wants it.
+ *
+ * `function` is where the module name goes — it is the only field describing *where* a line came
+ * from, and the template caps it at 100. `logmessage` is capped at 10000, so a long stack is
+ * trimmed rather than having the whole batch refused for one oversized line.
+ */
+function entryFor(item) {
+    var entry = {
+        sessionstarttime: state._ZAP._current_session.starttime || item.happenedat || utils.nowMs(),
+        logtime: item.happenedat || utils.nowMs(),
+        // an app's line carries the level it was logged at; the SDK's own failures carry none
+        level: Number(item.level) || constants.REMOTE_LOG_LEVEL,
+        logmessage: String(item.exceptionlog).slice(0, constants.CONSOLE_LOG_MAX_BODY),
+        function: String(item.module || 'SDK').slice(0, constants.LOG_FUNCTION_MAX), // no i18n
+        // the endpoint reads linenumber with getInt(), which throws on a missing key rather than
+        // defaulting, so it goes out on every line - 0 where the stack gave us no frame
+        linenumber: Number(item.linenumber) || 0,
+    };
+    // filename is read with optString and validated against file_name, whose pattern needs at
+    // least one character: sending '' would have the whole batch refused, so it is left out
+    if (!utils.isEmpty(item.filename)) {
+        entry.filename = String(item.filename).slice(0, constants.LOG_FILENAME_MAX);
+    }
+    return entry;
+}
+/** The batch body: `{ logs, meta }`, where meta is metaWebSDKV2 like every other v2 payload. */
+function bodyFor(items) {
+    return JSON.stringify({ logs: items.map(entryFor), meta: transport.getMetaObj() }); // no i18n
+}
+/** Queues a pass over the stored lines, coalescing a burst into one. */
+function scheduleSend() {
+    if (sendScheduled) {
+        return;
+    }
+    sendScheduled = true;
+    setTimeout(function () {
+        sendScheduled = false;
+        sendStoredLogs();
+    }, SEND_DELAY_MS);
+}
+/** Drops the oldest lines once the queue is over MAX_STORED_BYTES, keeping the newest that fit. */
+function trim(items) {
+    var total = 0;
+    var keepFrom = items.length;
+    // newest first: they are the ones worth keeping
+    for (var i = items.length - 1; i >= 0; i--) {
+        total += JSON.stringify(items[i]).length;
+        if (total > MAX_STORED_BYTES) {
+            break;
+        }
+        keepFrom = i;
+    }
+    if (keepFrom === 0) {
+        return items;
+    }
+    storage.consolelog_transactions.remove(items.slice(0, keepFrom));
+    return items.slice(keepFrom);
+}
+/**
+ * Sends the stored lines as one batch. A batch the server refuses for its shape is dropped —
+ * retrying it could only fail the same way and would hold every later line behind it.
+ */
+function sendStoredLogs() {
+    if (sending || !gate.remoteLogSendable() || navigator.onLine === false) {
+        return Promise.resolve();
+    }
+    sending = true;
+    return storage.consolelog_transactions.all().then(function (stored) {
+        var batch = trim(stored).slice(0, MAX_PER_BATCH);
+        if (batch.length === 0) {
+            return undefined;
+        }
+        return transport.postToApptics('consolelog', bodyFor(batch), transport.apiHeaders(), LABEL).then(function () {
+            return storage.consolelog_transactions.remove(batch);
+        }, function (err) {
+            if (transport.isPermanentRefusal(err)) {
+                logger.warnAlways('apptics: the server refused these log lines, so they were dropped: ' + String(err && err.message)); // no i18n
+                return storage.consolelog_transactions.remove(batch);
+            }
+            logger.Console.log(LABEL + ': ' + String(err)); // no i18n
+            return undefined;
+        });
+    }).then(function () {
+        sending = false;
+    }).catch(function () {
+        sending = false;
+    });
+}
+/**
+ * Sends what is stored as the page goes away, where a normal request would be cancelled.
+ * One keepalive request for the whole batch, which is what the endpoint now accepts. The lines
+ * stay stored until the server has confirmed them.
+ */
+function forgetStoredLogs() {
+    if (!gate.remoteLogSendable()) {
+        return Promise.resolve();
+    }
+    return storage.consolelog_transactions.all().then(function (stored) {
+        if (stored.length === 0) {
+            return undefined;
+        }
+        var batch = stored.slice(0, MAX_PER_BATCH);
+        // removed once the server has them; lines whose answer never comes go on the next visit
+        transport.postKeepalive('consolelog', bodyFor(batch), transport.apiHeaders(), LABEL).then(function () {
+            return storage.consolelog_transactions.remove(batch);
+        }, function (err) {
+            if (transport.isPermanentRefusal(err)) {
+                return storage.consolelog_transactions.remove(batch);
+            }
+            logger.Console.log(LABEL + ': ' + String(err)); // no i18n
+            return undefined;
+        });
+        return undefined;
+    });
+}
+
+exports.forgetStoredLogs = forgetStoredLogs;
+exports.scheduleSend = scheduleSend;
+exports.sendStoredLogs = sendStoredLogs;

package/dist/cjs/scheduler.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sends everything queued now. With `forget`, the requests are sent without waiting for a
+ * response (page hide), so they survive the page going away.
+ */
+export declare function flush(forget?: boolean): Promise<void>;
+/** Starts the flush and getupdates intervals once; later calls do nothing until stopTimers(). */
+export declare function startTimers(): void;
+export declare function stopTimers(): void;

package/dist/cjs/scheduler.js

@@ -0,0 +1,78 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+'use strict';
+
+var state = require('./core/state.js');
+var utils = require('./core/utils.js');
+var logger = require('./core/logger.js');
+var consent = require('./core/consent.js');
+var batch = require('./core/batch.js');
+var send = require('./engagement/send.js');
+var send$1 = require('./errors/send.js');
+var hooks = require('./core/hooks.js');
+var index = require('./device/index.js');
+var debug = require('./core/debug.js');
+
+/**
+ * Sends everything queued now. With `forget`, the requests are sent without waiting for a
+ * response (page hide), so they survive the page going away.
+ */
+function flush(forget) {
+    if (!consent.canTrack('flush')) { // no i18n
+        return Promise.resolve();
+    }
+    state._ZAP._sending = false;
+    // one after the other: sending both at once makes the second wait for the 500 ms retry
+    return send.sendEngagementData(forget).then(function () {
+        return send$1.sendErrorData(forget);
+    }).then(function () {
+        // no-op unless the heatmap entry was imported, which is what sets the hook
+        return hooks.hooks.sendHeatmaps(forget);
+    });
+}
+var sendingInterval = null;
+var getUpdatesInterval = null;
+/** Starts the flush and getupdates intervals once; later calls do nothing until stopTimers(). */
+function startTimers() {
+    if (sendingInterval === null) {
+        sendingInterval = setInterval(function () {
+            // the only tick that happens whether or not anything is being tracked, which is
+            // exactly the case debug mode has to expire in
+            debug.expireDebugIfIdle();
+            logger.Console.log('scheduleToSendDataToServer: Scheduling to send engagement data to the server after sometime'); // no i18n
+            // one after the other, as flush() does: run together, the second and third find the
+            // first still sending and are deferred, and the third's retry replaces the second's
+            send.sendEngagementData().then(function () {
+                return send$1.sendErrorData();
+            }).then(function () {
+                return hooks.hooks.sendHeatmaps();
+            });
+        }, state.getConfig('batch_flush_interval')); // no i18n
+    }
+    if (getUpdatesInterval === null) {
+        // the interval is the floor, not the schedule: getsdkconfig answers with next_check_after,
+        // and asking again before then is a call the server has already told us it will not answer
+        // differently. The timer still ticks so a server that sends no hint behaves as before.
+        getUpdatesInterval = setInterval(function () {
+            if (state._ZAP._nextConfigCheck > 0 && utils.nowMs() < state._ZAP._nextConfigCheck) {
+                return;
+            }
+            logger.Console.log('scheduleToGetUpdatesFromServer: asking the server for its config'); // no i18n
+            index.getUpdatesFromServer().catch(function (err) {
+                logger.Console.log(err);
+            });
+        }, state.getConfig('getupdates_interval')); // no i18n
+    }
+}
+function stopTimers() {
+    if (sendingInterval !== null)
+        clearInterval(sendingInterval);
+    if (getUpdatesInterval !== null)
+        clearInterval(getUpdatesInterval);
+    sendingInterval = null;
+    getUpdatesInterval = null;
+    batch.clearDefer();
+}
+
+exports.flush = flush;
+exports.startTimers = startTimers;
+exports.stopTimers = stopTimers;