@dropout-ai/runtime 0.4.0 → 0.4.2

package/README.md

@@ -1,74 +1,87 @@
+
 # 🕵️ Dropout AI Runtime (`@dropout-ai/runtime`)
 
 **Universal AI Behavior Analysis & Capture for Node.js**
 
-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 is a lightweight, "install-and-forget" runtime that automatically captures AI interactions (prompts & responses) from your application without requiring code changes to your API calls. It acts as a passive observer, patching the network layer to ensure you never miss a conversation.
 
 * **🔌 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.
+* **🔋 Robust:** Explicit initialization ensures you always know when it's running.
 
 ---
 
-## 🚀 Quick Start (Recommended)
+## 🚀 Quick Start (Wizard)
 
-Run our initialization wizard in your project root. It will detect your framework and automatically create the necessary configuration files.
+The easiest way to get started is to run our installer. It will install the package and give you the exact code snippet to copy.
 
 ```bash
-npx @dropout-ai/runtime init
+npx @dropout-ai/wizard@latest
 
 ```
 
-*Supports: **Next.js** (App Router), **NestJS**, **Express**, and standard **Node.js** apps.*
-
 ---
 
-## 🛠️ Manual Installation
+## 🛠️ Manual Installation & Usage
+
+If you prefer to install manually, follow these two steps.
 
-If you prefer to configure it yourself, install the package and follow the guide for your specific framework.
+### 1. Install the Package
 
 ```bash
 npm install @dropout-ai/runtime
 # or
-yarn add @dropout-ai/runtime
+pnpm add @dropout-ai/runtime
 
 ```
 
-### 1. Next.js (App Router)
+### 2. Initialize (The "Universal" Method)
+
+To start capturing, you must explicitly initialize Dropout. Place this code snippet **as early as possible** in your application lifecycle (before you make any AI calls).
+
+It is safe to call `init()` multiple times; it will only run once.
 
-Next.js uses lazy-loading, so we use `instrumentation.ts` to ensure Dropout loads immediately on server boot.
+#### ➤ For Next.js (App Router)
 
-**Create/Edit:** `src/instrumentation.ts` (or `instrumentation.ts` in root)
+**File:** `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');
+    const { default: Dropout } = await import('@dropout-ai/runtime');
+
+    Dropout.init({
+      apiKey: process.env.DROPOUT_API_KEY,
+      projectId: process.env.DROPOUT_PROJECT_ID,
+      debug: true // Set to false in production
+    });
   }
 }
 
 ```
 
-### 2. Node.js / Express / Fastify
+#### ➤ For Node.js / Express / Fastify
 
-Initialize Dropout at the **very top** of your entry file (`index.js` or `server.js`), before importing other libraries.
+**File:** `index.js` or `server.js` (Top of file)
 
 ```javascript
-// MUST be the first line
-require('@dropout-ai/runtime'); 
+require('dotenv').config(); // Ensure env vars are loaded first
+const Dropout = require('@dropout-ai/runtime');
+
+Dropout.init({
+  apiKey: process.env.DROPOUT_API_KEY,
+  projectId: process.env.DROPOUT_PROJECT_ID,
+  debug: process.env.NODE_ENV !== 'production'
+});
 
 const express = require('express');
 const app = express();
-// ... rest of your code
+// ...
 
 ```
 
-### 3. NestJS
-
-Initialize Dropout inside your `bootstrap()` function before creating the Nest app.
+#### ➤ For NestJS
 
 **File:** `src/main.ts`
 
@@ -78,10 +91,11 @@ 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 
+  // ✅ Initialize before the app starts
+  Dropout.init({
+    apiKey: process.env.DROPOUT_API_KEY,
+    projectId: process.env.DROPOUT_PROJECT_ID,
+    debug: true
   });
 
   const app = await NestFactory.create(AppModule);
@@ -91,96 +105,54 @@ 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
 
-```
+| Option | Type | Description | Required |
+| --- | --- | --- | --- |
+| `projectId` | `string` | Your Project ID from the dashboard. | ✅ |
+| `apiKey` | `string` | Your Secret Key (`dp_live_...`). | ✅ |
+| `debug` | `boolean` | Set `true` to see "🟢 Online" logs and errors in console. | No |
+| `privacy` | `string` | `full` (capture text) or `mask` (metadata only). Default: `full`. | No |
 
 ---
 
-## ⚙️ Configuration
+## ❓ Troubleshooting
 
-You can configure Dropout via **Environment Variables** (Recommended) or by passing options to the constructor.
+**Q: How do I know if it's working?**
+Set `debug: true` in your config. When your app starts, you should see this message immediately:
 
-| 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 |
+> `[Dropout] 🟢 Online | Project: <Your-Project-ID>`
 
-**Example `.env` file:**
+**Q: I don't see any logs.**
 
-```bash
-DROPOUT_PROJECT_ID="HomeOS"
-DROPOUT_API_KEY="dp_live_xyz123..."
-DROPOUT_DEBUG="true"
+1. Check that you called `Dropout.init()`.
+2. Ensure your `apiKey` and `projectId` are not undefined (log them to check).
+3. If using Next.js, ensure `instrumentation.ts` is in the correct folder (`src/` if you use it).
 
-```
+**Q: Does this work with Edge Functions?**
+No. This runtime relies on Node.js core modules (`http`, `https`). It does not support Vercel Edge Runtime or Cloudflare Workers.
 
 ---
 
-## 🌐 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.
+If you are using Python, Go, or other languages, you can manually send interaction logs to our ingestion endpoint.
 
 **Endpoint:** `POST https://hipughmjlwmwjxzyxfzs.supabase.co/functions/v1/capture-sealed`
+**Headers:** `x-dropout-key: <YOUR_API_KEY>`
 
-**Headers:**
-
-* `Content-Type: application/json`
-* `x-dropout-key: YOUR_API_KEY`
-
-**Payload:**
-
-```json
+json
 {
   "project_id": "your_project_id",
-  "turn_role": "assistant",       // or "user"
+  "turn_role": "assistant",
   "content": "AI response text...",
-  "model": "gpt-4",               // optional
-  "provider": "openai",           // optional
-  "latency_ms": 1250              // optional
+  "model": "gpt-4",
+  "provider": "openai"
 }
 
-```
-
----
-
-## ❓ 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.
-
----
-
 ### License
 
-MIT
+MIT
+

package/package.json

@@ -1,12 +1,9 @@
 {
   "name": "@dropout-ai/runtime",
-  "version": "0.4.0",
-  "description": "Invisible Node.js runtime for understanding behavoiral impact of AI interactions.",
+  "version": "0.4.2",
+  "description": "Invisible Node.js runtime for understanding behavioral impact of AI interactions.",
   "main": "src/index.js",
   "types": "src/index.d.ts",
-  "bin": {
-    "init": "./bin/init.js"
-  },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
@@ -17,7 +14,7 @@
     "invisible",
     "observability",
     "ai",
-    "behavoiral analysis",
+    "behavioral analysis",
     "ai forensic",
     "llm",
     "monitoring",
@@ -30,16 +27,12 @@
     "url": "git+https://github.com/vaibhavv4re/dropout.git",
     "directory": "packages/runtime"
   },
-  "dependencies": {
-    "dotenv": "^16.4.5"
-  },
+  "dependencies": {},
   "exports": {
-    ".": "./src/index.js",
-    "./register": "./src/autoload.js"
+    ".": "./src/index.js"
   },
   "files": [
-    "src",
-    "bin"
+    "src"
   ],
   "publishConfig": {
     "access": "public"

package/src/index.d.ts

@@ -1,33 +1,38 @@
+// packages/runtime/src/index.d.ts
+
 export interface DropoutConfig {
+    projectId: string;
+    apiKey: string;
+    debug?: boolean;
+    privacy?: 'full' | 'mask';
+}
+
+export default class Dropout {
     /**
-     * Your project ID from the Dropout Dashboard.
+     * The project ID associated with this instance.
      */
     projectId: string;
 
     /**
-     * Your secret API Key (starts with dp_live_...).
+     * The API Key used for authentication.
      */
     apiKey: string;
 
     /**
-     * Data Privacy Level.
-     * 'full' - Captures prompts and responses (Default).
-     * 'mask' - Captures metadata only, redacts text.
+     * Enable debug mode for verbose logging.
      */
-    privacy?: 'full' | 'mask';
+    debug: boolean;
 
     /**
-     * Enable verbose logging for connection debugging.
-     * Default: false
+     * Privacy setting ('full' captures text, 'mask' captures metadata only).
      */
-    debug?: boolean;
-}
-
-export default class Dropout {
-    constructor(config: DropoutConfig);
+    privacy: 'full' | 'mask';
 
     /**
-     * Manually log a message to the debug stream.
+     * Universal Initialization Method (Idempotent).
+     * Safe to call multiple times; will only initialize once.
      */
-    log(msg: string, ...args: any[]): void;
+    static init(config: DropoutConfig): Dropout;
+
+    constructor(config: DropoutConfig);
 }

package/bin/init.js

@@ -1,71 +0,0 @@
-#!/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/src/autoload.js

@@ -1,35 +0,0 @@
-// packages/runtime/src/autoload.js
-const fs = require('fs');
-const path = require('path');
-const Dropout = require('./index');
-
-// 1. Force Load Environment Variables (Fixes the "undefined" error)
-try {
-    const dotenv = require('dotenv');
-    const cwd = process.cwd();
-
-    // We explicitly look for .env.local first (Next.js standard), then .env
-    const envFiles = ['.env.local', '.env'];
-
-    envFiles.forEach(file => {
-        const envPath = path.resolve(cwd, file);
-        if (fs.existsSync(envPath)) {
-            dotenv.config({ path: envPath, override: true });
-        }
-    });
-} catch (e) {
-    // dotenv might not be installed, ignore if using system env vars
-}
-
-// 2. Initialize Immediately
-if (process.env.DROPOUT_PROJECT_ID && process.env.DROPOUT_API_KEY) {
-    new Dropout({
-        projectId: process.env.DROPOUT_PROJECT_ID,
-        apiKey: process.env.DROPOUT_API_KEY,
-        debug: process.env.DROPOUT_DEBUG === 'true'
-    });
-    // Log strictly for debug verification
-    if (process.env.DROPOUT_DEBUG === 'true') {
-        console.log(`[Dropout] 🚀 Global Autoload Active: ${process.env.DROPOUT_PROJECT_ID}`);
-    }
-}