oblien 1.1.2 → 1.1.4

package/README.md

@@ -87,7 +87,7 @@ const overview = await agentInstance.getOverview({ days: 7 });
 
 ### 💬 Chat Module
 
-Create and manage chat sessions with guest support.
+Create sessions, send messages, and manage guests with streaming support.
 
 ```javascript
 import { OblienChat } from 'oblien/chat';
@@ -100,6 +100,27 @@ const session = await chat.createSession({
     namespace: 'production'
 });
 
+// Send message with streaming
+await chat.send({
+    token: session.token,
+    message: 'Tell me about AI',
+    stream: true,
+    onChunk: (data) => console.log(data)
+});
+
+// Upload files
+const uploadResult = await chat.upload({
+    token: session.token,
+    files: fileArray
+});
+
+// Send message with uploaded files
+await chat.send({
+    token: session.token,
+    message: 'Analyze these files',
+    uploadId: uploadResult.uploadId
+});
+
 // Create guest session
 const guestSession = await chat.createGuestSession({
     ip: '192.168.1.1',
@@ -107,17 +128,20 @@ const guestSession = await chat.createGuestSession({
     agentId: 'agent-id'
 });
 
-// List sessions
-const sessions = await chat.listSessions({ limit: 20 });
+// Get guest usage
+const usage = await chat.getGuestUsage(guestSession.token);
 ```
 
 **Features:**
-- ✅ Session management
-- ✅ Guest sessions with fingerprint tracking
-- ✅ Token generation
-- ✅ Automatic guest ID generation
+- ✅ Session management (create, list, delete)
+- ✅ Message sending with streaming support
+- ✅ File uploads for agent analysis
+- ✅ Guest sessions with IP + fingerprint tracking
+- ✅ Guest usage monitoring and rate limiting
+- ✅ Hybrid mode (works with token or client credentials)
+- ✅ Cache statistics for monitoring
 
-📖 [Documentation](./docs/CHAT.md) | 💡 [Examples](./examples/chat-example.js)
+📖 [Full Documentation](./docs/CHAT.md) | 💡 [Examples](./examples/chat-example.js)
 
 ---
 
@@ -517,6 +541,14 @@ MIT License - see LICENSE file for details
 
 ## Changelog
 
+### v1.3.0 (Latest)
+- ✅ Added `send()` method to Chat module with streaming support
+- ✅ Added `upload()` method for file attachments
+- ✅ Added guest usage monitoring (`getGuestUsage()`)
+- ✅ Added cache statistics (`getCacheStatistics()`)
+- ✅ Hybrid mode support (token or client credentials)
+- ✅ Complete Chat documentation with examples
+
 ### v1.2.0
 - ✅ Added Sandboxes module
 - ✅ Enhanced Agents module with proper settings sections

package/index.d.ts

@@ -164,17 +164,60 @@ export interface GuestSessionData extends SessionData {
     };
 }
 
+export interface SendMessageOptions {
+    token?: string;
+    message: string;
+    uploadId?: string;
+    files?: any[];
+    stream?: boolean;
+    onChunk?: (data: any) => void;
+    onError?: (error: Error) => void;
+    onComplete?: () => void;
+    metadata?: Record<string, any>;
+}
+
+export interface UploadOptions {
+    token?: string;
+    files: any[] | any;
+    metadata?: Record<string, any>;
+}
+
+export interface GuestUsageInfo {
+    success: boolean;
+    namespace: string;
+    requestCount: number;
+    limit: number;
+    remaining: number;
+    resetAt?: Date;
+}
+
+export interface CacheStatistics {
+    success: boolean;
+    cache: {
+        keys: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+        keysSize: number;
+        valuesSize: number;
+    };
+}
+
 export class OblienChat {
     constructor(client: OblienClient, options?: ChatOptions);
     
     createSession(options: CreateSessionOptions): Promise<SessionData>;
     createGuestSession(options: CreateGuestSessionOptions): Promise<GuestSessionData>;
     getGuest(ip: string, fingerprint?: string): Promise<Guest | null>;
+    send(options: SendMessageOptions): Promise<any>;
+    upload(options: UploadOptions): Promise<any>;
     getSession(sessionId: string): Promise<any>;
     listSessions(options?: Record<string, any>): Promise<any[]>;
     deleteSession(sessionId: string): Promise<any>;
     getAllGuests(): Promise<Guest[]>;
     cleanupGuests(): Promise<number>;
+    getGuestUsage(token: string): Promise<GuestUsageInfo>;
+    getCacheStatistics(): Promise<CacheStatistics>;
 }
 
 // ============ Namespaces ============

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oblien",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Server-side SDK for Oblien AI Platform - Build AI-powered applications with chat, agents, and workflows",
   "main": "index.js",
   "type": "module",

package/src/chat/index.js

@@ -45,10 +45,9 @@ export class OblienChat {
     async createSession(options) {
         const session = new ChatSession({
             client: this.client,
-            ...options,
         });
 
-        return await session.create();
+        return await session.create(options);
     }
 
     /**
@@ -80,6 +79,9 @@ export class OblienChat {
         // Create session
         const session = new ChatSession({
             client: this.client,
+        });
+
+        const sessionData = await session.create({
             agentId,
             workflowId,
             workspace,
@@ -91,8 +93,6 @@ export class OblienChat {
             endUserId: endUserId,
         });
 
-        const sessionData = await session.create();
-
         // Link session to guest
         await this.guestManager.addSession(guest.id, sessionData.sessionId);
 
@@ -138,6 +138,205 @@ export class OblienChat {
         return null;
     }
 
+    /**
+     * Send a message in a chat session
+     * Hybrid mode: Works with session token OR client credentials
+     * 
+     * @param {Object} options - Send options
+     * @param {string} [options.token] - Session token (optional, uses client credentials if not provided)
+     * @param {string} options.message - Message to send
+     * @param {string} [options.uploadId] - Upload ID for attached files
+     * @param {Array} [options.files] - File attachments (alternative to uploadId)
+     * @param {boolean} [options.stream] - Enable streaming response
+     * @param {Function} [options.onChunk] - Callback for streaming chunks (data) => void
+     * @param {Function} [options.onError] - Callback for errors (error) => void
+     * @param {Function} [options.onComplete] - Callback when stream completes () => void
+     * @param {Object} [options.metadata] - Additional metadata
+     * @returns {Promise<Object>} Response data
+     */
+    async send(options = {}) {
+        const { 
+            token,
+            message,
+            uploadId, 
+            files, 
+            stream = false, 
+            onChunk,
+            onError,
+            onComplete,
+            metadata = {} 
+        } = options;
+
+        if (!message || !message.trim()) {
+            throw new Error('Message is required');
+        }
+
+        const payload = {
+            message,
+            stream,
+            ...metadata,
+        };
+
+        if (uploadId) {
+            payload.upload_id = uploadId;
+        }
+
+        if (files) {
+            payload.files = files;
+        }
+
+        // Build headers - use token if provided, otherwise use client credentials
+        const headers = {
+            ...this.client.getAuthHeaders(),
+            'Content-Type': 'application/json',
+        };
+
+        if (token) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
+
+        const url = this.client._buildURL('ai/chat/send');
+
+        if (stream) {
+            // Handle streaming response
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(payload),
+            });
+
+            if (!response.ok) {
+                const error = await response.text();
+                throw new Error(error || `API error: ${response.status}`);
+            }
+
+            // Process SSE stream
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    
+                    if (done) {
+                        if (onComplete) onComplete();
+                        break;
+                    }
+
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split('\n');
+                    buffer = lines.pop() || '';
+
+                    for (const line of lines) {
+                        if (line.trim() === '') continue;
+                        
+                        try {
+                            const data = JSON.parse(line);
+                            if (onChunk) onChunk(data);
+                        } catch (e) {
+                            // Skip non-JSON lines (SSE format)
+                            if (line.startsWith('data: ')) {
+                                try {
+                                    const jsonStr = line.substring(6);
+                                    const data = JSON.parse(jsonStr);
+                                    if (onChunk) onChunk(data);
+                                } catch (parseError) {
+                                    console.warn('Failed to parse chunk:', line);
+                                }
+                            }
+                        }
+                    }
+                }
+
+                return { success: true, stream: true };
+            } catch (error) {
+                if (onError) onError(error);
+                throw error;
+            }
+        } else {
+            // Regular non-streaming request
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(payload),
+            });
+
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ message: response.statusText }));
+                throw new Error(error.message || error.error || `API error: ${response.status}`);
+            }
+
+            return await response.json();
+        }
+    }
+
+    /**
+     * Upload files for a chat session
+     * Hybrid mode: Works with session token OR client credentials
+     * 
+     * @param {Object} options - Upload options
+     * @param {string} [options.token] - Session token (optional, uses client credentials if not provided)
+     * @param {Array|Object} options.files - Files to upload
+     * @param {Object} [options.metadata] - Additional metadata
+     * @returns {Promise<Object>} Upload result with uploadId
+     */
+    async upload(options = {}) {
+        const { token, files, metadata } = options;
+
+        if (!files || (Array.isArray(files) && files.length === 0)) {
+            throw new Error('Files are required');
+        }
+
+        const formData = new FormData();
+        
+        // Handle both single file and array of files
+        const fileArray = Array.isArray(files) ? files : [files];
+        
+        fileArray.forEach((file, index) => {
+            if (file instanceof File || file instanceof Blob) {
+                formData.append('files', file);
+            } else if (file.path && file.buffer) {
+                // Node.js file object
+                formData.append('files', file.buffer, file.originalname || file.path);
+            } else {
+                throw new Error(`Invalid file at index ${index}`);
+            }
+        });
+
+        // Add any additional options
+        if (metadata) {
+            formData.append('metadata', JSON.stringify(metadata));
+        }
+
+        // Build headers - use token if provided, otherwise use client credentials
+        const headers = {
+            ...this.client.getAuthHeaders(),
+        };
+
+        if (token) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
+
+        // Remove Content-Type for FormData (browser will set it with boundary)
+        delete headers['Content-Type'];
+
+        const url = this.client._buildURL('ai/chat/upload');
+
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: formData,
+        });
+
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ message: response.statusText }));
+            throw new Error(error.message || error.error || `API error: ${response.status}`);
+        }
+
+        return await response.json();
+    }
+
     /**
      * Get session info
      * @param {string} sessionId - Session ID
@@ -150,11 +349,23 @@ export class OblienChat {
     /**
      * List sessions
      * @param {Object} [options] - Query options
+     * @param {string} [options.namespace] - Filter by namespace
+     * @param {string} [options.agentId] - Filter by agent ID
+     * @param {string} [options.endUserId] - Filter by end user ID
+     * @param {number} [options.limit] - Number of results (max 100)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {string} [options.search] - Search in title and user ID
+     * @param {string} [options.sortBy] - Sort by 'time' or 'tokens'
+     * @param {string} [options.sortOrder] - 'asc' or 'desc'
+     * @param {boolean} [options.includeStats] - Include message count and tokens
      * @returns {Promise<Array>} Array of sessions
      */
     async listSessions(options = {}) {
-        const data = await this.client.get('ai/session', options);
-        return data.sessions || data;
+        const session = new ChatSession({
+            client: this.client,
+        });
+        
+        return await session.list(options);
     }
 
     /**
@@ -181,6 +392,43 @@ export class OblienChat {
     async cleanupGuests() {
         return await this.guestManager.cleanup();
     }
+
+    /**
+     * Get guest usage information (requires session token)
+     * @param {string} token - Session token from guest session
+     * @returns {Promise<Object>} Usage information for the guest
+     */
+    async getGuestUsage(token) {
+        if (!token) {
+            throw new Error('Session token is required');
+        }
+
+        const headers = {
+            ...this.client.getAuthHeaders(),
+            'Authorization': `Bearer ${token}`,
+        };
+
+        const response = await fetch(this.client._buildURL('ai/guest/usage'), {
+            method: 'GET',
+            headers,
+        });
+
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ message: response.statusText }));
+            throw new Error(error.message || error.error || `API error: ${response.status}`);
+        }
+
+        return await response.json();
+    }
+
+    /**
+     * Get cache statistics (admin/monitoring)
+     * @returns {Promise<Object>} Cache statistics
+     */
+    async getCacheStatistics() {
+        const data = await this.client.get('ai/guest/cache-stats');
+        return data;
+    }
 }
 
 export { ChatSession } from './session.js';

package/src/chat/session.js

@@ -8,6 +8,19 @@ export class ChatSession {
      * @param {Object} options - Session options
      * @param {import('../client.js').OblienClient} options.client - Oblien client instance
      * @param {string} [options.sessionId] - Existing session ID
+     */
+    constructor({ client, sessionId = null }) {
+        if (!client) {
+            throw new Error('Oblien client is required');
+        }
+
+        this.client = client;
+        this.sessionId = sessionId;
+    }
+
+    /**
+     * Create session and get token for client
+     * @param {Object} options - Session creation options
      * @param {string} options.agentId - Agent ID to chat with
      * @param {string} [options.workflowId] - Workflow ID (if using workflow)
      * @param {boolean} [options.isGuest] - Is this a guest session
@@ -17,71 +30,30 @@ export class ChatSession {
      * @param {string} [options.userAgent] - User agent of the user
      * @param {string} [options.fingerprint] - Fingerprint of the user
      * @param {string} [options.endUserId] - End user ID (for client's end users)
+     * @returns {Promise<Object>} Session data with token for browser
      */
-    constructor(options) {
-        if (!options.client) {
-            throw new Error('Oblien client is required');
-        }
-
+    async create(options) {
         if (!options.agentId && !options.workflowId) {
             throw new Error('Either agentId or workflowId is required');
         }
 
-        this.client = options.client;
-        this.sessionId = options.sessionId || null;
-        this.agentId = options.agentId;
-        this.workflowId = options.workflowId;
-        this.isGuest = options.isGuest || false;
-        this.namespace = options.namespace;
-        this.workspace = options.workspace;
-        this.token = null;
-        this.data = null;
-        this.ipAddress = options.ipAddress || null;
-        this.userAgent = options.userAgent || null;
-        this.fingerprint = options.fingerprint || null;
-        this.endUserId = options.endUserId || null;
-    }
-
-    /**
-     * Create session and get token for client
-     * @returns {Promise<Object>} Session data with token for browser
-     */
-    async create() {
-        const payload = {
-            agent_id: this.agentId,
-            app_id: this.workflowId, // Backend uses app_id for workflow_id
-            is_guest: this.isGuest,
-            namespace: this.namespace,
-            workspace: this.workspace,
-            ip_address: this.ipAddress,
-            user_agent: this.userAgent,
-            fingerprint: this.fingerprint,
-            end_user_id: this.endUserId,
-        };
-
-        this.data = await this.client.post('ai/session/create', payload);
-        this.sessionId = this.data.sessionId || this.data.session_id;
-        this.token = this.data.token || this.data.accessToken || this.data.tokens?.token;
-
-        return {
-            sessionId: this.sessionId,
-            token: this.token,
-            agentId: this.data.agentId || this.agentId,
-            workflowId: this.data.workflowId || this.data.appId || this.workflowId,
-            namespace: this.namespace,
-        };
+        const data = await this.client.post('ai/session/create', options);
+        return data
     }
 
     /**
      * Get existing session info
-     * @param {string} sessionId - Session ID
+     * @param {string} [sessionId] - Session ID (uses instance sessionId if not provided)
      * @returns {Promise<Object>} Session details
      */
     async get(sessionId) {
-        this.data = await this.client.get(`ai/session/${sessionId || this.sessionId}`);
-        return this.data;
-    }
+        const id = sessionId || this.sessionId;
+        if (!id) {
+            throw new Error('Session ID required');
+        }
 
+        return await this.client.get(`ai/session/${id}`);
+    }
 
     /**
      * Delete session
@@ -100,12 +72,21 @@ export class ChatSession {
     /**
      * List all sessions
      * @param {Object} [options] - Query options
+     * @param {string} [options.namespace] - Filter by namespace
+     * @param {string} [options.agentId] - Filter by agent ID
+     * @param {string} [options.endUserId] - Filter by end user ID
+     * @param {number} [options.limit] - Number of results (max 100)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {string} [options.search] - Search in title and user ID
+     * @param {string} [options.sortBy] - Sort by 'time' or 'tokens'
+     * @param {string} [options.sortOrder] - 'asc' or 'desc'
+     * @param {boolean} [options.includeStats] - Include message count and tokens
      * @returns {Promise<Array>} Array of sessions
      */
     async list(options = {}) {
-        const data = await this.client.get('ai/session', options);
-        return data.sessions || data;
+        const data = await this.client.get('ai/session/list', options);
+        return data;
     }
 }
 
-export default ChatSession;
+export default ChatSession;

package/src/chat/sessionQuota.js

@@ -0,0 +1,99 @@
+/**
+ * Session Quota Manager
+ * Manages per-session quota limits and tracking
+ */
+
+export class SessionQuota {
+    /**
+     * @param {Object} options
+     * @param {import('../client.js').OblienClient} options.client - Oblien client instance
+     * @param {string} options.sessionId - Session ID
+     */
+    constructor({ client, sessionId }) {
+        if (!client) {
+            throw new Error('Oblien client is required');
+        }
+        if (!sessionId) {
+            throw new Error('Session ID is required');
+        }
+
+        this.client = client;
+        this.sessionId = sessionId;
+    }
+
+    /**
+     * Get session quota status
+     * @returns {Promise<Object>} Quota status
+     */
+    async get() {
+        const data = await this.client.get(`ai/session/${this.sessionId}/quota`);
+        return data.quota || data;
+    }
+
+    /**
+     * Set session quota limit (manual override)
+     * @param {number} limit - Quota limit (null for unlimited)
+     * @param {string} [period] - Quota period: 'daily', 'monthly', 'unlimited'
+     * @returns {Promise<Object>} Updated quota status
+     */
+    async set(limit, period = 'unlimited') {
+        const data = await this.client.post(`ai/session/${this.sessionId}/quota`, {
+            limit,
+            period
+        });
+        return data.quota || data;
+    }
+
+    /**
+     * Reset session quota usage
+     * @returns {Promise<Object>} Reset result
+     */
+    async reset() {
+        return await this.client.post(`ai/session/${this.sessionId}/quota/reset`, {});
+    }
+
+    /**
+     * Check if session can use credits (validation before action)
+     * @param {number} amount - Amount of credits to check
+     * @returns {Promise<Object>} { canUse, quota, reason }
+     */
+    async canUse(amount) {
+        const data = await this.client.post(`ai/session/${this.sessionId}/quota/can-use`, {
+            amount
+        });
+        return {
+            canUse: data.canUse,
+            quota: data.quota,
+            reason: data.reason
+        };
+    }
+
+    /**
+     * Get quota transaction history
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Number of results (max 100)
+     * @param {number} [options.offset] - Offset for pagination
+     * @returns {Promise<Array>} Array of transactions
+     */
+    async getTransactions(options = {}) {
+        const data = await this.client.get(`ai/session/${this.sessionId}/quota/transactions`, options);
+        return data.transactions || data;
+    }
+
+    /**
+     * Get current usage
+     * @returns {Promise<Object>} { used, limit, available }
+     */
+    async getUsage() {
+        const quota = await this.get();
+        return {
+            used: quota.used || 0,
+            limit: quota.limit,
+            available: quota.available,
+            enabled: quota.enabled
+        };
+    }
+}
+
+export default SessionQuota;
+