oblien 1.0.5 → 1.0.6

package/README.md

@@ -2,6 +2,16 @@
 
 Server-side SDK for building AI-powered applications with Oblien platform.
 
+## Features
+
+- 🔐 **Direct header authentication** - Uses `x-client-id` and `x-client-secret` headers
+- 👤 **Dual-layer guest identification** - IP + fingerprint for better guest tracking
+- 🔄 **Smart guest matching** - Detects same guest even when IP or fingerprint changes
+- 📊 **Namespace support** - Pass user ID for authenticated session tracking
+- ⚡ **Automatic rate limiting** - Built-in limits for guest sessions
+- 💾 **Flexible storage** - NodeCache (default), Redis, or custom adapters
+- 🎯 **Single function for guest lookup** - `getGuest(ip, fingerprint)` handles both
+
 ## Installation
 
 ```bash
@@ -27,9 +37,9 @@ npm install oblien
 import { OblienClient } from 'oblien';
 
 const client = new OblienClient({
-    apiKey: 'your-api-key',
-    apiSecret: 'your-api-secret', // For server-side
-});
+    apiKey: 'your-client-id',      // Your Oblien Client ID
+    apiSecret: 'your-client-secret', // Your Oblien Client Secret (required)
+ });
 ```
 
 ### 2. Create Chat Session
@@ -39,9 +49,10 @@ import { OblienChat } from 'oblien/chat';
 
 const chat = new OblienChat(client);
 
-// Create session
+// Create session for authenticated user
 const session = await chat.createSession({
     agentId: 'your-agent-id',
+    namespace: 'user_123', // Optional: User ID for rate limiting/tracking
     // workflowId: 'workflow-id', // Optional
     // workspace: {}, // Optional
 });
@@ -51,7 +62,7 @@ console.log(session);
 //   sessionId: 'session-xxx',
 //   token: 'jwt-token-for-client',
 //   agentId: 'agent-id',
-//   namespace: null
+//   namespace: 'user_123'
 // }
 ```
 
@@ -102,7 +113,7 @@ function App() {
 
 ## Guest Sessions (Rate Limited)
 
-For anonymous users, create guest sessions based on IP address:
+For anonymous users, create guest sessions with **dual-layer identification** using IP + fingerprint:
 
 ```javascript
 import { OblienChat } from 'oblien/chat';
@@ -112,9 +123,11 @@ const chat = new OblienChat(client);
 // Express route
 app.post('/api/guest-session', async (req, res) => {
     const ip = req.ip || req.headers['x-forwarded-for'];
+    const fingerprint = req.body.fingerprint; // Browser fingerprint
 
     const session = await chat.createGuestSession({
-        ip: ip,
+        ip,
+        fingerprint, // NEW: Enables dual-layer identification
         agentId: 'your-agent-id',
         metadata: {
             userAgent: req.headers['user-agent'],
@@ -133,12 +146,24 @@ app.post('/api/guest-session', async (req, res) => {
 
 ### Guest Features:
 
+- ✅ **Dual-layer identification**: IP + fingerprint for better guest tracking
+- ✅ **Smart guest matching**: Same guest detected even if IP or fingerprint changes
 - ✅ Automatic rate limiting (100K tokens/day, 50 messages/day)
-- ✅ IP-based identification (privacy-friendly)
+- ✅ Privacy-friendly (IP masked, fingerprint hashed)
 - ✅ Auto-expiring sessions (24h TTL)
 - ✅ Built-in caching with `node-cache` (no Redis required!)
 - ✅ Optional Redis support for distributed systems
 
+### How Dual-Layer Identification Works:
+
+The package automatically tracks guests using both IP and fingerprint:
+
+- **Fingerprint changes, IP stays** → Same guest detected ✅
+- **IP changes, fingerprint stays** → Same guest detected ✅
+- **Both change** → New guest created
+
+This provides better continuity for users on mobile networks or using VPNs.
+
 ## Guest Storage Options
 
 ### Default: NodeCache (Recommended)
@@ -215,11 +240,23 @@ Session management:
 ```javascript
 const chat = new OblienChat(client, options?);
 
-// Create regular session
-await chat.createSession({ agentId, workflowId?, workspace? });
+// Create regular session (authenticated users)
+await chat.createSession({ 
+    agentId, 
+    namespace?, // Optional: user_id for tracking
+    workflowId?, 
+    workspace? 
+});
 
-// Create guest session
-await chat.createGuestSession({ ip, agentId, workflowId?, metadata?, workspace? });
+// Create guest session (with dual-layer identification)
+await chat.createGuestSession({ 
+    ip, 
+    fingerprint?, // NEW: Browser fingerprint for better tracking
+    agentId, 
+    workflowId?, 
+    metadata?, 
+    workspace? 
+});
 
 // Get session info
 await chat.getSession(sessionId);
@@ -231,7 +268,7 @@ await chat.listSessions({ page?, limit? });
 await chat.deleteSession(sessionId);
 
 // Guest management
-await chat.getGuestByIP(ip);
+await chat.getGuest(ip, fingerprint?); // NEW: Unified function for IP and/or fingerprint lookup
 await chat.getAllGuests(); // Admin only
 await chat.cleanupGuests(); // Clean expired
 ```
@@ -249,7 +286,12 @@ const guestManager = new GuestManager({
     onGuestCreated?: (guest) => void,
 });
 
-await guestManager.getOrCreateGuest(ip, metadata?);
+// With dual-layer identification
+await guestManager.getOrCreateGuest(ip, fingerprint?, metadata?);
+
+// Find existing guest by IP and/or fingerprint
+await guestManager.findExistingGuest(fingerprint, ip);
+
 await guestManager.getGuest(guestId);
 await guestManager.updateGuest(guestId, updates);
 await guestManager.deleteGuest(guestId);
@@ -281,6 +323,7 @@ app.post('/api/session', async (req, res) => {
     try {
         const session = await chat.createSession({
             agentId: req.body.agentId,
+            namespace: req.user.id, // Pass user ID as namespace
         });
 
         res.json(session);
@@ -289,14 +332,36 @@ app.post('/api/session', async (req, res) => {
     }
 });
 
-// Create guest session
+// Create guest session with dual-layer identification
 app.post('/api/guest-session', async (req, res) => {
     try {
-        const ip = req.ip;
+        const ip = req.ip || req.headers['x-forwarded-for'];
+        const fingerprint = req.body.fingerprint; // From client
+        
+        // Check for existing guest first
+        const existingGuest = await chat.getGuest(ip, fingerprint);
         
+        if (existingGuest && existingGuest.sessions.length > 0) {
+            // Return existing session if available
+            const latestSession = existingGuest.sessions[existingGuest.sessions.length - 1];
+            const sessionDetails = await chat.getSession(latestSession);
+            
+            if (sessionDetails?.token) {
+                return res.json({
+                    ...sessionDetails,
+                    isExisting: true,
+                });
+            }
+        }
+        
+        // Create new guest session
         const session = await chat.createGuestSession({
             ip,
+            fingerprint,
             agentId: req.body.agentId,
+            metadata: {
+                userAgent: req.headers['user-agent'],
+            },
         });
 
         res.json(session);
@@ -330,9 +395,11 @@ export default async function handler(req, res) {
         // For guests
         if (!req.headers.authorization) {
             const ip = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
+            const fingerprint = req.body.fingerprint;
             
             const session = await chat.createGuestSession({
                 ip,
+                fingerprint, // Dual-layer identification
                 agentId: req.body.agentId,
             });
 
@@ -342,6 +409,7 @@ export default async function handler(req, res) {
         // For authenticated users
         const session = await chat.createSession({
             agentId: req.body.agentId,
+            namespace: req.user.id, // User ID for tracking
         });
 
         res.json(session);
@@ -381,10 +449,17 @@ OBLIEN_BASE_URL=https://api.oblien.com  # Optional
 
 Check the `/examples` folder for complete examples:
 
+- `raw.js` - Complete test suite demonstrating all features
 - `express-server.js` - Full Express.js implementation
 - `nextjs-api-route.js` - Next.js API routes (App Router & Pages Router)
 - `with-redis.js` - Production setup with Redis
 
+Run the test example:
+```bash
+cd node_modules/oblien
+node examples/raw.js
+```
+
 ## TypeScript Support
 
 Full TypeScript definitions included:
@@ -413,9 +488,38 @@ const chat: OblienChat = new OblienChat(client);
 - 50 messages/day  
 - 20 messages/hour
 
+### Q: How does dual-layer identification work?
+
+**A:** The package tracks guests using both IP address and browser fingerprint:
+
+```javascript
+// First visit: Creates guest with IP + fingerprint
+await chat.createGuestSession({
+    ip: '1.2.3.4',
+    fingerprint: 'abc123',
+    agentId: 'agent-id',
+});
+
+// Same user, different IP (e.g., mobile network)
+// → Same guest detected by fingerprint ✅
+await chat.createGuestSession({
+    ip: '5.6.7.8',        // Different IP
+    fingerprint: 'abc123', // Same fingerprint
+    agentId: 'agent-id',
+});
+
+// Same user, different fingerprint (e.g., cleared browser data)
+// → Same guest detected by IP ✅
+await chat.createGuestSession({
+    ip: '1.2.3.4',        // Same IP
+    fingerprint: 'xyz789', // Different fingerprint
+    agentId: 'agent-id',
+});
+```
+
 ### Q: Can I use custom guest IDs instead of IP?
 
-**A:** Yes! Just create your own guest ID and pass it as the `namespace`:
+**A:** Yes! Pass it as the `namespace`:
 
 ```javascript
 await chat.createSession({

package/index.d.ts

@@ -133,11 +133,13 @@ export interface ChatOptions {
 export interface CreateSessionOptions {
     agentId: string;
     workflowId?: string;
+    namespace?: string; // For authenticated users, typically user_id
     workspace?: Record<string, any>;
 }
 
 export interface CreateGuestSessionOptions {
     ip: string;
+    fingerprint?: string;
     agentId: string;
     workflowId?: string;
     metadata?: Record<string, any>;
@@ -157,7 +159,7 @@ export class OblienChat {
     
     createSession(options: CreateSessionOptions): Promise<SessionData>;
     createGuestSession(options: CreateGuestSessionOptions): Promise<GuestSessionData>;
-    getGuestByIP(ip: string): Promise<Guest | null>;
+    getGuest(ip: string, fingerprint?: string): Promise<Guest | null>;
     getSession(sessionId: string): Promise<any>;
     listSessions(options?: Record<string, any>): Promise<any[]>;
     deleteSession(sessionId: string): Promise<any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oblien",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "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

@@ -46,9 +46,10 @@ export class OblienChat {
     }
 
     /**
-     * Create a guest session based on IP
+     * Create a guest session based on IP and fingerprint (dual-layer identification)
      * @param {Object} options - Guest session options
      * @param {string} options.ip - Client IP address
+     * @param {string} [options.fingerprint] - Client fingerprint for identification
      * @param {string} options.agentId - Agent ID to chat with
      * @param {string} [options.workflowId] - Workflow ID
      * @param {Object} [options.metadata] - Additional guest metadata
@@ -56,14 +57,18 @@ export class OblienChat {
      * @returns {Promise<Object>} Session data with token and guest info
      */
     async createGuestSession(options) {
-        const { ip, agentId, workflowId, metadata, workspace } = options;
+        const { ip, fingerprint, agentId, workflowId, metadata = {}, workspace } = options;
 
         if (!ip) {
             throw new Error('IP address is required for guest sessions');
         }
 
-        // Get or create guest user
-        const guest = await this.guestManager.getOrCreateGuest(ip, metadata);
+        // Get or create guest user (handles fingerprint and IP mapping internally)
+        const guest = await this.guestManager.getOrCreateGuest(ip, fingerprint, {
+            ...metadata,
+            fingerprint,
+            ip,
+        });
 
         // Create session
         const session = new ChatSession({
@@ -91,13 +96,35 @@ export class OblienChat {
     }
 
     /**
-     * Get guest by IP
+     * Get guest by IP and/or fingerprint (dual-layer identification)
      * @param {string} ip - IP address
+     * @param {string} [fingerprint] - Client fingerprint (optional)
      * @returns {Promise<Object|null>} Guest object or null
      */
-    async getGuestByIP(ip) {
-        const guestId = this.guestManager.generateGuestId(ip);
-        return await this.guestManager.getGuest(guestId);
+    async getGuest(ip, fingerprint = null) {
+        // Try fingerprint first if provided
+        if (fingerprint) {
+            const guestIdByFingerprint = await this.guestManager.storage.get(`fingerprint:${fingerprint}`);
+            if (guestIdByFingerprint) {
+                const guest = await this.guestManager.getGuest(guestIdByFingerprint);
+                if (guest) return guest;
+            }
+        }
+
+        // Fallback to IP
+        if (ip) {
+            const guestIdByIp = await this.guestManager.storage.get(`ip:${ip}`);
+            if (guestIdByIp) {
+                const guest = await this.guestManager.getGuest(guestIdByIp);
+                if (guest) return guest;
+            }
+            
+            // Fallback to old method (generate guest ID from IP)
+            const fallbackGuestId = this.guestManager.generateGuestId(ip);
+            return await this.guestManager.getGuest(fallbackGuestId);
+        }
+
+        return null;
     }
 
     /**

package/src/chat/session.js

@@ -41,21 +41,21 @@ export class ChatSession {
     async create() {
         const payload = {
             agent_id: this.agentId,
-            workflow_id: this.workflowId,
+            app_id: this.workflowId, // Backend uses app_id for workflow_id
             is_guest: this.isGuest,
             namespace: this.namespace,
             workspace: this.workspace,
         };
 
-        this.data = await this.client.post('ai/session', payload);
+        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.tokens?.token;
+        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.workflowId,
+            workflowId: this.data.workflowId || this.data.appId || this.workflowId,
             namespace: this.namespace,
         };
     }

package/src/client.js

@@ -6,22 +6,22 @@
 export class OblienClient {
     /**
      * @param {Object} config - Configuration options
-     * @param {string} config.apiKey - Your Oblien API key
-     * @param {string} [config.apiSecret] - Your Oblien API secret (for server-side)
+     * @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)
      */
     constructor(config) {
         if (!config || !config.apiKey) {
-            throw new Error('Oblien API key is required');
+            throw new Error('Oblien API key (client ID) is required');
+        }
+        if (!config.apiSecret) {
+            throw new Error('Oblien API secret (client secret) is required');
         }
 
-        this.apiKey = config.apiKey;
-        this.apiSecret = config.apiSecret;
+        this.clientId = config.apiKey;
+        this.clientSecret = config.apiSecret;
         this.baseURL = config.baseURL || 'https://api.oblien.com';
-        this.version = config.version || 'v1';
-        this.token = null;
-        this.tokenExpiry = null;
     }
 
     /**
@@ -30,55 +30,18 @@ export class OblienClient {
      */
     _buildURL(path) {
         const cleanPath = path.startsWith('/') ? path.slice(1) : path;
-        return `${this.baseURL}/${this.version}/${cleanPath}`;
-    }
-
-    /**
-     * Authenticate and get access token
-     * @returns {Promise<string>} Access token
-     */
-    async authenticate() {
-        // Check if we have a valid token
-        if (this.token && this.tokenExpiry && Date.now() < this.tokenExpiry) {
-            return this.token;
-        }
-
-        try {
-            const response = await fetch(this._buildURL('auth/authenticate'), {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                },
-                body: JSON.stringify({
-                    apiKey: this.apiKey,
-                    apiSecret: this.apiSecret,
-                }),
-            });
-
-            if (!response.ok) {
-                const error = await response.json();
-                throw new Error(error.message || 'Authentication failed');
-            }
-
-            const data = await response.json();
-            this.token = data.token;
-            // Token expires in 1 hour, refresh 5 min before
-            this.tokenExpiry = Date.now() + (55 * 60 * 1000);
-
-            return this.token;
-        } catch (error) {
-            throw new Error(`Authentication error: ${error.message}`);
-        }
+        // Backend doesn't use version prefix, routes are directly mounted
+        return `${this.baseURL}/${cleanPath}`;
     }
 
     /**
      * Get authentication headers
-     * @returns {Promise<Object>} Headers object
+     * @returns {Object} Headers object with x-client-id and x-client-secret
      */
-    async getAuthHeaders() {
-        const token = await this.authenticate();
+    getAuthHeaders() {
         return {
-            'Authorization': `Bearer ${token}`,
+            'x-client-id': this.clientId,
+            'x-client-secret': this.clientSecret,
             'Content-Type': 'application/json',
         };
     }
@@ -90,7 +53,7 @@ export class OblienClient {
      * @returns {Promise<any>} Response data
      */
     async get(path, params = {}) {
-        const headers = await this.getAuthHeaders();
+        const headers = this.getAuthHeaders();
         const url = new URL(this._buildURL(path));
         
         // Add query parameters
@@ -115,7 +78,7 @@ export class OblienClient {
      * @returns {Promise<any>} Response data
      */
     async post(path, body = {}) {
-        const headers = await this.getAuthHeaders();
+        const headers = this.getAuthHeaders();
         
         const response = await fetch(this._buildURL(path), {
             method: 'POST',
@@ -133,7 +96,7 @@ export class OblienClient {
      * @returns {Promise<any>} Response data
      */
     async put(path, body = {}) {
-        const headers = await this.getAuthHeaders();
+        const headers = this.getAuthHeaders();
         
         const response = await fetch(this._buildURL(path), {
             method: 'PUT',
@@ -150,7 +113,7 @@ export class OblienClient {
      * @returns {Promise<any>} Response data
      */
     async delete(path) {
-        const headers = await this.getAuthHeaders();
+        const headers = this.getAuthHeaders();
         
         const response = await fetch(this._buildURL(path), {
             method: 'DELETE',

package/src/utils/guest-manager.js

@@ -31,38 +31,139 @@ export class GuestManager {
     }
 
     /**
-     * Get or create guest user by IP
+     * Find existing guest by fingerprint or IP (dual-layer identification)
+     * @param {string} fingerprint - Client fingerprint
      * @param {string} ip - IP address
-     * @param {Object} [metadata] - Additional metadata to store
+     * @returns {Promise<Object|null>} Guest object or null
+     */
+    async findExistingGuest(fingerprint, ip) {
+        // Layer 1: Try to find by fingerprint first
+        const guestIdByFingerprint = await this.storage.get(`fingerprint:${fingerprint}`);
+        if (guestIdByFingerprint) {
+            const guest = await this.getGuest(guestIdByFingerprint);
+            if (guest) {
+                // Update IP mapping if it changed
+                if (guest.metadata?.ip !== ip) {
+                    await this._updateMappings(guest.id, fingerprint, ip);
+                    await this.updateGuest(guest.id, {
+                        ip: this._maskIP(ip),
+                        metadata: {
+                            ...guest.metadata,
+                            ip,
+                            previousIps: [...(guest.metadata?.previousIps || []), guest.metadata?.ip].filter(Boolean),
+                        },
+                    });
+                }
+                return guest;
+            }
+        }
+
+        // Layer 2: Fallback to IP if fingerprint didn't match
+        const guestIdByIp = await this.storage.get(`ip:${ip}`);
+        if (guestIdByIp) {
+            const guest = await this.getGuest(guestIdByIp);
+            if (guest) {
+                // Update fingerprint mapping
+                await this._updateMappings(guest.id, fingerprint, ip);
+                await this.updateGuest(guest.id, {
+                    metadata: {
+                        ...guest.metadata,
+                        fingerprint,
+                        previousFingerprints: [...(guest.metadata?.previousFingerprints || []), guest.metadata?.fingerprint].filter(Boolean),
+                    },
+                });
+                return guest;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Update fingerprint and IP mappings
+     * @private
+     */
+    async _updateMappings(guestId, fingerprint, ip) {
+        await this.storage.set(`fingerprint:${fingerprint}`, guestId, this.ttl);
+        await this.storage.set(`ip:${ip}`, guestId, this.ttl);
+    }
+
+    /**
+     * Get or create guest user by IP and fingerprint (dual-layer identification)
+     * Supports both old signature: getOrCreateGuest(ip, metadata)
+     * and new signature: getOrCreateGuest(ip, fingerprint, metadata)
+     * @param {string} ip - IP address
+     * @param {string|Object} fingerprintOrMetadata - Client fingerprint (string) or metadata (object)
+     * @param {Object} [metadata] - Additional metadata to store (only if fingerprint is provided)
      * @returns {Promise<Object>} Guest user object
      */
-    async getOrCreateGuest(ip, metadata = {}) {
-        const guestId = this.generateGuestId(ip);
-        
-        // Try to get existing guest
-        let guest = await this.storage.get(`guest:${guestId}`);
-        
-        if (guest) {
-            // Update last seen
-            guest.lastSeen = new Date().toISOString();
-            await this.storage.set(`guest:${guestId}`, guest, this.ttl);
-            return guest;
+    async getOrCreateGuest(ip, fingerprintOrMetadata = null, metadata = {}) {
+        // Handle backward compatibility: detect if second param is metadata (object) or fingerprint (string)
+        let fingerprint = null;
+        let finalMetadata = {};
+
+        if (fingerprintOrMetadata === null || fingerprintOrMetadata === undefined) {
+            // No second parameter
+            finalMetadata = metadata || {};
+        } else if (typeof fingerprintOrMetadata === 'string') {
+            // New signature: (ip, fingerprint, metadata)
+            fingerprint = fingerprintOrMetadata;
+            finalMetadata = metadata || {};
+        } else if (typeof fingerprintOrMetadata === 'object') {
+            // Old signature: (ip, metadata) - fingerprint is in metadata
+            finalMetadata = fingerprintOrMetadata;
+            fingerprint = finalMetadata.fingerprint || null;
+        }
+
+        // Try to find existing guest by fingerprint or IP
+        if (fingerprint) {
+            const existingGuest = await this.findExistingGuest(fingerprint, ip);
+            if (existingGuest) {
+                // Update last seen
+                existingGuest.lastSeen = new Date().toISOString();
+                await this.storage.set(`guest:${existingGuest.id}`, existingGuest, this.ttl);
+                return existingGuest;
+            }
+        } else {
+            // Try to find by IP only
+            const guestIdByIp = await this.storage.get(`ip:${ip}`);
+            if (guestIdByIp) {
+                const guest = await this.getGuest(guestIdByIp);
+                if (guest) {
+                    guest.lastSeen = new Date().toISOString();
+                    await this.storage.set(`guest:${guest.id}`, guest, this.ttl);
+                    return guest;
+                }
+            }
         }
 
         // Create new guest
-        guest = {
+        const guestId = this.generateGuestId(ip);
+        const guest = {
             id: guestId,
             namespace: guestId, // For rate limiting
             ip: this._maskIP(ip), // Store masked IP for privacy
             isGuest: true,
             createdAt: new Date().toISOString(),
             lastSeen: new Date().toISOString(),
-            metadata,
+            metadata: {
+                ...finalMetadata,
+                ip,
+                fingerprint,
+            },
             sessions: [],
         };
 
         await this.storage.set(`guest:${guestId}`, guest, this.ttl);
 
+        // Store mappings
+        if (fingerprint) {
+            await this._updateMappings(guestId, fingerprint, ip);
+        } else {
+            // Fallback: just store IP mapping if no fingerprint
+            await this.storage.set(`ip:${ip}`, guestId, this.ttl);
+        }
+
         // Call callback if provided
         if (this.onGuestCreated) {
             this.onGuestCreated(guest);