@dropout-ai/runtime 0.3.8 → 0.3.10

package/README.md

@@ -1,36 +1,186 @@
-# @dropout-ai/runtime
+# 🕵️ Dropout AI Runtime (`@dropout-ai/runtime`)
 
-The invisible Node.js sensor for AI observability.
+**Universal AI Behavior Analysis & Capture for Node.js**
 
-## Overview
+Dropout is a lightweight, "install-and-forget" runtime that automatically captures AI interactions (prompts & responses) from your application without requiring code changes. It acts as a passive observer, patching the network layer to ensure you never miss a conversation.
 
-`@dropout-ai/runtime` is a zero-dependency, fire-and-forget telemetry sensor that automatically captures OpenAI API interactions from your Node.js or Next.js application.
+* **🔌 Universal:** Works with OpenAI, Anthropic, Genkit, LangChain, Axios, and `fetch`.
+* **🛡️ Safe:** Designed for production with silent failure modes and browser guards.
+* **⚡ Zero-Latency:** Uses fire-and-forget logging to ensure your app stays fast.
+* **🔋 Auto-Discovery:** Automatically detects framework (Next.js, NestJS) and configures itself.
 
-## Installation
+---
+
+## 🚀 Quick Start (Recommended)
+
+Run our initialization wizard in your project root. It will detect your framework and automatically create the necessary configuration files.
+
+```bash
+npx @dropout-ai/runtime init
+
+```
+
+*Supports: **Next.js** (App Router), **NestJS**, **Express**, and standard **Node.js** apps.*
+
+---
+
+## 🛠️ Manual Installation
+
+If you prefer to configure it yourself, install the package and follow the guide for your specific framework.
 
 ```bash
 npm install @dropout-ai/runtime
+# or
+yarn add @dropout-ai/runtime
+
 ```
 
-## Usage
+### 1. Next.js (App Router)
+
+Next.js uses lazy-loading, so we use `instrumentation.ts` to ensure Dropout loads immediately on server boot.
+
+**Create/Edit:** `src/instrumentation.ts` (or `instrumentation.ts` in root)
+
+```typescript
+export async function register() {
+  // Ensure we only run on the Node.js server runtime
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('@dropout-ai/runtime');
+    console.log('✅ Dropout AI Monitoring Active');
+  }
+}
+
+```
 
-Simply import the package at the very top of your application's entry point (e.g., `index.js` or `instrumentation.ts`):
+### 2. Node.js / Express / Fastify
+
+Initialize Dropout at the **very top** of your entry file (`index.js` or `server.js`), before importing other libraries.
 
 ```javascript
-import "@dropout-ai/runtime";
+// MUST be the first line
+require('@dropout-ai/runtime'); 
+
+const express = require('express');
+const app = express();
+// ... rest of your code
+
 ```
 
-Once imported, it automatically:
-1.  Patches `global.fetch`.
-2.  Detects OpenAI API calls.
-3.  Reports telemetry to your local Dropout backend (defaulting to `http://localhost:3000/capture`).
-4.  Fails gracefully and silently without affecting your production traffic.
+### 3. NestJS
+
+Initialize Dropout inside your `bootstrap()` function before creating the Nest app.
+
+**File:** `src/main.ts`
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import Dropout from '@dropout-ai/runtime';
+
+async function bootstrap() {
+  // ✅ Initialize first - Sends "Boot Ping" immediately
+  new Dropout({ 
+    projectId: process.env.DROPOUT_PROJECT_ID, 
+    apiKey: process.env.DROPOUT_API_KEY 
+  });
+
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+bootstrap();
+
+```
+
+### 4. Docker / Zero-Code Injection
+
+You can inject Dropout into any Node.js application without editing a single file by using the Node `--require` flag. This is perfect for Docker containers or PaaS deployments.
+
+```bash
+# 1. Set credentials
+export DROPOUT_PROJECT_ID="your_project_id"
+export DROPOUT_API_KEY="dp_live_..."
+
+# 2. Run your app with the runtime injected
+node -r @dropout-ai/runtime dist/index.js
+
+```
+
+---
+
+## ⚙️ Configuration
+
+You can configure Dropout via **Environment Variables** (Recommended) or by passing options to the constructor.
+
+| Environment Variable | Config Option | Description | Required |
+| --- | --- | --- | --- |
+| `DROPOUT_PROJECT_ID` | `projectId` | Your Project ID from dashboard. | ✅ |
+| `DROPOUT_API_KEY` | `apiKey` | Your Secret Key (`dp_live_...`). | ✅ |
+| `DROPOUT_DEBUG` | `debug` | Set `true` to see logs in console and enable connectivity checks. | No |
+| `DROPOUT_PRIVACY` | `privacy` | `full` (capture text) or `mask` (metadata only). | No |
+
+**Example `.env` file:**
+
+```bash
+DROPOUT_PROJECT_ID="HomeOS"
+DROPOUT_API_KEY="dp_live_xyz123..."
+DROPOUT_DEBUG="true"
+
+```
+
+---
+
+## 🌐 Supported Environments
+
+| Language/Framework | Status | Integration Method |
+| --- | --- | --- |
+| **Node.js** (v18+) | ✅ Ready | `require('@dropout-ai/runtime')` |
+| **Next.js** | ✅ Ready | `instrumentation.ts` |
+| **NestJS** | ✅ Ready | `main.ts` import |
+| **Python / Java / Go** | 🚧 Beta | Use REST API (see below) |
+
+### Non-Node.js Usage (REST API)
+
+If you are using Python, Java, or Go, you can manually send interaction logs to our ingestion endpoint.
+
+**Endpoint:** `POST https://hipughmjlwmwjxzyxfzs.supabase.co/functions/v1/capture-sealed`
+
+**Headers:**
+
+* `Content-Type: application/json`
+* `x-dropout-key: YOUR_API_KEY`
+
+**Payload:**
+
+```json
+{
+  "project_id": "your_project_id",
+  "turn_role": "assistant",       // or "user"
+  "content": "AI response text...",
+  "model": "gpt-4",               // optional
+  "provider": "openai",           // optional
+  "latency_ms": 1250              // optional
+}
+
+```
+
+---
+
+## ❓ Troubleshooting
+
+**Q: I don't see any logs in the dashboard.**
+
+1. Ensure `DROPOUT_DEBUG="true"` is set.
+2. Check your console for `[Dropout] 🟢 Online: <ProjectID>`.
+3. If using Next.js, ensure you created `instrumentation.ts` in the correct folder (root or `src`).
+
+**Q: Does this work with Edge Functions (Vercel Edge / Cloudflare)?**
+No. This runtime relies on Node.js core modules (`http`, `https`) to capture traffic. It does not currently support Vercel Edge Runtime or Cloudflare Workers. Please ensure your API routes use the Node.js runtime.
+
+**Q: Will this crash my app if the API is down?**
+No. The SDK is built with a "Safety Fuse." If it cannot connect or encounters an error, it fails silently and your application continues running without interruption.
+
+---
 
-## Features
-- **Zero Configuration**: Just import and it works.
-- **Invisible capture**: No code changes to your AI logic.
-- **Non-blocking**: Uses fire-and-forget network calls.
-- **Remote Config**: Supports dynamic output capping and provider filtering.
+### License
 
-## License
-MIT
+MIT

package/bin/init.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const colors = {
+    reset: "\x1b[0m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m"
+};
+
+const log = (color, msg) => console.log(`${color}${msg}${colors.reset}`);
+
+function detectFramework() {
+    const cwd = process.cwd();
+    if (fs.existsSync(path.resolve(cwd, 'package.json'))) {
+        const pkg = JSON.parse(fs.readFileSync(path.resolve(cwd, 'package.json'), 'utf-8'));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (deps.next) return 'nextjs';
+        if (deps['@nestjs/core']) return 'nestjs';
+        return 'node';
+    }
+    return 'unknown';
+}
+
+function setupNextJs() {
+    log(colors.cyan, '🔍 Next.js project detected.');
+    const hasSrc = fs.existsSync(path.resolve(process.cwd(), 'src'));
+    const targetDir = hasSrc ? 'src' : '.';
+    const isTs = fs.existsSync(path.resolve(process.cwd(), 'tsconfig.json'));
+    const ext = isTs ? 'ts' : 'js';
+    const filePath = path.resolve(process.cwd(), targetDir, `instrumentation.${ext}`);
+
+    const content = `export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('@dropout-ai/runtime');
+    console.log('[Dropout] 🟢 Initialized via instrumentation hook');
+  }
+}`;
+
+    if (fs.existsSync(filePath)) {
+        log(colors.yellow, `⚠️  File exists: ${filePath}`);
+        log(colors.yellow, `👉 Please add the register() hook manually.`);
+    } else {
+        fs.writeFileSync(filePath, content);
+        log(colors.green, `✅ Created: ${targetDir}/instrumentation.${ext}`);
+    }
+
+    log(colors.cyan, '\nNEXT STEP: Add .env keys (DROPOUT_PROJECT_ID, DROPOUT_API_KEY).');
+}
+
+function run() {
+    console.log(colors.cyan + "\nDropout AI - Init Wizard 🧙‍♂️" + colors.reset);
+    const framework = detectFramework();
+
+    switch (framework) {
+        case 'nextjs': setupNextJs(); break;
+        case 'nestjs':
+            log(colors.cyan, '🔍 NestJS detected.');
+            log(colors.green, '👉 Initialize in src/main.ts before bootstrap().');
+            break;
+        case 'node':
+            log(colors.cyan, '🔍 Node/Express detected.');
+            log(colors.green, '👉 Add require("@dropout-ai/runtime") at the top of index.js.');
+            break;
+        default:
+            log(colors.yellow, '⚠️  Unknown framework. Check docs for manual setup.');
+    }
+}
+
+run();

package/package.json

@@ -1,16 +1,29 @@
 {
   "name": "@dropout-ai/runtime",
-  "version": "0.3.8",
-  "description": "Invisible Node.js runtime for capturing AI interactions.",
+  "version": "0.3.10",
+  "description": "Invisible Node.js runtime for understanding behavoiral impact of AI interactions.",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "bin": {
+    "init": "./bin/init.js"
+  },
   "scripts": {
-    "test": "node test.js"
+    "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [
     "openai",
     "telemetry",
     "runtime",
-    "invisible"
+    "invisible",
+    "observability",
+    "ai",
+    "behavoiral analysis",
+    "ai forensic",
+    "llm",
+    "monitoring",
+    "genkit",
+    "nestjs",
+    "nextjs"
   ],
   "repository": {
     "type": "git",
@@ -18,7 +31,8 @@
     "directory": "packages/runtime"
   },
   "files": [
-    "src"
+    "src",
+    "bin"
   ],
   "publishConfig": {
     "access": "public"

package/src/index.d.ts

@@ -0,0 +1,33 @@
+export interface DropoutConfig {
+    /**
+     * Your project ID from the Dropout Dashboard.
+     */
+    projectId: string;
+
+    /**
+     * Your secret API Key (starts with dp_live_...).
+     */
+    apiKey: string;
+
+    /**
+     * Data Privacy Level.
+     * 'full' - Captures prompts and responses (Default).
+     * 'mask' - Captures metadata only, redacts text.
+     */
+    privacy?: 'full' | 'mask';
+
+    /**
+     * Enable verbose logging for connection debugging.
+     * Default: false
+     */
+    debug?: boolean;
+}
+
+export default class Dropout {
+    constructor(config: DropoutConfig);
+
+    /**
+     * Manually log a message to the debug stream.
+     */
+    log(msg: string, ...args: any[]): void;
+}

package/src/index.js

@@ -19,13 +19,12 @@ const KNOWN_AI_DOMAINS = [
 class Dropout {
   constructor(config = {}) {
     // 🛡️ 1. BROWSER GUARD (Client-Side Protection)
-    // If this accidentally runs in a browser/Client Component, we abort silently.
     if (typeof window !== 'undefined' && typeof window.document !== 'undefined') {
       if (config.debug) console.warn("[Dropout] ⚠️ Skipped: Browser detected. SDK is Server-Only.");
       return;
     }
 
-    // 🛡️ 2. CREDENTIAL CHECK
+    // 🛡️ 2. CREDENTIAL GUARD
     if (!config.apiKey || !config.projectId) {
       if (config.debug) console.warn("[Dropout] ⚠️ Skipped: Missing API Key or Project ID.");
       return;
@@ -69,18 +68,18 @@ class Dropout {
         global.__dropout_session_id__ = this.generateSessionId();
       }
 
+      if (this.debug) console.log(`[Dropout] 🟢 Online: ${this.projectId}`);
+
       // Bindings
       this.log = this.log.bind(this);
       this.emit = this.emit.bind(this);
 
-      // 🛡️ 4. SAFE STARTUP
+      // 4. Start Network Interceptor
       this.patchNetwork();
 
-      // 🔍 5. CONNECTION VERIFICATION (Async Ping)
-      // Only runs if debug is TRUE to confirm setup
-      if (this.debug) {
-        this.validateConnection();
-      }
+      // 5. SEND STARTUP PING (Always run this, silent by default)
+      // This turns the dashboard status GREEN immediately on app boot.
+      this.sendStartupSignal();
 
     } catch (err) {
       // THE ULTIMATE CATCH-ALL: Ensure app NEVER crashes
@@ -101,9 +100,22 @@ class Dropout {
     }
   }
 
-  // --- HEALTH CHECK ---
-  validateConnection() {
-    this.log("🔄 Verifying connection to Dropout Cloud...");
+  // --- HEARTBEAT ---
+  sendStartupSignal() {
+    const payload = JSON.stringify({
+      project_id: this.projectId,
+      session_id: 'system_boot_' + Date.now(),
+      turn_role: 'system',
+      turn_index: 0,
+      content: 'Dropout SDK Initialized',
+      // content_blob: 'Dropout SDK Initialized',
+      metadata_flags: {
+        type: 'system_boot',
+        environment: process.env.NODE_ENV || 'development',
+        runtime: 'node'
+      },
+      received_at: new Date().toISOString()
+    });
 
     const req = https.request(this.captureEndpoint, {
       method: 'POST',
@@ -111,26 +123,10 @@ class Dropout {
         'Content-Type': 'application/json',
         'x-dropout-key': this.apiKey
       }
-    }, (res) => {
-      if (res.statusCode >= 200 && res.statusCode < 300) {
-        console.log(`[Dropout] ✅ Connected to Project: ${this.projectId}`);
-      } else {
-        console.warn(`[Dropout] ⚠️ Connection Failed (Status: ${res.statusCode}). Check your API Key.`);
-      }
     });
 
-    req.on('error', (e) => console.warn(`[Dropout] ❌ Connection Error: ${e.message}`));
-
-    // Send lightweight Ping payload
-    req.write(JSON.stringify({
-      project_id: this.projectId,
-      session_id: 'system_ping',
-      turn_role: 'system',
-      turn_index: 0,
-      content: 'ping',
-      //content_blob: 'ping',
-      metadata_flags: { type: 'connectivity_check' }
-    }));
+    req.on('error', (e) => this.log("❌ Startup Signal Failed", e.message));
+    req.write(payload);
     req.end();
   }
 
@@ -160,7 +156,7 @@ class Dropout {
         if (parsed.model) model = parsed.model;
         if (provider === 'custom' && (parsed.messages || parsed.prompt)) provider = 'heuristic';
       }
-    } catch (e) { /* Ignore parsing errors */ }
+    } catch (e) { }
     return { provider, model };
   }
 
@@ -189,7 +185,7 @@ class Dropout {
         model: payload.model,
         latency_ms: payload.latency_ms || null,
         content: payload.content,
-        //content_blob: payload.content,
+        // content_blob: payload.content,
         content_hash: payload.content_hash,
         metadata_flags: payload.metadata_flags,
         received_at: new Date().toISOString()