@zintrust/trace 0.4.75

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * TraceConfig — defaults and merge helper for @zintrust/trace
+ */
+import type { ITraceConfig, TraceConfigOverrides } from './types';
+export declare const TraceConfig: Readonly<{
+    defaults(): ITraceConfig;
+    merge(overrides?: TraceConfigOverrides): ITraceConfig;
+    isWatcherEnabled: (config: ITraceConfig, key: keyof ITraceConfig["watchers"]) => boolean;
+}>;

package/dist/config.js

@@ -0,0 +1,38 @@
+const DEFAULTS = Object.freeze({
+    enabled: false,
+    connection: undefined,
+    pruneAfterHours: 24,
+    ignoreRoutes: ['/trace', '/health', '/ping'],
+    slowQueryThreshold: 100,
+    logMinLevel: 'info',
+    watchers: {},
+    redaction: {
+        headers: ['authorization', 'cookie', 'x-api-key', 'x-auth-token'],
+        body: ['password', 'token', 'secret', 'apiKey', 'api_key', 'jwt', 'bearer'],
+        query: [],
+    },
+});
+const isWatcherEnabled = (config, key) => {
+    const override = config.watchers[key];
+    return override !== false; // undefined = enabled by default; explicit false = disabled
+};
+export const TraceConfig = Object.freeze({
+    defaults() {
+        return DEFAULTS;
+    },
+    merge(overrides) {
+        if (overrides === undefined || overrides === null)
+            return DEFAULTS;
+        return Object.freeze({
+            ...DEFAULTS,
+            ...overrides,
+            watchers: { ...DEFAULTS.watchers, ...(overrides.watchers ?? {}) },
+            redaction: {
+                ...DEFAULTS.redaction,
+                ...(overrides.redaction ?? {}),
+            },
+            ignoreRoutes: overrides.ignoreRoutes ?? DEFAULTS.ignoreRoutes,
+        });
+    },
+    isWatcherEnabled,
+});

package/dist/context.d.ts

@@ -0,0 +1,18 @@
+/**
+ * TraceContext — sealed namespace for batch_id, userId, hostname, and memory.
+ * Piggybacks on RequestContext (already available in core) — no new ALS store.
+ */
+type RequestContextProvider = {
+    current?: () => unknown;
+    peek?: () => unknown;
+};
+export declare const TraceContext: Readonly<{
+    getBatchId: () => string;
+    getUserId: () => string | undefined;
+    getRequestPath: () => string | undefined;
+    getHostname: () => string;
+    getMemory: () => number | null;
+    now: () => number;
+    setRequestContextImpl: (impl: RequestContextProvider) => void;
+}>;
+export {};

package/dist/context.js

@@ -0,0 +1,86 @@
+// Lazy reference to ZinTrust RequestContext — typed as unknown to stay runtime-agnostic.
+let _reqCtx;
+const getRequestContext = () => {
+    return _reqCtx;
+};
+const setRequestContextImpl = (impl) => {
+    _reqCtx = impl;
+};
+const isPromiseLike = (value) => {
+    return typeof value === 'object' && value !== null && 'then' in value;
+};
+const getCurrentContext = () => {
+    const provider = getRequestContext();
+    if (!provider)
+        return undefined;
+    let currentValue;
+    if (typeof provider.peek === 'function') {
+        currentValue = provider.peek();
+    }
+    else if (typeof provider.current === 'function') {
+        currentValue = provider.current();
+    }
+    else {
+        currentValue = undefined;
+    }
+    if (isPromiseLike(currentValue))
+        return undefined;
+    if (typeof currentValue !== 'object' || currentValue === null)
+        return undefined;
+    return currentValue;
+};
+const getContextString = (key) => {
+    const value = getCurrentContext()?.[key];
+    if (typeof value === 'string' && value.trim() !== '')
+        return value;
+    if (typeof value === 'number')
+        return String(value);
+    return undefined;
+};
+const getBatchId = () => {
+    return getContextString('traceId') ?? crypto.randomUUID();
+};
+const getUserId = () => {
+    return getContextString('userId');
+};
+const getRequestPath = () => {
+    return getContextString('path');
+};
+const getHostname = () => {
+    // Workers do not expose `os` or `process` — return 'worker' as fallback.
+    if (typeof process !== 'undefined' && typeof process.env === 'object') {
+        try {
+            // Dynamic import avoids the need for a node-singletons wrapper at the type level.
+            // Hostname is non-critical; we fall back gracefully.
+            const hostname = process.env['HOSTNAME'];
+            if (typeof hostname === 'string' && hostname.length > 0)
+                return hostname;
+        }
+        catch {
+            // fall through
+        }
+        return 'node';
+    }
+    return 'worker';
+};
+const getMemory = () => {
+    if (typeof process !== 'undefined' && typeof process.memoryUsage === 'function') {
+        try {
+            return Math.round(process.memoryUsage().heapUsed / 1024 / 1024);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+};
+const now = () => Date.now();
+export const TraceContext = Object.freeze({
+    getBatchId,
+    getUserId,
+    getRequestPath,
+    getHostname,
+    getMemory,
+    now,
+    setRequestContextImpl,
+});

package/dist/dashboard/handlers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * TraceDashboard handlers — pure handler functions wired to ITraceStorage.
+ * No auth in this layer — caller mounts middleware as needed.
+ */
+import type { IRequest, IResponse } from '@zintrust/core';
+import type { ITraceStorage } from '../types';
+export declare const setHandlerStorage: (s: ITraceStorage) => void;
+export declare function listEntries(req: IRequest, res: IResponse): Promise<void>;
+export declare function getEntry(req: IRequest, res: IResponse): Promise<void>;
+export declare function getBatch(req: IRequest, res: IResponse): Promise<void>;
+export declare function getStats(_req: IRequest, res: IResponse): Promise<void>;
+export declare function clearEntries(_req: IRequest, res: IResponse): Promise<void>;
+export declare function getMonitoring(_req: IRequest, res: IResponse): Promise<void>;
+export declare function addMonitoring(req: IRequest, res: IResponse): Promise<void>;
+export declare function removeMonitoring(req: IRequest, res: IResponse): Promise<void>;

package/dist/dashboard/handlers.js

@@ -0,0 +1,179 @@
+// ---------------------------------------------------------------------------
+// Storage holder (set once from routes.ts)
+// ---------------------------------------------------------------------------
+let _storage = null;
+export const setHandlerStorage = (s) => {
+    _storage = s;
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const requireStorage = (res) => {
+    if (_storage) {
+        return true;
+    }
+    res.setStatus(503).json({ error: 'Trace not initialised' });
+    return false;
+};
+const getStorage = (res) => {
+    if (requireStorage(res)) {
+        return _storage;
+    }
+    return null;
+};
+const qp = (req, key) => {
+    const v = req.getQueryParam(key);
+    return Array.isArray(v) ? v[0] : v;
+};
+const qpInt = (req, key, fallback) => {
+    const raw = qp(req, key);
+    const n = typeof raw === 'string' ? Number.parseInt(raw, 10) : Number.NaN;
+    return Number.isNaN(n) ? fallback : n;
+};
+const getNumericQueryParam = (req, key) => {
+    const raw = qp(req, key);
+    if (typeof raw === 'string') {
+        const parsed = Number(raw);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+};
+// ---------------------------------------------------------------------------
+// Entry handlers
+// ---------------------------------------------------------------------------
+export async function listEntries(req, res) {
+    const storage = getStorage(res);
+    if (storage !== null) {
+        const opts = {
+            type: qp(req, 'type'),
+            tag: qp(req, 'tag'),
+            batchId: qp(req, 'batchId'),
+            from: getNumericQueryParam(req, 'from'),
+            to: getNumericQueryParam(req, 'to'),
+            page: qpInt(req, 'page', 1),
+            perPage: Math.min(qpInt(req, 'perPage', 50), 200),
+        };
+        try {
+            const result = await storage.queryEntries(opts);
+            res.json({ ok: true, ...result, page: opts.page, perPage: opts.perPage });
+        }
+        catch (err) {
+            res.setStatus(500).json({ error: err.message });
+        }
+    }
+}
+export async function getEntry(req, res) {
+    const storage = getStorage(res);
+    if (storage === null)
+        return;
+    const uuid = req.getParam('uuid');
+    if (uuid) {
+        try {
+            const entry = await storage.getEntry(uuid);
+            if (entry) {
+                res.json({ ok: true, entry });
+                return;
+            }
+            res.setStatus(404).json({ error: 'Not found' });
+            return;
+        }
+        catch (err) {
+            res.setStatus(500).json({ error: err.message });
+            return;
+        }
+    }
+    res.setStatus(400).json({ error: 'uuid required' });
+}
+export async function getBatch(req, res) {
+    const storage = getStorage(res);
+    if (storage === null)
+        return;
+    const batchId = req.getParam('batchId');
+    if (batchId) {
+        try {
+            const entries = await storage.getBatch(batchId);
+            res.json({ ok: true, entries });
+            return;
+        }
+        catch (err) {
+            res.setStatus(500).json({ error: err.message });
+            return;
+        }
+    }
+    res.setStatus(400).json({ error: 'batchId required' });
+}
+export async function getStats(_req, res) {
+    const storage = getStorage(res);
+    if (storage === null)
+        return;
+    try {
+        const stats = await storage.stats();
+        res.json({ ok: true, stats });
+    }
+    catch (err) {
+        res.setStatus(500).json({ error: err.message });
+    }
+}
+export async function clearEntries(_req, res) {
+    const storage = getStorage(res);
+    if (storage === null)
+        return;
+    try {
+        await storage.clear();
+        res.json({ ok: true });
+    }
+    catch (err) {
+        res.setStatus(500).json({ error: err.message });
+    }
+}
+// ---------------------------------------------------------------------------
+// Monitoring handlers
+// ---------------------------------------------------------------------------
+export async function getMonitoring(_req, res) {
+    const storage = getStorage(res);
+    if (storage === null)
+        return;
+    try {
+        const tags = await storage.getMonitoring();
+        res.json({ ok: true, tags });
+    }
+    catch (err) {
+        res.setStatus(500).json({ error: err.message });
+    }
+}
+export async function addMonitoring(req, res) {
+    const storage = getStorage(res);
+    if (storage === null)
+        return;
+    const tag = req.getParam('tag');
+    if (tag) {
+        try {
+            await storage.addMonitoring(tag);
+            res.json({ ok: true });
+            return;
+        }
+        catch (err) {
+            res.setStatus(500).json({ error: err.message });
+            return;
+        }
+    }
+    res.setStatus(400).json({ error: 'tag required' });
+}
+export async function removeMonitoring(req, res) {
+    const storage = getStorage(res);
+    if (storage === null)
+        return;
+    const tag = req.getParam('tag');
+    if (tag) {
+        try {
+            await storage.removeMonitoring(tag);
+            res.json({ ok: true });
+            return;
+        }
+        catch (err) {
+            res.setStatus(500).json({ error: err.message });
+            return;
+        }
+    }
+    res.setStatus(400).json({ error: 'tag required' });
+}

package/dist/dashboard/routes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Dashboard route registrar for @zintrust/trace.
+ * Mounts the SPA + all REST API endpoints under the configured basePath.
+ * Auth is NOT applied here — callers add middleware via routeOptions.
+ */
+import { type IRouter } from '@zintrust/core';
+import type { ITraceStorage } from '../types';
+export type TraceDashboardOptions = {
+    /** Base path for the dashboard, e.g. '/trace'. Defaults to '/trace'. */
+    basePath?: string;
+    /** Optional ZinTrust middleware names to apply to all routes. */
+    middleware?: ReadonlyArray<string>;
+};
+export type TraceDashboardRegistrationOptions = TraceDashboardOptions & {
+    /** Optional trace storage connection override. Defaults to TraceConfig / runtime default. */
+    connectionName?: string;
+};
+export declare const registerTraceRoutes: (router: IRouter, storage: ITraceStorage, options?: TraceDashboardOptions) => void;
+export declare const registerTraceDashboard: (router: IRouter, options?: TraceDashboardRegistrationOptions) => void;

package/dist/dashboard/routes.js

@@ -0,0 +1,50 @@
+/**
+ * Dashboard route registrar for @zintrust/trace.
+ * Mounts the SPA + all REST API endpoints under the configured basePath.
+ * Auth is NOT applied here — callers add middleware via routeOptions.
+ */
+import { appConfig, Router, useDatabase } from '@zintrust/core';
+import { TraceConfig } from '../config';
+import { TraceStorage } from '../storage';
+import { addMonitoring, clearEntries, getBatch, getEntry, getMonitoring, getStats, listEntries, removeMonitoring, setHandlerStorage, } from './handlers';
+import { buildDashboardHtml } from './ui';
+const resolveDashboardConnectionName = (connectionName) => {
+    const explicitConnection = connectionName?.trim();
+    if (explicitConnection !== undefined && explicitConnection !== '') {
+        return explicitConnection;
+    }
+    const configuredConnection = TraceConfig.merge().connection?.trim();
+    return configuredConnection === undefined || configuredConnection === ''
+        ? undefined
+        : configuredConnection;
+};
+export const registerTraceRoutes = (router, storage, options = {}) => {
+    setHandlerStorage(storage);
+    const base = options.basePath ?? '/trace';
+    const routeOptions = (options.middleware?.length ?? 0) > 0
+        ? { middleware: options.middleware }
+        : undefined;
+    // SPA shell
+    Router.get(router, base, (_req, res) => {
+        res.html(buildDashboardHtml(base, appConfig.name));
+    }, routeOptions);
+    // Serve the SPA for any /<basePath>/* sub-path (client-side routing)
+    Router.get(router, `${base}/*`, (_req, res) => {
+        res.html(buildDashboardHtml(base, appConfig.name));
+    }, routeOptions);
+    // REST API
+    Router.group(router, `${base}/api`, (r) => {
+        Router.get(r, '/entries', listEntries, routeOptions);
+        Router.get(r, '/entries/:uuid', getEntry, routeOptions);
+        Router.del(r, '/entries', clearEntries, routeOptions);
+        Router.get(r, '/batch/:batchId', getBatch, routeOptions);
+        Router.get(r, '/stats', getStats, routeOptions);
+        Router.get(r, '/monitoring', getMonitoring, routeOptions);
+        Router.post(r, '/monitoring/:tag', addMonitoring, routeOptions);
+        Router.del(r, '/monitoring/:tag', removeMonitoring, routeOptions);
+    });
+};
+export const registerTraceDashboard = (router, options = {}) => {
+    const storage = TraceStorage.resolveStorage(useDatabase(undefined, resolveDashboardConnectionName(options.connectionName)));
+    registerTraceRoutes(router, storage, options);
+};

package/dist/dashboard/ui.d.ts

@@ -0,0 +1,2 @@
+declare const buildDashboardHtml: (basePath: string, projectName?: string) => string;
+export { buildDashboardHtml };