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

package/dist/esm/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/esm/remotelog/index.js

@@ -0,0 +1,51 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import '../core/constants.js';
+import { NO_CALL_SITE } from '../core/callsite.js';
+import { consolelog_transactions } from '../core/storage.js';
+import { hooks } from '../core/hooks.js';
+import { nowMs } from '../core/utils.js';
+import { remoteLogEnabled } from './gate.js';
+import { scheduleSend } from './send.js';
+export { forgetStoredLogs, sendStoredLogs } from './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 (!remoteLogEnabled()) {
+            return;
+        }
+        var where = site || NO_CALL_SITE;
+        consolelog_transactions.add({
+            module: module,
+            happenedat: nowMs(),
+            exceptionlog: String(message),
+            attempt: 1,
+            filename: where.filename,
+            linenumber: where.linenumber,
+        });
+        scheduleSend();
+    }
+    catch (err) {
+        // never let the logger be the thing that fails
+    }
+}
+hooks.remoteLog = remoteLog;
+
+export { remoteLog, remoteLogEnabled };

package/dist/esm/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/esm/remotelog/logger.js

@@ -0,0 +1,136 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { LOG_FUNCTION_MAX } from '../core/constants.js';
+import { callSite } from '../core/callsite.js';
+import { consolelog_transactions } from '../core/storage.js';
+import { guard } from '../core/guard.js';
+import { nowMs } from '../core/utils.js';
+import { getConfig } from '../core/state.js';
+import { appLoggerEnabled, setAppLogger, appLogEnabled } from './gate.js';
+import { scheduleSend } from './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, 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 (!appLogEnabled()) {
+        return;
+    }
+    var text = [message].concat(details).map(describe).join(' '); // no i18n
+    consolelog_transactions.add({
+        module: functionName(site),
+        level: level,
+        happenedat: at,
+        exceptionlog: text,
+        attempt: 1,
+        filename: site.filename,
+        linenumber: site.linenumber,
+    });
+    scheduleSend();
+}
+const recordLine = 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 (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), nowMs(), 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) {
+    setAppLogger(on !== false);
+}
+/** Turns the app logger off, as AppticsLogger.disable() does; the same as enable(false). */
+function disable() {
+    setAppLogger(false);
+}
+/** Android's AppticsLogger: enable, disable, isEnabled and v / d / i / w / e(tag, message). */
+const AppticsLogger = {
+    enable: guard('AppticsLogger.enable', function () { enable(true); }), // no i18n
+    disable: guard('AppticsLogger.disable', disable), // no i18n
+    isEnabled: guard('AppticsLogger.isEnabled', 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),
+};
+
+export { AppticsLogger, LOG_LEVEL };

package/dist/esm/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/esm/remotelog/send.js

@@ -0,0 +1,149 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { LOG_FUNCTION_MAX, CONSOLE_LOG_MAX_BODY, REMOTE_LOG_LEVEL, LOG_FILENAME_MAX } from '../core/constants.js';
+import { _ZAP } from '../core/state.js';
+import { warnAlways, Console } from '../core/logger.js';
+import { nowMs, isEmpty } from '../core/utils.js';
+import { consolelog_transactions } from '../core/storage.js';
+import { postToApptics, apiHeaders, isPermanentRefusal, getMetaObj, postKeepalive } from '../core/transport.js';
+import { remoteLogSendable } from './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: _ZAP._current_session.starttime || item.happenedat || nowMs(),
+        logtime: item.happenedat || nowMs(),
+        // an app's line carries the level it was logged at; the SDK's own failures carry none
+        level: Number(item.level) || REMOTE_LOG_LEVEL,
+        logmessage: String(item.exceptionlog).slice(0, CONSOLE_LOG_MAX_BODY),
+        function: String(item.module || 'SDK').slice(0, 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 (!isEmpty(item.filename)) {
+        entry.filename = String(item.filename).slice(0, 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: 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;
+    }
+    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 || !remoteLogSendable() || navigator.onLine === false) {
+        return Promise.resolve();
+    }
+    sending = true;
+    return consolelog_transactions.all().then(function (stored) {
+        var batch = trim(stored).slice(0, MAX_PER_BATCH);
+        if (batch.length === 0) {
+            return undefined;
+        }
+        return postToApptics('consolelog', bodyFor(batch), apiHeaders(), LABEL).then(function () {
+            return consolelog_transactions.remove(batch);
+        }, function (err) {
+            if (isPermanentRefusal(err)) {
+                warnAlways('apptics: the server refused these log lines, so they were dropped: ' + String(err && err.message)); // no i18n
+                return consolelog_transactions.remove(batch);
+            }
+            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 (!remoteLogSendable()) {
+        return Promise.resolve();
+    }
+    return 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
+        postKeepalive('consolelog', bodyFor(batch), apiHeaders(), LABEL).then(function () {
+            return consolelog_transactions.remove(batch);
+        }, function (err) {
+            if (isPermanentRefusal(err)) {
+                return consolelog_transactions.remove(batch);
+            }
+            Console.log(LABEL + ': ' + String(err)); // no i18n
+            return undefined;
+        });
+        return undefined;
+    });
+}
+
+export { forgetStoredLogs, scheduleSend, sendStoredLogs };

package/dist/esm/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/esm/scheduler.js

@@ -0,0 +1,74 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { _ZAP, getConfig } from './core/state.js';
+import { nowMs } from './core/utils.js';
+import { Console } from './core/logger.js';
+import { canTrack } from './core/consent.js';
+import { clearDefer } from './core/batch.js';
+import { sendEngagementData } from './engagement/send.js';
+import { sendErrorData } from './errors/send.js';
+import { hooks } from './core/hooks.js';
+import { getUpdatesFromServer } from './device/index.js';
+import { expireDebugIfIdle } from './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 (!canTrack('flush')) { // no i18n
+        return Promise.resolve();
+    }
+    _ZAP._sending = false;
+    // one after the other: sending both at once makes the second wait for the 500 ms retry
+    return sendEngagementData(forget).then(function () {
+        return sendErrorData(forget);
+    }).then(function () {
+        // no-op unless the heatmap entry was imported, which is what sets the hook
+        return 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
+            expireDebugIfIdle();
+            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
+            sendEngagementData().then(function () {
+                return sendErrorData();
+            }).then(function () {
+                return hooks.sendHeatmaps();
+            });
+        }, 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 (_ZAP._nextConfigCheck > 0 && nowMs() < _ZAP._nextConfigCheck) {
+                return;
+            }
+            Console.log('scheduleToGetUpdatesFromServer: asking the server for its config'); // no i18n
+            getUpdatesFromServer().catch(function (err) {
+                Console.log(err);
+            });
+        }, getConfig('getupdates_interval')); // no i18n
+    }
+}
+function stopTimers() {
+    if (sendingInterval !== null)
+        clearInterval(sendingInterval);
+    if (getUpdatesInterval !== null)
+        clearInterval(getUpdatesInterval);
+    sendingInterval = null;
+    getUpdatesInterval = null;
+    clearDefer();
+}
+
+export { flush, startTimers, stopTimers };