@interfere/nest 0.0.1-canary.3 → 0.0.1-canary.5

package/README.md

@@ -1,26 +1,46 @@
 # @interfere/nest
 
-> **Status: canary.** Pre-1.0 API, expect breaking changes. Pin to a specific `10.0.0-canary.N` in CI.
-
-NestJS SDK for [Interfere](https://interfere.com). Wraps [`@interfere/node`](../node) with a global exception filter and OTel auto-instrumentation for controllers, guards, pipes, interceptors, and middleware.
+NestJS SDK for [Interfere](https://interfere.com). Auto-captures uncaught exceptions and creates per-request spans for controllers, guards, pipes, interceptors, and middleware.
 
 ## Install
 
 ```sh
+npm install @interfere/nest
+# or
 bun add @interfere/nest
+# or
+pnpm add @interfere/nest
 ```
 
-## Usage
+## Setup
+
+The SDK uses two subpath imports to avoid loading `@nestjs/*` before instrumentation hooks are registered:
+
+- `@interfere/nest/instrument` — SDK init, error capture, span utilities (no `@nestjs/*` imports)
+- `@interfere/nest/module` — `InterfereModule` and `InterfereExceptionFilter` (imports `@nestjs/*`)
+
+### 1. Create `instrument.ts`
+
+This file must be imported before any `@nestjs/*` module. It registers OTel instrumentation hooks that patch NestJS internals for automatic span creation.
 
 ```ts
-// instrument.ts — imported first in main.ts, before any @nestjs/* import
-import { init } from "@interfere/nest";
-init({ serviceName: "my-api", debug: true });
+// src/instrument.ts
+import { init } from "@interfere/nest/instrument";
+
+init({
+  serviceName: "my-api",
+  debug: true, // logs init status and exporter results to stdout
+});
 ```
 
+`init()` is synchronous and works in both ESM and CJS projects.
+
+### 2. Import it first in `main.ts`
+
 ```ts
-// main.ts
+// src/main.ts
 import "./instrument";
+
 import { NestFactory } from "@nestjs/core";
 import { AppModule } from "./app.module";
 
@@ -31,10 +51,14 @@ async function bootstrap() {
 bootstrap();
 ```
 
+### 3. Register the module in `app.module.ts`
+
+`InterfereModule.forRoot()` registers a global exception filter that captures 5xx errors and uncaught throws. 4xx responses (client errors) are not reported — they still produce OTel request spans but don't create error events.
+
 ```ts
-// app.module.ts
+// src/app.module.ts
 import { Module } from "@nestjs/common";
-import { InterfereModule } from "@interfere/nest";
+import { InterfereModule } from "@interfere/nest/module";
 
 @Module({ imports: [InterfereModule.forRoot()] })
 export class AppModule {}
@@ -42,7 +66,11 @@ export class AppModule {}
 
 ## Build & Deploy
 
-Add a `postbuild` script so source maps are uploaded and the release is registered with the collector:
+Install [`@interfere/cli`](../cli) as a dev dependency and add a `postbuild` script so source maps are uploaded and the release is registered with the collector. Without this step, the collector will reject spans from production deployments.
+
+```sh
+npm install -D @interfere/cli
+```
 
 ```json
 {
@@ -53,11 +81,28 @@ Add a `postbuild` script so source maps are uploaded and the release is register
 }
 ```
 
+The CLI derives the release slug from the same commit SHA the SDK uses at runtime (`INTERFERE_SOURCE_ID`, `GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, or `git rev-parse HEAD`). Both must see the same SHA for the slugs to match. See the [`@interfere/cli` README](../cli) for full options, Docker examples, and CI setup.
+
 ## Environment Variables
 
 | Variable | Where | Purpose |
 |---|---|---|
 | `INTERFERE_PUBLIC_KEY` | Runtime | Routes spans to your surface (`interfere_pk_*`) |
-| `INTERFERE_API_KEY` | CI / Build | Uploads source maps and registers releases (`interfere_ak_*`) |
+| `INTERFERE_API_KEY` | CI / Build | Authenticates source map uploads and release registration (`interfere_ak_*`) |
+| `INTERFERE_SOURCE_ID` | Both | Override the commit SHA used to derive the release slug. Falls back to `GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, or `git rev-parse HEAD`. |
+| `INTERFERE_DEBUG` | Runtime | Set to `1` to enable debug logging without changing code. Equivalent to `debug: true` in `init()`. |
+
+## What gets captured
+
+| Signal | When | Subpath |
+|---|---|---|
+| Request spans (middleware, guards, pipes, interceptors) | Every HTTP request | `@interfere/nest/instrument` |
+| Error events (5xx, uncaught throws) | Exceptions that reach the global filter | `@interfere/nest/module` |
+| Manual spans (`withSpan`, `captureError`) | Anywhere in your code | `@interfere/nest/instrument` |
+
+## Compatibility
 
-Full docs at <https://interfere.com/docs>.
+- NestJS 10.x and 11.x
+- Node.js >= 18.19.0
+- Works with Express (default) and Fastify adapters
+- CJS and ESM projects

package/dist/init.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let _interfere_node=require("@interfere/node"),_opentelemetry_instrumentation=require("@opentelemetry/instrumentation"),_opentelemetry_instrumentation_nestjs_core=require("@opentelemetry/instrumentation-nestjs-core"),instrumented=!1;function init(options={}){instrumented||=((0,_opentelemetry_instrumentation.registerInstrumentations)({instrumentations:[new _opentelemetry_instrumentation_nestjs_core.NestInstrumentation]}),!0),(0,_interfere_node.init)(options)}exports.init=init;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const require_nest_instrumentation=require("./nest-instrumentation.cjs");let _interfere_node=require("@interfere/node"),node_module=require("node:module"),_opentelemetry_instrumentation=require("@opentelemetry/instrumentation"),_opentelemetry_instrumentation_nestjs_core=require("@opentelemetry/instrumentation-nestjs-core");const INIT_KEY=`__interfereNestInitialized__`,g=globalThis;function init(options={}){g[INIT_KEY]||(typeof node_module.register==`function`&&(0,node_module.register)(`import-in-the-middle/hook.mjs`,require("url").pathToFileURL(__filename).href),(0,_interfere_node.init)(options),(0,_opentelemetry_instrumentation.registerInstrumentations)({instrumentations:[new _opentelemetry_instrumentation_nestjs_core.NestInstrumentation,new require_nest_instrumentation.InterfereNestInstrumentation]}),g[INIT_KEY]=!0)}exports.init=init;

package/dist/init.d.cts

@@ -2,11 +2,18 @@ import { InitOptions, InitOptions as InitOptions$1 } from "@interfere/node";
 
 //#region src/init.d.ts
 /**
- * Bootstraps `@interfere/node` and registers
- * `@opentelemetry/instrumentation-nestjs-core` for auto-spans across
- * controllers, guards, pipes, interceptors, and middleware. Must run
- * before `@nestjs/core` is imported — see the README for the
- * `instrument.ts` pattern.
+ * Bootstraps `@interfere/node` and registers auto-instrumentation for
+ * NestJS controllers, guards, pipes, interceptors, and middleware.
+ *
+ * Uses two complementary instrumentation strategies:
+ * - `@opentelemetry/instrumentation-nestjs-core` for NestFactory and
+ *   router-level spans (when RITM hooks engage)
+ * - `InterfereNestInstrumentation` which patches `@Injectable` to wrap
+ *   middleware, guards, pipes, and interceptors at the decorator level
+ *   (always works, no RITM dependency for nested paths)
+ *
+ * Registers ESM loader hooks via `module.register()` so that
+ * `@nestjs/common` imports are intercepted for auto-instrumentation.
  */
 declare function init(options?: InitOptions$1): void;
 //#endregion

package/dist/init.d.mts

@@ -2,11 +2,18 @@ import { InitOptions, InitOptions as InitOptions$1 } from "@interfere/node";
 
 //#region src/init.d.ts
 /**
- * Bootstraps `@interfere/node` and registers
- * `@opentelemetry/instrumentation-nestjs-core` for auto-spans across
- * controllers, guards, pipes, interceptors, and middleware. Must run
- * before `@nestjs/core` is imported — see the README for the
- * `instrument.ts` pattern.
+ * Bootstraps `@interfere/node` and registers auto-instrumentation for
+ * NestJS controllers, guards, pipes, interceptors, and middleware.
+ *
+ * Uses two complementary instrumentation strategies:
+ * - `@opentelemetry/instrumentation-nestjs-core` for NestFactory and
+ *   router-level spans (when RITM hooks engage)
+ * - `InterfereNestInstrumentation` which patches `@Injectable` to wrap
+ *   middleware, guards, pipes, and interceptors at the decorator level
+ *   (always works, no RITM dependency for nested paths)
+ *
+ * Registers ESM loader hooks via `module.register()` so that
+ * `@nestjs/common` imports are intercepted for auto-instrumentation.
  */
 declare function init(options?: InitOptions$1): void;
 //#endregion

package/dist/init.mjs

@@ -1,2 +1,2 @@
-import{init as init$1}from"@interfere/node";import{registerInstrumentations}from"@opentelemetry/instrumentation";import{NestInstrumentation}from"@opentelemetry/instrumentation-nestjs-core";let instrumented=!1;function init(options={}){instrumented||=(registerInstrumentations({instrumentations:[new NestInstrumentation]}),!0),init$1(options)}export{init};
+import{InterfereNestInstrumentation}from"./nest-instrumentation.mjs";import{register}from"node:module";import{init as init$1}from"@interfere/node";import{registerInstrumentations}from"@opentelemetry/instrumentation";import{NestInstrumentation}from"@opentelemetry/instrumentation-nestjs-core";const INIT_KEY=`__interfereNestInitialized__`,g=globalThis;function init(options={}){g[INIT_KEY]||(typeof register==`function`&&register(`import-in-the-middle/hook.mjs`,import.meta.url),init$1(options),registerInstrumentations({instrumentations:[new NestInstrumentation,new InterfereNestInstrumentation]}),g[INIT_KEY]=!0)}export{init};
 //# sourceMappingURL=init.mjs.map

package/dist/instrument.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const require_init=require("./init.cjs");let _interfere_node=require("@interfere/node");Object.defineProperty(exports,"captureError",{enumerable:!0,get:function(){return _interfere_node.captureError}}),Object.defineProperty(exports,"captureMessage",{enumerable:!0,get:function(){return _interfere_node.captureMessage}}),Object.defineProperty(exports,"close",{enumerable:!0,get:function(){return _interfere_node.close}}),Object.defineProperty(exports,"flush",{enumerable:!0,get:function(){return _interfere_node.flush}}),exports.init=require_init.init,Object.defineProperty(exports,"withSpan",{enumerable:!0,get:function(){return _interfere_node.withSpan}});

package/dist/instrument.d.cts

@@ -0,0 +1,3 @@
+import { InitOptions, init } from "./init.cjs";
+import { CaptureErrorContext, captureError, captureMessage, close, flush, withSpan } from "@interfere/node";
+export { type CaptureErrorContext, type InitOptions, captureError, captureMessage, close, flush, init, withSpan };

package/dist/instrument.d.mts

@@ -0,0 +1,3 @@
+import { InitOptions, init } from "./init.mjs";
+import { CaptureErrorContext, captureError, captureMessage, close, flush, withSpan } from "@interfere/node";
+export { type CaptureErrorContext, type InitOptions, captureError, captureMessage, close, flush, init, withSpan };

package/dist/instrument.mjs

@@ -0,0 +1 @@
+import{init}from"./init.mjs";import{captureError,captureMessage,close,flush,withSpan}from"@interfere/node";export{captureError,captureMessage,close,flush,init,withSpan};

package/dist/module-entry.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const require_exception_filter=require("./exception-filter.cjs"),require_module=require("./module.cjs");Object.defineProperty(exports,"InterfereExceptionFilter",{enumerable:!0,get:function(){return require_exception_filter.InterfereExceptionFilter}}),Object.defineProperty(exports,"InterfereModule",{enumerable:!0,get:function(){return require_module.InterfereModule}});

package/dist/module-entry.d.cts

@@ -0,0 +1,3 @@
+import { InterfereExceptionFilter } from "./exception-filter.cjs";
+import { InterfereModule } from "./module.cjs";
+export { InterfereExceptionFilter, InterfereModule };

package/dist/module-entry.d.mts

@@ -0,0 +1,3 @@
+import { InterfereExceptionFilter } from "./exception-filter.mjs";
+import { InterfereModule } from "./module.mjs";
+export { InterfereExceptionFilter, InterfereModule };

package/dist/module-entry.mjs

@@ -0,0 +1 @@
+import{InterfereExceptionFilter}from"./exception-filter.mjs";import{InterfereModule}from"./module.mjs";export{InterfereExceptionFilter,InterfereModule};

package/dist/nest-instrumentation.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const require_package=require("./package.cjs");let _opentelemetry_instrumentation=require("@opentelemetry/instrumentation"),_opentelemetry_api=require("@opentelemetry/api");const SUPPORTED_VERSIONS=[`>=8.0.0 <12`],COMPONENT=`@nestjs/common`;var InterfereNestInstrumentation=class extends _opentelemetry_instrumentation.InstrumentationBase{constructor(config={}){super(require_package.name,require_package.version,config)}init(){let moduleDef=new _opentelemetry_instrumentation.InstrumentationNodeModuleDefinition(COMPONENT,SUPPORTED_VERSIONS);return moduleDef.files.push(this.getInjectableInstrumentation(SUPPORTED_VERSIONS)),moduleDef}getInjectableInstrumentation(versions){return new _opentelemetry_instrumentation.InstrumentationNodeModuleFile(`@nestjs/common/decorators/core/injectable.decorator.js`,versions,moduleExports=>((0,_opentelemetry_instrumentation.isWrapped)(moduleExports.Injectable)&&this._unwrap(moduleExports,`Injectable`),this._wrap(moduleExports,`Injectable`,original=>this.wrapInjectable(original)),moduleExports),moduleExports=>{this._unwrap(moduleExports,`Injectable`)})}wrapInjectable(original){let tracer=this.tracer;return function(options){return target=>target.__INTERFERE_PATCHED__?original(options)(target):(target.__INTERFERE_PATCHED__=!0,typeof target.prototype.use==`function`&&patchMethod(tracer,target,`use`,`middleware.nestjs`),typeof target.prototype.canActivate==`function`&&patchMethod(tracer,target,`canActivate`,`guard.nestjs`),typeof target.prototype.transform==`function`&&patchMethod(tracer,target,`transform`,`pipe.nestjs`),typeof target.prototype.intercept==`function`&&patchMethod(tracer,target,`intercept`,`interceptor.nestjs`),original(options)(target))}}};function patchMethod(tracer,target,method,op){let original=target.prototype[method];target.prototype[method]=function(...args){let span=tracer.startSpan(`${target.name}.${method}`,{kind:_opentelemetry_api.SpanKind.INTERNAL,attributes:{component:COMPONENT,"nestjs.type":op,"nestjs.callback":method,"nestjs.controller":target.name}}),ctx=_opentelemetry_api.trace.setSpan(_opentelemetry_api.context.active(),span);return _opentelemetry_api.context.with(ctx,()=>{try{let result=original.apply(this,args);return result&&typeof result.then==`function`?result.then(v=>(span.end(),v),err=>{throw span.recordException(err),span.setStatus({code:_opentelemetry_api.SpanStatusCode.ERROR}),span.end(),err}):(span.end(),result)}catch(err){throw span.recordException(err),span.setStatus({code:_opentelemetry_api.SpanStatusCode.ERROR}),span.end(),err}})}}exports.InterfereNestInstrumentation=InterfereNestInstrumentation;

package/dist/nest-instrumentation.d.cts

@@ -0,0 +1,12 @@
+import { InstrumentationBase, InstrumentationConfig, InstrumentationNodeModuleDefinition } from "@opentelemetry/instrumentation";
+
+//#region src/nest-instrumentation.d.ts
+declare class InterfereNestInstrumentation extends InstrumentationBase {
+  constructor(config?: InstrumentationConfig);
+  init(): InstrumentationNodeModuleDefinition;
+  private getInjectableInstrumentation;
+  private wrapInjectable;
+}
+//#endregion
+export { InterfereNestInstrumentation };
+//# sourceMappingURL=nest-instrumentation.d.cts.map

package/dist/nest-instrumentation.d.mts

@@ -0,0 +1,12 @@
+import { InstrumentationBase, InstrumentationConfig, InstrumentationNodeModuleDefinition } from "@opentelemetry/instrumentation";
+
+//#region src/nest-instrumentation.d.ts
+declare class InterfereNestInstrumentation extends InstrumentationBase {
+  constructor(config?: InstrumentationConfig);
+  init(): InstrumentationNodeModuleDefinition;
+  private getInjectableInstrumentation;
+  private wrapInjectable;
+}
+//#endregion
+export { InterfereNestInstrumentation };
+//# sourceMappingURL=nest-instrumentation.d.mts.map

package/dist/nest-instrumentation.mjs

@@ -0,0 +1,2 @@
+import{name,version}from"./package.mjs";import{InstrumentationBase,InstrumentationNodeModuleDefinition,InstrumentationNodeModuleFile,isWrapped}from"@opentelemetry/instrumentation";import{SpanKind,SpanStatusCode,context,trace}from"@opentelemetry/api";const SUPPORTED_VERSIONS=[`>=8.0.0 <12`],COMPONENT=`@nestjs/common`;var InterfereNestInstrumentation=class extends InstrumentationBase{constructor(config={}){super(name,version,config)}init(){let moduleDef=new InstrumentationNodeModuleDefinition(COMPONENT,SUPPORTED_VERSIONS);return moduleDef.files.push(this.getInjectableInstrumentation(SUPPORTED_VERSIONS)),moduleDef}getInjectableInstrumentation(versions){return new InstrumentationNodeModuleFile(`@nestjs/common/decorators/core/injectable.decorator.js`,versions,moduleExports=>(isWrapped(moduleExports.Injectable)&&this._unwrap(moduleExports,`Injectable`),this._wrap(moduleExports,`Injectable`,original=>this.wrapInjectable(original)),moduleExports),moduleExports=>{this._unwrap(moduleExports,`Injectable`)})}wrapInjectable(original){let tracer=this.tracer;return function(options){return target=>target.__INTERFERE_PATCHED__?original(options)(target):(target.__INTERFERE_PATCHED__=!0,typeof target.prototype.use==`function`&&patchMethod(tracer,target,`use`,`middleware.nestjs`),typeof target.prototype.canActivate==`function`&&patchMethod(tracer,target,`canActivate`,`guard.nestjs`),typeof target.prototype.transform==`function`&&patchMethod(tracer,target,`transform`,`pipe.nestjs`),typeof target.prototype.intercept==`function`&&patchMethod(tracer,target,`intercept`,`interceptor.nestjs`),original(options)(target))}}};function patchMethod(tracer,target,method,op){let original=target.prototype[method];target.prototype[method]=function(...args){let span=tracer.startSpan(`${target.name}.${method}`,{kind:SpanKind.INTERNAL,attributes:{component:COMPONENT,"nestjs.type":op,"nestjs.callback":method,"nestjs.controller":target.name}}),ctx=trace.setSpan(context.active(),span);return context.with(ctx,()=>{try{let result=original.apply(this,args);return result&&typeof result.then==`function`?result.then(v=>(span.end(),v),err=>{throw span.recordException(err),span.setStatus({code:SpanStatusCode.ERROR}),span.end(),err}):(span.end(),result)}catch(err){throw span.recordException(err),span.setStatus({code:SpanStatusCode.ERROR}),span.end(),err}})}}export{InterfereNestInstrumentation};
+//# sourceMappingURL=nest-instrumentation.mjs.map

package/dist/package.cjs

@@ -0,0 +1 @@
+var name=`@interfere/nest`,version=`0.0.1-canary.5`;Object.defineProperty(exports,"name",{enumerable:!0,get:function(){return name}}),Object.defineProperty(exports,"version",{enumerable:!0,get:function(){return version}});

package/dist/package.mjs

@@ -0,0 +1,2 @@
+var name=`@interfere/nest`,version=`0.0.1-canary.5`;export{name,version};
+//# sourceMappingURL=package.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interfere/nest",
-  "version": "0.0.1-canary.3",
+  "version": "0.0.1-canary.5",
   "license": "MIT",
   "description": "NestJS SDK for Interfere. Auto-captures uncaught exceptions from controllers, providers, and middleware via a global ExceptionFilter, plus re-exports the @interfere/node OTel instrumentation.",
   "keywords": [
@@ -43,6 +43,28 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./instrument": {
+      "monorepo": "./src/instrument.ts",
+      "import": {
+        "types": "./dist/instrument.d.mts",
+        "default": "./dist/instrument.mjs"
+      },
+      "require": {
+        "types": "./dist/instrument.d.cts",
+        "default": "./dist/instrument.cjs"
+      }
+    },
+    "./module": {
+      "monorepo": "./src/module-entry.ts",
+      "import": {
+        "types": "./dist/module-entry.d.mts",
+        "default": "./dist/module-entry.mjs"
+      },
+      "require": {
+        "types": "./dist/module-entry.d.cts",
+        "default": "./dist/module-entry.cjs"
+      }
     }
   },
   "sideEffects": false,
@@ -55,7 +77,8 @@
     "typecheck": "tsc --noEmit --incremental"
   },
   "dependencies": {
-    "@interfere/node": "^0.0.1-canary.3",
+    "@interfere/node": "^0.0.1-canary.5",
+    "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/instrumentation": "^0.218.0",
     "@opentelemetry/instrumentation-nestjs-core": "^0.64.0"
   },