kalshi-trading-bot-cli 2.1.0

package/src/gateway/channels/whatsapp/README.md

@@ -0,0 +1,234 @@
+# WhatsApp Gateway
+
+Chat with the bot through WhatsApp by linking your phone to the gateway. Messages you send to yourself (self-chat) are processed by the bot and responses are sent back to the same chat.
+
+## Table of Contents
+
+- [✅ Prerequisites](#-prerequisites)
+- [🔗 How to Link WhatsApp](#-how-to-link-whatsapp)
+- [🚀 How to Run](#-how-to-run)
+- [💬 How to Chat](#-how-to-chat)
+- [⚙️ Configuration](#️-configuration)
+- [👥 Group Chat](#-group-chat)
+- [🔄 How to Relink](#-how-to-relink)
+- [🐛 Troubleshooting](#-troubleshooting)
+- [🔧 Full Reset](#-full-reset)
+
+## ✅ Prerequisites
+
+- The bot installed and working (see main [README](../../../../README.md))
+- WhatsApp installed on your phone
+- Your phone connected to the internet
+
+## 🔗 How to Link WhatsApp
+
+Link your WhatsApp account by scanning a QR code:
+
+```bash
+bun run gateway:login
+```
+
+This will:
+1. Display a QR code in your terminal
+2. Open WhatsApp on your phone
+3. Go to **Settings > Linked Devices > Link a Device**
+4. Scan the QR code
+
+After linking, you'll be asked how you want to use the bot:
+
+### Option 1: Self-chat (personal phone)
+
+Use your own WhatsApp to talk to the bot by messaging yourself. The linked phone number is added to `allowFrom` and self-chat mode is activated automatically.
+
+### Option 2: Dedicated bot phone
+
+If the bot has its own phone number (e.g. a separate SIM), choose this option and enter the phone number(s) allowed to message it. The gateway will be configured with `dmPolicy: "allowlist"` so other people can DM the bot.
+
+Credentials are saved to `.kalshi-trading-bot-cli/credentials/whatsapp/default/`.
+
+## 🚀 How to Run
+
+Start the gateway to begin receiving messages:
+
+```bash
+bun run gateway
+```
+
+You should see:
+```
+[whatsapp] Connected
+Gateway running. Press Ctrl+C to stop.
+```
+
+The gateway will now listen for incoming WhatsApp messages and respond using the bot.
+
+## 💬 How to Chat
+
+Once the gateway is running:
+
+1. Open WhatsApp on your phone
+2. Go to your own chat (message yourself)
+3. Send a message like "What is Apple's revenue?"
+4. You'll see a typing indicator while the bot processes
+5. The bot's response will appear in the chat
+
+**Example conversation:**
+```
+You: What was NVIDIA's revenue in 2024?
+Bot: NVIDIA's revenue for fiscal year 2024 was $60.9 billion...
+```
+
+## ⚙️ Configuration
+
+The gateway configuration is stored at `.kalshi-trading-bot-cli/gateway.json`. It's auto-created when you run `gateway:login`.
+
+**Self-chat configuration** (personal phone, message yourself):
+```json
+{
+  "gateway": {
+    "accountId": "default",
+    "logLevel": "info"
+  },
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "allowFrom": ["+1234567890"]
+    }
+  },
+  "bindings": []
+}
+```
+
+**Bot phone configuration** (dedicated bot phone, others message it):
+```json
+{
+  "gateway": {
+    "accountId": "default",
+    "logLevel": "info"
+  },
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "accounts": {
+        "default": {
+          "dmPolicy": "allowlist",
+          "allowFrom": ["+1555YOURNUM"],
+          "groupPolicy": "disabled",
+          "groupAllowFrom": []
+        }
+      },
+      "allowFrom": ["+1555YOURNUM"]
+    }
+  },
+  "bindings": []
+}
+```
+
+**Key settings:**
+
+| Setting | Description |
+|---------|-------------|
+| `channels.whatsapp.allowFrom` | Phone numbers allowed to message the bot (E.164 format) |
+| `channels.whatsapp.enabled` | Enable/disable the WhatsApp channel |
+| `accounts.<id>.dmPolicy` | DM access policy: `pairing` (default), `allowlist`, `open`, or `disabled` |
+| `accounts.<id>.allowFrom` | Per-account allowed senders (overrides top-level `allowFrom`) |
+| `gateway.logLevel` | Log verbosity: `silent`, `error`, `info`, `debug` |
+
+## 👥 Group Chat
+
+The bot can participate in WhatsApp group chats, responding only when @-mentioned.
+
+### Setup
+
+Add group policy to your account in `.kalshi-trading-bot-cli/gateway.json`:
+
+```jsonc
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "accounts": {
+        "default": {
+          "groupPolicy": "open",       // "open", "allowlist", or "disabled"
+          "groupAllowFrom": ["*"]       // no need to list individual group members
+        }
+      },
+      "allowFrom": ["+1234567890"]      // existing DM allowlist (unrelated to groups)
+    }
+  }
+}
+```
+
+| Setting | Description |
+|---------|-------------|
+| `groupPolicy` | `"open"` (any group), `"allowlist"` (restricted), or `"disabled"` (default) |
+| `groupAllowFrom` | Which groups the bot can participate in (`["*"]` for any) |
+
+You don't need to list individual group members — when `groupPolicy` is `"open"`, the bot will respond to @-mentions from anyone in any group it's added to.
+
+### Usage
+
+1. Add the bot's WhatsApp number to a group
+2. Send messages normally — the bot stays silent
+3. @-mention the bot (tap `@` and select from the picker) to get a response
+4. The bot sees recent group messages for context, so it can follow the conversation
+
+**Note:** You must use WhatsApp's @-mention picker (tap `@` then select the contact) — typing a phone number manually won't trigger a response.
+
+## 🔄 How to Relink
+
+If you need to relink your WhatsApp (e.g., after logging out or switching phones):
+
+1. Stop the gateway (Ctrl+C)
+2. Delete the credentials:
+   ```bash
+   rm -rf .kalshi-trading-bot-cli/credentials/whatsapp/default
+   ```
+3. Run login again:
+   ```bash
+   bun run gateway:login
+   ```
+4. Scan the new QR code
+
+## 🐛 Troubleshooting
+
+**Gateway shows "Disconnected":**
+- Check your internet connection
+- Try relinking (see above)
+
+**Messages not being received:**
+- Verify your phone number is in `allowFrom` in `.kalshi-trading-bot-cli/gateway.json`
+- Make sure you're messaging yourself (self-chat mode)
+
+**Debug logs:**
+- Check `.kalshi-trading-bot-cli/gateway-debug.log` for detailed logs
+
+## 🔧 Full Reset
+
+If you're experiencing persistent issues (connection problems, encryption errors, messages not sending), perform a full reset:
+
+1. **Stop the gateway** (Ctrl+C if running)
+
+2. **Unlink from WhatsApp:**
+   - Open WhatsApp on your phone
+   - Go to **Settings > Linked Devices**
+   - Tap on the device and select **Log Out**
+
+3. **Clear all local data:**
+   ```bash
+   rm -rf .kalshi-trading-bot-cli/credentials/whatsapp/default
+   rm -rf .kalshi-trading-bot-cli/gateway.json
+   rm -rf .kalshi-trading-bot-cli/gateway-debug.log
+   ```
+
+4. **Relink and start fresh:**
+   ```bash
+   bun run gateway:login
+   ```
+
+5. **Scan the QR code** and start the gateway:
+   ```bash
+   bun run gateway
+   ```
+
+This clears all cached credentials and encryption sessions, which resolves most connection issues.

package/src/gateway/channels/whatsapp/auth-store.ts

@@ -0,0 +1,140 @@
+import { existsSync, statSync, readFileSync, copyFileSync, rmSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export function resolveCredsPath(authDir: string): string {
+  return join(authDir, 'creds.json');
+}
+
+export function resolveCredsBackupPath(authDir: string): string {
+  return join(authDir, 'creds.json.bak');
+}
+
+export function hasCredsSync(authDir: string): boolean {
+  try {
+    const stats = statSync(resolveCredsPath(authDir));
+    return stats.isFile() && stats.size > 1;
+  } catch {
+    return false;
+  }
+}
+
+function readCredsJsonRaw(filePath: string): string | null {
+  try {
+    if (!existsSync(filePath)) {
+      return null;
+    }
+    const stats = statSync(filePath);
+    if (!stats.isFile() || stats.size <= 1) {
+      return null;
+    }
+    return readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * If creds.json is missing or corrupted, restore from backup if available.
+ */
+export function maybeRestoreCredsFromBackup(authDir: string): void {
+  try {
+    const credsPath = resolveCredsPath(authDir);
+    const backupPath = resolveCredsBackupPath(authDir);
+    const raw = readCredsJsonRaw(credsPath);
+    if (raw) {
+      // Validate that creds.json is parseable
+      JSON.parse(raw);
+      return;
+    }
+
+    const backupRaw = readCredsJsonRaw(backupPath);
+    if (!backupRaw) {
+      return;
+    }
+
+    // Ensure backup is parseable before restoring
+    JSON.parse(backupRaw);
+    copyFileSync(backupPath, credsPath);
+    console.log('Restored WhatsApp creds.json from backup');
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Back up creds.json before saving new credentials.
+ */
+export function backupCredsBeforeSave(authDir: string): void {
+  try {
+    const credsPath = resolveCredsPath(authDir);
+    const backupPath = resolveCredsBackupPath(authDir);
+    const raw = readCredsJsonRaw(credsPath);
+    if (raw) {
+      // Validate before backing up
+      JSON.parse(raw);
+      copyFileSync(credsPath, backupPath);
+    }
+  } catch {
+    // ignore backup failures
+  }
+}
+
+/**
+ * Check if valid WhatsApp credentials exist.
+ */
+export async function authExists(authDir: string): Promise<boolean> {
+  maybeRestoreCredsFromBackup(authDir);
+  const credsPath = resolveCredsPath(authDir);
+  try {
+    const stats = statSync(credsPath);
+    if (!stats.isFile() || stats.size <= 1) {
+      return false;
+    }
+    const raw = readFileSync(credsPath, 'utf-8');
+    JSON.parse(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract the linked phone number from stored credentials.
+ * Returns E.164 format (e.g., "+1234567890") and raw JID.
+ */
+export function readSelfId(authDir: string): { e164: string | null; jid: string | null } {
+  try {
+    const credsPath = resolveCredsPath(authDir);
+    if (!existsSync(credsPath)) {
+      return { e164: null, jid: null };
+    }
+    const raw = readFileSync(credsPath, 'utf-8');
+    const parsed = JSON.parse(raw) as { me?: { id?: string } } | undefined;
+    const jid = parsed?.me?.id ?? null;
+    // JID format: "1234567890:123@s.whatsapp.net" -> "+1234567890"
+    const e164 = jid ? jidToE164(jid) : null;
+    return { e164, jid };
+  } catch {
+    return { e164: null, jid: null };
+  }
+}
+
+function jidToE164(jid: string): string | null {
+  const match = jid.match(/^(\d+):/);
+  return match ? `+${match[1]}` : null;
+}
+
+/**
+ * Clear WhatsApp credentials (logout).
+ */
+export async function logout(authDir: string): Promise<boolean> {
+  const exists = await authExists(authDir);
+  if (!exists) {
+    console.log('No WhatsApp session found; nothing to delete.');
+    return false;
+  }
+  await rm(authDir, { recursive: true, force: true });
+  console.log('Cleared WhatsApp credentials.');
+  return true;
+}

package/src/gateway/channels/whatsapp/dedupe.ts

@@ -0,0 +1,60 @@
+const RECENT_MESSAGE_TTL_MS = 20 * 60_000; // 20 minutes
+const RECENT_MESSAGE_MAX = 5000;
+
+type CacheEntry = {
+  key: string;
+  timestamp: number;
+};
+
+const cache = new Map<string, CacheEntry>();
+const insertionOrder: string[] = [];
+
+function pruneExpired(): void {
+  const now = Date.now();
+  const cutoff = now - RECENT_MESSAGE_TTL_MS;
+
+  // Remove expired entries from the front of insertion order
+  while (insertionOrder.length > 0) {
+    const oldestKey = insertionOrder[0];
+    const entry = cache.get(oldestKey);
+    if (entry && entry.timestamp < cutoff) {
+      cache.delete(oldestKey);
+      insertionOrder.shift();
+    } else {
+      break;
+    }
+  }
+
+  // Enforce max size
+  while (cache.size > RECENT_MESSAGE_MAX && insertionOrder.length > 0) {
+    const oldestKey = insertionOrder.shift();
+    if (oldestKey) {
+      cache.delete(oldestKey);
+    }
+  }
+}
+
+/**
+ * Check if a message ID was recently seen.
+ * Returns true if it's a duplicate (already seen), false if new.
+ * Automatically adds the key to the cache if not seen before.
+ */
+export function isRecentInboundMessage(key: string): boolean {
+  pruneExpired();
+
+  if (cache.has(key)) {
+    return true;
+  }
+
+  cache.set(key, { key, timestamp: Date.now() });
+  insertionOrder.push(key);
+  return false;
+}
+
+/**
+ * Clear the deduplication cache (useful for testing).
+ */
+export function resetInboundDedupe(): void {
+  cache.clear();
+  insertionOrder.length = 0;
+}

package/src/gateway/channels/whatsapp/error.ts

@@ -0,0 +1,122 @@
+import { getStatusCode } from './session.js';
+
+function safeStringify(value: unknown, limit = 800): string {
+  try {
+    const seen = new WeakSet();
+    const raw = JSON.stringify(
+      value,
+      (_key, v) => {
+        if (typeof v === 'bigint') {
+          return v.toString();
+        }
+        if (typeof v === 'function') {
+          const maybeName = (v as { name?: unknown }).name;
+          const name =
+            typeof maybeName === 'string' && maybeName.length > 0 ? maybeName : 'anonymous';
+          return `[Function ${name}]`;
+        }
+        if (typeof v === 'object' && v) {
+          if (seen.has(v)) {
+            return '[Circular]';
+          }
+          seen.add(v);
+        }
+        return v;
+      },
+      2,
+    );
+    if (!raw) {
+      return String(value);
+    }
+    return raw.length > limit ? `${raw.slice(0, limit)}…` : raw;
+  } catch {
+    return String(value);
+  }
+}
+
+function extractBoomDetails(err: unknown): {
+  statusCode?: number;
+  error?: string;
+  message?: string;
+} | null {
+  if (!err || typeof err !== 'object') {
+    return null;
+  }
+  const output = (err as { output?: unknown })?.output as
+    | { statusCode?: unknown; payload?: unknown }
+    | undefined;
+  if (!output || typeof output !== 'object') {
+    return null;
+  }
+  const payload = (output as { payload?: unknown }).payload as
+    | { error?: unknown; message?: unknown; statusCode?: unknown }
+    | undefined;
+  const statusCode =
+    typeof (output as { statusCode?: unknown }).statusCode === 'number'
+      ? ((output as { statusCode?: unknown }).statusCode as number)
+      : typeof payload?.statusCode === 'number'
+        ? payload.statusCode
+        : undefined;
+  const error = typeof payload?.error === 'string' ? payload.error : undefined;
+  const message = typeof payload?.message === 'string' ? payload.message : undefined;
+  if (!statusCode && !error && !message) {
+    return null;
+  }
+  return { statusCode, error, message };
+}
+
+/**
+ * Format Baileys errors into human-readable messages.
+ * Handles nested Boom error structures.
+ */
+export function formatError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  if (typeof err === 'string') {
+    return err;
+  }
+  if (!err || typeof err !== 'object') {
+    return String(err);
+  }
+
+  // Baileys frequently wraps errors under `error` with a Boom-like shape.
+  const boom =
+    extractBoomDetails(err) ??
+    extractBoomDetails((err as { error?: unknown })?.error) ??
+    extractBoomDetails((err as { lastDisconnect?: { error?: unknown } })?.lastDisconnect?.error);
+
+  const status = boom?.statusCode ?? getStatusCode(err);
+  const code = (err as { code?: unknown })?.code;
+  const codeText = typeof code === 'string' || typeof code === 'number' ? String(code) : undefined;
+
+  const messageCandidates = [
+    boom?.message,
+    typeof (err as { message?: unknown })?.message === 'string'
+      ? ((err as { message?: unknown }).message as string)
+      : undefined,
+    typeof (err as { error?: { message?: unknown } })?.error?.message === 'string'
+      ? ((err as { error?: { message?: unknown } }).error?.message as string)
+      : undefined,
+  ].filter((v): v is string => Boolean(v && v.trim().length > 0));
+  const message = messageCandidates[0];
+
+  const pieces: string[] = [];
+  if (typeof status === 'number') {
+    pieces.push(`status=${status}`);
+  }
+  if (boom?.error) {
+    pieces.push(boom.error);
+  }
+  if (message) {
+    pieces.push(message);
+  }
+  if (codeText) {
+    pieces.push(`code=${codeText}`);
+  }
+
+  if (pieces.length > 0) {
+    return pieces.join(' ');
+  }
+  return safeStringify(err);
+}