linkedin-automation-cli 1.0.0

package/src/agent/extension-client.ts

@@ -0,0 +1,306 @@
+/**
+ * Page Agent Extension Client
+ *
+ * Uses direct WebSocket connection to Chrome DevTools Protocol
+ * following the official Page Agent usage guide.
+ */
+
+import WebSocket from 'ws';
+
+/**
+ * Configuration for the Page Agent Extension
+ */
+export interface ExtensionClientConfig {
+  /** Auth token from extension side panel */
+  authToken: string;
+  /** LLM API key */
+  apiKey: string;
+  /** LLM API endpoint (OpenAI-compatible) */
+  baseURL?: string;
+  /** Model name */
+  model?: string;
+  /** CDP port (default: 9222) */
+  port?: number;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * Result from the Page Agent Extension
+ */
+export interface ExtensionResult {
+  success: boolean;
+  status: string;
+  message: string;
+  data?: string;
+}
+
+const DEFAULT_BASE_URL = 'https://open.bigmodel.cn/api/paas/v4';
+const DEFAULT_MODEL = 'glm-5';
+const DEFAULT_PORT = 9222;
+
+/**
+ * Client for the Alibaba Page Agent browser extension
+ */
+export class PageAgentExtensionClient {
+  private readonly config: Required<ExtensionClientConfig>;
+  private readonly debug: boolean;
+
+  constructor(config: ExtensionClientConfig) {
+    this.config = {
+      baseURL: config.baseURL ?? DEFAULT_BASE_URL,
+      model: config.model ?? DEFAULT_MODEL,
+      port: config.port ?? DEFAULT_PORT,
+      authToken: config.authToken,
+      apiKey: config.apiKey,
+      debug: config.debug ?? false,
+    };
+    this.debug = config.debug ?? false;
+  }
+
+  /**
+   * List available browser pages
+   */
+  async listPages(): Promise<Array<{ id: string; url: string; title: string }>> {
+    const response = await fetch(`http://localhost:${this.config.port}/json/list`);
+    const pages = await response.json();
+    return pages
+      .filter((p: any) => p.type === 'page')
+      .map((p: any) => ({ id: p.id, url: p.url, title: p.title }));
+  }
+
+  /**
+   * Find a page by URL pattern
+   */
+  async findPage(urlPattern: string): Promise<string | null> {
+    const pages = await this.listPages();
+    const page = pages.find((p) => p.url.includes(urlPattern));
+    return page?.id ?? null;
+  }
+
+  /**
+   * Execute JavaScript on a page via CDP WebSocket
+   * Simplified version following the guide pattern
+   */
+  private async evaluate(ws: WebSocket, expression: string, awaitPromise = false): Promise<any> {
+    return new Promise((resolve, reject) => {
+      const id = Math.floor(Math.random() * 1000000);
+      let resolved = false;
+
+      const timeout = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          ws.off('message', handler);
+          reject(new Error('Evaluation timeout'));
+        }
+      }, 60000);
+
+      const handler = (data: Buffer) => {
+        if (resolved) return;
+        try {
+          const response = JSON.parse(data.toString());
+          if (response.id === id) {
+            resolved = true;
+            clearTimeout(timeout);
+            ws.off('message', handler);
+            if (response.error) {
+              reject(new Error(response.error.message));
+            } else {
+              resolve(response.result?.result?.value);
+            }
+          }
+        } catch {
+          // Ignore parse errors
+        }
+      };
+
+      ws.on('message', handler);
+
+      ws.send(
+        JSON.stringify({
+          id,
+          method: 'Runtime.evaluate',
+          params: {
+            expression,
+            returnByValue: true,
+            awaitPromise,
+          },
+        })
+      );
+    });
+  }
+
+  /**
+   * Execute a task on a specific page
+   */
+  async executeOnPage(pageId: string, task: string): Promise<ExtensionResult> {
+    const wsUrl = `ws://localhost:${this.config.port}/devtools/page/${pageId}`;
+    this.log('Connecting to:', wsUrl);
+
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(wsUrl);
+      let settled = false;
+
+      ws.on('error', (err) => {
+        if (!settled) {
+          settled = true;
+          reject(new Error(`WebSocket error: ${err.message}`));
+        }
+      });
+
+      ws.on('open', async () => {
+        if (settled) return;
+
+        try {
+          this.log('Connected, setting auth token...');
+
+          // Step 1: Set auth token
+          await this.evaluate(
+            ws,
+            `localStorage.setItem('PageAgentExtUserAuthToken', '${this.config.authToken}')`
+          );
+          this.log('Auth token set');
+
+          // Step 2: Wait for extension to inject API (3 seconds as per guide)
+          this.log('Waiting 3 seconds for extension injection...');
+          await new Promise((r) => setTimeout(r, 3000));
+
+          // Step 3: Verify extension is available
+          const extCheck = await this.evaluate(
+            ws,
+            `({
+              version: window.PAGE_AGENT_EXT_VERSION,
+              hasExt: !!window.PAGE_AGENT_EXT,
+              canExecute: typeof window.PAGE_AGENT_EXT?.execute === 'function'
+            })`
+          );
+
+          this.log('Extension check:', extCheck);
+
+          if (!extCheck?.hasExt) {
+            settled = true;
+            ws.close();
+            resolve({
+              success: false,
+              status: 'error',
+              message: 'Page Agent extension not found. Check auth token.',
+            });
+            return;
+          }
+
+          this.log('Extension detected, version:', extCheck.version);
+
+          // Step 4: Execute task
+          this.log('Executing task:', task.substring(0, 100) + '...');
+
+          const result = await this.evaluate(
+            ws,
+            `(async () => {
+              try {
+                const response = await window.PAGE_AGENT_EXT.execute(
+                  ${JSON.stringify(task)},
+                  {
+                    baseURL: ${JSON.stringify(this.config.baseURL)},
+                    apiKey: ${JSON.stringify(this.config.apiKey)},
+                    model: ${JSON.stringify(this.config.model)},
+                    includeInitialTab: true,
+                    onStatusChange: (status) => console.log('[Status]', status),
+                    onActivity: (activity) => console.log('[Activity]', JSON.stringify(activity))
+                  }
+                );
+                return { success: true, data: response };
+              } catch (error) {
+                return { success: false, error: error.message };
+              }
+            })()`,
+            true // awaitPromise
+          );
+
+          this.log('Task result:', JSON.stringify(result)?.substring(0, 500));
+
+          settled = true;
+          ws.close();
+
+          resolve({
+            success: result?.success ?? false,
+            status: result?.success ? 'completed' : 'error',
+            message: result?.success ? 'Task completed' : result?.error || 'Unknown error',
+            data: typeof result?.data === 'string' ? result.data : JSON.stringify(result?.data),
+          });
+        } catch (err: any) {
+          settled = true;
+          ws.close();
+          resolve({
+            success: false,
+            status: 'error',
+            message: err.message,
+          });
+        }
+      });
+    });
+  }
+
+  /**
+   * Send a connection request on a LinkedIn profile
+   */
+  async connect(_profileUrl: string, note: string): Promise<ExtensionResult> {
+    // Step 1: Find LinkedIn page
+    this.log('Looking for LinkedIn page...');
+    let pageId = await this.findPage('linkedin.com/in/');
+
+    if (!pageId) {
+      pageId = await this.findPage('linkedin.com');
+    }
+
+    if (!pageId) {
+      return {
+        success: false,
+        status: 'error',
+        message: 'No LinkedIn page found. Please open a LinkedIn profile in your browser.',
+      };
+    }
+
+    this.log('Found LinkedIn page:', pageId);
+
+    // Step 2: Build task
+    const task = `On this LinkedIn profile page:
+1. Click the "Connect" button (or find it in "More" menu if not visible)
+2. If a modal opens with "Add a note" option, click it
+3. Type this message: "${note}"
+4. STOP - Do NOT click Send button
+5. Report success
+
+Important: Work on the current page. Do not navigate away.`;
+
+    // Step 3: Execute on that page
+    return this.executeOnPage(pageId, task);
+  }
+
+  /**
+   * Log debug messages
+   */
+  private log(message: string, data?: unknown): void {
+    if (this.debug) {
+      if (data !== undefined) {
+        console.log(`[ExtensionClient] ${message}`, data);
+      } else {
+        console.log(`[ExtensionClient] ${message}`);
+      }
+    }
+  }
+}
+
+/**
+ * Get the Page Agent auth token from environment variable
+ * @throws Error if PAGE_AGENT_AUTH_TOKEN is not set
+ */
+export function getAuthToken(): string {
+  const token = process.env.PAGE_AGENT_AUTH_TOKEN;
+  if (!token) {
+    throw new Error(
+      'PAGE_AGENT_AUTH_TOKEN environment variable is required. ' +
+        'Get your auth token from the Page Agent extension side panel.'
+    );
+  }
+  return token;
+}

package/src/agent/index.ts

@@ -0,0 +1,28 @@
+// Types
+export type {
+  Action,
+  ActionContext,
+  ActionPlan,
+  BoundingBox,
+  ClaudeClientConfig,
+  ClickAction,
+  ConnectionResult,
+  DOMElement,
+  DOMRepresentation,
+  ExecutedAction,
+  MessageResult,
+  NavigateAction,
+  PageMetadata,
+  Task,
+  TaskResult,
+  TypeAction,
+  WaitAction,
+} from './types';
+
+// Classes
+export { DOMExtractor } from './dom-extractor';
+export { ClaudeClient } from './claude-client';
+export { ActionExecutor } from './action-executor';
+export { PageAgent } from './page-agent';
+export { PageAgentExtensionClient, getAuthToken } from './extension-client';
+export type { ExtensionClientConfig, ExtensionResult } from './extension-client';

package/src/agent/page-agent.ts

@@ -0,0 +1,292 @@
+/**
+ * Page Agent Orchestrator Module
+ *
+ * Combines DOM extractor, Claude client, and action executor into a cohesive workflow.
+ * Provides high-level methods for LinkedIn automation tasks with retry logic and error recovery.
+ */
+
+import type { Page } from 'playwright';
+import { DOMExtractor } from './dom-extractor';
+import { ClaudeClient } from './claude-client';
+import { ActionExecutor } from './action-executor';
+import type {
+  Task,
+  TaskResult,
+  ConnectionResult,
+  MessageResult,
+  ActionContext,
+  ExecutedAction,
+  ClaudeClientConfig,
+} from './types';
+
+/**
+ * Configuration options for PageAgent
+ */
+export interface PageAgentOptions {
+  /** Configuration for Claude API client */
+  claudeConfig: ClaudeClientConfig;
+  /** Maximum number of retry attempts for failed actions (default: 3) */
+  maxRetries?: number;
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+
+/**
+ * High-level agent for executing tasks on LinkedIn pages
+ * Orchestrates DOM extraction, action planning, and execution
+ */
+export class PageAgent {
+  private readonly claudeClient: ClaudeClient;
+  private readonly domExtractor: DOMExtractor;
+  private readonly maxRetries: number;
+  private readonly debug: boolean;
+
+  /**
+   * Creates a new PageAgent instance
+   * @param options - Configuration options including Claude client config
+   */
+  constructor(options: PageAgentOptions) {
+    this.claudeClient = new ClaudeClient(options.claudeConfig);
+    this.domExtractor = new DOMExtractor();
+    this.maxRetries = options.maxRetries ?? 3;
+    this.debug = options.debug ?? false;
+  }
+
+  /**
+   * Execute a task on the given page with retry logic
+   * @param task - The task to execute
+   * @param page - Playwright page instance
+   * @returns Promise<TaskResult> with execution results
+   */
+  async execute(task: Task, page: Page): Promise<TaskResult> {
+    const goal = this.buildGoal(task);
+    const previousActions: ExecutedAction[] = [];
+    let retryCount = 0;
+
+    this.logDebug(`Starting task execution: ${goal}`);
+
+    while (retryCount < this.maxRetries) {
+      // Step 1: Extract DOM
+      const dom = await this.domExtractor.extract(page);
+      this.logDebug(`Extracted DOM with ${dom.elements.length} elements`);
+
+      if (this.debug) {
+        this.logDebug('DOM:', JSON.stringify(dom, null, 2));
+      }
+
+      // Step 2: Build action context
+      const context: ActionContext = {
+        goal,
+        previousActions,
+        retryCount,
+      };
+
+      // Step 3: Get action plan from Claude
+      const plan = await this.claudeClient.generateActionPlan(dom, context);
+      this.logDebug(`Action plan status: ${plan.status}`);
+
+      // Step 4: Handle plan status
+      if (plan.status === 'completed') {
+        this.logDebug('Task completed successfully');
+        return {
+          success: true,
+          message: `Task completed successfully. ${plan.reasoning}`,
+          actionsTaken: previousActions.map((ea) => ea.action),
+          finalUrl: page.url(),
+        };
+      }
+
+      if (plan.status === 'failed') {
+        this.logDebug(`Task failed: ${plan.error}`);
+        return {
+          success: false,
+          message: `Task failed: ${plan.error || 'Unknown error'}`,
+          actionsTaken: previousActions.map((ea) => ea.action),
+          finalUrl: page.url(),
+        };
+      }
+
+      // Step 5: Execute actions
+      const executor = new ActionExecutor(page, dom);
+      const executedActions = await executor.executeAll(plan.actions);
+
+      // Step 6: Add executed actions to history
+      previousActions.push(...executedActions);
+
+      // Step 7: Check for failures
+      const hasFailures = executedActions.some((ea) => !ea.success);
+
+      if (hasFailures) {
+        const failedActions = executedActions.filter((ea) => !ea.success);
+        this.logDebug(`Action execution failed: ${failedActions.map((ea) => ea.error).join(', ')}`);
+        retryCount++;
+
+        if (retryCount < this.maxRetries) {
+          this.logDebug(`Retrying (${retryCount}/${this.maxRetries})...`);
+          await page.waitForTimeout(2000);
+        }
+      } else {
+        this.logDebug('Actions executed successfully');
+      }
+
+      // Step 8: Wait between iterations
+      await page.waitForTimeout(1000);
+    }
+
+    // Max retries exceeded
+    this.logDebug('Max retries exceeded');
+    return {
+      success: false,
+      message: `Task failed after ${this.maxRetries} retries`,
+      actionsTaken: previousActions.map((ea) => ea.action),
+      finalUrl: page.url(),
+    };
+  }
+
+  /**
+   * Send a connection request to a LinkedIn profile
+   * @param profileUrl - URL of the LinkedIn profile
+   * @param note - Optional personalized note for the connection request
+   * @param page - Playwright page instance
+   * @returns Promise<ConnectionResult> with connection status
+   */
+  async connect(
+    profileUrl: string,
+    note: string | undefined,
+    page: Page
+  ): Promise<ConnectionResult> {
+    this.logDebug(`Navigating to profile: ${profileUrl}`);
+
+    // Step 1: Navigate to profile
+    await page.goto(profileUrl, {
+      waitUntil: 'domcontentloaded',
+      timeout: 30000,
+    });
+
+    // Step 2: Wait for page to settle
+    await page.waitForTimeout(3000);
+
+    // Step 3: Create and execute task
+    const task: Task = {
+      goal: 'Send connection request',
+      profileUrl,
+      note,
+    };
+
+    const result = await this.execute(task, page);
+
+    // Step 4: Extract final DOM to check connection state
+    const finalDom = await this.domExtractor.extract(page);
+    const connectionState = finalDom.metadata.connectionState;
+
+    // Determine the outcome
+    const sent = result.success && connectionState === 'pending';
+    const alreadyConnected = connectionState === 'connected';
+    const pending = connectionState === 'pending';
+
+    let message = result.message;
+    if (alreadyConnected) {
+      message = 'Already connected with this user';
+    } else if (sent) {
+      message = 'Connection request sent successfully';
+    } else if (pending) {
+      message = 'Connection request is pending';
+    }
+
+    return {
+      ...result,
+      sent,
+      pending,
+      alreadyConnected,
+      message,
+    };
+  }
+
+  /**
+   * Send a message to a LinkedIn connection
+   * @param profileUrl - URL of the LinkedIn profile
+   * @param message - Message text to send
+   * @param page - Playwright page instance
+   * @returns Promise<MessageResult> with message status
+   */
+  async sendMessage(profileUrl: string, message: string, page: Page): Promise<MessageResult> {
+    this.logDebug(`Navigating to profile for messaging: ${profileUrl}`);
+
+    // Step 1: Navigate to profile
+    await page.goto(profileUrl, {
+      waitUntil: 'domcontentloaded',
+      timeout: 30000,
+    });
+
+    // Step 2: Wait for page to settle
+    await page.waitForTimeout(3000);
+
+    // Step 3: Create and execute task
+    const task: Task = {
+      goal: 'Send message',
+      profileUrl,
+      message,
+    };
+
+    const result = await this.execute(task, page);
+
+    // Determine the outcome
+    const sent = result.success;
+    const finalMessage = sent ? 'Message sent successfully' : result.message;
+
+    return {
+      ...result,
+      sent,
+      message: finalMessage,
+    };
+  }
+
+  /**
+   * Build a goal string from task properties
+   * @param task - Task with goal, note, or message
+   * @returns Goal string for the agent
+   */
+  private buildGoal(task: Task): string {
+    // Use explicit goal if provided
+    if (task.goal) {
+      return task.goal;
+    }
+
+    // Build goal from note (connection request)
+    if (task.note !== undefined) {
+      return `Send connection request to ${task.profileUrl || 'profile'} with note: ${task.note}`;
+    }
+
+    // Build goal from message
+    if (task.message !== undefined) {
+      return `Send message to ${task.profileUrl || 'profile'}: ${task.message}`;
+    }
+
+    // Default goal
+    return 'Complete task on LinkedIn';
+  }
+
+  /**
+   * Log debug message if debug mode is enabled
+   * @param message - Message to log
+   * @param data - Optional data to log
+   */
+  private logDebug(message: string, data?: unknown): void {
+    if (this.debug) {
+      if (data !== undefined) {
+        console.log(`[PageAgent] ${message}`, data);
+      } else {
+        console.log(`[PageAgent] ${message}`);
+      }
+    }
+  }
+}
+
+/**
+ * Create a new PageAgent instance
+ * @param options - Configuration options
+ * @returns PageAgent instance
+ */
+export function createPageAgent(options: PageAgentOptions): PageAgent {
+  return new PageAgent(options);
+}