JavaScript documentation

@fintechiq/logwatcher — dependency-free ESM for evergreen browsers and Node ≥18. localStorage queue in the browser (survives reloads), window.onerror/unhandledrejection crash capture, keepalive flush on page hide. Building a Svelte app? Use the Svelte SDK.

Getting started

You need an application key. Create an account, add an app in the dashboard, and copy the key shown on its card. Every SDK call is tied to that key.

Install the SDK

The package is plain ESM with no build step and no dependencies — install it from the repository (registry publication is planned), or vendor the src/ folder and import it directly:

# from a checkout of the LogWatcher repository
npm install file:path/to/client-sdks/javascript/logwatcher-sdk

<!-- or straight into the browser, no bundler -->
<script type="module">
  import { LogWatcher } from '/vendor/logwatcher/src/index.js';
</script>

Initialize

Initialize once at startup. URL overrides go in the options (or call setApiUrl() before init()).

import { LogWatcher } from '@fintechiq/logwatcher';

LogWatcher.init('YOUR_APP_KEY', {
  apiUrl: 'https://fintechiq-logwatcher-19133922986.europe-west1.run.app',
  enableCrashReporting: true,   // window.onerror / unhandledrejection → crashes
});

In the browser, device identity persists in localStorage. In Node, pass udid in the options for a stable device identity (the default is per-process).

Send logs

One method per level. Logs are queued locally and uploaded in batches; if the network is down they are retried later.

LogWatcher.d('PaymentFlow', 'card inserted · reading chip');
LogWatcher.i('PaymentFlow', 'auth approved · code 00');
LogWatcher.w('Network', 'settle latency 2.1s — retrying');
LogWatcher.e('PaymentFlow', 'auth declined · code 05');
LogWatcher.t('Lifecycle', 'route mounted');   // trace
LogWatcher.f('Watchdog', 'unrecoverable state'); // fatal

Also available: LogWatcher.log(line, method, file, level, tag, text) for explicit source locations, and LogWatcher.transition(name) to record navigations (rendered as TRANSITION rows in the dashboard).

The non-sequential wire values are part of the LogWatcher wire protocol — the SDK handles the mapping.

Crash reporting

With enableCrashReporting: true the SDK listens for window.onerror and unhandledrejection in the browser (uncaughtException/unhandledRejection in Node) and reports them with stack traces. Explicit reporting:

LogWatcher.sendCrash('Checkout crashed', error.stack);

Issues & user feedback

Report a noteworthy condition as an issue, or collect a message from the user. Each call returns a deep-link to the item in your dashboard.

const url = LogWatcher.sendIssue('Sync failed', '3 retries exhausted on /settle');
LogWatcher.sendUserFeedback('From the merchant', 'Receipt printed twice today');

Device key-values

Attach searchable properties to a device — a store number, a merchant id, a build flavour:

LogWatcher.setDeviceString('store', 'ATH-0042');
LogWatcher.setDeviceInteger('lane', 2);
LogWatcher.setDeviceBoolean('pilot', true);
LogWatcher.removeDeviceKey('pilot');

Remote device control

On every launch the SDK registers the device and receives its remote flags. From the dashboard you can enable log collection for a single device while the rest of the fleet stays quiet — no release, no restart loop. To force collection locally regardless of the remote flag:

LogWatcher.setForceEnabled(true);   // override the remote toggle
LogWatcher.forceSendOnce();          // flush the queue right now

Advanced options

The browser queue persists in localStorage and is drained on the next load; the page-hide flush uses fetch(…, { keepalive: true }). TypeScript declarations ship with the package.