@tellann/backend-sdk 0.1.0 → 0.3.0

package/dist/integrations/hapi/index.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tellannHapiPlugin = void 0;
+const TELLANN_1 = require("../../core/TELLANN");
+const express_1 = require("../express");
+const requestContext_1 = require("../../core/requestContext");
+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(),
+            };
+            // hapi extensions do not wrap the handler, so the context is bound to
+            // this execution rather than to a callback, and kept on the request for
+            // the response extension to read back.
+            request.app.tellannContext = (0, requestContext_1.enterRequestContext)({
+                ...(0, express_1.extractCorrelationContext)(request.headers ?? {}),
+                method: request.method?.toUpperCase?.() ?? 'GET',
+                route: request.route?.path ?? request.path,
+                dataAccess: [],
+            });
+            return h.continue;
+        });
+        server.ext('onPreResponse', (request, h) => {
+            const correlation = request.app.tellann ?? {};
+            const startedAt = typeof correlation.startedAt === 'number' ? correlation.startedAt : Date.now();
+            const context = request.app.tellannContext;
+            void TELLANN_1.TELLANN.trackApi({
+                endpoint: request.path,
+                // The route table's pattern, so `/users/{id}` stays one endpoint.
+                route: 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,
+                framework: 'hapi',
+                models: (0, requestContext_1.summarizeDataAccess)(context?.dataAccess ?? []),
+                query: request.query,
+                requestBody: request.payload,
+                // A Boom error's `source` is the error payload hapi will serialize.
+                responseBody: request.response?.isBoom ? undefined : request.response?.source,
+                requestHeaders: request.headers,
+                responseHeaders: request.response?.headers,
+            });
+            void TELLANN_1.TELLANN.flushDataAccess(context);
+            if (request.response?.isBoom) {
+                void TELLANN_1.TELLANN.captureError({
+                    error: request.response,
+                    sessionId: correlation.sessionId,
+                    runId: correlation.runId,
+                    traceId: correlation.traceId,
+                    eventType: 'SERVER_ERROR',
+                    route: request.route?.path ?? request.path,
+                    method: request.method?.toUpperCase?.() ?? 'GET',
+                    statusCode: statusOf(request),
+                });
+            }
+            return h.continue;
+        });
+    },
+};

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

@@ -0,0 +1,34 @@
+/**
+ * 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;
+    /** Present when a body parser is registered. */
+    body?: unknown;
+    query?: Record<string, unknown>;
+    request: {
+        headers: Record<string, any>;
+        body?: unknown;
+    };
+    response?: {
+        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,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tellannKoaMiddleware = tellannKoaMiddleware;
+const TELLANN_1 = require("../../core/TELLANN");
+const express_1 = require("../express");
+const requestContext_1 = require("../../core/requestContext");
+/**
+ * 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;
+        const tellannContext = {
+            ...correlation,
+            method: context.method,
+            route: context._matchedRoute ?? context.path,
+            dataAccess: [],
+        };
+        await (0, requestContext_1.runInRequestContext)(tellannContext, async () => {
+            try {
+                await next();
+            }
+            catch (error) {
+                await TELLANN_1.TELLANN.captureError({
+                    error: error,
+                    sessionId: correlation.sessionId,
+                    runId: correlation.runId,
+                    traceId: correlation.traceId,
+                    eventType: 'SERVER_ERROR',
+                    route: context._matchedRoute ?? context.path,
+                    method: context.method,
+                    statusCode: context.status,
+                });
+                throw error;
+            }
+            finally {
+                await TELLANN_1.TELLANN.trackApi({
+                    endpoint: context.path,
+                    // Read after `next`, by which point the router has matched.
+                    route: context._matchedRoute ?? context.path,
+                    method: context.method,
+                    statusCode: context.status,
+                    durationMs: Date.now() - start,
+                    sessionId: correlation.sessionId,
+                    runId: correlation.runId,
+                    traceId: correlation.traceId,
+                    framework: 'koa',
+                    models: (0, requestContext_1.summarizeDataAccess)(tellannContext.dataAccess),
+                    query: context.query,
+                    requestBody: context.request?.body,
+                    responseBody: context.body,
+                    requestHeaders: context.request?.headers,
+                    responseHeaders: context.response?.headers,
+                });
+                await TELLANN_1.TELLANN.flushDataAccess(tellannContext);
+            }
+        });
+    };
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Prisma integration.
+ *
+ * Prisma's types are described structurally rather than imported, so this SDK
+ * never pulls `@prisma/client` into a project that does not use it. Both of
+ * Prisma's interception points are supported because which one a project can
+ * use depends on its version: `$extends` on 4.16 and later, `$use` before it.
+ */
+export type TellannPrismaOperationArgs = {
+    model?: string | null;
+    operation: string;
+    args: unknown;
+    query: (args: unknown) => Promise<unknown>;
+};
+export type TellannPrismaMiddlewareParams = {
+    model?: string | null;
+    action: string;
+    args?: unknown;
+};
+/**
+ * A Prisma client extension that reports every query as a data-access event.
+ *
+ * Usage:
+ *   const prisma = new PrismaClient().$extends(tellannPrismaExtension());
+ *
+ * The extension reports the model and the operation, never the arguments: a
+ * `where` clause routinely contains the identifiers a QA run is required not
+ * to keep in the clear, and the request's own captured payload already says
+ * what was asked for.
+ */
+export declare function tellannPrismaExtension(): {
+    name: string;
+    query: {
+        $allModels: {
+            $allOperations({ model, operation, args, query }: TellannPrismaOperationArgs): Promise<unknown>;
+        };
+    };
+};
+/**
+ * The same reporting for Prisma clients older than 4.16, which have `$use`
+ * rather than `$extends`.
+ *
+ * Usage:
+ *   prisma.$use(tellannPrismaMiddleware());
+ */
+export declare function tellannPrismaMiddleware(): (params: TellannPrismaMiddlewareParams, next: (params: TellannPrismaMiddlewareParams) => Promise<unknown>) => Promise<unknown>;

package/dist/integrations/prisma/index.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tellannPrismaExtension = tellannPrismaExtension;
+exports.tellannPrismaMiddleware = tellannPrismaMiddleware;
+const TELLANN_1 = require("../../core/TELLANN");
+const trackDataAccess_1 = require("../../core/trackDataAccess");
+function recordCount(result) {
+    if (Array.isArray(result))
+        return result.length;
+    if (result && typeof result === 'object') {
+        const count = result.count;
+        if (typeof count === 'number')
+            return count;
+        return 1;
+    }
+    return result === null || result === undefined ? 0 : 1;
+}
+async function report(model, operation, startedAt, result) {
+    if (!model)
+        return;
+    await TELLANN_1.TELLANN.trackDataAccess({
+        model,
+        operation,
+        records: recordCount(result),
+        durationMs: Date.now() - startedAt,
+        mutation: (0, trackDataAccess_1.isMutationOperation)(operation),
+    }).catch(() => undefined);
+}
+/**
+ * A Prisma client extension that reports every query as a data-access event.
+ *
+ * Usage:
+ *   const prisma = new PrismaClient().$extends(tellannPrismaExtension());
+ *
+ * The extension reports the model and the operation, never the arguments: a
+ * `where` clause routinely contains the identifiers a QA run is required not
+ * to keep in the clear, and the request's own captured payload already says
+ * what was asked for.
+ */
+function tellannPrismaExtension() {
+    return {
+        name: 'tellann',
+        query: {
+            $allModels: {
+                async $allOperations({ model, operation, args, query }) {
+                    const startedAt = Date.now();
+                    const result = await query(args);
+                    void report(model, operation, startedAt, result);
+                    return result;
+                },
+            },
+        },
+    };
+}
+/**
+ * The same reporting for Prisma clients older than 4.16, which have `$use`
+ * rather than `$extends`.
+ *
+ * Usage:
+ *   prisma.$use(tellannPrismaMiddleware());
+ */
+function tellannPrismaMiddleware() {
+    return async (params, next) => {
+        const startedAt = Date.now();
+        const result = await next(params);
+        void report(params.model, params.action, startedAt, result);
+        return result;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellann/backend-sdk",
-  "version": "0.1.0",
+  "version": "0.3.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();