@adonis-agora/telescope 0.1.0

package/dist/src/stores/lucid.js

@@ -0,0 +1,257 @@
+import { randomUUID } from 'node:crypto';
+import { currentTraceId } from '../context_accessor.js';
+import { isBatchOrigin } from '../entry.js';
+/**
+ * The table {@link LucidTelescopeStore} reads and writes. Override via
+ * {@link LucidStoreOptions.tableName} when `telescope_entries` collides with an
+ * existing table.
+ */
+export const DEFAULT_TABLE_NAME = 'telescope_entries';
+/**
+ * `CREATE TABLE IF NOT EXISTS` DDL for the telescope entries table, plus the
+ * indexes `list` / `prune` / `topFamilies` lean on, as one statement per array
+ * element so each can be issued through Lucid's `rawQuery`.
+ *
+ * Portable across sqlite / Postgres / MySQL (quoted identifiers, no dialect-only
+ * column types). A real deployment should still prefer the bundled migration stub
+ * so the schema is versioned, but this lets a store stand itself up in tests and
+ * scripts without a migration runner.
+ */
+export function createTableStatements(tableName = DEFAULT_TABLE_NAME) {
+    return [
+        `CREATE TABLE IF NOT EXISTS "${tableName}" (
+      "id" VARCHAR(255) PRIMARY KEY NOT NULL,
+      "type" VARCHAR(255) NOT NULL,
+      "family_hash" VARCHAR(255) NULL,
+      "content" TEXT NOT NULL,
+      "tags" TEXT NOT NULL,
+      "sequence" INTEGER NOT NULL,
+      "duration_ms" INTEGER NULL,
+      "origin" VARCHAR(255) NOT NULL,
+      "trace_id" VARCHAR(255) NULL,
+      "created_at" BIGINT NOT NULL
+    )`,
+        `CREATE INDEX IF NOT EXISTS "${tableName}_created_at_idx" ON "${tableName}" ("created_at")`,
+        `CREATE INDEX IF NOT EXISTS "${tableName}_type_idx" ON "${tableName}" ("type")`,
+        `CREATE INDEX IF NOT EXISTS "${tableName}_trace_id_idx" ON "${tableName}" ("trace_id")`,
+        `CREATE INDEX IF NOT EXISTS "${tableName}_family_hash_idx" ON "${tableName}" ("family_hash")`,
+    ];
+}
+/**
+ * A persistent, SQL-backed {@link TelescopeStore} on AdonisJS Lucid. Uses Lucid's
+ * **async** query builder directly, so it works on every dialect Lucid supports
+ * (sqlite / Postgres / MySQL) — no synchronous driver handle, no dialect lock-in.
+ *
+ * `content` and `tags` are stored as JSON text and round-tripped on read;
+ * `created_at` is epoch-ms so ordering and age-pruning are integer comparisons.
+ * `sequence` is seeded from `MAX(sequence)` on first use so it keeps climbing
+ * across process restarts.
+ *
+ * Usually you don't construct this directly: `config/telescope.ts` selects it via
+ * `storage.lucid({ ... })` and the provider builds it for you, lazily importing
+ * `@adonisjs/lucid` only when the `lucid` driver is the active one.
+ */
+export class LucidTelescopeStore {
+    db;
+    tableName;
+    maxEntries;
+    autoCreateTable;
+    /** Lazily-resolved init (table creation + sequence seed), run at most once. */
+    ready = null;
+    sequence = 0;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.tableName = options.tableName ?? DEFAULT_TABLE_NAME;
+        this.maxEntries =
+            options.maxEntries !== undefined && options.maxEntries > 0 ? options.maxEntries : null;
+        this.autoCreateTable = options.autoCreateTable ?? false;
+    }
+    async record(input) {
+        await this.init();
+        const traceId = input.traceId !== undefined ? input.traceId : currentTraceId();
+        const origin = isBatchOrigin(input.origin) ? input.origin : 'manual';
+        const entry = {
+            id: randomUUID(),
+            type: input.type,
+            familyHash: input.familyHash ?? null,
+            content: input.content,
+            tags: input.tags ?? [],
+            sequence: this.sequence++,
+            durationMs: input.durationMs ?? null,
+            origin,
+            traceId,
+            createdAt: new Date(),
+        };
+        const row = {
+            id: entry.id,
+            type: entry.type,
+            family_hash: entry.familyHash,
+            content: safeJson(entry.content),
+            tags: JSON.stringify(entry.tags),
+            sequence: entry.sequence,
+            duration_ms: entry.durationMs,
+            origin: entry.origin,
+            trace_id: entry.traceId,
+            created_at: entry.createdAt.getTime(),
+        };
+        await this.db.table(this.tableName).insert(row);
+        return entry;
+    }
+    async get(id) {
+        await this.init();
+        const row = await this.db.from(this.tableName).where('id', id).first();
+        return row ? hydrate(row) : null;
+    }
+    async list(query = {}) {
+        await this.init();
+        let builder = this.db.from(this.tableName);
+        if (query.type !== undefined)
+            builder = builder.where('type', query.type);
+        if (query.familyHash !== undefined)
+            builder = builder.where('family_hash', query.familyHash);
+        if (query.traceId !== undefined)
+            builder = builder.where('trace_id', query.traceId);
+        if (query.before !== undefined)
+            builder = builder.where('created_at', '<', query.before.getTime());
+        if (query.after !== undefined)
+            builder = builder.where('created_at', '>', query.after.getTime());
+        if (query.tag !== undefined) {
+            // A tag is one element of the JSON array text, e.g. `["lib:billing",...]`.
+            // Match the quoted token so `lib:bill` never matches `lib:billing`.
+            builder = builder.whereRaw(`"tags" LIKE ? ESCAPE '\\'`, [
+                `%${likeEscape(JSON.stringify(query.tag))}%`,
+            ]);
+        }
+        if (query.search !== undefined) {
+            const needle = `%${likeEscape(query.search.toLowerCase())}%`;
+            builder = builder.whereRaw(`(LOWER("content") LIKE ? ESCAPE '\\' OR LOWER("tags") LIKE ? ESCAPE '\\')`, [needle, needle]);
+        }
+        // Newest-first: created_at desc, sequence desc as a deterministic tiebreaker.
+        builder = builder.orderBy('created_at', 'desc').orderBy('sequence', 'desc');
+        if (query.limit !== undefined)
+            builder = builder.limit(query.limit);
+        const rows = await builder.select('*');
+        return rows.map((r) => hydrate(r));
+    }
+    async count() {
+        await this.init();
+        const rows = await this.db.from(this.tableName).count('*', 'total');
+        return toInt(rows[0]?.total);
+    }
+    async prune(olderThan, keepLast) {
+        await this.init();
+        const cutoff = olderThan.getTime();
+        if (keepLast === undefined) {
+            return this.db.from(this.tableName).where('created_at', '<', cutoff).delete();
+        }
+        // Keep the newest `keepLast` of the doomed (older-than-cutoff) entries: find
+        // their ids ordered newest-first, skip the first `keepLast`, delete the rest.
+        const doomed = await this.db
+            .from(this.tableName)
+            .where('created_at', '<', cutoff)
+            .orderBy('created_at', 'desc')
+            .orderBy('sequence', 'desc')
+            .select('id');
+        const toDelete = doomed.slice(keepLast).map((r) => String(r.id));
+        if (toDelete.length === 0)
+            return 0;
+        return this.db
+            .from(this.tableName)
+            .whereRaw(`"id" IN (${toDelete.map(() => '?').join(', ')})`, toDelete)
+            .delete();
+    }
+    async clear() {
+        await this.init();
+        await this.db.from(this.tableName).whereRaw('1 = 1').delete();
+    }
+    /** Cap enforcement helper for callers running a scheduled trim. */
+    get capacity() {
+        return this.maxEntries;
+    }
+    /** Run table creation (optional) + sequence seeding exactly once. */
+    init() {
+        if (!this.ready)
+            this.ready = this.doInit();
+        return this.ready;
+    }
+    async doInit() {
+        if (this.autoCreateTable) {
+            for (const stmt of createTableStatements(this.tableName)) {
+                await this.db.rawQuery(stmt);
+            }
+        }
+        // Seed the in-process counter from the persisted maximum so sequence keeps
+        // climbing monotonically across restarts.
+        const maxRow = await this.db
+            .from(this.tableName)
+            .orderBy('sequence', 'desc')
+            .limit(1)
+            .select('sequence');
+        const max = maxRow.length > 0 ? toInt(maxRow[0]?.sequence) : -1;
+        this.sequence = max + 1;
+    }
+}
+/**
+ * Stand up the telescope entries table (and its indexes) through Lucid's async
+ * query runner, idempotently (`CREATE TABLE IF NOT EXISTS`). Works on every Lucid
+ * dialect. Handy for tests, scripts and quick-starts where running a full
+ * migration is overkill.
+ *
+ * Production apps should prefer the bundled migration stub so the schema is
+ * versioned and runs through `node ace migration:run`.
+ */
+export async function createTelescopeTable(db, options = {}) {
+    const tableName = options.tableName ?? DEFAULT_TABLE_NAME;
+    for (const stmt of createTableStatements(tableName)) {
+        await db.rawQuery(stmt);
+    }
+}
+/** Parse JSON text columns back into an {@link Entry}. */
+function hydrate(row) {
+    return {
+        id: row.id,
+        type: row.type,
+        familyHash: row.family_hash ?? null,
+        content: parseJson(row.content),
+        tags: parseTags(row.tags),
+        sequence: toInt(row.sequence),
+        durationMs: row.duration_ms === null || row.duration_ms === undefined ? null : toInt(row.duration_ms),
+        origin: isBatchOrigin(row.origin) ? row.origin : 'manual',
+        traceId: row.trace_id ?? null,
+        createdAt: new Date(toInt(row.created_at)),
+    };
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value) ?? 'null';
+    }
+    catch {
+        return 'null';
+    }
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function parseTags(text) {
+    const parsed = parseJson(text);
+    return Array.isArray(parsed) ? parsed.filter((t) => typeof t === 'string') : [];
+}
+function toInt(value) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'bigint')
+        return Number(value);
+    if (typeof value === 'string')
+        return Number.parseInt(value, 10) || 0;
+    return 0;
+}
+/** Escape LIKE wildcards so user input matches literally (escape char `\`). */
+function likeEscape(value) {
+    return value.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+//# sourceMappingURL=lucid.js.map

package/dist/src/stores/lucid.js.map

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

package/dist/src/stores/memory.d.ts

@@ -0,0 +1,31 @@
+import { type Entry, type RecordInput } from '../entry.js';
+import type { EntryQuery, TelescopeStore } from '../store.js';
+/** Options for {@link InMemoryTelescopeStore}. */
+export interface InMemoryStoreOptions {
+    /**
+     * Hard cap on retained entries. When exceeded, the oldest entries are evicted
+     * (ring-buffer semantics) so an unbounded process can never OOM. Default 1000.
+     */
+    maxEntries?: number;
+}
+/**
+ * The default, dependency-free {@link TelescopeStore}: a bounded in-process ring
+ * buffer. Ideal for development and tests; production deployments that need
+ * cross-process or durable storage swap in the `lucid` driver (or any store
+ * implementing the same contract).
+ */
+export declare class InMemoryTelescopeStore implements TelescopeStore {
+    private readonly maxEntries;
+    private readonly entries;
+    private readonly byId;
+    private sequence;
+    constructor(options?: InMemoryStoreOptions);
+    record<TContent>(input: RecordInput<TContent>): Promise<Entry<TContent>>;
+    get(id: string): Promise<Entry | null>;
+    list(query?: EntryQuery): Promise<Entry[]>;
+    count(): Promise<number>;
+    prune(olderThan: Date, keepLast?: number): Promise<number>;
+    clear(): Promise<void>;
+    private evictOverflow;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/src/stores/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/stores/memory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,KAAK,EAAE,KAAK,WAAW,EAAiB,MAAM,aAAa,CAAC;AAC5F,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE9D,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAK;gBAET,OAAO,GAAE,oBAAyB;IAKxC,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAuBxE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IAItC,IAAI,CAAC,KAAK,GAAE,UAAe,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAkB9C,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAIxB,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoB1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,OAAO,CAAC,aAAa;CAMtB"}

package/dist/src/stores/memory.js

@@ -0,0 +1,117 @@
+import { randomUUID } from 'node:crypto';
+import { currentTraceId } from '../context_accessor.js';
+import { isBatchOrigin } from '../entry.js';
+/**
+ * The default, dependency-free {@link TelescopeStore}: a bounded in-process ring
+ * buffer. Ideal for development and tests; production deployments that need
+ * cross-process or durable storage swap in the `lucid` driver (or any store
+ * implementing the same contract).
+ */
+export class InMemoryTelescopeStore {
+    maxEntries;
+    entries = [];
+    byId = new Map();
+    sequence = 0;
+    constructor(options = {}) {
+        const max = options.maxEntries ?? 1000;
+        this.maxEntries = max > 0 ? max : 1000;
+    }
+    async record(input) {
+        const traceId = input.traceId !== undefined ? input.traceId : currentTraceId();
+        const origin = isBatchOrigin(input.origin) ? input.origin : 'manual';
+        const entry = {
+            id: randomUUID(),
+            type: input.type,
+            familyHash: input.familyHash ?? null,
+            content: input.content,
+            tags: input.tags ?? [],
+            sequence: this.sequence++,
+            durationMs: input.durationMs ?? null,
+            origin,
+            traceId,
+            createdAt: new Date(),
+        };
+        // Newest-first ordering: unshift so index 0 is always the most recent.
+        this.entries.unshift(entry);
+        this.byId.set(entry.id, entry);
+        this.evictOverflow();
+        return entry;
+    }
+    async get(id) {
+        return this.byId.get(id) ?? null;
+    }
+    async list(query = {}) {
+        const search = query.search?.toLowerCase();
+        const results = [];
+        // `entries` is already newest-first.
+        for (const entry of this.entries) {
+            if (query.type !== undefined && entry.type !== query.type)
+                continue;
+            if (query.tag !== undefined && !entry.tags.includes(query.tag))
+                continue;
+            if (query.familyHash !== undefined && entry.familyHash !== query.familyHash)
+                continue;
+            if (query.traceId !== undefined && entry.traceId !== query.traceId)
+                continue;
+            if (query.before !== undefined && !(entry.createdAt < query.before))
+                continue;
+            if (query.after !== undefined && !(entry.createdAt > query.after))
+                continue;
+            if (search !== undefined && !matchesSearch(entry, search))
+                continue;
+            results.push(entry);
+            if (query.limit !== undefined && results.length >= query.limit)
+                break;
+        }
+        return results;
+    }
+    async count() {
+        return this.entries.length;
+    }
+    async prune(olderThan, keepLast) {
+        // Indices of the doomed entries (older than the cutoff), newest-first.
+        const doomed = [];
+        for (let i = 0; i < this.entries.length; i++) {
+            const entry = this.entries[i];
+            if (entry && entry.createdAt < olderThan)
+                doomed.push(i);
+        }
+        // Keep the newest N of the doomed set: since `entries` is newest-first, the
+        // first `keepLast` doomed indices are the newest doomed ones.
+        const toDelete = keepLast !== undefined ? doomed.slice(keepLast) : doomed;
+        if (toDelete.length === 0)
+            return 0;
+        // Delete from the back so earlier indices stay valid.
+        const ascending = [...toDelete].sort((a, b) => b - a);
+        for (const index of ascending) {
+            const [removed] = this.entries.splice(index, 1);
+            if (removed)
+                this.byId.delete(removed.id);
+        }
+        return toDelete.length;
+    }
+    async clear() {
+        this.entries.length = 0;
+        this.byId.clear();
+    }
+    evictOverflow() {
+        while (this.entries.length > this.maxEntries) {
+            const removed = this.entries.pop();
+            if (removed)
+                this.byId.delete(removed.id);
+        }
+    }
+}
+/** Substring match against the entry's JSON content and its tags. */
+function matchesSearch(entry, needle) {
+    if (entry.tags.some((tag) => tag.toLowerCase().includes(needle)))
+        return true;
+    try {
+        return JSON.stringify(entry.content).toLowerCase().includes(needle);
+    }
+    catch {
+        // Content with a circular reference / BigInt — fall back to no match.
+        return false;
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/src/stores/memory.js.map

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

package/dist/src/telescope_middleware.d.ts

@@ -0,0 +1,19 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { NextFn } from '@adonisjs/core/types/http';
+/**
+ * Records each inbound HTTP request as a `request` telescope entry (method, url,
+ * status, duration, traceId), and auto-captures any exception thrown by the
+ * downstream pipeline as an `exception` entry (message, name, stack, a stable
+ * family hash, traceId, method/url) BEFORE re-throwing — so HTTP exceptions are
+ * captured with zero app changes. Registered on the **server** middleware stack
+ * so it wraps the whole pipeline and observes the final response status.
+ *
+ * Reads the active store from the global runtime slot rather than via DI, so the
+ * middleware needs no constructor wiring and is a no-op (zero overhead) when
+ * telescope is disabled or not booted. Both recordings are wrapped so they can
+ * never break a request and never swallow the original error.
+ */
+export default class TelescopeMiddleware {
+    handle(ctx: HttpContext, next: NextFn): Promise<any>;
+}
+//# sourceMappingURL=telescope_middleware.d.ts.map

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

@@ -0,0 +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;AAKxD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAmB;IAChC,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM;CAkC5C"}

package/dist/src/telescope_middleware.js

@@ -0,0 +1,56 @@
+import { recordExceptionInStore } from './exception_watcher.js';
+import { getTelescopeRuntime } from './registry.js';
+import { recordRequest } from './request_watcher.js';
+/**
+ * Records each inbound HTTP request as a `request` telescope entry (method, url,
+ * status, duration, traceId), and auto-captures any exception thrown by the
+ * downstream pipeline as an `exception` entry (message, name, stack, a stable
+ * family hash, traceId, method/url) BEFORE re-throwing — so HTTP exceptions are
+ * captured with zero app changes. Registered on the **server** middleware stack
+ * so it wraps the whole pipeline and observes the final response status.
+ *
+ * Reads the active store from the global runtime slot rather than via DI, so the
+ * middleware needs no constructor wiring and is a no-op (zero overhead) when
+ * telescope is disabled or not booted. Both recordings are wrapped so they can
+ * never break a request and never swallow the original error.
+ */
+export default class TelescopeMiddleware {
+    async handle(ctx, next) {
+        const runtime = getTelescopeRuntime();
+        if (!runtime.store || !runtime.requestWatcherEnabled) {
+            return next();
+        }
+        const startedAt = Date.now();
+        const store = runtime.store;
+        try {
+            return await next();
+        }
+        catch (error) {
+            // Auto-capture the exception, then re-throw the ORIGINAL error untouched.
+            // Recording is wrapped so it can never mask the error it observes.
+            try {
+                const request = ctx.request;
+                await recordExceptionInStore(store, error, {
+                    method: request.method(),
+                    url: request.url(),
+                });
+            }
+            catch {
+                // Observability must never break the request it observes.
+            }
+            throw error;
+        }
+        finally {
+            // Post-response phase: record the now-complete request. Awaited so a slow
+            // store surfaces back-pressure here rather than leaking an unhandled
+            // rejection, but wrapped so observability can never break the request.
+            try {
+                await recordRequest(store, ctx, startedAt);
+            }
+            catch {
+                // Observability must never break the request it observes.
+            }
+        }
+    }
+}
+//# sourceMappingURL=telescope_middleware.js.map

package/dist/src/telescope_middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telescope_middleware.js","sourceRoot":"","sources":["../../src/telescope_middleware.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAwB,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE3E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAmB;IACtC,KAAK,CAAC,MAAM,CAAC,GAAgB,EAAE,IAAY;QACzC,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;QACtC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,CAAC;YACrD,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,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,CAAC,CAAC;YAC3E,CAAC;YAAC,MAAM,CAAC;gBACP,0DAA0D;YAC5D,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

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

@@ -0,0 +1,49 @@
+import type { Entry } from '../entry.js';
+import type { TelescopeService } from '../service.js';
+import type { EntryQuery } from '../store.js';
+import type { UiHttpContext, UiRequest } from './http.js';
+/**
+ * The JSON-API handler functions over a {@link TelescopeService}. Each takes the
+ * framework-light {@link UiHttpContext} (an Adonis `HttpContext` satisfies it) plus
+ * the service, reads query/route params off the request, and writes a JSON body to
+ * the response. No DI, no router — trivially unit-testable with a plain object.
+ */
+export declare class TelescopeApi {
+    private readonly service;
+    constructor(service: TelescopeService);
+    /**
+     * `GET <path>/api/entries` — list entries newest-first, with optional filters:
+     * `?type=`, `?traceId=`, `?search=`, `?limit=` (capped), `?before=` (ISO date).
+     */
+    list(ctx: UiHttpContext): Promise<unknown>;
+    /** `GET <path>/api/entries/:id` — one entry with its full `content`, or 404. */
+    show(ctx: UiHttpContext, id: string): Promise<unknown>;
+    /** `GET <path>/api/trace/:traceId` — every entry under a trace, newest-first. */
+    trace(ctx: UiHttpContext, traceId: string): Promise<unknown>;
+    /**
+     * `GET <path>/api/stats` — dashboard aggregates: total count, top families, and
+     * top tags. `?limit=` caps each top-N list; `?type=` scopes `topFamilies`.
+     */
+    stats(ctx: UiHttpContext): Promise<unknown>;
+}
+/**
+ * A trimmed projection of an {@link Entry} for the list views — drops the
+ * potentially-large `content` (the detail endpoint serves that) and derives a
+ * short, human-readable `summary` line.
+ */
+export interface EntrySummary {
+    id: string;
+    type: string;
+    familyHash: string | null;
+    tags: string[];
+    traceId: string | null;
+    durationMs: number | null;
+    sequence: number;
+    createdAt: string;
+    summary: string;
+}
+/** Project an entry to its {@link EntrySummary}. */
+export declare function toSummary(entry: Entry): EntrySummary;
+/** Build an {@link EntryQuery} from the request's query string. */
+export declare function buildQuery(request: UiRequest): EntryQuery;
+//# sourceMappingURL=api.d.ts.map

package/dist/src/ui/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/ui/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAO1D;;;;;GAKG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,gBAAgB;IAEtD;;;OAGG;IACG,IAAI,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAYhD,gFAAgF;IAC1E,IAAI,CAAC,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW5D,iFAAiF;IAC3E,KAAK,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQlE;;;OAGG;IACG,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;CAalD;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oDAAoD;AACpD,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,YAAY,CAapD;AAqBD,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,GAAG,UAAU,CAgBzD"}