@adonis-agora/telescope 0.11.0 → 0.13.0

package/dist/src/request_watcher.d.ts

@@ -12,6 +12,16 @@ export interface RequestEntryContent {
     durationMs: number;
     /** The active trace id at request time, or `null`. */
     traceId: string | null;
+    /**
+     * Host-supplied context for this request, from the {@link RequestEnrichment}
+     * hook — e.g. which front-end screen issued the call. Absent when no hook is
+     * configured or it returned nothing.
+     *
+     * Declared BEFORE `body` on purpose: the recorder's content-byte budget drops
+     * keys in insertion order, and a captured body is the field that can be
+     * megabytes. A few short context fields must not be the ones starved out.
+     */
+    context?: Record<string, unknown>;
     /**
      * Captured request body — present ONLY when the request exposes a body and it
      * passed the {@link RequestCaptureOptions} gates. A gated-out body is a marker
@@ -20,9 +30,10 @@ export interface RequestEntryContent {
      */
     body?: unknown;
     /**
-     * The authenticated user at request time, when the host exposes `ctx.auth.user`
-     * (Adonis @adonisjs/auth / authkit guard). Only `id` and `email` are captured —
-     * never the full model. `null` when unauthenticated or not exposed.
+     * The authenticated user at request time, from `ctx.auth.user` or — when the
+     * host's guard is async and publishes it instead — the `@adonis-agora/context`
+     * `userRef()` (see {@link resolveRequestUser}). Only `id` and `email` are
+     * captured, never the full model. `null` when unauthenticated or not exposed.
      */
     user: {
         id: string;
@@ -79,6 +90,55 @@ export interface ResolvedRequestCapture {
 }
 /** Apply the requestCapture defaults to a (possibly partial) config. */
 export declare function resolveRequestCapture(options: RequestCaptureOptions | undefined): ResolvedRequestCapture;
+/** Cap on host-supplied tags per entry — a buggy hook can't bloat the entry. */
+export declare const MAX_ENRICHMENT_TAGS = 16;
+/** Cap on the length of a single host-supplied tag. */
+export declare const MAX_ENRICHMENT_TAG_LENGTH = 128;
+/**
+ * What a {@link RequestEnrichment} hook may contribute to a `request` entry.
+ * Every field is optional; returning `undefined` (or nothing) enriches nothing.
+ */
+export interface RequestEnrichmentResult {
+    /**
+     * Extra tags, appended to the ones the watcher derives. Tags are how the
+     * dashboard filters, so this is the field to use for anything you want to slice
+     * by — `screen:researcher/dashboard_page`, `tenant:acme`, `feature-flag:new-nav`.
+     * Capped at {@link MAX_ENRICHMENT_TAGS} tags of {@link MAX_ENRICHMENT_TAG_LENGTH}
+     * characters; non-strings and blanks are dropped.
+     */
+    tags?: string[];
+    /**
+     * The authenticated user, for hosts where neither `ctx.auth.user` nor the
+     * `@adonis-agora/context` `userRef()` applies. Wins over both when returned.
+     */
+    user?: {
+        id: string;
+        email?: string;
+    } | null;
+    /**
+     * Free-form fields recorded under `content.context`. Use for detail you want to
+     * READ on the entry but not filter by; anything you want to filter by belongs
+     * in `tags`.
+     */
+    context?: Record<string, unknown>;
+}
+/**
+ * Host hook that enriches a `request` entry with information only the app has.
+ *
+ * The motivating case: correlating a front-end screen with the calls it makes.
+ * The browser sends the current page in a header, and this hook turns it into a
+ * `screen:<name>` tag — after which the dashboard can answer "which requests came
+ * from the writing screen?" with its existing tag filter.
+ *
+ * SYNCHRONOUS on purpose. It runs on the recording path of every request, so an
+ * `await` here (a DB lookup for the user, say) would put host I/O between the
+ * response and the next request. Read what is already on the `ctx` — headers,
+ * route, a guard's resolved state — and return.
+ *
+ * A throw is swallowed: enrichment is never a reason to lose an entry, let alone
+ * to break the request being observed.
+ */
+export type RequestEnrichment = (ctx: HttpContextLike) => RequestEnrichmentResult | undefined;
 /** The minimal slice of an Adonis HttpContext the watcher reads. */
 export interface RequestLike {
     method(): string;
@@ -88,9 +148,23 @@ export interface RequestLike {
     /** A single request header by (case-insensitive) name, when exposed. */
     header?(name: string): string | string[] | number | undefined;
 }
+/**
+ * The minimal slice of a response the watcher reads.
+ *
+ * BOTH accessors are optional because hosts disagree on which they expose:
+ * AdonisJS's `Response` has ONLY `getStatus()` (its `statusCode` lives on the
+ * wrapped Node `ServerResponse`, one level down), while a Node/Express-style
+ * response — and every stub in this repo's tests — exposes `statusCode`. Reading
+ * just one silently yields `null` on half the hosts, which is how the status went
+ * missing on every real Adonis request for so long: `statusCode?: number` is
+ * satisfied by any object, so the type system had nothing to say about it.
+ */
 export interface ResponseLike {
     response: {
+        /** Node/Express-style status property. */
         statusCode?: number;
+        /** AdonisJS `Response.getStatus()` — the only status accessor Adonis exposes. */
+        getStatus?(): number;
     };
 }
 export interface HttpContextLike {
@@ -115,18 +189,47 @@ export interface RecordRequestOptions {
      */
     capture?: RequestCaptureOptions;
     /**
-     * Override the user resolved from `ctx.auth`; pass `null` to force "no user".
-     * Omit to resolve from the context (default).
+     * Override the resolved user; pass `null` to force "no user". Omit to resolve
+     * from the enrichment hook, then `ctx.auth`, then the context accessor
+     * (see {@link resolveRequestUser}).
      */
     user?: {
         id: string;
         email?: string;
     } | null;
+    /**
+     * Host hook contributing tags / user / context to the entry. See
+     * {@link RequestEnrichment}. Omit for the pre-existing behavior.
+     */
+    enrich?: RequestEnrichment;
 }
 /**
- * Read the authenticated user off a (possibly absent) `ctx.auth`, extracting only
- * `id` + `email`. Strictly defensive: any throw or malformed shape yields `null`,
- * so a hostile/odd auth model can never break (or crash) request capture.
+ * The response status, or `null` when it genuinely cannot be determined.
+ *
+ * Tries `getStatus()` FIRST — it is what AdonisJS exposes, and an Adonis
+ * `Response` has no `statusCode` of its own — then the Node/Express-style
+ * `statusCode` property. Defensive throughout: a throwing accessor or a
+ * non-finite result yields `null` rather than breaking request capture.
+ */
+export declare function resolveResponseStatus(response: HttpContextLike['response']): number | null;
+/**
+ * The authenticated user for the entry, extracting only `id` + `email` — never the
+ * full model. Two sources, in order:
+ *
+ *  1. `ctx.auth.user` — the `@adonisjs/auth` convention: a SYNCHRONOUS property,
+ *     populated once the guard has authenticated.
+ *  2. `userRef()` from the `@adonis-agora/context` accessor — the Agora
+ *     convention, where the guard is async (`getUser()`/`getIdentity()`) and the
+ *     host publishes the resolved reference into the request context instead.
+ *
+ * The fallback is what makes attribution work at all on an Agora stack: an auth
+ * lib with no synchronous `user` property leaves (1) permanently `undefined`, so
+ * every request entry recorded `user: null` even for a fully authenticated
+ * session. Reading (2) costs one property read and is skipped entirely when
+ * `@adonis-agora/context` is not installed.
+ *
+ * Strictly defensive: any throw or malformed shape yields `null`, so a hostile or
+ * odd auth model can never break (or crash) request capture.
  */
 export declare function resolveRequestUser(ctx: HttpContextLike): {
     id: string;

package/dist/src/request_watcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request_watcher.d.ts","sourceRoot":"","sources":["../../src/request_watcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"request_watcher.d.ts","sourceRoot":"","sources":["../../src/request_watcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAA+B,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7C;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,SAAU,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,+BAA+B,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAIvE,CAAC;AAEF,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,4DAA4D;IAC5D,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC9B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC;CACrD;AAED,iEAAiE;AACjE,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7B,oBAAoB,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1C,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CAClE;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,sBAAsB,CAMxB;AAED,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,uDAAuD;AACvD,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7C;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,eAAe,KAAK,uBAAuB,GAAG,SAAS,CAAC;AAE9F,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,MAAM,IAAI,MAAM,CAAC;IACjB,GAAG,IAAI,MAAM,CAAC;IACd,0DAA0D;IAC1D,IAAI,CAAC,IAAI,OAAO,CAAC;IACjB,wEAAwE;IACxE,MAAM,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAAC;CAC/D;AACD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE;QACR,0CAA0C;QAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,iFAAiF;QACjF,SAAS,CAAC,IAAI,MAAM,CAAC;KACtB,CAAC;CACH;AACD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;IACnC,2EAA2E;IAC3E,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC3B;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC;;;;OAIG;IACH,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7C;;;OAGG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAwED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,IAAI,CAU1F;AAeD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAY9F;AAqDD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAmDrC"}

package/dist/src/request_watcher.js

@@ -1,3 +1,4 @@
+import { currentUserRef } from './context_accessor.js';
 import { EntryType } from './entry.js';
 /**
  * Default `requestCapture.maxBodyBytes`: bodies over 128 KiB are not captured.
@@ -22,6 +23,10 @@ export function resolveRequestCapture(options) {
         skipBody: options?.skipBody,
     };
 }
+/** Cap on host-supplied tags per entry — a buggy hook can't bloat the entry. */
+export const MAX_ENRICHMENT_TAGS = 16;
+/** Cap on the length of a single host-supplied tag. */
+export const MAX_ENRICHMENT_TAG_LENGTH = 128;
 /** First string value of a header read via the platform accessor. */
 function headerString(request, name) {
     const value = request.header?.(name);
@@ -93,29 +98,111 @@ function gateRequestBody(request, capture) {
     return body;
 }
 /**
- * Read the authenticated user off a (possibly absent) `ctx.auth`, extracting only
- * `id` + `email`. Strictly defensive: any throw or malformed shape yields `null`,
- * so a hostile/odd auth model can never break (or crash) request capture.
+ * The response status, or `null` when it genuinely cannot be determined.
+ *
+ * Tries `getStatus()` FIRST — it is what AdonisJS exposes, and an Adonis
+ * `Response` has no `statusCode` of its own — then the Node/Express-style
+ * `statusCode` property. Defensive throughout: a throwing accessor or a
+ * non-finite result yields `null` rather than breaking request capture.
+ */
+export function resolveResponseStatus(response) {
+    try {
+        if (typeof response.getStatus === 'function') {
+            const status = response.getStatus();
+            if (typeof status === 'number' && Number.isFinite(status))
+                return status;
+        }
+    }
+    catch {
+        // A throwing accessor is not a reason to lose the whole entry — fall through.
+    }
+    return typeof response.statusCode === 'number' ? response.statusCode : null;
+}
+/** Narrow an arbitrary user-ish value to the `{ id, email? }` slice we record. */
+function userSlice(value) {
+    if (value === null || value === undefined)
+        return null;
+    const record = value;
+    const id = record.id;
+    if (typeof id !== 'string' && typeof id !== 'number')
+        return null;
+    const email = record.email;
+    return {
+        id: String(id),
+        ...(typeof email === 'string' && email.length > 0 ? { email } : {}),
+    };
+}
+/**
+ * The authenticated user for the entry, extracting only `id` + `email` — never the
+ * full model. Two sources, in order:
+ *
+ *  1. `ctx.auth.user` — the `@adonisjs/auth` convention: a SYNCHRONOUS property,
+ *     populated once the guard has authenticated.
+ *  2. `userRef()` from the `@adonis-agora/context` accessor — the Agora
+ *     convention, where the guard is async (`getUser()`/`getIdentity()`) and the
+ *     host publishes the resolved reference into the request context instead.
+ *
+ * The fallback is what makes attribution work at all on an Agora stack: an auth
+ * lib with no synchronous `user` property leaves (1) permanently `undefined`, so
+ * every request entry recorded `user: null` even for a fully authenticated
+ * session. Reading (2) costs one property read and is skipped entirely when
+ * `@adonis-agora/context` is not installed.
+ *
+ * Strictly defensive: any throw or malformed shape yields `null`, so a hostile or
+ * odd auth model can never break (or crash) request capture.
  */
 export function resolveRequestUser(ctx) {
     try {
-        const user = ctx.auth?.user;
-        if (user === null || user === undefined)
-            return null;
-        const record = user;
-        const id = record.id;
-        if (typeof id !== 'string' && typeof id !== 'number')
-            return null;
-        const email = record.email;
-        return {
-            id: String(id),
-            ...(typeof email === 'string' && email.length > 0 ? { email } : {}),
-        };
+        const fromGuard = userSlice(ctx.auth?.user);
+        if (fromGuard !== null)
+            return fromGuard;
+    }
+    catch {
+        // Fall through to the context — a broken guard must not cost us the fallback.
+    }
+    try {
+        return userSlice(currentUserRef());
     }
     catch {
         return null;
     }
 }
+/**
+ * Run the host's enrichment hook defensively and normalize what it returned.
+ *
+ * Everything here is "never let the host break the entry": a throwing hook, a
+ * hook returning garbage, a hook returning a thousand tags — all degrade to
+ * recording what we would have recorded anyway. Tags are filtered to non-empty
+ * strings, trimmed to {@link MAX_ENRICHMENT_TAG_LENGTH}, and capped at
+ * {@link MAX_ENRICHMENT_TAGS}.
+ */
+function runEnrichment(enrich, ctx) {
+    if (enrich === undefined)
+        return { tags: [] };
+    let result;
+    try {
+        result = enrich(ctx);
+    }
+    catch {
+        return { tags: [] };
+    }
+    if (result === null || typeof result !== 'object')
+        return { tags: [] };
+    const tags = Array.isArray(result.tags)
+        ? result.tags
+            .filter((tag) => typeof tag === 'string' && tag.length > 0)
+            .slice(0, MAX_ENRICHMENT_TAGS)
+            .map((tag) => tag.length > MAX_ENRICHMENT_TAG_LENGTH ? tag.slice(0, MAX_ENRICHMENT_TAG_LENGTH) : tag)
+        : [];
+    const context = result.context !== null && typeof result.context === 'object' && !Array.isArray(result.context)
+        ? result.context
+        : undefined;
+    return {
+        tags,
+        ...(result.user !== undefined ? { user: userSlice(result.user) } : {}),
+        ...(context !== undefined ? { context } : {}),
+    };
+}
 /**
  * The pure, framework-agnostic core of the HTTP request watcher: build a
  * `request` {@link RecordInput} from a (stubbable) HttpContext-like value and a
@@ -125,9 +212,16 @@ export function resolveRequestUser(ctx) {
 export async function recordRequest(store, ctx, startedAt, options = {}) {
     const method = String(ctx.request.method()).toUpperCase();
     const url = stripQuery(ctx.request.url());
-    const status = typeof ctx.response.statusCode === 'number' ? ctx.response.statusCode : null;
+    const status = resolveResponseStatus(ctx.response);
     const durationMs = options.durationMs ?? Math.max(0, Date.now() - startedAt);
-    const user = options.user === undefined ? resolveRequestUser(ctx) : options.user;
+    const enrichment = runEnrichment(options.enrich, ctx);
+    // Precedence: an explicit `options.user` (a caller that already knows) beats the
+    // host hook, which beats what we can read off the ctx.
+    const user = options.user !== undefined
+        ? options.user
+        : enrichment.user !== undefined
+            ? enrichment.user
+            : resolveRequestUser(ctx);
     // Body capture (gated). Only when the caller opted in AND the request exposes a
     // body accessor. The gate runs HERE — before the store's synchronous redaction
     // walk — so a huge/binary body is replaced by a marker and never walked; a body
@@ -144,6 +238,7 @@ export async function recordRequest(store, ctx, startedAt, options = {}) {
             durationMs,
             traceId: options.traceId ?? null,
             user,
+            ...(enrichment.context !== undefined ? { context: enrichment.context } : {}),
             ...(captureBody !== undefined ? { body: captureBody } : {}),
         },
         durationMs,
@@ -152,6 +247,7 @@ export async function recordRequest(store, ctx, startedAt, options = {}) {
             `method:${method}`,
             ...(status !== null ? [`status:${status}`] : []),
             ...(user?.id ? [`user:${user.id}`] : []),
+            ...enrichment.tags,
         ],
         ...(options.traceId !== undefined ? { traceId: options.traceId } : {}),
     };

package/dist/src/request_watcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"request_watcher.js","sourceRoot":"","sources":["../../src/request_watcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"request_watcher.js","sourceRoot":"","sources":["../../src/request_watcher.ts"],"names":[],"mappings":"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"}

package/dist/src/telescope_middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telescope_middleware.d.ts","sourceRoot":"","sources":["../../src/telescope_middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAwBxD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAmB;IAChC,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,gBA0D1C;CACF"}
+{"version":3,"file":"telescope_middleware.d.ts","sourceRoot":"","sources":["../../src/telescope_middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAwBxD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAmB;IAChC,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,gBA4D1C;CACF"}

package/dist/src/telescope_middleware.js

@@ -70,6 +70,8 @@ export default class TelescopeMiddleware {
                     // Body capture is opt-in: only pass `capture` when configured, so the
                     // default stays "no body field" and zero body-read overhead.
                     ...(runtime.requestCapture !== null ? { capture: runtime.requestCapture } : {}),
+                    // Host enrichment (screen tag, tenant, …). Absent unless configured.
+                    ...(runtime.requestEnrichment !== null ? { enrich: runtime.requestEnrichment } : {}),
                 });
             }
             catch {

package/dist/src/telescope_middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"telescope_middleware.js","sourceRoot":"","sources":["../../src/telescope_middleware.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAwB,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAU3E;;;8FAG8F;AAC9F,SAAS,YAAY,CAAC,GAAoB;IACxC,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;IACpC,MAAM,OAAO,GAAI,GAAsC,CAAC,KAAK,EAAE,OAAO,CAAC;IACvE,OAAO,GAAG,MAAM,IAAI,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAmB;IACtC,KAAK,CAAC,MAAM,CAAC,GAAgB,EAAE,IAAY;QACzC,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;QACtC,gFAAgF;QAChF,gFAAgF;QAChF,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,qBAAqB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACvE,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAE5B,8FAA8F;QAC9F,oFAAoF;QACpF,sFAAsF;QACtF,yFAAyF;QACzF,oEAAoE;QACpE,MAAM,OAAO,GAAG,GAAiC,CAAC;QAClD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACjE,MAAM,OAAO,GACX,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,aAAa,CAAC,KAAK,CAAC;YACzD,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC;YAClC,CAAC,CAAC,IAAI,CAAC;QAEX,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,0EAA0E;YAC1E,mEAAmE;YACnE,IAAI,CAAC;gBACH,MAAM,OAAO,GAAI,GAAkC,CAAC,OAAO,CAAC;gBAC5D,MAAM,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE;oBACzC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;oBACxB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;iBACnB,CAAC,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,0DAA0D;YAC5D,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,0EAA0E;YAC1E,qEAAqE;YACrE,uEAAuE;YACvE,IAAI,CAAC;gBACH,MAAM,aAAa,CAAC,KAAK,EAAE,GAAiC,EAAE,SAAS,EAAE;oBACvE,sEAAsE;oBACtE,6DAA6D;oBAC7D,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAChF,CAAC,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,0DAA0D;YAC5D,CAAC;YACD,uEAAuE;YACvE,4EAA4E;YAC5E,qEAAqE;YACrE,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,KAAK,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"telescope_middleware.js","sourceRoot":"","sources":["../../src/telescope_middleware.ts"],"names":[],"mappings":"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"}

package/dist/src/ui/index.d.ts

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export declare const VERSION = "0.11.0";
+export declare const VERSION = "0.13.0";
 export type { AccessDeniedInfo, AccessDeniedPageOptions, AccessDeniedReason, } from './access_denied_page.js';
 export { CONSOLE as ACCESS_DENIED_CONSOLE, escapeHtml, renderAccessDeniedPage, resolveAccessDeniedPage, } from './access_denied_page.js';
 export type { EntrySummary, RetentionInfo, RetentionOptions, RetentionPruneOptions, RetentionSamplingRate, } from './api.js';

package/dist/src/ui/index.js

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export const VERSION = '0.11.0';
+export const VERSION = '0.13.0';
 // — the built-in "access denied" page (what a browser sees on a refused page navigation) —
 export { CONSOLE as ACCESS_DENIED_CONSOLE, escapeHtml, renderAccessDeniedPage, resolveAccessDeniedPage, } from './access_denied_page.js';
 // — JSON API —

package/dist/src/watchers/index.d.ts

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export declare const VERSION = "0.11.0";
+export declare const VERSION = "0.13.0";
 export type { CacheEntryContent, CacheEventLike, CacheOperation } from './cache_watcher.js';
 export { buildCacheEntry, CACHE_EVENTS, CacheWatcher } from './cache_watcher.js';
 export { nextCronRunMs } from './cron_next_run.js';

package/dist/src/watchers/index.js

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export const VERSION = '0.11.0';
+export const VERSION = '0.13.0';
 // — cache watcher —
 export { buildCacheEntry, CACHE_EVENTS, CacheWatcher } from './cache_watcher.js';
 export { nextCronRunMs } from './cron_next_run.js';

package/dist/stubs/config/telescope.stub

@@ -88,6 +88,26 @@ export default defineConfig({
   //   skipBody: (request) => request.url.startsWith('/webhooks/'),
   // },
 
+  /**
+   * Enrich every request entry with what only your app knows. Return 'tags' for
+   * anything you want to FILTER by in the dashboard, 'context' for detail you only
+   * want to read, and 'user' when neither ctx.auth.user nor the
+   * @adonis-agora/context userRef() applies.
+   *
+   * The classic use: have the front end send its current screen in a header, and
+   * tag the entry with it — then the dashboard answers "which requests came from
+   * the writing screen?" with its normal tag filter.
+   *
+   * SYNCHRONOUS: it runs on the recording path of every request, so read what is
+   * already on the ctx (headers, route, resolved guard state) rather than doing
+   * I/O. A throw is swallowed — enrichment never costs you the entry.
+   */
+  // requestEnrichment: (ctx) => {
+  //   // header() is optional on the framework-agnostic ctx type — hence the ?. call
+  //   const screen = ctx.request.header?.('x-screen')
+  //   return typeof screen === 'string' ? { tags: ['screen:' + screen] } : undefined
+  // },
+
   /**
    * Sensitive-data redaction. Every entry's content is scrubbed before it is
    * persisted — a built-in set of sensitive keys ('authorization', 'cookie',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/telescope",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Laravel Telescope-style headless observability for AdonisJS — records HTTP requests and every Agora diagnostics event as queryable entries, plus opt-in subpaths for per-technology watchers, a web dashboard, AI exception diagnosis, and alerting.",
   "license": "MIT",
   "repository": {