linkedin-automation-cli 1.0.0

package/docs/plans/2026-02-19-linkedin-connection-feature.md

@@ -0,0 +1,596 @@
+# LinkedIn Connection Feature Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a `connect` command to send LinkedIn connection requests to specific profiles, handling cases where the button is hidden behind the "..." menu.
+
+**Architecture:**
+- Add connection selectors to `selectors.ts` for various button states
+- Create a `LinkedInConnector` class in `linkedin/connector.ts` to handle connection logic
+- Add CLI command `linkedin connect <profile-url>` with option to add a note
+- Handle the "More" (three dots) menu when the connect button is not directly visible
+
+**Tech Stack:** TypeScript, Playwright, Commander.js
+
+---
+
+## Pre-Task: Complete Login First
+
+**Status check:** Run `npm run build` and verify the project compiles.
+
+**Command:**
+```bash
+npm run build
+```
+
+**Expected:** TypeScript compiles without errors.
+
+---
+
+## Task 1: Add Connection Selectors
+
+**Files:**
+- Modify: `src/linkedin/selectors.ts`
+
+**Step 1: Add connection selectors to SELECTORS object**
+
+Add a new `connection` section after the `messages` section:
+
+```typescript
+  // Connection requests
+  connection: {
+    // Primary connect button (various states)
+    connectButton: [
+      'button[aria-label*="Connect"]',
+      'button:has-text("Connect")',
+      'button.connect',
+      '[data-testid="connect-button"]',
+    ],
+    // More actions menu (three dots)
+    moreActionsButton: [
+      'button[aria-label*="More actions"]',
+      'button[aria-label*="More"]',
+      'button:has-text("More")',
+      '.artdeco-dropdown__trigger',
+      'button[data-testid="more-actions"]',
+    ],
+    // Connect option in dropdown menu
+    connectOptionInMenu: [
+      'div[role="menuitem"]:has-text("Connect")',
+      'button:has-text("Connect")',
+      '[role="menuitem"][aria-label*="Connect"]',
+    ],
+    // Add a note modal
+    addNoteButton: [
+      'button[aria-label*="Add a note"]',
+      'button:has-text("Add a note")',
+    ],
+    noteTextarea: [
+      'textarea[name="message"]',
+      'textarea[placeholder*="note"]',
+      'textarea',
+    ],
+    sendButton: [
+      'button[aria-label*="Send invitation"]',
+      'button:has-text("Send")',
+      'button[type="submit"]',
+    ],
+  },
+```
+
+**Step 2: Run build to verify no TypeScript errors**
+
+```bash
+npm run build
+```
+
+**Expected:** Compiles successfully.
+
+**Step 3: Commit**
+
+```bash
+git add src/linkedin/selectors.ts
+git commit -m "feat: add connection selectors for LinkedIn connect feature"
+```
+
+---
+
+## Task 2: Create LinkedInConnector Class
+
+**Files:**
+- Create: `src/linkedin/connector.ts`
+- Create: `src/linkedin/__tests__/connector.test.ts` (optional, basic test)
+
+**Step 1: Write the LinkedInConnector class**
+
+```typescript
+import type { BrowserController } from '../core/browser';
+import { SELECTORS } from './selectors';
+
+export interface ConnectionResult {
+  success: boolean;
+  error?: string;
+  sent?: boolean;
+  pending?: boolean;
+}
+
+export interface ConnectionOptions {
+  profileUrl: string;
+  note?: string;
+  skipNote?: boolean;
+}
+
+export class LinkedInConnector {
+  private browser: BrowserController;
+
+  constructor(browser: BrowserController) {
+    this.browser = browser;
+  }
+
+  /**
+   * Send a connection request to a LinkedIn profile
+   */
+  async connect(options: ConnectionOptions): Promise<ConnectionResult> {
+    const page = this.browser.getPage();
+    if (!page) {
+      return { success: false, error: 'Browser not initialized' };
+    }
+
+    try {
+      // Navigate to the profile
+      console.log(`Navigating to ${options.profileUrl}...`);
+      await page.goto(options.profileUrl, {
+        waitUntil: 'domcontentloaded',
+        timeout: 30000,
+      });
+
+      // Wait a moment for any dynamic content
+      await page.waitForTimeout(2000);
+
+      // Try to find the Connect button
+      console.log('Looking for Connect button...');
+      const connectResult = await this.findConnectButton();
+
+      if (!connectResult) {
+        // Check if already connected or pending
+        const status = await this.checkConnectionStatus();
+        if (status === 'connected') {
+          return { success: true, sent: false, error: 'Already connected to this person' };
+        } else if (status === 'pending') {
+          return { success: true, pending: true, error: 'Connection request already sent (pending)' };
+        }
+        return { success: false, error: 'Could not find Connect button - LinkedIn UI may have changed' };
+      }
+
+      // Click the Connect button
+      console.log('Clicking Connect button...');
+      await connectResult.element.click();
+      await page.waitForTimeout(1000);
+
+      // Handle adding a note if specified
+      if (options.note && !options.skipNote) {
+        const noteResult = await this.findElementWithFallbacks(
+          SELECTORS.connection.addNoteButton,
+          'Add a note button'
+        );
+
+        if (noteResult?.element) {
+          console.log('Clicking "Add a note" button...');
+          await noteResult.element.click();
+          await page.waitForTimeout(500);
+
+          // Find and fill the note textarea
+          const textareaResult = await this.findElementWithFallbacks(
+            SELECTORS.connection.noteTextarea,
+            'Note textarea'
+        );
+
+          if (textareaResult?.element) {
+            console.log('Adding note...');
+            const page = this.browser.getPage();
+            if (page) {
+              await page.fill(textareaResult.selectorUsed, options.note);
+            }
+          }
+        }
+      }
+
+      // Send the invitation
+      console.log('Sending connection request...');
+      const sendResult = await this.findElementWithFallbacks(
+        SELECTORS.connection.sendButton,
+        'Send invitation button'
+      );
+
+      if (sendResult?.element) {
+        await sendResult.element.click();
+        await page.waitForTimeout(1000);
+        console.log('Connection request sent successfully!');
+        return { success: true, sent: true };
+      }
+
+      return { success: false, error: 'Could not find Send button' };
+
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error('Connection error:', errorMessage);
+      return { success: false, error: `Connection error: ${errorMessage}` };
+    }
+  }
+
+  /**
+   * Try to find the Connect button - either directly or in the More menu
+   */
+  private async findConnectButton(): Promise<{ element: Awaited<ReturnType<import('playwright').Page['$']>>; selectorUsed: string } | null> {
+    // First try direct Connect button
+    const directConnect = await this.findElementWithFallbacks(
+      SELECTORS.connection.connectButton,
+      'direct Connect button'
+    );
+
+    if (directConnect) {
+      return directConnect;
+    }
+
+    console.log('Direct Connect button not found, checking More menu...');
+
+    // Try the More menu
+    const moreButton = await this.findElementWithFallbacks(
+      SELECTORS.connection.moreActionsButton,
+      'More actions button'
+    );
+
+    if (moreButton?.element) {
+      console.log('Clicking More actions menu...');
+      const page = this.browser.getPage();
+      if (page) {
+        await moreButton.element.click();
+        await page.waitForTimeout(1000);
+
+        // Look for Connect option in the dropdown
+        const connectOption = await this.findElementWithFallbacks(
+          SELECTORS.connection.connectOptionInMenu,
+          'Connect option in menu'
+        );
+
+        if (connectOption) {
+          return connectOption;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Check the current connection status with a person
+   */
+  private async checkConnectionStatus(): Promise<'connected' | 'pending' | 'none' | 'unknown'> {
+    const page = this.browser.getPage();
+    if (!page) return 'unknown';
+
+    try {
+      // Look for indicators of existing connection
+      const indicators = [
+        { selector: 'button[aria-label*="Message"] i', text: 'Message', status: 'connected' as const },
+        { selector: 'button:has-text("Pending")', text: 'Pending', status: 'pending' as const },
+        { selector: 'span:has-text("1st")', text: '1st', status: 'connected' as const },
+      ];
+
+      for (const indicator of indicators) {
+        const element = await page.$(indicator.selector);
+        if (element) {
+          return indicator.status;
+        }
+      }
+
+      return 'none';
+    } catch {
+      return 'unknown';
+    }
+  }
+
+  /**
+   * Try to find an element using multiple selector strategies
+   */
+  private async findElementWithFallbacks(
+    selectors: readonly string[],
+    elementName: string
+  ): Promise<{ element: Awaited<ReturnType<import('playwright').Page['$']>>; selectorUsed: string } | null> {
+    const page = this.browser.getPage();
+    if (!page) return null;
+
+    for (const selector of selectors) {
+      try {
+        const element = await page.$(selector);
+        if (element) {
+          console.log(`Found ${elementName} using selector: ${selector}`);
+          return { element, selectorUsed: selector };
+        }
+      } catch {
+        // Continue to next selector
+      }
+    }
+
+    return null;
+  }
+}
+```
+
+**Step 2: Create the CLI command for connections**
+
+Create `src/cli/connection.ts`:
+
+```typescript
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { BrowserController } from '../core/browser';
+import { LinkedInConnector } from '../linkedin/connector';
+import { getSecureStorage } from '../core/storage';
+import { getAuditLogger } from '../core/audit';
+import { getConfig } from '../core/config';
+
+const SESSION_KEY = 'linkedin-session';
+
+export function registerConnectionCommands(program: Command): void {
+  const connection = program
+    .command('connect')
+    .description('Send connection requests to LinkedIn profiles');
+
+  connection
+    .command('send')
+    .description('Send a connection request to a profile')
+    .argument('<profile-url>', 'LinkedIn profile URL (e.g., https://www.linkedin.com/in/williamhgates/)')
+    .option('-n, --note <note>', 'Personalized note to include with connection request (max 300 characters)')
+    .option('--headless', 'Run browser in headless mode', false)
+    .action(async (profileUrl, options) => {
+      const storage = getSecureStorage();
+      const logger = getAuditLogger();
+      const config = getConfig();
+
+      try {
+        // Validate profile URL
+        if (!profileUrl.match(/^https?:\/\/www\.linkedin\.com\/in\/[^\/]+\/?$/)) {
+          console.error(chalk.red('✗ Invalid profile URL'));
+          console.log(chalk.gray('Expected format: https://www.linkedin.com/in/username/'));
+          process.exit(1);
+        }
+
+        // Check for existing session
+        if (!storage.exists(SESSION_KEY)) {
+          console.error(chalk.red('✗ Not logged in'));
+          console.log(chalk.gray('Run: linkedin-cli auth login'));
+          process.exit(1);
+        }
+
+        const sessionData = storage.load(SESSION_KEY);
+        if (!sessionData) {
+          console.error(chalk.red('✗ Session data corrupted'));
+          console.log(chalk.gray('Run: linkedin-cli auth login'));
+          process.exit(1);
+        }
+
+        console.log(chalk.blue(`Preparing to connect with ${profileUrl}...`));
+
+        // Launch browser
+        const browser = new BrowserController({
+          headless: options.headless ?? config.getValue('headless'),
+        });
+
+        await browser.launch();
+
+        // Restore session
+        const session = JSON.parse(sessionData);
+        await browser.restoreSession(session);
+
+        // Create connector and send request
+        const connector = new LinkedInConnector(browser);
+        const result = await connector.connect({
+          profileUrl,
+          note: options.note,
+        });
+
+        if (result.success && result.sent) {
+          console.log(chalk.green('✓ Connection request sent successfully!'));
+          logger.log('connection.send', { profileUrl, hasNote: !!options.note }, true);
+        } else if (result.pending) {
+          console.log(chalk.yellow('⚠ Connection request already pending'));
+        } else if (result.error?.includes('Already connected')) {
+          console.log(chalk.yellow('✓ Already connected to this person'));
+        } else {
+          console.error(chalk.red('✗ Failed to send connection request:'), result.error);
+          logger.log('connection.send', { profileUrl, error: result.error }, false);
+          await browser.close();
+          process.exit(1);
+        }
+
+        await browser.close();
+      } catch (error) {
+        console.error(chalk.red('✗ Connection failed:'), error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}
+```
+
+**Step 3: Register the command in the main CLI**
+
+Modify `src/index.ts` to import and register the connection commands:
+
+```typescript
+import { registerAuthCommands, registerMessageCommands, registerReplyCommands, registerConnectionCommands } from './cli';
+
+// ... existing code ...
+
+// Register command groups
+registerAuthCommands(program);
+registerMessageCommands(program);
+registerReplyCommands(program);
+registerConnectionCommands(program);  // Add this line
+```
+
+**Step 4: Export the command from cli/index.ts**
+
+Modify `src/cli/index.ts` to export the connection commands:
+
+```typescript
+export { registerAuthCommands } from './auth';
+export { registerMessageCommands } from './messages';
+export { registerReplyCommands } from './reply';
+export { registerConnectionCommands } from './connection';  // Add this line
+```
+
+**Step 5: Run build to verify no TypeScript errors**
+
+```bash
+npm run build
+```
+
+**Expected:** Compiles successfully.
+
+**Step 6: Commit**
+
+```bash
+git add src/linkedin/connector.ts src/cli/connection.ts src/cli/index.ts src/index.ts
+git commit -m "feat: add connection command to send LinkedIn connection requests"
+```
+
+---
+
+## Task 3: Test Connection Feature
+
+**Step 1: Verify the command is registered**
+
+```bash
+node dist/index.js --help
+```
+
+**Expected:** See `connect` command in the list.
+
+**Step 2: Check help for connect command**
+
+```bash
+node dist/index.js connect send --help
+```
+
+**Expected:** Shows usage: `Usage: linkedin-cli connect send [options] <profile-url>`
+
+**Step 3: Test without login (should fail with helpful message)**
+
+```bash
+node dist/index.js connect send "https://www.linkedin.com/in/williamhgates/"
+```
+
+**Expected:** Error message: "Not logged in. Run: linkedin-cli auth login"
+
+**Step 4: Commit test results**
+
+```bash
+git add -A
+git commit -m "test: verify connection command structure"
+```
+
+---
+
+## Task 4: Document the Connection Feature
+
+**Files:**
+- Create: `docs/connection-command.md`
+
+**Step 1: Write documentation**
+
+```markdown
+# Connection Command
+
+Send LinkedIn connection requests via CLI.
+
+## Prerequisites
+
+You must be logged in:
+```bash
+linkedin-cli auth login
+```
+
+## Usage
+
+### Basic connection request
+```bash
+linkedin-cli connect send "https://www.linkedin.com/in/williamhgates/"
+```
+
+### With a personalized note
+```bash
+linkedin-cli connect send "https://www.linkedin.com/in/williamhgates/" \
+  --note "Hi Bill, I'd love to connect and discuss technology."
+```
+
+### Run in headless mode
+```bash
+linkedin-cli connect send "https://www.linkedin.com/in/williamhgates/" --headless
+```
+
+## How It Works
+
+1. **Navigates to profile:** Opens the LinkedIn profile URL
+2. **Finds Connect button:** Tries multiple selectors to locate the Connect button
+3. **Handles "More" menu:** If Connect is hidden, clicks the "..." (More actions) button and selects Connect from the dropdown
+4. **Optional note:** If `--note` provided, clicks "Add a note", fills the textarea
+5. **Sends request:** Clicks "Send invitation"
+
+## Error Handling
+
+- **Not logged in:** Prompts to run `linkedin-cli auth login`
+- **Already connected:** Shows "Already connected to this person"
+- **Pending request:** Shows "Connection request already pending"
+- **Button not found:** Reports "LinkedIn UI may have changed" with debug info
+
+## Technical Details
+
+The command uses a multi-layer selector system to handle LinkedIn's dynamic UI:
+- Tries `aria-label` selectors first (accessibility-friendly)
+- Falls back to text-based selectors (`:has-text()`)
+- Uses class-based selectors as final fallback
+
+This approach makes the tool resilient to LinkedIn's frequent UI updates.
+```
+
+**Step 2: Commit documentation**
+
+```bash
+git add docs/connection-command.md
+git commit -m "docs: add connection command documentation"
+```
+
+---
+
+## Final Verification
+
+**Run all tests and verify build:**
+
+```bash
+npm run build
+node dist/index.js --help
+node dist/index.js connect send --help
+```
+
+**Final commit:**
+
+```bash
+git add -A
+git commit -m "feat: complete LinkedIn connection request feature"
+```
+
+---
+
+## Execution Summary
+
+This implementation adds a complete `connect` command that:
+
+1. **Accepts profile URLs** - Validates LinkedIn profile URL format
+2. **Supports personalized notes** - `--note` option for custom messages
+3. **Handles hidden buttons** - Clicks "..." menu when Connect is not directly visible
+4. **Provides clear feedback** - Success/error messages for all scenarios
+5. **Uses resilient selectors** - Multi-layer fallback system
+6. **Includes full documentation** - Usage guide and technical details
+
+**Estimated implementation time:** 45-60 minutes for all tasks.