@tracelet/express 0.0.1

package/README.md

@@ -0,0 +1,23 @@
+# Tracelet (Express)
+
+Lightweight request logging for Express apps.
+
+## Install
+yarn add @tracelet/express
+
+## Usage
+```ts
+import express from "express";
+import tracelet from "@tracelet/express";
+
+const app = express();
+
+app.use(tracelet({
+  serviceName: "example-api"
+}));
+
+app.get("/users/:id", (req, res) => {
+  res.json({ id: req.params.id });
+});
+
+app.listen(3000);

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./middleware";
+export * from "./types";
+export { traceletMiddleware as tracelet } from "./middleware";
+export * from "./traceletDoc/index";

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tracelet = void 0;
+__exportStar(require("./middleware"), exports);
+__exportStar(require("./types"), exports);
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "tracelet", { enumerable: true, get: function () { return middleware_1.traceletMiddleware; } });
+__exportStar(require("./traceletDoc/index"), exports);

package/dist/jsdoc/index.d.ts

@@ -0,0 +1 @@
+export { parseFileForRouteJSDoc, parseRouteFiles, buildRouteTree, } from "./parseRouteJSDoc";

package/dist/jsdoc/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRouteTree = exports.parseRouteFiles = exports.parseFileForRouteJSDoc = void 0;
+var parseRouteJSDoc_1 = require("./parseRouteJSDoc");
+Object.defineProperty(exports, "parseFileForRouteJSDoc", { enumerable: true, get: function () { return parseRouteJSDoc_1.parseFileForRouteJSDoc; } });
+Object.defineProperty(exports, "parseRouteFiles", { enumerable: true, get: function () { return parseRouteJSDoc_1.parseRouteFiles; } });
+Object.defineProperty(exports, "buildRouteTree", { enumerable: true, get: function () { return parseRouteJSDoc_1.buildRouteTree; } });

package/dist/jsdoc/parseRouteJSDoc.d.ts

@@ -0,0 +1,17 @@
+import type { TraceletMeta } from "../types";
+/**
+ * Parse a single file and extract route registrations with their preceding JSDoc.
+ * Uses format: @description, @request { type }, @response [...], @query { type }.
+ * Path params are extracted from the route path.
+ */
+export declare function parseFileForRouteJSDoc(filePath: string): TraceletMeta[];
+/**
+ * Parse multiple files and return TraceletMeta[] for each route found.
+ */
+export declare function parseRouteFiles(filePaths: string[]): TraceletMeta[];
+/**
+ * Build a parent-child route tree with PARENT grouping nodes.
+ * - If routes are /user, /user/:id, /user/:id/posts → parent is /user (method PARENT), children are those three with their methods.
+ * - If routes are only /user/:id, /user/:id/posts → parent is /user/:id (method PARENT), children are those two with their methods.
+ */
+export declare function buildRouteTree(flat: TraceletMeta[]): TraceletMeta[];

package/dist/jsdoc/parseRouteJSDoc.js

@@ -0,0 +1,432 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFileForRouteJSDoc = parseFileForRouteJSDoc;
+exports.parseRouteFiles = parseRouteFiles;
+exports.buildRouteTree = buildRouteTree;
+var fs_1 = __importDefault(require("fs"));
+var path_1 = __importDefault(require("path"));
+var ROUTE_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+var ROUTE_REG = /(?:app|router)\.(get|post|put|patch|delete|head|options)\s*\(\s*['"`]([^'"`]+)['"`]/gi;
+/** Match JSDoc block comment - non-greedy. */
+var BLOCK_COMMENT_REG = /\/\*\*([\s\S]*?)\*\//g;
+/** Normalize type string to a simple type name. */
+function normalizeType(t) {
+    var s = (t || "string").trim().toLowerCase();
+    if (s.includes("number"))
+        return "number";
+    if (s.includes("boolean"))
+        return "boolean";
+    if (s.includes("object") || s.includes("{}"))
+        return "object";
+    if (s.includes("array") || s.includes("[]"))
+        return "array";
+    return "string";
+}
+/**
+ * Parse a type expression inside braces to extract properties.
+ * e.g. " name: string, age: number " or " limit: number, offset: number "
+ * If no "key: type" pairs (e.g. just "updateUserRequest"), returns empty or single placeholder.
+ */
+function parseTypeProperties(inner) {
+    var trimmed = inner.replace(/\s+/g, " ").trim();
+    if (!trimmed)
+        return [];
+    var pairReg = /(\w+)\s*:\s*([^,}]+)/g;
+    var props = [];
+    var m;
+    while ((m = pairReg.exec(trimmed)) !== null) {
+        props.push({
+            name: m[1].trim(),
+            type: normalizeType(m[2].trim()),
+            required: false,
+        });
+    }
+    if (props.length === 0 && trimmed) {
+        props.push({ name: "body", type: "object", desc: trimmed });
+    }
+    return props;
+}
+/**
+ * Extract a single top-level { ... } (balanced braces) starting at position.
+ */
+function extractBracedObject(str, start) {
+    if (str[start] !== "{")
+        return null;
+    var depth = 0;
+    for (var i = start; i < str.length; i++) {
+        if (str[i] === "{")
+            depth++;
+        else if (str[i] === "}") {
+            depth--;
+            if (depth === 0)
+                return str.slice(start, i + 1);
+        }
+    }
+    return null;
+}
+/**
+ * Parse properties from object string like { id: "string", name: "string" }.
+ */
+function parsePropertiesObject(objStr) {
+    var inner = objStr.replace(/^\s*\{\s*|\s*\}\s*$/g, "").trim();
+    if (!inner)
+        return [];
+    var props = [];
+    var pairReg = /(\w+)\s*:\s*["']?([^,"'}]+)["']?/g;
+    var m;
+    while ((m = pairReg.exec(inner)) !== null) {
+        props.push({
+            name: m[1].trim(),
+            type: normalizeType(m[2].trim()),
+            required: false,
+        });
+    }
+    return props;
+}
+/**
+ * Strip optional @type from the start of content, then return rest (for highlighting; parsing ignores it).
+ */
+function stripOptionalType(content) {
+    return content.trim().replace(/^@type\s*/i, "").trim();
+}
+/**
+ * Parse @response format. @type is optional (for highlighting).
+ * @response @type { status: 200, description: "Success", properties: { id: string, name: string } }
+ * or @response { status: 200, description: "Success", properties: { id: string } }
+ */
+function parseResponseTag(block) {
+    var _a;
+    var responses = [];
+    var responseReg = /@response\s+/gi;
+    var match;
+    while ((match = responseReg.exec(block)) !== null) {
+        var after = stripOptionalType(block.slice(match.index + match[0].length));
+        var open_1 = after.indexOf("{");
+        if (open_1 === -1)
+            continue;
+        var objStr = extractBracedObject(after, open_1);
+        if (!objStr)
+            continue;
+        var statusMatch = objStr.match(/status\s*:\s*(\d+)/i);
+        var descMatch = (_a = objStr.match(/(?:description|descrition)\s*:\s*["']([^"']*)["']/i)) !== null && _a !== void 0 ? _a : objStr.match(/(?:description|descrition)\s*:\s*(\S+)/i);
+        var status_1 = statusMatch ? parseInt(statusMatch[1], 10) : 200;
+        var description = descMatch ? (descMatch[1].trim().replace(/^["']|["']$/g, "") || undefined) : undefined;
+        var properties = [];
+        var propsKeyIdx = objStr.search(/properties\s*:\s*/i);
+        if (propsKeyIdx !== -1) {
+            var afterProps = stripOptionalType(objStr.slice(propsKeyIdx).replace(/properties\s*:\s*/i, ""));
+            if (afterProps.startsWith("{")) {
+                var innerObj = extractBracedObject(afterProps, 0);
+                if (innerObj)
+                    properties = parsePropertiesObject(innerObj);
+            }
+        }
+        responses.push({ status: status_1, description: description, properties: properties });
+    }
+    return responses;
+}
+/**
+ * From a string like "@type { a: b }" or "{ a: b }", extract the braced content and parse as type properties.
+ */
+function parseTypeFromLineOrBlock(content) {
+    var trimmed = content.trim();
+    var typeStart = trimmed.search(/@type\s*/i);
+    var from = typeStart >= 0 ? trimmed.slice(typeStart).replace(/^@type\s*/i, "").trim() : trimmed;
+    var open = from.indexOf("{");
+    if (open === -1)
+        return [];
+    var obj = extractBracedObject(from, open);
+    return obj ? parseTypeProperties(obj.slice(1, -1)) : [];
+}
+/**
+ * Parse JSDoc block. @type is optional everywhere (for highlighting).
+ * @description - endpoint description
+ * @request @type { ... } or @request { ... }
+ * @response @type { status: 200, description: "Success", properties: { id: string } } or @response { ... }
+ * @query @type { limit: number, offset: number } or @query { ... }
+ * @params @type { id: string } or @params { ... } — path params; if omitted, derived from route path.
+ */
+function parseJSDocBlock(block, routePath) {
+    var lines = block.split(/\r?\n/).map(function (l) { return l.replace(/^\s*\*\s?/, "").trim(); });
+    var request;
+    var query;
+    var paramsFromJSDoc;
+    var descriptionLines = [];
+    var currentTag = null;
+    var seenAnyTag = false;
+    for (var i = 0; i < lines.length; i++) {
+        var line = lines[i];
+        var tagMatch = line.match(/^@(description|request|response|query|params)\s*(.*)/i);
+        if (tagMatch) {
+            seenAnyTag = true;
+            currentTag = tagMatch[1].toLowerCase();
+            if (currentTag === "description") {
+                if (tagMatch[2].trim())
+                    descriptionLines.push(tagMatch[2].trim());
+            }
+            else if (currentTag === "request") {
+                var parsed = parseTypeFromLineOrBlock(tagMatch[2]);
+                if (parsed.length)
+                    request = parsed;
+            }
+            else if (currentTag === "query") {
+                var parsed = parseTypeFromLineOrBlock(tagMatch[2]);
+                if (parsed.length)
+                    query = parsed;
+            }
+            else if (currentTag === "params") {
+                var parsed = parseTypeFromLineOrBlock(tagMatch[2]);
+                if (parsed.length)
+                    paramsFromJSDoc = parsed;
+            }
+            continue;
+        }
+        if (currentTag === "description" && line.length > 0) {
+            descriptionLines.push(line);
+        }
+        else if (currentTag === "request" && line.length > 0 && !line.startsWith("@")) {
+            var parsed = parseTypeFromLineOrBlock(line);
+            if (parsed.length)
+                request = parsed;
+        }
+        else if (currentTag === "query" && line.length > 0 && !line.startsWith("@")) {
+            var parsed = parseTypeFromLineOrBlock(line);
+            if (parsed.length)
+                query = parsed;
+        }
+        else if (currentTag === "params" && line.length > 0 && !line.startsWith("@")) {
+            var parsed = parseTypeFromLineOrBlock(line);
+            if (parsed.length)
+                paramsFromJSDoc = parsed;
+        }
+        else if (!seenAnyTag && line.length > 0) {
+            descriptionLines.push(line);
+        }
+    }
+    var description = descriptionLines.length > 0 ? descriptionLines.join(" ").trim() : undefined;
+    var responses = parseResponseTag(block);
+    var params = (paramsFromJSDoc === null || paramsFromJSDoc === void 0 ? void 0 : paramsFromJSDoc.length) ? paramsFromJSDoc : extractParamsFromPath(routePath);
+    return {
+        description: description,
+        request: (request === null || request === void 0 ? void 0 : request.length) ? request : undefined,
+        query: (query === null || query === void 0 ? void 0 : query.length) ? query : undefined,
+        params: params.length ? params : undefined,
+        responses: responses.length ? responses : undefined,
+    };
+}
+/** Extract path param names from route path (e.g. /users/:id/posts/:postId → id, postId). */
+function extractParamsFromPath(routePath) {
+    var params = [];
+    var paramReg = /:(\w+)/g;
+    var m;
+    while ((m = paramReg.exec(routePath)) !== null) {
+        params.push({
+            name: m[1],
+            type: "string",
+            required: true,
+        });
+    }
+    return params;
+}
+/**
+ * Find the block comment that ends immediately before position (closest above).
+ */
+function getCommentBefore(content, position) {
+    var blocks = [];
+    var match;
+    BLOCK_COMMENT_REG.lastIndex = 0;
+    while ((match = BLOCK_COMMENT_REG.exec(content)) !== null) {
+        var end = match.index + match[0].length;
+        if (end <= position) {
+            blocks.push({ end: end, body: match[1] });
+        }
+    }
+    if (blocks.length === 0)
+        return null;
+    var closest = blocks.reduce(function (a, b) { return (b.end > a.end ? b : a); });
+    return closest.body;
+}
+/**
+ * Parse a single file and extract route registrations with their preceding JSDoc.
+ * Uses format: @description, @request { type }, @response [...], @query { type }.
+ * Path params are extracted from the route path.
+ */
+function parseFileForRouteJSDoc(filePath) {
+    var _a, _b, _c, _d;
+    var absolutePath = path_1.default.resolve(filePath);
+    var content;
+    try {
+        content = fs_1.default.readFileSync(absolutePath, "utf-8");
+    }
+    catch (_e) {
+        return [];
+    }
+    var results = [];
+    var match;
+    ROUTE_REG.lastIndex = 0;
+    while ((match = ROUTE_REG.exec(content)) !== null) {
+        var method = match[1].toUpperCase();
+        var routePath = match[2].trim();
+        var fullPath = routePath.startsWith("/") ? routePath : "/".concat(routePath);
+        if (!ROUTE_METHODS.includes(match[1].toLowerCase()))
+            continue;
+        var comment = getCommentBefore(content, match.index);
+        var meta = {
+            method: method,
+            path: fullPath,
+        };
+        if (comment) {
+            var parsed = parseJSDocBlock(comment, fullPath);
+            if (parsed.description)
+                meta.description = parsed.description;
+            if ((_a = parsed.request) === null || _a === void 0 ? void 0 : _a.length)
+                meta.request = parsed.request;
+            if ((_b = parsed.query) === null || _b === void 0 ? void 0 : _b.length)
+                meta.query = parsed.query;
+            if ((_c = parsed.params) === null || _c === void 0 ? void 0 : _c.length)
+                meta.params = parsed.params;
+            if ((_d = parsed.responses) === null || _d === void 0 ? void 0 : _d.length)
+                meta.responses = parsed.responses;
+        }
+        else {
+            var pathParams = extractParamsFromPath(fullPath);
+            meta.params = pathParams.length ? pathParams : undefined;
+        }
+        results.push(meta);
+    }
+    return results;
+}
+/**
+ * Parse multiple files and return TraceletMeta[] for each route found.
+ */
+function parseRouteFiles(filePaths) {
+    var seen = new Set();
+    var out = [];
+    var _loop_1 = function (fp) {
+        var resolved = path_1.default.resolve(fp);
+        var stat = fs_1.default.existsSync(resolved) ? fs_1.default.statSync(resolved) : null;
+        if (stat === null || stat === void 0 ? void 0 : stat.isDirectory()) {
+            var entries = fs_1.default.readdirSync(resolved, { withFileTypes: true });
+            var files = entries
+                .filter(function (e) { return e.isFile() && /\.(js|ts|mjs|cjs)$/.test(e.name); })
+                .map(function (e) { return path_1.default.join(resolved, e.name); });
+            for (var _a = 0, files_1 = files; _a < files_1.length; _a++) {
+                var f = files_1[_a];
+                var metas = parseFileForRouteJSDoc(f);
+                for (var _b = 0, metas_1 = metas; _b < metas_1.length; _b++) {
+                    var m = metas_1[_b];
+                    var key = "".concat(m.method, ":").concat(m.path);
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        out.push(m);
+                    }
+                }
+            }
+        }
+        else {
+            var metas = parseFileForRouteJSDoc(resolved);
+            for (var _c = 0, metas_2 = metas; _c < metas_2.length; _c++) {
+                var m = metas_2[_c];
+                var key = "".concat(m.method, ":").concat(m.path);
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    out.push(m);
+                }
+            }
+        }
+    };
+    for (var _i = 0, filePaths_1 = filePaths; _i < filePaths_1.length; _i++) {
+        var fp = filePaths_1[_i];
+        _loop_1(fp);
+    }
+    return out;
+}
+/**
+ * Build a parent-child route tree with PARENT grouping nodes.
+ * - If routes are /user, /user/:id, /user/:id/posts → parent is /user (method PARENT), children are those three with their methods.
+ * - If routes are only /user/:id, /user/:id/posts → parent is /user/:id (method PARENT), children are those two with their methods.
+ */
+function buildRouteTree(flat) {
+    var _a;
+    var normalized = flat.map(function (r) { return (__assign(__assign({}, r), { path: (r.path.startsWith("/") ? r.path : "/".concat(r.path)).replace(/\/+/g, "/") || "/" })); });
+    var pathSet = new Set(normalized.map(function (r) { return r.path; }));
+    var pathList = Array.from(pathSet);
+    /** Longest path in pathSet that is a strict prefix of path, or null. */
+    function groupParent(path) {
+        var best = null;
+        for (var _i = 0, pathList_1 = pathList; _i < pathList_1.length; _i++) {
+            var p = pathList_1[_i];
+            if (path !== p && path.startsWith(p + "/") && (best === null || p.length > best.length)) {
+                best = p;
+            }
+        }
+        return best;
+    }
+    var groups = new Map();
+    for (var _i = 0, normalized_1 = normalized; _i < normalized_1.length; _i++) {
+        var r = normalized_1[_i];
+        var p = groupParent(r.path);
+        if (p !== null) {
+            var list = (_a = groups.get(p)) !== null && _a !== void 0 ? _a : [];
+            list.push(r);
+            groups.set(p, list);
+        }
+    }
+    var roots = normalized.filter(function (r) { return groupParent(r.path) === null; });
+    function toRelativePath(fullPath, parentPath) {
+        var rel = fullPath.slice(parentPath.length).replace(/^\//, "") || "";
+        return rel ? "/".concat(rel) : "/";
+    }
+    function buildGroupNode(parentPath, routeMeta, childrenPaths) {
+        var childNodes = [];
+        if (routeMeta) {
+            childNodes.push(__assign(__assign({}, routeMeta), { path: toRelativePath(routeMeta.path, parentPath) }));
+        }
+        var _loop_2 = function (c) {
+            var directChildren = groups.get(c.path);
+            if (directChildren && directChildren.length > 0) {
+                var selfRoute = normalized.find(function (r) { return r.path === c.path; });
+                var nested = buildGroupNode(c.path, selfRoute, directChildren);
+                childNodes.push(__assign(__assign({}, nested), { path: toRelativePath(c.path, parentPath) }));
+            }
+            else {
+                childNodes.push(__assign(__assign({}, c), { path: toRelativePath(c.path, parentPath) }));
+            }
+        };
+        for (var _i = 0, childrenPaths_1 = childrenPaths; _i < childrenPaths_1.length; _i++) {
+            var c = childrenPaths_1[_i];
+            _loop_2(c);
+        }
+        return {
+            method: "PARENT",
+            path: parentPath,
+            routes: childNodes,
+        };
+    }
+    var result = [];
+    for (var _b = 0, roots_1 = roots; _b < roots_1.length; _b++) {
+        var r = roots_1[_b];
+        var directChildren = groups.get(r.path);
+        if (directChildren && directChildren.length > 0) {
+            result.push(buildGroupNode(r.path, r, directChildren));
+        }
+        else {
+            result.push(__assign({}, r));
+        }
+    }
+    return result;
+}

package/dist/middleware.d.ts

@@ -0,0 +1,7 @@
+import type { Request, Response, NextFunction } from "express";
+interface TraceletExpressOptions {
+    serviceName: string;
+    environment?: string;
+}
+export declare function traceletMiddleware(options: TraceletExpressOptions): (req: Request, res: Response, next: NextFunction) => void;
+export {};

package/dist/middleware.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceletMiddleware = traceletMiddleware;
+var core_1 = require("@tracelet/core");
+var collectedRoutes = [];
+function traceletMiddleware(options) {
+    var _a;
+    var logger = (0, core_1.createLogger)({
+        serviceName: options.serviceName,
+        environment: (_a = options.environment) !== null && _a !== void 0 ? _a : "prod",
+    });
+    return function (req, res, next) {
+        var startTime = process.hrtime.bigint();
+        var tracingId = logger.createTracingId();
+        req.traceletRequestId = tracingId;
+        req.traceletTracingId = tracingId;
+        req.traceletLogger = logger;
+        res.on("finish", function () {
+            var _a;
+            var path = req.originalUrl.split("?")[0];
+            var route = ((_a = req.route) === null || _a === void 0 ? void 0 : _a.path) || req.baseUrl + req.path || req.originalUrl;
+            if (path === "/tracelet-docs" || path.startsWith("/tracelet-docs/") || route.startsWith("undefined")) {
+                return;
+            }
+            var endTime = process.hrtime.bigint();
+            var durationMs = Number(endTime - startTime) / 1000000;
+            var rawSize = res.getHeader("content-length");
+            var responseSize = typeof rawSize === "string" || typeof rawSize === "number"
+                ? rawSize
+                : 0;
+            logger.logHttp({
+                requestId: tracingId,
+                tracingId: tracingId,
+                method: req.method,
+                route: route,
+                statusCode: res.statusCode,
+                durationMs: durationMs,
+                responseSize: responseSize,
+            });
+            if (!collectedRoutes.some(function (r) { return r.method === req.method && r.path === route; })) {
+                collectedRoutes.push({ method: req.method, path: route });
+            }
+        });
+        next();
+    };
+}

package/dist/routeDiscovery.d.ts

@@ -0,0 +1,9 @@
+import type { Application } from "express";
+/**
+ * Returns all routes registered on the Express app (and nested routers).
+ * Uses Express internal router stack; works with Express 4 and 5.
+ */
+export declare function getExpressRoutes(app: Application): {
+    method: string;
+    path: string;
+}[];

package/dist/routeDiscovery.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getExpressRoutes = getExpressRoutes;
+/**
+ * Returns all routes registered on the Express app (and nested routers).
+ * Uses Express internal router stack; works with Express 4 and 5.
+ */
+function getExpressRoutes(app) {
+    var routes = [];
+    var router = app.router;
+    if (!(router === null || router === void 0 ? void 0 : router.stack))
+        return routes;
+    function walk(stack, prefix) {
+        var _a;
+        if (prefix === void 0) { prefix = ""; }
+        for (var _i = 0, stack_1 = stack; _i < stack_1.length; _i++) {
+            var layer = stack_1[_i];
+            if (layer.route) {
+                var path = (prefix + layer.route.path).replace(/\/+/g, "/") || "/";
+                var methods = Object.keys(layer.route.methods).filter(function (m) { return m !== "_all"; });
+                for (var _b = 0, methods_1 = methods; _b < methods_1.length; _b++) {
+                    var method = methods_1[_b];
+                    if (method !== "head") {
+                        routes.push({ method: method.toUpperCase(), path: path });
+                    }
+                }
+            }
+            else if (layer.name === "router" && ((_a = layer.handle) === null || _a === void 0 ? void 0 : _a.stack)) {
+                var segment = typeof layer.path === "string" ? layer.path : "";
+                walk(layer.handle.stack, prefix + segment);
+            }
+        }
+    }
+    walk(router.stack);
+    return routes;
+}

package/dist/traceletDoc/handler/auth.d.ts

@@ -0,0 +1,4 @@
+declare const auth: import("@tracelet/core").Auth;
+declare const authRouter: import("express-serve-static-core").Router;
+export default authRouter;
+export { auth };

package/dist/traceletDoc/handler/auth.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auth = void 0;
+var core_1 = require("@tracelet/core");
+var express_1 = __importDefault(require("express"));
+var auth = (0, core_1.createAuth)();
+exports.auth = auth;
+var authRouter = express_1.default.Router();
+authRouter.get("/check-auth", function (_req, res) {
+    res.status(200).json({ authRequired: auth.isAuthRequired() });
+});
+/** POST body: { username, password }. Returns { token } (JWT) on success, 401 on failure. */
+authRouter.post("/auth", function (req, res) {
+    var _a;
+    var _b = (_a = req.body) !== null && _a !== void 0 ? _a : {}, username = _b.username, password = _b.password;
+    if (typeof username !== "string" || typeof password !== "string") {
+        return res.status(400).json({ error: "username and password required" });
+    }
+    if (!auth.authenticate(username, password)) {
+        return res.status(401).json({ error: "Invalid credentials" });
+    }
+    try {
+        var token = auth.createToken(username);
+        return res.status(200).json({ token: token });
+    }
+    catch (e) {
+        return res.status(500).json({ error: "Failed to create token" });
+    }
+});
+/** GET for backward compat: pass ?username=...&password=... (less secure). Prefer POST /auth. */
+authRouter.get("/auth", function (req, res) {
+    var username = req.query.username;
+    var password = req.query.password;
+    if (!username || !password) {
+        return res.status(400).json({ error: "username and password required" });
+    }
+    if (!auth.authenticate(username, password)) {
+        return res.status(401).json({ error: "Invalid credentials" });
+    }
+    try {
+        var token = auth.createToken(username);
+        return res.status(200).json({ token: token });
+    }
+    catch (e) {
+        return res.status(500).json({ error: "Failed to create token" });
+    }
+});
+exports.default = authRouter;

package/dist/traceletDoc/handlers/auth.d.ts

@@ -0,0 +1,2 @@
+declare const authRouter: import("express-serve-static-core").Router;
+export default authRouter;

package/dist/traceletDoc/handlers/auth.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var core_1 = require("@tracelet/core");
+var express_1 = __importDefault(require("express"));
+var authRouter = express_1.default.Router();
+authRouter.get("/check-auth", function (req, res) {
+    var TRACELET_DOC_USERNAME = (0, core_1.getEnv)("TRACELET_DOC_USERNAME");
+    var TRACELET_DOC_PASSWORD = (0, core_1.getEnv)("TRACELET_DOC_PASSWORD");
+    if (TRACELET_DOC_USERNAME && TRACELET_DOC_PASSWORD) {
+        res.status(200).json({ authRequired: true });
+    }
+    else {
+        res.status(200).json({ authRequired: false });
+    }
+});
+authRouter.get("/auth", function (req, res) {
+    res.json({ ok: true });
+});
+exports.default = authRouter;

package/dist/traceletDoc/index.d.ts

@@ -0,0 +1,12 @@
+import { type Application } from "express";
+import { type TraceletMeta } from "@tracelet/core";
+/** Options for the tracelet docs UI. */
+export interface TraceletDocOptions {
+    /** Path to JSON file for route meta (e.g. tracelet.doc.json). Defaults to `tracelet.doc.json` in process.cwd(). */
+    docFilePath?: string;
+}
+/**
+ * Mounts the Tracelet docs UI on the given Express app.
+ * Creates a route at `path` (default `/tracelet-docs`) serving the built UI and `?json=true` for route meta.
+ */
+export declare function traceletDoc(app: Application, meta?: TraceletMeta[], options?: TraceletDocOptions): void;

package/dist/traceletDoc/index.js

@@ -0,0 +1,90 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceletDoc = traceletDoc;
+var express_1 = __importDefault(require("express"));
+var core_1 = require("@tracelet/core");
+var fs_1 = __importDefault(require("fs"));
+var path_1 = __importDefault(require("path"));
+var auth_1 = __importStar(require("./handler/auth"));
+var DEFAULT_DOCS_PATH = "/tracelet-docs";
+/**
+ * Mounts the Tracelet docs UI on the given Express app.
+ * Creates a route at `path` (default `/tracelet-docs`) serving the built UI and `?json=true` for route meta.
+ */
+function traceletDoc(app, meta, options) {
+    var _a;
+    if (meta === void 0) { meta = []; }
+    if (options === void 0) { options = {}; }
+    var routeMeta = (0, core_1.createRouteMeta)();
+    var mountPath = DEFAULT_DOCS_PATH;
+    var uiPath = path_1.default.resolve((0, core_1.resolveDefaultUiPath)());
+    var indexHtml = path_1.default.join(uiPath, "index.html");
+    var staticHandler = express_1.default.static(uiPath, { index: false });
+    var docFilePath = (_a = options.docFilePath) !== null && _a !== void 0 ? _a : path_1.default.join(process.cwd(), routeMeta.defaultDocFile);
+    var resolvedMeta = routeMeta.loadAndMerge(docFilePath, meta !== null && meta !== void 0 ? meta : []);
+    var handler = function (req, res, next) {
+        if (req.query.json === "true") {
+            if (!auth_1.auth.isAuthRequired()) {
+                return res.json(routeMeta.resolveTree(resolvedMeta));
+            }
+            if (auth_1.auth.isAuthRequired() && auth_1.auth.verifyRequest(req.headers.authorization)) {
+                return res.json(routeMeta.resolveTree(resolvedMeta));
+            }
+            return res.status(401).json({ error: "Unauthorized" });
+        }
+        if (req.method !== "GET" && req.method !== "HEAD") {
+            return next();
+        }
+        staticHandler(req, res, function (err) {
+            if (err)
+                return next(err);
+            if (res.headersSent)
+                return;
+            if (!fs_1.default.existsSync(indexHtml)) {
+                return res
+                    .status(500)
+                    .set("Content-Type", "text/plain")
+                    .send("Tracelet UI not found. Build the UI or set uiPath." + indexHtml);
+            }
+            res.sendFile(indexHtml);
+        });
+    };
+    app.use(mountPath, auth_1.default);
+    app.use(mountPath, handler);
+}

package/dist/traceletDoc/routeDiscovery.d.ts

@@ -0,0 +1,33 @@
+import type express from "express";
+export declare function captureAppMountPaths(app: express.Application): void;
+/** Express router layer (internal shape). */
+interface RouterLayer {
+    route?: {
+        path: string;
+        methods: Record<string, boolean>;
+    };
+    name?: string;
+    path?: string;
+    handle?: {
+        stack?: RouterLayer[];
+        mountpath?: string;
+    };
+    regexp?: RegExp;
+    matchers?: ((path: string) => {
+        path: string;
+        params: Record<string, string>;
+    } | false)[];
+}
+/** Resolver for router mount path: (layer) => path string, or string[] of paths to try / use in order. */
+export type RouterMountPathResolver = ((layer: RouterLayer) => string) | string[];
+/**
+ * Returns all routes registered on the Express app (and nested routers).
+ * Call captureAppMountPaths(app) right after creating the app and before mounting any routers
+ * so nested mount paths are resolved. Or pass routerMountPathResolver to supply mount paths
+ * (function or array of path strings to try / use in order).
+ */
+export declare function getExpressRoutes(app: express.Application, routerMountPathResolver?: RouterMountPathResolver): {
+    method: string;
+    path: string;
+}[];
+export {};

package/dist/traceletDoc/routeDiscovery.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureAppMountPaths = captureAppMountPaths;
+exports.getExpressRoutes = getExpressRoutes;
+/**
+ * Alternative way to get routes: capture mount paths when app.use(path, router) is called.
+ * Call captureAppMountPaths(app) right after creating the app and before mounting any routers.
+ * Then getExpressRoutes(app) will use the captured paths for router layers (no resolver needed).
+ */
+var mountPathByHandle = new WeakMap();
+function captureAppMountPaths(app) {
+    var originalUse = app.use.bind(app);
+    app.use = function use() {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var path = typeof args[0] === "string" ? args[0] : "/";
+        var start = typeof args[0] === "string" ? 1 : 0;
+        for (var i = start; i < args.length; i++) {
+            var fn = args[i];
+            if (fn && typeof fn === "function")
+                mountPathByHandle.set(fn, path);
+        }
+        return originalUse.apply(this, args);
+    };
+}
+/**
+ * Regex to extract a mount path from a layer's regexp.source when present.
+ */
+var MOUNT_PATH_FROM_REGEXP_SOURCE = /^\^\\\/((?:[^\\\[\](){}|*+?^$]|\\.)*?)(?:\$|\\\/|\()/;
+/**
+ * Get the mount path for a router layer: captured path (from captureAppMountPaths),
+ * layer.path, handle.mountpath, regexp extraction, then try matcher with candidates, then resolver.
+ */
+function getMountPath(layer, resolver, mountPathIndex) {
+    var _a, _b, _c;
+    var handle = layer.handle;
+    if (handle && mountPathByHandle.has(handle))
+        return mountPathByHandle.get(handle);
+    if (typeof layer.path === "string" && layer.path.length > 0)
+        return layer.path;
+    var h = handle;
+    if (h === null || h === void 0 ? void 0 : h.mountpath)
+        return h.mountpath;
+    var src = (_a = layer.regexp) === null || _a === void 0 ? void 0 : _a.source;
+    if (src) {
+        var m = src.match(MOUNT_PATH_FROM_REGEXP_SOURCE);
+        if (m === null || m === void 0 ? void 0 : m[1])
+            return "/" + m[1].replace(/\\\//g, "/");
+    }
+    var matchers = layer.matchers;
+    if (Array.isArray(resolver) && (matchers === null || matchers === void 0 ? void 0 : matchers[0])) {
+        for (var _i = 0, resolver_1 = resolver; _i < resolver_1.length; _i++) {
+            var candidate = resolver_1[_i];
+            if (candidate && matchers[0](candidate))
+                return candidate;
+        }
+        return (_b = resolver[mountPathIndex]) !== null && _b !== void 0 ? _b : "";
+    }
+    if (resolver === undefined)
+        return "";
+    return typeof resolver === "function"
+        ? resolver(layer)
+        : (_c = resolver[mountPathIndex]) !== null && _c !== void 0 ? _c : "";
+}
+/**
+ * Returns all routes registered on the Express app (and nested routers).
+ * Call captureAppMountPaths(app) right after creating the app and before mounting any routers
+ * so nested mount paths are resolved. Or pass routerMountPathResolver to supply mount paths
+ * (function or array of path strings to try / use in order).
+ */
+function getExpressRoutes(app, routerMountPathResolver) {
+    var routes = [];
+    var router = app.router;
+    if (!(router === null || router === void 0 ? void 0 : router.stack))
+        return routes;
+    var mountPathIndex = 0;
+    function walk(stack, prefix) {
+        var _a, _b;
+        if (prefix === void 0) { prefix = ""; }
+        for (var _i = 0, stack_1 = stack; _i < stack_1.length; _i++) {
+            var layer = stack_1[_i];
+            if (layer.route) {
+                var path = (prefix + layer.route.path).replace(/\/+/g, "/") || "/";
+                var methods = Object.keys(layer.route.methods).filter(function (m) { return m !== "_all"; });
+                for (var _c = 0, methods_1 = methods; _c < methods_1.length; _c++) {
+                    var method = methods_1[_c];
+                    if (method !== "head")
+                        routes.push({ method: method.toUpperCase(), path: path });
+                }
+            }
+            else if ((layer.name === "router" || ((_a = layer.handle) === null || _a === void 0 ? void 0 : _a.stack)) && ((_b = layer.handle) === null || _b === void 0 ? void 0 : _b.stack)) {
+                var segment = getMountPath(layer, routerMountPathResolver, mountPathIndex);
+                if (Array.isArray(routerMountPathResolver))
+                    mountPathIndex++;
+                var nextPrefix = (prefix + segment).replace(/\/+/g, "/") || "/";
+                walk(layer.handle.stack, nextPrefix);
+            }
+        }
+    }
+    walk(router.stack);
+    return routes;
+}

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+import type { Logger } from "@tracelet/core";
+declare global {
+    namespace Express {
+        interface Request {
+            traceletRequestId?: string;
+            traceletTracingId?: string;
+            traceletLogger: Logger;
+        }
+    }
+}
+/** Re-export meta types from core so consumers can keep importing from @tracelet/express */
+export type { RequestContentType, TraceletMeta, TraceletHttpMethod, TraceletProperty, TraceletResponseProperty, } from "@tracelet/core";
+/** Map of field name to type/schema (query, params – simple key/value) */
+export type TraceletSchema = Record<string, string>;
+export {};

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+// Express type augmentation for Tracelet.
+//
+// This file is imported by `src/index.ts` so that consumers automatically get
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@tracelet/express",
+  "version": "0.0.1",
+  "description": "Express middleware for Tracelet",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "src/types.d.ts"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@tracelet/core": "^0.0.1",
+    "@tracelet/ui": "^0.0.1",
+    "express": "^5.2.1"
+  },
+  "peerDependencies": {
+    "express": "^4 || ^5"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tracelethq/tracelet.git",
+    "directory": "packages/sdk-express"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.2.1",
+    "typescript": "^5.9.3"
+  }
+}