Server adapter

createJevDevtools(options)#

Create one independent adapter for a Node process whose lifecycle you own.

// server/jev.ts — Node only
import { createJevDevtools } from "jev-devtools/server";

export const inspector = createJevDevtools({
  enabled: process.env.NODE_ENV === "development",
  origin: "http://localhost:3000", // Must match the browser URL exactly.
});

export const jev = inspector.createClient({
  apiKey: process.env.TYPESAFE_API_KEY,
});

createJevDevtools(options)

enabled

origin

adapter.createClient(options, metadata?)

API reference: createJevDevtools() · adapter.createClient()

Example walkthrough: the adapter enables inspection only in development and checks requests against the browser's origin. createClient() wraps the SDK client so its requests use the same recording history as the inspector routes. The key stays in this server module.

Return interface#

Options#

These form JevDevtoolsServerOptions; limit and redact also form the exported CaptureOptions type.

createClient(options, metadata?)#

Accepts the TypeSafe SDK's constructor options and returns an instrumented SDK client. Metadata is { label?: string, source?: 'sample' | 'live' }, exported as ClientMetadata. Defaults are Jev request and live.

const client = inspector.createClient(
  { apiKey: process.env.TYPESAFE_API_KEY },
  { label: "Support triage", source: "live" },
);

label

source

API reference: adapter.createClient()

Example walkthrough: the SDK options contain the server-side key. The metadata labels captures as “Support triage” and live. The returned client is the one your application should use for systemOne() calls.

Return interface#

Changing source only labels captures; it does not turn live inference into a sample transport. With recording disabled, this method returns an ordinary SDK client. Only systemOne calls on the instrumented client are captured.

HTTP adapters#

Return interfaces#

Route the base path and all subpaths to the same adapter. The browser uses configuration, SSE events, flow events, and DELETE /clear. The package handles that protocol for you; see the stream protocol if building another viewer.

getJevDevtools(key, createOptions)#

import { getJevDevtools } from "jev-devtools/server";

const inspector = getJevDevtools("my-app", () => ({
  enabled: process.env.NODE_ENV === "development",
  origin: "http://localhost:3000",
}));

getJevDevtools(key, createOptions)

API reference: getJevDevtools() · createJevDevtools()

Example walkthrough: "my-app" identifies the shared adapter. The factory supplies options only on the first lookup, so module reloads reuse the same capture history.

Return interface#

Returns the same adapter for a stable, nonempty key in the same Node realm. The options factory runs once per key. Restart after configuration changes. Different keys have separate histories; different processes do not share histories.

run(request, callback)#

Select the request's server-derived recording scope while the callback runs. Use it for inference handlers when getSession is customized:

return inspector.run(request, () => jev.systemOne(input));

adapter.run(request, callback)

API reference: adapter.run()

Example walkthrough: the adapter derives a session from request, then executes jev.systemOne(input) within that session. Its promise resolves to the SDK result; the wrapper does not replace it with recorder data.

Return interface#

Here request and input come from your application handler. Authenticate that handler separately: run scopes capture but does not authorize the application action.

dispose() and startFlow()#

dispose() disables the adapter and closes active streams. For shared adapters, it also releases the key. Use it at shutdown, not after each request.

startFlow(definition, run) implements the exported FlowObserver contract. Normally pass the adapter as devtools to a flow's run(); there is no need to invoke observer methods directly.