oblien 1.1.1 → 1.1.3

package/README.md

@@ -25,9 +25,8 @@ import { OblienCredits } from 'oblien/credits';
 
 // Initialize client
 const client = new OblienClient({
-    apiKey: 'your-client-id',
-    apiSecret: 'your-client-secret',
-    baseURL: 'https://api.oblien.com'  // Optional
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret'
 });
 
 // Use modules
@@ -88,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';
@@ -101,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',
@@ -108,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)
 
 ---
 
@@ -284,8 +307,8 @@ import { OblienSandboxes } from 'oblien/sandbox';
 
 // Initialize
 const client = new OblienClient({
-    apiKey: 'your-client-id',
-    apiSecret: 'your-client-secret'
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret'
 });
 
 const agents = new OblienAgents(client);
@@ -384,8 +407,8 @@ All modules use client credentials authentication:
 
 ```javascript
 const client = new OblienClient({
-    apiKey: 'your-client-id',        // X-Client-ID header
-    apiSecret: 'your-client-secret'  // X-Client-Secret header
+    clientId: 'your-client-id',        // X-Client-ID header
+    clientSecret: 'your-client-secret'  // X-Client-Secret header
 });
 ```
 
@@ -409,8 +432,8 @@ import {
 } from 'oblien';
 
 const client: OblienClient = new OblienClient({
-    apiKey: string,
-    apiSecret: string
+    clientId: string,
+    clientSecret: string
 });
 ```
 
@@ -518,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

@@ -5,10 +5,9 @@
 // ============ Client Types ============
 
 export interface OblienConfig {
-    apiKey: string;
-    apiSecret?: string;
+    clientId: string;
+    clientSecret: string;
     baseURL?: string;
-    version?: string;
 }
 
 export class OblienClient {
@@ -101,6 +100,10 @@ export interface SessionOptions {
     isGuest?: boolean;
     namespace?: string;
     workspace?: Record<string, any>;
+    ipAddress?: string;
+    userAgent?: string;
+    fingerprint?: string;
+    endUserId?: string;
 }
 
 export interface SessionData {
@@ -136,6 +139,11 @@ export interface CreateSessionOptions {
     workflowId?: string;
     namespace?: string; // For authenticated users, typically user_id
     workspace?: Record<string, any>;
+    endUserId?: string;
+    isGuest?: boolean;
+    ipAddress?: string;
+    userAgent?: string;
+    fingerprint?: string;
 }
 
 export interface CreateGuestSessionOptions {
@@ -145,6 +153,7 @@ export interface CreateGuestSessionOptions {
     workflowId?: string;
     metadata?: Record<string, any>;
     workspace?: Record<string, any>;
+    endUserId?: string;
 }
 
 export interface GuestSessionData extends SessionData {
@@ -155,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.1",
+  "version": "1.1.3",
   "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

@@ -34,6 +34,12 @@ export class OblienChat {
      * @param {string} options.agentId - Agent ID to chat with
      * @param {string} [options.workflowId] - Workflow ID (if using workflow)
      * @param {Object} [options.workspace] - Workspace configuration
+     * @param {string} [options.endUserId] - End user ID (for client's end users)
+     * @param {string} [options.namespace] - Guest namespace for rate limiting
+     * @param {boolean} [options.isGuest] - Is this a guest session
+     * @param {string} [options.ipAddress] - IP address of the user
+     * @param {string} [options.userAgent] - User agent of the user
+     * @param {string} [options.fingerprint] - Fingerprint of the user
      * @returns {Promise<Object>} Session data with token
      */
     async createSession(options) {
@@ -54,10 +60,11 @@ export class OblienChat {
      * @param {string} [options.workflowId] - Workflow ID
      * @param {Object} [options.metadata] - Additional guest metadata
      * @param {Object} [options.workspace] - Workspace configuration
+     * @param {string} [options.endUserId] - End user ID (for client's end users)
      * @returns {Promise<Object>} Session data with token and guest info
      */
     async createGuestSession(options) {
-        const { ip, fingerprint, agentId, workflowId, metadata = {}, workspace } = options;
+        const { ip, fingerprint, agentId, workflowId, metadata = {}, workspace, endUserId } = options;
 
         if (!ip) {
             throw new Error('IP address is required for guest sessions');
@@ -81,6 +88,7 @@ export class OblienChat {
             ipAddress: ip,
             userAgent: metadata.userAgent,
             fingerprint: fingerprint,
+            endUserId: endUserId,
         });
 
         const sessionData = await session.create();
@@ -130,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
@@ -173,6 +380,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

@@ -16,6 +16,7 @@ export class ChatSession {
      * @param {string} [options.ipAddress] - IP address of the user
      * @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)
      */
     constructor(options) {
         if (!options.client) {
@@ -38,6 +39,7 @@ export class ChatSession {
         this.ipAddress = options.ipAddress || null;
         this.userAgent = options.userAgent || null;
         this.fingerprint = options.fingerprint || null;
+        this.endUserId = options.endUserId || null;
     }
 
     /**
@@ -54,6 +56,7 @@ export class ChatSession {
             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);

package/src/client.js

@@ -6,21 +6,19 @@
 export class OblienClient {
     /**
      * @param {Object} config - Configuration options
-     * @param {string} config.apiKey - Your Oblien Client ID (x-client-id)
-     * @param {string} config.apiSecret - Your Oblien Client Secret (x-client-secret)
-     * @param {string} [config.baseURL] - Base URL for API (default: https://api.oblien.com)
-     * @param {string} [config.version] - API version (default: v1)
+     * @param {string} config.clientId - Your Oblien Client ID (x-client-id)
+     * @param {string} config.clientSecret - Your Oblien Client Secret (x-client-secret)
      */
     constructor(config) {
-        if (!config || !config.apiKey) {
-            throw new Error('Oblien API key (client ID) is required');
+        if (!config || !config.clientId) {
+            throw new Error('Oblien client ID is required');
         }
-        if (!config.apiSecret) {
-            throw new Error('Oblien API secret (client secret) is required');
+        if (!config.clientSecret) {
+            throw new Error('Oblien client secret is required');
         }
 
-        this.clientId = config.apiKey;
-        this.clientSecret = config.apiSecret;
+        this.clientId = config.clientId;
+        this.clientSecret = config.clientSecret;
         this.baseURL = config.baseURL || 'https://api.oblien.com';
     }