@tellann/backend-sdk 0.1.0 → 0.3.0

package/dist/core/TELLANN.d.ts

@@ -1,7 +1,10 @@
 import { TrackApiOptions } from './trackApi';
 import { CaptureErrorOptions } from './captureError';
 import { TrackStateOptions } from './trackState';
+import { TrackDataAccessOptions } from './trackDataAccess';
+import type { TellannRequestContext } from './requestContext';
 import { BackendWorkflowTracker } from './workflowTracker';
+import type { TellannCaptureConfig } from './capture';
 import type { EventType } from '../event-types';
 export interface TellannBackendConfig {
     endpoint: string;
@@ -14,6 +17,12 @@ export interface TellannBackendConfig {
     traceId?: string;
     agentVersion?: string;
     instrumentationManifestVersion?: string;
+    /**
+     * What a captured request may carry. Bodies and headers are on by default so
+     * a QA run can show what was actually sent; credential-shaped fields are
+     * dropped here regardless, before anything leaves this process.
+     */
+    capture?: TellannCaptureConfig;
 }
 export declare class TELLANNBackend {
     private config;
@@ -24,6 +33,16 @@ export declare class TELLANNBackend {
     trackApi(options: TrackApiOptions): Promise<void>;
     captureError(options: CaptureErrorOptions): Promise<void>;
     trackState(options: TrackStateOptions): Promise<void>;
+    /**
+     * Reports one persistence operation, and attaches it to the request that is
+     * in flight so that request can say which models it touched.
+     */
+    trackDataAccess(options: TrackDataAccessOptions): Promise<void>;
+    /**
+     * Sends what a finished request touched, one event per model and operation.
+     * The framework integrations call this; applications rarely need to.
+     */
+    flushDataAccess(context: TellannRequestContext | undefined): Promise<void>;
     trackEvent(eventType: EventType, metadata?: Record<string, any>, sessionId?: string): Promise<void>;
     verifyInstallation(sessionId?: string): Promise<void>;
     startWorkflow(workflowName: string, sessionId?: string): string;

package/dist/core/TELLANN.js

@@ -4,6 +4,7 @@ exports.BackendWorkflowTracker = exports.TELLANN = exports.TELLANNBackend = void
 const trackApi_1 = require("./trackApi");
 const captureError_1 = require("./captureError");
 const trackState_1 = require("./trackState");
+const trackDataAccess_1 = require("./trackDataAccess");
 const workflowTracker_1 = require("./workflowTracker");
 Object.defineProperty(exports, "BackendWorkflowTracker", { enumerable: true, get: function () { return workflowTracker_1.BackendWorkflowTracker; } });
 const uuid_1 = require("uuid");
@@ -35,6 +36,24 @@ class TELLANNBackend {
             return;
         await (0, trackState_1.trackStateEvent)(this.config, options);
     }
+    /**
+     * Reports one persistence operation, and attaches it to the request that is
+     * in flight so that request can say which models it touched.
+     */
+    async trackDataAccess(options) {
+        if (!this.config)
+            return;
+        await (0, trackDataAccess_1.trackDataAccessEvent)(this.config, options);
+    }
+    /**
+     * Sends what a finished request touched, one event per model and operation.
+     * The framework integrations call this; applications rarely need to.
+     */
+    async flushDataAccess(context) {
+        if (!this.config)
+            return;
+        await (0, trackDataAccess_1.flushRequestDataAccess)(this.config, context);
+    }
     async trackEvent(eventType, metadata = {}, sessionId) {
         await this.sendEvent(eventType, sessionId, metadata);
     }

package/dist/core/capture.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What a captured request is allowed to carry out of the application process.
+ *
+ * Two independent protections apply to a QA run's payloads. This module is the
+ * first: anything that looks like a credential never leaves the server at all,
+ * and bodies are clipped so one large upload cannot push an event past the
+ * collector's size limit. The second lives in the desktop and the ingestion
+ * pipeline, which classify every remaining leaf and encrypt it at rest.
+ *
+ * Doing it here as well matters because the value would otherwise sit in a
+ * relay buffer, a spool file and a log line before the classifier ever sees it.
+ */
+export interface TellannCaptureConfig {
+    /** Capture request bodies. Default true. */
+    requestBody?: boolean;
+    /** Capture response bodies. Default true. */
+    responseBody?: boolean;
+    /** Capture the safe subset of request and response headers. Default true. */
+    headers?: boolean;
+    /** Per-body ceiling before clipping, in bytes. Default 8 KB. */
+    maxBodyBytes?: number;
+    /** Extra key names to drop, on top of the built-in credential list. */
+    redactKeys?: string[];
+}
+export type ResolvedCaptureConfig = Required<Omit<TellannCaptureConfig, 'redactKeys'>> & {
+    redactKeys: string[];
+};
+export declare function resolveCaptureConfig(config?: TellannCaptureConfig): ResolvedCaptureConfig;
+export declare function isSecretKey(key: string, extra?: string[]): boolean;
+/**
+ * Copies a payload, dropping credential-shaped fields and clipping the result.
+ *
+ * Returns `undefined` when there is nothing worth sending, so the caller can
+ * leave the field off the event entirely rather than send an empty object.
+ */
+export declare function sanitizePayload(value: unknown, capture: ResolvedCaptureConfig): unknown;
+/**
+ * Keeps a sanitized payload inside its byte budget.
+ *
+ * A body over budget is replaced by a description of itself rather than a
+ * half-serialized fragment: a truncated JSON string reads as corrupt data in
+ * the run, while "an object with these keys, this big" is still useful.
+ */
+export declare function clipToBudget(value: unknown, maxBytes: number): unknown;
+/** The safe subset of a header bag, with credential headers never included. */
+export declare function sanitizeHeaders(headers: Record<string, unknown> | undefined, capture: ResolvedCaptureConfig): Record<string, string> | undefined;
+/** Best-effort byte size of a payload, for the run's throughput totals. */
+export declare function payloadBytes(value: unknown): number | undefined;
+/** Parses a body the framework handed over as a raw string. */
+export declare function parseBody(raw: unknown, contentType?: string): unknown;

package/dist/core/capture.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * What a captured request is allowed to carry out of the application process.
+ *
+ * Two independent protections apply to a QA run's payloads. This module is the
+ * first: anything that looks like a credential never leaves the server at all,
+ * and bodies are clipped so one large upload cannot push an event past the
+ * collector's size limit. The second lives in the desktop and the ingestion
+ * pipeline, which classify every remaining leaf and encrypt it at rest.
+ *
+ * Doing it here as well matters because the value would otherwise sit in a
+ * relay buffer, a spool file and a log line before the classifier ever sees it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCaptureConfig = resolveCaptureConfig;
+exports.isSecretKey = isSecretKey;
+exports.sanitizePayload = sanitizePayload;
+exports.clipToBudget = clipToBudget;
+exports.sanitizeHeaders = sanitizeHeaders;
+exports.payloadBytes = payloadBytes;
+exports.parseBody = parseBody;
+const DEFAULT_MAX_BODY_BYTES = 8 * 1024;
+function resolveCaptureConfig(config) {
+    return {
+        requestBody: config?.requestBody ?? true,
+        responseBody: config?.responseBody ?? true,
+        headers: config?.headers ?? true,
+        maxBodyBytes: config?.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
+        redactKeys: (config?.redactKeys ?? []).map((key) => key.toLowerCase()),
+    };
+}
+/**
+ * Key names whose value is dropped outright.
+ *
+ * Token based rather than substring based: a plain substring test drops
+ * ordinary fields by accident (`profile` contains `file`, `company` contains
+ * `pan`), and a value dropped by mistake cannot be recovered from the run.
+ */
+const SECRET_TOKENS = new Set([
+    'password', 'passwd', 'passcode', 'passphrase', 'secret', 'token', 'jwt', 'bearer',
+    'authorization', 'cookie', 'cookies', 'cvv', 'cvc', 'pin', 'otp', 'credential',
+    'credentials', 'pan', 'salt', 'hash', 'signature',
+]);
+const SECRET_PHRASES = [
+    'cardnumber', 'cardnum', 'creditcard', 'debitcard', 'securitycode',
+    'sessionid', 'sessiontoken', 'sessionkey', 'privatekey', 'secretkey', 'apikey',
+    'accesstoken', 'refreshtoken', 'idtoken', 'clientsecret', 'setcookie',
+];
+/** Request and response headers worth keeping. Everything else is dropped. */
+const SAFE_HEADERS = new Set([
+    'accept', 'accept-encoding', 'accept-language', 'content-type', 'content-length',
+    'host', 'origin', 'referer', 'user-agent', 'x-request-id', 'x-requested-with',
+    'x-forwarded-proto', 'cache-control', 'etag', 'location', 'retry-after',
+]);
+function tokensOf(key) {
+    return key
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((token) => token.toLowerCase());
+}
+function isSecretKey(key, extra = []) {
+    const lower = key.toLowerCase();
+    if (extra.includes(lower))
+        return true;
+    const tokens = tokensOf(key);
+    if (tokens.some((token) => SECRET_TOKENS.has(token)))
+        return true;
+    const joined = tokens.join('');
+    return SECRET_PHRASES.some((phrase) => joined.includes(phrase));
+}
+/**
+ * Copies a payload, dropping credential-shaped fields and clipping the result.
+ *
+ * Returns `undefined` when there is nothing worth sending, so the caller can
+ * leave the field off the event entirely rather than send an empty object.
+ */
+function sanitizePayload(value, capture) {
+    if (value === undefined || value === null)
+        return undefined;
+    const visit = (child, key, depth) => {
+        if (depth > 8)
+            return '[TRUNCATED]';
+        if (child === null || typeof child === 'boolean' || typeof child === 'number')
+            return child;
+        if (typeof child === 'string') {
+            if (key && isSecretKey(key, capture.redactKeys))
+                return '[REDACTED]';
+            return child.length > 4_096 ? `${child.slice(0, 4_096)}…[TRUNCATED]` : child;
+        }
+        if (Array.isArray(child))
+            return child.slice(0, 100).map((item, index) => visit(item, `${key}.${index}`, depth + 1));
+        if (typeof child === 'object') {
+            if (Buffer.isBuffer(child))
+                return `[BINARY · ${child.length} bytes]`;
+            return Object.fromEntries(Object.entries(child).slice(0, 100).map(([childKey, item]) => [
+                childKey,
+                isSecretKey(childKey, capture.redactKeys) ? '[REDACTED]' : visit(item, childKey, depth + 1),
+            ]));
+        }
+        return String(child).slice(0, 2_000);
+    };
+    const sanitized = visit(value, '', 0);
+    return clipToBudget(sanitized, capture.maxBodyBytes);
+}
+/**
+ * Keeps a sanitized payload inside its byte budget.
+ *
+ * A body over budget is replaced by a description of itself rather than a
+ * half-serialized fragment: a truncated JSON string reads as corrupt data in
+ * the run, while "an object with these keys, this big" is still useful.
+ */
+function clipToBudget(value, maxBytes) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value) ?? '';
+    }
+    catch {
+        return '[UNSERIALIZABLE]';
+    }
+    if (Buffer.byteLength(serialized, 'utf8') <= maxBytes)
+        return value;
+    if (typeof value === 'string')
+        return `${value.slice(0, maxBytes)}…[TRUNCATED]`;
+    if (Array.isArray(value)) {
+        return { truncated: true, kind: 'array', length: value.length, bytes: Buffer.byteLength(serialized, 'utf8') };
+    }
+    if (value && typeof value === 'object') {
+        return {
+            truncated: true,
+            kind: 'object',
+            keys: Object.keys(value).slice(0, 50),
+            bytes: Buffer.byteLength(serialized, 'utf8'),
+        };
+    }
+    return '[TRUNCATED]';
+}
+/** The safe subset of a header bag, with credential headers never included. */
+function sanitizeHeaders(headers, capture) {
+    if (!capture.headers || !headers)
+        return undefined;
+    const entries = Object.entries(headers)
+        .filter(([key]) => SAFE_HEADERS.has(key.toLowerCase()) && !isSecretKey(key, capture.redactKeys))
+        .slice(0, 40)
+        .map(([key, value]) => [
+        key.toLowerCase(),
+        String(Array.isArray(value) ? value.join(', ') : value ?? '').slice(0, 500),
+    ]);
+    return entries.length ? Object.fromEntries(entries) : undefined;
+}
+/** Best-effort byte size of a payload, for the run's throughput totals. */
+function payloadBytes(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === 'string')
+        return Buffer.byteLength(value, 'utf8');
+    if (Buffer.isBuffer(value))
+        return value.length;
+    try {
+        return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parses a body the framework handed over as a raw string. */
+function parseBody(raw, contentType = '') {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'string')
+        return raw;
+    if (!raw)
+        return undefined;
+    if (/json/i.test(contentType) || /^[[{]/.test(raw.trim())) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    if (/application\/x-www-form-urlencoded/i.test(contentType)) {
+        return Object.fromEntries(new URLSearchParams(raw).entries());
+    }
+    return raw;
+}

package/dist/core/captureError.d.ts

@@ -7,5 +7,13 @@ export interface CaptureErrorOptions {
     eventType?: 'SERVER_ERROR' | 'ERROR_OCCURRED';
     runId?: string;
     traceId?: string;
+    /**
+     * The route the error came from. Reported alongside the error rather than
+     * only inside `context`, because a QA run groups server errors by route and
+     * cannot go looking for it in a free-form bag.
+     */
+    route?: string;
+    method?: string;
+    statusCode?: number;
 }
 export declare function captureErrorEvent(config: TellannBackendConfig, options: CaptureErrorOptions): Promise<void>;

package/dist/core/captureError.js

@@ -2,17 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.captureErrorEvent = captureErrorEvent;
 const uuid_1 = require("uuid");
+const requestContext_1 = require("./requestContext");
+const qaEvidence_1 = require("./qaEvidence");
 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 requestContext = (0, requestContext_1.currentRequestContext)();
     const event = {
         eventId: (0, uuid_1.v4)(),
-        sessionId: options.sessionId ?? config.sessionId ?? (0, uuid_1.v4)(),
+        sessionId: options.sessionId ?? requestContext?.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,
+        runId: options.runId ?? requestContext?.runId ?? config.runId ?? null,
+        traceId: options.traceId ?? requestContext?.traceId ?? config.traceId ?? null,
         agentVersion: config.agentVersion ?? null,
         instrumentationManifestVersion: config.instrumentationManifestVersion ?? null,
         source: 'backend-sdk',
@@ -23,6 +26,9 @@ async function captureErrorEvent(config, options) {
             message: err.message,
             stack: err.stack ?? null,
             name: err.name,
+            route: options.route ?? requestContext?.route ?? null,
+            method: options.method ?? requestContext?.method ?? null,
+            statusCode: options.statusCode ?? null,
             context: options.context ?? {},
         },
     };
@@ -47,10 +53,10 @@ async function captureErrorEvent(config, options) {
         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;
+        if (event.runId)
+            headers['x-tellann-run-id'] = event.runId;
+        if (event.traceId)
+            headers['x-tellann-trace-id'] = event.traceId;
         await fetch(`${config.endpoint}/v1/events`, {
             method: 'POST',
             headers,
@@ -60,4 +66,10 @@ async function captureErrorEvent(config, options) {
     catch {
         // Silently swallow
     }
+    await (0, qaEvidence_1.postQaEvidence)(config, {
+        eventType: 'QA_BACKEND_ERROR',
+        metadata: event.metadata,
+        traceId: event.traceId,
+        runId: event.runId,
+    });
 }

package/dist/core/qaEvidence.d.ts

@@ -0,0 +1,31 @@
+import type { TellannBackendConfig } from './TELLANN';
+/**
+ * The desktop app's local relay only ever binds to loopback (see
+ * `LocalRunRelay.start`), so an endpoint pointed anywhere else is the
+ * standing, environment-scoped gateway a deployed server is configured with
+ * once and never has to change per run.
+ */
+export declare function isLocalRelayEndpoint(endpoint: string): boolean;
+export declare function nextEvidenceEnvelope(): {
+    sessionId: string;
+    localSequence: number;
+};
+export interface QaEvidencePost {
+    eventType: 'QA_BACKEND_REQUEST' | 'QA_BACKEND_ERROR' | 'QA_BACKEND_DATA_ACCESS';
+    metadata: Record<string, unknown>;
+    traceId?: string | null;
+    runId?: string | null;
+}
+/**
+ * Posts one backend evidence event through the environment's standing
+ * ingestion key rather than a credential scoped to a single run.
+ *
+ * Which run this lands on is resolved server-side, against whichever run is
+ * currently recording for this environment — see
+ * `POST /environments/:environmentId/qa-evidence/batch` in onboarding-api.
+ * Silently a no-op when the config carries no `apiKey`/`environmentId`
+ * (nothing configured to post through) or when the endpoint is the desktop's
+ * own local relay (which already carries backend evidence its own way, over
+ * `/v1/events`).
+ */
+export declare function postQaEvidence(config: TellannBackendConfig, input: QaEvidencePost): Promise<void>;

package/dist/core/qaEvidence.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLocalRelayEndpoint = isLocalRelayEndpoint;
+exports.nextEvidenceEnvelope = nextEvidenceEnvelope;
+exports.postQaEvidence = postQaEvidence;
+const uuid_1 = require("uuid");
+/**
+ * The desktop app's local relay only ever binds to loopback (see
+ * `LocalRunRelay.start`), so an endpoint pointed anywhere else is the
+ * standing, environment-scoped gateway a deployed server is configured with
+ * once and never has to change per run.
+ */
+function isLocalRelayEndpoint(endpoint) {
+    try {
+        return new URL(endpoint).hostname === '127.0.0.1';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One evidence session per process, not per event.
+ *
+ * `QAEvidenceEventSchema` groups events by `(sessionId, localSequence)` the
+ * same way the desktop's own recorder does; a process that lives for the
+ * lifetime of a request or a worker keeps one sequence for as long as it
+ * runs, so `localSequence` only has to be unique within that lifetime.
+ */
+let evidenceSessionId = null;
+let evidenceSequence = 0;
+function nextEvidenceEnvelope() {
+    if (!evidenceSessionId)
+        evidenceSessionId = (0, uuid_1.v4)();
+    evidenceSequence += 1;
+    return { sessionId: evidenceSessionId, localSequence: evidenceSequence };
+}
+/**
+ * Posts one backend evidence event through the environment's standing
+ * ingestion key rather than a credential scoped to a single run.
+ *
+ * Which run this lands on is resolved server-side, against whichever run is
+ * currently recording for this environment — see
+ * `POST /environments/:environmentId/qa-evidence/batch` in onboarding-api.
+ * Silently a no-op when the config carries no `apiKey`/`environmentId`
+ * (nothing configured to post through) or when the endpoint is the desktop's
+ * own local relay (which already carries backend evidence its own way, over
+ * `/v1/events`).
+ */
+async function postQaEvidence(config, input) {
+    if (!config.apiKey || !config.environmentId || isLocalRelayEndpoint(config.endpoint))
+        return;
+    const envelope = nextEvidenceEnvelope();
+    const event = {
+        schemaVersion: '2.0',
+        eventId: (0, uuid_1.v4)(),
+        sessionId: envelope.sessionId,
+        traceId: input.traceId ?? config.traceId ?? null,
+        applicationId: config.applicationId,
+        environmentId: config.environmentId,
+        localSequence: envelope.localSequence,
+        timestamp: new Date().toISOString(),
+        eventType: input.eventType,
+        source: 'BACKEND_SDK',
+        scope: 'PRE_BOUNDARY',
+        metadata: input.metadata,
+        protectedValues: [],
+        ...(input.runId ?? config.runId ? { runId: input.runId ?? config.runId } : {}),
+    };
+    try {
+        await fetch(`${config.endpoint}/environments/${config.environmentId}/qa-evidence/batch`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${config.apiKey}` },
+            body: JSON.stringify({ events: [event] }),
+        });
+    }
+    catch {
+        // Telemetry never fails the operation it describes.
+    }
+}

package/dist/core/requestContext.d.ts

@@ -0,0 +1,49 @@
+/**
+ * One persistence operation observed while a request was in flight.
+ */
+export interface TellannDataAccess {
+    model: string;
+    operation: string;
+    records?: number | null;
+    durationMs?: number | null;
+    mutation?: boolean;
+}
+export interface TellannRequestContext {
+    sessionId?: string;
+    runId?: string;
+    traceId?: string;
+    method?: string;
+    route?: string;
+    /** Filled in as the request runs, then attached to its API_REQUEST event. */
+    dataAccess: TellannDataAccess[];
+}
+export declare function runInRequestContext<T>(context: TellannRequestContext, callback: () => T): T;
+export declare function currentRequestContext(): TellannRequestContext | undefined;
+/**
+ * Enters a context without a callback to wrap.
+ *
+ * Koa and Express middleware wrap what comes after them, so they can use
+ * `runInRequestContext`. Fastify and hapi hooks do not: they run, return, and
+ * the framework carries on by itself. `enterWith` binds the context to the
+ * current asynchronous execution instead, which is how those hooks reach the
+ * handlers the framework runs after them.
+ */
+export declare function enterRequestContext(context: TellannRequestContext): TellannRequestContext;
+/** Records one operation against the in-flight request, if there is one. */
+export declare function recordDataAccess(access: TellannDataAccess): TellannRequestContext | undefined;
+/**
+ * The models a request touched, collapsed to one entry per model and
+ * operation, with the record counts summed and the operations counted.
+ *
+ * Collapsing matters: a request that reads one model in a loop produces
+ * thousands of entries, and reporting each one would flood the run with rows
+ * that all say the same thing. The count keeps the volume visible without the
+ * noise.
+ */
+export declare function summarizeDataAccess(entries: TellannDataAccess[]): Array<{
+    model: string;
+    operation: string;
+    records: number | null;
+    count: number;
+    mutation: boolean;
+}>;

package/dist/core/requestContext.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInRequestContext = runInRequestContext;
+exports.currentRequestContext = currentRequestContext;
+exports.enterRequestContext = enterRequestContext;
+exports.recordDataAccess = recordDataAccess;
+exports.summarizeDataAccess = summarizeDataAccess;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * Ties a persistence operation to the request that caused it.
+ *
+ * `AsyncLocalStorage` is what makes "which models did this endpoint touch"
+ * answerable without the application passing a context object down through
+ * every layer: the integration opens a store per request, and an ORM hook
+ * anywhere below it lands in the same store no matter how many awaits deep it
+ * is. Work that escapes the request - a queued job, a detached promise - lands
+ * in no store at all and is reported without a route, which is correct: it did
+ * not belong to that request.
+ */
+const storage = new node_async_hooks_1.AsyncLocalStorage();
+function runInRequestContext(context, callback) {
+    return storage.run(context, callback);
+}
+function currentRequestContext() {
+    return storage.getStore();
+}
+/**
+ * Enters a context without a callback to wrap.
+ *
+ * Koa and Express middleware wrap what comes after them, so they can use
+ * `runInRequestContext`. Fastify and hapi hooks do not: they run, return, and
+ * the framework carries on by itself. `enterWith` binds the context to the
+ * current asynchronous execution instead, which is how those hooks reach the
+ * handlers the framework runs after them.
+ */
+function enterRequestContext(context) {
+    storage.enterWith(context);
+    return context;
+}
+/** Records one operation against the in-flight request, if there is one. */
+function recordDataAccess(access) {
+    const context = storage.getStore();
+    if (!context)
+        return undefined;
+    // A request in a loop can touch one model thousands of times; the run needs
+    // the shape of what happened, not an unbounded list.
+    if (context.dataAccess.length < 200)
+        context.dataAccess.push(access);
+    return context;
+}
+/**
+ * The models a request touched, collapsed to one entry per model and
+ * operation, with the record counts summed and the operations counted.
+ *
+ * Collapsing matters: a request that reads one model in a loop produces
+ * thousands of entries, and reporting each one would flood the run with rows
+ * that all say the same thing. The count keeps the volume visible without the
+ * noise.
+ */
+function summarizeDataAccess(entries) {
+    const totals = new Map();
+    for (const entry of entries) {
+        const key = `${entry.model}:${entry.operation}`;
+        const existing = totals.get(key);
+        if (!existing) {
+            totals.set(key, {
+                model: entry.model,
+                operation: entry.operation,
+                records: entry.records ?? null,
+                count: 1,
+                mutation: Boolean(entry.mutation),
+            });
+            continue;
+        }
+        existing.count += 1;
+        if (entry.records != null)
+            existing.records = (existing.records ?? 0) + entry.records;
+    }
+    return [...totals.values()].slice(0, 50);
+}

package/dist/core/trackApi.d.ts

@@ -1,14 +1,39 @@
 import { TellannBackendConfig } from './TELLANN';
 export interface TrackApiOptions {
+    /** The concrete path the client called. */
     endpoint: string;
     method: string;
     statusCode: number;
     durationMs: number;
+    /**
+     * The route template the framework matched, e.g. `/orders/:id`. Supplying it
+     * is what keeps a thousand calls to `/orders/17` from reading as a thousand
+     * distinct endpoints, and keeps identifiers out of the grouping key.
+     */
+    route?: string;
     /** Optional: correlate with a frontend session via X-TELLANN-Session-ID header */
     sessionId?: string;
     /** Optional: idempotency / tracing */
     requestId?: string;
     runId?: string;
     traceId?: string;
+    /** Parsed query parameters. Credential-shaped keys are dropped. */
+    query?: Record<string, unknown>;
+    requestBody?: unknown;
+    responseBody?: unknown;
+    requestHeaders?: Record<string, unknown>;
+    responseHeaders?: Record<string, unknown>;
+    /** The function or controller that served the request, where it is known. */
+    handler?: string;
+    framework?: string;
+    /**
+     * Models this request touched. Left unset, it is taken from whatever the
+     * data-access hooks recorded while the request was in flight.
+     */
+    models?: Array<{
+        model: string;
+        operation?: string;
+        records?: number | null;
+    }>;
 }
 export declare function trackApiEvent(config: TellannBackendConfig, options: TrackApiOptions): Promise<void>;