@beignet/devtools 0.0.1

package/dist/routes.js

@@ -0,0 +1,247 @@
+/**
+ * HTTP handlers for devtools API
+ *
+ * These handlers can be used to expose devtools data via HTTP endpoints
+ * in Next.js or any other framework that uses the Fetch API Request/Response.
+ */
+import { authorizeDevtoolsRequest, } from "./access";
+import { isDevtoolsEventType } from "./events";
+import { handleDevtoolsUIRequest } from "./ui";
+/**
+ * Handle GET requests to list devtools events with optional filtering.
+ *
+ * Query parameters:
+ * - type: Filter by event type (request, error, usecase, eventBus, job, schedule, provider)
+ * - requestId: Filter by request correlation ID
+ * - traceId: Filter by W3C trace ID
+ * - limit: Maximum number of events to return (default: 200)
+ *
+ * @param req - The incoming HTTP request
+ * @param devtools - The DevtoolsPort instance to query
+ * @returns JSON response with events array
+ *
+ * @example
+ * ```ts
+ * // In a Next.js route handler:
+ * // app/api/devtools/core/events/route.ts
+ * import { handleDevtoolsEventsRequest } from "@beignet/devtools";
+ *
+ * export async function GET(req: Request) {
+ *   const devtools = getAppDevtoolsPort(); // app-specific helper
+ *   return handleDevtoolsEventsRequest(req, devtools);
+ * }
+ * ```
+ */
+export async function handleDevtoolsEventsRequest(req, devtools, options = {}) {
+    const denied = await authorizeDevtoolsRequest(req, options);
+    if (denied)
+        return denied;
+    const url = new URL(req.url);
+    const type = url.searchParams.get("type");
+    const requestId = url.searchParams.get("requestId");
+    const traceId = url.searchParams.get("traceId");
+    const limitParam = url.searchParams.get("limit");
+    if (type !== null && !isDevtoolsEventType(type)) {
+        return new Response(JSON.stringify({ error: "Invalid event type" }), {
+            status: 400,
+            headers: {
+                "Content-Type": "application/json",
+                "Cache-Control": "no-store",
+            },
+        });
+    }
+    let limit;
+    if (limitParam !== null) {
+        const parsed = Number.parseInt(limitParam, 10);
+        if (!Number.isNaN(parsed)) {
+            limit = parsed;
+        }
+    }
+    const filter = {
+        type: type ?? undefined,
+        requestId: requestId ?? undefined,
+        traceId: traceId ?? undefined,
+        limit,
+    };
+    const events = devtools.getEvents(filter);
+    return new Response(JSON.stringify({
+        events,
+        watchers: devtools.getWatchers(),
+    }), {
+        status: 200,
+        headers: {
+            "Content-Type": "application/json",
+            "Cache-Control": "no-store",
+        },
+    });
+}
+/**
+ * Handle POST requests to clear all devtools events.
+ *
+ * This endpoint requires a POST request and will clear the in-memory event buffer.
+ *
+ * @param req - The incoming HTTP request
+ * @param devtools - The DevtoolsPort instance to clear
+ * @returns JSON response with success status
+ *
+ * @example
+ * ```ts
+ * // In a Next.js route handler:
+ * // app/api/devtools/clear/route.ts
+ * import { handleDevtoolsClearRequest } from "@beignet/devtools";
+ *
+ * export async function POST(req: Request) {
+ *   const devtools = getAppDevtoolsPort(); // app-specific helper
+ *   return handleDevtoolsClearRequest(req, devtools);
+ * }
+ * ```
+ */
+export async function handleDevtoolsClearRequest(req, devtools, options = {}) {
+    const denied = await authorizeDevtoolsRequest(req, options);
+    if (denied)
+        return denied;
+    if (req.method !== "POST") {
+        return new Response("Method Not Allowed", { status: 405 });
+    }
+    await devtools.clear();
+    return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: {
+            "Content-Type": "application/json",
+            "Cache-Control": "no-store",
+        },
+    });
+}
+function encodeSse(event, data) {
+    return new TextEncoder().encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+}
+/**
+ * Handle GET requests for a live Server-Sent Events stream.
+ *
+ * The stream emits:
+ * - `snapshot` with the current event buffer
+ * - `event` when a new event is recorded
+ * - `clear` when the buffer is cleared
+ */
+export async function handleDevtoolsStreamRequest(req, devtools, options = {}) {
+    const denied = await authorizeDevtoolsRequest(req, options);
+    if (denied)
+        return denied;
+    if (req.method !== "GET") {
+        return new Response("Method Not Allowed", { status: 405 });
+    }
+    let unsubscribe;
+    const stream = new ReadableStream({
+        start(controller) {
+            let closed = false;
+            const enqueue = (event, data) => {
+                if (closed)
+                    return;
+                try {
+                    controller.enqueue(encodeSse(event, data));
+                }
+                catch {
+                    closed = true;
+                }
+            };
+            enqueue("snapshot", {
+                events: devtools.getEvents({ limit: 500 }),
+                watchers: devtools.getWatchers(),
+            });
+            unsubscribe = devtools.subscribe((event) => {
+                if (event.type === "record") {
+                    enqueue("event", { event: event.event });
+                    return;
+                }
+                enqueue("clear", { ok: true });
+            });
+            req.signal.addEventListener("abort", () => {
+                closed = true;
+                unsubscribe?.();
+                try {
+                    controller.close();
+                }
+                catch {
+                    // The stream may already be closed by the client.
+                }
+            }, { once: true });
+        },
+        cancel() {
+            unsubscribe?.();
+        },
+    });
+    return new Response(stream, {
+        status: 200,
+        headers: {
+            "Content-Type": "text/event-stream; charset=utf-8",
+            "Cache-Control": "no-store, no-transform",
+            Connection: "keep-alive",
+        },
+    });
+}
+/**
+ * Unified devtools request handler.
+ *
+ * Routes requests to the appropriate handler based on the URL path:
+ * - `{basePath}/core/events` → event list (GET)
+ * - `{basePath}/stream` → live event stream (GET)
+ * - `{basePath}/clear` → clear buffer (POST)
+ * - `{basePath}` → dashboard UI (GET)
+ *
+ * This lets you wire up a single catch-all route instead of three separate ones.
+ *
+ * @param req - The incoming HTTP request
+ * @param devtools - The DevtoolsPort instance
+ * @param options - Devtools route options including base path and access policy
+ * @returns Response for the matched sub-route
+ *
+ * @example
+ * ```ts
+ * // Next.js catch-all route: app/api/devtools/[[...path]]/route.ts
+ * import { createDevtoolsRoute } from "@beignet/devtools";
+ * import { getDevtools } from "@/server";
+ *
+ * export const { GET, POST } = createDevtoolsRoute(getDevtools(), {
+ *   basePath: "/api/devtools",
+ * });
+ * ```
+ */
+export async function handleDevtoolsRequest(req, devtools, options) {
+    const denied = await authorizeDevtoolsRequest(req, options);
+    if (denied)
+        return denied;
+    const url = new URL(req.url);
+    const path = url.pathname.replace(/\/+$/, "");
+    const normalizedBase = options.basePath.replace(/\/+$/, "");
+    const accessChecked = { enabled: true };
+    if (path === `${normalizedBase}/core/events`) {
+        return handleDevtoolsEventsRequest(req, devtools, accessChecked);
+    }
+    if (path === `${normalizedBase}/clear`) {
+        return handleDevtoolsClearRequest(req, devtools, accessChecked);
+    }
+    if (path === `${normalizedBase}/stream`) {
+        return handleDevtoolsStreamRequest(req, devtools, accessChecked);
+    }
+    if (path === normalizedBase) {
+        if (req.method !== "GET") {
+            return new Response("Method Not Allowed", { status: 405 });
+        }
+        return handleDevtoolsUIRequest(options.basePath, accessChecked);
+    }
+    return new Response("Not Found", { status: 404 });
+}
+/**
+ * Create GET and POST handlers for a devtools catch-all route.
+ *
+ * This is the recommended integration for frameworks such as Next.js that
+ * export HTTP method functions from route modules.
+ */
+export function createDevtoolsRoute(devtools, options) {
+    const handle = (req) => handleDevtoolsRequest(req, devtools, options);
+    return {
+        GET: handle,
+        POST: handle,
+    };
+}
+//# sourceMappingURL=routes.js.map

package/dist/routes.js.map

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

package/dist/trace-context.d.ts

@@ -0,0 +1,29 @@
+export interface DevtoolsTraceContext {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    traceparent: string;
+}
+export interface ParsedTraceparent {
+    traceId: string;
+    spanId: string;
+    traceFlags: string;
+    traceparent: string;
+}
+export interface DevtoolsTraceContextInput {
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    traceparent?: string;
+}
+export declare function createTraceId(): string;
+export declare function createSpanId(): string;
+export declare function createTraceparent(args: {
+    traceId: string;
+    spanId: string;
+    traceFlags?: string;
+}): string;
+export declare function parseTraceparent(value: string | null | undefined): ParsedTraceparent | undefined;
+export declare function createDevtoolsTraceContext(input?: DevtoolsTraceContextInput): DevtoolsTraceContext;
+export declare function createChildDevtoolsTraceContext(parent: DevtoolsTraceContextInput): DevtoolsTraceContext;
+//# sourceMappingURL=trace-context.d.ts.map

package/dist/trace-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context.d.ts","sourceRoot":"","sources":["../src/trace-context.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAsBD,wBAAgB,aAAa,IAAI,MAAM,CAMtC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAMrC;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAET;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,iBAAiB,GAAG,SAAS,CAe/B;AAED,wBAAgB,0BAA0B,CACxC,KAAK,GAAE,yBAA8B,GACpC,oBAAoB,CAgBtB;AAED,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,yBAAyB,GAChC,oBAAoB,CAMtB"}

package/dist/trace-context.js

@@ -0,0 +1,74 @@
+const TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+function createHexId(length) {
+    const bytes = new Uint8Array(length / 2);
+    if (typeof crypto !== "undefined" && "getRandomValues" in crypto) {
+        crypto.getRandomValues(bytes);
+        return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    }
+    let value = "";
+    while (value.length < length) {
+        value += Math.floor(Math.random() * 16).toString(16);
+    }
+    return value.slice(0, length);
+}
+function isNonZeroHex(value) {
+    return !/^0+$/.test(value);
+}
+export function createTraceId() {
+    let traceId = createHexId(32);
+    while (!isNonZeroHex(traceId)) {
+        traceId = createHexId(32);
+    }
+    return traceId;
+}
+export function createSpanId() {
+    let spanId = createHexId(16);
+    while (!isNonZeroHex(spanId)) {
+        spanId = createHexId(16);
+    }
+    return spanId;
+}
+export function createTraceparent(args) {
+    return `00-${args.traceId}-${args.spanId}-${args.traceFlags ?? "01"}`;
+}
+export function parseTraceparent(value) {
+    if (!value)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    const match = TRACEPARENT_PATTERN.exec(normalized);
+    if (!match)
+        return undefined;
+    const [, traceId, spanId, traceFlags] = match;
+    if (!isNonZeroHex(traceId) || !isNonZeroHex(spanId))
+        return undefined;
+    return {
+        traceId,
+        spanId,
+        traceFlags,
+        traceparent: normalized,
+    };
+}
+export function createDevtoolsTraceContext(input = {}) {
+    const parsed = parseTraceparent(input.traceparent);
+    const traceId = input.traceId ?? parsed?.traceId ?? createTraceId();
+    const parentSpanId = input.parentSpanId ?? parsed?.spanId;
+    const spanId = input.spanId ?? createSpanId();
+    return {
+        traceId,
+        spanId,
+        ...(parentSpanId ? { parentSpanId } : {}),
+        traceparent: createTraceparent({
+            traceId,
+            spanId,
+            traceFlags: parsed?.traceFlags,
+        }),
+    };
+}
+export function createChildDevtoolsTraceContext(parent) {
+    return createDevtoolsTraceContext({
+        traceId: parent.traceId,
+        parentSpanId: parent.spanId,
+        traceparent: parent.traceparent,
+    });
+}
+//# sourceMappingURL=trace-context.js.map

package/dist/trace-context.js.map

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

package/dist/ui.d.ts

@@ -0,0 +1,14 @@
+import { type DevtoolsRouteAccessOptions } from "./access";
+/**
+ * Devtools UI handler
+ *
+ * Serves a self-contained HTML dashboard for viewing devtools events.
+ */
+/**
+ * Handle requests for the devtools dashboard UI.
+ *
+ * @param basePath - The URL path prefix where devtools routes are mounted (e.g. "/api/devtools")
+ * @returns HTML response with the devtools dashboard
+ */
+export declare function handleDevtoolsUIRequest(basePath: string, options?: DevtoolsRouteAccessOptions): Response;
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,0BAA0B,EAGhC,MAAM,UAAU,CAAC;AAElB;;;;GAIG;AAEH;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,0BAA+B,GACvC,QAAQ,CAWV"}