linkedin-automation-cli 1.0.0

package/docs/plans/2026-02-28-messages-send-feature.md

@@ -0,0 +1,480 @@
+# Messages Send Feature Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a new `messages send` command that can start a new conversation with a LinkedIn profile URL.
+
+**Architecture:** Create a new `LinkedInMessageSender` class that navigates to a profile page, finds and clicks the "Message" button, and sends a message. The CLI command will accept a profile URL and message text.
+
+**Tech Stack:** TypeScript, Playwright for browser automation, Commander.js for CLI
+
+---
+
+### Task 1: Add TypeScript types for send message feature
+
+**Files:**
+- Modify: `src/types/index.ts:17-29`
+
+**Step 1: Add new types to types/index.ts**
+
+Add after the `Message` interface (around line 29):
+
+```typescript
+// New message sending types
+export interface SendMessageOptions {
+  profileUrl: string;
+  text: string;
+  dryRun?: boolean;
+}
+
+export interface SendMessageResult {
+  success: boolean;
+  messageId?: string;
+  threadId?: string;
+  error?: string;
+}
+```
+
+**Step 2: Verify types compile**
+
+Run: `npm run build`
+Expected: No errors
+
+**Step 3: Commit**
+
+```bash
+git add src/types/index.ts
+git commit -m "types: add SendMessageOptions and SendMessageResult interfaces"
+```
+
+---
+
+### Task 2: Create LinkedInMessageSender class
+
+**Files:**
+- Create: `src/linkedin/message-sender.ts`
+
+**Step 1: Create the message sender class**
+
+```typescript
+import type { Page } from 'playwright';
+import { SelectorEngine } from './selector-engine';
+
+export interface SendMessageOptions {
+  profileUrl: string;
+  text: string;
+  dryRun?: boolean;
+}
+
+export interface SendMessageResult {
+  success: boolean;
+  messageId?: string;
+  threadId?: string;
+  error?: string;
+}
+
+export class LinkedInMessageSender {
+  private page: Page;
+  private selectorEngine: SelectorEngine;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.selectorEngine = new SelectorEngine(page);
+  }
+
+  /**
+   * Send a message to a LinkedIn profile
+   */
+  async sendMessage(options: SendMessageOptions): Promise<SendMessageResult> {
+    try {
+      // Navigate to profile
+      await this.page.goto(options.profileUrl, {
+        waitUntil: 'networkidle',
+        timeout: 30000,
+      });
+
+      // Wait for page to load
+      await this.page.waitForTimeout(2000);
+
+      // Find and click the Message button
+      const messageButton = await this.findMessageButton();
+      if (!messageButton) {
+        return { success: false, error: 'Could not find Message button on profile' };
+      }
+
+      // Click message button - this opens or navigates to conversation
+      await messageButton.click();
+
+      // Wait for messaging UI to load
+      await this.page.waitForTimeout(2000);
+
+      // Wait for message input field
+      const inputResult = await this.selectorEngine.findElement('messages', 'messageInput', {
+        timeout: 10000,
+        visible: true,
+      });
+
+      if (!inputResult.element) {
+        return { success: false, error: 'Could not find message input field' };
+      }
+
+      // Type the message
+      await inputResult.element.fill(options.text);
+
+      // Check if dry run
+      if (options.dryRun) {
+        return {
+          success: true,
+          messageId: `dry-run-${Date.now()}`,
+          threadId: this.extractThreadId(),
+        };
+      }
+
+      // Click send button
+      const sendResult = await this.selectorEngine.findElement('messages', 'sendButton', {
+        timeout: 5000,
+        visible: true,
+      });
+
+      if (!sendResult.element) {
+        return { success: false, error: 'Could not find send button' };
+      }
+
+      await sendResult.element.click();
+
+      // Wait for message to be sent
+      await this.page.waitForTimeout(1000);
+
+      // Try to get message ID
+      const messageId = await this.page.evaluate(() => {
+        const lastMessage = document.querySelector('[data-urn*="urn:li:fsd_message:"]');
+        if (lastMessage) {
+          const urn = lastMessage.getAttribute('data-urn');
+          if (urn) {
+            const match = urn.match(/urn:li:fsd_message:(\d+)/);
+            return match ? match[1] : urn;
+          }
+        }
+        return `msg-${Date.now()}`;
+      });
+
+      return {
+        success: true,
+        messageId,
+        threadId: this.extractThreadId(),
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error sending message',
+      };
+    }
+  }
+
+  /**
+   * Find the Message button on a profile page
+   */
+  private async findMessageButton() {
+    // Try multiple selector strategies
+    const selectors = [
+      'button[aria-label*="Message"]',
+      'button:has-text("Message")',
+      'a[href*="messaging/compose"]',
+      '[data-test-message-btn]',
+    ];
+
+    for (const selector of selectors) {
+      try {
+        const button = await this.page.$(selector);
+        if (button) {
+          return button;
+        }
+      } catch {
+        // Continue to next selector
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Extract thread ID from current URL
+   */
+  private extractThreadId(): string | undefined {
+    const url = this.page.url();
+    const match = url.match(/\/messaging\/thread\/([^/]+)/);
+    return match ? match[1] : undefined;
+  }
+}
+```
+
+**Step 2: Verify types compile**
+
+Run: `npm run build`
+Expected: No errors
+
+**Step 3: Commit**
+
+```bash
+git add src/linkedin/message-sender.ts
+git commit -m "feat(message-sender): create LinkedInMessageSender class for new conversations"
+```
+
+---
+
+### Task 3: Add selectors for message sending
+
+**Files:**
+- Modify: `src/linkedin/selectors.ts:42-64`
+
+**Step 1: Add message button selector**
+
+Add to the `messages` section:
+
+```typescript
+messages: {
+  // ... existing selectors ...
+  messageButton: [
+    'button[aria-label*="Message"]',
+    'button:has-text("Message")',
+    'a[href*="messaging/compose"]',
+    '[data-test-message-btn]',
+  ],
+  // ... rest of existing selectors ...
+},
+```
+
+**Step 2: Verify compile**
+
+Run: `npm run build`
+Expected: Success
+
+**Step 3: Commit**
+
+```bash
+git add src/linkedin/selectors.ts
+git commit -m "selectors: add message button selectors"
+```
+
+---
+
+### Task 4: Create CLI command for messages send
+
+**Files:**
+- Modify: `src/cli/messages.ts`
+
+**Step 1: Add send command to registerMessageCommands**
+
+Add after the `show` command (around line 187):
+
+```typescript
+  // Send new message
+  messages
+    .command('send')
+    .description('Send a new message to a LinkedIn profile')
+    .requiredOption('-u, --url <profile>', 'LinkedIn profile URL')
+    .requiredOption('-m, --message <text>', 'Message text to send')
+    .option('--dry-run', 'Simulate sending without actually sending', false)
+    .option('--headless', 'Run browser in headless mode', false)
+    .action(async (options) => {
+      const spinner = ora('Preparing to send message...').start();
+
+      try {
+        spinner.text = 'Launching browser...';
+
+        // Launch browser - will connect to existing Edge/Chrome via CDP if available
+        const config = getConfig();
+        const browser = new BrowserController({
+          headless: options.headless ?? config.getValue('headless'),
+        });
+
+        await browser.launch();
+
+        // Get the page
+        const page = browser.getPage();
+        if (!page) throw new Error('Browser page not available');
+
+        spinner.text = options.dryRun ? 'Simulating message send...' : 'Sending message...';
+
+        const sender = new LinkedInMessageSender(page);
+
+        const result = await sender.sendMessage({
+          profileUrl: options.url,
+          text: options.message,
+          dryRun: options.dryRun,
+        });
+
+        if (!result.success) {
+          spinner.fail(`Failed to send message: ${result.error}`);
+          await browser.close();
+          process.exit(1);
+        }
+
+        if (options.dryRun) {
+          spinner.succeed('Dry run completed - message would have been sent');
+          console.log(chalk.gray('Profile URL: ' + options.url));
+          console.log(chalk.gray('Message content:'));
+          console.log(chalk.cyan(options.message));
+          if (result.threadId) {
+            console.log(chalk.gray(`Thread ID: ${result.threadId}`));
+          }
+        } else {
+          spinner.succeed('Message sent successfully!');
+          console.log(chalk.gray(`Thread ID: ${result.threadId}`));
+          if (result.messageId) {
+            console.log(chalk.gray(`Message ID: ${result.messageId}`));
+          }
+        }
+
+        // Log action
+        const logger = getAuditLogger();
+        logger.log(
+          options.dryRun ? 'messages.send.dry-run' : 'messages.send',
+          { profileUrl: options.url, messageLength: options.message.length },
+          true
+        );
+
+        await browser.close();
+      } catch (error) {
+        spinner.fail('Failed to send message');
+        console.error(chalk.red('Error:'), error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+```
+
+**Step 2: Add import for LinkedInMessageSender**
+
+At the top of the file, add:
+
+```typescript
+import { LinkedInMessageSender } from '../linkedin/message-sender';
+```
+
+**Step 3: Verify compile**
+
+Run: `npm run build`
+Expected: Success
+
+**Step 4: Commit**
+
+```bash
+git add src/cli/messages.ts
+git commit -m "cli: add messages send command for new conversations"
+```
+
+---
+
+### Task 5: Test with Lily's profile
+
+**Files:**
+- No file changes
+
+**Step 1: Build the project**
+
+Run: `npm run build`
+Expected: Success
+
+**Step 2: Test dry run first**
+
+Run:
+```bash
+node dist/index.js messages send -u "https://www.linkedin.com/in/lily-q-7145971b9/" -m "Hi Lily, this is a test message from the LinkedIn CLI automation tool. Please ignore." --dry-run
+```
+
+Expected output:
+```
+✔ Dry run completed - message would have been sent
+Profile URL: https://www.linkedin.com/in/lily-q-7145971b9/
+Message content:
+Hi Lily, this is a test message from the LinkedIn CLI automation tool. Please ignore.
+```
+
+**Step 3: Test actual message send**
+
+Run:
+```bash
+node dist/index.js messages send -u "https://www.linkedin.com/in/lily-q-7145971b9/" -m "Hi Lily, this is Thaddeus's LinkedIn automation CLI testing the new message sending feature. This is just a test - no action needed on your end. Thanks!"
+```
+
+Expected output:
+```
+✔ Message sent successfully!
+Thread ID: 2-xxxxx...
+Message ID: xxxxx
+```
+
+**Step 4: Verify message in LinkedIn**
+
+Open your browser and check the messaging conversation with Lily to confirm the message was sent.
+
+**Step 5: Commit any fixes if needed**
+
+If any issues are found during testing, fix them and commit:
+
+```bash
+git add src/linkedin/message-sender.ts
+git commit -m "fix: message sender adjustments based on testing"
+```
+
+---
+
+### Task 6: Add help documentation
+
+**Files:**
+- Modify: `README.md` (if exists in project)
+
+**Step 1: Add documentation for the new command**
+
+Add to the Messages section:
+
+```markdown
+### Send a new message
+
+Send a message to a LinkedIn profile (starts a new conversation):
+
+```bash
+linkedin-cli messages send -u "https://www.linkedin.com/in/profile-url/" -m "Hello!"
+
+# Dry run first (recommended)
+linkedin-cli messages send -u "https://www.linkedin.com/in/profile-url/" -m "Hello!" --dry-run
+```
+
+Options:
+- `-u, --url <profile>` - LinkedIn profile URL (required)
+- `-m, --message <text>` - Message text to send (required)
+- `--dry-run` - Simulate without sending
+- `--headless` - Run browser in headless mode
+```
+
+**Step 2: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: add messages send command documentation"
+```
+
+---
+
+## Testing Checklist
+
+- [ ] Dry run works without errors
+- [ ] Actual message sends successfully
+- [ ] Error handling works (invalid URL, no message button, etc.)
+- [ ] CDP integration works (uses existing browser session)
+- [ ] Thread ID is correctly extracted
+- [ ] Audit logging works
+- [ ] Help command shows new options
+
+## Estimated Effort
+
+- **Implementation:** 2-3 hours
+- **Testing:** 30 minutes
+- **Total:** ~3 hours
+
+---
+
+## Next Steps
+
+1. ✅ Plan complete and saved to `docs/plans/2026-02-28-messages-send-feature.md`
+2. ⏳ Execute plan with `superpowers:executing-plans`

package/docs/plans/2026-02-28-messages-show-design.md

@@ -0,0 +1,243 @@
+# v0.3.0 Design: Fix `messages show` Command
+
+## Overview
+
+Fix the `messages show` command to display full conversation threads by implementing click-to-navigate URL capture for extracting real LinkedIn thread IDs.
+
+**v0.2.0 Problem:** Thread IDs are fallback ember IDs (ember50, ember58) which don't work for navigation.
+
+**v0.3.0 Solution:** Click conversation cards → capture URL → extract real thread ID → scrape messages.
+
+---
+
+## Requirements
+
+### Functional Requirements
+
+1. **Show Thread by ID**
+   - `linkedin-cli messages show -t ember50` displays full conversation
+   - Works with both ember IDs and real thread IDs
+
+2. **Message Display**
+   - Default: Human-readable Style A (chronological chat format)
+   - `--json` flag: Structured JSON for LLM/automation processing
+
+3. **Message Metadata**
+   - Sender name (with "You" indicator for current user)
+   - Timestamp (formatted + raw in JSON)
+   - Message content (with newline preservation)
+
+### Non-Functional Requirements
+
+- **Reliability:** Handle LinkedIn's dynamic UI with fallback strategies
+- **Performance:** Load messages within 10 seconds for typical conversations
+- **Rate Limiting:** Respect LinkedIn's rate limits (max 1 request/second)
+
+---
+
+## Architecture
+
+### Component Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     messages show Command                        │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
+│  │ Card Locator │───▶│ Click & Wait │───▶│ URL Extractor│      │
+│  └──────────────┘    └──────────────┘    └──────────────┘      │
+│                                                │                 │
+│                                                ▼                 │
+│                                         ┌──────────────┐        │
+│                                         │ Message      │        │
+│                                         │ Scraper      │        │
+│                                         └──────────────┘        │
+│                                                │                 │
+│                    ┌──────────────┐           ▼                 │
+│                    │ JSON Output  │◀───┐ ┌──────────────┐      │
+│                    │   Formatter  │    └─│  Text Output │      │
+│                    └──────────────┘      └──────────────┘      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Data Flow
+
+1. **User Input:** `messages show -t ember50 [--json]`
+2. **Card Lookup:** Find conversation card by ember ID in DOM
+3. **Navigation:** Click card → wait for URL change
+4. **ID Extraction:** Parse real thread ID from new URL
+5. **Message Scraping:** Extract all message bubbles
+6. **Output:** Format as text (default) or JSON
+
+---
+
+## Implementation Details
+
+### 1. Card Locator (`findConversationCard()`)
+
+```typescript
+async findConversationCard(cardId: string): Promise<ElementHandle> {
+  // Try direct ember ID match
+  let card = await page.$(`#conversation-card-${cardId}`);
+
+  // Fallback: search by class + index
+  if (!card) {
+    const cards = await page.$$('.msg-conversation-card');
+    const index = cardId.replace('ember', '');
+    card = cards[parseInt(index)];
+  }
+
+  return card;
+}
+```
+
+### 2. Click & Navigate
+
+```typescript
+async navigateToThread(card: ElementHandle): Promise<string> {
+  // Set up URL change listener
+  const [newUrl] = await Promise.all([
+    page.waitForNavigation({ waitUntil: 'domcontentloaded' }),
+    card.click(),
+  ]);
+
+  return page.url(); // Contains real thread ID
+}
+```
+
+### 3. Message Scraper
+
+```typescript
+async scrapeMessages(threadId: string): Promise<Message[]> {
+  const messageBubbles = await page.$$('.msg-s-message-group__message');
+
+  return Promise.all(messageBubbles.map(async (bubble) => {
+    return {
+      sender: await bubble.$eval('.msg-s-message-group__name', el => el.textContent),
+      content: await bubble.$eval('.msg-s-event-listitem__body', el => el.textContent),
+      timestamp: await bubble.$eval('time', el => el.getAttribute('datetime')),
+      isMe: await bubble.evaluate(el => el.classList.contains('msg-s-message-group--me')),
+    };
+  }));
+}
+```
+
+### 4. Output Formatters
+
+**Text Formatter (Default):**
+```
+Conversations with Lucia Söffge
+────────────────────────────────
+Feb 26, 2024
+
+10:30 AM  Lucia: Hey! How are you?
+10:32 AM  You: I'm good, thanks!
+```
+
+**JSON Formatter (`--json`):**
+```json
+{
+  "threadId": "2-ZWY1Mzkx...",
+  "participants": [{"name": "Lucia Söffge", "profileUrl": null}],
+  "messages": [
+    {
+      "id": "msg-1",
+      "threadId": "2-ZWY1Mzkx...",
+      "sender": {"name": "Lucia Söffge", "isMe": false},
+      "content": "Hey! How are you?",
+      "timestamp": "2024-02-26T10:30:00Z"
+    }
+  ]
+}
+```
+
+---
+
+## Error Handling
+
+| Error | Handling |
+|-------|----------|
+| Card not found | Show list of available ember IDs |
+| Navigation timeout | Retry click, then fail with message |
+| No messages found | Show empty state with thread info |
+| Rate limited | Wait + retry with exponential backoff |
+| Session expired | Prompt user to re-authenticate |
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+- [ ] `findConversationCard()` with valid/invalid IDs
+- [ ] URL extraction regex for thread IDs
+- [ ] Message scraper with various message types
+
+### Integration Tests
+- [ ] Click navigation with real LinkedIn session
+- [ ] JSON output validation against schema
+- [ ] Text output formatting
+
+### Manual Testing
+- [ ] Conversations with 1 message
+- [ ] Conversations with 100+ messages
+- [ ] Conversations with attachments
+- [ ] Group conversations (3+ participants)
+
+---
+
+## Success Criteria
+
+- [ ] `messages show -t ember50` displays full thread
+- [ ] `messages show -t ember50 --json` outputs valid JSON
+- [ ] Works with real thread IDs (e.g., `2-ZWY1...`)
+- [ ] Handles conversations up to 100 messages
+- [ ] All tests pass (unit + integration)
+
+---
+
+## Out of Scope (v0.4.0+)
+
+- [ ] Message attachments/images
+- [ ] Message reactions
+- [ ] Edit/delete messages
+- [ ] Search within conversations
+- [ ] Export conversations to file
+
+---
+
+## Files to Modify
+
+| File | Changes |
+|------|---------|
+| `src/linkedin/messages.ts` | Add `showThread()` method with click navigation |
+| `src/cli/messages.ts` | Add `--json` flag, update output formatting |
+| `src/types/index.ts` | Add/verify `Message` and `Thread` types |
+| `src/linkedin/selector-engine.ts` | Add message-specific selectors |
+
+---
+
+## Estimated Effort
+
+- **Implementation:** 3-4 hours
+- **Testing:** 1-2 hours
+- **Documentation:** 30 minutes
+- **Total:** 5-6 hours
+
+---
+
+## Approval
+
+**Approved by:** [User]
+**Date:** 2026-02-28
+**Status:** Ready for implementation planning
+
+---
+
+## Next Steps
+
+1. ✅ Design approved
+2. ⏳ Invoke `writing-plans` skill for detailed implementation plan
+3. ⏳ Implement features
+4. ⏳ Test with real LinkedIn data
+5. ⏳ Release v0.3.0