oblien 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Oblien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,455 @@
+# Oblien Core SDK
+
+Server-side SDK for building AI-powered applications with Oblien platform.
+
+## Installation
+
+```bash
+npm install oblien-core
+```
+
+## What This SDK Does
+
+**Server-Side Only** - This SDK is for creating and managing chat sessions on your server. It **does not** handle actual messaging - that happens client-side in the browser using the tokens this SDK generates.
+
+### Workflow:
+
+1. **Server:** Create session using this SDK → Get token
+2. **Server:** Send token to client (browser)
+3. **Client:** Use token to chat directly with Oblien API
+4. **Client:** Use [react-chat-agent](https://npmjs.com/package/react-chat-agent) or your own implementation
+
+## Quick Start
+
+### 1. Initialize Client
+
+```javascript
+import { OblienClient } from 'oblien-core';
+
+const client = new OblienClient({
+    apiKey: 'your-api-key',
+    apiSecret: 'your-api-secret', // For server-side
+});
+```
+
+### 2. Create Chat Session
+
+```javascript
+import { OblienChat } from 'oblien-core/chat';
+
+const chat = new OblienChat(client);
+
+// Create session
+const session = await chat.createSession({
+    agentId: 'your-agent-id',
+    // workflowId: 'workflow-id', // Optional
+    // workspace: {}, // Optional
+});
+
+console.log(session);
+// {
+//   sessionId: 'session-xxx',
+//   token: 'jwt-token-for-client',
+//   agentId: 'agent-id',
+//   namespace: null
+// }
+```
+
+### 3. Send Token to Client
+
+```javascript
+// Express example
+app.post('/api/create-session', async (req, res) => {
+    const session = await chat.createSession({
+        agentId: req.body.agentId,
+    });
+
+    res.json({
+        sessionId: session.sessionId,
+        token: session.token, // Client uses this to chat
+    });
+});
+```
+
+### 4. Client Uses Token
+
+```javascript
+// In browser (using react-chat-agent)
+import { ChatProvider } from 'react-chat-agent';
+
+function App() {
+    const [sessionToken, setSessionToken] = useState(null);
+
+    useEffect(() => {
+        // Get token from your server
+        fetch('/api/create-session', {
+            method: 'POST',
+            body: JSON.stringify({ agentId: 'agent-id' }),
+        })
+        .then(r => r.json())
+        .then(data => setSessionToken(data.token));
+    }, []);
+
+    if (!sessionToken) return <div>Loading...</div>;
+
+    return (
+        <ChatProvider token={sessionToken}>
+            <ChatPanel />
+        </ChatProvider>
+    );
+}
+```
+
+## Guest Sessions (Rate Limited)
+
+For anonymous users, create guest sessions based on IP address:
+
+```javascript
+import { OblienChat } from 'oblien-core/chat';
+
+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 session = await chat.createGuestSession({
+        ip: ip,
+        agentId: 'your-agent-id',
+        metadata: {
+            userAgent: req.headers['user-agent'],
+            referrer: req.headers['referer'],
+        },
+    });
+
+    res.json({
+        sessionId: session.sessionId,
+        token: session.token,
+        guest: session.guest,
+        // Guest sessions are rate-limited automatically
+    });
+});
+```
+
+### Guest Features:
+
+- ✅ Automatic rate limiting (100K tokens/day, 50 messages/day)
+- ✅ IP-based identification (privacy-friendly)
+- ✅ Auto-expiring sessions (24h TTL)
+- ✅ Built-in caching with `node-cache` (no Redis required!)
+- ✅ Optional Redis support for distributed systems
+
+## Guest Storage Options
+
+### Default: NodeCache (Recommended)
+
+Works out of the box - no setup needed:
+
+```javascript
+import { OblienChat } from 'oblien-core/chat';
+
+const chat = new OblienChat(client);
+// Uses NodeCacheStorage by default
+// Automatic expiration, memory management, and cleanup
+```
+
+### Option 1: Custom NodeCache Settings
+
+```javascript
+import { OblienChat, NodeCacheStorage } from 'oblien-core/chat';
+
+const storage = new NodeCacheStorage(86400); // 24 hours TTL
+
+const chat = new OblienChat(client, {
+    guestStorage: storage,
+});
+
+// Get cache stats
+console.log(storage.getStats());
+```
+
+### Option 2: Redis (For Distributed Systems)
+
+```javascript
+import { createClient } from 'redis';
+import { OblienChat, RedisStorage } from 'oblien-core/chat';
+
+const redis = createClient();
+await redis.connect();
+
+const chat = new OblienChat(client, {
+    guestStorage: new RedisStorage(redis),
+    guestTTL: 86400, // 24 hours
+});
+```
+
+### Option 3: Simple In-Memory (Dev Only)
+
+```javascript
+import { OblienChat, InMemoryStorage } from 'oblien-core/chat';
+
+const chat = new OblienChat(client, {
+    guestStorage: new InMemoryStorage(),
+});
+// Note: Basic Map storage, no advanced features
+```
+
+## API Reference
+
+### `OblienClient`
+
+Main client for authentication:
+
+```javascript
+const client = new OblienClient({
+    apiKey: string,
+    apiSecret?: string,
+    baseURL?: string,
+});
+```
+
+### `OblienChat`
+
+Session management:
+
+```javascript
+const chat = new OblienChat(client, options?);
+
+// Create regular session
+await chat.createSession({ agentId, workflowId?, workspace? });
+
+// Create guest session
+await chat.createGuestSession({ ip, agentId, workflowId?, metadata?, workspace? });
+
+// Get session info
+await chat.getSession(sessionId);
+
+// List sessions
+await chat.listSessions({ page?, limit? });
+
+// Delete session
+await chat.deleteSession(sessionId);
+
+// Guest management
+await chat.getGuestByIP(ip);
+await chat.getAllGuests(); // Admin only
+await chat.cleanupGuests(); // Clean expired
+```
+
+### `GuestManager`
+
+Manual guest management:
+
+```javascript
+import { GuestManager } from 'oblien-core/chat';
+
+const guestManager = new GuestManager({
+    storage?: StorageAdapter,
+    ttl?: number, // seconds
+    onGuestCreated?: (guest) => void,
+});
+
+await guestManager.getOrCreateGuest(ip, metadata?);
+await guestManager.getGuest(guestId);
+await guestManager.updateGuest(guestId, updates);
+await guestManager.deleteGuest(guestId);
+await guestManager.getAllGuests();
+await guestManager.cleanup();
+```
+
+## Complete Example
+
+### Express Server
+
+```javascript
+import express from 'express';
+import { OblienClient, OblienChat } from 'oblien-core';
+
+const app = express();
+app.use(express.json());
+
+// Initialize Oblien
+const client = new OblienClient({
+    apiKey: process.env.OBLIEN_API_KEY,
+    apiSecret: process.env.OBLIEN_API_SECRET,
+});
+
+const chat = new OblienChat(client);
+
+// Create authenticated session
+app.post('/api/session', async (req, res) => {
+    try {
+        const session = await chat.createSession({
+            agentId: req.body.agentId,
+        });
+
+        res.json(session);
+    } catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+});
+
+// Create guest session
+app.post('/api/guest-session', async (req, res) => {
+    try {
+        const ip = req.ip;
+        
+        const session = await chat.createGuestSession({
+            ip,
+            agentId: req.body.agentId,
+        });
+
+        res.json(session);
+    } catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+});
+
+app.listen(3000);
+```
+
+### Next.js API Route
+
+```javascript
+// pages/api/session.js
+import { OblienClient, OblienChat } from 'oblien-core';
+
+const client = new OblienClient({
+    apiKey: process.env.OBLIEN_API_KEY,
+    apiSecret: process.env.OBLIEN_API_SECRET,
+});
+
+const chat = new OblienChat(client);
+
+export default async function handler(req, res) {
+    if (req.method !== 'POST') {
+        return res.status(405).json({ error: 'Method not allowed' });
+    }
+
+    try {
+        // For guests
+        if (!req.headers.authorization) {
+            const ip = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
+            
+            const session = await chat.createGuestSession({
+                ip,
+                agentId: req.body.agentId,
+            });
+
+            return res.json(session);
+        }
+
+        // For authenticated users
+        const session = await chat.createSession({
+            agentId: req.body.agentId,
+        });
+
+        res.json(session);
+    } catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+}
+```
+
+## Environment Variables
+
+```bash
+OBLIEN_API_KEY=your-api-key
+OBLIEN_API_SECRET=your-api-secret
+OBLIEN_BASE_URL=https://api.oblien.com  # Optional
+```
+
+## Storage Comparison
+
+| Feature | NodeCache (Default) | InMemory | Redis |
+|---------|-------------------|----------|-------|
+| **Setup** | ✅ Zero config | ✅ Zero config | ⚠️ Requires Redis |
+| **Auto-expiry** | ✅ Yes | ✅ Manual | ✅ Yes |
+| **Memory limit** | ✅ Configurable | ❌ No | ✅ Configurable |
+| **Statistics** | ✅ Yes | ❌ No | ⚠️ Via Redis |
+| **Distributed** | ❌ Single instance | ❌ Single instance | ✅ Multi-server |
+| **Persistence** | ❌ Memory only | ❌ Memory only | ✅ Disk backup |
+| **Production** | ✅ Recommended | ❌ Dev only | ✅ High-traffic |
+
+### When to Use What:
+
+- **NodeCache**: Most applications, single server, < 100K guests/day ✅ Recommended
+- **InMemory**: Development, testing, quick prototypes
+- **Redis**: Distributed systems, > 1M guests/day, need persistence
+
+## Examples
+
+Check the `/examples` folder for complete examples:
+
+- `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
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
+import { OblienClient, OblienChat } from 'oblien-core';
+
+const client: OblienClient = new OblienClient({
+    apiKey: string,
+    apiSecret?: string,
+});
+
+const chat: OblienChat = new OblienChat(client);
+```
+
+## FAQ
+
+### Q: Do I need Redis?
+
+**A:** No! NodeCache works great for most applications. Use Redis only if you need multi-server support or very high traffic.
+
+### Q: How does guest rate limiting work?
+
+**A:** Guest sessions are automatically rate-limited by the Oblien API based on the `namespace` (guest ID). Limits:
+- 100K tokens/day
+- 50 messages/day  
+- 20 messages/hour
+
+### Q: Can I use custom guest IDs instead of IP?
+
+**A:** Yes! Just create your own guest ID and pass it as the `namespace`:
+
+```javascript
+await chat.createSession({
+    agentId: 'agent-id',
+    isGuest: true,
+    namespace: 'custom-guest-id',
+});
+```
+
+### Q: How do I clean up expired guests?
+
+**A:** Call `chat.cleanupGuests()` periodically (e.g., cron job or `setInterval`).
+
+## Performance
+
+Benchmarks on standard server:
+
+- Session creation: ~50ms
+- Guest lookup (cached): ~1ms
+- Guest cleanup (1000 guests): ~100ms
+
+## Dependencies
+
+- `node-cache` - Built-in caching (included)
+- `redis` - Optional, for distributed systems (peer dependency)
+
+## License
+
+MIT
+
+## Links
+
+- [Documentation](https://oblien.com/docs/core-sdk)
+- [GitHub](https://github.com/oblien/oblien-core)
+- [Website](https://oblien.com)
+- [React Chat Agent](https://npmjs.com/package/react-chat-agent) - Client-side chat component
+- [Agent Sandbox](https://npmjs.com/package/agent-sandbox) - Sandbox SDK

package/chat.js

@@ -0,0 +1,21 @@
+/**
+ * Chat Module Entry Point
+ * Import this for chat session management only
+ */
+
+export { OblienChat, ChatSession } from './src/chat/index.js';
+export { 
+    GuestManager,
+    NodeCacheStorage,
+    InMemoryStorage,
+    RedisStorage 
+} from './src/utils/guest-manager.js';
+
+export default { 
+    OblienChat, 
+    ChatSession, 
+    GuestManager,
+    NodeCacheStorage,
+    InMemoryStorage,
+    RedisStorage 
+};

package/index.d.ts

@@ -0,0 +1,180 @@
+/**
+ * TypeScript definitions for oblien-core
+ */
+
+// ============ Client Types ============
+
+export interface OblienConfig {
+    apiKey: string;
+    apiSecret?: string;
+    baseURL?: string;
+    version?: string;
+}
+
+export class OblienClient {
+    constructor(config: OblienConfig);
+    
+    authenticate(): Promise<string>;
+    getAuthHeaders(): Promise<Record<string, string>>;
+    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>;
+    delete(path: string): Promise<any>;
+}
+
+// ============ Storage Adapters ============
+
+export interface StorageAdapter {
+    get(key: string): Promise<any>;
+    set(key: string, value: any, ttl?: number): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    getAll(pattern: string): Promise<any[]>;
+}
+
+export class NodeCacheStorage implements StorageAdapter {
+    constructor(ttl?: number);
+    
+    get(key: string): Promise<any>;
+    set(key: string, value: any, ttl?: number): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    getAll(pattern: string): Promise<any[]>;
+    getStats(): any;
+    clear(): void;
+}
+
+export class InMemoryStorage implements StorageAdapter {
+    get(key: string): Promise<any>;
+    set(key: string, value: any, ttl?: number): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    getAll(pattern: string): Promise<any[]>;
+}
+
+export class RedisStorage implements StorageAdapter {
+    constructor(redisClient: any);
+    
+    get(key: string): Promise<any>;
+    set(key: string, value: any, ttl?: number): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    getAll(pattern: string): Promise<any[]>;
+}
+
+// ============ Guest Manager ============
+
+export interface GuestManagerOptions {
+    storage?: StorageAdapter;
+    ttl?: number;
+    onGuestCreated?: (guest: Guest) => void;
+}
+
+export interface Guest {
+    id: string;
+    namespace: string;
+    ip: string;
+    isGuest: boolean;
+    createdAt: string;
+    lastSeen: string;
+    metadata: Record<string, any>;
+    sessions: string[];
+}
+
+export class GuestManager {
+    constructor(options?: GuestManagerOptions);
+    
+    generateGuestId(ip: string): string;
+    getOrCreateGuest(ip: string, metadata?: Record<string, any>): Promise<Guest>;
+    getGuest(guestId: string): Promise<Guest | null>;
+    updateGuest(guestId: string, updates: Partial<Guest>): Promise<Guest>;
+    addSession(guestId: string, sessionId: string): Promise<Guest>;
+    deleteGuest(guestId: string): Promise<boolean>;
+    getAllGuests(): Promise<Guest[]>;
+    cleanup(): Promise<number>;
+}
+
+// ============ Chat Session ============
+
+export interface SessionOptions {
+    client: OblienClient;
+    sessionId?: string;
+    agentId?: string;
+    workflowId?: string;
+    isGuest?: boolean;
+    namespace?: string;
+    workspace?: Record<string, any>;
+}
+
+export interface SessionData {
+    sessionId: string;
+    token: string;
+    agentId?: string;
+    workflowId?: string;
+    namespace?: string;
+}
+
+export class ChatSession {
+    constructor(options: SessionOptions);
+    
+    sessionId: string | null;
+    token: string | null;
+    
+    create(): Promise<SessionData>;
+    get(sessionId?: string): Promise<any>;
+    delete(sessionId?: string): Promise<any>;
+    list(options?: Record<string, any>): Promise<any[]>;
+}
+
+// ============ Chat Manager ============
+
+export interface ChatOptions {
+    guestManager?: GuestManager;
+    guestStorage?: StorageAdapter;
+    guestTTL?: number;
+}
+
+export interface CreateSessionOptions {
+    agentId: string;
+    workflowId?: string;
+    workspace?: Record<string, any>;
+}
+
+export interface CreateGuestSessionOptions {
+    ip: string;
+    agentId: string;
+    workflowId?: string;
+    metadata?: Record<string, any>;
+    workspace?: Record<string, any>;
+}
+
+export interface GuestSessionData extends SessionData {
+    guest: {
+        id: string;
+        namespace: string;
+        createdAt: string;
+    };
+}
+
+export class OblienChat {
+    constructor(client: OblienClient, options?: ChatOptions);
+    
+    createSession(options: CreateSessionOptions): Promise<SessionData>;
+    createGuestSession(options: CreateGuestSessionOptions): Promise<GuestSessionData>;
+    getGuestByIP(ip: string): Promise<Guest | null>;
+    getSession(sessionId: string): Promise<any>;
+    listSessions(options?: Record<string, any>): Promise<any[]>;
+    deleteSession(sessionId: string): Promise<any>;
+    getAllGuests(): Promise<Guest[]>;
+    cleanupGuests(): Promise<number>;
+}
+
+// ============ Exports ============
+
+declare const _default: {
+    OblienClient: typeof OblienClient;
+    OblienChat: typeof OblienChat;
+    ChatSession: typeof ChatSession;
+    GuestManager: typeof GuestManager;
+    NodeCacheStorage: typeof NodeCacheStorage;
+    InMemoryStorage: typeof InMemoryStorage;
+    RedisStorage: typeof RedisStorage;
+};
+
+export default _default;

package/index.js

@@ -0,0 +1,23 @@
+/**
+ * Oblien Core SDK
+ * Server-side SDK for Oblien AI Platform
+ */
+
+export { OblienClient } from './src/client.js';
+export { OblienChat, ChatSession } from './src/chat/index.js';
+export { 
+    GuestManager, 
+    NodeCacheStorage,
+    InMemoryStorage,
+    RedisStorage 
+} from './src/utils/guest-manager.js';
+
+export default {
+    OblienClient,
+    OblienChat,
+    ChatSession,
+    GuestManager,
+    NodeCacheStorage,
+    InMemoryStorage,
+    RedisStorage,
+};