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

package/dist/esm/feedback/controls.js

@@ -0,0 +1,309 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { Console } from '../core/logger.js';
+import { hooks } from '../core/hooks.js';
+import { user_defaults } from '../core/storage.js';
+import { isEmpty } from '../core/utils.js';
+import { _ZAP } from '../core/state.js';
+import { hasLogLines, hasDiagnostics, logText, diagnosticsText } from './logs.js';
+
+/**
+ * The three controls at the top and bottom of the feedback form: the user picker, the
+ * log/diagnostics toggles with their data viewer, and dragging the dialog by its header.
+ *
+ * They live here rather than in ui.ts so that init() stays about assembling the modal, and each
+ * control can be wired (and read back) on its own.
+ */
+const ANONYMOUS = 'anonymous'; // no i18n
+const ANONYMOUS_LABEL = 'Anonymous'; // no i18n
+/** Read by core/transport when it builds the feedback request's parameters. */
+const userChoice = { anonymous: true, userid: '', groupid: '' }; // no i18n
+/** Whether the next submission carries the stored logs and diagnostics. Unset means "decide from what is stored". */
+const logChoice = {};
+function resetUserChoice() {
+    userChoice.anonymous = true;
+    userChoice.userid = ''; // no i18n
+    userChoice.groupid = ''; // no i18n
+}
+/**
+ * Who a sendFeedback() report, made without the form, is attributed to: nobody when `anonymous`,
+ * else the user AppticsUser.setUser set (or the active registered one, status 1). Returns a function
+ * that puts back the choice that was there, so a form left open keeps its own.
+ */
+function chooseUserForSend(anonymous) {
+    var before = { anonymous: userChoice.anonymous, userid: userChoice.userid, groupid: userChoice.groupid };
+    resetUserChoice();
+    if (!anonymous) {
+        // the user setUser set on this page, else the active one of those registered before
+        var active = !isEmpty(_ZAP._user_info.userid) ? _ZAP._user_info : null;
+        storedUsers().forEach(function (user) {
+            if (!active && user && user.status == 1 && !isEmpty(user.userid)) {
+                active = user;
+            }
+        });
+        if (active) {
+            userChoice.anonymous = false;
+            userChoice.userid = String(active.userid);
+            userChoice.groupid = String(active.groupid || ''); // no i18n
+        }
+    }
+    return function restore() {
+        userChoice.anonymous = before.anonymous;
+        userChoice.userid = before.userid;
+        userChoice.groupid = before.groupid;
+    };
+}
+/** Every distinct registered user, by the address the picker shows. */
+function storedUsers() {
+    var users = user_defaults.item('users'); // no i18n
+    return Array.isArray(users) ? users : [];
+}
+function pickerItems(users) {
+    var items = [{ value: ANONYMOUS, label: ANONYMOUS_LABEL }];
+    var seen = {};
+    users.forEach(function (user) {
+        var mam = user && user.mam;
+        if (!isEmpty(mam) && !seen[mam]) {
+            seen[mam] = true;
+            items.push({ value: String(mam), label: String(mam) });
+        }
+    });
+    return items;
+}
+const SVG_NS = 'http://www.w3.org/2000/svg'; // no i18n
+/** The tick beside the picked option. */
+function tickIcon() {
+    var svg = document.createElementNS(SVG_NS, 'svg'); // no i18n
+    svg.setAttribute('viewBox', '0 0 14 10'); // no i18n
+    svg.setAttribute('width', '14'); // no i18n
+    svg.setAttribute('height', '10'); // no i18n
+    svg.setAttribute('fill', 'none'); // no i18n
+    var path = document.createElementNS(SVG_NS, 'path'); // no i18n
+    path.setAttribute('d', 'M1 5l4 4 8-8'); // no i18n
+    path.setAttribute('stroke', '#0078d4'); // no i18n
+    path.setAttribute('stroke-width', '2'); // no i18n
+    path.setAttribute('stroke-linecap', 'round'); // no i18n
+    path.setAttribute('stroke-linejoin', 'round'); // no i18n
+    svg.appendChild(path);
+    return svg;
+}
+/**
+ * The "User" dropdown above the description. It lists Anonymous plus every registered user, and
+ * starts on the active one (status 1) unless the caller asked for anonymous.
+ */
+function wireUserPicker(modal, forceAnonymous) {
+    var trigger = modal.querySelector('#zasdkEmailTrigger'); // no i18n
+    var panel = modal.querySelector('#zasdkEmailPanel'); // no i18n
+    var label = modal.querySelector('#zasdkEmailLabel'); // no i18n
+    var list = modal.querySelector('#zasdkEmailList'); // no i18n
+    var dropdown = modal.querySelector('#zasdkEmailDropdown'); // no i18n
+    if (!trigger || !panel || !label || !list || !dropdown) {
+        return;
+    }
+    var users = storedUsers();
+    var items = pickerItems(users);
+    var selected = ANONYMOUS;
+    resetUserChoice();
+    if (!forceAnonymous) {
+        var active = null;
+        users.forEach(function (user) {
+            if (!active && user && user.status == 1 && !isEmpty(user.mam)) {
+                active = user;
+            }
+        });
+        if (active) {
+            select(String(active.mam));
+        }
+    }
+    function select(value) {
+        selected = value;
+        userChoice.anonymous = value === ANONYMOUS;
+        var matched = null;
+        if (!userChoice.anonymous) {
+            users.forEach(function (user) {
+                if (!matched && user && user.mam === value) {
+                    matched = user;
+                }
+            });
+        }
+        userChoice.userid = matched ? String(matched.userid || '') : ''; // no i18n
+        userChoice.groupid = matched ? String(matched.groupid || '') : ''; // no i18n
+        label.textContent = userChoice.anonymous ? ANONYMOUS_LABEL : value;
+        render();
+    }
+    function render() {
+        list.innerHTML = ''; // no i18n
+        if (items.length === 0) {
+            var empty = document.createElement('div'); // no i18n
+            empty.className = 'zasdk-select-empty'; // no i18n
+            empty.textContent = 'No users to choose from'; // no i18n
+            list.appendChild(empty);
+            return;
+        }
+        items.forEach(function (item) {
+            var isSelected = item.value === selected;
+            var option = document.createElement('li'); // no i18n
+            option.className = 'zasdk-select-option' + (isSelected ? ' zasdk-option-selected' : ''); // no i18n
+            option.setAttribute('data-value', item.value); // no i18n
+            var text = document.createElement('span'); // no i18n
+            text.textContent = item.label;
+            option.appendChild(text);
+            if (isSelected) {
+                option.appendChild(tickIcon());
+            }
+            list.appendChild(option);
+        });
+    }
+    trigger.addEventListener('click', function (event) {
+        event.stopPropagation();
+        var open = panel.style.display !== 'none'; // no i18n
+        panel.style.display = open ? 'none' : 'block'; // no i18n
+        if (!open) {
+            render();
+        }
+    });
+    list.addEventListener('click', function (event) {
+        var option = event.target.closest('.zasdk-select-option'); // no i18n
+        if (!option) {
+            return;
+        }
+        select(String(option.getAttribute('data-value'))); // no i18n
+        panel.style.display = 'none'; // no i18n
+    });
+    // closing on focusout rather than a document click keeps it working inside a shadow root
+    dropdown.setAttribute('tabindex', '0'); // no i18n
+    dropdown.addEventListener('focusout', function (event) {
+        if (!dropdown.contains(event.relatedTarget)) {
+            panel.style.display = 'none'; // no i18n
+        }
+    });
+    render();
+}
+/** Shows `content` in the viewer panel over the form. */
+function openViewer(modal, title, content) {
+    var viewer = modal.querySelector('#zasdkDataViewer'); // no i18n
+    var viewerTitle = modal.querySelector('#zasdkViewerTitle'); // no i18n
+    var viewerContent = modal.querySelector('#zasdkViewerContent'); // no i18n
+    if (!viewer || !viewerTitle || !viewerContent) {
+        return;
+    }
+    viewerTitle.textContent = title;
+    viewerContent.textContent = content || '(No data available)'; // no i18n
+    viewer.style.display = 'flex'; // no i18n
+}
+/**
+ * The two "Include …" switches and the viewer behind their View links. A row is shown only when
+ * there is something to include, and is then on by default, so a submission carries what the app
+ * recorded unless the user turns it off.
+ */
+function wireLogControls(modal, opts) {
+    var logToggle = modal.querySelector('#zasdkIncludeLogToggle'); // no i18n
+    var diagToggle = modal.querySelector('#zasdkIncludeDiagToggle'); // no i18n
+    var section = modal.querySelector('.zasdk-toggles-section'); // no i18n
+    var separator = modal.querySelector('.zasdk-toggle-separator'); // no i18n
+    var viewLogs = modal.querySelector('#zasdkViewLogsBtn'); // no i18n
+    var viewDiag = modal.querySelector('#zasdkViewDiagBtn'); // no i18n
+    var viewerClose = modal.querySelector('#zasdkViewerClose'); // no i18n
+    var viewer = modal.querySelector('#zasdkDataViewer'); // no i18n
+    if (!logToggle || !diagToggle || !section) {
+        return;
+    }
+    var logRow = logToggle.closest('.zasdk-toggle-row'); // no i18n
+    var diagRow = diagToggle.closest('.zasdk-toggle-row'); // no i18n
+    logChoice.includeLog = opts.includeLog === true ? true : undefined;
+    logChoice.includeDyninfo = opts.includeDyninfo === true ? true : undefined;
+    // hidden until the reads come back, so an empty section never flashes into view
+    section.style.display = 'none'; // no i18n
+    Promise.all([hasLogLines(), hasDiagnostics()]).then(function ([anyLogs, anyDiagnostics]) {
+        if (logRow)
+            logRow.style.display = anyLogs ? '' : 'none'; // no i18n
+        if (diagRow)
+            diagRow.style.display = anyDiagnostics ? '' : 'none'; // no i18n
+        if (separator)
+            separator.style.display = anyLogs && anyDiagnostics ? '' : 'none'; // no i18n
+        section.style.display = anyLogs || anyDiagnostics ? '' : 'none'; // no i18n
+        // on when there is data, unless the caller already decided
+        logToggle.checked = opts.includeLog === true || anyLogs;
+        diagToggle.checked = opts.includeDyninfo === true || anyDiagnostics;
+        logChoice.includeLog = logToggle.checked;
+        logChoice.includeDyninfo = diagToggle.checked;
+    }).catch(function (err) {
+        Console.warn('apptics: could not read the stored logs: ' + String(err)); // no i18n
+    });
+    logToggle.addEventListener('change', function () {
+        logChoice.includeLog = logToggle.checked;
+    });
+    diagToggle.addEventListener('change', function () {
+        logChoice.includeDyninfo = diagToggle.checked;
+    });
+    if (viewLogs) {
+        viewLogs.addEventListener('click', function () {
+            logText().then(function (text) {
+                openViewer(modal, 'System Logs', text); // no i18n
+            });
+        });
+    }
+    if (viewDiag) {
+        viewDiag.addEventListener('click', function () {
+            diagnosticsText().then(function (text) {
+                openViewer(modal, 'Diagnostic Information', text); // no i18n
+            });
+        });
+    }
+    if (viewerClose && viewer) {
+        viewerClose.addEventListener('click', function () {
+            viewer.style.display = 'none'; // no i18n
+        });
+    }
+}
+/**
+ * Drags the dialog by its header. The right/bottom placement from the stylesheet is converted to
+ * an explicit left/top on the first drag, so the offsets have something to add to, and the box is
+ * kept inside the viewport.
+ */
+function wireDrag(box) {
+    var header = box.querySelector('.zasdk-header'); // no i18n
+    if (!header) {
+        return;
+    }
+    var startX = 0, startY = 0, boxLeft = 0, boxTop = 0, dragging = false;
+    header.addEventListener('mousedown', function (event) {
+        if (event.target.closest('.zasdk-close')) { // no i18n
+            return; // the close button is not a drag handle
+        }
+        if (!box.style.left || box.style.left === 'auto') { // no i18n
+            var rect = box.getBoundingClientRect();
+            box.style.right = 'auto'; // no i18n
+            box.style.bottom = 'auto'; // no i18n
+            box.style.left = rect.left + 'px'; // no i18n
+            box.style.top = rect.top + 'px'; // no i18n
+        }
+        dragging = true;
+        startX = event.clientX;
+        startY = event.clientY;
+        boxLeft = parseInt(box.style.left, 10);
+        boxTop = parseInt(box.style.top, 10);
+        header.style.cursor = 'grabbing'; // no i18n
+        event.preventDefault();
+    });
+    document.addEventListener('mousemove', function (event) {
+        if (!dragging) {
+            return;
+        }
+        var left = boxLeft + (event.clientX - startX);
+        var top = boxTop + (event.clientY - startY);
+        box.style.left = Math.max(0, Math.min(left, window.innerWidth - box.offsetWidth)) + 'px'; // no i18n
+        box.style.top = Math.max(0, Math.min(top, window.innerHeight - box.offsetHeight)) + 'px'; // no i18n
+    });
+    document.addEventListener('mouseup', function () {
+        if (dragging) {
+            dragging = false;
+            header.style.cursor = 'grab'; // no i18n
+        }
+    });
+}
+// core/transport asks for the picked user when it builds the feedback request's parameters
+hooks.feedbackUser = function () {
+    return userChoice.anonymous || isEmpty(userChoice.userid) ? null : userChoice;
+};
+
+export { chooseUserForSend, logChoice, userChoice, wireDrag, wireLogControls, wireUserPicker };

package/dist/esm/feedback/index.d.ts

@@ -0,0 +1,9 @@
+import type { AppticsFeedbackApi } from '../types.js';
+export type { FeedbackOpenOptions, SendFeedbackOptions } from '../types.js';
+/**
+ * Android's AppticsFeedback: the form, sending feedback without it, and the context recorded for
+ * the next one. Every feedback call, addFeedbackLog and addDiagnosticsInfo included, is here and
+ * only here: the main entry has no AppticsFeedback.
+ */
+export declare const AppticsFeedback: AppticsFeedbackApi;
+export default AppticsFeedback;

package/dist/esm/feedback/index.js

@@ -0,0 +1,51 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { forward, guard } from '../core/guard.js';
+import { AP_FEEDBACK_TYPE } from '../core/constants.js';
+import { Console } from '../core/logger.js';
+import { ready } from '../lifecycle.js';
+import { setFeedbackTheme, sendFeedback, feedbackFormClose, feedbackFormOpen } from './ui.js';
+import { addDiagnosticsInfo, addFeedbackLog } from './logs.js';
+
+/**
+ * Optional feedback modal, shipped as its own entry point:
+ *   import { AppticsFeedback } from '@zoho_apptics/apptics-js-sdk/feedback';
+ *   AppticsFeedback.feedbackFormOpen();
+ * Apps that never import it don't pay for the modal or its markup.
+ * The <script> build includes it, so snippet users are unaffected.
+ */
+const feedbackFormOpenGuarded = guard('AppticsFeedback.feedbackFormOpen', feedbackFormOpen); // no i18n
+const feedbackFormCloseGuarded = guard('AppticsFeedback.feedbackFormClose', feedbackFormClose); // no i18n
+const addFeedbackLogGuarded = guard('AppticsFeedback.addFeedbackLog', addFeedbackLog); // no i18n
+const addDiagnosticsInfoGuarded = guard('AppticsFeedback.addDiagnosticsInfo', addDiagnosticsInfo); // no i18n
+const setFeedbackThemeGuarded = guard('AppticsFeedback.setFeedbackTheme', setFeedbackTheme); // no i18n
+/** Resolves once the feedback is sent; rejects when it wasn't (SDK not started, offline, refused). */
+const sendFeedbackGuarded = guard('AppticsFeedback.sendFeedback', function (...args) {
+    return ready().then(function (started) {
+        if (!started) {
+            throw new Error('AppticsFeedback.sendFeedback: not sent, the SDK has not started; call Apptics.init() first'); // no i18n
+        }
+        return sendFeedback(...args);
+    }).catch(function (err) {
+        Console.error('AppticsFeedback.sendFeedback failed:', err); // no i18n
+        throw err;
+    });
+});
+/* each call a function of its own, with the parameter names the console shows (see forward) */
+/**
+ * Android's AppticsFeedback: the form, sending feedback without it, and the context recorded for
+ * the next one. Every feedback call, addFeedbackLog and addDiagnosticsInfo included, is here and
+ * only here: the main entry has no AppticsFeedback.
+ */
+const AppticsFeedback = {
+    /** The feedback types: BUG, FEEDBACK, HELP, REPORT. */
+    AP_FEEDBACK_TYPE: AP_FEEDBACK_TYPE,
+    feedbackFormOpen: function feedbackFormOpen(options) { return forward(feedbackFormOpenGuarded, arguments); },
+    feedbackFormClose: function feedbackFormClose() { return forward(feedbackFormCloseGuarded, arguments); },
+    sendFeedback: function sendFeedback(options) { return forward(sendFeedbackGuarded, arguments); },
+    addFeedbackLog: function addFeedbackLog(message) { return forward(addFeedbackLogGuarded, arguments); },
+    addDiagnosticsInfo: function addDiagnosticsInfo(heading, key, value) { return forward(addDiagnosticsInfoGuarded, arguments); },
+    /** The form's theme from now on, and of a form open now: 'light', 'dark' or 'auto'. */
+    setFeedbackTheme: function setFeedbackTheme(theme) { return forward(setFeedbackThemeGuarded, arguments); },
+};
+
+export { AppticsFeedback, AppticsFeedback as default };

package/dist/esm/feedback/logs.d.ts

@@ -0,0 +1,45 @@
+/** Neither rendered file is sent above this size (the 1.x limit). */
+export declare const MAX_LOG_FILE_SIZE: number;
+export declare const LOG_FILE_NAME = "feedbacklog.txt";
+export declare const DYNINFO_FILE_NAME = "dyninfo.txt";
+/** One rendered file, with the ids to remove once the server has it. */
+export interface RenderedFile {
+    file: File;
+    ids: string[];
+}
+/** Drops the oldest entries once the store is over MAX_ENTRIES. */
+export declare function trimStoredLogs(): Promise<void>;
+/**
+ * Records a timestamped line for the next feedback submission, sent as feedbacklog.txt.
+ * Ignores anything that isn't a non-empty string, as 1.x did.
+ */
+export declare function addFeedbackLog(message: string): void;
+/**
+ * Records a diagnostics entry, `value` under `key` in the `heading` block of dyninfo.txt. All three
+ * are required: an entry without a value says nothing, so it is refused and the console says why.
+ * A value of 0 or false is a value.
+ */
+export declare function addDiagnosticsInfo(heading: string, key: string, value: unknown): void;
+/** Removes every stored entry. */
+export declare function clearFeedbackLogs(): Promise<void>;
+/** Removes the entries a submission carried, by the ids the rendered files reported. */
+export declare function feedbacklog_transactions_remove(sentIds: string[]): Promise<void>;
+/** feedbacklog.txt from the stored log lines, or null when there are none. */
+export declare function toLogFile(): Promise<RenderedFile | null>;
+/**
+ * The log lines for showing in the modal before sending, each time in the visitor's local zone.
+ * The file that is sent (toLogFile) keeps the ISO 8601 UTC stamps, so the server and anything
+ * that parses it are unaffected.
+ */
+export declare function logText(): Promise<string>;
+/** The diagnostics entries as dyninfo.txt would carry them, without the device info block. */
+export declare function diagnosticsText(): Promise<string>;
+/** True when any log line is waiting, so the modal knows whether to offer the toggle. */
+export declare function hasLogLines(): Promise<boolean>;
+/**
+ * dyninfo.txt: the stored diagnostics entries followed by a [Device Info] block holding
+ * `deviceInfo`. Returns null only when there is nothing at all to put in it.
+ */
+export declare function toDyninfoFile(deviceInfo: string | null): Promise<RenderedFile | null>;
+/** True when any diagnostics entry is waiting, so a submission knows to send dyninfo unasked. */
+export declare function hasDiagnostics(): Promise<boolean>;

package/dist/esm/feedback/logs.js

@@ -0,0 +1,227 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { warnAlways, Console } from '../core/logger.js';
+import { FEEDBACK_LOG, FEEDBACK_DIAGNOSTICS } from '../core/db.js';
+import { feedbacklog_transactions } from '../core/storage.js';
+import { isExpired } from '../core/state.js';
+import { nowMs } from '../core/utils.js';
+
+/**
+ * Log lines and diagnostics entries an app records for its next feedback submission.
+ *
+ * addFeedbackLog() and addDiagnosticsInfo() accumulate entries in the `logs` store; a feedback
+ * submission renders them into the files feedback/add carries (feedbacklog.txt and dyninfo.txt)
+ * and removes the ones it took with it, so entries added while a submission is in flight survive.
+ *
+ * This module deliberately depends on core only, never on the modal, so the main entry point can
+ * expose the two collection functions without pulling the feedback UI into an app's bundle.
+ */
+/** Entries beyond this are dropped oldest-first, so an app that never submits can't grow forever. */
+const MAX_ENTRIES = 1000;
+/** A single message longer than this is truncated rather than stored whole. */
+const MAX_MESSAGE_LENGTH = 10000;
+/** Neither rendered file is sent above this size (the 1.x limit). */
+const MAX_LOG_FILE_SIZE = 2 * 1024 * 1024;
+/** Bursts of addFeedbackLog() calls coalesce into one trim. */
+const TRIM_DELAY_MS = 2000;
+const LOG_FILE_NAME = 'feedbacklog.txt'; // no i18n
+const DYNINFO_FILE_NAME = 'dyninfo.txt'; // no i18n
+// the types the entries are stored under (2.0.0-beta and 1.x said log and diagnostics)
+const LOG = FEEDBACK_LOG;
+const DIAGNOSTICS = FEEDBACK_DIAGNOSTICS;
+let trimScheduled = false;
+/** Drops the oldest entries once the store is over MAX_ENTRIES. */
+function trimStoredLogs() {
+    return feedbacklog_transactions.all().then(function (items) {
+        const excess = items.length - MAX_ENTRIES;
+        if (excess <= 0) {
+            return undefined;
+        }
+        Console.warn('apptics: dropping ' + excess + ' oldest feedback log entries (cap is ' + MAX_ENTRIES + ')'); // no i18n
+        return feedbacklog_transactions.remove(items.slice(0, excess));
+    });
+}
+/** One trim per burst of adds, so a chatty app pays for one pass over the store, not one per line. */
+function scheduleTrim() {
+    if (trimScheduled) {
+        return;
+    }
+    trimScheduled = true;
+    setTimeout(function () {
+        trimScheduled = false;
+        trimStoredLogs();
+    }, TRIM_DELAY_MS);
+}
+function store(item) {
+    feedbacklog_transactions.add(item);
+    scheduleTrim();
+}
+function truncate(text) {
+    return text.length > MAX_MESSAGE_LENGTH ? text.slice(0, MAX_MESSAGE_LENGTH) + '…' : text;
+}
+/**
+ * Records a timestamped line for the next feedback submission, sent as feedbacklog.txt.
+ * Ignores anything that isn't a non-empty string, as 1.x did.
+ */
+function addFeedbackLog(message) {
+    if (typeof message !== 'string' || message.length === 0) { // no i18n
+        return;
+    }
+    store({ type: LOG, happenedat: nowMs(), message: truncate(message) });
+}
+/**
+ * Records a diagnostics key/value under a heading, sent inside dyninfo.txt.
+ * Entries sharing a heading are grouped together in the file.
+ */
+/** Messages already printed, so a call repeated in a loop says so once. */
+const refusedSaid = {};
+function refuse(message) {
+    if (!refusedSaid[message]) {
+        refusedSaid[message] = true;
+        warnAlways('AppticsFeedback.addDiagnosticsInfo: ' + message + ', so the entry is not recorded'); // no i18n
+    }
+}
+/**
+ * Records a diagnostics entry, `value` under `key` in the `heading` block of dyninfo.txt. All three
+ * are required: an entry without a value says nothing, so it is refused and the console says why.
+ * A value of 0 or false is a value.
+ */
+function addDiagnosticsInfo(heading, key, value) {
+    if (typeof heading !== 'string' || heading.length === 0) { // no i18n
+        refuse('a heading is required');
+        return;
+    }
+    if (typeof key !== 'string' || key.length === 0) { // no i18n
+        refuse('a key is required');
+        return;
+    }
+    if (value === undefined || value === null || value === '') { // no i18n
+        refuse('a value is required for "' + heading + '" / "' + key + '"');
+        return;
+    }
+    store({
+        type: DIAGNOSTICS,
+        happenedat: nowMs(),
+        heading: heading,
+        key: key,
+        value: truncate(String(value)),
+    });
+}
+/** Removes the entries a submission carried, by the ids the rendered files reported. */
+function feedbacklog_transactions_remove(sentIds) {
+    return feedbacklog_transactions.remove(sentIds.map(function (id) { return { id: id }; }));
+}
+/** Entries of one type, oldest first, skipping any that have passed batch_request_timeout. */
+function entriesOfType(type) {
+    return feedbacklog_transactions.all().then(function (items) {
+        return items.filter(function (item) {
+            return item.type === type && !isExpired(item.happenedat);
+        });
+    });
+}
+/** ISO 8601, from the stored time or a 1.x entry's own timestamp string. */
+function stamp(item) {
+    if (typeof item.timestamp === 'string' && item.timestamp.length > 0) {
+        return item.timestamp; // migrated from 1.x, which stored the ISO string
+    }
+    return new Date(typeof item.happenedat === 'number' ? item.happenedat : nowMs()).toISOString();
+}
+function ids(items) {
+    return items.map(function (item) { return String(item.id); });
+}
+/** `[heading]` blocks of `key: value` lines, in the order the headings first appeared. */
+function groupDiagnostics(items) {
+    const order = [];
+    const grouped = {};
+    items.forEach(function (item) {
+        const heading = String(item.heading);
+        if (!grouped[heading]) {
+            grouped[heading] = [];
+            order.push(heading);
+        }
+        grouped[heading].push(item.key + ': ' + item.value); // no i18n
+    });
+    return order.map(function (heading) {
+        return '[' + heading + ']\n' + grouped[heading].join('\n'); // no i18n
+    }).join('\n\n'); // no i18n
+}
+function asFile(name, content, items) {
+    const file = new File([content], name, { type: 'text/plain' }); // no i18n
+    if (file.size > MAX_LOG_FILE_SIZE) {
+        Console.warn('apptics: ' + name + ' is over ' + (MAX_LOG_FILE_SIZE / (1024 * 1024)) + ' MB, not sending it'); // no i18n
+        return null;
+    }
+    return { file: file, ids: ids(items) };
+}
+function renderLogLines(items) {
+    return items.map(function (item) {
+        return '[' + stamp(item) + '] ' + item.message; // no i18n
+    }).join('\n'); // no i18n
+}
+/** feedbacklog.txt from the stored log lines, or null when there are none. */
+function toLogFile() {
+    return entriesOfType(LOG).then(function (items) {
+        if (items.length === 0) {
+            return null;
+        }
+        return asFile(LOG_FILE_NAME, renderLogLines(items), items);
+    });
+}
+/** `16 Oct 2026, 11:53:48 PM IST`: a log line's time in the visitor's own zone, for the viewer. */
+function readableStamp(item) {
+    var iso = stamp(item);
+    var d = new Date(iso);
+    if (isNaN(d.getTime())) {
+        return iso;
+    }
+    return d.toLocaleDateString(undefined, { day: '2-digit', month: 'short', year: 'numeric' }) + ', ' + // no i18n
+        d.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit', second: '2-digit', timeZoneName: 'short' }); // no i18n
+}
+/**
+ * The log lines for showing in the modal before sending, each time in the visitor's local zone.
+ * The file that is sent (toLogFile) keeps the ISO 8601 UTC stamps, so the server and anything
+ * that parses it are unaffected.
+ */
+function logText() {
+    return entriesOfType(LOG).then(function (items) {
+        return items.map(function (item) {
+            return '[' + readableStamp(item) + '] ' + item.message; // no i18n
+        }).join('\n'); // no i18n
+    });
+}
+/** The diagnostics entries as dyninfo.txt would carry them, without the device info block. */
+function diagnosticsText() {
+    return entriesOfType(DIAGNOSTICS).then(groupDiagnostics);
+}
+/** True when any log line is waiting, so the modal knows whether to offer the toggle. */
+function hasLogLines() {
+    return entriesOfType(LOG).then(function (items) {
+        return items.length > 0;
+    });
+}
+/**
+ * dyninfo.txt: the stored diagnostics entries followed by a [Device Info] block holding
+ * `deviceInfo`. Returns null only when there is nothing at all to put in it.
+ */
+function toDyninfoFile(deviceInfo) {
+    return entriesOfType(DIAGNOSTICS).then(function (items) {
+        const blocks = [];
+        if (items.length > 0) {
+            blocks.push(groupDiagnostics(items));
+        }
+        if (deviceInfo) {
+            blocks.push('[Device Info]\n' + deviceInfo); // no i18n
+        }
+        if (blocks.length === 0) {
+            return null;
+        }
+        return asFile(DYNINFO_FILE_NAME, blocks.join('\n\n'), items); // no i18n
+    });
+}
+/** True when any diagnostics entry is waiting, so a submission knows to send dyninfo unasked. */
+function hasDiagnostics() {
+    return entriesOfType(DIAGNOSTICS).then(function (items) {
+        return items.length > 0;
+    });
+}
+
+export { DYNINFO_FILE_NAME, LOG_FILE_NAME, MAX_LOG_FILE_SIZE, addDiagnosticsInfo, addFeedbackLog, diagnosticsText, feedbacklog_transactions_remove, hasDiagnostics, hasLogLines, logText, toDyninfoFile, toLogFile, trimStoredLogs };

package/dist/esm/feedback/quartz.d.ts

@@ -0,0 +1,18 @@
+/** quartz_domain as a recording host: zoho.com → https://quartz.zoho.com. '' when it isn't a domain. */
+export declare function recordingDomain(domain: string): string;
+/**
+ * The Quartz script for an app whose getsdkconfig answer carries no quartz_cdn_url, chosen by
+ * the serviceUrl: a localzoho server's apps load it from Zoho's local CDN, every other app from
+ * the public one.
+ */
+export declare function defaultQuartzScriptUrl(serviceUrl: string): string;
+/** The script to load: quartz_cdn_url when getsdkconfig gave one, else the CDN the serviceUrl points to. */
+export declare function quartzScriptSource(cdnUrl: string, serviceUrl: string): string;
+/** The url to load, or '' when it isn't an https url on a Zoho host. */
+export declare function quartzScriptUrl(url: string): string;
+/**
+ * Makes Quartz available: resolves true once it is on the page, false when it can't be (no url,
+ * a url that isn't allowed, or a script that failed to load). Adds the script once; every caller
+ * waits on the same load, and a failed one may be tried again on the next open.
+ */
+export declare function loadQuartz(url: string): Promise<boolean>;