baileys-redis-auth 1.0.14 → 2.0.0

package/LOGOUT_GUIDE.md

@@ -0,0 +1,210 @@
+# Logout Implementation Guide
+
+This document explains how to properly implement logout functionality with `baileys-redis-auth`.
+
+## How Baileys Logout Works
+
+When you call `sock.logout()`, Baileys:
+
+1. Sends a "remove-companion-device" request to WhatsApp servers
+2. Triggers a connection close with `DisconnectReason.loggedOut` status code
+3. **Does NOT automatically clear auth state** - this is the responsibility of your application
+
+## Important: Auth State Does Not Auto-Clear
+
+Unlike some other libraries, **Baileys does not automatically clear authentication state when logout() is called**. This is intentional and follows the file-based auth state pattern.
+
+Your application MUST manually clear the Redis session when it detects a logout.
+
+## Proper Logout Implementation
+
+### Step 1: Detect Logout in Connection Handler
+
+```typescript
+import {deleteKeysWithPattern, useRedisAuthState} from 'baileys-redis-auth'
+import {DisconnectReason} from '@whiskeysockets/baileys'
+
+const {state, saveCreds, redis} = await useRedisAuthState(redisOptions, 'my-session')
+
+sock.ev.on('connection.update', async (update) => {
+  const {connection, lastDisconnect} = update
+
+  if (connection === 'close') {
+    const statusCode = (lastDisconnect?.error as Boom)?.output?.statusCode
+
+    if (statusCode === DisconnectReason.loggedOut) {
+      // User logged out - clear the session
+      await deleteKeysWithPattern({
+        redis,
+        pattern: 'my-session:*',  // Must match your session prefix
+        logger: console.log        // Optional: pass logger for debugging
+      })
+      console.log('Session cleared after logout')
+    }
+  }
+})
+```
+
+### Step 2: Call Logout When Needed
+
+```typescript
+// When user wants to logout
+try {
+  await sock.logout()
+} catch (error) {
+  // Logout throws "Intentional Logout" error - this is expected
+  // The connection.update handler will handle cleanup
+}
+```
+
+## Using Hash-Based Storage (useRedisAuthStateWithHSet)
+
+If you're using `useRedisAuthStateWithHSet`, use `deleteHSetKeys` instead:
+
+```typescript
+import {deleteHSetKeys, useRedisAuthStateWithHSet} from 'baileys-redis-auth'
+
+const {state, saveCreds, redis} = await useRedisAuthStateWithHSet(redisOptions, 'my-session')
+
+sock.ev.on('connection.update', async (update) => {
+  const {connection, lastDisconnect} = update
+
+  if (connection === 'close') {
+    const statusCode = (lastDisconnect?.error as Boom)?.output?.statusCode
+
+    if (statusCode === DisconnectReason.loggedOut) {
+      // Clear HSet-based session
+      await deleteHSetKeys({
+        redis,
+        key: 'my-session',
+        logger: console.log  // Optional: pass logger for debugging
+      })
+      console.log('Session cleared after logout')
+    }
+  }
+})
+```
+
+## Complete Example
+
+```typescript
+import {deleteKeysWithPattern, useRedisAuthState} from 'baileys-redis-auth'
+import makeWASocket, {DisconnectReason} from '@whiskeysockets/baileys'
+import type {Boom} from '@hapi/boom'
+
+async function startWhatsApp() {
+  const sessionPrefix = 'my-session'
+
+  const {state, saveCreds, redis} = await useRedisAuthState({
+    host: 'localhost',
+    port: 6379,
+  }, sessionPrefix)
+
+  const sock = makeWASocket({
+    auth: state,
+    // ... other options
+  })
+
+  // Save credentials on update
+  sock.ev.on('creds.update', saveCreds)
+
+  // Handle connection updates
+  sock.ev.on('connection.update', async (update) => {
+    const {connection, lastDisconnect} = update
+
+    if (connection === 'close') {
+      const statusCode = (lastDisconnect?.error as Boom)?.output?.statusCode
+
+      if (statusCode === DisconnectReason.loggedOut) {
+        // THIS IS CRITICAL: Clear Redis session on logout
+        await deleteKeysWithPattern({
+          redis,
+          pattern: `${sessionPrefix}:*`,
+          logger: console.log  // Optional: pass logger for debugging
+        })
+        console.log('✅ Session cleared successfully')
+      } else {
+        // Reconnect on other errors
+        console.log('Reconnecting...')
+        startWhatsApp()
+      }
+    }
+  })
+
+  return sock
+}
+
+// Usage
+const sock = await startWhatsApp()
+
+// Later, when user wants to logout:
+await sock.logout() // This will trigger the cleanup in connection.update handler
+```
+
+## Why This Design?
+
+This design follows Baileys' philosophy:
+
+1. **Separation of Concerns**: Auth state storage is separate from connection management
+2. **Flexibility**: You can choose when and how to clear sessions
+3. **Consistency**: Works the same way as file-based auth state
+4. **Control**: You have full control over session lifecycle
+
+## Common Mistakes
+
+### ❌ Wrong: Calling logout without cleanup handler
+
+```typescript
+// This will NOT clear your Redis session!
+await sock.logout()
+// Session data still exists in Redis
+```
+
+### ❌ Wrong: Clearing session before logout completes
+
+```typescript
+await sock.logout()
+await deleteKeysWithPattern({redis, pattern: 'session:*'})
+// Race condition - might clear before logout message is sent
+```
+
+### ✅ Correct: Handle cleanup in connection.update
+
+```typescript
+sock.ev.on('connection.update', async (update) => {
+  if (connection === 'close' && statusCode === DisconnectReason.loggedOut) {
+    await deleteKeysWithPattern({redis, pattern: 'session:*'})
+  }
+})
+
+// Later...
+await sock.logout() // Cleanup happens automatically
+```
+
+## Exported Functions Reference
+
+### For Key-Value Storage
+
+```typescript
+deleteKeysWithPattern({
+  redis: RedisClient,    // Redis client from useRedisAuthState
+  pattern: string,       // Pattern to match (e.g., 'session:*')
+  logger?: (message: string, ...args: unknown[]) => void  // Optional logger function
+}): Promise<void>
+```
+
+### For Hash Storage
+
+```typescript
+deleteHSetKeys({
+  redis: RedisClient,    // Redis client from useRedisAuthStateWithHSet
+  key: string,          // Session prefix (e.g., 'session')
+  logger?: (message: string, ...args: unknown[]) => void  // Optional logger function
+}): Promise<void>
+```
+
+## See Also
+
+- [Example Implementation](./example/example.ts) - Complete working example with logout
+- [Main Documentation](./CLAUDE.md) - Full library documentation
+- [Baileys Documentation](https://github.com/WhiskeySockets/Baileys) - Official Baileys docs

package/README.md

@@ -1,36 +1,314 @@
 # baileys-redis-auth
 
-use redis as auth storage for baileys
+`baileys-redis-auth` is a library designed to seamlessly integrate Redis as an authentication state storage solution for [Baileys](https://github.com/WhiskeySockets/Baileys), the powerful WhatsApp Web API library. By leveraging Redis, this module allows you to persist Baileys sessions, enabling your application to resume connections without needing to re-scan QR codes frequently. This is particularly useful for applications requiring robust and scalable session management.
 
-**how to install:**
+This library provides flexible ways to store authentication data in Redis, using either simple key-value pairs or Redis Hashes for optimized storage.
 
-    npm install baileys-redis-auth
+## ⚠️ Version Compatibility
 
-**update version 1.0.7:**
+| baileys-redis-auth | Baileys Version | Package Name |
+|-------------------|-----------------|--------------|
+| v2.x | `baileys` v7.0.0-rc.1+ | `baileys` |
+| v1.x | `@whiskeysockets/baileys` v6.x | `@whiskeysockets/baileys` |
 
-    const {useRedisAuthStateWithHSet, deleteHSetKeys} = require('baileys-redis-auth');
+**v2.0.0 Breaking Changes:**
+- Now requires **Baileys v7+** (the new `baileys` package)
+- Library is now **ESM-only** (no CommonJS support)
+- Baileys is now a **peer dependency** - you must install it separately
 
-    const  redisOptions  = {
-    	host:  'localhost',
-    	port:  6379,
-    };
+## Prerequisites
 
-    const {state, saveCreds, redis} =  await  useRedisAuthStateWithHSet(redisOptions, 'DB1');
+Before using `baileys-redis-auth`, ensure you have the following installed and configured:
 
-    // if you need to delete all keys in the DB1 database, you can use the following code:
-    await deleteHSetKeys({redis, key: 'DB1'});
+*   **Node.js:** Version 18.x or higher is recommended.
+*   **Redis:** A running Redis server instance. You'll need its connection details (host, port, password if any).
+*   **Baileys v7+:** This library is an auth handler for Baileys. Install the new `baileys` package (not `@whiskeysockets/baileys`).
 
+## Installation
+
+```bash
+# Install both the auth library and Baileys v7
+npm install baileys-redis-auth baileys
+```
+
+Or with other package managers:
+```bash
+# Bun
+bun add baileys-redis-auth baileys
+
+# Yarn
+yarn add baileys-redis-auth baileys
+
+# pnpm
+pnpm add baileys-redis-auth baileys
+```
+
+## Usage
+
+### Using `useRedisAuthStateWithHSet` (Recommended)
+
+This is the recommended method for storing Baileys authentication data in Redis. It utilizes Redis Hashes (HSET) to store all authentication credentials and keys under a single Redis key per session prefix. This approach is generally more efficient and organized, especially when managing multiple Baileys sessions.
+
+**Parameters:**
+*   `redisOptions`: An object containing your Redis server connection details (e.g., `host`, `port`, `password`). This is passed directly to the `ioredis` constructor.
+*   `prefix`: A string used to namespace your Baileys session data in Redis. For example, if your `prefix` is `'DB1'`, all data for this session will be stored under a Redis key like `authState:DB1`. This allows you to manage multiple independent Baileys sessions in the same Redis database.
+*   `logger` (optional): A function `(message: string, ...args: unknown[]) => void` for logging Redis connection events. Pass `console.log` or your custom logger function.
+
+```typescript
+import {useRedisAuthStateWithHSet, deleteHSetKeys} from 'baileys-redis-auth';
+import type {RedisOptions} from 'ioredis';
+
+// Define your Redis connection options
+const redisOptions: RedisOptions = {
+    host: 'localhost',
+    port: 6379,
+    // password: 'your_redis_password', // Uncomment if your Redis has a password
+};
+
+// Define a unique prefix for this Baileys session
+const sessionPrefix = 'baileys_session_1';
+
+async function initializeBaileysWithHSet() {
+    // Initialize a new Redis client instance if you need to pass it around or use it elsewhere
+    // const redis = new Redis(redisOptions);
+    // redis.on('connect', () => console.log('Connected to Redis for HSet method!'));
+    // Note: useRedisAuthStateWithHSet creates its own Redis instance internally based on redisOptions.
+    // If you pass an existing ioredis instance, it should be the first argument,
+    // and redisOptions the second, though the current library signature seems to expect options first.
+    // For simplicity, we'll let the function create its own connection.
+
+    const {state, saveCreds, redis: authRedisInstance} = await useRedisAuthStateWithHSet(
+        redisOptions,
+        sessionPrefix,
+        console.log  // Optional: pass logger for Redis connection events
+    );
+
+    // 'state' will be used to initialize Baileys
+    // 'saveCreds' is a function to periodically save the authentication state
+    // 'authRedisInstance' is the Redis client instance used by the auth state hook
+
+    console.log('Baileys state loaded using HSet method.');
+
+    // Example: Listen for Redis connection events on the instance returned by the hook
+    authRedisInstance.on('connect', () => console.log(`Redis (from hook) connected for session: ${sessionPrefix}`));
+    authRedisInstance.on('error', (err) => console.error(`Redis (from hook) error for session ${sessionPrefix}:`, err));
+
+    // ... your Baileys setup code using 'state' and 'saveCreds'
+
+    // Example of how to delete all keys for this specific session prefix if needed:
+    // await deleteHSetKeys({redis: authRedisInstance, key: sessionPrefix});
+    // console.log(`Authentication data for session ${sessionPrefix} deleted.`);
+}
+
+initializeBaileysWithHSet().catch(console.error);
+```
+
+#### Deleting Session Data (`deleteHSetKeys`)
+
+To remove all authentication data associated with a specific session prefix used with `useRedisAuthStateWithHSet`, you can use the `deleteHSetKeys` utility function.
+
+**Usage:**
+
+```typescript
+import { deleteHSetKeys } from 'baileys-redis-auth';
+// Use the Redis instance from useRedisAuthStateWithHSet
+
+// Assuming 'authRedisInstance' is the Redis instance from useRedisAuthStateWithHSet
+// or a new instance configured with the same options.
+// const redisClient = new Redis(redisOptions);
+// const sessionPrefixToDelete = 'baileys_session_1';
+
+// await deleteHSetKeys({redis: authRedisInstance, key: sessionPrefixToDelete});
+// console.log(`All HSet data for prefix '${sessionPrefixToDelete}' deleted.`);
+```
+
+**Parameters:**
+*   `options`: An object with the following properties:
+    *   `redis`: An active `ioredis` client instance.
+    *   `key`: The session `prefix` string (e.g., `'baileys_session_1'`) whose data needs to be deleted. This corresponds to the `prefix` you used with `useRedisAuthStateWithHSet`.
+    *   `logger` (optional): A function for logging deletion operations.
+
+### Using `useRedisAuthState`
+
+This method stores each piece of authentication data as a separate key-value pair in Redis, prefixed by the `prefix` string. While functional, it can lead to a larger number of individual keys in your Redis database compared to the HSET method.
+
+**Parameters:**
+*   `redisOptions`: An object containing your Redis server connection details (e.g., `host`, `port`, `password`). This is passed directly to the `ioredis` constructor.
+*   `prefix`: A string used to prefix all Redis keys for this Baileys session. For example, if your `prefix` is `'DB1'`, keys will be stored like `DB1:creds`, `DB1:pre-key-1`, etc.
+*   `logger` (optional): A function `(message: string, ...args: unknown[]) => void` for logging Redis connection events. Pass `console.log` or your custom logger function.
+
+```typescript
+import {useRedisAuthState, deleteKeysWithPattern} from 'baileys-redis-auth';
+import type {RedisOptions} from 'ioredis';
+
+// Define your Redis connection options
+const redisOptions: RedisOptions = {
+    host: 'localhost',
+    port: 6379,
+    // password: 'your_redis_password', // Uncomment if your Redis has a password
+};
+
+// Define a unique prefix for this Baileys session
+const sessionPrefix = 'baileys_session_2';
+
+async function initializeBaileysSimple() {
+    // Initialize a new Redis client instance if you need to pass it around
+    // const redis = new Redis(redisOptions);
+    // redis.on('connect', () => console.log('Connected to Redis for simple method!'));
+    // As with HSet, useRedisAuthState creates its own Redis instance.
+
+    const {state, saveCreds, redis: authRedisInstance} = await useRedisAuthState(
+        redisOptions,
+        sessionPrefix,
+        console.log  // Optional: pass logger for Redis connection events
+    );
+
+    // 'state' will be used to initialize Baileys
+    // 'saveCreds' is a function to periodically save the authentication state
+    // 'authRedisInstance' is the Redis client instance used by the auth state hook
+
+    console.log('Baileys state loaded using simple key-value method.');
     
-**example v1.0.6:**
+    // Example: Listen for Redis connection events on the instance returned by the hook
+    authRedisInstance.on('connect', () => console.log(`Redis (from hook) connected for session: ${sessionPrefix}`));
+    authRedisInstance.on('error', (err) => console.error(`Redis (from hook) error for session ${sessionPrefix}:`, err));
+
+    // ... your Baileys setup code using 'state' and 'saveCreds'
+
+    // Example of how to delete all keys for this specific session prefix if needed:
+    // The pattern should match the prefix used.
+    // await deleteKeysWithPattern({redis: authRedisInstance, pattern: `${sessionPrefix}:*`});
+    // console.log(`Authentication data for session ${sessionPrefix} (pattern: ${sessionPrefix}:*) deleted.`);
+}
+
+initializeBaileysSimple().catch(console.error);
+```
+
+#### Deleting Session Data (`deleteKeysWithPattern`)
+
+To remove all authentication data associated with a specific session prefix used with `useRedisAuthState`, you can use the `deleteKeysWithPattern` utility function. This function deletes all Redis keys matching a given pattern.
+
+**Usage:**
+
+```typescript
+import { deleteKeysWithPattern } from 'baileys-redis-auth';
+// Use the Redis instance from useRedisAuthState
+
+// Assuming 'authRedisInstance' is the Redis instance from useRedisAuthState
+// or a new instance configured with the same options.
+// const redisClient = new Redis(redisOptions);
+// const sessionPrefixToDelete = 'baileys_session_2';
+
+// The pattern must match how useRedisAuthState stores keys, typically `prefix:*`
+// await deleteKeysWithPattern({redis: authRedisInstance, pattern: `${sessionPrefixToDelete}:*`});
+// console.log(`All keys matching pattern '${sessionPrefixToDelete}:*' deleted.`);
+```
+
+**Parameters:**
+*   `options`: An object with the following properties:
+    *   `redis`: An active `ioredis` client instance.
+    *   `pattern`: The key pattern to delete (e.g., `'baileys_session_2:*'`). This should align with the `prefix` used in `useRedisAuthState`, followed by `:*` to match all related keys.
+    *   `logger` (optional): A function for logging deletion operations.
+
+## Logout and Session Cleanup
+
+**Important**: When you call `sock.logout()`, Baileys does NOT automatically clear your Redis session. You must manually handle session cleanup in your `connection.update` event handler.
+
+### Proper Logout Implementation
+
+```typescript
+import {deleteKeysWithPattern, useRedisAuthState} from 'baileys-redis-auth'
+import makeWASocket, {DisconnectReason} from 'baileys'
+import type {Boom} from '@hapi/boom'
+
+const sessionPrefix = 'my-session'
+const {state, saveCreds, redis} = await useRedisAuthState(redisOptions, sessionPrefix, console.log)
+
+const sock = makeWASocket({auth: state})
+
+// Handle connection updates
+sock.ev.on('connection.update', async (update) => {
+  const {connection, lastDisconnect} = update
+
+  if (connection === 'close') {
+    const statusCode = (lastDisconnect?.error as Boom)?.output?.statusCode
+
+    if (statusCode === DisconnectReason.loggedOut) {
+      // Clear Redis session on logout
+      await deleteKeysWithPattern({
+        redis,
+        pattern: `${sessionPrefix}:*`,
+        logger: console.log  // Optional: pass logger for debugging
+      })
+      console.log('Session cleared')
+    }
+  }
+})
+
+// When you want to logout
+await sock.logout() // Session cleanup happens in connection.update handler
+```
+
+For detailed logout implementation guide, see [LOGOUT_GUIDE.md](./LOGOUT_GUIDE.md).
+
+## Running the Example
+
+This project includes an example script to demonstrate the usage of `baileys-redis-auth`. To run it:
+
+1.  **Clone the repository (if you haven't already):**
+    ```bash
+    git clone https://github.com/hbinduni/baileys-redis-auth.git
+    cd baileys-redis-auth
+    ```
+
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    # or
+    # pnpm install
+    # or
+    # yarn install
+    ```
+
+3.  **Ensure you have a Redis server running** and accessible on `localhost:6379` (or update the example script with your Redis configuration).
+
+4.  **Configure environment variables:**
+    ```bash
+    cp .env.example .env
+    # Edit .env with your Redis configuration
+    ```
+
+5.  **Run the example script:**
+    ```bash
+    npm run example
+    # or
+    # pnpm example
+    # or
+    # bun run example
+    ```
+    This command executes `tsx example/example.ts`.
+    The example will guide you through connecting to WhatsApp using Baileys with Redis for authentication storage. You'll see a QR code in your terminal to scan with WhatsApp.
+
+    **Interactive Commands:**
+    - `send <phone> <message>` - Send a WhatsApp message
+    - `logout` - Logout and clear session
+    - `help` - Show available commands
+    - `exit` - Exit the application
+
+## Contributing
+
+Contributions are welcome! If you have suggestions for improvements, bug fixes, or new features, please feel free to:
 
-    const {useRedisAuthState, deleteKeysWithPattern} = require('baileys-redis-auth');
+1.  Fork the repository.
+2.  Create a new branch (`git checkout -b feature/your-feature-name`).
+3.  Make your changes.
+4.  Commit your changes (`git commit -m 'Add some feature'`).
+5.  Push to the branch (`git push origin feature/your-feature-name`).
+6.  Open a Pull Request.
 
-    const  redisOptions  = {
-    	host:  'localhost',
-    	port:  6379,
-    };
+Please ensure your code adheres to the existing style and that any new functionality is appropriately documented.
 
-    const {state, saveCreds, redis} =  await  useRedisAuthState(redisOptions, 'DB1');
+## License
 
-    // if you need to delete all keys in the DB1 database, you can use the following code:
-    await deleteKeysWithPattern({redis, pattern: 'DB1*'});
+This project is licensed under the MIT License. Refer to the license information in the `package.json` for details.
+```

package/lib/index.d.ts

@@ -0,0 +1,43 @@
+import { type AuthenticationState } from 'baileys';
+import { Redis, type RedisOptions } from 'ioredis';
+type RedisClient = Redis;
+interface IDeleteHSetKeyOptions {
+    redis: RedisClient;
+    key: string;
+    logger?: (message: string, ...args: unknown[]) => void;
+}
+interface IDeleteKeysOptions {
+    redis: RedisClient;
+    pattern: string;
+    logger?: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Redis-based authentication state storage using Hash (HSET) - Recommended
+ * Stores all authentication data in a single Redis Hash per prefix
+ * More efficient than key-value approach for Redis memory and operations
+ */
+export declare const useRedisAuthStateWithHSet: (redisOptions: RedisOptions, prefix?: string, logger?: (message: string, ...args: unknown[]) => void) => Promise<{
+    state: AuthenticationState;
+    saveCreds: () => Promise<void>;
+    redis: RedisClient;
+}>;
+/**
+ * Deletes all authentication data for a specific prefix using Hash (HSET)
+ */
+export declare const deleteHSetKeys: ({ redis, key, logger }: IDeleteHSetKeyOptions) => Promise<void>;
+/**
+ * Redis-based authentication state storage using key-value pairs
+ * Stores each piece of authentication data as a separate Redis key
+ * Less efficient than Hash approach but more compatible with existing systems
+ */
+export declare const useRedisAuthState: (redisOptions: RedisOptions, prefix?: string, logger?: (message: string, ...args: unknown[]) => void) => Promise<{
+    state: AuthenticationState;
+    saveCreds: () => Promise<void>;
+    redis: RedisClient;
+}>;
+/**
+ * Deletes all authentication keys matching a pattern using key-value approach
+ * Uses SCAN to safely iterate through keys without blocking Redis
+ */
+export declare const deleteKeysWithPattern: ({ redis, pattern, logger }: IDeleteKeysOptions) => Promise<void>;
+export {};