oblien 1.1.4 → 1.1.5

package/index.d.ts

@@ -396,6 +396,42 @@ export interface SetQuotaOptions {
     period?: 'daily' | 'monthly' | 'unlimited';
 }
 
+export interface SetEndUserQuotaOptions {
+    namespace: string;
+    endUserId: string;
+    service: string;
+    quotaLimit: number;
+    period?: 'daily' | 'monthly' | 'unlimited';
+}
+
+export interface EndUserQuota {
+    limit: number;
+    used: number;
+    remaining: number;
+    period: string;
+    enabled: boolean;
+}
+
+export interface SetDefaultQuotaOptions {
+    level: 'namespace' | 'end_user';
+    service: string;
+    quotaLimit: number | null;
+    period?: 'daily' | 'monthly' | 'unlimited';
+    autoApply?: boolean;
+}
+
+export interface DefaultQuotaConfig {
+    id: number;
+    level: 'namespace' | 'end_user';
+    service: string;
+    quotaLimit: number | null;
+    period: string;
+    autoApply: boolean;
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+
 export interface HistoryOptions {
     namespace?: string;
     endUserId?: string;
@@ -457,6 +493,18 @@ export class OblienCredits {
     setQuota(options: SetQuotaOptions): Promise<QuotaData>;
     resetQuota(namespace: string, service: string): Promise<any>;
     
+    // End User Quota Management (Optional Third Level)
+    setEndUserQuota(options: SetEndUserQuotaOptions): Promise<any>;
+    getEndUserQuota(namespace: string, endUserId: string, service: string): Promise<{ success: boolean; quota: EndUserQuota | null }>;
+    resetEndUserQuota(namespace: string, endUserId: string, service: string): Promise<any>;
+    
+    // Default Quota Configuration (Dynamic, per client)
+    setDefaultQuota(options: SetDefaultQuotaOptions): Promise<any>;
+    getDefaultQuota(level: 'namespace' | 'end_user', service: string): Promise<{ success: boolean; config: DefaultQuotaConfig | null }>;
+    getAllDefaultQuotas(level?: 'namespace' | 'end_user'): Promise<{ success: boolean; configs: DefaultQuotaConfig[] }>;
+    deleteDefaultQuota(level: 'namespace' | 'end_user', service: string): Promise<any>;
+    toggleDefaultQuotaAutoApply(level: 'namespace' | 'end_user', service: string, autoApply: boolean): Promise<any>;
+    
     // Usage History & Transactions
     getHistory(options?: HistoryOptions): Promise<{ success: boolean; data: CreditTransaction[]; pagination: any }>;
     getHistoryFilters(): Promise<{ namespaces: string[]; services: string[] }>;

package/package.json

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

@@ -52,23 +52,60 @@ export class OblienChat {
 
     /**
      * Create a guest session based on IP and fingerprint (dual-layer identification)
+     * 
+     * Namespace handling:
+     * - If `namespace` is provided: Uses it as the session namespace
+     * - If `namespace` is NOT provided: Uses guest's auto-generated namespace (based on IP)
+     * - `endUserId`: Optional identifier for your end user (tracked separately)
+     * 
      * @param {Object} options - Guest session options
-     * @param {string} options.ip - Client IP address
+     * @param {string} options.ip - Client IP address (required)
      * @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
+     * @param {string} [options.namespace] - Custom namespace (e.g., 'my-app-guests'). If not provided, uses auto-generated guest namespace
+     * @param {string} [options.endUserId] - Your end user's ID (e.g., from your database)
+     * @param {Object} [options.metadata] - Additional guest metadata (userAgent, etc.)
      * @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
+     * 
+     * @example
+     * // Simple guest session (auto namespace)
+     * await chat.createGuestSession({
+     *   ip: '1.2.3.4',
+     *   agentId: 'my-agent-id'
+     * });
+     * 
+     * @example
+     * // With custom namespace and end user ID
+     * await chat.createGuestSession({
+     *   ip: '1.2.3.4',
+     *   fingerprint: 'abc123',
+     *   agentId: 'my-agent-id',
+     *   namespace: 'my-app-guests',
+     *   endUserId: 'user_12345'
+     * });
      */
     async createGuestSession(options) {
-        const { ip, fingerprint, agentId, workflowId, metadata = {}, workspace, endUserId } = options;
+        const { 
+            ip, 
+            fingerprint, 
+            agentId, 
+            workflowId, 
+            namespace,
+            endUserId,
+            metadata = {}, 
+            workspace 
+        } = options;
 
         if (!ip) {
             throw new Error('IP address is required for guest sessions');
         }
 
+        if (!agentId) {
+            throw new Error('Agent ID is required for guest sessions');
+        }
+
         // Get or create guest user (handles fingerprint and IP mapping internally)
         const guest = await this.guestManager.getOrCreateGuest(ip, fingerprint, {
             ...metadata,
@@ -81,16 +118,20 @@ export class OblienChat {
             client: this.client,
         });
 
+        // Use custom namespace if provided, otherwise use guest's default namespace
+        const sessionNamespace = namespace || guest.namespace;
+
         const sessionData = await session.create({
             agentId,
             workflowId,
             workspace,
             isGuest: true,
-            namespace: guest.namespace,
+            namespace: sessionNamespace,
             ipAddress: ip,
             userAgent: metadata.userAgent,
+            guestNamespace: guest.namespace,
             fingerprint: fingerprint,
-            endUserId: endUserId,
+            endUserId: endUserId, // Optional: Your end user identifier
         });
 
         // Link session to guest
@@ -338,16 +379,104 @@ export class OblienChat {
     }
 
     /**
-     * Get session info
+     * Get session info (server-side)
      * @param {string} sessionId - Session ID
      * @returns {Promise<Object>} Session details
      */
     async getSession(sessionId) {
+        if (!sessionId) {
+            throw new Error('Session ID is required');
+        }
         return await this.client.get(`ai/session/${sessionId}`);
     }
 
     /**
-     * List sessions
+     * Create a session token for client-side access (server-side)
+     * @param {string} sessionId - Session ID
+     * @returns {Promise<Object>} Token data (accessToken, refreshToken)
+     */
+    async createSessionToken(sessionId) {
+        if (!sessionId) {
+            throw new Error('Session ID is required');
+        }
+        return await this.client.post(`ai/session/${sessionId}/token/create`);
+    }
+
+    /**
+     * Revoke a session token (server-side)
+     * @param {string} sessionId - Session ID
+     * @returns {Promise<Object>} Revocation result
+     */
+    async revokeSessionToken(sessionId) {
+        if (!sessionId) {
+            throw new Error('Session ID is required');
+        }
+        return await this.client.post(`ai/session/${sessionId}/token/revoke`);
+    }
+
+    /**
+     * Get session history by session ID (server-side)
+     * @param {string} sessionId - Session ID
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Number of messages (max 100)
+     * @param {number} [options.offset] - Offset for pagination
+     * @returns {Promise<Object>} Session history with messages
+     */
+    async getSessionHistory(sessionId, options = {}) {
+        if (!sessionId) {
+            throw new Error('Session ID is required');
+        }
+
+        const params = new URLSearchParams();
+        if (options.limit) params.append('limit', Math.min(options.limit, 100).toString());
+        if (options.offset) params.append('offset', Math.max(options.offset, 0).toString());
+
+        const url = `ai/session/${sessionId}/history${params.toString() ? `?${params.toString()}` : ''}`;
+        return await this.client.get(url);
+    }
+
+    /**
+     * Ban a user from a session (server-side)
+     * @param {string} sessionId - Session ID
+     * @param {Object} [options] - Ban options
+     * @param {string} [options.reason] - Reason for ban
+     * @returns {Promise<Object>} Ban result
+     */
+    async banUser(sessionId, options = {}) {
+        if (!sessionId) {
+            throw new Error('Session ID is required');
+        }
+        return await this.client.post(`ai/session/${sessionId}/ban`, options);
+    }
+
+    /**
+     * Unban a user from a session (server-side)
+     * @param {string} sessionId - Session ID
+     * @returns {Promise<Object>} Unban result
+     */
+    async unbanUser(sessionId) {
+        if (!sessionId) {
+            throw new Error('Session ID is required');
+        }
+        return await this.client.post(`ai/session/${sessionId}/unban`);
+    }
+
+    /**
+     * Lock or unlock a session (server-side)
+     * @param {string} sessionId - Session ID
+     * @param {Object} [options] - Lock options
+     * @param {boolean} [options.locked] - Lock state (true to lock, false to unlock)
+     * @returns {Promise<Object>} Lock result
+     */
+    async lockSession(sessionId, options = {}) {
+        if (!sessionId) {
+            throw new Error('Session ID is required');
+        }
+        return await this.client.post(`ai/session/${sessionId}/lock`, options);
+    }
+
+    /**
+     * List sessions (server-side)
      * @param {Object} [options] - Query options
      * @param {string} [options.namespace] - Filter by namespace
      * @param {string} [options.agentId] - Filter by agent ID
@@ -369,11 +498,14 @@ export class OblienChat {
     }
 
     /**
-     * Delete a session
+     * Delete a session (server-side)
      * @param {string} sessionId - Session ID to delete
      * @returns {Promise<Object>} Deletion result
      */
     async deleteSession(sessionId) {
+        if (!sessionId) {
+            throw new Error('Session ID is required');
+        }
         return await this.client.delete(`ai/session/${sessionId}`);
     }
 
@@ -429,6 +561,107 @@ export class OblienChat {
         const data = await this.client.get('ai/guest/cache-stats');
         return data;
     }
+
+    /**
+     * Refresh session token (client-side)
+     * Uses refresh token to get new access token
+     * 
+     * @param {string} refreshToken - Refresh token from session
+     * @returns {Promise<Object>} New tokens
+     */
+    async refreshToken(refreshToken) {
+        if (!refreshToken) {
+            throw new Error('Refresh token is required');
+        }
+
+        const url = this.client._buildURL('ai/session/token/refresh');
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${refreshToken}`,
+                'Content-Type': 'application/json',
+            },
+        });
+
+        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 chat history (client-side)
+     * Uses session token to get chat history
+     * 
+     * @param {Object} options - History options
+     * @param {string} options.token - Session token (required for client-side)
+     * @param {string} [options.namespace] - Namespace filter
+     * @param {number} [options.limit] - Number of messages (max 50)
+     * @param {number} [options.offset] - Offset for pagination
+     * @returns {Promise<Object>} Chat history with messages
+     */
+    async getHistory(options = {}) {
+        const { token, namespace, limit = 50, offset = 0 } = options;
+
+        if (!token) {
+            throw new Error('Session token is required for client-side history');
+        }
+
+        const params = new URLSearchParams();
+        if (namespace) params.append('namespace', namespace);
+        params.append('limit', Math.min(limit, 50).toString());
+        params.append('offset', Math.max(offset, 0).toString());
+
+        const url = `${this.client._buildURL('ai/session/history')}?${params.toString()}`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+        });
+
+        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();
+    }
+
+    /**
+     * Prepare session (client-side)
+     * Prepares session for app/container usage
+     * 
+     * @param {Object} options - Prepare options
+     * @param {string} options.token - Session token (required for client-side)
+     * @returns {Promise<Object>} Preparation result
+     */
+    async prepareSession(options = {}) {
+        const { token } = options;
+
+        if (!token) {
+            throw new Error('Session token is required for client-side prepare');
+        }
+
+        const url = this.client._buildURL('ai/session/prepare');
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+        });
+
+        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();
+    }
 }
 
 export { ChatSession } from './session.js';

package/src/client.js

@@ -126,15 +126,22 @@ export class OblienClient {
     /**
      * Make DELETE request
      * @param {string} path - API path
+     * @param {Object} [body] - Request body
      * @returns {Promise<any>} Response data
      */
-    async delete(path) {
+    async delete(path, body = null) {
         const headers = this.getAuthHeaders();
         
-        const response = await fetch(this._buildURL(path), {
+        const options = {
             method: 'DELETE',
             headers,
-        });
+        };
+
+        if (body) {
+            options.body = JSON.stringify(body);
+        }
+        
+        const response = await fetch(this._buildURL(path), options);
 
         return this._handleResponse(response);
     }

package/src/credits/index.js

@@ -122,6 +122,187 @@ export class OblienCredits {
         return response;
     }
 
+    // =============================================================================
+    // End User Quota Management (Optional Third Level)
+    // =============================================================================
+
+    /**
+     * Set quota for an end user within a namespace
+     * @param {Object} options - Quota options
+     * @param {string} options.namespace - Namespace slug
+     * @param {string} options.endUserId - End user ID
+     * @param {string} options.service - Service name (e.g., 'ai_chat', 'deployment', 'sandbox')
+     * @param {number} options.quotaLimit - Quota limit (null or 0 for unlimited)
+     * @param {string} [options.period] - Quota period: 'daily', 'monthly', 'unlimited'
+     * @returns {Promise<Object>} Created/updated end user quota
+     */
+    async setEndUserQuota(options) {
+        if (!options.namespace || !options.endUserId || !options.service) {
+            throw new Error('namespace, endUserId, and service are required');
+        }
+
+        if (options.quotaLimit === undefined) {
+            throw new Error('quotaLimit is required');
+        }
+
+        const response = await this.client.post('credits/end-users/quota', {
+            namespace: options.namespace,
+            endUserId: options.endUserId,
+            service: options.service,
+            quotaLimit: options.quotaLimit,
+            period: options.period || 'unlimited'
+        });
+
+        return response;
+    }
+
+    /**
+     * Get end user quota
+     * @param {string} namespace - Namespace slug
+     * @param {string} endUserId - End user ID
+     * @param {string} service - Service name
+     * @returns {Promise<Object>} End user quota details
+     */
+    async getEndUserQuota(namespace, endUserId, service) {
+        if (!namespace || !endUserId || !service) {
+            throw new Error('namespace, endUserId, and service are required');
+        }
+
+        const response = await this.client.get('credits/end-users/quota', {
+            namespace,
+            endUserId,
+            service
+        });
+
+        return response;
+    }
+
+    /**
+     * Reset end user quota usage
+     * @param {string} namespace - Namespace slug
+     * @param {string} endUserId - End user ID
+     * @param {string} service - Service name
+     * @returns {Promise<Object>} Reset result
+     */
+    async resetEndUserQuota(namespace, endUserId, service) {
+        if (!namespace || !endUserId || !service) {
+            throw new Error('namespace, endUserId, and service are required');
+        }
+
+        const response = await this.client.post('credits/end-users/reset', {
+            namespace,
+            endUserId,
+            service
+        });
+
+        return response;
+    }
+
+    // =============================================================================
+    // Default Quota Configuration (Dynamic, per client)
+    // =============================================================================
+
+    /**
+     * Set default quota configuration
+     * @param {Object} options - Configuration options
+     * @param {string} options.level - 'namespace' or 'end_user'
+     * @param {string} options.service - Service name (e.g., 'ai_chat', 'deployment')
+     * @param {number} options.quotaLimit - Default quota limit (null for unlimited)
+     * @param {string} [options.period] - 'daily', 'monthly', or 'unlimited'
+     * @param {boolean} [options.autoApply] - Auto-apply to new namespaces/users
+     * @returns {Promise<Object>} Configuration result
+     */
+    async setDefaultQuota(options) {
+        if (!options.level || !options.service || options.quotaLimit === undefined) {
+            throw new Error('level, service, and quotaLimit are required');
+        }
+
+        if (!['namespace', 'end_user'].includes(options.level)) {
+            throw new Error('level must be "namespace" or "end_user"');
+        }
+
+        const response = await this.client.post('credits/defaults', {
+            level: options.level,
+            service: options.service,
+            quotaLimit: options.quotaLimit,
+            period: options.period || 'unlimited',
+            autoApply: options.autoApply !== undefined ? options.autoApply : true,
+        });
+
+        return response;
+    }
+
+    /**
+     * Get default quota configuration
+     * @param {string} level - 'namespace' or 'end_user'
+     * @param {string} service - Service name
+     * @returns {Promise<Object>} Configuration details
+     */
+    async getDefaultQuota(level, service) {
+        if (!level || !service) {
+            throw new Error('level and service are required');
+        }
+
+        const response = await this.client.get('credits/defaults', {
+            level,
+            service,
+        });
+
+        return response;
+    }
+
+    /**
+     * Get all default quota configurations
+     * @param {string} [level] - Optional: filter by 'namespace' or 'end_user'
+     * @returns {Promise<Object>} All configurations
+     */
+    async getAllDefaultQuotas(level = null) {
+        const params = level ? { level } : {};
+        const response = await this.client.get('credits/defaults/all', params);
+        return response;
+    }
+
+    /**
+     * Delete default quota configuration
+     * @param {string} level - 'namespace' or 'end_user'
+     * @param {string} service - Service name
+     * @returns {Promise<Object>} Deletion result
+     */
+    async deleteDefaultQuota(level, service) {
+        if (!level || !service) {
+            throw new Error('level and service are required');
+        }
+
+        // DELETE with body
+        const response = await this.client.delete('credits/defaults', {
+            level,
+            service,
+        });
+
+        return response;
+    }
+
+    /**
+     * Toggle auto-apply for default quota
+     * @param {string} level - 'namespace' or 'end_user'
+     * @param {string} service - Service name
+     * @param {boolean} autoApply - Enable/disable auto-apply
+     * @returns {Promise<Object>} Toggle result
+     */
+    async toggleDefaultQuotaAutoApply(level, service, autoApply) {
+        if (!level || !service || autoApply === undefined) {
+            throw new Error('level, service, and autoApply are required');
+        }
+
+        const response = await this.client.post('credits/defaults/toggle-auto-apply', {
+            level,
+            service,
+            autoApply,
+        });
+
+        return response;
+    }
+
     // =============================================================================
     // Usage History & Transactions
     // =============================================================================

package/src/chat/sessionQuota.js

@@ -1,99 +0,0 @@
-/**
- * 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;
-