{"_id":"@alikhan-devs/watchtower-sdk","_rev":"2-23b381c10599663c37bdaabed4d299c4","name":"@alikhan-devs/watchtower-sdk","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@alikhan-devs/watchtower-sdk","version":"1.0.0","keywords":["monitoring","express","metrics","watchtower","apm"],"license":"MIT","_id":"@alikhan-devs/watchtower-sdk@1.0.0","maintainers":[{"name":"alikhan-devs","email":"alikhandevs@gmail.com"}],"dist":{"shasum":"7d6cab56fd25c79f794c276e59469367eababf17","tarball":"https://registry.npmjs.org/@alikhan-devs/watchtower-sdk/-/watchtower-sdk-1.0.0.tgz","fileCount":13,"integrity":"sha512-atALDhYEHCbEmi2r38Mj7T5ZXHCBmE9+TcutSjMQSha/WSSX3wgLA+y/ThX02LRlUCCZ+hK4oJXgtNNysOeoDQ==","signatures":[{"sig":"MEQCIBWWim/ReTLOuU55mmOa511OzC5/vXHo3T27QJAw/FVxAiAb8lnwfg100khyZl5qeNIqDev2HUClGYtxoyugGaJuCQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13568},"main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"dev":"npx tsc --watch","build":"npx tsc","prepare":"npm run build"},"_npmUser":{"name":"alikhan-devs","email":"alikhandevs@gmail.com"},"_npmVersion":"11.8.0","description":"Lightweight monitoring SDK for Express apps — automatically tracks response times, error rates, and sends metrics to WatchTower.","directories":{},"_nodeVersion":"24.13.1","_hasShrinkwrap":false,"devDependencies":{"typescript":"^6.0.2","@types/node":"^24.6.0","@types/express":"^5.0.3"},"peerDependencies":{"express":"^4.18.0 || ^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/watchtower-sdk_1.0.0_1774344542426_0.8181188010969231","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@alikhan-devs/watchtower-sdk","version":"1.0.1","description":"Lightweight monitoring SDK for Express apps — automatically tracks response times, error rates, and sends metrics to WatchTower.","main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"npx tsc","dev":"npx tsc --watch","prepare":"npm run build"},"keywords":["monitoring","express","metrics","watchtower","apm"],"license":"MIT","peerDependencies":{"express":"^4.18.0 || ^5.0.0"},"devDependencies":{"@types/express":"^5.0.3","@types/node":"^24.6.0","typescript":"^6.0.2"},"gitHead":"062bdb6443d1ac2553543b551270538578baedd1","_id":"@alikhan-devs/watchtower-sdk@1.0.1","_nodeVersion":"24.13.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-nv1pCcjJtt5eZtgWsN1K1XNWjq8uv8CloWPQpTcYxqYqcPAQ3GtY2/OVd4eyswFQq+YZ6B71v5zEpayHfFgUsg==","shasum":"0cf38365d51b431f3b25e693209d36c4fa19333e","tarball":"https://registry.npmjs.org/@alikhan-devs/watchtower-sdk/-/watchtower-sdk-1.0.1.tgz","fileCount":14,"unpackedSize":17870,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDatnpGM7+KPpAO7o4Ii0ipTULsDAMcIukBBTntlNmTFAIgNpH4uTsyNZrGB4fHzqk/gBFwNS6UUbJoisbmh+S9WOk="}]},"_npmUser":{"name":"alikhan-devs","email":"alikhandevs@gmail.com"},"directories":{},"maintainers":[{"name":"alikhan-devs","email":"alikhandevs@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/watchtower-sdk_1.0.1_1774369374046_0.43529128290447705"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-24T09:29:02.029Z","modified":"2026-03-24T16:22:54.308Z","1.0.0":"2026-03-24T09:29:02.576Z","1.0.1":"2026-03-24T16:22:54.189Z"},"license":"MIT","keywords":["monitoring","express","metrics","watchtower","apm"],"description":"Lightweight monitoring SDK for Express apps — automatically tracks response times, error rates, and sends metrics to WatchTower.","maintainers":[{"name":"alikhan-devs","email":"alikhandevs@gmail.com"}],"readme":"# @alikhan-devs/watchtower-sdk\n\nLightweight Express monitoring middleware for [WatchTower](https://github.com/AliKhan-Devs/WatchTower).\n\nDrop it into your app and it will automatically:\n\n- Track response time for every request\n- Capture status codes and error-rate data\n- Normalize route patterns like `/users/123` to `/users/:id`\n- Batch metrics and send them to your WatchTower API\n- Flush in the background without keeping your Node process alive\n\n## Installation\n\n```bash\nnpm install @alikhan-devs/watchtower-sdk\n```\n\nThis package has a peer dependency on Express:\n\n```bash\nnpm install express\n```\n\n## Requirements\n\n- Node.js 18+ recommended\n- Express 4.18+ or 5+\n- A WatchTower app `apiKey` from your dashboard\n- Your WatchTower API base URL\n\n## Quick Start\n\n### CommonJS\n\n```js\nconst express = require('express');\nconst { watchTower } = require('@alikhan-devs/watchtower-sdk');\n\nconst app = express();\n\napp.use(watchTower({\n  apiKey: 'your-app-api-key',\n  host: 'http://localhost:3000'\n}));\n\napp.get('/users/:id', (req, res) => {\n  res.json({ id: req.params.id });\n});\n\napp.listen(4000);\n```\n\n### ESM / TypeScript\n\n```ts\nimport express from 'express';\nimport { watchTower } from '@alikhan-devs/watchtower-sdk';\n\nconst app = express();\n\napp.use(watchTower({\n  apiKey: 'your-app-api-key',\n  host: 'http://localhost:3000'\n}));\n\napp.get('/health', (_req, res) => {\n  res.send('ok');\n});\n\napp.listen(4000);\n```\n\n## How It Works\n\nThe middleware listens for each response `finish` event, records:\n\n- `route`\n- `method`\n- `statusCode`\n- `responseTime`\n- `timestamp`\n\nIt then batches those metrics and sends them to:\n\n```http\nPOST /api/ingest\n```\n\nwith:\n\n```http\nx-api-key: <your-app-api-key>\n```\n\n## API\n\n### `watchTower(options)`\n\nCreates the Express middleware and starts the background flusher.\n\n```ts\nimport { watchTower } from '@alikhan-devs/watchtower-sdk';\n\nconst middleware = watchTower({\n  apiKey: 'your-app-api-key',\n  host: 'http://localhost:3000',\n  flushIntervalMs: 10000,\n  maxBatchSize: 100,\n  debug: false\n});\n```\n\n### Options\n\n| Option | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `apiKey` | `string` | Yes | - | App API key from WatchTower dashboard |\n| `host` | `string` | No | `http://localhost:3000` | Base URL of your WatchTower API |\n| `flushIntervalMs` | `number` | No | `10000` | Flush queued metrics every N milliseconds |\n| `maxBatchSize` | `number` | No | `100` | Flush immediately once queue reaches this size |\n| `debug` | `boolean` | No | `false` | Log SDK flush activity to console |\n\n## Graceful Shutdown\n\nThe returned middleware includes a `.stop()` method so you can flush remaining metrics before process exit.\n\n```ts\nimport express from 'express';\nimport { watchTower } from '@alikhan-devs/watchtower-sdk';\n\nconst app = express();\nconst monitoring = watchTower({\n  apiKey: 'your-app-api-key',\n  host: 'http://localhost:3000'\n});\n\napp.use(monitoring);\n\nprocess.on('SIGTERM', async () => {\n  await monitoring.stop?.();\n  process.exit(0);\n});\n```\n\n## What Gets Ignored\n\nThe middleware skips:\n\n- `/health`\n- `/favicon`\n\n## Route Normalization\n\nIf Express provides the matched route, the SDK uses it directly.\n\nExamples:\n\n- `/users/123` -> `/users/:id`\n- `/orders/550e8400-e29b-41d4-a716-446655440000` -> `/orders/:id`\n- Long cuid-style IDs are also normalized to `:id`\n\nThis keeps your dashboard clean and prevents route-cardinality explosions.\n\n## Advanced Exports\n\nIf you need more control, the package also exports:\n\n```ts\nimport { WatchTowerClient, createMiddleware } from '@alikhan-devs/watchtower-sdk';\n```\n\n## Dependencies\n\n### Runtime dependencies\n\nThis package currently has no direct runtime dependencies.\n\n### Peer dependencies\n\n- `express`: `^4.18.0 || ^5.0.0`\n\nThat means users should install `express` in their own app:\n\n```bash\nnpm install express\n```\n\n## Troubleshooting\n\n### No metrics appearing\n\n- Make sure `host` points to your WatchTower API, not the dashboard URL\n- Make sure `apiKey` is the app API key from WatchTower\n- Enable `debug: true` to inspect flush behavior\n- Confirm your WatchTower API is reachable from the monitored app\n\n### Using Node below 18\n\nThis SDK relies on `fetch`. If you are on an older Node version, upgrade Node or provide a compatible fetch polyfill in your environment.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}