{"_id":"@aivorynet/monitor-agent-nodejs","_rev":"4-77c5f8b69921544af49c33dea99af037","name":"@aivorynet/monitor-agent-nodejs","dist-tags":{"latest":"1.0.2"},"versions":{"0.0.1":{"name":"@aivorynet/monitor-agent-nodejs","version":"0.0.1","keywords":["oidc","trusted-publishing","setup"],"_id":"@aivorynet/monitor-agent-nodejs@0.0.1","maintainers":[{"name":"jenni_aivory","email":"jenni@aivory.net"},{"name":"madppiper","email":"paul@aivory.net"}],"dist":{"shasum":"79a706a6462f82300e7abb716071dd112aedba07","tarball":"https://registry.npmjs.org/@aivorynet/monitor-agent-nodejs/-/monitor-agent-nodejs-0.0.1.tgz","fileCount":2,"integrity":"sha512-2abCEH8fBsXH5ajG/aryFplnlSsMKhuMF9MHyfXH+yDykz5YeTsbri8W5wnemt6Kdb8uG2RFSCb+B50/XwBPOQ==","signatures":[{"sig":"MEYCIQCcb4lH7M8WsQnKpd4L3ixyOu+OcNaKKS2otVtTf7KN+AIhAP/703Xsxp4SKcijAKBeRHQPmA/SYBxX5JKrCRfcJn3p","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2087},"_npmUser":{"name":"jenni_aivory","email":"jenni@aivory.net"},"_npmVersion":"11.10.0","description":"OIDC trusted publishing setup package for @aivorynet/monitor-agent-nodejs","directories":{},"_nodeVersion":"22.21.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/monitor-agent-nodejs_0.0.1_1771342339094_0.20461434996526728","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@aivorynet/monitor-agent-nodejs","version":"1.0.0","keywords":["aivory","monitor","debugging","exception","nodejs","agent"],"author":{"name":"AIVory"},"license":"MIT","_id":"@aivorynet/monitor-agent-nodejs@1.0.0","maintainers":[{"name":"jenni_aivory","email":"jenni@aivory.net"},{"name":"madppiper","email":"paul@aivory.net"}],"homepage":"https://aivory.net/monitor/","bugs":{"url":"https://github.com/aivorynet/agent-nodejs/issues"},"dist":{"shasum":"2643c311273d4ceed1d637df0d82835da4d031fc","tarball":"https://registry.npmjs.org/@aivorynet/monitor-agent-nodejs/-/monitor-agent-nodejs-1.0.0.tgz","fileCount":23,"integrity":"sha512-f7Cy7KUQxVnDCPq21WML0xry4Ll87vwzWMHOlapGlX+FqtNjnTGsSJlOW3IyEbI30w7MylAsqU6VzT1t34b43g==","signatures":[{"sig":"MEYCIQCAJqijEViiCl2YvPzFeGUOkkNkdyIHZGD1t45V0S/x1wIhALUmyMaBbC8qQ62YvPjRlhp4TlS8e2DKPc4UPxxziA/x","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aivorynet%2fmonitor-agent-nodejs@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":139232},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=16.0.0"},"gitHead":"e616d2b888bae7eac27a2b6b05e568f053cee914","scripts":{"lint":"eslint src/**/*.ts","test":"jest","build":"tsc","watch":"tsc --watch","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:e8353816-9b79-4a34-89fc-b9f4cb54da7e"}},"repository":{"url":"git+https://github.com/aivorynet/agent-nodejs.git","type":"git"},"_npmVersion":"11.10.0","description":"AIVory Monitor Node.js agent for exception capture and breakpoints","directories":{},"_nodeVersion":"22.22.0","dependencies":{"ws":"^8.16.0","source-map":"^0.7.4"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.56.0","ts-jest":"^29.1.1","@types/ws":"^8.5.10","typescript":"^5.3.3","@types/jest":"^29.5.11","@types/node":"^20.11.0","@typescript-eslint/parser":"^6.18.0","@typescript-eslint/eslint-plugin":"^6.18.0"},"_npmOperationalInternal":{"tmp":"tmp/monitor-agent-nodejs_1.0.0_1771343877901_0.007507504822557465","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aivorynet/monitor-agent-nodejs","version":"1.0.1","keywords":["aivory","monitor","debugging","exception","nodejs","agent"],"author":{"name":"AIVory"},"license":"MIT","_id":"@aivorynet/monitor-agent-nodejs@1.0.1","maintainers":[{"name":"jenni_aivory","email":"jenni@aivory.net"},{"name":"madppiper","email":"paul@aivory.net"}],"homepage":"https://aivory.net/monitor/","bugs":{"url":"https://github.com/aivorynet/agent-nodejs/issues"},"dist":{"shasum":"3e0d5871ef548b180417fe6f1dc2ddb75990c332","tarball":"https://registry.npmjs.org/@aivorynet/monitor-agent-nodejs/-/monitor-agent-nodejs-1.0.1.tgz","fileCount":23,"integrity":"sha512-QDilxvcKNhW+l5rFZMURr+rP2fuwax2lB1yw208SPDr6WqkZ4Obs17wKopcP1nPWkiBz5QknIXnAWI7Tz7zo6g==","signatures":[{"sig":"MEUCIHqyrVhOwR0qtKKQkuz9yoMV/BkhoaBz6RvRssbi9lkHAiEA+i8vmDDoN/vE3fyOVYuyCEZtc36AowbxUvXq6i1Rkec=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aivorynet%2fmonitor-agent-nodejs@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":139291},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=16.0.0"},"gitHead":"5e3155b35c30f136a71eb898ecdbe6b68193badc","scripts":{"lint":"eslint src/**/*.ts","test":"jest --passWithNoTests","build":"tsc","watch":"tsc --watch","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:e8353816-9b79-4a34-89fc-b9f4cb54da7e"}},"repository":{"url":"git+https://github.com/aivorynet/agent-nodejs.git","type":"git"},"_npmVersion":"11.10.0","description":"AIVory Monitor Node.js agent for exception capture and breakpoints","directories":{},"_nodeVersion":"22.22.0","dependencies":{"ws":"^8.16.0","source-map":"^0.7.4"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.56.0","ts-jest":"^29.1.1","@types/ws":"^8.5.10","typescript":"^5.3.3","@types/jest":"^29.5.11","@types/node":"^20.11.0","@typescript-eslint/parser":"^6.18.0","@typescript-eslint/eslint-plugin":"^6.18.0"},"_npmOperationalInternal":{"tmp":"tmp/monitor-agent-nodejs_1.0.1_1771411999829_0.7783678830275242","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@aivorynet/monitor-agent-nodejs","version":"1.0.2","description":"AIVory Monitor Node.js agent for exception capture and breakpoints","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","watch":"tsc --watch","test":"jest --passWithNoTests","lint":"eslint src/**/*.ts","prepublishOnly":"npm run build"},"keywords":["aivory","monitor","debugging","exception","nodejs","agent"],"author":{"name":"AIVory"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aivorynet/agent-nodejs.git"},"homepage":"https://aivory.net/monitor/","bugs":{"url":"https://github.com/aivorynet/agent-nodejs/issues"},"engines":{"node":">=16.0.0"},"dependencies":{"ws":"^8.16.0","source-map":"^0.7.4"},"devDependencies":{"@types/node":"^20.11.0","@types/ws":"^8.5.10","typescript":"^5.3.3","jest":"^29.7.0","@types/jest":"^29.5.11","ts-jest":"^29.1.1","eslint":"^8.56.0","@typescript-eslint/eslint-plugin":"^6.18.0","@typescript-eslint/parser":"^6.18.0"},"gitHead":"b085d7e7caa3c49eb656e6092cb41d81211c4c22","_id":"@aivorynet/monitor-agent-nodejs@1.0.2","_nodeVersion":"22.22.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-NWKCgVB0WoftNald4NIqHeV/gYwX8wZy49U6lWgoj7bVcz+EwI2fw+Y3B63BnMfepBPLHdpACtrlerHYIdsE+Q==","shasum":"d84d50363c57bd05b8b06edd0ece1c2a88c847b1","tarball":"https://registry.npmjs.org/@aivorynet/monitor-agent-nodejs/-/monitor-agent-nodejs-1.0.2.tgz","fileCount":23,"unpackedSize":139296,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aivorynet%2fmonitor-agent-nodejs@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCeS1VaHRQR+5htluRpYLXixCu1jbh968vbJlZJOGsqMwIgP6GoypOPnN1o/DX2rJWq9zl576K/h/3befTDQVxGps0="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:e8353816-9b79-4a34-89fc-b9f4cb54da7e"}},"directories":{},"maintainers":[{"name":"jenni_aivory","email":"jenni@aivory.net"},{"name":"madppiper","email":"paul@aivory.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/monitor-agent-nodejs_1.0.2_1772199472100_0.8417410674923218"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-17T15:32:19.004Z","modified":"2026-02-27T13:37:52.566Z","0.0.1":"2026-02-17T15:32:19.253Z","1.0.0":"2026-02-17T15:57:58.058Z","1.0.1":"2026-02-18T10:53:19.973Z","1.0.2":"2026-02-27T13:37:52.251Z"},"bugs":{"url":"https://github.com/aivorynet/agent-nodejs/issues"},"author":{"name":"AIVory"},"license":"MIT","homepage":"https://aivory.net/monitor/","keywords":["aivory","monitor","debugging","exception","nodejs","agent"],"repository":{"type":"git","url":"git+https://github.com/aivorynet/agent-nodejs.git"},"description":"AIVory Monitor Node.js agent for exception capture and breakpoints","maintainers":[{"name":"jenni_aivory","email":"jenni@aivory.net"},{"name":"madppiper","email":"paul@aivory.net"}],"readme":"# AIVory Monitor Node.js Agent\n\nNode.js agent using V8 Inspector Protocol for capturing exceptions and breakpoint data.\n\n## Requirements\n\n- Node.js 16+ (V8 Inspector Protocol)\n- npm or yarn\n\n## Installation\n\n```bash\nnpm install @aivory/monitor\n# or\nyarn add @aivory/monitor\n```\n\n## Usage\n\n### Option 1: Require Hook (Recommended)\n\n```bash\n# Set API key\nexport AIVORY_API_KEY=your_api_key\n\n# Run with require hook\nnode -r @aivory/monitor app.js\n\n# Or in package.json\n{\n  \"scripts\": {\n    \"start\": \"node -r @aivory/monitor app.js\"\n  }\n}\n```\n\n### Option 2: Programmatic Initialization\n\n```javascript\nimport { init } from '@aivory/monitor';\n// or: const { init } = require('@aivory/monitor');\n\ninit({\n  apiKey: process.env.AIVORY_API_KEY,\n  environment: 'production'\n});\n\n// Your application code\n```\n\n### Option 3: Framework Middleware\n\n**Express:**\n```javascript\nimport express from 'express';\nimport { expressMiddleware } from '@aivory/monitor';\n\nconst app = express();\napp.use(expressMiddleware({ apiKey: process.env.AIVORY_API_KEY }));\n```\n\n**Fastify:**\n```javascript\nimport Fastify from 'fastify';\nimport { fastifyPlugin } from '@aivory/monitor';\n\nconst app = Fastify();\napp.register(fastifyPlugin, { apiKey: process.env.AIVORY_API_KEY });\n```\n\n**NestJS:**\n```typescript\nimport { Module } from '@nestjs/common';\nimport { AIVoryMonitorModule } from '@aivory/monitor/nestjs';\n\n@Module({\n  imports: [\n    AIVoryMonitorModule.forRoot({\n      apiKey: process.env.AIVORY_API_KEY\n    })\n  ]\n})\nexport class AppModule {}\n```\n\n## Configuration\n\n```typescript\ninit({\n  // Required\n  apiKey: string,\n\n  // Optional\n  backendUrl: string,           // default: 'wss://api.aivory.net'\n  environment: string,          // default: process.env.NODE_ENV\n\n  // Capture settings\n  capture: {\n    maxDepth: number,           // default: 3\n    maxStringLength: number,    // default: 1000\n    maxArrayLength: number,     // default: 100\n  },\n\n  // Filtering\n  include: string[],            // glob patterns to include\n  exclude: string[],            // default: ['node_modules/**']\n\n  // Performance\n  sampling: {\n    rate: number,               // 0-1, default: 1 (all)\n    maxPerMinute: number,       // rate limit\n  },\n\n  // Source maps\n  sourceMaps: {\n    enabled: boolean,           // default: true\n    uploadMaps: boolean,        // upload to backend\n  }\n});\n```\n\n## Building from Source\n\n```bash\ncd agent-nodejs\nnpm install\nnpm run build\n```\n\n## How It Works\n\n1. **V8 Inspector Protocol**: Uses Node's built-in debugger for breakpoint support\n2. **Exception Handling**: Hooks `process.on('uncaughtException')` and `unhandledRejection`\n3. **Async Context**: Uses `AsyncLocalStorage` to track request context\n4. **Source Maps**: Automatically resolves TypeScript/Babel source maps\n\n## TypeScript Support\n\nFull TypeScript support with type definitions included.\n\n## Local Development Testing\n\n### Quick Test (with test-app.js)\n\n```bash\ncd monitor-agents/agent-nodejs\nnpm run build\nnode test-app.js\n```\n\nThis connects to the local backend and triggers sample exceptions automatically.\n\n### Interactive Test Server\n\nStart a test HTTP server that you can hit to trigger exceptions on demand:\n\n```bash\ncd monitor-agents/agent-nodejs\nnode -e \"\nconst monitor = require('./dist');\n\nmonitor.init({\n  apiKey: 'ilscipio-dev-2024',\n  backendUrl: 'ws://localhost:19999/ws/monitor/agent',\n  environment: 'development',\n  debug: true\n});\n\nconst http = require('http');\nconst server = http.createServer((req, res) => {\n  if (req.url === '/error') throw new Error('Test sync error');\n  if (req.url === '/null') { const x = null; x.foo(); }\n  if (req.url === '/async') {\n    setTimeout(() => { throw new Error('Async error'); }, 100);\n    res.end('Async error in 100ms'); return;\n  }\n  res.end('Endpoints: /error, /null, /async');\n});\n\nserver.listen(3333, () => console.log('Test server: http://localhost:3333'));\n\"\n```\n\n**Test URLs:**\n- http://localhost:3333/error - Throws synchronous Error\n- http://localhost:3333/null - Throws TypeError (null pointer)\n- http://localhost:3333/async - Throws async Error after 100ms\n\n### Prerequisites for Local Testing\n\n1. Backend running on `localhost:19999`\n2. Dev token bypass enabled (uses `ilscipio-dev-2024`)\n3. Org schema `org_test_20` exists in database\n\n## Troubleshooting\n\n**Breakpoints not working:**\n- Ensure source maps are available\n- Check file paths match between IDE and runtime\n\n**High memory usage:**\n- Reduce `capture.maxDepth`\n- Exclude large objects from capture\n\n**Source map issues:**\n- Ensure `.map` files are deployed\n- Check `sourceMaps.enabled` is true\n\n**Agent not connecting:**\n- Check backend is running: `curl http://localhost:19999/health`\n- Check WebSocket endpoint: `ws://localhost:19999/ws/monitor/agent`\n- Verify dev token is accepted in backend logs\n","readmeFilename":"README.md"}