chatly-sdk 0.0.8 → 2.0.0

package/IMPROVEMENTS.md

@@ -4,7 +4,7 @@ This document outlines the major improvements and production-ready features that
 
 ---
 
-## 🎯 Production-Ready Features
+## 🎯 Production-Ready Features (Beta)
 
 ### 1. Message Queue with Automatic Retry
 

package/README.md

@@ -1,6 +1,9 @@
 # 🔐 Chatly SDK
 
-Beta end-to-end encrypted chat SDK with WhatsApp-style features, event-driven architecture, and automatic reconnection.
+Production-ready end-to-end encrypted chat SDK with WhatsApp-style features, event-driven architecture, and automatic reconnection.
+
+You can find the sample project repository here: [Chatly SDK Sample Project](https://github.com/bharath-arch/chatly-sdk-demo.git)
+
 
 [![npm version](https://img.shields.io/npm/v/chatly-sdk.svg)](https://www.npmjs.com/package/chatly-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -12,6 +15,7 @@ Beta end-to-end encrypted chat SDK with WhatsApp-style features, event-driven ar
 - **Per-User Identity Keys** - Unique cryptographic identity
 - **Session-Based Encryption** - Secure 1:1 and group messaging
 - **Input Validation** - Protection against injection attacks
+- **Configurable Media Storage** - Offload encrypted files to S3 or Local storage
 
 ### 💬 Messaging
 - **1:1 Chat** - Secure direct messaging
@@ -181,6 +185,7 @@ const sdk = new ChatSDK({
   userStore: new InMemoryUserStore(),
   messageStore: new InMemoryMessageStore(),
   groupStore: new InMemoryGroupStore(),
+  storageProvider: new LocalStorageProvider('./uploads'), // Optional: S3 or Local
   logLevel: LogLevel.INFO, // Optional: DEBUG, INFO, WARN, ERROR, NONE
 });
 
@@ -376,24 +381,59 @@ console.log('Supported image types:', SUPPORTED_MIME_TYPES.image);
 console.log('Max video size:', FILE_SIZE_LIMITS.video); // 100 MB
 ```
 
+### 📦 Media Storage & Offloading
+
+To prevent database bloat, large media files are automatically offloaded to a storage provider. The SDK encrypts the file locally, then uploads the ciphertext.
+
+#### Local Storage
+Store files on the server's local filesystem:
+
+```typescript
+import { LocalStorageProvider } from 'chatly-sdk';
+
+const storage = new LocalStorageProvider('./uploads');
+const sdk = new ChatSDK({ storageProvider: storage, ... });
+```
+
+#### AWS S3 Storage
+Store files in an S3 bucket:
+
+```typescript
+import { S3StorageProvider } from 'chatly-sdk';
+
+const storage = new S3StorageProvider({
+  region: 'us-east-1',
+  bucket: 'my-chat-app-media',
+  credentials: {
+    accessKeyId: '...',
+    secretAccessKey: '...'
+  }
+});
+const sdk = new ChatSDK({ storageProvider: storage, ... });
+```
+
 ### Media Encryption
 
 All media files are **fully encrypted end-to-end**:
 
-1. **File data** is encrypted with the session/group key
-2. **Metadata** (filename, size, etc.) is stored in plaintext for efficiency
-3. **Thumbnails** (for images/videos) are encrypted
-4. **No URL-based approach** - all files sent directly through SDK
+1. **Double Encryption**: File data and captions are encrypted separately with unique IVs.
+2. **Offloading**: Encrypted data is sent to the `StorageProvider`, leaving only a small reference in the database.
+3. **Automatic Management**: The SDK automatically downloads and decrypts media when needed.
+4. **Cleanup**: Deleting a message automatically triggers deletion of the remote file.
 
 ```typescript
-// Media encryption happens automatically
-const media = await createMediaAttachment(file);
-const message = await sdk.sendMediaMessage(session, caption, media);
-
-// Message contains:
-// - Encrypted caption (ciphertext)
-// - Encrypted media data (media.data)
-// - Plaintext metadata (media.metadata)
+// Message in database now looks like this:
+{
+  "id": "msg_123",
+  "type": "media",
+  "media": {
+    "storage": "s3",
+    "storageKey": "session_id/unique-file-name.jpg",
+    "iv": "media_specific_iv",
+    "data": undefined, // Raw data is removed from DB
+    "metadata": { ... }
+  }
+}
 ```
 
 ### Example: Sending an Image

package/dist/index.d.ts

@@ -37,8 +37,12 @@ interface MediaMetadata {
  */
 interface MediaAttachment {
     type: MediaType;
-    data: string;
+    data?: string | undefined;
+    iv?: string | undefined;
     metadata: MediaMetadata;
+    storage?: 'local' | 's3' | undefined;
+    storageKey?: string | undefined;
+    url?: string | undefined;
 }
 /**
  * Supported MIME types
@@ -87,8 +91,10 @@ interface UserStoreAdapter {
 }
 interface MessageStoreAdapter {
     create(message: Message): Promise<Message>;
+    findById(id: string): Promise<Message | undefined>;
     listByUser(userId: string): Promise<Message[]>;
     listByGroup(groupId: string): Promise<Message[]>;
+    delete(id: string): Promise<void>;
 }
 interface GroupStoreAdapter {
     create(group: Group): Promise<Group>;
@@ -191,13 +197,43 @@ interface TransportAdapter {
     isConnected(): boolean;
 }
 
+interface StorageUploadResult {
+    storageKey: string;
+    url?: string;
+}
+interface StorageProvider {
+    /**
+     * Name of the storage provider (e.g., 'local', 's3')
+     */
+    readonly name: string;
+    /**
+     * Upload data to storage
+     * @param data Base64 encoded data or Buffer
+     * @param filename Desired filename or path
+     * @param mimeType MIME type of the file
+     */
+    upload(data: string | Buffer, filename: string, mimeType: string): Promise<StorageUploadResult>;
+    /**
+     * Download data from storage
+     * @param storageKey Key/path of the file in storage
+     * @returns Base64 encoded data
+     */
+    download(storageKey: string): Promise<string>;
+    /**
+     * Delete data from storage
+     * @param storageKey Key/path of the file in storage
+     */
+    delete(storageKey: string): Promise<void>;
+}
+
 declare class ChatSession {
     readonly id: string;
     readonly userA: User;
     readonly userB: User;
+    private storageProvider?;
     private sharedSecret;
     private ephemeralKeyPair;
-    constructor(id: string, userA: User, userB: User);
+    constructor(id: string, userA: User, userB: User, storageProvider?: StorageProvider | undefined);
     /**
      * Initialize the session by deriving the shared secret
      * ECDH is commutative, so we can use either user's keys
@@ -219,6 +255,7 @@ declare class ChatSession {
      * Decrypt a message in this session
      */
     decrypt(message: Message, user: User): Promise<string>;
+    private deriveLegacySecret;
     /**
      * Decrypt a media message in this session
      */
@@ -230,8 +267,9 @@ declare class ChatSession {
 
 declare class GroupSession {
     readonly group: Group;
+    private storageProvider?;
     private groupKey;
-    constructor(group: Group);
+    constructor(group: Group, storageProvider?: StorageProvider | undefined);
     /**
      * Initialize the session by deriving the group key
      */
@@ -303,8 +341,10 @@ declare class InMemoryUserStore implements UserStoreAdapter {
 declare class InMemoryMessageStore implements MessageStoreAdapter {
     private messages;
     create(message: Message): Promise<Message>;
+    findById(id: string): Promise<Message | undefined>;
     listByUser(userId: string): Promise<Message[]>;
     listByGroup(groupId: string): Promise<Message[]>;
+    delete(id: string): Promise<void>;
 }
 
 declare class InMemoryGroupStore implements GroupStoreAdapter {
@@ -481,10 +521,40 @@ declare function createMediaAttachment(file: File | Blob, filename?: string): Pr
  */
 declare function formatFileSize(bytes: number): string;
 
+declare class LocalStorageProvider implements StorageProvider {
+    readonly name = "local";
+    private storageDir;
+    constructor(storageDir?: string);
+    upload(data: string | Buffer, filename: string, mimeType: string): Promise<StorageUploadResult>;
+    download(storageKey: string): Promise<string>;
+    delete(storageKey: string): Promise<void>;
+}
+
+interface S3Config {
+    region: string;
+    bucket: string;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    endpoint?: string;
+    forcePathStyle?: boolean;
+}
+declare class S3StorageProvider implements StorageProvider {
+    readonly name = "s3";
+    private client;
+    private bucket;
+    constructor(config: S3Config);
+    upload(data: string | Buffer, filename: string, mimeType: string): Promise<StorageUploadResult>;
+    download(storageKey: string): Promise<string>;
+    delete(storageKey: string): Promise<void>;
+}
+
 interface ChatSDKConfig {
     userStore: UserStoreAdapter;
     messageStore: MessageStoreAdapter;
     groupStore: GroupStoreAdapter;
+    storageProvider?: StorageProvider;
     transport?: TransportAdapter;
     logLevel?: LogLevel;
 }
@@ -606,4 +676,4 @@ declare class ChatSDK extends EventEmitter {
     };
 }
 
-export { ALGORITHM, AuthError, CONNECTION_TIMEOUT, ChatSDK, type ChatSDKConfig, ChatSession, ConfigError, ConnectionState, EVENTS, EncryptionError, FILE_SIZE_LIMITS, GROUP_MAX_MEMBERS, GROUP_MIN_MEMBERS, GROUP_NAME_MAX_LENGTH, type Group, GroupSession, type GroupStoreAdapter, HEARTBEAT_INTERVAL, IV_LENGTH, InMemoryGroupStore, InMemoryMessageStore, InMemoryTransport, InMemoryUserStore, KEY_LENGTH, LogLevel, Logger, type LoggerConfig, MAX_QUEUE_SIZE, MESSAGE_MAX_LENGTH, MESSAGE_RETRY_ATTEMPTS, MESSAGE_RETRY_DELAY, type MediaAttachment, type MediaMetadata, MediaType, type Message, MessageStatus, type MessageStoreAdapter, type MessageType, NetworkError, PBKDF2_ITERATIONS, RECONNECT_BASE_DELAY, RECONNECT_MAX_ATTEMPTS, RECONNECT_MAX_DELAY, SALT_LENGTH, SDKError, SUPPORTED_CURVE, SUPPORTED_MIME_TYPES, SessionError, StorageError, type StoredUser, TAG_LENGTH, type TransportAdapter, TransportError, USERNAME_MAX_LENGTH, USERNAME_MIN_LENGTH, type User, type UserStoreAdapter, ValidationError, WebSocketClient, createMediaAttachment, createMediaMetadata, decodeBase64ToBlob, encodeFileToBase64, formatFileSize, getMediaType, logger, validateGroupMembers, validateGroupName, validateMediaFile, validateMessage, validateUserId, validateUsername };
+export { ALGORITHM, AuthError, CONNECTION_TIMEOUT, ChatSDK, type ChatSDKConfig, ChatSession, ConfigError, ConnectionState, EVENTS, EncryptionError, FILE_SIZE_LIMITS, GROUP_MAX_MEMBERS, GROUP_MIN_MEMBERS, GROUP_NAME_MAX_LENGTH, type Group, GroupSession, type GroupStoreAdapter, HEARTBEAT_INTERVAL, IV_LENGTH, InMemoryGroupStore, InMemoryMessageStore, InMemoryTransport, InMemoryUserStore, KEY_LENGTH, LocalStorageProvider, LogLevel, Logger, type LoggerConfig, MAX_QUEUE_SIZE, MESSAGE_MAX_LENGTH, MESSAGE_RETRY_ATTEMPTS, MESSAGE_RETRY_DELAY, type MediaAttachment, type MediaMetadata, MediaType, type Message, MessageStatus, type MessageStoreAdapter, type MessageType, NetworkError, PBKDF2_ITERATIONS, RECONNECT_BASE_DELAY, RECONNECT_MAX_ATTEMPTS, RECONNECT_MAX_DELAY, type S3Config, S3StorageProvider, SALT_LENGTH, SDKError, SUPPORTED_CURVE, SUPPORTED_MIME_TYPES, SessionError, StorageError, type StorageProvider, type StorageUploadResult, type StoredUser, TAG_LENGTH, type TransportAdapter, TransportError, USERNAME_MAX_LENGTH, USERNAME_MIN_LENGTH, type User, type UserStoreAdapter, ValidationError, WebSocketClient, createMediaAttachment, createMediaMetadata, decodeBase64ToBlob, encodeFileToBase64, formatFileSize, getMediaType, logger, validateGroupMembers, validateGroupName, validateMediaFile, validateMessage, validateUserId, validateUsername };