@tellann/backend-sdk 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# @tellann/backend-sdk
+
+Server-side telemetry and QA-run correlation SDK for Tellann. Tracks API requests,
+server errors, state transitions, and workflow lifecycle events, and correlates them
+with a frontend session/run/trace via inbound headers. Ships optional Express and
+Fastify integrations.
+
+## Install
+
+```bash
+npm install @tellann/backend-sdk
+# or
+pnpm add @tellann/backend-sdk
+```
+
+`express` and `fastify` are optional peer dependencies — install whichever framework
+you use. The core API works without either.
+
+## Quick start
+
+```ts
+import { TELLANN } from '@tellann/backend-sdk';
+
+TELLANN.initialize({
+  endpoint: 'https://collector.example.com',
+  applicationId: 'my-api',
+  environmentId: 'production',
+  apiKey: '<server-key>', // optional
+});
+
+await TELLANN.trackApi({
+  endpoint: '/orders',
+  method: 'POST',
+  statusCode: 201,
+  durationMs: 42,
+  sessionId, // optional, from x-tellann-session-id
+});
+
+await TELLANN.captureError({ error, eventType: 'SERVER_ERROR' });
+await TELLANN.trackState({ /* TrackStateOptions */ });
+```
+
+Standalone helper functions are also exported and operate on the initialized singleton:
+
+```ts
+import { trackApi, captureError, trackState } from '@tellann/backend-sdk';
+```
+
+### Configuration (`TellannBackendConfig`)
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `endpoint` | `string` | Collector base URL. |
+| `applicationId` | `string` | Identifies the service. |
+| `tenantId` | `string` | Optional; defaults to `'unknown'`. |
+| `environmentId` | `string` | Optional environment identifier. |
+| `apiKey` | `string` | Optional; sent as a bearer token. |
+| `runId` / `sessionId` / `traceId` | `string` | Optional correlation IDs. |
+| `agentVersion` / `instrumentationManifestVersion` | `string` | Optional correlation metadata. |
+
+Individual events are capped at 32 KB.
+
+## Express integration
+
+```ts
+import express from 'express';
+import {
+  tellannExpressMiddleware,
+  tellannExpressErrorHandler,
+} from '@tellann/backend-sdk';
+
+const app = express();
+
+app.use(tellannExpressMiddleware());     // extracts correlation context, times requests
+// ... your routes ...
+app.use(tellannExpressErrorHandler());   // captures errors (mount last)
+```
+
+The middleware populates `req.tellann` with `{ sessionId, runId, traceId }` extracted
+from `x-tellann-session-id`, `x-tellann-run-id`, `x-tellann-trace-id`, and W3C
+`traceparent` headers.
+
+## Fastify integration
+
+```ts
+import Fastify from 'fastify';
+import { tellannFastifyPlugin } from '@tellann/backend-sdk';
+
+const fastify = Fastify();
+await fastify.register(tellannFastifyPlugin);
+```
+
+The plugin adds `onResponse` and `onError` hooks that emit `API_REQUEST` and
+`SERVER_ERROR` events with timing and correlation data.
+
+## Workflows
+
+```ts
+const id = TELLANN.startWorkflow('nightly-reconcile', sessionId);
+await TELLANN.completeWorkflow(id, sessionId);
+// or failWorkflow(id, sessionId, reason)
+```
+
+## TypeScript
+
+Types ship with the package. `TellannBackendConfig`, `TrackApiOptions`,
+`CaptureErrorOptions`, `TrackStateOptions`, `EventType`, and `TellannEvent` are exported.
+
+## License
+
+`UNLICENSED` — see the repository for terms.

package/dist/core/SOTS.d.ts

@@ -0,0 +1,39 @@
+import { TrackApiOptions } from './trackApi';
+import { CaptureErrorOptions } from './captureError';
+import { TrackStateOptions } from './trackState';
+import { BackendWorkflowTracker } from './workflowTracker';
+import type { EventType } from '../event-types';
+export interface SotsBackendConfig {
+    endpoint: string;
+    tenantId?: string;
+    applicationId: string;
+    apiKey?: string;
+    environmentId?: string;
+    runId?: string;
+    sessionId?: string;
+    traceId?: string;
+    agentVersion?: string;
+    instrumentationManifestVersion?: string;
+}
+export declare class SOTSBackend {
+    private config;
+    private workflowTracker;
+    initialize(config: SotsBackendConfig): void;
+    getConfig(): SotsBackendConfig | null;
+    isInitialized(): boolean;
+    trackApi(options: TrackApiOptions): Promise<void>;
+    captureError(options: CaptureErrorOptions): Promise<void>;
+    trackState(options: TrackStateOptions): Promise<void>;
+    trackEvent(eventType: EventType, metadata?: Record<string, any>, sessionId?: string): Promise<void>;
+    verifyInstallation(sessionId?: string): Promise<void>;
+    startWorkflow(workflowName: string, sessionId?: string): string;
+    completeWorkflow(workflowId: string, sessionId?: string): Promise<void>;
+    failWorkflow(workflowId: string, reason?: string, sessionId?: string): Promise<void>;
+    abandonWorkflow(workflowId: string): void;
+    cancelWorkflow(workflowId: string, reason?: string, sessionId?: string): Promise<void>;
+    captureMessage(message: string, severity?: string, sessionId?: string): Promise<void>;
+    private sendEvent;
+    teardown(): void;
+}
+export declare const SOTS: SOTSBackend;
+export { BackendWorkflowTracker };

package/dist/core/SOTS.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackendWorkflowTracker = exports.SOTS = exports.SOTSBackend = void 0;
+const trackApi_1 = require("./trackApi");
+const captureError_1 = require("./captureError");
+const trackState_1 = require("./trackState");
+const workflowTracker_1 = require("./workflowTracker");
+Object.defineProperty(exports, "BackendWorkflowTracker", { enumerable: true, get: function () { return workflowTracker_1.BackendWorkflowTracker; } });
+const uuid_1 = require("uuid");
+class SOTSBackend {
+    config = null;
+    workflowTracker = new workflowTracker_1.BackendWorkflowTracker();
+    initialize(config) {
+        this.config = config;
+        console.log('[Tellann Backend] Initialized');
+    }
+    getConfig() {
+        return this.config;
+    }
+    isInitialized() {
+        return this.config !== null;
+    }
+    async trackApi(options) {
+        if (!this.config)
+            return;
+        await (0, trackApi_1.trackApiEvent)(this.config, options);
+    }
+    async captureError(options) {
+        if (!this.config)
+            return;
+        await (0, captureError_1.captureErrorEvent)(this.config, options);
+    }
+    async trackState(options) {
+        if (!this.config)
+            return;
+        await (0, trackState_1.trackStateEvent)(this.config, options);
+    }
+    async trackEvent(eventType, metadata = {}, sessionId) {
+        await this.sendEvent(eventType, sessionId, metadata);
+    }
+    async verifyInstallation(sessionId) {
+        await this.trackEvent('TELLANN_INITIALIZED', {
+            source: 'manual_verification',
+            verificationKind: 'BOOTSTRAP_INITIALIZED',
+        }, sessionId);
+    }
+    startWorkflow(workflowName, sessionId) {
+        const id = this.workflowTracker.start(workflowName);
+        this.sendEvent('WORKFLOW_STARTED', sessionId, {
+            workflowId: id,
+            workflowName,
+        });
+        return id;
+    }
+    async completeWorkflow(workflowId, sessionId) {
+        const result = this.workflowTracker.complete(workflowId);
+        if (result) {
+            await this.sendEvent('WORKFLOW_COMPLETED', sessionId, {
+                workflowId,
+                workflowName: result.name,
+                durationMs: result.durationMs,
+            });
+        }
+    }
+    async failWorkflow(workflowId, reason, sessionId) {
+        const result = this.workflowTracker.fail(workflowId);
+        if (result) {
+            await this.sendEvent('WORKFLOW_FAILED', sessionId, {
+                workflowId,
+                workflowName: result.name,
+                durationMs: result.durationMs,
+                reason: reason || 'Unknown error',
+            });
+        }
+    }
+    abandonWorkflow(workflowId) {
+        this.workflowTracker.abandon(workflowId);
+    }
+    async cancelWorkflow(workflowId, reason, sessionId) {
+        const result = this.workflowTracker.fail(workflowId);
+        if (result) {
+            await this.sendEvent('WORKFLOW_CANCELLED', sessionId, {
+                workflowId,
+                workflowName: result.name,
+                durationMs: result.durationMs,
+                reason: reason ?? 'Cancelled',
+            });
+        }
+    }
+    async captureMessage(message, severity, sessionId) {
+        await this.sendEvent('SERVER_ERROR', sessionId, {
+            message,
+            severity: severity || 'error',
+        });
+    }
+    async sendEvent(eventType, sessionId, metadata) {
+        if (!this.config)
+            return;
+        const event = {
+            eventId: (0, uuid_1.v4)(),
+            sessionId: sessionId ?? this.config.sessionId ?? (0, uuid_1.v4)(),
+            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: 'backend-sdk',
+            eventVersion: '1.0',
+            eventType: eventType,
+            timestamp: new Date().toISOString(),
+            metadata,
+        };
+        // Enforce size limit
+        try {
+            const eventJson = JSON.stringify(event);
+            const eventSize = Buffer.byteLength(eventJson, 'utf8');
+            if (eventSize > 32 * 1024) {
+                console.error(`[Tellann Backend] Event of type "${eventType}" discarded. Size (${eventSize} bytes) exceeds limit of 32 KB.`);
+                return;
+            }
+        }
+        catch {
+            return;
+        }
+        try {
+            const headers = { 'Content-Type': 'application/json' };
+            if (this.config.apiKey) {
+                headers.Authorization = `Bearer ${this.config.apiKey}`;
+            }
+            if (this.config.environmentId) {
+                headers['x-sots-environment-id'] = this.config.environmentId;
+            }
+            if (this.config.runId)
+                headers['x-tellann-run-id'] = this.config.runId;
+            if (sessionId ?? this.config.sessionId)
+                headers['x-tellann-session-id'] = sessionId ?? this.config.sessionId;
+            if (this.config.traceId)
+                headers['x-tellann-trace-id'] = this.config.traceId;
+            await fetch(`${this.config.endpoint}/v1/events`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(event),
+            });
+        }
+        catch {
+            // Swallowed
+        }
+    }
+    // Allow teardown to clean up intervals/tracker memory
+    teardown() {
+        this.workflowTracker.destroy();
+        this.config = null;
+    }
+}
+exports.SOTSBackend = SOTSBackend;
+exports.SOTS = new SOTSBackend();

package/dist/core/TELLANN.d.ts

@@ -0,0 +1,39 @@
+import { TrackApiOptions } from './trackApi';
+import { CaptureErrorOptions } from './captureError';
+import { TrackStateOptions } from './trackState';
+import { BackendWorkflowTracker } from './workflowTracker';
+import type { EventType } from '../event-types';
+export interface TellannBackendConfig {
+    endpoint: string;
+    tenantId?: string;
+    applicationId: string;
+    apiKey?: string;
+    environmentId?: string;
+    runId?: string;
+    sessionId?: string;
+    traceId?: string;
+    agentVersion?: string;
+    instrumentationManifestVersion?: string;
+}
+export declare class TELLANNBackend {
+    private config;
+    private workflowTracker;
+    initialize(config: TellannBackendConfig): void;
+    getConfig(): TellannBackendConfig | null;
+    isInitialized(): boolean;
+    trackApi(options: TrackApiOptions): Promise<void>;
+    captureError(options: CaptureErrorOptions): Promise<void>;
+    trackState(options: TrackStateOptions): Promise<void>;
+    trackEvent(eventType: EventType, metadata?: Record<string, any>, sessionId?: string): Promise<void>;
+    verifyInstallation(sessionId?: string): Promise<void>;
+    startWorkflow(workflowName: string, sessionId?: string): string;
+    completeWorkflow(workflowId: string, sessionId?: string): Promise<void>;
+    failWorkflow(workflowId: string, reason?: string, sessionId?: string): Promise<void>;
+    abandonWorkflow(workflowId: string): void;
+    cancelWorkflow(workflowId: string, reason?: string, sessionId?: string): Promise<void>;
+    captureMessage(message: string, severity?: string, sessionId?: string): Promise<void>;
+    private sendEvent;
+    teardown(): void;
+}
+export declare const TELLANN: TELLANNBackend;
+export { BackendWorkflowTracker };

package/dist/core/TELLANN.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackendWorkflowTracker = exports.TELLANN = exports.TELLANNBackend = void 0;
+const trackApi_1 = require("./trackApi");
+const captureError_1 = require("./captureError");
+const trackState_1 = require("./trackState");
+const workflowTracker_1 = require("./workflowTracker");
+Object.defineProperty(exports, "BackendWorkflowTracker", { enumerable: true, get: function () { return workflowTracker_1.BackendWorkflowTracker; } });
+const uuid_1 = require("uuid");
+class TELLANNBackend {
+    config = null;
+    workflowTracker = new workflowTracker_1.BackendWorkflowTracker();
+    initialize(config) {
+        this.config = config;
+        console.log('[Tellann Backend] Initialized');
+    }
+    getConfig() {
+        return this.config;
+    }
+    isInitialized() {
+        return this.config !== null;
+    }
+    async trackApi(options) {
+        if (!this.config)
+            return;
+        await (0, trackApi_1.trackApiEvent)(this.config, options);
+    }
+    async captureError(options) {
+        if (!this.config)
+            return;
+        await (0, captureError_1.captureErrorEvent)(this.config, options);
+    }
+    async trackState(options) {
+        if (!this.config)
+            return;
+        await (0, trackState_1.trackStateEvent)(this.config, options);
+    }
+    async trackEvent(eventType, metadata = {}, sessionId) {
+        await this.sendEvent(eventType, sessionId, metadata);
+    }
+    async verifyInstallation(sessionId) {
+        await this.trackEvent('TELLANN_INITIALIZED', {
+            source: 'manual_verification',
+            verificationKind: 'BOOTSTRAP_INITIALIZED',
+        }, sessionId);
+    }
+    startWorkflow(workflowName, sessionId) {
+        const id = this.workflowTracker.start(workflowName);
+        this.sendEvent('WORKFLOW_STARTED', sessionId, {
+            workflowId: id,
+            workflowName,
+        });
+        return id;
+    }
+    async completeWorkflow(workflowId, sessionId) {
+        const result = this.workflowTracker.complete(workflowId);
+        if (result) {
+            await this.sendEvent('WORKFLOW_COMPLETED', sessionId, {
+                workflowId,
+                workflowName: result.name,
+                durationMs: result.durationMs,
+            });
+        }
+    }
+    async failWorkflow(workflowId, reason, sessionId) {
+        const result = this.workflowTracker.fail(workflowId);
+        if (result) {
+            await this.sendEvent('WORKFLOW_FAILED', sessionId, {
+                workflowId,
+                workflowName: result.name,
+                durationMs: result.durationMs,
+                reason: reason || 'Unknown error',
+            });
+        }
+    }
+    abandonWorkflow(workflowId) {
+        this.workflowTracker.abandon(workflowId);
+    }
+    async cancelWorkflow(workflowId, reason, sessionId) {
+        const result = this.workflowTracker.fail(workflowId);
+        if (result) {
+            await this.sendEvent('WORKFLOW_CANCELLED', sessionId, {
+                workflowId,
+                workflowName: result.name,
+                durationMs: result.durationMs,
+                reason: reason ?? 'Cancelled',
+            });
+        }
+    }
+    async captureMessage(message, severity, sessionId) {
+        await this.sendEvent('SERVER_ERROR', sessionId, {
+            message,
+            severity: severity || 'error',
+        });
+    }
+    async sendEvent(eventType, sessionId, metadata) {
+        if (!this.config)
+            return;
+        const event = {
+            eventId: (0, uuid_1.v4)(),
+            sessionId: sessionId ?? this.config.sessionId ?? (0, uuid_1.v4)(),
+            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: 'backend-sdk',
+            eventVersion: '1.0',
+            eventType: eventType,
+            timestamp: new Date().toISOString(),
+            metadata,
+        };
+        // Enforce size limit
+        try {
+            const eventJson = JSON.stringify(event);
+            const eventSize = Buffer.byteLength(eventJson, 'utf8');
+            if (eventSize > 32 * 1024) {
+                console.error(`[Tellann Backend] Event of type "${eventType}" discarded. Size (${eventSize} bytes) exceeds limit of 32 KB.`);
+                return;
+            }
+        }
+        catch {
+            return;
+        }
+        try {
+            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 (sessionId ?? this.config.sessionId)
+                headers['x-tellann-session-id'] = sessionId ?? this.config.sessionId;
+            if (this.config.traceId)
+                headers['x-tellann-trace-id'] = this.config.traceId;
+            await fetch(`${this.config.endpoint}/v1/events`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(event),
+            });
+        }
+        catch {
+            // Swallowed
+        }
+    }
+    // Allow teardown to clean up intervals/tracker memory
+    teardown() {
+        this.workflowTracker.destroy();
+        this.config = null;
+    }
+}
+exports.TELLANNBackend = TELLANNBackend;
+exports.TELLANN = new TELLANNBackend();

package/dist/core/captureError.d.ts

@@ -0,0 +1,11 @@
+import { TellannBackendConfig } from './TELLANN';
+export interface CaptureErrorOptions {
+    error: Error | unknown;
+    context?: Record<string, any>;
+    /** Optional: link to a frontend session */
+    sessionId?: string;
+    eventType?: 'SERVER_ERROR' | 'ERROR_OCCURRED';
+    runId?: string;
+    traceId?: string;
+}
+export declare function captureErrorEvent(config: TellannBackendConfig, options: CaptureErrorOptions): Promise<void>;

package/dist/core/captureError.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureErrorEvent = captureErrorEvent;
+const uuid_1 = require("uuid");
+const MAX_EVENT_SIZE_BYTES = 32 * 1024; // 32 KB limit
+async function captureErrorEvent(config, options) {
+    const err = options.error instanceof Error ? options.error : new Error(String(options.error));
+    const event = {
+        eventId: (0, uuid_1.v4)(),
+        sessionId: options.sessionId ?? config.sessionId ?? (0, uuid_1.v4)(),
+        tenantId: config.tenantId ?? 'unknown',
+        applicationId: config.applicationId,
+        environmentId: config.environmentId ?? null,
+        runId: options.runId ?? config.runId ?? null,
+        traceId: options.traceId ?? config.traceId ?? null,
+        agentVersion: config.agentVersion ?? null,
+        instrumentationManifestVersion: config.instrumentationManifestVersion ?? null,
+        source: 'backend-sdk',
+        eventVersion: '1.0',
+        eventType: options.eventType ?? 'SERVER_ERROR',
+        timestamp: new Date().toISOString(),
+        metadata: {
+            message: err.message,
+            stack: err.stack ?? null,
+            name: err.name,
+            context: options.context ?? {},
+        },
+    };
+    // Enforce Size Limit
+    try {
+        const eventJson = JSON.stringify(event);
+        const eventSize = Buffer.byteLength(eventJson, 'utf8');
+        if (eventSize > MAX_EVENT_SIZE_BYTES) {
+            console.error(`[Tellann Backend] Error event discarded. Size (${eventSize} bytes) exceeds limit of ${MAX_EVENT_SIZE_BYTES} bytes.`);
+            return;
+        }
+    }
+    catch (err) {
+        console.error('[Tellann Backend] Failed to compute size of error event, discarding', err);
+        return;
+    }
+    try {
+        const headers = { 'Content-Type': 'application/json' };
+        if (config.apiKey) {
+            headers.Authorization = `Bearer ${config.apiKey}`;
+        }
+        if (config.environmentId) {
+            headers['x-tellann-environment-id'] = config.environmentId;
+        }
+        if (config.runId)
+            headers['x-tellann-run-id'] = config.runId;
+        if (config.traceId)
+            headers['x-tellann-trace-id'] = config.traceId;
+        await fetch(`${config.endpoint}/v1/events`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(event),
+        });
+    }
+    catch {
+        // Silently swallow
+    }
+}

package/dist/core/trackApi.d.ts

@@ -0,0 +1,14 @@
+import { TellannBackendConfig } from './TELLANN';
+export interface TrackApiOptions {
+    endpoint: string;
+    method: string;
+    statusCode: number;
+    durationMs: number;
+    /** Optional: correlate with a frontend session via X-TELLANN-Session-ID header */
+    sessionId?: string;
+    /** Optional: idempotency / tracing */
+    requestId?: string;
+    runId?: string;
+    traceId?: string;
+}
+export declare function trackApiEvent(config: TellannBackendConfig, options: TrackApiOptions): Promise<void>;

package/dist/core/trackApi.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackApiEvent = trackApiEvent;
+const uuid_1 = require("uuid");
+const MAX_EVENT_SIZE_BYTES = 32 * 1024; // 32 KB limit
+async function trackApiEvent(config, options) {
+    const event = {
+        eventId: (0, uuid_1.v4)(),
+        sessionId: options.sessionId ?? config.sessionId ?? (0, uuid_1.v4)(),
+        tenantId: config.tenantId ?? 'unknown',
+        applicationId: config.applicationId,
+        environmentId: config.environmentId ?? null,
+        runId: options.runId ?? config.runId ?? null,
+        traceId: options.traceId ?? config.traceId ?? null,
+        agentVersion: config.agentVersion ?? null,
+        instrumentationManifestVersion: config.instrumentationManifestVersion ?? null,
+        source: 'backend-sdk',
+        eventVersion: '1.0',
+        eventType: 'API_REQUEST',
+        timestamp: new Date().toISOString(),
+        metadata: {
+            requestId: options.requestId ?? (0, uuid_1.v4)(),
+            endpoint: options.endpoint,
+            method: options.method.toUpperCase(),
+            statusCode: options.statusCode,
+            durationMs: options.durationMs,
+        },
+    };
+    // Enforce Size Limit
+    try {
+        const eventJson = JSON.stringify(event);
+        const eventSize = Buffer.byteLength(eventJson, 'utf8');
+        if (eventSize > MAX_EVENT_SIZE_BYTES) {
+            console.error(`[Tellann Backend] API request event discarded. Size (${eventSize} bytes) exceeds limit of ${MAX_EVENT_SIZE_BYTES} bytes.`);
+            return;
+        }
+    }
+    catch (err) {
+        console.error('[Tellann Backend] Failed to compute size of API event, discarding', err);
+        return;
+    }
+    try {
+        const headers = { 'Content-Type': 'application/json' };
+        if (config.apiKey) {
+            headers.Authorization = `Bearer ${config.apiKey}`;
+        }
+        if (config.environmentId) {
+            headers['x-tellann-environment-id'] = config.environmentId;
+        }
+        if (config.runId)
+            headers['x-tellann-run-id'] = config.runId;
+        if (config.traceId)
+            headers['x-tellann-trace-id'] = config.traceId;
+        await fetch(`${config.endpoint}/v1/events`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(event),
+        });
+    }
+    catch {
+        // Silently swallow
+    }
+}

package/dist/core/trackState.d.ts

@@ -0,0 +1,10 @@
+import { TellannBackendConfig } from './TELLANN';
+export interface TrackStateOptions {
+    stateName: string;
+    category?: 'BUSINESS' | 'NAVIGATION' | 'SYSTEM';
+    sessionId?: string;
+    context?: Record<string, any>;
+    runId?: string;
+    traceId?: string;
+}
+export declare function trackStateEvent(config: TellannBackendConfig, options: TrackStateOptions): Promise<void>;

package/dist/core/trackState.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackStateEvent = trackStateEvent;
+const uuid_1 = require("uuid");
+const MAX_EVENT_SIZE_BYTES = 32 * 1024; // 32 KB limit
+async function trackStateEvent(config, options) {
+    const event = {
+        eventId: (0, uuid_1.v4)(),
+        sessionId: options.sessionId ?? config.sessionId ?? (0, uuid_1.v4)(),
+        tenantId: config.tenantId ?? 'unknown',
+        applicationId: config.applicationId,
+        environmentId: config.environmentId ?? null,
+        runId: options.runId ?? config.runId ?? null,
+        traceId: options.traceId ?? config.traceId ?? null,
+        agentVersion: config.agentVersion ?? null,
+        instrumentationManifestVersion: config.instrumentationManifestVersion ?? null,
+        source: 'backend-sdk',
+        eventVersion: '1.0',
+        eventType: 'STATE_ENTERED',
+        timestamp: new Date().toISOString(),
+        metadata: {
+            stateName: options.stateName,
+            category: options.category ?? 'BUSINESS',
+            context: options.context ?? {},
+        },
+    };
+    // Enforce Size Limit
+    try {
+        const eventJson = JSON.stringify(event);
+        const eventSize = Buffer.byteLength(eventJson, 'utf8');
+        if (eventSize > MAX_EVENT_SIZE_BYTES) {
+            console.error(`[Tellann Backend] State event discarded. Size (${eventSize} bytes) exceeds limit of ${MAX_EVENT_SIZE_BYTES} bytes.`);
+            return;
+        }
+    }
+    catch (err) {
+        console.error('[Tellann Backend] Failed to compute size of state event, discarding', err);
+        return;
+    }
+    try {
+        const headers = { 'Content-Type': 'application/json' };
+        if (config.apiKey) {
+            headers.Authorization = `Bearer ${config.apiKey}`;
+        }
+        if (config.environmentId) {
+            headers['x-tellann-environment-id'] = config.environmentId;
+        }
+        if (config.runId)
+            headers['x-tellann-run-id'] = config.runId;
+        if (config.traceId)
+            headers['x-tellann-trace-id'] = config.traceId;
+        await fetch(`${config.endpoint}/v1/events`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(event),
+        });
+    }
+    catch {
+        // Silently swallow
+    }
+}

package/dist/core/workflowTracker.d.ts

@@ -0,0 +1,19 @@
+export declare class BackendWorkflowTracker {
+    private workflows;
+    private readonly ttlMs;
+    private readonly maxLifetimeMs;
+    private cleanupInterval;
+    constructor();
+    start(name: string): string;
+    complete(workflowId: string): {
+        name: string;
+        durationMs: number;
+    } | null;
+    fail(workflowId: string): {
+        name: string;
+        durationMs: number;
+    } | null;
+    abandon(workflowId: string): void;
+    private cleanup;
+    destroy(): void;
+}

package/dist/core/workflowTracker.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackendWorkflowTracker = void 0;
+const uuid_1 = require("uuid");
+class BackendWorkflowTracker {
+    workflows = new Map();
+    ttlMs = 30 * 60 * 1000; // 30 minutes idle timeout
+    maxLifetimeMs = 2 * 60 * 60 * 1000; // 2 hours absolute limit
+    cleanupInterval = null;
+    constructor() {
+        // Periodic cleanup every 5 minutes
+        if (typeof setInterval !== 'undefined') {
+            this.cleanupInterval = setInterval(() => this.cleanup(), 5 * 60 * 1000);
+            // Allow Node process to exit if only this timer is active
+            if (this.cleanupInterval.unref) {
+                this.cleanupInterval.unref();
+            }
+        }
+    }
+    start(name) {
+        this.cleanup(); // Clean up on start
+        const id = (0, uuid_1.v4)();
+        this.workflows.set(id, {
+            name,
+            startedAt: Date.now(),
+            lastAccessedAt: Date.now()
+        });
+        return id;
+    }
+    complete(workflowId) {
+        this.cleanup();
+        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) {
+        this.cleanup();
+        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);
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const [id, workflow] of this.workflows.entries()) {
+            const isIdleExpired = now - workflow.lastAccessedAt > this.ttlMs;
+            const isAbsoluteExpired = now - workflow.startedAt > this.maxLifetimeMs;
+            if (isIdleExpired || isAbsoluteExpired) {
+                this.workflows.delete(id);
+            }
+        }
+    }
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.workflows.clear();
+    }
+}
+exports.BackendWorkflowTracker = BackendWorkflowTracker;

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,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { TrackApiOptions } from './core/trackApi';
+import { CaptureErrorOptions } from './core/captureError';
+import { TrackStateOptions } from './core/trackState';
+export * from './core/TELLANN';
+export type { EventType, TellannEvent } from './event-types';
+export { TrackApiOptions } from './core/trackApi';
+export { CaptureErrorOptions } from './core/captureError';
+export { TrackStateOptions } from './core/trackState';
+export * from './integrations/express';
+export * from './integrations/fastify';
+/**
+ * Backward compatible helper to track an API call using the initialized TELLANN singleton.
+ */
+export declare function trackApi(options: TrackApiOptions): Promise<void>;
+/**
+ * Backward compatible helper to capture an error using the initialized TELLANN singleton.
+ */
+export declare function captureError(options: CaptureErrorOptions): Promise<void>;
+/**
+ * Backward compatible helper to track a state transition using the initialized TELLANN singleton.
+ */
+export declare function trackState(options: TrackStateOptions): Promise<void>;

package/dist/index.js

@@ -0,0 +1,41 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackApi = trackApi;
+exports.captureError = captureError;
+exports.trackState = trackState;
+const TELLANN_1 = require("./core/TELLANN");
+__exportStar(require("./core/TELLANN"), exports);
+__exportStar(require("./integrations/express"), exports);
+__exportStar(require("./integrations/fastify"), exports);
+/**
+ * Backward compatible helper to track an API call using the initialized TELLANN singleton.
+ */
+async function trackApi(options) {
+    await TELLANN_1.TELLANN.trackApi(options);
+}
+/**
+ * Backward compatible helper to capture an error using the initialized TELLANN singleton.
+ */
+async function captureError(options) {
+    await TELLANN_1.TELLANN.captureError(options);
+}
+/**
+ * Backward compatible helper to track a state transition using the initialized TELLANN singleton.
+ */
+async function trackState(options) {
+    await TELLANN_1.TELLANN.trackState(options);
+}

package/dist/integrations/express/index.d.ts

@@ -0,0 +1,31 @@
+import type { ErrorRequestHandler, RequestHandler } from 'express';
+declare global {
+    namespace Express {
+        interface Request {
+            tellann?: {
+                sessionId?: string;
+                runId?: string;
+                traceId?: string;
+            };
+        }
+    }
+}
+export declare function extractSessionId(headers: Record<string, any>): string | undefined;
+export declare function extractCorrelationContext(headers: Record<string, any>): {
+    sessionId?: string;
+    runId?: string;
+    traceId?: string;
+};
+/**
+ * Express middleware that automatically tracks every API request and hydrates req.tellann context.
+ *
+ * The middleware reads the `X-TELLANN-Session-ID` or W3C `traceparent` header to correlate
+ * backend API calls with the originating frontend session.
+ */
+export declare function tellannExpressMiddleware(): RequestHandler;
+/**
+ * Global Express error-handling middleware that automatically captures unhandled errors.
+ */
+export declare function tellannExpressErrorHandler(): ErrorRequestHandler;
+/** @deprecated Use tellannExpressMiddleware() */
+export declare const expressMiddleware: typeof tellannExpressMiddleware;

package/dist/integrations/express/index.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expressMiddleware = void 0;
+exports.extractSessionId = extractSessionId;
+exports.extractCorrelationContext = extractCorrelationContext;
+exports.tellannExpressMiddleware = tellannExpressMiddleware;
+exports.tellannExpressErrorHandler = tellannExpressErrorHandler;
+const TELLANN_1 = require("../../core/TELLANN");
+function extractSessionId(headers) {
+    if (headers['x-tellann-session-id'] || headers['x-tellann-session-id']) {
+        return (headers['x-tellann-session-id'] || headers['x-tellann-session-id']);
+    }
+    const traceparent = headers['traceparent'];
+    if (traceparent) {
+        const parts = traceparent.split('-');
+        if (parts.length >= 2 && parts[1].length === 32) {
+            const t = parts[1];
+            return `${t.slice(0, 8)}-${t.slice(8, 12)}-${t.slice(12, 16)}-${t.slice(16, 20)}-${t.slice(20)}`;
+        }
+    }
+    return undefined;
+}
+function extractCorrelationContext(headers) {
+    const traceparent = headers.traceparent;
+    const traceId = headers['x-tellann-trace-id'] ?? traceparent?.split('-')[1];
+    return {
+        sessionId: extractSessionId(headers),
+        runId: headers['x-tellann-run-id'],
+        traceId,
+    };
+}
+/**
+ * Express middleware that automatically tracks every API request and hydrates req.tellann context.
+ *
+ * The middleware reads the `X-TELLANN-Session-ID` or W3C `traceparent` header to correlate
+ * backend API calls with the originating frontend session.
+ */
+function tellannExpressMiddleware() {
+    return (req, res, next) => {
+        const start = Date.now();
+        const correlation = extractCorrelationContext(req.headers);
+        const { sessionId } = correlation;
+        const requestId = req.headers['x-request-id'];
+        // Decorate request object
+        req.tellann = correlation;
+        res.on('finish', () => {
+            TELLANN_1.TELLANN.trackApi({
+                endpoint: req.path,
+                method: req.method,
+                statusCode: res.statusCode,
+                durationMs: Date.now() - start,
+                sessionId,
+                requestId,
+                runId: correlation.runId,
+                traceId: correlation.traceId,
+            });
+        });
+        next();
+    };
+}
+/**
+ * Global Express error-handling middleware that automatically captures unhandled errors.
+ */
+function tellannExpressErrorHandler() {
+    return (err, req, res, next) => {
+        const sessionId = req.tellann?.sessionId;
+        TELLANN_1.TELLANN.captureError({
+            error: err,
+            sessionId,
+            eventType: 'SERVER_ERROR',
+            runId: req.tellann?.runId,
+            traceId: req.tellann?.traceId,
+            context: {
+                path: req.path,
+                method: req.method,
+                query: req.query,
+            },
+        });
+        next(err);
+    };
+}
+/** @deprecated Use tellannExpressMiddleware() */
+exports.expressMiddleware = tellannExpressMiddleware;

package/dist/integrations/fastify/index.d.ts

@@ -0,0 +1,13 @@
+import type { FastifyPluginAsync } from 'fastify';
+declare module 'fastify' {
+    interface FastifyRequest {
+        tellann?: {
+            sessionId?: string;
+            runId?: string;
+            traceId?: string;
+        };
+    }
+}
+export declare const tellannFastifyPlugin: FastifyPluginAsync;
+/** @deprecated Use tellannFastifyPlugin */
+export declare const fastifyPlugin: FastifyPluginAsync;

package/dist/integrations/fastify/index.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fastifyPlugin = exports.tellannFastifyPlugin = void 0;
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+const TELLANN_1 = require("../../core/TELLANN");
+const express_1 = require("../express");
+/**
+ * Fastify plugin that automatically tracks every API request and handles error correlation.
+ *
+ * Usage:
+ *   import { tellannFastifyPlugin } from '@tellann/backend-sdk';
+ *   await fastify.register(tellannFastifyPlugin);
+ *
+ * The plugin reads the `x-tellann-session-id` or W3C `traceparent` header to correlate
+ * backend API calls with the originating frontend session.
+ */
+const tellannFastifyPluginImpl = async (fastify) => {
+    // Add preHandler to extract session metadata
+    fastify.addHook('onRequest', async (request) => {
+        request.tellann = (0, express_1.extractCorrelationContext)(request.headers);
+    });
+    // Track API completion
+    fastify.addHook('onResponse', async (request, reply) => {
+        const sessionId = request.tellann?.sessionId;
+        const requestId = request.headers['x-request-id'];
+        await TELLANN_1.TELLANN.trackApi({
+            endpoint: request.routeOptions?.url ?? request.url,
+            method: request.method,
+            statusCode: reply.statusCode,
+            durationMs: Math.round(reply.elapsedTime),
+            sessionId,
+            requestId,
+            runId: request.tellann?.runId,
+            traceId: request.tellann?.traceId,
+        });
+    });
+    // Track errors
+    fastify.addHook('onError', async (request, reply, error) => {
+        const sessionId = request.tellann?.sessionId;
+        await TELLANN_1.TELLANN.captureError({
+            error,
+            sessionId,
+            eventType: 'SERVER_ERROR',
+            runId: request.tellann?.runId,
+            traceId: request.tellann?.traceId,
+            context: {
+                url: request.url,
+                method: request.method,
+            },
+        });
+    });
+};
+exports.tellannFastifyPlugin = (0, fastify_plugin_1.default)(tellannFastifyPluginImpl, {
+    name: 'tellann-fastify-plugin',
+    fastify: '>=4.0.0',
+});
+/** @deprecated Use tellannFastifyPlugin */
+exports.fastifyPlugin = exports.tellannFastifyPlugin;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@tellann/backend-sdk",
+  "version": "0.1.0",
+  "description": "Tellann server telemetry and QA-run correlation SDK",
+  "license": "UNLICENSED",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pellumi/monitor.git",
+    "directory": "packages/backend-sdk"
+  },
+  "homepage": "https://github.com/Pellumi/monitor/tree/main/packages/backend-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/Pellumi/monitor/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "fastify-plugin": "^4.5.1",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/uuid": "^9.0.8",
+    "express": "^4.18.2",
+    "fastify": "^4.26.0",
+    "typescript": "^5.0.0",
+    "@tellann/shared": "0.1.0"
+  },
+  "peerDependencies": {
+    "express": ">=4",
+    "fastify": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "test": "node --test dist/index.test.js"
+  }
+}