midline-agent 0.1.5 → 0.1.7

package/README.md

@@ -32,10 +32,20 @@ After login, navigate to your **Dashboard → API Keys** and generate a key for
 ### 2. Install Package
 
 ```bash
-npm install midline-agent express
+npm install midline-agent
 ```
 
-### Basic Usage
+Choose one of the guides below based on your framework.
+
+---
+
+## Framework Setup
+
+### Express.js
+
+```bash
+npm install midline-agent express
+```
 
 ```ts
 import express from "express";
@@ -43,60 +53,243 @@ import { MidlineAgent, midlineMiddleware, midlineErrorHandler } from "midline-ag
 
 const app = express();
 
-// Initialize Midline Agent
+// Initialize Midline Agent (do this once, early in your app startup)
 MidlineAgent.init({
-  apiKey: "YOUR_API_KEY_FROM_MIDLINE",  // Get this from https://midline.com
-  serviceName: "my-express-service",
-  maskFields: ["password", "token"]      // Optional fields to mask
+  apiKey: process.env.MIDLINE_KEY!,
+  serviceName: "checkout-api",
+  environment: "production",
+  maskFields: ["password", "token", "card_number", "cvv"]
 });
 
-// Middleware to capture requests
+// Parse incoming JSON
 app.use(express.json());
+
+// Add request capture middleware BEFORE your routes
 app.use(midlineMiddleware());
 
-// Example route
-app.get("/hello", (req, res) => res.json({ msg: "Hello World" }));
+// Your routes here
+app.get("/health", (req, res) => res.json({ status: "ok" }));
+app.post("/v1/charges", async (req, res) => {
+  // Handle payment processing
+  res.json({ success: true });
+});
 
-// Middleware to capture errors
+// Add error handler middleware AFTER your routes
+// This must be the last middleware registered
 app.use(midlineErrorHandler());
 
-// Start server
 app.listen(3000, () => console.log("Server running on port 3000"));
 ```
 
-### Advanced Configuration
-- maskFields: Array of sensitive fields to exclude from logs (e.g., passwords, tokens)
-- endpoint: Optional — override default Midline Cloud endpoint
-- serviceName: Unique identifier for your application
+**Key points:**
+- `MidlineAgent.init()` must be called once during app startup
+- `midlineMiddleware()` captures all requests and responses
+- `midlineErrorHandler()` must be registered **after** all other middleware and routes
+- Express only routes errors to handlers declared after the code that threw, so order matters
 
-### Developer Example
+---
+
+### NestJS
+
+```bash
+npm install midline-agent
+```
+
+**Using with NestJS requires wrapping the Express middleware. Here's the setup:**
 
 ```ts
-// example.ts
-import express from "express";
-import { MidlineAgent, midlineMiddleware, midlineErrorHandler } from "midline-agent";
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { MidlineAgent, midlineMiddleware, midlineErrorHandler } from 'midline-agent';
 
-const app = express();
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  // Initialize Midline Agent early in bootstrap
+  MidlineAgent.init({
+    apiKey: process.env.MIDLINE_KEY!,
+    serviceName: 'nest-api',
+    environment: process.env.NODE_ENV || 'development',
+    maskFields: ['password', 'token', 'apiKey', 'secret']
+  });
+
+  // Apply request capture middleware
+  app.use(midlineMiddleware());
+
+  // Apply error handler after NestJS is configured
+  app.use(midlineErrorHandler());
+
+  await app.listen(3000);
+}
+
+bootstrap();
+```
+
+**For module-level integration, create a middleware:**
+
+```ts
+// midline.middleware.ts
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { midlineMiddleware, midlineErrorHandler } from 'midline-agent';
+import { Request, Response, NextFunction } from 'express';
+
+@Injectable()
+export class MidlineMiddleware implements NestMiddleware {
+  use(req: Request, res: Response, next: NextFunction) {
+    midlineMiddleware()(req, res, next);
+  }
+}
+```
+
+Then apply it in your module:
+
+```ts
+import { Module, MiddlewareConsumer } from '@nestjs/common';
+import { MidlineMiddleware } from './midline.middleware';
+
+@Module({
+  imports: [],
+  controllers: [],
+  providers: [],
+})
+export class AppModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer
+      .apply(MidlineMiddleware)
+      .forRoutes('*');
+  }
+}
+```
+
+---
+
+### Plain Node.js / HTTP Server
+
+If you're not using Express or NestJS, you can integrate midline-agent by manually wrapping your request handlers:
+
+```ts
+import http from 'http';
+import { MidlineAgent, midlineMiddleware, midlineErrorHandler } from 'midline-agent';
 
 MidlineAgent.init({
-  apiKey: "YOUR_API_KEY",
-  serviceName: "example-service",
-  maskFields: ["password"]
+  apiKey: process.env.MIDLINE_KEY!,
+  serviceName: 'raw-node-server',
+  environment: 'production',
+  maskFields: ['password', 'token']
 });
 
-app.use(express.json());
-app.use(midlineMiddleware());
+const server = http.createServer((req, res) => {
+  // Create Express-like req/res wrapper for middleware
+  const next = (err?: any) => {
+    if (err) throw err;
+    // Handle your route
+    if (req.url === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ok' }));
+    } else {
+      res.writeHead(404);
+      res.end('Not Found');
+    }
+  };
+
+  midlineMiddleware()(req, res, next);
+});
 
-app.get("/", (req, res) => res.send("Hello Midline!"));
+server.listen(3000, () => console.log('Server listening on port 3000'));
+```
 
-app.use(midlineErrorHandler());
+---
+
+## Configuration Options
 
-app.listen(3000, () => console.log("Example server running on port 3000"));
+```ts
+MidlineAgent.init({
+  // Required
+  apiKey: string;                  // Get from https://midline.com/dashboard/api-keys
+  serviceName: string;              // Name of your service (e.g., "checkout-api", "auth-service")
+
+  // Optional
+  maskFields?: string[];            // Field names to mask before sending (passwords, tokens, etc)
+  environment?: string;             // e.g., "production", "staging", "development"
+  endpoint?: string;                // Override default ingest URL (for self-hosted)
+  host?: string;                    // Machine/pod name for identifying instances
+  region?: string;                  // Deployment region (e.g., "us-east-1", "eu-west-1")
+});
 ```
 
 ---
 
-## Any other backend
+## Sensitive Field Masking
+
+By default, `maskFields` removes the following fields before serialization:
+- `password`
+- `token`
+- `apiKey`
+- `secret`
+- `authorization`
+
+Add custom fields as needed:
+
+```ts
+MidlineAgent.init({
+  apiKey: process.env.MIDLINE_KEY!,
+  serviceName: 'checkout-api',
+  maskFields: [
+    'password',
+    'card_number',
+    'cvv',
+    'ssn',
+    'oauth_token',
+    'jwt'
+  ]
+});
+```
+
+**Important:** Masking happens in your process before the event is built. Masked values never leave your machine and are never stored on Midline servers.
+
+---
+
+## Error Handling
+
+The error handler middleware captures:
+- Unhandled errors thrown by your route handlers
+- HTTP error responses
+- Validation errors
+
+**Example with error throwing:**
+
+```ts
+app.post('/v1/charges', (req, res, next) => {
+  try {
+    if (!req.body.amount) {
+      throw new Error('Amount is required');
+    }
+    // Process payment...
+  } catch (error) {
+    next(error); // Pass to Midline error handler
+  }
+});
+
+// The error handler will capture and report this
+app.use(midlineErrorHandler());
+```
+
+---
+
+## How Delivery Works
+
+- Events are queued in memory and flushed to Midline Cloud every 1.5 seconds
+- Request capturing is non-blocking — your response is sent before telemetry is reported
+- No network call can slow down your API responses
+
+**Important for production:**
+- In-memory events are lost if your process crashes before the flush interval
+- This is acceptable for monitoring telemetry (good for operations, not billing/audit)
+- For high-traffic services, consider using the batch endpoint directly for reliability
+
+---
+
+## Not using Node.js? Any other backend
 
 This agent does two things: it turns a request or an error into an event, and it POSTs that event to
 the Midline ingest API. Both are things your own service can do directly, in whatever language it
@@ -106,8 +299,8 @@ is written in.
 
 | Endpoint | Use |
 | --- | --- |
-| `POST https://api.midline.com/api/api-monitor/events` | One event |
-| `POST https://api.midline.com/api/api-monitor/events/batch` | Many events — `{ "events": [ … ] }` |
+| `POST https://api.usemidline.com/api/api-monitor/events` | One event |
+| `POST https://api.usemidline.com/api/api-monitor/events/batch` | Many events — `{ "events": [ … ] }` |
 
 The API key identifies your organisation and travels in the body; there is no separate auth header.
 
@@ -134,7 +327,7 @@ be stored.
 **curl**
 
 ```bash
-curl -X POST https://api.midline.com/api/api-monitor/events \
+curl -X POST https://api.usemidline.com/api/api-monitor/events \
   -H "Content-Type: application/json" \
   -d '{
     "apiKey": "YOUR_API_KEY",
@@ -155,7 +348,7 @@ curl -X POST https://api.midline.com/api/api-monitor/events \
 ```python
 import requests, threading
 
-INGEST = "https://api.midline.com/api/api-monitor/events"
+INGEST = "https://api.usemidline.com/api/api-monitor/events"
 
 def report(event: dict) -> None:
     event["apiKey"] = MIDLINE_KEY
@@ -194,7 +387,7 @@ func Report(e Event) {
     e.APIKey = os.Getenv("MIDLINE_KEY")
     body, _ := json.Marshal(e)
     go http.Post(
-        "https://api.midline.com/api/api-monitor/events",
+        "https://api.usemidline.com/api/api-monitor/events",
         "application/json",
         bytes.NewReader(body),
     ) // fire and forget

package/dist/agent.js

@@ -8,7 +8,7 @@ const cross_fetch_1 = __importDefault(require("cross-fetch"));
 class MidlineAgent {
     static init(config) {
         this.config = {
-            endpoint: "https://api.midline.com/api/api-monitor/events",
+            endpoint: "https://api.usemidline.com/api/api-monitor/events",
             maskFields: ["password", "token", ...(config.maskFields || [])],
             ...config,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "midline-agent",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Express.js SDK for Midline — request & error monitoring with security detection",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/agent.ts

@@ -8,7 +8,7 @@ export class MidlineAgent {
 
   static init(config: MidlineConfig) {
     this.config = {
-      endpoint: "https://api.midline.com/api/api-monitor/events",
+      endpoint: "https://api.usemidline.com/api/api-monitor/events",
       maskFields: ["password", "token", ...(config.maskFields || [])],
       ...config,
     };