oblien 1.0.6 → 1.1.0

package/README.md

@@ -7,10 +7,10 @@ Server-side SDK for building AI-powered applications with Oblien platform.
 - 🔐 **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
+- 📊 **Namespace management** - Multi-tenant workspaces with service configurations
 - ⚡ **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
+- 🎯 **Complete usage tracking** - Monitor credits, quotas, and activity
 
 ## Installation
 
@@ -164,6 +164,102 @@ The package automatically tracks guests using both IP and fingerprint:
 
 This provides better continuity for users on mobile networks or using VPNs.
 
+## Namespace Management
+
+Manage multi-tenant workspaces with service configurations, usage tracking, and quotas.
+
+```javascript
+import { OblienNamespaces } from 'oblien/namespaces';
+
+const namespaces = new OblienNamespaces(client);
+
+// Create a namespace
+const namespace = await namespaces.create({
+    name: 'Production Environment',
+    type: 'production',
+    metadata: { region: 'us-east-1' },
+    tags: ['production', 'critical'],
+});
+
+// Configure services
+await namespaces.configureService(namespace.id, {
+    service: 'ai',
+    enabled: true,
+    config: { model: 'gpt-4', maxTokens: 4000 },
+    rateLimitRequests: 1000,
+    rateLimitPeriod: 'hour',
+});
+
+// Get usage statistics
+const usage = await namespaces.getUsage(namespace.id, { days: 30 });
+console.log(usage.summary); // Credits, tokens, requests per service
+
+// List all namespaces
+const result = await namespaces.list({
+    status: 'active',
+    type: 'production',
+});
+```
+
+### Namespace Features:
+
+- ✅ **Full CRUD** - Create, read, update, delete namespaces
+- ✅ **Service configuration** - Enable/disable services per namespace
+- ✅ **Usage tracking** - Monitor credits, tokens, and requests
+- ✅ **Quota management** - Set limits per service
+- ✅ **Activity logging** - Complete audit trail
+- ✅ **Rich metadata** - Custom fields and tags
+
+[📖 Full Namespaces Documentation](./docs/NAMESPACES.md)
+
+## Credits Management
+
+Manage credits, quotas, usage tracking, and purchases.
+
+```javascript
+import { OblienCredits } from 'oblien/credits';
+
+const credits = new OblienCredits(client);
+
+// Get balance
+const balance = await credits.getBalance();
+
+// Set namespace quota
+await credits.setQuota({
+    namespace: 'production',
+    service: 'ai',
+    quotaLimit: 10000,
+    period: 'monthly',
+});
+
+// Get usage statistics
+const stats = await credits.getUsageStats({ days: 7 });
+
+// Purchase credits
+const checkout = await credits.createCheckout({
+    packageId: 'pro',
+});
+console.log('Checkout URL:', checkout.checkoutUrl);
+
+// Get transaction history
+const history = await credits.getHistory({
+    namespace: 'production',
+    service: 'ai',
+    limit: 50,
+});
+```
+
+### Credits Features:
+
+- ✅ **Balance management** - Check and add credits
+- ✅ **Quota system** - Set limits per namespace and service
+- ✅ **Usage tracking** - Complete transaction history
+- ✅ **Statistics** - Daily/monthly aggregated data
+- ✅ **Purchase integration** - Stripe checkout for buying credits
+- ✅ **Package management** - Predefined credit packages
+
+[📖 Full Credits Documentation](./docs/CREDITS.md)
+
 ## Guest Storage Options
 
 ### Default: NodeCache (Recommended)

package/credits.js

@@ -0,0 +1,11 @@
+/**
+ * Credits Module Entry Point
+ * Import this for credits management only
+ */
+
+export { OblienCredits } from './src/credits/index.js';
+
+export default { 
+    OblienCredits
+};
+

package/index.d.ts

@@ -19,6 +19,7 @@ export class OblienClient {
     get(path: string, params?: Record<string, any>): Promise<any>;
     post(path: string, body?: Record<string, any>): Promise<any>;
     put(path: string, body?: Record<string, any>): Promise<any>;
+    patch(path: string, body?: Record<string, any>): Promise<any>;
     delete(path: string): Promise<any>;
 }
 
@@ -167,12 +168,272 @@ export class OblienChat {
     cleanupGuests(): Promise<number>;
 }
 
+// ============ Namespaces ============
+
+export interface NamespaceData {
+    id: string;
+    client_id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    end_user_id?: string;
+    fingerprint?: string;
+    ip_address?: string;
+    user_agent?: string;
+    country?: string;
+    status: 'active' | 'inactive' | 'suspended' | 'archived';
+    type: string;
+    is_default: boolean;
+    metadata?: Record<string, any>;
+    tags?: string[];
+    created_at: string;
+    updated_at: string;
+    last_active_at?: string;
+    archived_at?: string;
+}
+
+export interface CreateNamespaceOptions {
+    name: string;
+    slug?: string;
+    description?: string;
+    type?: 'default' | 'production' | 'testing' | 'development';
+    isDefault?: boolean;
+    metadata?: Record<string, any>;
+    tags?: string[];
+    endUserId?: string;
+}
+
+export interface UpdateNamespaceOptions {
+    name?: string;
+    description?: string;
+    status?: 'active' | 'inactive' | 'suspended' | 'archived';
+    type?: string;
+    metadata?: Record<string, any>;
+    tags?: string[];
+}
+
+export interface ListNamespacesOptions {
+    limit?: number;
+    offset?: number;
+    status?: 'active' | 'inactive' | 'suspended' | 'archived';
+    type?: string;
+    search?: string;
+    sortBy?: 'name' | 'created_at' | 'updated_at' | 'last_active_at';
+    sortOrder?: 'ASC' | 'DESC';
+}
+
+export interface ServiceConfig {
+    id: number;
+    namespace_id: string;
+    service: string;
+    enabled: boolean;
+    config?: Record<string, any>;
+    rate_limit_requests?: number;
+    rate_limit_period?: string;
+    features?: string[];
+    created_at: string;
+    updated_at: string;
+}
+
+export interface ConfigureServiceOptions {
+    service: string;
+    enabled?: boolean;
+    config?: Record<string, any>;
+    rateLimitRequests?: number;
+    rateLimitPeriod?: 'minute' | 'hour' | 'day';
+    features?: string[];
+}
+
+export interface NamespaceUsage {
+    usage: Array<{
+        service: string;
+        date: string;
+        requests: number;
+        credits: number;
+        deductions: number;
+    }>;
+    summary: Array<{
+        service: string;
+        total_requests: number;
+        total_credits: number;
+        first_used: string;
+        last_used: string;
+    }>;
+    quotas: Array<any>;
+    active_sessions: number;
+}
+
+export class Namespace {
+    constructor(options: { client: OblienClient; namespaceId?: string; data?: NamespaceData });
+    
+    namespaceId: string | null;
+    data: NamespaceData | null;
+    
+    create(options: CreateNamespaceOptions): Promise<NamespaceData>;
+    get(identifier?: string): Promise<NamespaceData>;
+    update(updates: UpdateNamespaceOptions, namespaceId?: string): Promise<NamespaceData>;
+    delete(namespaceId?: string): Promise<any>;
+    getActivity(options?: { limit?: number; offset?: number }, namespaceId?: string): Promise<any[]>;
+    getUsage(options?: { service?: string; days?: number }, namespaceId?: string): Promise<NamespaceUsage>;
+    configureService(options: ConfigureServiceOptions, namespaceId?: string): Promise<ServiceConfig>;
+    listServices(namespaceId?: string): Promise<ServiceConfig[]>;
+    getServiceConfig(service: string, namespaceId?: string): Promise<ServiceConfig>;
+    toggleService(service: string, enabled: boolean, namespaceId?: string): Promise<ServiceConfig>;
+    deleteService(service: string, namespaceId?: string): Promise<any>;
+    bulkConfigureServices(services: ConfigureServiceOptions[], namespaceId?: string): Promise<ServiceConfig[]>;
+}
+
+export class OblienNamespaces {
+    constructor(client: OblienClient);
+    
+    create(options: CreateNamespaceOptions): Promise<NamespaceData>;
+    get(identifier: string): Promise<NamespaceData>;
+    list(options?: ListNamespacesOptions): Promise<{ success: boolean; data: NamespaceData[]; pagination: any }>;
+    update(namespaceId: string, updates: UpdateNamespaceOptions): Promise<NamespaceData>;
+    delete(namespaceId: string): Promise<any>;
+    getActivity(namespaceId: string, options?: { limit?: number; offset?: number }): Promise<any[]>;
+    getUsage(namespaceId: string, options?: { service?: string; days?: number }): Promise<NamespaceUsage>;
+    getAvailableServices(): Promise<any[]>;
+    configureService(namespaceId: string, options: ConfigureServiceOptions): Promise<ServiceConfig>;
+    listServices(namespaceId: string): Promise<ServiceConfig[]>;
+    getServiceConfig(namespaceId: string, service: string): Promise<ServiceConfig>;
+    toggleService(namespaceId: string, service: string, enabled: boolean): Promise<ServiceConfig>;
+    enableService(namespaceId: string, service: string): Promise<ServiceConfig>;
+    disableService(namespaceId: string, service: string): Promise<ServiceConfig>;
+    deleteService(namespaceId: string, service: string): Promise<any>;
+    bulkConfigureServices(namespaceId: string, services: ConfigureServiceOptions[]): Promise<ServiceConfig[]>;
+    namespace(namespaceId?: string): Namespace;
+}
+
+// ============ Credits ============
+
+export interface QuotaData {
+    id: number;
+    client_id: string;
+    namespace: string;
+    service: string;
+    quota_limit: number | null;
+    quota_used: number;
+    period: string;
+    period_start?: string;
+    period_end?: string;
+    enabled: boolean;
+    created_at: string;
+    updated_at: string;
+}
+
+export interface CreditTransaction {
+    id: number;
+    client_id: string;
+    namespace: string;
+    end_user_id?: string;
+    amount: number;
+    client_balance_after: number;
+    namespace_quota_used?: number;
+    type: 'deduction' | 'addition' | 'refund' | 'adjustment';
+    service?: string;
+    description?: string;
+    metadata?: Record<string, any>;
+    created_at: string;
+}
+
+export interface SetQuotaOptions {
+    namespace: string;
+    service: string;
+    quotaLimit: number;
+    period?: 'daily' | 'monthly' | 'unlimited';
+}
+
+export interface HistoryOptions {
+    namespace?: string;
+    endUserId?: string;
+    service?: string;
+    type?: 'deduction' | 'addition' | 'refund' | 'adjustment';
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+    offset?: number;
+    after?: string;
+    afterId?: number;
+}
+
+export interface SummaryOptions {
+    namespace?: string;
+    days?: number;
+    limit?: number;
+    offset?: number;
+    after?: number;
+}
+
+export interface CreditPackage {
+    id: string;
+    name: string;
+    credits: number;
+    price: number;
+    currency: string;
+    active: boolean;
+}
+
+export interface CalculateCostOptions {
+    packageId?: string;
+    amount?: number;
+    credits?: number;
+}
+
+export interface PurchaseOptions {
+    packageId?: string;
+    amount?: number;
+    metadata?: Record<string, any>;
+}
+
+export interface PurchaseHistoryOptions {
+    limit?: number;
+    offset?: number;
+    light?: boolean;
+}
+
+export class OblienCredits {
+    constructor(client: OblienClient);
+    
+    // Balance Management
+    getBalance(): Promise<number>;
+    addCredits(amount: number, reason?: string, metadata?: Record<string, any>): Promise<any>;
+    
+    // Quota Management
+    getNamespaceQuotas(options?: { limit?: number; offset?: number; after?: string; search?: string; status?: string }): Promise<any>;
+    getNamespaceDetails(namespace: string, options?: { days?: number }): Promise<any>;
+    setQuota(options: SetQuotaOptions): Promise<QuotaData>;
+    resetQuota(namespace: string, service: string): Promise<any>;
+    
+    // Usage History & Transactions
+    getHistory(options?: HistoryOptions): Promise<{ success: boolean; data: CreditTransaction[]; pagination: any }>;
+    getHistoryFilters(): Promise<{ namespaces: string[]; services: string[] }>;
+    getSummary(options?: SummaryOptions): Promise<any>;
+    getUsageStats(options?: { days?: number }): Promise<any>;
+    
+    // Pricing & Packages
+    getPackages(): Promise<CreditPackage[]>;
+    getPricingInfo(): Promise<any>;
+    calculateCost(options: CalculateCostOptions): Promise<any>;
+    calculateCredits(amount: number): Promise<any>;
+    
+    // Purchase Management
+    createCheckout(options: PurchaseOptions): Promise<any>;
+    getPurchaseHistory(options?: PurchaseHistoryOptions): Promise<any>;
+    getPurchaseDetails(purchaseId: string): Promise<any>;
+    getPurchaseSession(purchaseId: string): Promise<any>;
+    cancelPurchase(purchaseId: string): Promise<any>;
+}
+
 // ============ Exports ============
 
 declare const _default: {
     OblienClient: typeof OblienClient;
     OblienChat: typeof OblienChat;
     ChatSession: typeof ChatSession;
+    OblienNamespaces: typeof OblienNamespaces;
+    Namespace: typeof Namespace;
+    OblienCredits: typeof OblienCredits;
     GuestManager: typeof GuestManager;
     NodeCacheStorage: typeof NodeCacheStorage;
     InMemoryStorage: typeof InMemoryStorage;

package/index.js

@@ -5,6 +5,8 @@
 
 import { OblienClient } from './src/client.js';
 import { OblienChat, ChatSession } from './src/chat/index.js';
+import { OblienNamespaces, Namespace } from './src/namespaces/index.js';
+import { OblienCredits } from './src/credits/index.js';
 import { 
     GuestManager, 
     NodeCacheStorage,
@@ -15,6 +17,8 @@ import {
 // Re-export as named exports
 export { OblienClient };
 export { OblienChat, ChatSession };
+export { OblienNamespaces, Namespace };
+export { OblienCredits };
 export { 
     GuestManager, 
     NodeCacheStorage,
@@ -27,6 +31,9 @@ export default {
     OblienClient,
     OblienChat,
     ChatSession,
+    OblienNamespaces,
+    Namespace,
+    OblienCredits,
     GuestManager,
     NodeCacheStorage,
     InMemoryStorage,

package/namespaces.js

@@ -0,0 +1,12 @@
+/**
+ * Namespaces Module Entry Point
+ * Import this for namespace management only
+ */
+
+export { OblienNamespaces, Namespace } from './src/namespaces/index.js';
+
+export default { 
+    OblienNamespaces, 
+    Namespace
+};
+

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "oblien",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Server-side SDK for Oblien AI Platform - Build AI-powered applications with chat, agents, and workflows",
   "main": "index.js",
   "type": "module",
   "types": "index.d.ts",
   "exports": {
     ".": "./index.js",
-    "./chat": "./chat.js"
+    "./chat": "./chat.js",
+    "./namespaces": "./namespaces.js",
+    "./credits": "./credits.js"
   },
   "scripts": {
     "test": "node --test tests/**/*.test.js"
@@ -56,6 +58,8 @@
     "index.js",
     "index.d.ts",
     "chat.js",
+    "namespaces.js",
+    "credits.js",
     "agents.js",
     "workflows.js",
     "README.md",

package/src/chat/index.js

@@ -78,6 +78,9 @@ export class OblienChat {
             workspace,
             isGuest: true,
             namespace: guest.namespace,
+            ipAddress: ip,
+            userAgent: metadata.userAgent,
+            fingerprint: fingerprint,
         });
 
         const sessionData = await session.create();

package/src/chat/session.js

@@ -13,6 +13,9 @@ export class ChatSession {
      * @param {boolean} [options.isGuest] - Is this a guest session
      * @param {string} [options.namespace] - Guest namespace for rate limiting
      * @param {Object} [options.workspace] - Workspace configuration
+     * @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
      */
     constructor(options) {
         if (!options.client) {
@@ -32,6 +35,9 @@ export class ChatSession {
         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;
     }
 
     /**
@@ -45,6 +51,9 @@ export class ChatSession {
             is_guest: this.isGuest,
             namespace: this.namespace,
             workspace: this.workspace,
+            ip_address: this.ipAddress,
+            user_agent: this.userAgent,
+            fingerprint: this.fingerprint,
         };
 
         this.data = await this.client.post('ai/session/create', payload);

package/src/client.js

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

package/src/credits/index.js

@@ -0,0 +1,299 @@
+/**
+ * Credits Module
+ * Manages credits, quotas, usage tracking, and transactions
+ */
+
+export class OblienCredits {
+    /**
+     * @param {import('../client.js').OblienClient} client - Oblien client instance
+     */
+    constructor(client) {
+        if (!client) {
+            throw new Error('Oblien client is required');
+        }
+
+        this.client = client;
+    }
+
+    // =============================================================================
+    // Balance Management
+    // =============================================================================
+
+    /**
+     * Get client's total credit balance
+     * @returns {Promise<number>} Current credit balance
+     */
+    async getBalance() {
+        const response = await this.client.get('credits/balance');
+        return response.balance;
+    }
+
+    /**
+     * Add credits to client (internal use - requires admin permissions)
+     * @param {number} amount - Amount of credits to add
+     * @param {string} [reason] - Reason for adding credits
+     * @param {Object} [metadata] - Additional metadata
+     * @returns {Promise<Object>} Result with new balance
+     */
+    async addCredits(amount, reason = 'manual', metadata = {}) {
+        const response = await this.client.post('credits/add', {
+            amount,
+            reason,
+            metadata
+        });
+        return response;
+    }
+
+    // =============================================================================
+    // Quota Management
+    // =============================================================================
+
+    /**
+     * Get all namespace quotas with pagination and filtering
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Max results (default: 100, max: 500)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {string} [options.after] - Cursor for pagination (format: "namespace:service")
+     * @param {string} [options.search] - Search query
+     * @param {string} [options.status] - Filter by status: 'active', 'warning', 'exceeded'
+     * @returns {Promise<Object>} Namespaces with quotas and pagination info
+     */
+    async getNamespaceQuotas(options = {}) {
+        const response = await this.client.get('credits/namespaces', options);
+        return response;
+    }
+
+    /**
+     * Get detailed namespace quota information
+     * @param {string} namespace - Namespace slug or ID
+     * @param {Object} [options] - Query options
+     * @param {number} [options.days] - Number of days for stats (default: 7, max: 90)
+     * @returns {Promise<Object>} Namespace details with quotas, usage, and transactions
+     */
+    async getNamespaceDetails(namespace, options = {}) {
+        const response = await this.client.get(`credits/namespaces/${namespace}`, options);
+        return response;
+    }
+
+    /**
+     * Set quota for a namespace and service
+     * @param {Object} options - Quota options
+     * @param {string} options.namespace - Namespace slug
+     * @param {string} options.service - Service name (e.g., 'ai', '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 quota
+     */
+    async setQuota(options) {
+        if (!options.namespace || !options.service) {
+            throw new Error('namespace and service are required');
+        }
+
+        if (options.quotaLimit === undefined) {
+            throw new Error('quotaLimit is required');
+        }
+
+        const response = await this.client.post('credits/namespace-quota', {
+            namespace: options.namespace,
+            service: options.service,
+            quotaLimit: options.quotaLimit,
+            period: options.period || 'unlimited'
+        });
+
+        return response;
+    }
+
+    /**
+     * Reset namespace quota (e.g., for monthly reset)
+     * @param {string} namespace - Namespace slug
+     * @param {string} service - Service name
+     * @returns {Promise<Object>} Reset result
+     */
+    async resetQuota(namespace, service) {
+        if (!namespace || !service) {
+            throw new Error('namespace and service are required');
+        }
+
+        const response = await this.client.post('credits/reset-quota', {
+            namespace,
+            service
+        });
+
+        return response;
+    }
+
+    // =============================================================================
+    // Usage History & Transactions
+    // =============================================================================
+
+    /**
+     * Get credit usage history with filtering and pagination
+     * @param {Object} [options] - Query options
+     * @param {string} [options.namespace] - Filter by namespace
+     * @param {string} [options.endUserId] - Filter by end user ID
+     * @param {string} [options.service] - Filter by service
+     * @param {string} [options.type] - Filter by type: 'deduction', 'addition', 'refund', 'adjustment'
+     * @param {string} [options.startDate] - Start date (ISO string)
+     * @param {string} [options.endDate] - End date (ISO string)
+     * @param {number} [options.limit] - Max results (default: 50)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {string} [options.after] - Cursor for pagination (timestamp)
+     * @param {number} [options.afterId] - Cursor ID for pagination
+     * @returns {Promise<Object>} History with transactions and pagination
+     */
+    async getHistory(options = {}) {
+        const response = await this.client.get('credits/history', options);
+        return response;
+    }
+
+    /**
+     * Get available filter options for history
+     * @returns {Promise<Object>} Available namespaces and services
+     */
+    async getHistoryFilters() {
+        const response = await this.client.get('credits/history/filters');
+        return response;
+    }
+
+    /**
+     * Get usage summary by namespace/service
+     * @param {Object} [options] - Query options
+     * @param {string} [options.namespace] - Filter by namespace
+     * @param {number} [options.days] - Number of days to look back (default: 30)
+     * @param {number} [options.limit] - Max results (default: 50, max: 500)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {number} [options.after] - Cursor for pagination (total_spent value)
+     * @returns {Promise<Object>} Summary with aggregated usage
+     */
+    async getSummary(options = {}) {
+        const response = await this.client.get('credits/summary', options);
+        return response;
+    }
+
+    /**
+     * Get daily usage statistics (for charts)
+     * @param {Object} [options] - Query options
+     * @param {number} [options.days] - Number of days (default: 7)
+     * @returns {Promise<Object>} Daily usage statistics
+     */
+    async getUsageStats(options = {}) {
+        const response = await this.client.get('credits/usage-stats', options);
+        return response;
+    }
+
+    // =============================================================================
+    // Pricing & Packages
+    // =============================================================================
+
+    /**
+     * Get available credit packages
+     * @returns {Promise<Array>} Array of credit packages
+     */
+    async getPackages() {
+        const response = await this.client.get('credits/packages');
+        return response.packages || response.data || response;
+    }
+
+    /**
+     * Get pricing information and limits
+     * @returns {Promise<Object>} Pricing info with rates and limits
+     */
+    async getPricingInfo() {
+        const response = await this.client.get('credits/pricing-info');
+        return response;
+    }
+
+    /**
+     * Calculate credits from money or vice versa
+     * @param {Object} options - Calculation options
+     * @param {string} [options.packageId] - Package ID to calculate
+     * @param {number} [options.amount] - Money amount to convert to credits
+     * @param {number} [options.credits] - Credits to convert to money
+     * @returns {Promise<Object>} Calculation result with amount and credits
+     */
+    async calculateCost(options) {
+        if (!options.packageId && !options.amount && !options.credits) {
+            throw new Error('Must provide either packageId, amount, or credits');
+        }
+
+        const response = await this.client.post('credits/calculate-cost', options);
+        return response;
+    }
+
+    /**
+     * Calculate credits for a given amount (preview)
+     * @param {number} amount - Money amount
+     * @returns {Promise<Object>} Credits calculation
+     */
+    async calculateCredits(amount) {
+        const response = await this.client.get('credits/calculate', { amount });
+        return response;
+    }
+
+    // =============================================================================
+    // Purchase Management
+    // =============================================================================
+
+    /**
+     * Create Stripe checkout to purchase credits
+     * @param {Object} options - Purchase options
+     * @param {string} [options.packageId] - Package ID to purchase
+     * @param {number} [options.amount] - Custom amount to purchase
+     * @param {Object} [options.metadata] - Additional metadata
+     * @returns {Promise<Object>} Checkout session with URL
+     */
+    async createCheckout(options) {
+        if (!options.packageId && !options.amount) {
+            throw new Error('Must provide either packageId or amount');
+        }
+
+        const response = await this.client.post('credits/purchase', options);
+        return response;
+    }
+
+    /**
+     * Get purchase history
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Max results (default: 50, max: 100)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {boolean} [options.light] - If true, returns basic data only (faster)
+     * @returns {Promise<Object>} Purchase history with pagination
+     */
+    async getPurchaseHistory(options = {}) {
+        const response = await this.client.get('credits/purchases', options);
+        return response;
+    }
+
+    /**
+     * Get single purchase details
+     * @param {string} purchaseId - Purchase ID
+     * @returns {Promise<Object>} Purchase details
+     */
+    async getPurchaseDetails(purchaseId) {
+        const response = await this.client.get(`credits/purchases/${purchaseId}`);
+        return response;
+    }
+
+    /**
+     * Get Stripe checkout session URL for pending purchase
+     * @param {string} purchaseId - Purchase ID
+     * @returns {Promise<Object>} Session with checkout URL
+     */
+    async getPurchaseSession(purchaseId) {
+        const response = await this.client.get(`credits/purchases/${purchaseId}/session`);
+        return response;
+    }
+
+    /**
+     * Cancel a pending purchase
+     * @param {string} purchaseId - Purchase ID
+     * @returns {Promise<Object>} Cancellation result
+     */
+    async cancelPurchase(purchaseId) {
+        const response = await this.client.post(`credits/purchases/${purchaseId}/cancel`);
+        return response;
+    }
+}
+
+export default OblienCredits;
+

package/src/namespaces/index.js

@@ -0,0 +1,225 @@
+/**
+ * Namespaces Module
+ * Manages namespaces, service configurations, and usage tracking
+ */
+
+import { Namespace } from './namespace.js';
+
+export class OblienNamespaces {
+    /**
+     * @param {import('../client.js').OblienClient} client - Oblien client instance
+     */
+    constructor(client) {
+        if (!client) {
+            throw new Error('Oblien client is required');
+        }
+
+        this.client = client;
+    }
+
+    /**
+     * Create a new namespace
+     * @param {Object} options - Namespace options
+     * @param {string} options.name - Namespace name (required)
+     * @param {string} [options.slug] - URL-friendly slug
+     * @param {string} [options.description] - Description
+     * @param {string} [options.type] - Type: 'default', 'production', 'testing', 'development'
+     * @param {boolean} [options.isDefault] - Is default namespace
+     * @param {Object} [options.metadata] - Custom metadata
+     * @param {Array<string>} [options.tags] - Tags
+     * @param {string} [options.endUserId] - End user ID
+     * @returns {Promise<Object>} Created namespace data
+     */
+    async create(options) {
+        const namespace = new Namespace({ client: this.client });
+        return await namespace.create(options);
+    }
+
+    /**
+     * Get namespace by ID or slug
+     * @param {string} identifier - Namespace ID or slug
+     * @returns {Promise<Object>} Namespace data
+     */
+    async get(identifier) {
+        const namespace = new Namespace({ client: this.client });
+        return await namespace.get(identifier);
+    }
+
+    /**
+     * List all namespaces with filtering and pagination
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Max results (default: 50, max: 100)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {string} [options.status] - Filter by status: 'active', 'inactive', 'suspended', 'archived'
+     * @param {string} [options.type] - Filter by type: 'default', 'production', 'testing', 'development'
+     * @param {string} [options.search] - Search in name, slug, description
+     * @param {string} [options.sortBy] - Sort by: 'name', 'created_at', 'updated_at', 'last_active_at'
+     * @param {string} [options.sortOrder] - Sort order: 'ASC', 'DESC'
+     * @returns {Promise<Object>} Namespaces data with pagination info
+     */
+    async list(options = {}) {
+        const response = await this.client.get('namespaces', options);
+        return response;
+    }
+
+    /**
+     * Update namespace
+     * @param {string} namespaceId - Namespace ID
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated namespace data
+     */
+    async update(namespaceId, updates) {
+        const namespace = new Namespace({ client: this.client, namespaceId });
+        return await namespace.update(updates);
+    }
+
+    /**
+     * Delete (archive) namespace
+     * @param {string} namespaceId - Namespace ID
+     * @returns {Promise<Object>} Deletion result
+     */
+    async delete(namespaceId) {
+        const namespace = new Namespace({ client: this.client, namespaceId });
+        return await namespace.delete();
+    }
+
+    /**
+     * Get namespace activity log
+     * @param {string} namespaceId - Namespace ID
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Number of activities (default: 50)
+     * @param {number} [options.offset] - Offset for pagination
+     * @returns {Promise<Array>} Array of activity logs
+     */
+    async getActivity(namespaceId, options = {}) {
+        const namespace = new Namespace({ client: this.client, namespaceId });
+        return await namespace.getActivity(options);
+    }
+
+    /**
+     * Get namespace usage statistics
+     * @param {string} namespaceId - Namespace ID
+     * @param {Object} [options] - Query options
+     * @param {string} [options.service] - Filter by service
+     * @param {number} [options.days] - Number of days (default: 30)
+     * @returns {Promise<Object>} Usage statistics
+     */
+    async getUsage(namespaceId, options = {}) {
+        const namespace = new Namespace({ client: this.client, namespaceId });
+        return await namespace.getUsage(options);
+    }
+
+    /**
+     * Get available services
+     * @returns {Promise<Array>} Array of available services
+     */
+    async getAvailableServices() {
+        const response = await this.client.get('namespaces/services/available');
+        return response.data || response;
+    }
+
+    /**
+     * Configure a service for a namespace
+     * @param {string} namespaceId - Namespace ID
+     * @param {Object} options - Service configuration
+     * @param {string} options.service - Service name (required)
+     * @param {boolean} [options.enabled] - Enable/disable service
+     * @param {Object} [options.config] - Service-specific configuration
+     * @param {number} [options.rateLimitRequests] - Rate limit requests
+     * @param {string} [options.rateLimitPeriod] - Rate limit period
+     * @param {Array<string>} [options.features] - Enabled features
+     * @returns {Promise<Object>} Service configuration
+     */
+    async configureService(namespaceId, options) {
+        const namespace = new Namespace({ client: this.client, namespaceId });
+        return await namespace.configureService(options);
+    }
+
+    /**
+     * List all services for a namespace
+     * @param {string} namespaceId - Namespace ID
+     * @returns {Promise<Array>} Array of service configurations
+     */
+    async listServices(namespaceId) {
+        const namespace = new Namespace({ client: this.client, namespaceId });
+        return await namespace.listServices();
+    }
+
+    /**
+     * Get specific service configuration
+     * @param {string} namespaceId - Namespace ID
+     * @param {string} service - Service name
+     * @returns {Promise<Object>} Service configuration
+     */
+    async getServiceConfig(namespaceId, service) {
+        const namespace = new Namespace({ client: this.client, namespaceId });
+        return await namespace.getServiceConfig(service);
+    }
+
+    /**
+     * Toggle service enabled/disabled
+     * @param {string} namespaceId - Namespace ID
+     * @param {string} service - Service name
+     * @param {boolean} enabled - Enable or disable
+     * @returns {Promise<Object>} Updated service configuration
+     */
+    async toggleService(namespaceId, service, enabled) {
+        const namespace = new Namespace({ client: this.client, namespaceId });
+        return await namespace.toggleService(service, enabled);
+    }
+
+    /**
+     * Enable a service for a namespace
+     * @param {string} namespaceId - Namespace ID
+     * @param {string} service - Service name
+     * @returns {Promise<Object>} Updated service configuration
+     */
+    async enableService(namespaceId, service) {
+        return await this.toggleService(namespaceId, service, true);
+    }
+
+    /**
+     * Disable a service for a namespace
+     * @param {string} namespaceId - Namespace ID
+     * @param {string} service - Service name
+     * @returns {Promise<Object>} Updated service configuration
+     */
+    async disableService(namespaceId, service) {
+        return await this.toggleService(namespaceId, service, false);
+    }
+
+    /**
+     * Delete service configuration
+     * @param {string} namespaceId - Namespace ID
+     * @param {string} service - Service name
+     * @returns {Promise<Object>} Deletion result
+     */
+    async deleteService(namespaceId, service) {
+        const namespace = new Namespace({ client: this.client, namespaceId });
+        return await namespace.deleteService(service);
+    }
+
+    /**
+     * Bulk configure multiple services
+     * @param {string} namespaceId - Namespace ID
+     * @param {Array<Object>} services - Array of service configurations
+     * @returns {Promise<Array>} Array of configured services
+     */
+    async bulkConfigureServices(namespaceId, services) {
+        const namespace = new Namespace({ client: this.client, namespaceId });
+        return await namespace.bulkConfigureServices(services);
+    }
+
+    /**
+     * Create a Namespace instance for chaining operations
+     * @param {string} [namespaceId] - Namespace ID
+     * @returns {Namespace} Namespace instance
+     */
+    namespace(namespaceId) {
+        return new Namespace({ client: this.client, namespaceId });
+    }
+}
+
+export { Namespace };
+export default OblienNamespaces;
+

package/src/namespaces/namespace.js

@@ -0,0 +1,274 @@
+/**
+ * Namespace Entity Manager
+ * Manages individual namespace operations
+ */
+
+export class Namespace {
+    /**
+     * @param {Object} options - Namespace options
+     * @param {import('../client.js').OblienClient} options.client - Oblien client instance
+     * @param {string} [options.namespaceId] - Existing namespace ID
+     * @param {Object} [options.data] - Namespace data
+     */
+    constructor(options) {
+        if (!options.client) {
+            throw new Error('Oblien client is required');
+        }
+
+        this.client = options.client;
+        this.namespaceId = options.namespaceId || null;
+        this.data = options.data || null;
+    }
+
+    /**
+     * Create a new namespace
+     * @param {Object} options - Namespace options
+     * @param {string} options.name - Namespace name (required)
+     * @param {string} [options.slug] - URL-friendly slug (auto-generated from name if not provided)
+     * @param {string} [options.description] - Namespace description
+     * @param {string} [options.type] - Type: 'default', 'production', 'testing', 'development'
+     * @param {boolean} [options.isDefault] - Is this the default namespace
+     * @param {Object} [options.metadata] - Custom metadata object
+     * @param {Array<string>} [options.tags] - Array of tags
+     * @param {string} [options.endUserId] - End user ID (creator)
+     * @returns {Promise<Object>} Created namespace data
+     */
+    async create(options) {
+        if (!options.name) {
+            throw new Error('Namespace name is required');
+        }
+
+        const payload = {
+            name: options.name,
+            slug: options.slug,
+            description: options.description,
+            type: options.type || 'default',
+            isDefault: options.isDefault || false,
+            metadata: options.metadata || {},
+            tags: options.tags || [],
+            endUserId: options.endUserId,
+        };
+
+        const response = await this.client.post('namespaces', payload);
+        this.data = response.data;
+        this.namespaceId = this.data.id;
+
+        return this.data;
+    }
+
+    /**
+     * Get namespace details
+     * @param {string} [identifier] - Namespace ID or slug (uses instance namespaceId if not provided)
+     * @returns {Promise<Object>} Namespace data
+     */
+    async get(identifier) {
+        const id = identifier || this.namespaceId;
+        if (!id) {
+            throw new Error('Namespace ID or slug is required');
+        }
+
+        const response = await this.client.get(`namespaces/${id}`);
+        this.data = response.data;
+        this.namespaceId = this.data.id;
+
+        return this.data;
+    }
+
+    /**
+     * Update namespace
+     * @param {Object} updates - Fields to update
+     * @param {string} [updates.name] - New name
+     * @param {string} [updates.description] - New description
+     * @param {string} [updates.status] - New status: 'active', 'inactive', 'suspended', 'archived'
+     * @param {string} [updates.type] - New type
+     * @param {Object} [updates.metadata] - New metadata
+     * @param {Array<string>} [updates.tags] - New tags
+     * @param {string} [namespaceId] - Namespace ID (uses instance namespaceId if not provided)
+     * @returns {Promise<Object>} Updated namespace data
+     */
+    async update(updates, namespaceId) {
+        const id = namespaceId || this.namespaceId;
+        if (!id) {
+            throw new Error('Namespace ID is required');
+        }
+
+        const response = await this.client.put(`namespaces/${id}`, updates);
+        this.data = response.data;
+
+        return this.data;
+    }
+
+    /**
+     * Delete (archive) namespace
+     * @param {string} [namespaceId] - Namespace ID (uses instance namespaceId if not provided)
+     * @returns {Promise<Object>} Deletion result
+     */
+    async delete(namespaceId) {
+        const id = namespaceId || this.namespaceId;
+        if (!id) {
+            throw new Error('Namespace ID is required');
+        }
+
+        return await this.client.delete(`namespaces/${id}`);
+    }
+
+    /**
+     * Get namespace activity log
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Number of activities to return (default: 50)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {string} [namespaceId] - Namespace ID (uses instance namespaceId if not provided)
+     * @returns {Promise<Array>} Array of activity logs
+     */
+    async getActivity(options = {}, namespaceId) {
+        const id = namespaceId || this.namespaceId;
+        if (!id) {
+            throw new Error('Namespace ID is required');
+        }
+
+        const response = await this.client.get(`namespaces/${id}/activity`, options);
+        return response.data || response;
+    }
+
+    /**
+     * Get namespace usage statistics
+     * @param {Object} [options] - Query options
+     * @param {string} [options.service] - Filter by specific service
+     * @param {number} [options.days] - Number of days to include (default: 30)
+     * @param {string} [namespaceId] - Namespace ID (uses instance namespaceId if not provided)
+     * @returns {Promise<Object>} Usage statistics
+     */
+    async getUsage(options = {}, namespaceId) {
+        const id = namespaceId || this.namespaceId;
+        if (!id) {
+            throw new Error('Namespace ID is required');
+        }
+
+        const response = await this.client.get(`namespaces/${id}/usage`, options);
+        return response.data || response;
+    }
+
+    /**
+     * Configure a service for this namespace
+     * @param {Object} options - Service configuration
+     * @param {string} options.service - Service name (required)
+     * @param {boolean} [options.enabled] - Enable/disable service
+     * @param {Object} [options.config] - Service-specific configuration
+     * @param {number} [options.rateLimitRequests] - Rate limit requests per period
+     * @param {string} [options.rateLimitPeriod] - Rate limit period: 'minute', 'hour', 'day'
+     * @param {Array<string>} [options.features] - Enabled features
+     * @param {string} [namespaceId] - Namespace ID (uses instance namespaceId if not provided)
+     * @returns {Promise<Object>} Service configuration
+     */
+    async configureService(options, namespaceId) {
+        const id = namespaceId || this.namespaceId;
+        if (!id) {
+            throw new Error('Namespace ID is required');
+        }
+
+        if (!options.service) {
+            throw new Error('Service name is required');
+        }
+
+        const response = await this.client.post(`namespaces/${id}/services`, options);
+        return response.data || response;
+    }
+
+    /**
+     * List all services for this namespace
+     * @param {string} [namespaceId] - Namespace ID (uses instance namespaceId if not provided)
+     * @returns {Promise<Array>} Array of service configurations
+     */
+    async listServices(namespaceId) {
+        const id = namespaceId || this.namespaceId;
+        if (!id) {
+            throw new Error('Namespace ID is required');
+        }
+
+        const response = await this.client.get(`namespaces/${id}/services`);
+        return response.data || response;
+    }
+
+    /**
+     * Get specific service configuration
+     * @param {string} service - Service name
+     * @param {string} [namespaceId] - Namespace ID (uses instance namespaceId if not provided)
+     * @returns {Promise<Object>} Service configuration
+     */
+    async getServiceConfig(service, namespaceId) {
+        const id = namespaceId || this.namespaceId;
+        if (!id) {
+            throw new Error('Namespace ID is required');
+        }
+
+        if (!service) {
+            throw new Error('Service name is required');
+        }
+
+        const response = await this.client.get(`namespaces/${id}/services/${service}`);
+        return response.data || response;
+    }
+
+    /**
+     * Toggle service enabled/disabled
+     * @param {string} service - Service name
+     * @param {boolean} enabled - Enable or disable
+     * @param {string} [namespaceId] - Namespace ID (uses instance namespaceId if not provided)
+     * @returns {Promise<Object>} Updated service configuration
+     */
+    async toggleService(service, enabled, namespaceId) {
+        const id = namespaceId || this.namespaceId;
+        if (!id) {
+            throw new Error('Namespace ID is required');
+        }
+
+        if (!service) {
+            throw new Error('Service name is required');
+        }
+
+        const response = await this.client.patch(`namespaces/${id}/services/${service}/toggle`, { enabled });
+        return response.data || response;
+    }
+
+    /**
+     * Delete service configuration
+     * @param {string} service - Service name
+     * @param {string} [namespaceId] - Namespace ID (uses instance namespaceId if not provided)
+     * @returns {Promise<Object>} Deletion result
+     */
+    async deleteService(service, namespaceId) {
+        const id = namespaceId || this.namespaceId;
+        if (!id) {
+            throw new Error('Namespace ID is required');
+        }
+
+        if (!service) {
+            throw new Error('Service name is required');
+        }
+
+        return await this.client.delete(`namespaces/${id}/services/${service}`);
+    }
+
+    /**
+     * Bulk configure multiple services
+     * @param {Array<Object>} services - Array of service configurations
+     * @param {string} [namespaceId] - Namespace ID (uses instance namespaceId if not provided)
+     * @returns {Promise<Array>} Array of service configurations
+     */
+    async bulkConfigureServices(services, namespaceId) {
+        const id = namespaceId || this.namespaceId;
+        if (!id) {
+            throw new Error('Namespace ID is required');
+        }
+
+        if (!Array.isArray(services)) {
+            throw new Error('Services must be an array');
+        }
+
+        const response = await this.client.post(`namespaces/${id}/services/bulk`, { services });
+        return response.data || response;
+    }
+}
+
+export default Namespace;
+

package/src/utils/guest-manager.js

@@ -129,10 +129,10 @@ export class GuestManager {
             const guestIdByIp = await this.storage.get(`ip:${ip}`);
             if (guestIdByIp) {
                 const guest = await this.getGuest(guestIdByIp);
-                if (guest) {
-                    guest.lastSeen = new Date().toISOString();
+        if (guest) {
+            guest.lastSeen = new Date().toISOString();
                     await this.storage.set(`guest:${guest.id}`, guest, this.ttl);
-                    return guest;
+            return guest;
                 }
             }
         }