@beignet/devtools 0.0.1 → 0.0.2

package/src/events.ts

@@ -156,14 +156,23 @@ export type DevtoolsEvent =
   | ProviderEvent
   | CustomDevtoolsEvent;
 
+/**
+ * Input accepted by `createDevtoolsEvent(...)`.
+ */
 export type DevtoolsEventInput = DevtoolsEvent extends infer Event
   ? Event extends DevtoolsEvent
     ? Omit<Event, "id" | "timestamp"> & Partial<Pick<Event, "id" | "timestamp">>
     : never
   : never;
 
+/**
+ * Function that redacts a normalized devtools event before storage.
+ */
 export type DevtoolsRedactor = (event: DevtoolsEvent) => DevtoolsEvent;
 
+/**
+ * Event emitted to live devtools subscribers.
+ */
 export type DevtoolsSubscriptionEvent =
   | {
       type: "record";
@@ -173,8 +182,14 @@ export type DevtoolsSubscriptionEvent =
       type: "clear";
     };
 
+/**
+ * Devtools subscription listener.
+ */
 export type DevtoolsListener = (event: DevtoolsSubscriptionEvent) => void;
 
+/**
+ * All built-in devtools event types.
+ */
 export const DEVTOOLS_EVENT_TYPES = [
   "request",
   "error",
@@ -186,6 +201,9 @@ export const DEVTOOLS_EVENT_TYPES = [
   "custom",
 ] as const satisfies readonly DevtoolsEvent["type"][];
 
+/**
+ * Check whether a string is a built-in devtools event type.
+ */
 export function isDevtoolsEventType(
   value: string,
 ): value is DevtoolsEvent["type"] {

package/src/instrumentation.ts

@@ -32,6 +32,9 @@ type ContextWithPorts = {
   };
 };
 
+/**
+ * Options for server hooks that record request/error events to devtools.
+ */
 export interface DevtoolsHooksOptions<Ctx> {
   /**
    * Devtools route prefix. Requests under this path are ignored to avoid
@@ -41,6 +44,9 @@ export interface DevtoolsHooksOptions<Ctx> {
    */
   basePath?: string;
 
+  /**
+   * Resolve the request ID used for event correlation.
+   */
   getRequestId?: (args: {
     req: HttpRequestLike;
     ctx?: Ctx;
@@ -66,6 +72,9 @@ export interface DevtoolsHooksOptions<Ctx> {
    */
   traceContextHeader?: string | false;
 
+  /**
+   * Resolve a trace context from request/context/response data.
+   */
   getTraceContext?: (args: {
     req: HttpRequestLike;
     ctx?: Ctx;
@@ -78,6 +87,9 @@ export interface DevtoolsHooksOptions<Ctx> {
    */
   redact?: DevtoolsRedactor;
 
+  /**
+   * Decide whether to capture a completed request event.
+   */
   shouldCapture?: (args: {
     req: HttpRequestLike;
     ctx?: Ctx;
@@ -87,6 +99,9 @@ export interface DevtoolsHooksOptions<Ctx> {
   }) => boolean;
 }
 
+/**
+ * Use-case run event shape consumed by the devtools observer.
+ */
 export interface DevtoolsUseCaseRunEvent<Ctx> {
   name: string;
   kind: "command" | "query";
@@ -96,10 +111,25 @@ export interface DevtoolsUseCaseRunEvent<Ctx> {
   ctx: Ctx;
 }
 
+/**
+ * Options for `createDevtoolsUseCaseObserver(...)`.
+ */
 export interface DevtoolsUseCaseObserverOptions<Ctx> {
+  /**
+   * Resolve a devtools port from use-case context.
+   */
   getDevtools?: (ctx: Ctx) => DevtoolsPort | undefined;
+  /**
+   * Resolve the request ID used for event correlation.
+   */
   getRequestId?: (ctx: Ctx) => string | undefined;
+  /**
+   * Whether use-case error phases should also emit `error` events.
+   */
   logErrorEvents?: boolean;
+  /**
+   * Optional redactor applied before events are recorded.
+   */
   redact?: DevtoolsRedactor;
 }
 
@@ -175,6 +205,13 @@ function isWatcherEnabled(
   return devtools.isWatcherEnabled(name);
 }
 
+/**
+ * Create server hooks that record Beignet request and error activity.
+ *
+ * Devtools routes under `basePath` are ignored so polling and SSE traffic do not
+ * fill the event buffer. Request IDs and trace context are also written to
+ * response headers unless disabled.
+ */
 export function createDevtoolsHooks<
   Ctx,
   Ports extends PortsWithDevtools = PortsWithDevtools,
@@ -359,6 +396,9 @@ export function createDevtoolsHooks<
   };
 }
 
+/**
+ * Create a use-case observer compatible with `createUseCase({ onRun })`.
+ */
 export function createDevtoolsUseCaseObserver<Ctx>(
   options: DevtoolsUseCaseObserverOptions<Ctx> = {},
 ): (event: DevtoolsUseCaseRunEvent<Ctx>) => void {

package/src/persistence.ts

@@ -1,15 +1,33 @@
 import type { DevtoolsEvent } from "./events";
 
+/**
+ * Persistence interface for devtools event stores.
+ */
 export interface DevtoolsEventStore {
+  /**
+   * Store name used in diagnostics.
+   */
   name?: string;
+  /**
+   * Load persisted events at startup.
+   */
   load?(): DevtoolsEvent[] | Promise<DevtoolsEvent[]>;
+  /**
+   * Append one event. The second argument is the current bounded buffer.
+   */
   append?(
     event: DevtoolsEvent,
     events: readonly DevtoolsEvent[],
   ): void | Promise<void>;
+  /**
+   * Clear persisted events.
+   */
   clear?(): void | Promise<void>;
 }
 
+/**
+ * Options for the Node-only file-backed devtools store.
+ */
 export interface FileDevtoolsStoreOptions {
   /**
    * JSONL file used for persisted devtools events.
@@ -80,6 +98,12 @@ async function loadNodeModules(): Promise<{
   return { fs, path };
 }
 
+/**
+ * Create a JSONL file-backed devtools store.
+ *
+ * This store lazily imports Node fs/path modules and is intended for Node
+ * runtimes. It compacts periodically to keep the persisted file bounded.
+ */
 export function createFileDevtoolsStore(
   options: FileDevtoolsStoreOptions = {},
 ): DevtoolsEventStore {

package/src/provider-instrumentation.ts

@@ -7,11 +7,25 @@ import {
 } from "@beignet/core/providers";
 import type { DevtoolsPort } from "./index";
 
+/**
+ * Provider devtools instrumentation options.
+ */
 export type ProviderDevtoolsOptions = ProviderInstrumentationOptions;
+
+/**
+ * Custom provider event input accepted by provider devtools instrumentation.
+ */
 export type ProviderCustomDevtoolsEventInput =
   ProviderCustomInstrumentationEventInput;
+
+/**
+ * Provider instrumentation object backed by devtools.
+ */
 export type ProviderDevtools = ProviderInstrumentation;
 
+/**
+ * Check whether an unknown value implements the devtools port shape.
+ */
 export function isDevtoolsPort(value: unknown): value is DevtoolsPort {
   return (
     isProviderInstrumentationPort(value) &&
@@ -24,6 +38,9 @@ export function isDevtoolsPort(value: unknown): value is DevtoolsPort {
   );
 }
 
+/**
+ * Resolve a devtools port from a direct port or `{ devtools }` object.
+ */
 export function resolveDevtoolsPort(target: unknown): DevtoolsPort | undefined {
   if (isDevtoolsPort(target)) return target;
 
@@ -39,6 +56,9 @@ export function resolveDevtoolsPort(target: unknown): DevtoolsPort | undefined {
   return undefined;
 }
 
+/**
+ * Create provider instrumentation backed by a devtools port when available.
+ */
 export function createProviderDevtools(
   target: unknown,
   options: ProviderDevtoolsOptions,

package/src/provider.ts

@@ -37,11 +37,29 @@ import {
  */
 const MAX_EVENTS = 500;
 
+/**
+ * Options for `createInMemoryDevtools(...)`.
+ */
 export interface InMemoryDevtoolsOptions {
+  /**
+   * Maximum events kept in memory.
+   */
   maxEvents?: number;
+  /**
+   * Custom redactor applied after the default devtools redactor.
+   */
   redact?: DevtoolsRedactor;
+  /**
+   * Watcher configuration.
+   */
   watchers?: DevtoolsWatchersOptions;
+  /**
+   * Events loaded into the buffer at startup.
+   */
   initialEvents?: readonly DevtoolsEvent[];
+  /**
+   * Optional persistence store.
+   */
   store?: DevtoolsEventStore;
 }
 
@@ -52,6 +70,9 @@ function createEventId(): string {
   return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
 }
 
+/**
+ * Normalize a devtools event by filling `id` and `timestamp`.
+ */
 export function createDevtoolsEvent(event: DevtoolsEventInput): DevtoolsEvent {
   return {
     ...event,
@@ -247,13 +268,34 @@ const DevtoolsConfigSchema = z.object({
   PERSIST_PATH: z.string().optional(),
 });
 
+/**
+ * Devtools provider config loaded from `DEVTOOLS_*` env vars.
+ */
 export type DevtoolsConfig = z.infer<typeof DevtoolsConfigSchema>;
 
+/**
+ * Options for `createDevtoolsProvider(...)`.
+ */
 export interface DevtoolsProviderOptions {
+  /**
+   * Whether devtools are enabled. Defaults to non-production.
+   */
   enabled?: boolean;
+  /**
+   * Maximum events kept in memory.
+   */
   maxEvents?: number;
+  /**
+   * Custom redactor applied after the default redactor.
+   */
   redact?: DevtoolsRedactor;
+  /**
+   * Watcher configuration.
+   */
   watchers?: DevtoolsWatchersOptions;
+  /**
+   * Optional persistence store or async store factory.
+   */
   store?:
     | DevtoolsEventStore
     | (() => DevtoolsEventStore | Promise<DevtoolsEventStore>);

package/src/redaction.ts

@@ -1,9 +1,15 @@
 import { redactValue } from "@beignet/core/ports";
 import type { DevtoolsEvent, DevtoolsRedactor } from "./events";
 
+/**
+ * Default devtools event redactor.
+ */
 export const defaultDevtoolsRedactor: DevtoolsRedactor = (event) =>
   redactValue(event);
 
+/**
+ * Apply default redaction and then an optional custom redactor.
+ */
 export function applyDevtoolsRedaction(
   event: DevtoolsEvent,
   redact?: DevtoolsRedactor,
@@ -13,6 +19,9 @@ export function applyDevtoolsRedaction(
   return redact(redacted);
 }
 
+/**
+ * Create a devtools error event when redaction fails.
+ */
 export function createRedactionFailureEvent(error: unknown): DevtoolsEvent {
   return {
     id: `${Date.now()}-${Math.random().toString(16).slice(2)}`,

package/src/routes.ts

@@ -13,6 +13,9 @@ import { isDevtoolsEventType } from "./events";
 import type { DevtoolsFilter, DevtoolsPort } from "./index";
 import { handleDevtoolsUIRequest } from "./ui";
 
+/**
+ * Devtools route options shared by route handlers.
+ */
 export interface DevtoolsRequestOptions extends DevtoolsRouteAccessOptions {
   /**
    * URL path prefix where devtools routes are mounted.
@@ -22,8 +25,17 @@ export interface DevtoolsRequestOptions extends DevtoolsRouteAccessOptions {
   basePath: string;
 }
 
+/**
+ * GET/POST route handlers returned by `createDevtoolsRoute(...)`.
+ */
 export interface DevtoolsRouteHandlers {
+  /**
+   * Handle devtools GET requests.
+   */
   GET(req: Request): Promise<Response>;
+  /**
+   * Handle devtools POST requests.
+   */
   POST(req: Request): Promise<Response>;
 }
 

package/src/trace-context.ts

@@ -1,19 +1,52 @@
 const TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
 
+/**
+ * Devtools trace context used to correlate related events.
+ */
 export interface DevtoolsTraceContext {
+  /**
+   * W3C trace ID.
+   */
   traceId: string;
+  /**
+   * Current span ID.
+   */
   spanId: string;
+  /**
+   * Parent span ID when available.
+   */
   parentSpanId?: string;
+  /**
+   * W3C traceparent header value.
+   */
   traceparent: string;
 }
 
+/**
+ * Parsed W3C traceparent header.
+ */
 export interface ParsedTraceparent {
+  /**
+   * W3C trace ID.
+   */
   traceId: string;
+  /**
+   * Span ID from the traceparent header.
+   */
   spanId: string;
+  /**
+   * Trace flags from the traceparent header.
+   */
   traceFlags: string;
+  /**
+   * Normalized traceparent header value.
+   */
   traceparent: string;
 }
 
+/**
+ * Input accepted when creating devtools trace context.
+ */
 export interface DevtoolsTraceContextInput {
   traceId?: string;
   spanId?: string;
@@ -41,6 +74,9 @@ function isNonZeroHex(value: string): boolean {
   return !/^0+$/.test(value);
 }
 
+/**
+ * Create a non-zero W3C trace ID.
+ */
 export function createTraceId(): string {
   let traceId = createHexId(32);
   while (!isNonZeroHex(traceId)) {
@@ -49,6 +85,9 @@ export function createTraceId(): string {
   return traceId;
 }
 
+/**
+ * Create a non-zero W3C span ID.
+ */
 export function createSpanId(): string {
   let spanId = createHexId(16);
   while (!isNonZeroHex(spanId)) {
@@ -57,6 +96,9 @@ export function createSpanId(): string {
   return spanId;
 }
 
+/**
+ * Create a W3C traceparent header value.
+ */
 export function createTraceparent(args: {
   traceId: string;
   spanId: string;
@@ -65,6 +107,9 @@ export function createTraceparent(args: {
   return `00-${args.traceId}-${args.spanId}-${args.traceFlags ?? "01"}`;
 }
 
+/**
+ * Parse and validate a W3C traceparent header value.
+ */
 export function parseTraceparent(
   value: string | null | undefined,
 ): ParsedTraceparent | undefined {
@@ -84,6 +129,9 @@ export function parseTraceparent(
   };
 }
 
+/**
+ * Create devtools trace context from explicit IDs or an existing traceparent.
+ */
 export function createDevtoolsTraceContext(
   input: DevtoolsTraceContextInput = {},
 ): DevtoolsTraceContext {
@@ -104,6 +152,9 @@ export function createDevtoolsTraceContext(
   };
 }
 
+/**
+ * Create child trace context from a parent context.
+ */
 export function createChildDevtoolsTraceContext(
   parent: DevtoolsTraceContextInput,
 ): DevtoolsTraceContext {

package/src/ui.ts

@@ -132,6 +132,7 @@ button.danger:hover{border-color:rgba(225,29,72,.24);background:#fff1f2}
 .badge-cache{background:#f7fee7;color:#4d7c0f;border-color:#d9f99d}
 .badge-db{background:#ecfeff;color:#0e7490;border-color:#cffafe}
 .badge-mail{background:#fdf2f8;color:#be185d;border-color:#fbcfe8}
+.badge-notifications{background:#f5f3ff;color:#6d28d9;border-color:#ddd6fe}
 .badge-rateLimit{background:#fffbeb;color:#b45309;border-color:#fde68a}
 .badge-storage{background:#f0fdf4;color:#15803d;border-color:#bbf7d0}
 .request-id{font-family:var(--font-mono);font-size:10px;color:var(--text-muted);padding:2px 5px;background:var(--surface-2);border:1px solid var(--border);border-radius:4px}
@@ -222,13 +223,14 @@ button.danger:hover{border-color:rgba(225,29,72,.24);background:#fff1f2}
     {id:"cache",label:"Cache",type:"custom",watcher:"cache",watcherName:"cache"},
     {id:"storage",label:"Storage",type:"custom",watcher:"storage",watcherName:"storage"},
     {id:"mail",label:"Mail",type:"custom",watcher:"mail",watcherName:"mail"},
+    {id:"notifications",label:"Notifications",type:"custom",watcher:"notifications",watcherName:"notifications"},
     {id:"auth",label:"Auth",type:"custom",watcher:"auth",watcherName:"auth"},
     {id:"audit",label:"Audit",type:"custom",watcher:"audit",watcherName:"audit"},
     {id:"rateLimit",label:"Rate limits",type:"custom",watcher:"rateLimit",watcherName:"rateLimit"},
     {id:"custom",label:"Custom",type:"custom",watcher:"custom"}
   ];
-  const FOCUS_PANEL_TABS={events:true,jobs:true,schedules:true,db:true,cache:true,storage:true,mail:true,auth:true,audit:true,rateLimit:true};
-  const BUILT_IN_WATCHERS={requests:true,errors:true,useCases:true,eventBus:true,jobs:true,schedules:true,providers:true,db:true,cache:true,storage:true,mail:true,auth:true,audit:true,rateLimit:true,custom:true};
+  const FOCUS_PANEL_TABS={events:true,jobs:true,schedules:true,db:true,cache:true,storage:true,mail:true,notifications:true,auth:true,audit:true,rateLimit:true};
+  const BUILT_IN_WATCHERS={requests:true,errors:true,useCases:true,eventBus:true,jobs:true,schedules:true,providers:true,db:true,cache:true,storage:true,mail:true,notifications:true,auth:true,audit:true,rateLimit:true,custom:true};
   let events=[];
   let watchers=[];
   let activeTab=localStorage.getItem("beignet-devtools-tab")||"timeline";
@@ -331,6 +333,7 @@ button.danger:hover{border-color:rgba(225,29,72,.24);background:#fff1f2}
         case "cache": return "cache";
         case "db": return "database";
         case "mail": return "mail";
+        case "notifications": return "notifications";
         case "rateLimit": return "rate limit";
         case "storage": return "storage";
         default: return "custom";
@@ -347,6 +350,7 @@ button.danger:hover{border-color:rgba(225,29,72,.24);background:#fff1f2}
         case "cache": return "cache";
         case "db": return "db";
         case "mail": return "mail";
+        case "notifications": return "notifications";
         case "rateLimit": return "rateLimit";
         case "storage": return "storage";
         default: return "custom";
@@ -565,6 +569,7 @@ button.danger:hover{border-color:rgba(225,29,72,.24);background:#fff1f2}
       case "cache": return {title:"Cache",subtitle:"Reads, writes, deletes, and hit rates"};
       case "storage": return {title:"Storage",subtitle:"Object storage operations"};
       case "mail": return {title:"Mail",subtitle:"Delivery attempts and provider results"};
+      case "notifications": return {title:"Notifications",subtitle:"Notification intent and channel delivery"};
       case "auth": return {title:"Auth",subtitle:"Session and authentication activity"};
       case "audit": return {title:"Audit",subtitle:"Durable activity records emitted by application code"};
       case "rateLimit": return {title:"Rate limits",subtitle:"Allowed, blocked, and failed checks"};

package/src/watchers.ts

@@ -1,5 +1,8 @@
 import type { DevtoolsEvent } from "./events";
 
+/**
+ * Built-in devtools watcher names.
+ */
 export const BUILT_IN_DEVTOOLS_WATCHER_NAMES = [
   "requests",
   "errors",
@@ -12,25 +15,53 @@ export const BUILT_IN_DEVTOOLS_WATCHER_NAMES = [
   "cache",
   "storage",
   "mail",
+  "notifications",
   "auth",
   "audit",
   "rateLimit",
   "custom",
 ] as const;
 
+/**
+ * Name of a built-in devtools watcher.
+ */
 export type BuiltInDevtoolsWatcherName =
   (typeof BUILT_IN_DEVTOOLS_WATCHER_NAMES)[number];
 
+/**
+ * Name of a built-in or app-defined devtools watcher.
+ */
 export type DevtoolsWatcherName = BuiltInDevtoolsWatcherName | (string & {});
 
+/**
+ * Resolved devtools watcher configuration.
+ */
 export interface DevtoolsWatcher {
+  /**
+   * Watcher name.
+   */
   name: DevtoolsWatcherName;
+  /**
+   * Display label.
+   */
   label: string;
+  /**
+   * Display description.
+   */
   description?: string;
+  /**
+   * Event types this watcher owns.
+   */
   eventTypes: readonly DevtoolsEvent["type"][];
+  /**
+   * Whether events owned by this watcher should be stored.
+   */
   enabled: boolean;
 }
 
+/**
+ * User-provided watcher override.
+ */
 export type DevtoolsWatcherOptions =
   | boolean
   | {
@@ -40,6 +71,9 @@ export type DevtoolsWatcherOptions =
       eventTypes?: readonly DevtoolsEvent["type"][];
     };
 
+/**
+ * Watcher overrides keyed by built-in or custom watcher name.
+ */
 export type DevtoolsWatchersOptions = Partial<
   Record<BuiltInDevtoolsWatcherName, DevtoolsWatcherOptions>
 > &
@@ -124,6 +158,13 @@ const BUILT_IN_DEVTOOLS_WATCHERS = {
     eventTypes: ["custom"],
     enabled: true,
   },
+  notifications: {
+    name: "notifications",
+    label: "Notifications",
+    description: "Application notification intent and channel delivery.",
+    eventTypes: ["custom"],
+    enabled: true,
+  },
   auth: {
     name: "auth",
     label: "Auth",
@@ -184,6 +225,9 @@ function normalizeWatcherOptions(
   };
 }
 
+/**
+ * Resolve built-in and custom watcher configuration.
+ */
 export function resolveDevtoolsWatchers(
   options: DevtoolsWatchersOptions = {},
 ): DevtoolsWatcher[] {
@@ -211,6 +255,9 @@ export function resolveDevtoolsWatchers(
   return watchers;
 }
 
+/**
+ * Check whether a watcher is enabled.
+ */
 export function isDevtoolsWatcherEnabled(
   watchers: readonly DevtoolsWatcher[],
   name: DevtoolsWatcherName,
@@ -218,6 +265,9 @@ export function isDevtoolsWatcherEnabled(
   return watchers.find((watcher) => watcher.name === name)?.enabled ?? true;
 }
 
+/**
+ * Check whether an event should be stored for a watcher configuration.
+ */
 export function isDevtoolsEventEnabled(
   watchers: readonly DevtoolsWatcher[],
   event: DevtoolsEvent,