@rasputin-ai/elysia 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,10 @@
 # Official Rasputin AI SDK for Elysia
 
-## Usage
+Report application errors to Rasputin.
+
+## Setup
+
+Initialize once and register the plugin early in your app:
 
 ```ts
 import { Elysia } from 'elysia';
@@ -8,25 +12,143 @@ import { RasputinInit } from '@rasputin-ai/elysia';
 
 const { client, plugin } = RasputinInit({
   projectApiKey: process.env.RASPUTIN_PROJECT_API_KEY!,
+  release: process.env.RASPUTIN_RELEASE!,
   environment: process.env.NODE_ENV ?? 'development',
-  release: process.env.RASPUTIN_RELEASE,
+  enabled: ['staging', 'production'].includes(process.env.NODE_ENV ?? 'development'),
   moduleUrl: import.meta.url,
 });
 
-const app = new Elysia().use(plugin);
+const app = new Elysia()
+  .use(plugin) // Register Rasputin before other plugins when possible.
+  .use(otherPlugins)
+  .listen(3000);
 ```
 
-Route errors are captured via the plugin. Use `client.captureException(error)` for manual reporting.
+Route errors, uncaught exceptions, and unhandled rejections are reported automatically.
+
+## Capture handled errors
 
-For short-lived processes, call `await client.flush()` before exit.
+```ts
+try {
+  await processPayment();
+} catch (error) {
+  client.captureException(error);
+}
+```
 
-## Options
+## Configuration
 
 | Field | Required | Description |
 | --- | --- | --- |
 | `projectApiKey` | yes | Project API key from the Rasputin dashboard |
-| `environment` | yes | Where errors occur, e.g. `production`, `staging` |
-| `release` | no | Git commit SHA. Prefer `process.env.RASPUTIN_RELEASE`; auto-detected from platform env / `.git` when omitted |
-| `enabled` | no | Master switch. Default `true` |
-| `moduleUrl` | one of these two | `import.meta.url` from the file where you call `RasputinInit`. Lets Rasputin find your project folder. |
-| `repoRoot` | one of these two | Your project folder — the one you open in your editor. Use this when `moduleUrl` isn't enough (for example in Docker). |
+| `environment` | yes | Environment such as `production`, `staging`, or `preview` |
+| `release` | yes | Git commit SHA for the deployed version |
+| `enabled` | no | Enables or disables the SDK; defaults to `true` |
+| `moduleUrl` | one of these two | `import.meta.url` from the initialization file |
+| `repoRoot` | one of these two | Explicit source root for deployments with a different filesystem layout |
+
+## Shutdown
+
+Events are sent in the background. Flush before a short-lived process exits:
+
+```ts
+await client.flush();
+```
+
+Call `await client.close()` during graceful shutdown when the process stays alive afterward.
+
+---
+
+# Runtime recorder
+
+Optionally attach the runtime state that led to an error — arguments, return values, and call history from the failing execution.
+
+The Elysia plugin scopes each HTTP request as an execution automatically. For background jobs and other non-HTTP work, wrap them manually (see below).
+
+## Automatic instrumentation
+
+Start your process with the adapter for your runtime so Rasputin can instrument application functions as they load:
+
+```json
+{
+  "scripts": {
+    "start:node": "node --import @rasputin-ai/elysia/instrument/node dist/app.js",
+    "start:bun": "bun --preload @rasputin-ai/elysia/instrument/bun src/app.ts"
+  }
+}
+```
+
+Runtime state is retained only inside an active execution and attached when that execution throws.
+
+## Manual capture
+
+For background jobs, scheduled tasks, or worker iterations, define an execution:
+
+```ts
+await client.execution.run({ kind: 'job', name: 'sync-invoices' }, async () => {
+  await syncInvoices();
+});
+```
+
+When automatic instrumentation is unavailable, mark individual functions explicitly:
+
+```ts
+const syncInvoices = client.execution.trace(
+  'src/jobs/sync-invoices.ts:syncInvoices',
+  async () => {
+    // ...
+  },
+);
+```
+
+## Runtime support
+
+| Environment | Support |
+| --- | --- |
+| Elysia 1.4 or newer within 1.x on Bun 1.3.x | Supported for directly loaded JavaScript and TypeScript using `instrument/bun` |
+| Elysia 1.4 or newer within 1.x on Node.js 22.15 or newer | Supported for unbundled ESM/CJS JavaScript using `instrument/node`; Node 22 and 24 are the supported LTS lines |
+| TypeScript compiled to multiple JavaScript files | Supported on Node; emit adjacent source maps to retain original TypeScript locations |
+| Single-file bundles (esbuild, tsup, webpack, Vite SSR, Next.js) | Automatic instrumentation not supported |
+| `tsx`, custom Node loader stacks, and Node's native TypeScript execution | Automatic instrumentation not supported |
+| Deno and edge runtimes | Not supported |
+
+Tested on Bun 1.3.13, Node.js 24.19.0, and Elysia 1.4.28. Node.js 22.15.0 is the minimum for automatic instrumentation (synchronous module hooks). Use `execution.run()` and `execution.trace()` when automatic instrumentation is not available.
+
+## Recorder configuration
+
+Defaults work for most apps. Customize to exclude noisy sources, redact fields, or retain less state:
+
+| Field | Default | Description |
+| --- | ---: | --- |
+| `enabled` | `true` | Enables runtime-state capture |
+| `maxEventsPerExecution` | `500` | Maximum events retained for one execution |
+| `maxCapturedCallsPerFunction` | `3` | Detailed successful calls retained before similar calls are summarized |
+| `maxActiveMemoryBytes` | `64 MiB` | Maximum recorder memory shared across active executions |
+| `maxDepth` | `3` | Maximum captured value depth |
+| `maxObjectKeys` | `30` | Maximum properties retained from one object |
+| `maxArrayElements` | `20` | Maximum items retained from one array, map, or set |
+| `maxStringLength` | `500` | Maximum characters retained from one string |
+| `maxSerializedValueBytes` | `8 KiB` | Maximum retained size of one captured value |
+| `redactKeys` | `[]` | Additional case-insensitive property names to redact |
+| `excludeSources` | `[]` | Source globs or function-ID patterns to exclude |
+
+```ts
+const { client, plugin } = RasputinInit({
+  // ...required options
+  executionRecorder: {
+    excludeSources: ['src/logger/**', 'packages/shared-logger/**'],
+    redactKeys: ['customerEmail'],
+    maxEventsPerExecution: 200,
+  },
+});
+```
+
+Runtime state can include application data. Use `redactKeys` for sensitive fields.
+
+## Diagnostics
+
+```ts
+const { recorder, transport } = client.getStats();
+```
+
+Counters are local to the current process and reset on restart.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export type { CaptureContext, RasputinClient, RasputinOptions } from '@rasputin-ai/core';
-export type { RasputinElysia, RasputinElysiaPlugin } from './rasputin-init';
+export type { RasputinElysia, RasputinElysiaOptions, RasputinElysiaPlugin } from './rasputin-init';
 export { RasputinInit } from './rasputin-init';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzF,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzF,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACnG,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,16 +1,54 @@
 // src/rasputin-init.ts
 import {
   createClient,
-  isClientEnabled
+  isClientEnabled,
+  resolveRepoRoot
 } from "@rasputin-ai/core";
-import { installGlobalHandlers } from "@rasputin-ai/node";
+import {
+  createExecutionRecorder,
+  installAutomaticExecutionRuntime,
+  installGlobalHandlers,
+  scheduleInstrumentationManifestUpload
+} from "@rasputin-ai/node";
 import { Elysia } from "elysia";
 
 // src/sdk-meta.ts
 var SDK_NAME = "@rasputin-ai/elysia";
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = "0.3.0";
 
 // src/rasputin-init.ts
+var withExecution = (client, execution, installRuntime, repoRoot, manifest) => {
+  const uninstallRuntime = installRuntime ? installAutomaticExecutionRuntime(execution, { repoRoot }) : () => {
+  };
+  const manifestUpload = scheduleInstrumentationManifestUpload({
+    ...manifest,
+    repoRoot
+  });
+  return {
+    ...client,
+    execution,
+    getStats: () => ({ ...client.getStats(), recorder: execution.getStats() }),
+    captureException: (error, context) => {
+      const runtimeState = context?.runtimeState ?? execution.getErrorState(
+        error,
+        context?.request ? { kind: "http", request: context.request } : void 0
+      );
+      const result = client.captureException(error, { ...context, runtimeState });
+      manifestUpload.flushSoon();
+      return result;
+    },
+    flush: async (timeoutMs) => {
+      await client.flush(timeoutMs);
+      await manifestUpload.wait();
+    },
+    close: async () => {
+      uninstallRuntime();
+      manifestUpload.disconnect();
+      await client.close();
+      await manifestUpload.wait();
+    }
+  };
+};
 var toStatus = (status) => {
   if (typeof status === "number" && Number.isFinite(status)) return status;
   if (typeof status === "string") {
@@ -19,20 +57,72 @@ var toStatus = (status) => {
   }
   return void 0;
 };
-var buildPlugin = (client) => new Elysia({ name: "rasputin" }).decorate("rasputin", client).onError({ as: "global" }, ({ error, request, set, route }) => {
+var isPromiseLike = (value) => {
+  return Boolean(value) && typeof value.then === "function";
+};
+var finishExecution = (scope, metadata) => {
   try {
-    client.captureException(error, {
-      request: {
-        method: request.method,
-        route: route || void 0,
-        status: toStatus(set.status)
-      }
-    });
+    scope.finish(metadata);
+  } catch {
+  }
+};
+var rememberExecutionError = (scope, error) => {
+  try {
+    scope.getErrorState(error);
   } catch {
   }
-  return;
-});
-var RasputinInit = (options, hooks = {}) => {
+};
+var buildPlugin = (client, execution, recorderEnabled) => {
+  const executionBoundary = ((handler, initialRequest) => {
+    const scope = execution.createScope({
+      kind: "http",
+      request: { method: initialRequest.method }
+    });
+    return (request) => scope.run(() => {
+      try {
+        const response = handler(request);
+        if (isPromiseLike(response)) {
+          return Promise.resolve(response).then(
+            (value) => {
+              finishExecution(scope, { request: { status: value.status } });
+              return value;
+            },
+            (error) => {
+              rememberExecutionError(scope, error);
+              finishExecution(scope);
+              throw error;
+            }
+          );
+        }
+        finishExecution(scope, { request: { status: response.status } });
+        return response;
+      } catch (error) {
+        rememberExecutionError(scope, error);
+        finishExecution(scope);
+        throw error;
+      }
+    });
+  });
+  const plugin = new Elysia({ name: "rasputin" }).decorate("rasputin", client);
+  if (recorderEnabled) plugin.wrap(executionBoundary);
+  return plugin.onError({ as: "global" }, ({ error, request, set, route }) => {
+    const requestContext = {
+      method: request.method,
+      route: route || void 0,
+      status: toStatus(set.status)
+    };
+    try {
+      const runtimeState = execution.getErrorState(error, {
+        kind: "http",
+        request: requestContext
+      });
+      client.captureException(error, { request: requestContext, runtimeState });
+    } catch {
+    }
+    return;
+  });
+};
+function RasputinInit(options, hooks = {}) {
   try {
     const {
       installGlobalHandlers: installProcessHandlers = true,
@@ -47,15 +137,43 @@ var RasputinInit = (options, hooks = {}) => {
       sdkVersion: SDK_VERSION,
       sdkName: SDK_NAME
     });
+    const recorderEnabled = isClientEnabled(options) && options.executionRecorder?.enabled !== false;
+    const execution = createExecutionRecorder({
+      ...options.executionRecorder,
+      enabled: recorderEnabled
+    });
+    const wrappedClient = withExecution(
+      client,
+      execution,
+      recorderEnabled,
+      resolveRepoRoot(options),
+      {
+        projectApiKey: options.projectApiKey,
+        release: options.release,
+        apiUrl: options.apiUrl,
+        fetch,
+        enabled: isClientEnabled(options)
+      }
+    );
     if (isClientEnabled(options) && installProcessHandlers) {
-      installGlobalHandlers(client);
+      installGlobalHandlers(wrappedClient);
     }
-    return { client, plugin: buildPlugin(client) };
+    return {
+      client: wrappedClient,
+      plugin: buildPlugin(wrappedClient, execution, recorderEnabled)
+    };
   } catch {
     const client = createClient({ ...options, enabled: false });
-    return { client, plugin: buildPlugin(client) };
+    const execution = createExecutionRecorder({ enabled: false });
+    const wrappedClient = withExecution(client, execution, false, void 0, {
+      projectApiKey: options.projectApiKey,
+      release: options.release,
+      apiUrl: options.apiUrl,
+      enabled: false
+    });
+    return { client: wrappedClient, plugin: buildPlugin(wrappedClient, execution, false) };
   }
-};
+}
 export {
   RasputinInit
 };

package/dist/instrument/bun.d.ts

@@ -0,0 +1,3 @@
+/** Elysia convenience entry point; instrumentation is shared with the Node/Bun SDK. */
+import '@rasputin-ai/node/instrument/bun';
+//# sourceMappingURL=bun.d.ts.map

package/dist/instrument/bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/instrument/bun.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,kCAAkC,CAAC"}

package/dist/instrument/bun.js

@@ -0,0 +1,2 @@
+// src/instrument/bun.ts
+import "@rasputin-ai/node/instrument/bun";

package/dist/instrument/node.d.ts

@@ -0,0 +1,3 @@
+/** Elysia convenience entry point; instrumentation is shared with the Node/Bun SDK. */
+import '@rasputin-ai/node/instrument/node';
+//# sourceMappingURL=node.d.ts.map

package/dist/instrument/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/instrument/node.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,mCAAmC,CAAC"}

package/dist/instrument/node.js

@@ -0,0 +1,2 @@
+// src/instrument/node.ts
+import "@rasputin-ai/node/instrument/node";

package/dist/rasputin-init.d.ts

@@ -1,21 +1,24 @@
-import { type RasputinClient, type RasputinOptions } from '@rasputin-ai/core';
+/**
+ * Elysia owns a reliable request/response lifecycle, so this integration creates HTTP execution
+ * boundaries automatically around the full middleware and handler chain. Framework-specific code is
+ * intentionally limited to lifecycle wiring; recording, serialization, and safety policy stay in
+ * the framework-neutral Node recorder.
+ */
+import { type RasputinOptions } from '@rasputin-ai/core';
+import { type ExecutionRecorderOptions, type RasputinExecution, type RasputinNodeClient } from '@rasputin-ai/node';
 import { Elysia } from 'elysia';
 export type RasputinElysiaPlugin = ReturnType<typeof buildPlugin>;
 export type RasputinElysia = {
-    client: RasputinClient;
+    client: RasputinNodeClient;
     plugin: RasputinElysiaPlugin;
 };
-/** Test / internal seams — not part of the public init API. */
-type RasputinElysiaHooks = {
-    fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-    announceDeploy?: boolean;
-    installTransportSignalHandlers?: boolean;
-    /** Install process uncaught/rejection handlers. Default true. */
-    installGlobalHandlers?: boolean;
+export type RasputinElysiaOptions = RasputinOptions & {
+    /** Bounded runtime-state capture. Enabled by default; successful executions are discarded. */
+    executionRecorder?: ExecutionRecorderOptions;
 };
-declare const buildPlugin: (client: RasputinClient) => Elysia<"", {
+declare const buildPlugin: (client: RasputinNodeClient, execution: RasputinExecution, recorderEnabled: boolean) => Elysia<"", {
     decorator: {
-        rasputin: RasputinClient;
+        rasputin: RasputinNodeClient;
     };
     store: {};
     derive: {};
@@ -48,17 +51,18 @@ declare const buildPlugin: (client: RasputinClient) => Elysia<"", {
  *
  * @example
  * const { client, plugin } = RasputinInit({
- *   projectApiKey: process.env.RASPUTIN_PROJECT_API_KEY!,
- *   environment: process.env.NODE_ENV ?? 'development',
- *   release: process.env.RASPUTIN_RELEASE,
- *   moduleUrl: import.meta.url,
+ *  projectApiKey: process.env.RASPUTIN_PROJECT_API_KEY!,
+ *  release: process.env.RASPUTIN_RELEASE!,
+ *  environment: process.env.NODE_ENV ?? 'development',
+ *  enabled: ['staging', 'production'].includes(process.env.NODE_ENV ?? 'development'),
+ *  moduleUrl: import.meta.url,
  * });
- * app.use(plugin);
+ * app.use(plugin); // Chain this plugin as early as possible with .use(), before any other plugins or middleware.
  * client.captureException(err); // manual capture
  * await client.flush();         // serverless shutdown
  *
  * Never throws into the host app.
  */
-export declare const RasputinInit: (options: RasputinOptions, hooks?: RasputinElysiaHooks) => RasputinElysia;
+export declare function RasputinInit(options: RasputinElysiaOptions): RasputinElysia;
 export {};
 //# sourceMappingURL=rasputin-init.d.ts.map

package/dist/rasputin-init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rasputin-init.d.ts","sourceRoot":"","sources":["../src/rasputin-init.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAElE,MAAM,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,oBAAoB,CAAC;CAC7B,CAAC;AAEF,+DAA+D;AAC/D,KAAK,mBAAmB,GAAG;IAC1B,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,iEAAiE;IACjE,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAWF,QAAA,MAAM,WAAW,GAAI,QAAQ,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBvC,CAAC;AAEL;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,GACxB,SAAS,eAAe,EACxB,QAAO,mBAAwB,KAC7B,cA0BF,CAAC"}
+{"version":3,"file":"rasputin-init.d.ts","sourceRoot":"","sources":["../src/rasputin-init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAKN,KAAK,eAAe,EAEpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEN,KAAK,wBAAwB,EAI7B,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EAEvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAElE,MAAM,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,oBAAoB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG;IACrD,8FAA8F;IAC9F,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC7C,CAAC;AA8FF,QAAA,MAAM,WAAW,GAChB,QAAQ,kBAAkB,EAC1B,WAAW,iBAAiB,EAC5B,iBAAiB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0DxB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAAC"}

package/dist/sdk-meta.d.ts

@@ -1,4 +1,4 @@
 /** Generated by packages/sdk/scripts/generate-sdk-meta.ts — do not edit. */
 export declare const SDK_NAME = "@rasputin-ai/elysia";
-export declare const SDK_VERSION = "0.2.0";
+export declare const SDK_VERSION = "0.3.0";
 //# sourceMappingURL=sdk-meta.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rasputin-ai/elysia",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Official Rasputin AI SDK for Elysia.",
 	"type": "module",
 	"exports": {
@@ -8,6 +8,16 @@
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js",
 			"default": "./dist/index.js"
+		},
+		"./instrument/bun": {
+			"types": "./dist/instrument/bun.d.ts",
+			"import": "./dist/instrument/bun.js",
+			"default": "./dist/instrument/bun.js"
+		},
+		"./instrument/node": {
+			"types": "./dist/instrument/node.d.ts",
+			"import": "./dist/instrument/node.js",
+			"default": "./dist/instrument/node.js"
 		}
 	},
 	"files": [
@@ -25,11 +35,11 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@rasputin-ai/core": "0.2.0",
-		"@rasputin-ai/node": "0.2.0"
+		"@rasputin-ai/core": "0.3.0",
+		"@rasputin-ai/node": "0.3.0"
 	},
 	"peerDependencies": {
-		"elysia": ">=1.0.0"
+		"elysia": ">=1.4.0 <2"
 	},
 	"devDependencies": {
 		"@rasputin-ai/core": "workspace:*",