chatly-sdk 1.0.0 → 2.0.0

package/examples/08-customer-support/index.js

@@ -0,0 +1,104 @@
+import { 
+  ChatSDK, 
+  InMemoryUserStore, 
+  InMemoryMessageStore, 
+  InMemoryGroupStore,
+  MemoryTransport,
+  EVENTS,
+  LogLevel 
+} from 'chatly-sdk';
+
+async function main() {
+  console.log('🎧 Chatly SDK - Customer Support Example');
+  console.log('========================================\n');
+
+  // Initialize support system
+  const transport = new MemoryTransport();
+  const sdk = new ChatSDK({
+    userStore: new InMemoryUserStore(),
+    messageStore: new InMemoryMessageStore(),
+    groupStore: new InMemoryGroupStore(),
+    transport,
+    logLevel: LogLevel.NONE,
+  });
+
+  console.log('Setting up support system...');
+  
+  // Create support agent and customer
+  const agent = await sdk.createUser('support-agent');
+  const customer = await sdk.createUser('customer-john');
+  console.log('✅ Support agent created');
+  console.log('✅ Customer created\n');
+
+  // Create support session
+  const session = await sdk.startSession(customer, agent);
+
+  // Scenario 1: Customer sends message (agent offline)
+  console.log('Scenario 1: Customer sends message (agent offline)');
+  sdk.setCurrentUser(customer);
+  
+  await sdk.sendMessage(session, 'I need help with my order');
+  console.log('📝 Customer: I need help with my order');
+  console.log('⏳ Message queued (no agents available)\n');
+
+  await new Promise(resolve => setTimeout(resolve, 1000));
+
+  // Scenario 2: Agent comes online and sees pending messages
+  console.log('Scenario 2: Agent comes online');
+  sdk.setCurrentUser(agent);
+  await sdk.setCurrentUser(agent); // Connect agent
+  
+  console.log('🟢 Agent online');
+  
+  const pendingMessages = await sdk.getMessagesForUser(agent.id);
+  console.log(`📬 Agent has ${pendingMessages.length} pending message(s)`);
+  
+  for (const msg of pendingMessages) {
+    const text = await sdk.decryptMessage(msg, agent);
+    console.log(`📨 Agent sees: ${text}`);
+  }
+  console.log();
+
+  // Scenario 3: Live chat (both online)
+  console.log('Scenario 3: Live chat (both online)');
+  console.log('💬 Real-time conversation started\n');
+
+  // Set up real-time event listeners
+  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: ${plaintext}`);
+    }
+  });
+
+  // Agent responds
+  sdk.setCurrentUser(agent);
+  await sdk.sendMessage(session, 'Hi! How can I help?');
+  console.log('📤 Agent: Hi! How can I help?');
+  await new Promise(resolve => setTimeout(resolve, 300));
+
+  // Customer replies
+  sdk.setCurrentUser(customer);
+  await sdk.sendMessage(session, 'My order #12345 is delayed');
+  console.log('📤 Customer: My order #12345 is delayed');
+  await new Promise(resolve => setTimeout(resolve, 300));
+
+  // Agent helps
+  sdk.setCurrentUser(agent);
+  await sdk.sendMessage(session, 'Let me check that for you');
+  console.log('📤 Agent: Let me check that for you');
+  await new Promise(resolve => setTimeout(resolve, 300));
+
+  console.log();
+  console.log('✅ Support system works perfectly!');
+  console.log('\n💡 Key Features:');
+  console.log('   - 24/7 availability (customers message anytime)');
+  console.log('   - Offline queue (messages saved for agents)');
+  console.log('   - Real-time chat when both online');
+  console.log('   - Full conversation history');
+
+  await sdk.disconnect();
+}
+
+main().catch(console.error);

package/examples/08-customer-support/package.json

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

package/examples/README.md

@@ -0,0 +1,105 @@
+# Chatly SDK - Examples
+
+This directory contains practical examples demonstrating different use cases for the Chatly SDK.
+
+## 📚 Examples
+
+### 1. [Basic Chat](./01-basic-chat)
+**Difficulty**: Beginner  
+**Topics**: User creation, sessions, encryption, message sending
+
+Simple 1:1 encrypted chat between two users.
+
+---
+
+### 2. [Group Chat](./02-group-chat)
+**Difficulty**: Beginner  
+**Topics**: Group creation, multi-user messaging, group encryption
+
+Multi-user encrypted group messaging with 3+ participants.
+
+---
+
+### 3. [Offline Messaging](./03-offline-messaging)
+Asynchronous messaging without WebSocket
+
+### 2. **Real-time Examples**
+- [`04-live-chat/`](./04-live-chat/) - Live chat with WebSocket (WhatsApp-style)
+- [`05-hybrid-messaging/`](./05-hybrid-messaging/) - Hybrid online/offline messaging
+
+### 3. **Database Integration**
+- [`06-postgresql-integration/`](./06-postgresql-integration/) - PostgreSQL storage adapter
+- [`07-mongodb-integration/`](./07-mongodb-integration/) - MongoDB storage adapter
+
+### 4. **Real-world Applications**
+- [`08-customer-support/`](./08-customer-support/) - Customer support chat system
+- [`09-react-chat-app/`](./09-react-chat-app/) - Full React chat application
+- [`10-websocket-server/`](./10-websocket-server/) - Node.js WebSocket server
+
+## 🚀 Quick Start
+
+Each example includes:
+- ✅ Complete source code
+- ✅ README with setup instructions
+- ✅ package.json for dependencies
+- ✅ Comments explaining key concepts
+
+### Running an Example
+
+```bash
+# Navigate to an example
+cd examples/01-basic-chat
+
+# Install dependencies
+npm install
+
+# Run the example
+npm start
+```
+
+## 📚 Learning Path
+
+**Beginner**: Start here
+1. `01-basic-chat` - Learn the basics
+2. `02-group-chat` - Understand group messaging
+3. `03-offline-messaging` - See how offline works
+
+**Intermediate**: Real-time features
+4. `04-live-chat` - Add WebSocket support
+5. `05-hybrid-messaging` - Combine online/offline
+
+**Advanced**: Production setup
+6. `06-postgresql-integration` - Database persistence
+7. `08-customer-support` - Real-world application
+8. `09-react-chat-app` - Full frontend integration
+
+## 🎯 Use Case Guide
+
+| Use Case | Example | Description |
+|----------|---------|-------------|
+| **Messaging App** | `04-live-chat` | WhatsApp-style real-time chat |
+| **Customer Support** | `08-customer-support` | Live support with offline fallback |
+| **Team Collaboration** | `02-group-chat` + `04-live-chat` | Slack-style team chat |
+| **Social Media DMs** | `05-hybrid-messaging` | Instagram-style direct messages |
+| **Email-like System** | `03-offline-messaging` | Asynchronous messaging |
+
+## 💡 Key Concepts Demonstrated
+
+- ✅ **End-to-end encryption** - All examples use E2E encryption
+- ✅ **Message queue** - Automatic retry and offline support
+- ✅ **Event handling** - Real-time UI updates
+- ✅ **Database integration** - PostgreSQL and MongoDB
+- ✅ **WebSocket** - Real-time bidirectional communication
+- ✅ **React integration** - Hooks and context providers
+
+## 🔧 Prerequisites
+
+- Node.js >= 16.x
+- npm >= 8.x
+- (Optional) PostgreSQL or MongoDB for database examples
+
+## 📞 Need Help?
+
+- Check the main [README](../README.md)
+- Read [CONTRIBUTING.md](../CONTRIBUTING.md)
+- Open an [issue](https://github.com/bharath-arch/chatly-sdk/issues)

package/jest.config.cjs

@@ -0,0 +1,28 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/test'],
+  testMatch: ['**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      tsconfig: 'tsconfig.test.json',
+    }],
+  },
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/**/index.ts',
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 70,
+      functions: 70,
+      lines: 70,
+      statements: 70,
+    },
+  },
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+};

package/package.json

@@ -1,19 +1,23 @@
 {
   "name": "chatly-sdk",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsup src/index.ts --dts --format esm",
     "start": "ts-node src/index.ts",
-    "test": "ts-node test/crypto.test.ts"
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
   },
-
   "publishConfig": {
     "access": "public"
   },
-
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bharath-arch/chatly-sdk.git"
+  },
   "keywords": [
     "chat",
     "sdk",
@@ -23,13 +27,18 @@
     "whatsapp"
   ],
   "author": "",
-  "license": "ISC",
+  "license": "MIT",
   "description": "Production-ready end-to-end encrypted chat SDK with WhatsApp-style features",
   "dependencies": {
-    "buffer": "^6.0.3"
+    "@aws-sdk/client-s3": "^3.958.0",
+    "buffer": "^6.0.3",
+    "events": "^3.3.0"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.14",
     "@types/node": "^24.10.1",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.0.0",
     "typescript": "^5.9.3"

package/src/chat/ChatSession.ts

@@ -1,8 +1,11 @@
 import type { User } from "../models/user.js";
 import type { Message } from "../models/message.js";
-import { deriveSharedSecret, encryptMessage, decryptMessage } from "../crypto/e2e.js";
+import type { MediaAttachment } from "../models/mediaTypes.js";
+import { deriveSharedSecret, deriveLegacySharedSecret, encryptMessage, decryptMessage } from "../crypto/e2e.js";
 import type { KeyPair } from "../crypto/keys.js";
 import { generateUUID } from "../crypto/uuid.js";
+import type { StorageProvider } from "../storage/adapters.js";
+import { logger } from "../utils/logger.js";
 
 export class ChatSession {
   private sharedSecret: Buffer | null = null;
@@ -11,7 +14,8 @@ export class ChatSession {
   constructor(
     public readonly id: string,
     public readonly userA: User,
-    public readonly userB: User
+    public readonly userB: User,
+    private storageProvider?: StorageProvider
   ) {}
 
   /**
@@ -40,6 +44,13 @@ export class ChatSession {
       privateKey: user.privateKey,
     };
     
+    logger.debug(`[ChatSession] Initializing for user ${user.id}`, {
+      hasLocalPriv: !!user.privateKey,
+      privType: typeof user.privateKey,
+      hasRemotePub: !!otherUser.publicKey,
+      pubType: typeof otherUser.publicKey
+    });
+    
     this.sharedSecret = deriveSharedSecret(localKeyPair, otherUser.publicKey);
   }
 
@@ -68,6 +79,65 @@ export class ChatSession {
     };
   }
 
+  /**
+   * Encrypt a media message for this session
+   */
+  async encryptMedia(
+    plaintext: string,
+    media: MediaAttachment,
+    senderId: string
+  ): Promise<Message> {
+    if (!this.sharedSecret) {
+      await this.initialize();
+    }
+
+    if (!this.sharedSecret) {
+      throw new Error("Failed to initialize session");
+    }
+
+    // Encrypt the message text (could be caption)
+    const { ciphertext, iv } = encryptMessage(plaintext, this.sharedSecret);
+
+    // Encrypt the media data with its own IV
+    const { ciphertext: encryptedMediaData, iv: mediaIv } = encryptMessage(
+      media.data || "",
+      this.sharedSecret
+    );
+
+    // Create encrypted media attachment
+    const encryptedMedia: MediaAttachment = {
+      ...media,
+      data: encryptedMediaData,
+      iv: mediaIv,
+    };
+
+    // If storage provider is available, upload the encrypted data
+    if (this.storageProvider) {
+      const filename = `${this.id}/${generateUUID()}-${media.metadata.filename}`;
+      const uploadResult = await this.storageProvider.upload(
+        encryptedMediaData,
+        filename,
+        media.metadata.mimeType
+      );
+      
+      encryptedMedia.storage = this.storageProvider.name as 'local' | 's3';
+      encryptedMedia.storageKey = uploadResult.storageKey;
+      encryptedMedia.url = uploadResult.url;
+      encryptedMedia.data = undefined; // Remove data from attachment if stored remotely
+    }
+
+    return {
+      id: generateUUID(),
+      senderId,
+      receiverId: senderId === this.userA.id ? this.userB.id : this.userA.id,
+      ciphertext,
+      iv,
+      timestamp: Date.now(),
+      type: "media",
+      media: encryptedMedia,
+    };
+  }
+
   /**
    * Decrypt a message in this session
    */
@@ -83,6 +153,93 @@ export class ChatSession {
       throw new Error("Failed to initialize session");
     }
 
-    return decryptMessage(message.ciphertext, message.iv, this.sharedSecret);
+    try {
+      return decryptMessage(message.ciphertext, message.iv, this.sharedSecret);
+    } catch (error) {
+      // Fallback for legacy messages (before salt logic)
+      const legacySecret = this.deriveLegacySecret(user);
+      try {
+        return decryptMessage(message.ciphertext, message.iv, legacySecret);
+      } catch (innerError) {
+        throw error; // Throw original error if fallback also fails
+      }
+    }
+  }
+
+  private deriveLegacySecret(user: User): Buffer {
+    const otherUser = user.id === this.userA.id ? this.userB : this.userA;
+    logger.debug(`[ChatSession] Deriving legacy secret for user ${user.id}`, {
+      hasPriv: !!user.privateKey,
+      privType: typeof user.privateKey,
+      remotePubType: typeof otherUser.publicKey
+    });
+    const localKeyPair: KeyPair = {
+      publicKey: user.publicKey,
+      privateKey: user.privateKey,
+    };
+    return deriveLegacySharedSecret(localKeyPair, otherUser.publicKey);
+  }
+
+  /**
+   * Decrypt a media message in this session
+   */
+  async decryptMedia(message: Message, user: User): Promise<{ text: string; media: MediaAttachment }> {
+    if (!message.media) {
+      throw new Error("Message does not contain media");
+    }
+
+    // Re-initialize if needed
+    if (!this.sharedSecret || 
+        (user.id !== this.userA.id && user.id !== this.userB.id)) {
+      await this.initializeForUser(user);
+    }
+
+    if (!this.sharedSecret) {
+      throw new Error("Failed to initialize session");
+    }
+
+    // Decrypt the message text
+    const text = decryptMessage(message.ciphertext, message.iv, this.sharedSecret);
+
+    let encryptedMediaData = message.media.data;
+
+    // If data is missing but storageKey is present, download it
+    if (!encryptedMediaData && message.media.storageKey && this.storageProvider) {
+      encryptedMediaData = await this.storageProvider.download(message.media.storageKey);
+    }
+
+    // Decrypt the media data using its own IV
+    if (!message.media.iv && !encryptedMediaData) {
+        throw new Error("Media data or IV missing");
+    }
+
+    let decryptedMediaData: string;
+    try {
+      decryptedMediaData = decryptMessage(
+        encryptedMediaData || "",
+        message.media.iv || message.iv,
+        this.sharedSecret
+      );
+    } catch (error) {
+      // Fallback for legacy media
+      const legacySecret = this.deriveLegacySecret(user);
+      try {
+        decryptedMediaData = decryptMessage(
+          encryptedMediaData || "",
+          message.media.iv || message.iv,
+          legacySecret
+        );
+      } catch (innerError) {
+        throw error;
+      }
+    }
+
+    // Create decrypted media attachment
+    const decryptedMedia: MediaAttachment = {
+      ...message.media,
+      data: decryptedMediaData,
+    };
+
+    return { text, media: decryptedMedia };
   }
 }

package/src/chat/GroupSession.ts

@@ -1,14 +1,16 @@
 import type { Group } from "../models/group.js";
 import type { Message } from "../models/message.js";
+import type { MediaAttachment } from "../models/mediaTypes.js";
 import { deriveGroupKey } from "../crypto/group.js";
 import { encryptMessage, decryptMessage } from "../crypto/e2e.js";
 import { base64ToBuffer } from "../crypto/utils.js";
 import { generateUUID } from "../crypto/uuid.js";
+import type { StorageProvider } from "../storage/adapters.js";
 
 export class GroupSession {
   private groupKey: Buffer | null = null;
 
-  constructor(public readonly group: Group) {}
+  constructor(public readonly group: Group, private storageProvider?: StorageProvider) {}
 
   /**
    * Initialize the session by deriving the group key
@@ -43,6 +45,65 @@ export class GroupSession {
     };
   }
 
+  /**
+   * Encrypt a media message for this group
+   */
+  async encryptMedia(
+    plaintext: string,
+    media: MediaAttachment,
+    senderId: string
+  ): Promise<Message> {
+    if (!this.groupKey) {
+      await this.initialize();
+    }
+
+    if (!this.groupKey) {
+      throw new Error("Failed to initialize group session");
+    }
+
+    // Encrypt the message text (could be caption)
+    const { ciphertext, iv } = encryptMessage(plaintext, this.groupKey);
+
+    // Encrypt the media data with its own IV
+    const { ciphertext: encryptedMediaData, iv: mediaIv } = encryptMessage(
+      media.data || "",
+      this.groupKey
+    );
+
+    // Create encrypted media attachment
+    const encryptedMedia: MediaAttachment = {
+      ...media,
+      data: encryptedMediaData,
+      iv: mediaIv,
+    };
+
+    // If storage provider is available, upload the encrypted data
+    if (this.storageProvider) {
+      const filename = `groups/${this.group.id}/${generateUUID()}-${media.metadata.filename}`;
+      const uploadResult = await this.storageProvider.upload(
+        encryptedMediaData,
+        filename,
+        media.metadata.mimeType
+      );
+      
+      encryptedMedia.storage = this.storageProvider.name as 'local' | 's3';
+      encryptedMedia.storageKey = uploadResult.storageKey;
+      encryptedMedia.url = uploadResult.url;
+      encryptedMedia.data = undefined; // Remove data from attachment if stored remotely
+    }
+
+    return {
+      id: generateUUID(),
+      senderId,
+      groupId: this.group.id,
+      ciphertext,
+      iv,
+      timestamp: Date.now(),
+      type: "media",
+      media: encryptedMedia,
+    };
+  }
+
   /**
    * Decrypt a message in this group
    */
@@ -57,4 +118,50 @@ export class GroupSession {
 
     return decryptMessage(message.ciphertext, message.iv, this.groupKey);
   }
+
+  /**
+   * Decrypt a media message in this group
+   */
+  async decryptMedia(message: Message): Promise<{ text: string; media: MediaAttachment }> {
+    if (!message.media) {
+      throw new Error("Message does not contain media");
+    }
+
+    if (!this.groupKey) {
+      await this.initialize();
+    }
+
+    if (!this.groupKey) {
+      throw new Error("Failed to initialize group session");
+    }
+
+    // Decrypt the message text
+    const text = decryptMessage(message.ciphertext, message.iv, this.groupKey);
+
+    let encryptedMediaData = message.media.data;
+
+    // If data is missing but storageKey is present, download it
+    if (!encryptedMediaData && message.media.storageKey && this.storageProvider) {
+      encryptedMediaData = await this.storageProvider.download(message.media.storageKey);
+    }
+
+    // Decrypt the media data using its own IV
+    if (!message.media.iv && !encryptedMediaData) {
+        throw new Error("Media data or IV missing");
+    }
+
+    const decryptedMediaData = decryptMessage(
+      encryptedMediaData || "",
+      message.media.iv || message.iv, // Fallback to message IV for backward compatibility
+      this.groupKey
+    );
+
+    // Create decrypted media attachment
+    const decryptedMedia: MediaAttachment = {
+      ...message.media,
+      data: decryptedMediaData,
+    };
+
+    return { text, media: decryptedMedia };
+  }
 }

package/src/constants.ts

@@ -0,0 +1,61 @@
+/**
+ * SDK Configuration Constants
+ */
+
+// Cryptography
+export const SUPPORTED_CURVE = "prime256v1";
+export const ALGORITHM = "aes-256-gcm";
+export const IV_LENGTH = 12; // 96 bits for GCM
+export const SALT_LENGTH = 16;
+export const KEY_LENGTH = 32; // 256 bits
+export const TAG_LENGTH = 16;
+export const PBKDF2_ITERATIONS = 100000;
+
+// Validation
+export const USERNAME_MIN_LENGTH = 3;
+export const USERNAME_MAX_LENGTH = 20;
+export const MESSAGE_MAX_LENGTH = 10000;
+export const GROUP_NAME_MAX_LENGTH = 100;
+export const GROUP_MIN_MEMBERS = 2;
+export const GROUP_MAX_MEMBERS = 256;
+
+// Transport
+export const RECONNECT_MAX_ATTEMPTS = 5;
+export const RECONNECT_BASE_DELAY = 1000; // 1 second
+export const RECONNECT_MAX_DELAY = 30000; // 30 seconds
+export const HEARTBEAT_INTERVAL = 30000; // 30 seconds
+export const CONNECTION_TIMEOUT = 10000; // 10 seconds
+
+// Message Queue
+export const MAX_QUEUE_SIZE = 1000;
+export const MESSAGE_RETRY_ATTEMPTS = 3;
+export const MESSAGE_RETRY_DELAY = 2000; // 2 seconds
+
+// Events
+export const EVENTS = {
+  MESSAGE_SENT: 'message:sent',
+  MESSAGE_RECEIVED: 'message:received',
+  MESSAGE_FAILED: 'message:failed',
+  CONNECTION_STATE_CHANGED: 'connection:state',
+  SESSION_CREATED: 'session:created',
+  GROUP_CREATED: 'group:created',
+  ERROR: 'error',
+  USER_CREATED: 'user:created',
+} as const;
+
+// Connection States
+export enum ConnectionState {
+  DISCONNECTED = 'disconnected',
+  CONNECTING = 'connecting',
+  CONNECTED = 'connected',
+  RECONNECTING = 'reconnecting',
+  FAILED = 'failed',
+}
+
+// Message Status
+export enum MessageStatus {
+  PENDING = 'pending',
+  SENT = 'sent',
+  DELIVERED = 'delivered',
+  FAILED = 'failed',
+}