@dropout-ai/runtime 0.4.4 → 0.5.0

package/README.md

@@ -115,6 +115,61 @@ bootstrap();
 | `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 |
+| `sessionId` | `string` | Optional initial session ID. If not provided, one is generated. | No |
+| `captureEndpoint` | `string` | Custom capture endpoint (for testing). Default: production URL. | No |
+
+---
+
+## 🔑 Session Management
+
+**Important:** A **session** represents a single conversation thread. By default, Dropout generates one session ID when initialized and uses it for all interactions. For proper analytics, you should call `startNewSession()` whenever the user starts a new conversation.
+
+### When to Call `startNewSession()`
+
+Call this method when:
+- User clicks "New Chat" button
+- User switches to a different conversation thread
+- User switches AI models (if you want to treat that as a new conversation)
+- Page refreshes and you want to start a fresh session
+
+### Example Usage
+
+```javascript
+const Dropout = require('@dropout-ai/runtime');
+
+// Initialize once at app startup
+const dropout = Dropout.init({
+  apiKey: process.env.DROPOUT_API_KEY,
+  projectId: process.env.DROPOUT_PROJECT_ID
+});
+
+// Later, when user clicks "New Chat":
+app.post('/api/new-chat', (req, res) => {
+  const newSessionId = dropout.startNewSession();
+  console.log(`Started new session: ${newSessionId}`);
+  res.json({ sessionId: newSessionId });
+});
+
+// Or with a custom session ID:
+dropout.startNewSession('user_123_chat_456');
+```
+
+### TypeScript Example
+
+```typescript
+import Dropout from '@dropout-ai/runtime';
+
+const dropout = Dropout.init({
+  apiKey: process.env.DROPOUT_API_KEY!,
+  projectId: process.env.DROPOUT_PROJECT_ID!
+});
+
+// Access current session
+console.log(dropout.currentSessionId);
+
+// Start new session
+const newSessionId = dropout.startNewSession();
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dropout-ai/runtime",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Invisible Node.js runtime for understanding behavioral impact of AI interactions.",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/index.d.ts

@@ -5,6 +5,8 @@ export interface DropoutConfig {
     apiKey: string;
     debug?: boolean;
     privacy?: 'full' | 'mask';
+    sessionId?: string;
+    captureEndpoint?: string;
 }
 
 export default class Dropout {
@@ -28,11 +30,24 @@ export default class Dropout {
      */
     privacy: 'full' | 'mask';
 
+    /**
+     * Current session ID for tracking conversation threads.
+     */
+    currentSessionId: string;
+
     /**
      * Universal Initialization Method (Idempotent).
      * Safe to call multiple times; will only initialize once.
      */
     static init(config: DropoutConfig): Dropout;
 
+    /**
+     * Start a new session (e.g., when user clicks "New Chat").
+     * Resets turn counter and generates a fresh session ID.
+     * @param customSessionId - Optional custom session ID, otherwise auto-generates
+     * @returns The new session ID
+     */
+    startNewSession(customSessionId?: string): string;
+
     constructor(config: DropoutConfig);
 }

package/src/index.js

@@ -86,10 +86,10 @@ class Dropout {
       }
       global.__dropout_initialized__ = true;
 
-      // Identity
-      if (!global.__dropout_session_id__) {
-        global.__dropout_session_id__ = this.generateSessionId();
-      }
+      // ✅ Session Identity (Instance-Level, Not Global)
+      // Accept session_id from config OR generate a default
+      // Host app controls session lifecycle via startNewSession()
+      this.currentSessionId = config.sessionId || this.generateSessionId();
 
       // ✅ VISUAL SUCCESS INDICATOR
       if (this.debug) {
@@ -125,6 +125,25 @@ class Dropout {
     }
   }
 
+  /**
+   * 🔑 START NEW SESSION
+   * Call this when user clicks "New Chat" or starts a new conversation thread.
+   * Resets turn counter and generates a fresh session_id.
+   * @param {string} [customSessionId] - Optional custom session ID, otherwise auto-generates
+   * @returns {string} The new session ID
+   */
+  startNewSession(customSessionId) {
+    this.currentSessionId = customSessionId || this.generateSessionId();
+    this.turnIndex = 0; // Reset turn counter for new session
+    this.lastTurnConfirmed = true;
+    this.lastPromptHash = null;
+    this.lastResponseHash = null;
+    if (this.debug) {
+      console.log(`[Dropout] 🔄 New Session Started: ${this.currentSessionId}`);
+    }
+    return this.currentSessionId;
+  }
+
   hash(text) {
     if (!text) return null;
     try {
@@ -243,7 +262,7 @@ class Dropout {
         const pHash = _this.hash(bodyStr);
 
         _this.emit({
-          session_id: global.__dropout_session_id__,
+          session_id: _this.currentSessionId,
           turn_index: activeTurn,
           turn_role: 'user',
           provider,
@@ -268,7 +287,7 @@ class Dropout {
           const oHash = _this.hash(oText);
 
           _this.emit({
-            session_id: global.__dropout_session_id__,
+            session_id: _this.currentSessionId,
             turn_index: activeTurn,
             turn_role: 'assistant',
             latency_ms: latency,
@@ -354,7 +373,7 @@ class Dropout {
             clientRequest._dropout_model = model;
 
             _this.emit({
-              session_id: global.__dropout_session_id__,
+              session_id: _this.currentSessionId,
               turn_index: activeTurn,
               turn_role: 'user',
               provider,
@@ -381,7 +400,7 @@ class Dropout {
               const oHash = _this.hash(resBody);
 
               _this.emit({
-                session_id: global.__dropout_session_id__,
+                session_id: _this.currentSessionId,
                 turn_index: clientRequest._dropout_turn || 0,
                 turn_role: 'assistant',
                 latency_ms: latency,