@tellann/backend-sdk 0.2.0 → 0.3.0

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

@@ -11,8 +11,15 @@ export type TellannKoaContext = {
     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>;
 };

package/dist/integrations/koa/index.js

@@ -3,6 +3,7 @@ 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.
  *
@@ -15,29 +16,50 @@ function tellannKoaMiddleware() {
         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,
-            });
-        }
+        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.2.0",
+  "version": "0.3.0",
   "description": "Tellann server telemetry and QA-run correlation SDK",
   "license": "UNLICENSED",
   "main": "dist/index.js",