@dropout-ai/runtime 0.3.9 → 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.9",
-  "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

@@ -1,14 +1,13 @@
 /**
  * @dropout-ai/runtime
  * Universal AI Interaction Capture for Node.js
- * Feature: Always-On Heartbeat & Auto-Discovery
+ * Stability: High (Browser-Safe, Silent Failures)
+ * Features: Auto-Discovery, Connectivity Check, Dual-Schema Support
  */
 
-const https = require('https');
-const http = require('http');
-const crypto = require('crypto');
+let https, http, crypto;
 
-// --- CONFIGURATION ---
+// --- DEFAULT CONFIGURATION ---
 const SUPABASE_FUNCTION_URL = "https://hipughmjlwmwjxzyxfzs.supabase.co/functions/v1/capture-sealed";
 
 // Known AI Domains
@@ -19,53 +18,73 @@ const KNOWN_AI_DOMAINS = [
 
 class Dropout {
   constructor(config = {}) {
-    // 🛡️ BROWSER GUARD
+    // 🛡️ 1. BROWSER GUARD (Client-Side Protection)
     if (typeof window !== 'undefined' && typeof window.document !== 'undefined') {
-      if (config.debug) console.warn("[Dropout] ⚠️ Skipped: Browser detected.");
+      if (config.debug) console.warn("[Dropout] ⚠️ Skipped: Browser detected. SDK is Server-Only.");
       return;
     }
 
-    // 🛡️ CREDENTIAL GUARD
+    // 🛡️ 2. CREDENTIAL GUARD
     if (!config.apiKey || !config.projectId) {
-      if (config.debug) console.warn("[Dropout] ⚠️ Skipped: Missing Credentials.");
+      if (config.debug) console.warn("[Dropout] ⚠️ Skipped: Missing API Key or Project ID.");
       return;
     }
 
-    // Initialize
-    this.config = config;
-    this.projectId = config.projectId;
-    this.apiKey = config.apiKey;
-    this.debug = config.debug || false;
-    this.privacy = config.privacy || 'full';
-    this.captureEndpoint = SUPABASE_FUNCTION_URL;
-    this.maxOutputBytes = 32768;
-
-    // State
-    this.turnIndex = 0;
-    this.lastTurnConfirmed = true;
-    this.lastPromptHash = null;
-    this.lastResponseHash = null;
-
-    // Singleton Guard
-    if (global.__dropout_initialized__) return;
-    global.__dropout_initialized__ = true;
-
-    if (!global.__dropout_session_id__) {
-      global.__dropout_session_id__ = this.generateSessionId();
+    // 🛡️ 3. DEPENDENCY CHECK
+    try {
+      https = require('https');
+      http = require('http');
+      crypto = require('crypto');
+    } catch (e) {
+      if (config.debug) console.warn("[Dropout] ⚠️ Skipped: Node core modules missing.");
+      return;
     }
 
-    if (this.debug) console.log(`[Dropout] 🟢 Online: ${this.projectId}`);
+    // --- INITIALIZATION ---
+    try {
+      this.config = config;
+      this.projectId = config.projectId;
+      this.apiKey = config.apiKey;
+      this.debug = config.debug || false;
+      this.privacy = config.privacy || 'full';
+      this.captureEndpoint = SUPABASE_FUNCTION_URL;
+      this.maxOutputBytes = 32768;
+
+      // State
+      this.turnIndex = 0;
+      this.lastTurnConfirmed = true;
+      this.lastPromptHash = null;
+      this.lastResponseHash = null;
+
+      // Singleton Guard
+      if (global.__dropout_initialized__) {
+        if (this.debug) console.log("[Dropout] ℹ️ Already initialized.");
+        return;
+      }
+      global.__dropout_initialized__ = true;
+
+      // Identity
+      if (!global.__dropout_session_id__) {
+        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);
+      // Bindings
+      this.log = this.log.bind(this);
+      this.emit = this.emit.bind(this);
 
-    // 1. Start Network Interceptor
-    this.patchNetwork();
+      // 4. Start Network Interceptor
+      this.patchNetwork();
 
-    // 2. SEND STARTUP PING (Always run this, silent by default)
-    // This turns the dashboard status GREEN immediately on app boot.
-    this.sendStartupSignal();
+      // 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
+      if (config.debug) console.error("[Dropout] ❌ Initialization Error:", err);
+    }
   }
 
   // --- UTILS ---
@@ -83,15 +102,13 @@ class Dropout {
 
   // --- HEARTBEAT ---
   sendStartupSignal() {
-    // We send a discrete 'system_boot' event.
-    // The Database Trigger will see this and update projects.last_active_at
     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',
+      // content_blob: 'Dropout SDK Initialized',
       metadata_flags: {
         type: 'system_boot',
         environment: process.env.NODE_ENV || 'development',
@@ -108,7 +125,6 @@ class Dropout {
       }
     });
 
-    // Silent error handling (unless debug is on)
     req.on('error', (e) => this.log("❌ Startup Signal Failed", e.message));
     req.write(payload);
     req.end();
@@ -169,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()
@@ -393,6 +409,7 @@ class Dropout {
   }
 }
 
+// Auto-Start (Server-Side Only)
 if (typeof process !== 'undefined' && process.env.DROPOUT_PROJECT_ID && process.env.DROPOUT_API_KEY) {
   new Dropout({
     projectId: process.env.DROPOUT_PROJECT_ID,