@interfere/nest 0.0.1-canary.4 → 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 — must run before @nestjs/core is imported
-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/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/package.cjs

@@ -1 +1 @@
-var name=`@interfere/nest`,version=`0.0.1-canary.4`;Object.defineProperty(exports,"name",{enumerable:!0,get:function(){return name}}),Object.defineProperty(exports,"version",{enumerable:!0,get:function(){return version}});
+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

@@ -1,2 +1,2 @@
-var name=`@interfere/nest`,version=`0.0.1-canary.4`;export{name,version};
+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.4",
+  "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,7 @@
     "typecheck": "tsc --noEmit --incremental"
   },
   "dependencies": {
-    "@interfere/node": "^0.0.1-canary.4",
+    "@interfere/node": "^0.0.1-canary.5",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/instrumentation": "^0.218.0",
     "@opentelemetry/instrumentation-nestjs-core": "^0.64.0"