chatly-sdk 0.0.5 → 0.0.6

package/examples/01-basic-chat/README.md

@@ -0,0 +1,61 @@
+# Basic Chat Example
+
+A simple 1:1 chat example using in-memory storage.
+
+## What You'll Learn
+
+- Creating users
+- Starting a chat session
+- Sending and receiving encrypted messages
+- Decrypting messages
+
+## Running the Example
+
+```bash
+npm install
+npm start
+```
+
+## Code Walkthrough
+
+This example demonstrates the core SDK functionality:
+
+1. **Initialize SDK** with in-memory stores
+2. **Create two users** (Alice and Bob)
+3. **Start a chat session** between them
+4. **Send encrypted messages** from Alice to Bob
+5. **Decrypt and read messages** as Bob
+
+All messages are end-to-end encrypted using ECDH + AES-256-GCM.
+
+## Output
+
+```
+🔐 Chatly SDK - Basic Chat Example
+==================================
+
+Creating users...
+✅ Created user: alice (ID: xxx)
+✅ Created user: bob (ID: xxx)
+
+Starting chat session...
+✅ Session created between alice and bob
+
+Alice sends messages...
+📤 Alice: Hello Bob!
+📤 Alice: How are you today?
+📤 Alice: This is end-to-end encrypted!
+
+Bob receives and decrypts messages...
+📨 Bob received: Hello Bob!
+📨 Bob received: How are you today?
+📨 Bob received: This is end-to-end encrypted!
+
+✅ All messages encrypted and decrypted successfully!
+```
+
+## Key Concepts
+
+- **In-Memory Storage**: No database required for testing
+- **E2E Encryption**: Messages encrypted on sender, decrypted on receiver
+- **Session Management**: Each conversation has a unique session

package/examples/01-basic-chat/index.js

@@ -0,0 +1,58 @@
+import { ChatSDK, InMemoryUserStore, InMemoryMessageStore, InMemoryGroupStore, LogLevel } from 'chatly-sdk';
+
+async function main() {
+  console.log('🔐 Chatly SDK - Basic Chat Example');
+  console.log('==================================\n');
+
+  // Initialize SDK with in-memory storage
+  const sdk = new ChatSDK({
+    userStore: new InMemoryUserStore(),
+    messageStore: new InMemoryMessageStore(),
+    groupStore: new InMemoryGroupStore(),
+    logLevel: LogLevel.NONE, // Disable logs for cleaner output
+  });
+
+  // Step 1: Create users
+  console.log('Creating users...');
+  const alice = await sdk.createUser('alice');
+  const bob = await sdk.createUser('bob');
+  console.log(`✅ Created user: ${alice.username} (ID: ${alice.id.substring(0, 8)}...)`);
+  console.log(`✅ Created user: ${bob.username} (ID: ${bob.id.substring(0, 8)}...)\n`);
+
+  // Step 2: Start a chat session
+  console.log('Starting chat session...');
+  const session = await sdk.startSession(alice, bob);
+  console.log(`✅ Session created between ${alice.username} and ${bob.username}\n`);
+
+  // Step 3: Alice sends messages
+  console.log('Alice sends messages...');
+  sdk.setCurrentUser(alice);
+  
+  const messages = [
+    'Hello Bob!',
+    'How are you today?',
+    'This is end-to-end encrypted!',
+  ];
+
+  for (const text of messages) {
+    await sdk.sendMessage(session, text);
+    console.log(`📤 Alice: ${text}`);
+  }
+  console.log();
+
+  // Step 4: Bob receives and decrypts messages
+  console.log('Bob receives and decrypts messages...');
+  sdk.setCurrentUser(bob);
+  
+  const receivedMessages = await sdk.getMessagesForUser(bob.id);
+  
+  for (const msg of receivedMessages) {
+    const plaintext = await sdk.decryptMessage(msg, bob);
+    console.log(`📨 Bob received: ${plaintext}`);
+  }
+  console.log();
+
+  console.log('✅ All messages encrypted and decrypted successfully!');
+}
+
+main().catch(console.error);

package/examples/01-basic-chat/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "chatly-sdk-basic-chat-example",
+  "version": "1.0.0",
+  "description": "Basic 1:1 chat example using Chatly SDK",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "chatly-sdk": "^0.0.5"
+  }
+}

package/examples/02-group-chat/README.md

@@ -0,0 +1,78 @@
+# Group Chat Example
+
+Multi-user encrypted group messaging.
+
+## What You'll Learn
+
+- Creating groups
+- Adding multiple members
+- Sending messages to groups
+- Group encryption
+- Retrieving group messages
+
+## Running the Example
+
+```bash
+npm install
+npm start
+```
+
+## How It Works
+
+This example demonstrates **group chat**:
+- Create a group with multiple members
+- All messages encrypted with group key
+- All members can send and receive
+- End-to-end encrypted group messaging
+
+## Output
+
+```
+👥 Chatly SDK - Group Chat Example
+==================================
+
+Creating users...
+✅ Alice created
+✅ Bob created
+✅ Charlie created
+
+Creating group...
+✅ Group created: Team Chat
+✅ Members: 3
+
+Alice sends to group...
+📤 Alice: Hello team!
+📤 Alice: Let's discuss the project
+
+Bob sends to group...
+📤 Bob: Sounds good!
+
+Charlie sends to group...
+📤 Charlie: I'm in!
+
+All members receive messages...
+📨 Bob received 4 messages
+📨 Charlie received 4 messages
+
+Decrypting messages...
+💬 Alice: Hello team!
+💬 Alice: Let's discuss the project
+💬 Bob: Sounds good!
+💬 Charlie: I'm in!
+
+✅ Group chat works perfectly!
+```
+
+## Key Features
+
+- **Multi-user**: 2-256 members per group
+- **Encrypted**: End-to-end encryption for all messages
+- **Scalable**: Same encryption performance regardless of group size
+- **Persistent**: Messages stored in database
+
+## Use Cases
+
+- **Team Chat** (Slack, Microsoft Teams)
+- **Family Groups** (WhatsApp groups)
+- **Community Channels**
+- **Project Collaboration**

package/examples/02-group-chat/index.js

@@ -0,0 +1,76 @@
+import { ChatSDK, InMemoryUserStore, InMemoryMessageStore, InMemoryGroupStore, LogLevel } from 'chatly-sdk';
+
+async function main() {
+  console.log('👥 Chatly SDK - Group Chat Example');
+  console.log('==================================\n');
+
+  // Initialize SDK
+  const sdk = new ChatSDK({
+    userStore: new InMemoryUserStore(),
+    messageStore: new InMemoryMessageStore(),
+    groupStore: new InMemoryGroupStore(),
+    logLevel: LogLevel.NONE,
+  });
+
+  // Create users
+  console.log('Creating users...');
+  const alice = await sdk.createUser('alice');
+  const bob = await sdk.createUser('bob');
+  const charlie = await sdk.createUser('charlie');
+  console.log('✅ Alice created');
+  console.log('✅ Bob created');
+  console.log('✅ Charlie created\n');
+
+  // Create group
+  console.log('Creating group...');
+  const group = await sdk.createGroup('Team Chat', [alice, bob, charlie]);
+  console.log(`✅ Group created: ${group.group.name}`);
+  console.log(`✅ Members: ${group.group.members.length}\n`);
+
+  // Alice sends messages to group
+  console.log('Alice sends to group...');
+  sdk.setCurrentUser(alice);
+  await sdk.sendMessage(group, 'Hello team!');
+  console.log('📤 Alice: Hello team!');
+  
+  await sdk.sendMessage(group, 'Let\'s discuss the project');
+  console.log('📤 Alice: Let\'s discuss the project\n');
+
+  // Bob sends to group
+  console.log('Bob sends to group...');
+  sdk.setCurrentUser(bob);
+  await sdk.sendMessage(group, 'Sounds good!');
+  console.log('📤 Bob: Sounds good!\n');
+
+  // Charlie sends to group
+  console.log('Charlie sends to group...');
+  sdk.setCurrentUser(charlie);
+  await sdk.sendMessage(group, 'I\'m in!');
+  console.log('📤 Charlie: I\'m in!\n');
+
+  // All members receive messages
+  console.log('All members receive messages...');
+  const bobMessages = await sdk.getMessagesForGroup(group.group.id);
+  const charlieMessages = await sdk.getMessagesForGroup(group.group.id);
+  console.log(`📨 Bob received ${bobMessages.length} messages`);
+  console.log(`📨 Charlie received ${charlieMessages.length} messages\n`);
+
+  // Decrypt and display messages
+  console.log('Decrypting messages...');
+  for (const msg of bobMessages) {
+    const plaintext = await sdk.decryptMessage(msg, bob);
+    const sender = msg.senderId === alice.id ? 'Alice' : 
+                   msg.senderId === bob.id ? 'Bob' : 'Charlie';
+    console.log(`💬 ${sender}: ${plaintext}`);
+  }
+  console.log();
+
+  console.log('✅ Group chat works perfectly!');
+  console.log('\n💡 Key Features:');
+  console.log('   - Multi-user (2-256 members)');
+  console.log('   - End-to-end encrypted');
+  console.log('   - All members can send/receive');
+  console.log('   - Messages stored in database');
+}
+
+main().catch(console.error);

package/examples/02-group-chat/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "chatly-sdk-group-chat-example",
+  "version": "1.0.0",
+  "description": "Group chat example using Chatly SDK",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "chatly-sdk": "^0.0.5"
+  }
+}

package/examples/03-offline-messaging/README.md

@@ -0,0 +1,73 @@
+# Offline Messaging Example
+
+Demonstrates asynchronous messaging without WebSocket (like email).
+
+## What You'll Learn
+
+- Messaging without real-time connection
+- Message persistence in database
+- Offline-first architecture
+- Message retrieval and synchronization
+
+## Running the Example
+
+```bash
+npm install
+npm start
+```
+
+## How It Works
+
+This example shows **asynchronous messaging** where:
+- No WebSocket connection required
+- Messages stored in database immediately
+- Users retrieve messages when they check
+- Works like email or traditional messaging
+
+## Code Walkthrough
+
+1. **No Transport Layer** - SDK initialized without WebSocket
+2. **Messages Stored** - All messages go directly to database
+3. **Pull-Based** - Users fetch messages when ready
+4. **Offline-First** - Works without internet connection
+
+## Output
+
+```
+📧 Chatly SDK - Offline Messaging Example
+=========================================
+
+Creating users...
+✅ Alice created
+✅ Bob created
+
+Alice sends messages (offline mode)...
+📤 Message queued: Hey Bob, check this out later!
+📤 Message queued: No rush to reply
+📤 Message queued: This works like email
+
+Bob checks messages later...
+📬 Bob has 3 new messages
+📨 Message 1: Hey Bob, check this out later!
+📨 Message 2: No rush to reply
+📨 Message 3: This works like email
+
+✅ Offline messaging works perfectly!
+```
+
+## Use Cases
+
+- **Email-like systems**
+- **Notification systems**
+- **Asynchronous team communication**
+- **IoT device messaging**
+- **Store-and-forward systems**
+
+## Key Difference from Live Chat
+
+| Feature | Offline Messaging | Live Chat |
+|---------|------------------|-----------|
+| Transport | None | WebSocket |
+| Delivery | Database | Real-time |
+| Retrieval | Pull (fetch) | Push (events) |
+| Use Case | Email-like | WhatsApp-like |

package/examples/03-offline-messaging/index.js

@@ -0,0 +1,80 @@
+import { ChatSDK, InMemoryUserStore, InMemoryMessageStore, InMemoryGroupStore, LogLevel } from 'chatly-sdk';
+
+async function main() {
+  console.log('📧 Chatly SDK - Offline Messaging Example');
+  console.log('=========================================\n');
+
+  // Initialize SDK WITHOUT transport (offline mode)
+  const sdk = new ChatSDK({
+    userStore: new InMemoryUserStore(),
+    messageStore: new InMemoryMessageStore(),
+    groupStore: new InMemoryGroupStore(),
+    // No transport = offline/asynchronous messaging
+    logLevel: LogLevel.NONE,
+  });
+
+  // Create users
+  console.log('Creating users...');
+  const alice = await sdk.createUser('alice');
+  const bob = await sdk.createUser('bob');
+  console.log('✅ Alice created');
+  console.log('✅ Bob created\n');
+
+  // Start session
+  const session = await sdk.startSession(alice, bob);
+
+  // Alice sends messages (offline mode)
+  console.log('Alice sends messages (offline mode)...');
+  sdk.setCurrentUser(alice);
+
+  const messages = [
+    'Hey Bob, check this out later!',
+    'No rush to reply',
+    'This works like email',
+  ];
+
+  for (const text of messages) {
+    await sdk.sendMessage(session, text);
+    console.log(`📤 Message queued: ${text}`);
+  }
+  console.log();
+
+  // Simulate time passing...
+  console.log('⏰ Time passes... Bob checks messages later...\n');
+
+  // Bob retrieves messages
+  console.log('Bob checks messages later...');
+  sdk.setCurrentUser(bob);
+  
+  const receivedMessages = await sdk.getMessagesForUser(bob.id);
+  console.log(`📬 Bob has ${receivedMessages.length} new messages`);
+  
+  for (let i = 0; i < receivedMessages.length; i++) {
+    const plaintext = await sdk.decryptMessage(receivedMessages[i], bob);
+    console.log(`📨 Message ${i + 1}: ${plaintext}`);
+  }
+  console.log();
+
+  // Bob replies (also offline)
+  console.log('Bob replies (also offline)...');
+  await sdk.sendMessage(session, 'Thanks Alice, got your messages!');
+  console.log('📤 Bob: Thanks Alice, got your messages!\n');
+
+  // Alice checks later
+  console.log('Alice checks messages later...');
+  sdk.setCurrentUser(alice);
+  
+  const aliceMessages = await sdk.getMessagesForUser(alice.id);
+  const bobReply = aliceMessages[aliceMessages.length - 1];
+  const replyText = await sdk.decryptMessage(bobReply, alice);
+  console.log(`📨 Alice received: ${replyText}\n`);
+
+  console.log('✅ Offline messaging works perfectly!');
+  console.log('\n💡 Key Points:');
+  console.log('   - No WebSocket connection needed');
+  console.log('   - Messages stored in database');
+  console.log('   - Users fetch messages when ready');
+  console.log('   - Works like email or async messaging');
+}
+
+main().catch(console.error);

package/examples/03-offline-messaging/package.json

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

package/examples/04-live-chat/README.md

@@ -0,0 +1,80 @@
+# Live Chat Example
+
+Real-time chat using WebSocket (WhatsApp-style).
+
+## What You'll Learn
+
+- Real-time messaging with WebSocket
+- Event-driven architecture
+- Connection state management
+- Instant message delivery
+
+## Prerequisites
+
+You need a WebSocket server running. See [`../10-websocket-server/`](../10-websocket-server/) for a simple server implementation.
+
+## Running the Example
+
+```bash
+# Terminal 1: Start WebSocket server
+cd ../10-websocket-server
+npm install
+npm start
+
+# Terminal 2: Run this example
+cd ../04-live-chat
+npm install
+npm start
+```
+
+## How It Works
+
+This example demonstrates **real-time messaging**:
+- WebSocket connection for instant delivery
+- Events for real-time UI updates
+- Automatic reconnection on disconnect
+- Message queue for offline scenarios
+
+## Output
+
+```
+💬 Chatly SDK - Live Chat Example
+=================================
+
+Connecting to WebSocket server...
+🟢 Connected to wss://localhost:8080
+
+Creating users...
+✅ Alice connected
+✅ Bob connected
+
+Setting up event listeners...
+✅ Event listeners ready
+
+Alice sends real-time messages...
+📤 Alice: Hi Bob! (sent instantly)
+📨 Bob received instantly: Hi Bob!
+
+📤 Alice: How's it going?
+📨 Bob received instantly: How's it going?
+
+📤 Alice: This is real-time!
+📨 Bob received instantly: This is real-time!
+
+✅ All messages delivered in real-time!
+```
+
+## Key Features
+
+- **Instant Delivery**: Messages delivered immediately via WebSocket
+- **Event-Driven**: Real-time events for UI updates
+- **Auto-Reconnect**: Automatically reconnects if connection drops
+- **Message Queue**: Queues messages if offline, sends when reconnected
+
+## Use Cases
+
+- **Messaging Apps** (WhatsApp, Telegram)
+- **Live Customer Support**
+- **Team Collaboration** (Slack, Discord)
+- **Gaming Chat**
+- **Social Media DMs**

package/examples/04-live-chat/index.js

@@ -0,0 +1,114 @@
+import { 
+  ChatSDK, 
+  InMemoryUserStore, 
+  InMemoryMessageStore, 
+  InMemoryGroupStore,
+  WebSocketClient,
+  EVENTS,
+  ConnectionState,
+  LogLevel 
+} from 'chatly-sdk';
+
+async function main() {
+  console.log('💬 Chatly SDK - Live Chat Example');
+  console.log('=================================\n');
+
+  // Create WebSocket transport for real-time communication
+  console.log('Connecting to WebSocket server...');
+  const transport = new WebSocketClient('ws://localhost:8080');
+
+  // Initialize SDK with WebSocket transport
+  const sdk = new ChatSDK({
+    userStore: new InMemoryUserStore(),
+    messageStore: new InMemoryMessageStore(),
+    groupStore: new InMemoryGroupStore(),
+    transport, // Add WebSocket for real-time
+    logLevel: LogLevel.NONE,
+  });
+
+  // Listen for connection state changes
+  sdk.on(EVENTS.CONNECTION_STATE_CHANGED, (state) => {
+    switch (state) {
+      case ConnectionState.CONNECTED:
+        console.log('🟢 Connected to WebSocket server');
+        break;
+      case ConnectionState.CONNECTING:
+        console.log('🟡 Connecting...');
+        break;
+      case ConnectionState.DISCONNECTED:
+        console.log('🔴 Disconnected');
+        break;
+      case ConnectionState.RECONNECTING:
+        console.log('🟡 Reconnecting...');
+        break;
+    }
+  });
+
+  // Create users
+  console.log('\nCreating users...');
+  const alice = await sdk.createUser('alice');
+  const bob = await sdk.createUser('bob');
+  console.log('✅ Alice created');
+  console.log('✅ Bob created\n');
+
+  // Start session
+  const session = await sdk.startSession(alice, bob);
+
+  // Set up event listeners for real-time updates
+  console.log('Setting up event listeners...');
+  
+  sdk.on(EVENTS.MESSAGE_SENT, (message) => {
+    console.log(`✅ Message sent (ID: ${message.id.substring(0, 8)}...)`);
+  });
+
+  sdk.on(EVENTS.MESSAGE_RECEIVED, async (message) => {
+    const currentUser = sdk.getCurrentUser();
+    if (currentUser) {
+      const plaintext = await sdk.decryptMessage(message, currentUser);
+      console.log(`📨 ${currentUser.username} received instantly: ${plaintext}`);
+    }
+  });
+
+  sdk.on(EVENTS.MESSAGE_FAILED, (message, error) => {
+    console.error(`❌ Message failed: ${error.message}`);
+  });
+
+  console.log('✅ Event listeners ready\n');
+
+  // Wait for connection
+  await new Promise(resolve => setTimeout(resolve, 1000));
+
+  // Alice sends real-time messages
+  console.log('Alice sends real-time messages...');
+  sdk.setCurrentUser(alice);
+
+  const messages = [
+    'Hi Bob! (sent instantly)',
+    'How\'s it going?',
+    'This is real-time!',
+  ];
+
+  for (const text of messages) {
+    await sdk.sendMessage(session, text);
+    console.log(`📤 Alice: ${text}`);
+    await new Promise(resolve => setTimeout(resolve, 500)); // Small delay for demo
+  }
+
+  console.log();
+
+  // Wait a bit for all messages to be received
+  await new Promise(resolve => setTimeout(resolve, 1000));
+
+  console.log('✅ All messages delivered in real-time!');
+  console.log('\n💡 Key Features:');
+  console.log('   - Instant delivery via WebSocket');
+  console.log('   - Real-time events for UI updates');
+  console.log('   - Automatic reconnection');
+  console.log('   - Message queue for offline scenarios');
+
+  // Disconnect
+  await sdk.disconnect();
+  console.log('\n🔌 Disconnected from server');
+}
+
+main().catch(console.error);

package/examples/04-live-chat/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "chatly-sdk-live-chat-example",
+  "version": "1.0.0",
+  "description": "Real-time live chat example using Chatly SDK with WebSocket",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "chatly-sdk": "^0.0.5"
+  }
+}