linkedin-automation-cli 1.0.0

package/src/agent/types.ts

@@ -0,0 +1,288 @@
+/**
+ * Agent Types Module
+ *
+ * Type definitions for the Page Agent system.
+ * Used for DOM-text based automation with Claude API integration.
+ */
+
+// ============================================================================
+// DOM Representation Types
+// ============================================================================
+
+/**
+ * Bounding box for an element's position and dimensions
+ */
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Represents a single DOM element extracted from the page
+ */
+export interface DOMElement {
+  /** Unique identifier for the element within the page */
+  id: string;
+  /** HTML tag name (e.g., 'button', 'input', 'a') */
+  tag: string;
+  /** ARIA role if present (e.g., 'button', 'link', 'textbox') */
+  role?: string;
+  /** ARIA label if present */
+  ariaLabel?: string;
+  /** Visible text content of the element */
+  text: string;
+  /** Input type for form elements (e.g., 'text', 'email', 'password') */
+  type?: string;
+  /** Current value for input elements */
+  value?: string;
+  /** Whether the element is currently visible */
+  visible: boolean;
+  /** Whether the element is enabled (not disabled) */
+  enabled: boolean;
+  /** Bounding box for element location */
+  bbox: BoundingBox;
+}
+
+/**
+ * Page type classification for LinkedIn pages
+ */
+export type PageType = 'profile' | 'search' | 'messaging' | 'notifications' | 'feed' | 'unknown';
+
+/**
+ * Connection state for profile pages
+ */
+export type ConnectionState = 'connected' | 'not_connected' | 'pending' | 'unknown';
+
+/**
+ * Metadata extracted from the page
+ */
+export interface PageMetadata {
+  /** Type of page detected */
+  pageType: PageType;
+  /** Name of the profile owner (if on a profile page) */
+  profileName?: string;
+  /** Title/headline of the profile (if on a profile page) */
+  profileTitle?: string;
+  /** Connection status with the profile owner */
+  connectionState?: ConnectionState;
+  /** Status messages or notifications displayed on the page */
+  statusMessages?: string[];
+}
+
+/**
+ * Complete DOM representation of a page
+ */
+export interface DOMRepresentation {
+  /** Current page URL */
+  url: string;
+  /** Page title */
+  title: string;
+  /** Array of interactive elements */
+  elements: DOMElement[];
+  /** Extracted metadata about the page */
+  metadata: PageMetadata;
+}
+
+// ============================================================================
+// Action Types
+// ============================================================================
+
+/**
+ * Base action interface
+ */
+export interface BaseAction {
+  /** Human-readable description of what this action does */
+  description: string;
+}
+
+/**
+ * Click action - simulates a mouse click on an element
+ */
+export interface ClickAction extends BaseAction {
+  type: 'click';
+  /** ID of the element to click (from DOMElement.id) */
+  elementId: string;
+}
+
+/**
+ * Type action - enters text into an input field
+ */
+export interface TypeAction extends BaseAction {
+  type: 'type';
+  /** ID of the input element (from DOMElement.id) */
+  elementId: string;
+  /** Text to type into the element */
+  text: string;
+}
+
+/**
+ * Wait action - pauses execution for a specified duration
+ */
+export interface WaitAction extends BaseAction {
+  type: 'wait';
+  /** Duration to wait in milliseconds */
+  durationMs: number;
+}
+
+/**
+ * Navigate action - navigates to a different URL
+ */
+export interface NavigateAction extends BaseAction {
+  type: 'navigate';
+  /** URL to navigate to */
+  url: string;
+}
+
+/**
+ * Union type of all possible actions
+ */
+export type Action = ClickAction | TypeAction | WaitAction | NavigateAction;
+
+/**
+ * Type guard for ClickAction
+ */
+export function isClickAction(action: Action): action is ClickAction {
+  return action.type === 'click';
+}
+
+/**
+ * Type guard for TypeAction
+ */
+export function isTypeAction(action: Action): action is TypeAction {
+  return action.type === 'type';
+}
+
+/**
+ * Type guard for WaitAction
+ */
+export function isWaitAction(action: Action): action is WaitAction {
+  return action.type === 'wait';
+}
+
+/**
+ * Type guard for NavigateAction
+ */
+export function isNavigateAction(action: Action): action is NavigateAction {
+  return action.type === 'navigate';
+}
+
+// ============================================================================
+// Action Planning Types
+// ============================================================================
+
+/**
+ * Status of an action plan execution
+ */
+export type ActionPlanStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+
+/**
+ * Action plan generated by Claude for task execution
+ */
+export interface ActionPlan {
+  /** Reasoning behind the planned actions */
+  reasoning: string;
+  /** Expected outcome after executing the actions */
+  expectedOutcome: string;
+  /** Sequence of actions to execute */
+  actions: Action[];
+  /** Current status of the plan */
+  status: ActionPlanStatus;
+  /** Error message if plan generation or execution failed */
+  error?: string;
+}
+
+// ============================================================================
+// Client Configuration Types
+// ============================================================================
+
+/**
+ * Configuration for Claude API client
+ */
+export interface ClaudeClientConfig {
+  /** Anthropic API key */
+  apiKey: string;
+  /** Base URL for API requests (optional, for custom endpoints) */
+  baseUrl?: string;
+  /** Claude model to use (e.g., 'claude-3-5-sonnet-20241022') */
+  model: string;
+}
+
+// ============================================================================
+// Task Execution Types
+// ============================================================================
+
+/**
+ * Task to be executed by the agent
+ */
+export interface Task {
+  /** High-level goal to accomplish */
+  goal: string;
+  /** LinkedIn profile URL (if applicable) */
+  profileUrl?: string;
+  /** Optional note for connection requests */
+  note?: string;
+  /** Optional message to send */
+  message?: string;
+}
+
+/**
+ * Result of task execution
+ */
+export interface TaskResult {
+  /** Whether the task was completed successfully */
+  success: boolean;
+  /** Human-readable message describing the outcome */
+  message: string;
+  /** List of actions that were executed */
+  actionsTaken: Action[];
+  /** Final URL after task completion */
+  finalUrl?: string;
+}
+
+/**
+ * Result of a connection request task
+ */
+export interface ConnectionResult extends TaskResult {
+  /** Whether the connection request was sent */
+  sent: boolean;
+  /** Whether the request is pending approval */
+  pending: boolean;
+  /** Whether already connected to this user */
+  alreadyConnected?: boolean;
+}
+
+/**
+ * Result of a message sending task
+ */
+export interface MessageResult extends TaskResult {
+  /** Whether the message was successfully sent */
+  sent: boolean;
+}
+
+/**
+ * Context for action execution
+ */
+export interface ActionContext {
+  /** Actions that have already been executed */
+  previousActions: ExecutedAction[];
+  /** Original task goal */
+  goal: string;
+  /** Number of retry attempts for the current action */
+  retryCount: number;
+}
+
+/**
+ * Record of an executed action
+ */
+export interface ExecutedAction {
+  /** The action that was executed */
+  action: Action;
+  /** Whether the action executed successfully */
+  success: boolean;
+  /** Timestamp when the action was executed */
+  timestamp: Date;
+  /** Error message if the action failed */
+  error?: string;
+}

package/src/cli/agent-commands.ts

@@ -0,0 +1,274 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { PageAgent, PageAgentExtensionClient, getAuthToken } from '../agent';
+import { BrowserController } from '../core/browser';
+import { getConfig } from '../core/config';
+import type { ClaudeClientConfig } from '../agent/types';
+
+// Constants
+const DASHSCOPE_API_KEY_ENV = 'DASHSCOPE_API_KEY';
+const LINKEDIN_URL_REGEX = /^https?:\/\/www\.linkedin\.com\/in\/[^\/]+\/?$/;
+const DEFAULT_CLAUDE_CONFIG = {
+  baseUrl: 'https://coding.dashscope.aliyuncs.com/apps/anthropic/v1',
+  model: 'qwen3.5-plus',
+};
+
+/**
+ * Check if a CDP-enabled browser is available
+ * @returns true if browser is listening on localhost:9222
+ */
+async function isCDPBrowserAvailable(port = 9222): Promise<boolean> {
+  try {
+    const response = await fetch(`http://localhost:${port}/json/version`, {
+      signal: AbortSignal.timeout(2000),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+// Validation functions
+function validateApiKey(): string | null {
+  const apiKey = process.env[DASHSCOPE_API_KEY_ENV];
+  if (!apiKey) {
+    console.error(chalk.red(`✗ ${DASHSCOPE_API_KEY_ENV} environment variable is required`));
+    console.log(chalk.gray('Set it with: export DASHSCOPE_API_KEY=your_key'));
+    return null;
+  }
+  return apiKey;
+}
+
+function validateLinkedInUrl(url: string): boolean {
+  if (!LINKEDIN_URL_REGEX.test(url)) {
+    console.error(chalk.red('✗ Invalid profile URL'));
+    console.log(chalk.gray('Expected format: https://www.linkedin.com/in/username/'));
+    return false;
+  }
+  return true;
+}
+
+export function registerAgentCommands(program: Command): void {
+  // Create agent subcommand
+  const agentCmd = program.command('agent').description('AI-powered LinkedIn automation');
+
+  // Connect command (auto-detects extension, falls back to Playwright)
+  agentCmd
+    .command('connect <url>')
+    .description('Send connection request (auto-detects fastest method)')
+    .option('--note <text>', 'Personal note')
+    .option('--debug', 'Enable debug output')
+    .option('--playwright', 'Force Playwright mode (ignore extension)')
+    .action(
+      async (url: string, options: { note?: string; debug?: boolean; playwright?: boolean }) => {
+        // Validate API key and URL
+        const apiKey = validateApiKey();
+        if (!apiKey) return;
+
+        if (!validateLinkedInUrl(url)) return;
+
+        const note = options.note || 'Hi, I would like to connect with you.';
+
+        // Check if CDP browser is available
+        if (!options.playwright && (await isCDPBrowserAvailable())) {
+          // Extension mode (fast)
+          console.log(chalk.blue('Using Page Agent Extension (fast mode)...'));
+          console.log(chalk.gray('Profile: ' + url));
+
+          try {
+            const extClient = new PageAgentExtensionClient({
+              authToken: getAuthToken(),
+              apiKey,
+              debug: options.debug,
+            });
+
+            const result = await extClient.connect(url, note);
+
+            if (result.success) {
+              console.log(chalk.green('✓ Connection request prepared!'));
+              console.log(chalk.gray(`Note: "${note}"`));
+              console.log(chalk.yellow('→ Ready for review - Send button NOT clicked'));
+            } else {
+              console.error(chalk.red('✗ Failed: ' + result.message));
+              process.exit(1);
+            }
+          } catch (error) {
+            console.error(
+              chalk.red('✗ Extension mode failed:'),
+              error instanceof Error ? error.message : error
+            );
+            process.exit(1);
+          }
+        } else {
+          // Playwright mode (fallback)
+          const modeReason = options.playwright
+            ? '--playwright flag specified'
+            : 'CDP browser not available';
+          console.log(chalk.blue(`Using Playwright Agent (${modeReason})...`));
+          console.log(chalk.gray('Profile: ' + url));
+
+          let browser: BrowserController | null = null;
+
+          try {
+            const config = getConfig();
+            browser = new BrowserController({
+              headless: config.getValue('headless'),
+              debug: options.debug,
+            });
+
+            const page = await browser.launch();
+
+            const claudeConfig: ClaudeClientConfig = {
+              apiKey,
+              ...DEFAULT_CLAUDE_CONFIG,
+            };
+
+            const agent = new PageAgent({
+              claudeConfig,
+              debug: options.debug,
+            });
+
+            const result = await agent.connect(url, options.note, page);
+
+            if (result.sent) {
+              console.log(chalk.green('✓ Connection request sent!'));
+            } else if (result.alreadyConnected) {
+              console.log(chalk.yellow('✓ Already connected'));
+            } else {
+              console.error(chalk.red('✗ Failed: ' + result.message));
+              process.exit(1);
+            }
+          } catch (error) {
+            console.error(
+              chalk.red('✗ Playwright mode failed:'),
+              error instanceof Error ? error.message : error
+            );
+            process.exit(1);
+          } finally {
+            if (browser) {
+              await browser.close();
+            }
+          }
+        }
+      }
+    );
+
+  // Message command
+  agentCmd
+    .command('message <url>')
+    .description('Send message using AI agent')
+    .requiredOption('--message <text>', 'Message to send')
+    .option('--debug', 'Enable debug output')
+    .action(async (url: string, options: { message: string; debug?: boolean }) => {
+      // Validate API key and URL
+      const apiKey = validateApiKey();
+      if (!apiKey) return;
+
+      if (!validateLinkedInUrl(url)) return;
+
+      let browser: BrowserController | null = null;
+
+      try {
+        console.log(chalk.blue(`Preparing to send message to ${url} using AI agent...`));
+
+        // Launch browser
+        const config = getConfig();
+        browser = new BrowserController({
+          headless: config.getValue('headless'),
+          debug: options.debug,
+        });
+
+        const page = await browser.launch();
+
+        // Create PageAgent with config
+        const claudeConfig: ClaudeClientConfig = {
+          apiKey,
+          ...DEFAULT_CLAUDE_CONFIG,
+        };
+
+        const agent = new PageAgent({
+          claudeConfig,
+          debug: options.debug,
+        });
+
+        // Call agent.sendMessage
+        const result = await agent.sendMessage(url, options.message, page);
+
+        // Print result
+        if (result.sent) {
+          console.log(chalk.green('✓ Message sent successfully!'));
+          console.log(chalk.gray(`Message: "${options.message}"`));
+        } else {
+          console.error(chalk.red('✗ Failed to send message'));
+          console.error(chalk.gray(result.message));
+        }
+      } catch (error) {
+        console.error(
+          chalk.red('✗ Message failed:'),
+          error instanceof Error ? error.message : error
+        );
+        process.exit(1);
+      } finally {
+        // Ensure browser closes
+        if (browser) {
+          await browser.close();
+        }
+      }
+    });
+
+  // Playwright command (explicit Playwright mode)
+  agentCmd
+    .command('playwright <url>')
+    .description('Send connection request using Playwright (slower, explicit)')
+    .option('--note <text>', 'Personal note')
+    .option('--debug', 'Enable debug output')
+    .action(async (url: string, options: { note?: string; debug?: boolean }) => {
+      const apiKey = validateApiKey();
+      if (!apiKey) return;
+
+      if (!validateLinkedInUrl(url)) return;
+
+      let browser: BrowserController | null = null;
+
+      try {
+        console.log(chalk.blue('Using Playwright Agent (explicit mode)...'));
+        console.log(chalk.gray('Profile: ' + url));
+
+        const config = getConfig();
+        browser = new BrowserController({
+          headless: config.getValue('headless'),
+          debug: options.debug,
+        });
+
+        const page = await browser.launch();
+
+        const claudeConfig: ClaudeClientConfig = {
+          apiKey,
+          ...DEFAULT_CLAUDE_CONFIG,
+        };
+
+        const agent = new PageAgent({
+          claudeConfig,
+          debug: options.debug,
+        });
+
+        const result = await agent.connect(url, options.note, page);
+
+        if (result.sent) {
+          console.log(chalk.green('✓ Connection request sent!'));
+        } else if (result.alreadyConnected) {
+          console.log(chalk.yellow('✓ Already connected'));
+        } else {
+          console.error(chalk.red('✗ Failed: ' + result.message));
+          process.exit(1);
+        }
+      } catch (error) {
+        console.error(chalk.red('✗ Failed:'), error instanceof Error ? error.message : error);
+        process.exit(1);
+      } finally {
+        if (browser) {
+          await browser.close();
+        }
+      }
+    });
+}