@tellann/frontend-sdk 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# @tellann/frontend-sdk
+
+Browser telemetry and QA-run correlation SDK for Tellann. Captures page views, clicks,
+form submissions, route changes, errors, workflow lifecycle events, and custom business
+events, then batches them to a Tellann collector endpoint.
+
+## Install
+
+```bash
+npm install @tellann/frontend-sdk
+# or
+pnpm add @tellann/frontend-sdk
+```
+
+This is an ES module and targets modern browsers (`fetch`, `navigator.sendBeacon`, `Blob`).
+
+## Quick start
+
+```ts
+import { TELLANN } from '@tellann/frontend-sdk';
+
+TELLANN.initialize({
+  endpoint: 'https://collector.example.com',
+  applicationId: 'my-web-app',
+  environmentId: 'production',
+  apiKey: '<publishable-key>', // optional
+  autoTrackClicks: true,   // default true
+  autoTrackForms: true,    // default true
+  autoTrackRoutes: true,   // default true
+  errorTracking: true,     // default true
+  debug: false,
+});
+```
+
+`initialize` starts a session (emitting a `PAGE_VIEW`), wires up auto-tracking, and
+begins a flush interval (`flushIntervalMs`, default 5000). Events are also flushed
+immediately when the buffer reaches `maxBufferSize` (default 200).
+
+## Configuration
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `endpoint` | `string` | – | Collector base URL. Events POST to `${endpoint}/v1/events/batch`. |
+| `applicationId` | `string` | – | Identifies the app sending events. |
+| `tenantId` | `string` | `'unknown'` | Optional tenant identifier. |
+| `environmentId` | `string` | `null` | Sent as `x-tellann-environment-id`. |
+| `apiKey` | `string` | – | Sent as `Authorization: Bearer`. Disables `sendBeacon` fallback. |
+| `runId` / `sessionId` / `traceId` | `string` | generated | QA-run / trace correlation IDs. |
+| `agentVersion` / `instrumentationManifestVersion` | `string` | `null` | Correlation metadata. |
+| `autoTrackClicks` / `autoTrackForms` / `autoTrackRoutes` | `boolean` | `true` | DOM auto-instrumentation. |
+| `errorTracking` | `boolean` | `true` | Capture uncaught errors and rejections. |
+| `flushIntervalMs` | `number` | `5000` | Batch flush cadence. |
+| `maxBufferSize` | `number` | `200` | Force a flush at this many buffered events. |
+| `debug` | `boolean` | `false` | Verbose console logging. |
+
+## Manual tracking API
+
+```ts
+TELLANN.trackEvent('PAGE_VIEW', { url: location.href });
+TELLANN.trackBusinessEvent({ type: 'checkout_completed', payload: { total: 42 } });
+
+TELLANN.trackState('cart_open', 'BUSINESS');
+TELLANN.trackTransition('cart_open', 'checkout', 'NAVIGATE');
+
+const wf = TELLANN.startWorkflow('signup');
+TELLANN.completeWorkflow(wf);           // or failWorkflow(wf, reason) / cancelWorkflow(wf)
+
+TELLANN.captureException(err, { route: '/checkout' });
+TELLANN.captureMessage('payment provider slow', 'warning');
+TELLANN.identifyUser('user_123', { plan: 'pro' });
+
+await TELLANN.verifyInstallation();     // emits TELLANN_INITIALIZED and flushes
+```
+
+Call `TELLANN.teardown()` on unmount / page teardown to clear the flush interval,
+detach auto-tracking listeners, and flush remaining events.
+
+### Payload limits
+
+- Standard event: 32 KB (oversized events are dropped with a console error).
+- Replay events (`eventType` containing `REPLAY`): 128 KB.
+- Batch payload: 5 MB (oversized batches are dropped).
+
+Metadata is sanitized before send (privacy-by-default).
+
+## TypeScript
+
+Types ship with the package. `TellannConfig`, `EventType`, and `TellannEvent` are exported.
+
+## License
+
+`UNLICENSED` — see the repository for terms.

package/dist/auto-track.d.ts

@@ -0,0 +1,12 @@
+import type { EventType } from './event-types.js';
+interface AutoTrackConfig {
+    autoTrackClicks?: boolean;
+    autoTrackForms?: boolean;
+    autoTrackRoutes?: boolean;
+    errorTracking?: boolean;
+}
+export declare function sanitizeMetadata(metadata: Record<string, any>): Record<string, any>;
+export declare function setupAutoTrack(sdk: {
+    trackEvent: (type: EventType, metadata?: Record<string, any>) => void;
+}, config: AutoTrackConfig): () => void;
+export {};

package/dist/auto-track.js

@@ -0,0 +1,200 @@
+// Utility to check if element or its parents should be ignored
+function shouldIgnore(element) {
+    let curr = element;
+    while (curr) {
+        if (curr.hasAttribute && curr.hasAttribute('data-tellann-ignore')) {
+            return true;
+        }
+        // Ignore password inputs completely
+        if (curr.tagName === 'INPUT' && curr.type === 'password') {
+            return true;
+        }
+        curr = curr.parentElement;
+    }
+    return false;
+}
+// CSS Selector generator
+function getCssSelector(el) {
+    if (el.id)
+        return `#${el.id}`;
+    let path = [];
+    let curr = el;
+    while (curr && curr.nodeType === Node.ELEMENT_NODE) {
+        let selector = curr.nodeName.toLowerCase();
+        if (curr.className) {
+            selector += `.${curr.className.trim().split(/\s+/).join('.')}`;
+        }
+        path.unshift(selector);
+        curr = curr.parentElement;
+    }
+    return path.join(' > ');
+}
+// Utility to recursively sanitize sensitive keys in metadata
+export function sanitizeMetadata(metadata) {
+    const sensitiveKeys = [
+        'password',
+        'credit_card',
+        'cvv',
+        'token',
+        'secret',
+        'private_key',
+        'access_token',
+        'authorization'
+    ];
+    const sanitize = (val) => {
+        if (val === null || val === undefined)
+            return val;
+        if (Array.isArray(val)) {
+            return val.map(sanitize);
+        }
+        if (typeof val === 'object') {
+            const result = {};
+            for (const key of Object.keys(val)) {
+                const lowerKey = key.toLowerCase();
+                if (sensitiveKeys.some(sk => lowerKey.includes(sk))) {
+                    result[key] = '[REDACTED]';
+                }
+                else {
+                    result[key] = sanitize(val[key]);
+                }
+            }
+            return result;
+        }
+        return val;
+    };
+    return sanitize(metadata);
+}
+export function setupAutoTrack(sdk, config) {
+    const cleanups = [];
+    // 1. Clicks (Buttons & Links)
+    if (config.autoTrackClicks !== false) {
+        const clickHandler = (e) => {
+            const target = e.target;
+            if (!target)
+                return;
+            // Find closest button or link
+            const interactiveEl = target.closest('a, button, [role="button"]');
+            if (!interactiveEl || shouldIgnore(interactiveEl))
+                return;
+            const isLink = interactiveEl.tagName === 'A';
+            const eventType = isLink ? 'LINK_CLICK' : 'BUTTON_CLICK';
+            const text = interactiveEl.innerText?.trim().slice(0, 100) || '';
+            const elementId = interactiveEl.id || '';
+            const selector = getCssSelector(interactiveEl);
+            const metadata = {
+                elementId,
+                text,
+                selector,
+            };
+            if (isLink) {
+                metadata.href = interactiveEl.getAttribute('href') || '';
+            }
+            sdk.trackEvent(eventType, metadata);
+        };
+        document.addEventListener('click', clickHandler, true);
+        cleanups.push(() => document.removeEventListener('click', clickHandler, true));
+    }
+    // 2. Form Submissions
+    if (config.autoTrackForms !== false) {
+        const submitHandler = (e) => {
+            const form = e.target;
+            if (!form || shouldIgnore(form))
+                return;
+            const formId = form.id || '';
+            const formAction = form.getAttribute('action') || '';
+            // Capture only names of fields, never values
+            const fields = [];
+            const elements = form.elements;
+            for (let i = 0; i < elements.length; i++) {
+                const item = elements[i];
+                if (item.name) {
+                    fields.push(item.name);
+                }
+                else if (item.id) {
+                    fields.push(item.id);
+                }
+            }
+            sdk.trackEvent('FORM_SUBMITTED', {
+                formId,
+                formAction,
+                fields,
+            });
+        };
+        document.addEventListener('submit', submitHandler, true);
+        cleanups.push(() => document.removeEventListener('submit', submitHandler, true));
+    }
+    // 3. SPA Route Changes
+    if (config.autoTrackRoutes !== false) {
+        let lastUrl = window.location.href;
+        const handleRouteChange = () => {
+            const currentUrl = window.location.href;
+            if (currentUrl === lastUrl)
+                return;
+            const from = lastUrl;
+            const to = currentUrl;
+            lastUrl = currentUrl;
+            sdk.trackEvent('ROUTE_CHANGE', { from, to });
+            // Emit settled PAGE_VIEW
+            setTimeout(() => {
+                sdk.trackEvent('PAGE_VIEW', {
+                    url: window.location.href,
+                    title: document.title,
+                    referrer: document.referrer,
+                });
+            }, 50);
+        };
+        // Patch history pushState and replaceState
+        const origPushState = history.pushState;
+        const origReplaceState = history.replaceState;
+        history.pushState = function (...args) {
+            origPushState.apply(this, args);
+            handleRouteChange();
+        };
+        history.replaceState = function (...args) {
+            origReplaceState.apply(this, args);
+            handleRouteChange();
+        };
+        window.addEventListener('popstate', handleRouteChange);
+        window.addEventListener('hashchange', handleRouteChange);
+        cleanups.push(() => {
+            history.pushState = origPushState;
+            history.replaceState = origReplaceState;
+            window.removeEventListener('popstate', handleRouteChange);
+            window.removeEventListener('hashchange', handleRouteChange);
+        });
+    }
+    // 4. Unhandled Errors and Promise Rejections
+    if (config.errorTracking !== false) {
+        const errorHandler = (e) => {
+            // Ignore errors that don't look like actual exceptions or are cross-origin script issues
+            const message = e.message || 'Unknown window error';
+            const stack = e.error instanceof Error ? e.error.stack : null;
+            const name = e.error instanceof Error ? e.error.name : 'Error';
+            sdk.trackEvent('UNHANDLED_EXCEPTION', {
+                message,
+                stack,
+                name,
+            });
+        };
+        const rejectionHandler = (e) => {
+            const reason = e.reason;
+            const message = reason instanceof Error ? reason.message : String(reason);
+            const stack = reason instanceof Error ? reason.stack : null;
+            const name = reason instanceof Error ? reason.name : 'UnhandledRejection';
+            sdk.trackEvent('UNHANDLED_EXCEPTION', {
+                message,
+                stack,
+                name,
+            });
+        };
+        window.addEventListener('error', errorHandler);
+        window.addEventListener('unhandledrejection', rejectionHandler);
+        cleanups.push(() => {
+            window.removeEventListener('error', errorHandler);
+            window.removeEventListener('unhandledrejection', rejectionHandler);
+        });
+    }
+    return () => {
+        cleanups.forEach(cleanup => cleanup());
+    };
+}

package/dist/event-types.d.ts

@@ -0,0 +1,17 @@
+export type EventType = 'PAGE_VIEW' | 'ROUTE_CHANGE' | 'BUTTON_CLICK' | 'LINK_CLICK' | 'FORM_SUBMIT' | 'FORM_SUBMITTED' | 'API_REQUEST' | 'ERROR_EVENT' | 'ERROR_OCCURRED' | 'UNHANDLED_EXCEPTION' | 'SERVER_ERROR' | 'CLIENT_ERROR' | 'BUSINESS_EVENT' | 'STATE_ENTERED' | 'STATE_TRANSITION' | 'FLOW_INITIAL_STATE' | 'FLOW_STATE_REACHED' | 'FLOW_TRANSITION' | 'FLOW_TERMINAL_STATE' | 'WORKFLOW_STARTED' | 'WORKFLOW_COMPLETED' | 'WORKFLOW_FAILED' | 'WORKFLOW_CANCELLED' | 'TELLANN_ONBOARDING_TEST' | 'TELLANN_INITIALIZED' | 'QA_RUN_STARTED' | 'QA_RUN_COMPLETED' | 'QA_RUN_FAILED' | 'BROWSER_PAGE_LOADED' | 'BROWSER_CONSOLE_ERROR' | 'BROWSER_NETWORK_FAILED' | 'VISUAL_ASSERTION_FAILED' | 'ACCESSIBILITY_FINDING' | 'INSTRUMENTATION_VERIFIED' | 'REPOSITORY_SNAPSHOT_CREATED' | 'EXPECTED_FLOW_VERSION_SELECTED';
+export interface TellannEvent {
+    eventId: string;
+    sessionId: string;
+    tenantId: string;
+    applicationId: string;
+    environmentId?: string | null;
+    runId?: string | null;
+    traceId?: string | null;
+    agentVersion?: string | null;
+    instrumentationManifestVersion?: string | null;
+    source: string;
+    eventVersion: string;
+    eventType: EventType;
+    timestamp: string;
+    metadata: Record<string, any>;
+}

package/dist/event-types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import type { EventType } from './event-types';
+export type { EventType, TellannEvent } from './event-types';
+export interface TellannConfig {
+    endpoint: string;
+    tenantId?: string;
+    applicationId: string;
+    apiKey?: string;
+    environmentId?: string;
+    autoTrackClicks?: boolean;
+    autoTrackForms?: boolean;
+    autoTrackRoutes?: boolean;
+    errorTracking?: boolean;
+    debug?: boolean;
+    flushIntervalMs?: number;
+    maxBufferSize?: number;
+    runId?: string;
+    sessionId?: string;
+    traceId?: string;
+    agentVersion?: string;
+    instrumentationManifestVersion?: string;
+}
+declare class TellannFrontendSDK {
+    private config;
+    private sessionId;
+    private eventBuffer;
+    private flushInterval;
+    private workflowTracker;
+    private teardownAutoTrack;
+    initialize(config: TellannConfig): void;
+    startSession(): void;
+    endSession(): void;
+    teardown(): void;
+    trackEvent(eventType: EventType, metadata?: Record<string, any>): void;
+    verifyInstallation(): Promise<void>;
+    trackBusinessEvent(config: {
+        type: string;
+        payload?: Record<string, any>;
+    }): void;
+    trackState(stateName: string, category?: string): void;
+    trackTransition(fromState: string, toState: string, action?: string): void;
+    startWorkflow(workflowName: string): string;
+    completeWorkflow(workflowId: string): void;
+    failWorkflow(workflowId: string, reason?: string): void;
+    abandonWorkflow(workflowId: string): void;
+    cancelWorkflow(workflowId: string, reason?: string): void;
+    captureException(error: Error | unknown, context?: Record<string, any>): void;
+    captureMessage(message: string, severity?: 'info' | 'warning' | 'error'): void;
+    identifyUser(userId: string, traits?: Record<string, any>): void;
+    private startFlushInterval;
+    private flush;
+}
+export declare const TELLANN: TellannFrontendSDK;
+export { TellannFrontendSDK };

package/dist/index.js

@@ -0,0 +1,266 @@
+import { v4 as uuidv4 } from 'uuid';
+import { WorkflowTracker } from './workflow-tracker.js';
+import { setupAutoTrack, sanitizeMetadata } from './auto-track.js';
+const MAX_EVENT_SIZE_BYTES = 32 * 1024; // 32 KB limit for standard events
+const MAX_REPLAY_SIZE_BYTES = 128 * 1024; // 128 KB limit for replay events (e.g. if eventType is a replay event)
+class TellannFrontendSDK {
+    config = null;
+    sessionId = null;
+    eventBuffer = [];
+    flushInterval = null;
+    workflowTracker = new WorkflowTracker();
+    teardownAutoTrack = null;
+    initialize(config) {
+        this.config = {
+            autoTrackClicks: true,
+            autoTrackForms: true,
+            autoTrackRoutes: true,
+            errorTracking: true,
+            debug: false,
+            flushIntervalMs: 5000,
+            maxBufferSize: 200,
+            ...config
+        };
+        this.startSession();
+        this.startFlushInterval();
+        // Set up auto-tracking
+        this.teardownAutoTrack = setupAutoTrack(this, {
+            autoTrackClicks: this.config.autoTrackClicks,
+            autoTrackForms: this.config.autoTrackForms,
+            autoTrackRoutes: this.config.autoTrackRoutes,
+            errorTracking: this.config.errorTracking
+        });
+        if (this.config.debug) {
+            console.log('[Tellann] Initialized and auto-tracking started', this.config);
+        }
+    }
+    startSession() {
+        this.sessionId = this.config?.sessionId ?? uuidv4();
+        this.trackEvent('PAGE_VIEW', {
+            url: window.location.href,
+            title: document.title,
+            referrer: document.referrer,
+        });
+    }
+    endSession() {
+        this.sessionId = null;
+        this.flush();
+    }
+    teardown() {
+        if (this.flushInterval) {
+            clearInterval(this.flushInterval);
+            this.flushInterval = null;
+        }
+        if (this.teardownAutoTrack) {
+            this.teardownAutoTrack();
+            this.teardownAutoTrack = null;
+        }
+        this.endSession();
+    }
+    trackEvent(eventType, metadata = {}) {
+        if (!this.config || !this.sessionId) {
+            if (this.config?.debug) {
+                console.warn('[Tellann] SDK not initialized or session not started');
+            }
+            return;
+        }
+        // Apply privacy-by-default metadata sanitization
+        const sanitizedMetadata = sanitizeMetadata(metadata);
+        const event = {
+            eventId: uuidv4(),
+            sessionId: this.sessionId,
+            tenantId: this.config.tenantId ?? 'unknown',
+            applicationId: this.config.applicationId,
+            environmentId: this.config.environmentId ?? null,
+            runId: this.config.runId ?? null,
+            traceId: this.config.traceId ?? null,
+            agentVersion: this.config.agentVersion ?? null,
+            instrumentationManifestVersion: this.config.instrumentationManifestVersion ?? null,
+            source: 'frontend-sdk',
+            eventVersion: '1.0',
+            eventType,
+            timestamp: new Date().toISOString(),
+            metadata: sanitizedMetadata,
+        };
+        // Payload Size Enforcement
+        try {
+            const eventJson = JSON.stringify(event);
+            const eventSize = typeof Blob !== 'undefined'
+                ? new Blob([eventJson]).size
+                : eventJson.length;
+            const limit = eventType.includes('REPLAY') ? MAX_REPLAY_SIZE_BYTES : MAX_EVENT_SIZE_BYTES;
+            if (eventSize > limit) {
+                console.error(`[Tellann] Event of type "${eventType}" discarded. Size (${eventSize} bytes) exceeds limit of ${limit} bytes.`);
+                return;
+            }
+        }
+        catch (err) {
+            console.error('[Tellann] Failed to compute size of event, discarding', err);
+            return;
+        }
+        this.eventBuffer.push(event);
+        // If max buffer size reached, flush immediately
+        const maxBuffer = this.config.maxBufferSize ?? 200;
+        if (this.eventBuffer.length >= maxBuffer) {
+            this.flush();
+        }
+    }
+    async verifyInstallation() {
+        this.trackEvent('TELLANN_INITIALIZED', {
+            source: 'manual_verification',
+            verificationKind: 'BOOTSTRAP_INITIALIZED',
+            instrumentationManifestVersion: this.config?.instrumentationManifestVersion ?? null,
+            agentVersion: this.config?.agentVersion ?? null,
+        });
+        await this.flush();
+    }
+    trackBusinessEvent(config) {
+        this.trackEvent('BUSINESS_EVENT', {
+            businessEventType: config.type,
+            ...(config.payload || {})
+        });
+    }
+    // Missing Frontend SDK methods
+    trackState(stateName, category) {
+        this.trackEvent('STATE_ENTERED', {
+            stateName,
+            category: category || 'BUSINESS',
+        });
+    }
+    trackTransition(fromState, toState, action) {
+        this.trackEvent('STATE_TRANSITION', {
+            fromState,
+            toState,
+            action: action || 'NAVIGATE',
+        });
+    }
+    startWorkflow(workflowName) {
+        const id = this.workflowTracker.start(workflowName);
+        this.trackEvent('WORKFLOW_STARTED', {
+            workflowId: id,
+            workflowName,
+        });
+        return id;
+    }
+    completeWorkflow(workflowId) {
+        const result = this.workflowTracker.complete(workflowId);
+        if (result) {
+            this.trackEvent('WORKFLOW_COMPLETED', {
+                workflowId,
+                workflowName: result.name,
+                durationMs: result.durationMs,
+            });
+        }
+    }
+    failWorkflow(workflowId, reason) {
+        const result = this.workflowTracker.fail(workflowId);
+        if (result) {
+            this.trackEvent('WORKFLOW_FAILED', {
+                workflowId,
+                workflowName: result.name,
+                durationMs: result.durationMs,
+                reason: reason || 'Unknown error',
+            });
+        }
+    }
+    abandonWorkflow(workflowId) {
+        this.workflowTracker.abandon(workflowId);
+    }
+    cancelWorkflow(workflowId, reason) {
+        const result = this.workflowTracker.fail(workflowId);
+        if (result) {
+            this.trackEvent('WORKFLOW_CANCELLED', {
+                workflowId,
+                workflowName: result.name,
+                durationMs: result.durationMs,
+                reason: reason ?? 'Cancelled',
+            });
+        }
+    }
+    captureException(error, context) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        this.trackEvent('ERROR_OCCURRED', {
+            message: err.message,
+            stack: err.stack || null,
+            name: err.name,
+            context: context || {},
+        });
+    }
+    captureMessage(message, severity = 'error') {
+        this.trackEvent('CLIENT_ERROR', {
+            message,
+            severity,
+        });
+    }
+    identifyUser(userId, traits) {
+        this.trackEvent('BUSINESS_EVENT', {
+            businessEventType: 'USER_IDENTIFIED',
+            userId,
+            traits: traits || {},
+        });
+    }
+    startFlushInterval() {
+        const intervalMs = this.config?.flushIntervalMs || 5000;
+        this.flushInterval = window.setInterval(() => {
+            this.flush();
+        }, intervalMs);
+    }
+    async flush() {
+        if (this.eventBuffer.length === 0 || !this.config)
+            return;
+        const eventsToSend = [...this.eventBuffer];
+        this.eventBuffer = [];
+        try {
+            const payload = JSON.stringify(eventsToSend);
+            // Enforce 5 MB batch limit
+            const payloadSize = typeof Blob !== 'undefined'
+                ? new Blob([payload]).size
+                : payload.length;
+            if (payloadSize > 5 * 1024 * 1024) {
+                console.error(`[Tellann] Batch payload size of ${payloadSize} bytes exceeds the 5 MB limit. Dropping batch.`);
+                return;
+            }
+            const headers = {
+                'Content-Type': 'application/json',
+            };
+            if (this.config.apiKey) {
+                headers.Authorization = `Bearer ${this.config.apiKey}`;
+            }
+            if (this.config.environmentId) {
+                headers['x-tellann-environment-id'] = this.config.environmentId;
+            }
+            if (this.config.runId)
+                headers['x-tellann-run-id'] = this.config.runId;
+            if (this.sessionId)
+                headers['x-tellann-session-id'] = this.sessionId;
+            if (this.config.traceId)
+                headers['x-tellann-trace-id'] = this.config.traceId;
+            // sendBeacon cannot set auth headers, so only use it for unauthenticated direct collector targets.
+            if (!this.config.apiKey && !this.config.environmentId && navigator.sendBeacon && typeof Blob !== 'undefined') {
+                const blob = new Blob([payload], { type: 'application/json' });
+                const success = navigator.sendBeacon(`${this.config.endpoint}/v1/events/batch`, blob);
+                if (!success) {
+                    throw new Error('sendBeacon returned false');
+                }
+            }
+            else {
+                // Fallback to fetch
+                await fetch(`${this.config.endpoint}/v1/events/batch`, {
+                    method: 'POST',
+                    headers,
+                    body: payload,
+                    keepalive: true, // Use keepalive for page unloads if beacon is unavailable
+                });
+            }
+        }
+        catch (error) {
+            if (this.config.debug) {
+                console.error('[Tellann] Failed to flush events', error);
+            }
+            // Re-add to buffer on failure
+            this.eventBuffer = [...eventsToSend, ...this.eventBuffer];
+        }
+    }
+}
+export const TELLANN = new TellannFrontendSDK();
+export { TellannFrontendSDK };

package/dist/workflow-tracker.d.ts

@@ -0,0 +1,13 @@
+export declare class WorkflowTracker {
+    private workflows;
+    start(name: string): string;
+    complete(workflowId: string): {
+        name: string;
+        durationMs: number;
+    } | null;
+    fail(workflowId: string): {
+        name: string;
+        durationMs: number;
+    } | null;
+    abandon(workflowId: string): void;
+}

package/dist/workflow-tracker.js

@@ -0,0 +1,35 @@
+import { v4 as uuidv4 } from 'uuid';
+export class WorkflowTracker {
+    workflows = new Map();
+    start(name) {
+        const id = uuidv4();
+        this.workflows.set(id, {
+            name,
+            startedAt: Date.now()
+        });
+        return id;
+    }
+    complete(workflowId) {
+        const workflow = this.workflows.get(workflowId);
+        if (!workflow)
+            return null;
+        this.workflows.delete(workflowId);
+        return {
+            name: workflow.name,
+            durationMs: Date.now() - workflow.startedAt
+        };
+    }
+    fail(workflowId) {
+        const workflow = this.workflows.get(workflowId);
+        if (!workflow)
+            return null;
+        this.workflows.delete(workflowId);
+        return {
+            name: workflow.name,
+            durationMs: Date.now() - workflow.startedAt
+        };
+    }
+    abandon(workflowId) {
+        this.workflows.delete(workflowId);
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@tellann/frontend-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Tellann browser telemetry and QA-run correlation SDK",
+  "license": "UNLICENSED",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pellumi/monitor.git",
+    "directory": "packages/frontend-sdk"
+  },
+  "homepage": "https://github.com/Pellumi/monitor/tree/main/packages/frontend-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/Pellumi/monitor/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/uuid": "^9.0.8",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "test": "node --test dist/index.test.js"
+  }
+}