@rasputin-ai/elysia 0.6.0 → 0.6.2

package/README.md

@@ -1,217 +1,5 @@
 # Official Rasputin AI SDK for Elysia
 
-Report application errors to Rasputin.
+Report application errors to Rasputin from Elysia services.
 
-## Setup
-
-Initialize once and register the plugin early in your app:
-
-```ts
-import { Elysia } from 'elysia';
-import { RasputinInit } from '@rasputin-ai/elysia';
-
-const { client, plugin } = RasputinInit({
-  dsn: process.env.RASPUTIN_DSN!,
-  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'),
-});
-
-const app = new Elysia()
-  .use(plugin) // Register Rasputin before other plugins when possible.
-  .use(otherPlugins)
-  .listen(3000);
-```
-
-Route errors, uncaught exceptions, and unhandled rejections are reported automatically.
-
-## Capture handled errors
-
-```ts
-try {
-  await processPayment();
-} catch (error) {
-  client.captureException(error);
-}
-```
-
-## Configuration
-
-| Field | Required | Description |
-| --- | --- | --- |
-| `dsn` | yes | Public project DSN from Rasputin project settings. Safe for application runtime. |
-| `projectApiKey` | yes | Secret project API key for deploy announcement and instrumentation manifest upload |
-| `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` |
-| `logSuccess` | no | Prints a configuration summary when setup succeeds; defaults to `true`. Failures always log. |
-| `moduleUrl` | no | `import.meta.url` from the initialization file; helps normalize local stack paths |
-| `sourceRoot` | no | Git repository folder for a single-package service, such as `apps/api` |
-| `sourceRoots` | no | Package-name to Git-folder mappings for ambiguous monorepos |
-| `repoRoot` | no | Local filesystem display root; it does not control instrumentation or Git identity |
-
-Rasputin normally identifies source from the nearest `package.json` and verifies it against the exact release on the server. Filesystem paths such as `/container` are never used as source identity.
-
-For deployment checks, call:
-
-```ts
-const verification = await client.verifyConfiguration();
-```
-
-`verified` means every instrumented source file maps uniquely to the configured Git release. If a monorepo is ambiguous, set `sourceRoot` or `sourceRoots` using repository-relative folders, never Docker paths.
-
-Rasputin also prints a configuration summary after the instrumentation manifest is uploaded. Set `logSuccess: false` if you do not want that banner in production logs. Mapping failures still warn.
-
-## 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
-
-Rasputin wraps your functions so it can show what ran when an error happened.
-
-**Compiled JavaScript (use this in production)**
-
-Build as you already do, then run `rasputin-instrument` on the output. Start the process normally — no extra flags:
-
-```json
-{
-  "scripts": {
-    "build": "tsc && rasputin-instrument dist",
-    "start:node": "node dist/app.js",
-    "start:bun": "bun dist/app.js"
-  }
-}
-```
-
-Have TypeScript write `.js.map` files next to the output so recorded functions still point at your `.ts` sources. The instrumenter writes `.rasputin/instrumentation-manifest.json` beside `dist`, and `RasputinInit` loads it automatically.
-
-**Running TypeScript directly**
-
-`rasputin-instrument` rewrites compiled `.js` files on disk. It does not run when you start TypeScript with Bun (`bun src/app.ts`, `bun run src/app.ts`, and similar). Use `--preload` so Bun wraps files as they load:
-
-```json
-{
-  "scripts": {
-    "start:bun": "bun --preload @rasputin-ai/elysia/instrument/bun src/app.ts"
-  }
-}
-```
-
-On Node you can wrap compiled files as they load instead of instrumenting at build time:
-
-```json
-{
-  "scripts": {
-    "start:node": "node --import @rasputin-ai/elysia/instrument/node dist/app.js"
-  }
-}
-```
-
-Use `--preload` / `--import` while you run TypeScript locally. In production, instrument at build time instead — wrapping files at startup is slower and uses more memory.
-
-Runtime state is kept only while a request or job is running, and is attached when that work throws.
-
-## Manual capture
-
-For background jobs, scheduled tasks, or worker iterations, define an execution:
-
-```ts
-const scope = client.execution.createScope({
-  kind: 'job',
-  name: 'sync-invoices',
-})
-
-try {
-  return await scope.run(() => syncInvoices())
-} catch (error) {
-  scope.associateError(error)
-  throw error
-} finally {
-  scope.finish()
-}
-```
-
-`scope.run()` executes the callback under this recording's async context and returns exactly what the callback returned. It does not wrap, replace, or observe Promises.
-
-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 |
-| --- | --- |
-| TypeScript compiled to multiple JavaScript files | Use `rasputin-instrument dist` after `tsc`, with adjacent source maps |
-| Elysia 1.4+ on Bun 1.3.x, running `.ts` or `.js` files directly | Use `--preload @rasputin-ai/elysia/instrument/bun` |
-| Elysia 1.4+ on Node.js 22.15 or newer, unbundled ESM/CJS | Use `rasputin-instrument`, or `--import @rasputin-ai/elysia/instrument/node`; Node 22 and 24 are the supported LTS lines |
-
-On Node.js 22, start the process with `--experimental-async-context-frame` (or set `NODE_OPTIONS`) so `AsyncLocalStorage` uses the faster implementation that Node.js 24 enables by default. Rasputin logs this once when the flag is missing; set `RASPUTIN_SUPPRESS_ASYNC_CONTEXT_FRAME_WARNING=1` to hide it.
-| Single-file bundles (esbuild, tsup, webpack, Vite SSR, Next.js) | Automatic instrumentation is not supported |
-| `tsx`, custom Node loader stacks, and Node's native TypeScript execution | Automatic instrumentation is 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. Use `execution.createScope()` 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` | `16 KiB` | Maximum retained size of one captured value |
-| `runtimeStateTargetBytes` | `256 KiB` | Soft size goal for the snapshot sent with an error; extra reconstruction data is dropped first |
-| `maxRuntimeStateBytes` | `512 KiB` | Hard size limit for that snapshot; values are dropped before call history |
-| `redactKeys` | `[]` | Additional property names to redact (case- and separator-insensitive) |
-| `excludeSources` | `[]` | Source globs or function-name 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();
-```
-
-These counters describe what this process has recorded and sent since it started. They reset on restart. Compare two snapshots if you want activity over a window, rather than dividing lifetime totals by one request.
+See the [Elysia documentation](https://rasputinai.dev/docs/elysia/installation).

package/dist/index.js

@@ -1,7 +1,10 @@
 // src/rasputin-init.ts
 import {
   createClient,
-  isClientEnabled
+  isClientEnabled,
+  parseDsn,
+  resolveEndpointUrls,
+  scheduleAnnounceDeploy
 } from "@rasputin-ai/core";
 import {
   createExecutionRecorder,
@@ -13,7 +16,7 @@ import { Elysia } from "elysia";
 
 // src/sdk-meta.ts
 var SDK_NAME = "@rasputin-ai/elysia";
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.6.2";
 
 // src/rasputin-init.ts
 var publicExecution = (runtime) => ({
@@ -32,35 +35,41 @@ var withExecution = (client, runtime, installRuntime, manifest, uninstallHandler
 }) => {
   const uninstallRuntime = installRuntime ? installAutomaticExecutionRuntime(runtime) : () => {
   };
-  const manifestUpload = scheduleInstrumentationManifestUpload(manifest);
+  const manifestUpload = scheduleInstrumentationManifestUpload({
+    ...manifest,
+    deferStart: true
+  });
   const execution = publicExecution(runtime);
   return {
-    ...client,
-    execution,
-    getStats: () => ({ ...client.getStats(), recorder: execution.getStats() }),
-    verifyConfiguration: manifestUpload.verify,
-    captureException: (error, context) => {
-      const result = client.captureException(error, context);
-      manifestUpload.flushSoon();
-      return result;
-    },
-    flush: async (timeoutMs) => {
-      const startedAt = Date.now();
-      await client.flush(timeoutMs);
-      if (timeoutMs === void 0) {
-        await manifestUpload.wait();
-        return;
+    client: {
+      ...client,
+      execution,
+      getStats: () => ({ ...client.getStats(), recorder: execution.getStats() }),
+      verifyConfiguration: manifestUpload.verify,
+      captureException: (error, context) => {
+        const result = client.captureException(error, context);
+        manifestUpload.flushSoon();
+        return result;
+      },
+      flush: async (timeoutMs) => {
+        const startedAt = Date.now();
+        await client.flush(timeoutMs);
+        if (timeoutMs === void 0) {
+          await manifestUpload.wait();
+          return;
+        }
+        await manifestUpload.wait(Math.max(0, timeoutMs - (Date.now() - startedAt)));
+      },
+      close: async () => {
+        uninstallHandlers();
+        uninstallRuntime();
+        manifestUpload.disconnect();
+        const startedAt = Date.now();
+        await client.close();
+        await manifestUpload.wait(Math.max(0, 2e3 - (Date.now() - startedAt)));
       }
-      await manifestUpload.wait(Math.max(0, timeoutMs - (Date.now() - startedAt)));
     },
-    close: async () => {
-      uninstallHandlers();
-      uninstallRuntime();
-      manifestUpload.disconnect();
-      const startedAt = Date.now();
-      await client.close();
-      await manifestUpload.wait(Math.max(0, 2e3 - (Date.now() - startedAt)));
-    }
+    startManifestUpload: manifestUpload.start
   };
 };
 var toStatus = (status) => {
@@ -152,7 +161,7 @@ function RasputinInit(options, hooks = {}) {
     });
     const client = createClient(options, {
       fetch,
-      announceDeploy,
+      announceDeploy: false,
       installTransportSignalHandlers,
       sdkVersion: SDK_VERSION,
       sdkName: SDK_NAME,
@@ -163,7 +172,7 @@ function RasputinInit(options, hooks = {}) {
     });
     let uninstallHandlers = () => {
     };
-    const wrappedClient = withExecution(
+    const { client: wrappedClient, startManifestUpload } = withExecution(
       client,
       runtime,
       recorderEnabled,
@@ -182,14 +191,28 @@ function RasputinInit(options, hooks = {}) {
     if (enabled && installProcessHandlers) {
       uninstallHandlers = installGlobalHandlers(wrappedClient);
     }
+    const plugin = buildPlugin(wrappedClient, runtime, recorderEnabled).onStart(() => {
+      startManifestUpload();
+      if (!enabled || announceDeploy === false) return;
+      const parsed = parseDsn(options.dsn);
+      const apiUrl = typeof options.apiUrl === "string" && options.apiUrl.trim() ? options.apiUrl.trim() : parsed?.apiUrl;
+      if (!apiUrl) return;
+      scheduleAnnounceDeploy({
+        deployUrl: resolveEndpointUrls(apiUrl).deployUrl,
+        projectApiKey: options.projectApiKey,
+        environment: options.environment,
+        release: options.release,
+        fetch
+      });
+    });
     return {
       client: wrappedClient,
-      plugin: buildPlugin(wrappedClient, runtime, recorderEnabled)
+      plugin
     };
   } catch {
     const client = createClient({ ...options, enabled: false });
     const runtime = createExecutionRecorder({ enabled: false });
-    const wrappedClient = withExecution(client, runtime, false, {
+    const { client: wrappedClient } = withExecution(client, runtime, false, {
       projectApiKey: options.projectApiKey,
       release: options.release,
       apiUrl: options.apiUrl,

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;;;;;GAKG;AACH,OAAO,EAKN,KAAK,eAAe,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACX,wBAAwB,EAExB,iBAAiB,EACjB,kBAAkB,EAClB,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,iFAAiF;AACjF,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAElE,MAAM,MAAM,cAAc,GAAG;IAC5B,8EAA8E;IAC9E,MAAM,EAAE,kBAAkB,CAAC;IAC3B,2EAA2E;IAC3E,MAAM,EAAE,oBAAoB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG;IACrD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;IAC7C;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;CACzC,CAAC;AA+GF,QAAA,MAAM,WAAW,GAChB,QAAQ,kBAAkB,EAC1B,WAAW,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAC,EACjD,iBAAiB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsDxB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAAC"}
+{"version":3,"file":"rasputin-init.d.ts","sourceRoot":"","sources":["../src/rasputin-init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAMN,KAAK,eAAe,EAGpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACX,wBAAwB,EAExB,iBAAiB,EACjB,kBAAkB,EAClB,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,iFAAiF;AACjF,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAElE,MAAM,MAAM,cAAc,GAAG;IAC5B,8EAA8E;IAC9E,MAAM,EAAE,kBAAkB,CAAC;IAC3B,2EAA2E;IAC3E,MAAM,EAAE,oBAAoB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG;IACrD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;IAC7C;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;CACzC,CAAC;AAqHF,QAAA,MAAM,WAAW,GAChB,QAAQ,kBAAkB,EAC1B,WAAW,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAC,EACjD,iBAAiB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsDxB,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 scripts/generate-sdk-meta.ts — do not edit. */
 export declare const SDK_NAME = "@rasputin-ai/elysia";
-export declare const SDK_VERSION = "0.6.0";
+export declare const SDK_VERSION = "0.6.2";
 //# sourceMappingURL=sdk-meta.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rasputin-ai/elysia",
-	"version": "0.6.0",
+	"version": "0.6.2",
 	"description": "Official Rasputin AI SDK for Elysia.",
 	"type": "module",
 	"exports": {
@@ -35,8 +35,8 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@rasputin-ai/core": "0.6.0",
-		"@rasputin-ai/node": "0.6.0"
+		"@rasputin-ai/core": "0.6.2",
+		"@rasputin-ai/node": "0.6.2"
 	},
 	"peerDependencies": {
 		"elysia": ">=1.4.0 <2"
@@ -46,7 +46,6 @@
 		"@rasputin-ai/node": "workspace:*",
 		"@types/bun": "1.3.14",
 		"@types/node": "22.13.10",
-		"esbuild": "0.25.12",
 		"elysia": "1.4.28",
 		"typescript": "5"
 	}