chatly-sdk 0.0.5 → 0.0.6

package/examples/05-hybrid-messaging/README.md

@@ -0,0 +1,71 @@
+# Hybrid Messaging Example
+
+Combines real-time and offline messaging (Slack/Instagram-style).
+
+## What You'll Learn
+
+- Hybrid online/offline messaging
+- Message queue with automatic retry
+- Graceful degradation
+- Best of both worlds
+
+## Running the Example
+
+```bash
+npm install
+npm start
+```
+
+## How It Works
+
+This example demonstrates **hybrid messaging**:
+- Real-time delivery when online
+- Automatic queueing when offline
+- Messages sent when reconnected
+- Seamless user experience
+
+## Output
+
+```
+🔄 Chatly SDK - Hybrid Messaging Example
+========================================
+
+Initializing hybrid SDK...
+✅ SDK ready (online + offline support)
+
+Creating users...
+✅ Alice and Bob created
+
+Scenario 1: Online messaging (real-time)
+🟢 Connected
+📤 Alice: Hey! (delivered instantly)
+📨 Bob received: Hey!
+
+Scenario 2: Offline messaging (queued)
+🔴 Simulating disconnect...
+📤 Alice: Are you there? (queued)
+📤 Alice: I'll wait for you (queued)
+⏳ 2 messages in queue
+
+Scenario 3: Reconnection (auto-send)
+🟢 Reconnected!
+✅ Sending queued messages...
+📨 Bob received: Are you there?
+📨 Bob received: I'll wait for you
+
+✅ Hybrid messaging works perfectly!
+```
+
+## Key Features
+
+- **Smart Delivery**: Real-time when online, queued when offline
+- **Automatic Queue**: Messages queued during disconnection
+- **Auto-Retry**: Failed messages retry automatically
+- **Seamless UX**: Users don't need to worry about connection state
+
+## Use Cases
+
+- **Social Media DMs** (Instagram, Twitter)
+- **Team Chat** (Slack, Microsoft Teams)
+- **Mobile Apps** (intermittent connectivity)
+- **Progressive Web Apps**

package/examples/05-hybrid-messaging/index.js

@@ -0,0 +1,106 @@
+import { 
+  ChatSDK, 
+  InMemoryUserStore, 
+  InMemoryMessageStore, 
+  InMemoryGroupStore,
+  MemoryTransport,
+  EVENTS,
+  ConnectionState,
+  LogLevel 
+} from 'chatly-sdk';
+
+async function main() {
+  console.log('🔄 Chatly SDK - Hybrid Messaging Example');
+  console.log('========================================\n');
+
+  // Use MemoryTransport for demo (simulates WebSocket)
+  const transport = new MemoryTransport();
+
+  console.log('Initializing hybrid SDK...');
+  const sdk = new ChatSDK({
+    userStore: new InMemoryUserStore(),
+    messageStore: new InMemoryMessageStore(),
+    groupStore: new InMemoryGroupStore(),
+    transport, // Hybrid: works online AND offline
+    logLevel: LogLevel.NONE,
+  });
+
+  // Track connection state
+  let connectionState = ConnectionState.DISCONNECTED;
+  sdk.on(EVENTS.CONNECTION_STATE_CHANGED, (state) => {
+    connectionState = state;
+    const emoji = state === ConnectionState.CONNECTED ? '🟢' : '🔴';
+    console.log(`${emoji} Connection: ${state}`);
+  });
+
+  console.log('✅ SDK ready (online + offline support)\n');
+
+  // Create users
+  console.log('Creating users...');
+  const alice = await sdk.createUser('alice');
+  const bob = await sdk.createUser('bob');
+  console.log('✅ Alice and Bob created\n');
+
+  const session = await sdk.startSession(alice, bob);
+
+  // Scenario 1: Online messaging (real-time)
+  console.log('Scenario 1: Online messaging (real-time)');
+  sdk.setCurrentUser(alice);
+  await sdk.setCurrentUser(alice); // This connects the transport
+
+  await new Promise(resolve => setTimeout(resolve, 500));
+
+  await sdk.sendMessage(session, 'Hey!');
+  console.log('📤 Alice: Hey! (delivered instantly)');
+
+  sdk.setCurrentUser(bob);
+  const messages1 = await sdk.getMessagesForUser(bob.id);
+  const text1 = await sdk.decryptMessage(messages1[0], bob);
+  console.log(`📨 Bob received: ${text1}\n`);
+
+  // Scenario 2: Offline messaging (queued)
+  console.log('Scenario 2: Offline messaging (queued)');
+  console.log('🔴 Simulating disconnect...');
+  await sdk.disconnect();
+
+  sdk.setCurrentUser(alice);
+  await sdk.sendMessage(session, 'Are you there?');
+  console.log('📤 Alice: Are you there? (queued)');
+  
+  await sdk.sendMessage(session, 'I\'ll wait for you');
+  console.log('📤 Alice: I\'ll wait for you (queued)');
+
+  const queueStatus = sdk.getQueueStatus();
+  console.log(`⏳ ${queueStatus.pending} messages in queue\n`);
+
+  // Scenario 3: Reconnection (auto-send queued messages)
+  console.log('Scenario 3: Reconnection (auto-send)');
+  console.log('🟢 Reconnecting...');
+  
+  await sdk.reconnect();
+  await new Promise(resolve => setTimeout(resolve, 500));
+
+  console.log('✅ Sending queued messages...');
+
+  sdk.setCurrentUser(bob);
+  const messages2 = await sdk.getMessagesForUser(bob.id);
+  
+  // Get the last 2 messages
+  const recentMessages = messages2.slice(-2);
+  for (const msg of recentMessages) {
+    const text = await sdk.decryptMessage(msg, bob);
+    console.log(`📨 Bob received: ${text}`);
+  }
+
+  console.log();
+  console.log('✅ Hybrid messaging works perfectly!');
+  console.log('\n💡 Key Features:');
+  console.log('   - Real-time when online');
+  console.log('   - Queued when offline');
+  console.log('   - Auto-send on reconnect');
+  console.log('   - Seamless user experience');
+
+  await sdk.disconnect();
+}
+
+main().catch(console.error);

package/examples/05-hybrid-messaging/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "chatly-sdk-hybrid-messaging-example",
+  "version": "1.0.0",
+  "description": "Hybrid online/offline messaging example using Chatly SDK",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "chatly-sdk": "^0.0.5"
+  }
+}

package/examples/06-postgresql-integration/README.md

@@ -0,0 +1,101 @@
+# PostgreSQL Integration Example
+
+Complete example of using Chatly SDK with PostgreSQL database.
+
+## What You'll Learn
+
+- Implementing custom storage adapters
+- PostgreSQL schema design
+- Database transactions
+- Connection pooling
+- Production-ready setup
+
+## Prerequisites
+
+- PostgreSQL installed and running
+- Database created: `chatly`
+
+## Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Create database
+createdb chatly
+
+# Run schema migration
+psql chatly < schema.sql
+
+# Update database credentials in index.js
+# Then run
+npm start
+```
+
+## Database Schema
+
+See [`schema.sql`](./schema.sql) for the complete schema:
+- `users` table
+- `messages` table
+- `groups` table
+- `group_members` table
+- Indexes for performance
+
+## Code Structure
+
+```
+06-postgresql-integration/
+├── README.md
+├── package.json
+├── schema.sql          # Database schema
+├── adapters/
+│   ├── userStore.js    # User storage adapter
+│   ├── messageStore.js # Message storage adapter
+│   └── groupStore.js   # Group storage adapter
+└── index.js            # Main example
+```
+
+## Output
+
+```
+🗄️  Chatly SDK - PostgreSQL Integration
+======================================
+
+Connecting to PostgreSQL...
+✅ Connected to database: chatly
+
+Creating users in database...
+✅ Alice saved to PostgreSQL
+✅ Bob saved to PostgreSQL
+
+Sending encrypted messages...
+📤 Message 1 saved to database
+📤 Message 2 saved to database
+📤 Message 3 saved to database
+
+Retrieving messages from database...
+📨 Retrieved 3 messages from PostgreSQL
+📨 Decrypted: Hello from PostgreSQL!
+📨 Decrypted: Messages are persisted
+📨 Decrypted: Even after restart!
+
+✅ PostgreSQL integration works!
+```
+
+## Production Features
+
+- ✅ Connection pooling
+- ✅ Prepared statements (SQL injection protection)
+- ✅ Transactions for data integrity
+- ✅ Indexes for performance
+- ✅ Error handling
+- ✅ Graceful shutdown
+
+## Adapting for Other Databases
+
+This pattern works for any SQL database:
+- **MySQL**: Change `pg` to `mysql2`
+- **SQLite**: Use `better-sqlite3`
+- **SQL Server**: Use `mssql`
+
+Just implement the same adapter interfaces!

package/examples/06-postgresql-integration/adapters/groupStore.js

@@ -0,0 +1,73 @@
+export class PostgreSQLGroupStore {
+  constructor(pool) {
+    this.pool = pool;
+  }
+
+  async create(group) {
+    const client = await this.pool.connect();
+    try {
+      await client.query('BEGIN');
+      
+      // Insert group
+      await client.query(
+        'INSERT INTO groups (id, name, shared_secret) VALUES ($1, $2, $3)',
+        [group.id, group.name, group.sharedSecret]
+      );
+      
+      // Insert members
+      for (const userId of group.members) {
+        await client.query(
+          'INSERT INTO group_members (group_id, user_id) VALUES ($1, $2)',
+          [group.id, userId]
+        );
+      }
+      
+      await client.query('COMMIT');
+      return group;
+    } catch (error) {
+      await client.query('ROLLBACK');
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
+  async findById(id) {
+    const groupResult = await this.pool.query(
+      'SELECT id, name, shared_secret as "sharedSecret" FROM groups WHERE id = $1',
+      [id]
+    );
+    
+    if (groupResult.rows.length === 0) return undefined;
+    
+    const membersResult = await this.pool.query(
+      'SELECT user_id FROM group_members WHERE group_id = $1',
+      [id]
+    );
+    
+    return {
+      ...groupResult.rows[0],
+      members: membersResult.rows.map(row => row.user_id)
+    };
+  }
+
+  async list() {
+    const groupsResult = await this.pool.query(
+      'SELECT id, name, shared_secret as "sharedSecret" FROM groups'
+    );
+    
+    const groups = [];
+    for (const group of groupsResult.rows) {
+      const membersResult = await this.pool.query(
+        'SELECT user_id FROM group_members WHERE group_id = $1',
+        [group.id]
+      );
+      groups.push({
+        ...group,
+        members: membersResult.rows.map(row => row.user_id)
+      });
+    }
+    
+    return groups;
+  }
+}

package/examples/06-postgresql-integration/adapters/messageStore.js

@@ -0,0 +1,47 @@
+export class PostgreSQLMessageStore {
+  constructor(pool) {
+    this.pool = pool;
+  }
+
+  async create(message) {
+    await this.pool.query(
+      `INSERT INTO messages (id, sender_id, receiver_id, group_id, ciphertext, iv, timestamp, status) 
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+      [
+        message.id,
+        message.senderId,
+        message.receiverId || null,
+        message.groupId || null,
+        message.ciphertext,
+        message.iv,
+        message.timestamp,
+        message.status || 'pending'
+      ]
+    );
+    return message;
+  }
+
+  async listByUser(userId) {
+    const result = await this.pool.query(
+      `SELECT id, sender_id as "senderId", receiver_id as "receiverId", 
+              group_id as "groupId", ciphertext, iv, timestamp, status
+       FROM messages 
+       WHERE receiver_id = $1 OR sender_id = $1 
+       ORDER BY timestamp ASC`,
+      [userId]
+    );
+    return result.rows;
+  }
+
+  async listByGroup(groupId) {
+    const result = await this.pool.query(
+      `SELECT id, sender_id as "senderId", receiver_id as "receiverId", 
+              group_id as "groupId", ciphertext, iv, timestamp, status
+       FROM messages 
+       WHERE group_id = $1 
+       ORDER BY timestamp ASC`,
+      [groupId]
+    );
+    return result.rows;
+  }
+}

package/examples/06-postgresql-integration/adapters/userStore.js

@@ -0,0 +1,40 @@
+export class PostgreSQLUserStore {
+  constructor(pool) {
+    this.pool = pool;
+  }
+
+  async create(user) {
+    await this.pool.query(
+      `INSERT INTO users (id, username, public_key, private_key) 
+       VALUES ($1, $2, $3, $4)`,
+      [user.id, user.username, user.publicKey, user.privateKey]
+    );
+    return user;
+  }
+
+  async findById(id) {
+    const result = await this.pool.query(
+      `SELECT id, username, public_key as "publicKey", private_key as "privateKey" 
+       FROM users WHERE id = $1`,
+      [id]
+    );
+    return result.rows[0];
+  }
+
+  async save(user) {
+    await this.pool.query(
+      `UPDATE users 
+       SET username = $1, public_key = $2 
+       WHERE id = $3`,
+      [user.username, user.publicKey, user.id]
+    );
+  }
+
+  async list() {
+    const result = await this.pool.query(
+      `SELECT id, username, public_key as "publicKey", private_key as "privateKey" 
+       FROM users`
+    );
+    return result.rows;
+  }
+}

package/examples/06-postgresql-integration/index.js

@@ -0,0 +1,92 @@
+import pkg from 'pg';
+const { Pool } = pkg;
+import { ChatSDK, LogLevel } from 'chatly-sdk';
+import { PostgreSQLUserStore } from './adapters/userStore.js';
+import { PostgreSQLMessageStore } from './adapters/messageStore.js';
+import { PostgreSQLGroupStore } from './adapters/groupStore.js';
+
+async function main() {
+  console.log('🗄️  Chatly SDK - PostgreSQL Integration');
+  console.log('======================================\n');
+
+  // Create PostgreSQL connection pool
+  console.log('Connecting to PostgreSQL...');
+  const pool = new Pool({
+    host: 'localhost',
+    port: 5432,
+    database: 'chatly',
+    user: 'postgres',      // Update with your credentials
+    password: 'password',  // Update with your credentials
+    max: 20,
+    min: 5,
+  });
+
+  // Test connection
+  try {
+    await pool.query('SELECT NOW()');
+    console.log('✅ Connected to database: chatly\n');
+  } catch (error) {
+    console.error('❌ Database connection failed:', error.message);
+    console.log('\n💡 Make sure PostgreSQL is running and database exists:');
+    console.log('   createdb chatly');
+    console.log('   psql chatly < schema.sql');
+    process.exit(1);
+  }
+
+  // Initialize SDK with PostgreSQL adapters
+  const sdk = new ChatSDK({
+    userStore: new PostgreSQLUserStore(pool),
+    messageStore: new PostgreSQLMessageStore(pool),
+    groupStore: new PostgreSQLGroupStore(pool),
+    logLevel: LogLevel.NONE,
+  });
+
+  // Create users
+  console.log('Creating users in database...');
+  const alice = await sdk.createUser('alice-pg');
+  const bob = await sdk.createUser('bob-pg');
+  console.log('✅ Alice saved to PostgreSQL');
+  console.log('✅ Bob saved to PostgreSQL\n');
+
+  // Start session
+  const session = await sdk.startSession(alice, bob);
+
+  // Send messages
+  console.log('Sending encrypted messages...');
+  sdk.setCurrentUser(alice);
+  
+  await sdk.sendMessage(session, 'Hello from PostgreSQL!');
+  console.log('📤 Message 1 saved to database');
+  
+  await sdk.sendMessage(session, 'Messages are persisted');
+  console.log('📤 Message 2 saved to database');
+  
+  await sdk.sendMessage(session, 'Even after restart!');
+  console.log('📤 Message 3 saved to database\n');
+
+  // Retrieve messages
+  console.log('Retrieving messages from database...');
+  sdk.setCurrentUser(bob);
+  
+  const messages = await sdk.getMessagesForUser(bob.id);
+  console.log(`📨 Retrieved ${messages.length} messages from PostgreSQL`);
+  
+  for (const msg of messages) {
+    const plaintext = await sdk.decryptMessage(msg, bob);
+    console.log(`📨 Decrypted: ${plaintext}`);
+  }
+  console.log();
+
+  console.log('✅ PostgreSQL integration works!');
+  console.log('\n💡 Key Features:');
+  console.log('   - Messages persisted in PostgreSQL');
+  console.log('   - Connection pooling for performance');
+  console.log('   - Transactions for data integrity');
+  console.log('   - Indexes for fast queries');
+
+  // Cleanup
+  await pool.end();
+  console.log('\n🔌 Database connection closed');
+}
+
+main().catch(console.error);

package/examples/06-postgresql-integration/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "chatly-sdk-postgresql-integration",
+  "version": "1.0.0",
+  "description": "PostgreSQL database integration example for Chatly SDK",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "chatly-sdk": "^0.0.5",
+    "pg": "^8.11.3"
+  }
+}

package/examples/06-postgresql-integration/schema.sql

@@ -0,0 +1,58 @@
+-- Chatly SDK PostgreSQL Schema
+
+-- Users table
+CREATE TABLE IF NOT EXISTS users (
+  id VARCHAR(255) PRIMARY KEY,
+  username VARCHAR(50) NOT NULL UNIQUE,
+  public_key TEXT NOT NULL,
+  private_key TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Messages table
+CREATE TABLE IF NOT EXISTS messages (
+  id VARCHAR(255) PRIMARY KEY,
+  sender_id VARCHAR(255) NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  receiver_id VARCHAR(255) REFERENCES users(id) ON DELETE CASCADE,
+  group_id VARCHAR(255),
+  ciphertext TEXT NOT NULL,
+  iv VARCHAR(255) NOT NULL,
+  timestamp BIGINT NOT NULL,
+  status VARCHAR(20) DEFAULT 'pending',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Groups table
+CREATE TABLE IF NOT EXISTS groups (
+  id VARCHAR(255) PRIMARY KEY,
+  name VARCHAR(100) NOT NULL,
+  shared_secret TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Group members table
+CREATE TABLE IF NOT EXISTS group_members (
+  group_id VARCHAR(255) NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
+  user_id VARCHAR(255) NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  joined_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (group_id, user_id)
+);
+
+-- Indexes for performance
+CREATE INDEX IF NOT EXISTS idx_messages_receiver ON messages(receiver_id, timestamp);
+CREATE INDEX IF NOT EXISTS idx_messages_group ON messages(group_id, timestamp);
+CREATE INDEX IF NOT EXISTS idx_messages_sender ON messages(sender_id);
+CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
+
+-- Update timestamp trigger
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = CURRENT_TIMESTAMP;
+    RETURN NEW;
+END;
+$$ language 'plpgsql';
+
+CREATE TRIGGER update_users_updated_at BEFORE UPDATE ON users
+FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

package/examples/08-customer-support/README.md

@@ -0,0 +1,70 @@
+# Customer Support Chat Example
+
+Real-world customer support system with live chat and offline fallback.
+
+## What You'll Learn
+
+- Building a customer support chat system
+- Agent availability management
+- Offline message handling
+- Queue management for support tickets
+
+## Running the Example
+
+```bash
+npm install
+npm start
+```
+
+## How It Works
+
+This example simulates a **customer support system**:
+- Customers can send messages anytime
+- Messages queued if no agents online
+- Agents see messages when they come online
+- Real-time chat when both are online
+
+## Output
+
+```
+🎧 Chatly SDK - Customer Support Example
+========================================
+
+Setting up support system...
+✅ Support agent created
+✅ Customer created
+
+Scenario 1: Customer sends message (agent offline)
+📝 Customer: I need help with my order
+⏳ Message queued (no agents available)
+
+Scenario 2: Agent comes online
+🟢 Agent online
+📬 Agent has 1 pending message
+📨 Agent sees: I need help with my order
+
+Scenario 3: Live chat (both online)
+💬 Real-time conversation started
+📤 Agent: Hi! How can I help?
+📨 Customer received: Hi! How can I help?
+📤 Customer: My order #12345 is delayed
+📨 Agent received: My order #12345 is delayed
+📤 Agent: Let me check that for you
+📨 Customer received: Let me check that for you
+
+✅ Support system works perfectly!
+```
+
+## Features
+
+- **24/7 Availability**: Customers can message anytime
+- **Offline Queue**: Messages queued when agents offline
+- **Real-time**: Live chat when agents available
+- **Message History**: Full conversation history
+
+## Use Cases
+
+- **Customer Support** (Zendesk, Intercom-style)
+- **Help Desk Systems**
+- **Live Chat Widgets**
+- **Support Ticketing**