fca-neokex-fix 1.0.1

package/THEME_FEATURES.md

@@ -0,0 +1,137 @@
+# Theme Management Features
+
+This document explains the theme-related features in NeoKEX-FCA v4.2.5.
+
+## 📚 Documentation
+
+- **[README](README.md)** - Getting started and overview
+- **[API Reference](API_REFERENCE.md)** - Complete API documentation
+- **[Bot Testing](BOT_TESTING.md)** - Test bot examples
+- **[Contributing](CONTRIBUTING.md)** - Contribution guidelines
+- **[Changelog](CHANGELOG.md)** - Version history
+
+---
+
+## Available Functions
+
+### 1. `getTheme(threadID)`
+Retrieves all available Facebook Messenger themes.
+
+```javascript
+const themes = await api.getTheme(threadID);
+console.log(`Found ${themes.length} themes!`);
+themes.forEach(theme => {
+  console.log(`- ${theme.name} (ID: ${theme.id})`);
+});
+```
+
+**Returns:** Array of theme objects with `id`, `name`, `theme_idx`, and `accessibility_label`.
+
+### 2. `getThemeInfo(threadID)`
+Gets the current theme information for a specific thread.
+
+```javascript
+const info = await api.getThemeInfo(threadID);
+console.log(`Thread: ${info.threadName}`);
+console.log(`Color: ${info.color}`);
+console.log(`Emoji: ${info.emoji}`);
+console.log(`Theme ID: ${info.theme_id}`);
+```
+
+**Returns:** Object containing thread name, color, emoji, theme_id, and more.
+
+### 3. `createAITheme(prompt)`
+Generates AI-powered custom themes based on a text prompt.
+
+```javascript
+try {
+  const aiThemes = await api.createAITheme("sunset ocean vibes");
+  console.log(`Generated ${aiThemes.length} AI themes!`);
+} catch (e) {
+  if (e.code === 'FEATURE_UNAVAILABLE') {
+    console.log("AI themes not available for this account");
+  }
+}
+```
+
+**Important:** AI theme generation is restricted by Facebook to specific accounts/regions. If unavailable for your account, you'll receive a `FEATURE_UNAVAILABLE` error - this is normal and not a bug.
+
+### 4. `setThreadThemeMqtt(threadID, themeID)`
+Applies a theme to a conversation thread.
+
+```javascript
+const themes = await api.getTheme(threadID);
+const blueTheme = themes.find(t => t.name.includes("Blue"));
+await api.setThreadThemeMqtt(threadID, blueTheme.id);
+console.log("Theme applied!");
+```
+
+## Complete Example
+
+See `examples/theme-usage-example.js` for a full working example.
+
+## Error Handling
+
+### Error 1545012 Fix with Automatic Retry
+
+**New in v4.2.4:** Error 1545012 ("Not part of conversation") now includes intelligent retry logic to handle temporary Facebook API glitches.
+
+**What changed:**
+- The API now automatically retries up to 3 times with exponential backoff (1s, 2s, 3s)
+- Between retries, it verifies your bot's membership using `getThreadInfo`
+- If the bot is confirmed NOT in the group, it fails immediately
+- If the bot IS in the group, it retries automatically
+
+**Why this matters:**
+Facebook often returns error 1545012 even when your bot IS in the group due to:
+- Stale thread membership cache on Facebook's side
+- Recent re-joins not yet propagated
+- Temporary backend hiccups
+
+This fix masks transient errors while still catching real "not in group" cases.
+
+```javascript
+try {
+  await api.sendMessage("Hello", threadID);
+} catch (err) {
+  if (err.code === 1545012) {
+    if (err.verified) {
+      console.log(`Confirmed: Bot is NOT in conversation ${err.threadID}`);
+    } else {
+      console.log(`Error persisted after ${err.attempts} retries for ${err.threadID}`);
+    }
+  }
+}
+```
+
+The error now includes:
+- `code`: 1545012
+- `threadID`: The thread you tried to message
+- `messageID`: The generated message ID
+- `timestamp`: When the error occurred
+- `attempts`: Number of retry attempts made
+- `verified`: Whether membership was verified via getThreadInfo
+
+## Testing
+
+Run the comprehensive test suite:
+
+```bash
+node test/theme-complete-test.js
+```
+
+This validates all theme functionality and clearly distinguishes between working features and Facebook-imposed restrictions.
+
+## Notes
+
+- **Standard themes**: Always work for all accounts (93+ themes available)
+- **AI themes**: May not be available depending on your Facebook account's region/permissions
+- **MQTT required**: Theme operations require an active MQTT connection via `api.listenMqtt()`
+
+---
+
+## See Also
+
+- **[API Reference](API_REFERENCE.md)** - Complete documentation of all API methods including theme functions
+- **[Bot Testing](BOT_TESTING.md)** - Test the theme commands with the test bot
+- **[README](README.md)** - Main project documentation

package/examples/README.md

@@ -0,0 +1,131 @@
+# NeoKEX-FCA Example Bot
+
+A comprehensive test bot demonstrating all API functions of NeoKEX-FCA.
+
+## Quick Start
+
+```bash
+# Make sure you have appstate.json in test/ directory
+node examples/test-bot.js
+```
+
+## Available Commands
+
+### 📌 Basic Commands
+- `/help` - Show all available commands
+- `/ping` - Test bot response time
+- `/about` - Bot information and stats
+
+### 👤 User Information
+- `/me` - Get your user information
+- `/user <name>` - Search for a user
+- `/friends` - List your friends (first 10)
+- `/userid <name>` - Get user ID by name
+
+### 💬 Thread Commands
+- `/info` - Get current thread information
+- `/history [limit]` - Get message history (default: 5 messages)
+- `/members` - List all thread members
+- `/photo` - Get thread photo URL
+
+### 🎨 Theme Commands
+- `/themes` - List all available themes
+- `/theme <name>` - Change thread theme by name or ID
+- `/color <hex>` - Change thread color (e.g., `/color #0084ff`)
+- `/aitheme <prompt>` - Generate AI theme (e.g., `/aitheme ocean sunset`)
+
+### ✏️ Thread Settings
+- `/name <new name>` - Change thread name
+- `/emoji <emoji>` - Change thread emoji (e.g., `/emoji 🔥`)
+- `/nickname @mention <nickname>` - Set someone's nickname
+
+### 📎 Messaging Features
+- `/typing` - Send typing indicator
+- `/react <emoji>` - React to your command message
+- `/unsend` - Unsend your command message
+- `/poll <question> | <option1> | <option2>` - Create a poll
+
+### 🔍 Search Commands
+- `/search <query>` - Search for users
+- `/searchthread <query>` - Search for threads
+
+### 📊 Status & Testing
+- `/status` - Bot status and uptime
+- `/test` - Run quick API function tests
+
+## Examples
+
+```
+/ping
+→ 🏓 Pong! Response time: 123ms
+
+/search John Doe
+→ 🔍 Search results for "John Doe"...
+
+/theme love
+→ ✅ Theme changed to: love
+
+/poll Best pizza? | Pepperoni | Hawaiian | Veggie
+→ Creates a poll with 3 options
+
+/test
+→ Runs 4 quick API tests
+```
+
+## Features Tested
+
+This bot demonstrates:
+- ✅ Message listening (MQTT)
+- ✅ User information retrieval
+- ✅ Thread management
+- ✅ Theme operations (GraphQL + MQTT)
+- ✅ Search functionality
+- ✅ Messaging features
+- ✅ Thread customization
+- ✅ Status monitoring
+
+## API Functions Coverage
+
+**Total Functions Tested: 25+**
+- Authentication & Session
+- Messaging (send, react, unsend)
+- Thread Management (info, history, members)
+- User Search & Info
+- Theme Operations (list, change, AI generation)
+- Thread Settings (name, emoji, nickname)
+- Typing indicators
+- Polls
+- Search operations
+
+## Notes
+
+- All commands use `/` prefix
+- Some commands require MQTT connection
+- Theme changes require MQTT to be active
+- Error handling included for all commands
+- Responds with helpful error messages
+
+## Troubleshooting
+
+**Bot not responding?**
+- Check MQTT connection status
+- Verify appstate.json is valid
+- Ensure bot has permission in the thread
+
+**Commands failing?**
+- Use `/status` to check bot health
+- Use `/test` to verify API functions
+- Check console for error messages
+
+## Architecture
+
+```
+test-bot.js
+├── Login with appstate
+├── Initialize MQTT listener
+├── Parse commands (prefix: /)
+├── Route to command handlers
+└── Error handling & logging
+```
+
+Built with NeoKEX-FCA v4.4.4 - 98.2% API success rate

package/examples/apply-ai-theme.js

@@ -0,0 +1,127 @@
+/**
+ * AI Theme Generation and Application Example
+ * 
+ * Usage:
+ *   node examples/apply-ai-theme.js "theme prompt" "thread_id"
+ * 
+ * Example:
+ *   node examples/apply-ai-theme.js "vibrant purple pink ocean sunset" "123456789"
+ * 
+ * Note: AI theme generation requires Facebook account-level access.
+ * If unavailable, use standard themes via api.getTheme() instead.
+ */
+
+const fs = require("fs");
+const { login } = require("../index");
+
+const APPSTATE_PATH = "appstate.json";
+const AI_THEME_PROMPT = process.argv[2] || "vibrant purple pink ocean sunset";
+// Replace with your actual thread ID (find it in messenger URL or use api.getThreadList())
+const THREAD_ID = process.argv[3] || "YOUR_THREAD_ID_HERE";
+
+if (THREAD_ID === "YOUR_THREAD_ID_HERE") {
+  console.error("❌ Please provide a thread ID:");
+  console.error('   node examples/apply-ai-theme.js "theme prompt" "thread_id"');
+  process.exit(1);
+}
+
+if (!fs.existsSync(APPSTATE_PATH)) {
+  console.error("❌ appstate.json is required.");
+  process.exit(1);
+}
+
+const credentials = { appState: JSON.parse(fs.readFileSync(APPSTATE_PATH, "utf8")) };
+
+console.log("🔐 Logging in...");
+
+login(credentials, {
+  online: true,
+  updatePresence: true,
+  selfListen: false
+}, async (err, api) => {
+  if (err) {
+    console.error("❌ LOGIN ERROR:", err);
+    process.exit(1);
+  }
+
+  console.log(`✅ Logged in as: ${api.getCurrentUserID()}`);
+  
+  console.log("🔌 Starting MQTT listener...");
+  api.listenMqtt((err, event) => {
+    if (err) console.error("MQTT Error:", err);
+  });
+  
+  await new Promise(resolve => setTimeout(resolve, 3000));
+  console.log("✅ MQTT connection established\n");
+
+  try {
+    console.log("═══════════════════════════════════════════════════════");
+    console.log(`🎨 AI THEME GENERATION AND APPLICATION`);
+    console.log("═══════════════════════════════════════════════════════\n");
+
+    console.log(`📝 Prompt: "${AI_THEME_PROMPT}"`);
+    
+    console.log("\n🎨 Step 1: Generating AI theme...");
+    const aiThemes = await api.createAITheme(AI_THEME_PROMPT);
+    
+    if (!aiThemes || aiThemes.length === 0) {
+      console.error("❌ No themes generated!");
+      process.exit(1);
+    }
+    
+    console.log(`✅ AI theme generated!`);
+    console.log(`   Theme ID: ${aiThemes[0].id}`);
+    console.log(`   Name: ${aiThemes[0].accessibility_label || AI_THEME_PROMPT}`);
+    
+    console.log("\n⏳ Waiting 2 seconds before applying...");
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    
+    console.log("\n🔄 Step 2: Applying theme to thread...");
+    console.log(`   Thread ID: ${THREAD_ID}`);
+    console.log(`   Theme ID: ${aiThemes[0].id}`);
+    
+    // Apply using callback to catch errors
+    await new Promise((resolve, reject) => {
+      api.setThreadThemeMqtt(THREAD_ID, aiThemes[0].id, (err) => {
+        if (err) {
+          console.error("❌ Error in setThreadThemeMqtt:", err);
+          reject(err);
+        } else {
+          console.log("✅ MQTT publish completed");
+          resolve();
+        }
+      });
+    });
+    
+    console.log("\n⏳ Waiting 3 seconds for theme to sync...");
+    await new Promise(resolve => setTimeout(resolve, 3000));
+    
+    console.log("\n📋 Step 3: Verifying theme was applied...");
+    const themeInfo = await api.getThemeInfo(THREAD_ID);
+    
+    console.log("\n═══════════════════════════════════════════════════════");
+    console.log("📊 VERIFICATION RESULTS");
+    console.log("═══════════════════════════════════════════════════════");
+    console.log(`Thread Name: ${themeInfo.threadName || 'Unnamed'}`);
+    console.log(`Current Color: ${themeInfo.color || 'Default'}`);
+    console.log(`Theme ID: ${themeInfo.theme_id || 'None'}`);
+    console.log(`Expected Theme ID: ${aiThemes[0].id}`);
+    console.log(`Match: ${themeInfo.theme_id === aiThemes[0].id ? '✅ YES' : '❌ NO'}`);
+    
+    if (themeInfo.theme_id === aiThemes[0].id) {
+      console.log("\n🎉 SUCCESS! AI theme applied successfully!");
+    } else {
+      console.log("\n⚠️  Theme generated but not applied. Theme ID mismatch.");
+      console.log("This might be a timing issue or MQTT delivery problem.");
+    }
+    
+    console.log("═══════════════════════════════════════════════════════\n");
+    
+    process.exit(0);
+
+  } catch (error) {
+    console.error("\n❌ Error occurred:", error.message || error);
+    console.error("Stack:", error.stack);
+    process.exit(1);
+  }
+});

package/examples/check-current-theme.js

@@ -0,0 +1,74 @@
+/**
+ * Check Current Thread Theme Example
+ * 
+ * Usage:
+ *   node examples/check-current-theme.js "thread_id"
+ * 
+ * Example:
+ *   node examples/check-current-theme.js "123456789"
+ */
+
+const fs = require("fs");
+const { login } = require("../index");
+
+const APPSTATE_PATH = "appstate.json";
+// Replace with your actual thread ID (find it in messenger URL or use api.getThreadList())
+const THREAD_ID = process.argv[2] || "YOUR_THREAD_ID_HERE";
+
+if (THREAD_ID === "YOUR_THREAD_ID_HERE") {
+  console.error("❌ Please provide a thread ID:");
+  console.error('   node examples/check-current-theme.js "thread_id"');
+  process.exit(1);
+}
+
+if (!fs.existsSync(APPSTATE_PATH)) {
+  console.error("❌ appstate.json is required.");
+  process.exit(1);
+}
+
+const credentials = { appState: JSON.parse(fs.readFileSync(APPSTATE_PATH, "utf8")) };
+
+console.log("🔐 Logging in...");
+
+login(credentials, {
+  online: true,
+  updatePresence: true,
+  selfListen: false
+}, async (err, api) => {
+  if (err) {
+    console.error("❌ LOGIN ERROR:", err);
+    process.exit(1);
+  }
+
+  console.log(`✅ Logged in as: ${api.getCurrentUserID()}`);
+  
+  console.log("🔌 Starting MQTT listener...");
+  api.listenMqtt((err, event) => {
+    if (err) console.error("MQTT Error:", err);
+  });
+  
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  console.log("✅ MQTT connection established\n");
+
+  try {
+    console.log("📋 Checking current theme for thread:", THREAD_ID);
+    const themeInfo = await api.getThemeInfo(THREAD_ID);
+    
+    console.log("\n═══════════════════════════════════════════════════════");
+    console.log("🎨 CURRENT THREAD THEME INFO");
+    console.log("═══════════════════════════════════════════════════════");
+    console.log(JSON.stringify(themeInfo, null, 2));
+    console.log("═══════════════════════════════════════════════════════\n");
+    
+    console.log("Thread Name:", themeInfo.threadName || 'Unnamed');
+    console.log("Current Color:", themeInfo.color || 'Default');
+    console.log("Current Emoji:", themeInfo.emoji || 'None');
+    console.log("Theme ID:", themeInfo.theme_id || 'None/Default');
+    
+    process.exit(0);
+
+  } catch (error) {
+    console.error("\n❌ Error:", error.message || error);
+    process.exit(1);
+  }
+});

package/examples/simple-bot.js

@@ -0,0 +1,114 @@
+/**
+ * Simple NeoKEX-FCA Bot Example
+ * 
+ * A minimal bot demonstrating basic functionality:
+ * - Auto-reply to mentions
+ * - Command handling
+ * - Basic info commands
+ */
+
+const { login } = require('../index');
+const fs = require('fs');
+const path = require('path');
+
+const APPSTATE_PATH = path.join(__dirname, '../test/appstate.json');
+const appState = JSON.parse(fs.readFileSync(APPSTATE_PATH, 'utf8'));
+
+console.log('🤖 Simple Bot Starting...\n');
+
+login({ appState }, (err, api) => {
+  if (err) {
+    console.error('❌ Login failed:', err);
+    return;
+  }
+
+  console.log('✅ Bot is online!');
+  const botID = api.getCurrentUserID();
+  
+  api.listenMqtt((err, event) => {
+    if (err) return console.error('Error:', err);
+    
+    if (event.type === 'message' && event.body) {
+      const { threadID, senderID, body } = event;
+      
+      // Ignore own messages
+      if (senderID === botID) return;
+      
+      // Auto-reply to mentions
+      if (event.mentions && event.mentions[botID]) {
+        api.sendMessage('👋 You mentioned me! Type "!help" for commands.', threadID);
+        return;
+      }
+      
+      // Command handling
+      if (body.startsWith('!')) {
+        handleCommand(api, body.substring(1).trim(), threadID, senderID);
+      }
+    }
+  });
+  
+  console.log('✅ Listening for messages...\n');
+});
+
+async function handleCommand(api, cmd, threadID, senderID) {
+  const [command, ...args] = cmd.split(' ');
+  
+  try {
+    switch (command.toLowerCase()) {
+      case 'help':
+        await api.sendMessage(`🤖 Simple Bot Commands
+
+!help - Show this menu
+!ping - Check if bot is alive
+!time - Current time
+!info - Thread information
+!me - Your user info
+!theme <name> - Change theme
+
+Example: !theme love`, threadID);
+        break;
+        
+      case 'ping':
+        await api.sendMessage('🏓 Pong! Bot is alive!', threadID);
+        break;
+        
+      case 'time':
+        await api.sendMessage(`⏰ ${new Date().toLocaleString()}`, threadID);
+        break;
+        
+      case 'info':
+        const info = await api.getThreadInfo(threadID);
+        await api.sendMessage(`💬 Thread: ${info.threadName || 'Unnamed'}
+👥 Members: ${info.participantIDs.length}
+💬 Messages: ${info.messageCount || 'Unknown'}`, threadID);
+        break;
+        
+      case 'me':
+        const userInfo = await api.getUserInfo(senderID);
+        const user = userInfo[senderID];
+        await api.sendMessage(`👤 ${user.name}
+🆔 ${senderID}`, threadID);
+        break;
+        
+      case 'theme':
+        if (args.length === 0) {
+          await api.sendMessage('❌ Usage: !theme <name>', threadID);
+          break;
+        }
+        await api.theme(args.join(' '), threadID);
+        await api.sendMessage(`✅ Theme changed!`, threadID);
+        break;
+        
+      default:
+        await api.sendMessage(`❓ Unknown command. Type !help for help.`, threadID);
+    }
+  } catch (error) {
+    console.error('Command error:', error);
+    await api.sendMessage(`❌ Error: ${error.message}`, threadID);
+  }
+}
+
+process.on('SIGINT', () => {
+  console.log('\n👋 Shutting down...');
+  process.exit(0);
+});