@tellann/backend-sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export { CaptureErrorOptions } from './core/captureError';
 export { TrackStateOptions } from './core/trackState';
 export * from './integrations/express';
 export * from './integrations/fastify';
+export * from './integrations/koa';
+export * from './integrations/hapi';
 /**
  * Backward compatible helper to track an API call using the initialized TELLANN singleton.
  */

package/dist/index.js

@@ -21,6 +21,8 @@ const TELLANN_1 = require("./core/TELLANN");
 __exportStar(require("./core/TELLANN"), exports);
 __exportStar(require("./integrations/express"), exports);
 __exportStar(require("./integrations/fastify"), exports);
+__exportStar(require("./integrations/koa"), exports);
+__exportStar(require("./integrations/hapi"), exports);
 /**
  * Backward compatible helper to track an API call using the initialized TELLANN singleton.
  */

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

@@ -0,0 +1,41 @@
+/**
+ * hapi integration, written as a hapi plugin.
+ *
+ * As with the Koa integration, hapi's types are described structurally so that
+ * this SDK never requires `@hapi/hapi` to be installed in a project that does
+ * not use it.
+ */
+export type TellannHapiRequest = {
+    method: string;
+    path: string;
+    headers: Record<string, any>;
+    /** The route table entry; its `path` is the pattern, not the request path. */
+    route?: {
+        path?: string;
+    };
+    response?: {
+        statusCode?: number;
+        isBoom?: boolean;
+        output?: {
+            statusCode?: number;
+        };
+    };
+    app: Record<string, any>;
+    info?: {
+        received?: number;
+    };
+};
+export type TellannHapiServer = {
+    ext(event: string, handler: (request: TellannHapiRequest, h: any) => any): void;
+    events?: {
+        on(name: string, handler: (...args: any[]) => void): void;
+    };
+};
+/**
+ * The hapi plugin object, registered with `await server.register(tellannHapiPlugin)`.
+ */
+export declare const tellannHapiPlugin: {
+    name: string;
+    version: string;
+    register(server: TellannHapiServer): void;
+};

package/dist/integrations/hapi/index.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tellannHapiPlugin = void 0;
+const TELLANN_1 = require("../../core/TELLANN");
+const express_1 = require("../express");
+function statusOf(request) {
+    const response = request.response;
+    if (!response)
+        return 0;
+    return (response.isBoom ? response.output?.statusCode : response.statusCode) ?? 0;
+}
+/**
+ * The hapi plugin object, registered with `await server.register(tellannHapiPlugin)`.
+ */
+exports.tellannHapiPlugin = {
+    name: 'tellann',
+    version: '1.0.0',
+    register(server) {
+        server.ext('onRequest', (request, h) => {
+            request.app.tellann = {
+                ...(0, express_1.extractCorrelationContext)(request.headers ?? {}),
+                startedAt: Date.now(),
+            };
+            return h.continue;
+        });
+        server.ext('onPreResponse', (request, h) => {
+            const correlation = request.app.tellann ?? {};
+            const startedAt = typeof correlation.startedAt === 'number' ? correlation.startedAt : Date.now();
+            void TELLANN_1.TELLANN.trackApi({
+                // The route table's pattern, so `/users/{id}` stays one endpoint.
+                endpoint: request.route?.path ?? request.path,
+                method: request.method?.toUpperCase?.() ?? 'GET',
+                statusCode: statusOf(request),
+                durationMs: Date.now() - startedAt,
+                sessionId: correlation.sessionId,
+                runId: correlation.runId,
+                traceId: correlation.traceId,
+            });
+            if (request.response?.isBoom) {
+                void TELLANN_1.TELLANN.captureError({
+                    error: request.response,
+                    sessionId: correlation.sessionId,
+                    runId: correlation.runId,
+                    traceId: correlation.traceId,
+                    eventType: 'SERVER_ERROR',
+                });
+            }
+            return h.continue;
+        });
+    },
+};

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

@@ -0,0 +1,27 @@
+/**
+ * Koa integration.
+ *
+ * Koa's types are described structurally rather than imported, so installing
+ * this SDK never drags `koa` and `@types/koa` into a project that does not use
+ * them. The shape used here is the stable part of Koa's context contract.
+ */
+export type TellannKoaContext = {
+    method: string;
+    path: string;
+    status: number;
+    /** Set by `koa-router`; the matched pattern rather than the concrete path. */
+    _matchedRoute?: string;
+    request: {
+        headers: Record<string, any>;
+    };
+    state: Record<string, any>;
+};
+export type TellannKoaMiddleware = (context: TellannKoaContext, next: () => Promise<any>) => Promise<void>;
+/**
+ * Track every request, and re-throw whatever the downstream middleware threw.
+ *
+ * The matched router pattern is preferred over `ctx.path`: reporting the
+ * concrete path would put identifiers from URLs into telemetry and would make
+ * every request to `/users/:id` a distinct endpoint.
+ */
+export declare function tellannKoaMiddleware(): TellannKoaMiddleware;

package/dist/integrations/koa/index.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tellannKoaMiddleware = tellannKoaMiddleware;
+const TELLANN_1 = require("../../core/TELLANN");
+const express_1 = require("../express");
+/**
+ * Track every request, and re-throw whatever the downstream middleware threw.
+ *
+ * The matched router pattern is preferred over `ctx.path`: reporting the
+ * concrete path would put identifiers from URLs into telemetry and would make
+ * every request to `/users/:id` a distinct endpoint.
+ */
+function tellannKoaMiddleware() {
+    return async (context, next) => {
+        const start = Date.now();
+        const correlation = (0, express_1.extractCorrelationContext)(context.request?.headers ?? {});
+        context.state.tellann = correlation;
+        try {
+            await next();
+        }
+        catch (error) {
+            await TELLANN_1.TELLANN.captureError({
+                error: error,
+                sessionId: correlation.sessionId,
+                runId: correlation.runId,
+                traceId: correlation.traceId,
+                eventType: 'SERVER_ERROR',
+            });
+            throw error;
+        }
+        finally {
+            await TELLANN_1.TELLANN.trackApi({
+                endpoint: context._matchedRoute ?? context.path,
+                method: context.method,
+                statusCode: context.status,
+                durationMs: Date.now() - start,
+                sessionId: correlation.sessionId,
+                runId: correlation.runId,
+                traceId: correlation.traceId,
+            });
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellann/backend-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Tellann server telemetry and QA-run correlation SDK",
   "license": "UNLICENSED",
   "main": "dist/index.js",

package/dist/core/SOTS.d.ts

@@ -1,39 +0,0 @@
-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

@@ -1,158 +0,0 @@
-"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();