linkedin-automation-cli 1.0.0

package/src/agent/claude-client.ts

@@ -0,0 +1,422 @@
+/**
+ * Claude API Client Module
+ *
+ * Client for interacting with the Claude API via Dashscope.
+ * Sends DOM representations and receives action plans for web automation.
+ */
+
+import {
+  type ActionPlan,
+  type ActionPlanStatus,
+  type Action,
+  type DOMRepresentation,
+  type ActionContext,
+  type ClaudeClientConfig,
+} from './types';
+
+/**
+ * Default configuration values
+ */
+const DEFAULT_BASE_URL = 'https://coding.dashscope.aliyuncs.com/apps/anthropic/v1';
+const DEFAULT_MODEL = 'qwen3.5-plus';
+const DEFAULT_MAX_TOKENS = 4096;
+
+/**
+ * Error thrown when the Claude API request fails
+ */
+export class ClaudeAPIError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode?: number,
+    public readonly responseBody?: string
+  ) {
+    super(message);
+    this.name = 'ClaudeAPIError';
+  }
+}
+
+/**
+ * Error thrown when the response cannot be parsed
+ */
+export class ClaudeParseError extends Error {
+  constructor(
+    message: string,
+    public readonly rawResponse?: string
+  ) {
+    super(message);
+    this.name = 'ClaudeParseError';
+  }
+}
+
+/**
+ * Message structure for Claude API
+ */
+interface Message {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * Request body for Claude API
+ */
+interface ClaudeRequest {
+  model: string;
+  max_tokens: number;
+  messages: Message[];
+}
+
+/**
+ * Response from Claude API
+ */
+interface ClaudeResponse {
+  id: string;
+  type: string;
+  role: string;
+  content: Array<{
+    type: string;
+    text: string;
+  }>;
+  model: string;
+  stop_reason: string | null;
+  stop_sequence: string | null;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+  };
+}
+
+/**
+ * Raw action structure from JSON parsing
+ */
+interface RawAction {
+  type: string;
+  description?: string;
+  elementId?: string;
+  text?: string;
+  durationMs?: number;
+  url?: string;
+}
+
+/**
+ * Raw action plan structure from JSON parsing
+ */
+interface RawActionPlan {
+  reasoning?: string;
+  expectedOutcome?: string;
+  actions?: RawAction[];
+  status?: ActionPlanStatus;
+  error?: string;
+}
+
+/**
+ * Client for interacting with the Claude API
+ */
+export class ClaudeClient {
+  private readonly config: Required<ClaudeClientConfig>;
+
+  constructor(config: ClaudeClientConfig) {
+    this.config = {
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl || DEFAULT_BASE_URL,
+      model: config.model || DEFAULT_MODEL,
+    };
+  }
+
+  /**
+   * Generates an action plan based on the current DOM state and context
+   */
+  async generateActionPlan(dom: DOMRepresentation, context: ActionContext): Promise<ActionPlan> {
+    const messages = this.buildMessages(dom, context);
+    const response = await this.makeAPICall(messages);
+    return this.parseResponse(response);
+  }
+
+  /**
+   * Builds the system and user messages for the API request
+   */
+  private buildMessages(dom: DOMRepresentation, context: ActionContext): Message[] {
+    return [
+      {
+        role: 'system',
+        content: this.buildSystemPrompt(),
+      },
+      {
+        role: 'user',
+        content: this.buildUserPrompt(dom, context),
+      },
+    ];
+  }
+
+  /**
+   * Builds the system prompt explaining the agent role and JSON format
+   */
+  private buildSystemPrompt(): string {
+    return `You are a web automation agent specialized in LinkedIn interactions.
+
+Your task is to analyze a DOM representation of a web page and determine the next action(s) to take to accomplish a goal.
+
+RULES:
+1. Respond ONLY with valid JSON. No markdown, no explanations outside JSON.
+2. The JSON must match this structure:
+   {
+     "reasoning": "string explaining your thought process",
+     "expectedOutcome": "string describing what should happen after these actions",
+     "actions": [
+       {
+         "type": "click|type|wait|navigate",
+         "description": "human-readable description of the action",
+         ...action-specific fields
+       }
+     ]
+   }
+
+AVAILABLE ACTIONS:
+- click: { type: "click", elementId: "string", description: "string" }
+- type: { type: "type", elementId: "string", text: "string", description: "string" }
+- wait: { type: "wait", durationMs: number, description: "string" }
+- navigate: { type: "navigate", url: "string", description: "string" }
+
+GUIDELINES:
+- Use element IDs from the provided DOM. Only reference elements that exist.
+- Break complex tasks into sequential actions.
+- Wait after actions that trigger page changes or loading.
+- If the goal is already achieved, return an empty actions array with appropriate reasoning.
+- If stuck or unable to proceed, explain why in the reasoning field.`;
+  }
+
+  /**
+   * Builds the user prompt with goal, DOM, and previous actions
+   */
+  private buildUserPrompt(dom: DOMRepresentation, context: ActionContext): string {
+    const previousActionsText =
+      context.previousActions.length > 0
+        ? context.previousActions
+            .map(
+              (action, index) =>
+                `${index + 1}. ${action.action.type}: ${action.action.description} (${action.success ? 'success' : 'failed'}${action.error ? ` - ${action.error}` : ''})`
+            )
+            .join('\n')
+        : 'None';
+
+    return `Goal: ${context.goal}
+
+Current page DOM:
+\`\`\`json
+${JSON.stringify(dom, null, 2)}
+\`\`\`
+
+Previous actions taken:
+${previousActionsText}
+
+Retry count: ${context.retryCount}
+
+What action(s) should be taken next? Respond with the JSON action plan.`;
+  }
+
+  /**
+   * Makes the API call to Claude
+   */
+  private async makeAPICall(messages: Message[]): Promise<ClaudeResponse> {
+    const url = `${this.config.baseUrl}/messages`;
+    const body: ClaudeRequest = {
+      model: this.config.model,
+      max_tokens: DEFAULT_MAX_TOKENS,
+      messages,
+    };
+
+    let response: globalThis.Response;
+    try {
+      response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.config.apiKey}`,
+        },
+        body: JSON.stringify(body),
+      });
+    } catch (error) {
+      throw new ClaudeAPIError(
+        `Failed to connect to Claude API: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    if (!response.ok) {
+      const responseBody = await response.text();
+      throw new ClaudeAPIError(
+        `Claude API error: ${response.status} ${response.statusText}`,
+        response.status,
+        responseBody
+      );
+    }
+
+    try {
+      return (await response.json()) as ClaudeResponse;
+    } catch (error) {
+      throw new ClaudeAPIError(
+        `Failed to parse Claude API response: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  /**
+   * Parses the API response into an ActionPlan
+   */
+  private parseResponse(response: ClaudeResponse): ActionPlan {
+    const content = response.content.find((c) => c.type === 'text');
+
+    if (!content) {
+      return this.createErrorPlan('No text content in Claude response');
+    }
+
+    const jsonText = this.extractJSON(content.text);
+
+    if (!jsonText) {
+      return this.createErrorPlan('Could not extract JSON from response');
+    }
+
+    try {
+      const raw = JSON.parse(jsonText) as RawActionPlan;
+      return this.validateAndTransformPlan(raw);
+    } catch (error) {
+      return this.createErrorPlan(
+        `Failed to parse action plan JSON: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  /**
+   * Extracts JSON from a string that may contain markdown or extra text
+   */
+  private extractJSON(text: string): string | null {
+    // Try to find JSON in code blocks
+    const codeBlockMatch = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    if (codeBlockMatch) {
+      return codeBlockMatch[1].trim();
+    }
+
+    // Try to find JSON between curly braces
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+      return jsonMatch[0].trim();
+    }
+
+    // If the text looks like it starts with JSON, return it as-is
+    if (text.trim().startsWith('{')) {
+      return text.trim();
+    }
+
+    return null;
+  }
+
+  /**
+   * Validates and transforms the raw plan into a proper ActionPlan
+   */
+  private validateAndTransformPlan(raw: RawActionPlan): ActionPlan {
+    const actions: Action[] = [];
+
+    if (raw.actions && Array.isArray(raw.actions)) {
+      for (const rawAction of raw.actions) {
+        const action = this.transformAction(rawAction);
+        if (action) {
+          actions.push(action);
+        }
+      }
+    }
+
+    return {
+      reasoning: raw.reasoning || 'No reasoning provided',
+      expectedOutcome: raw.expectedOutcome || 'No expected outcome provided',
+      actions,
+      status: this.validateStatus(raw.status),
+      error: raw.error,
+    };
+  }
+
+  /**
+   * Transforms a raw action into a properly typed Action
+   */
+  private transformAction(rawAction: RawAction): Action | null {
+    const description = rawAction.description || 'No description provided';
+
+    switch (rawAction.type) {
+      case 'click': {
+        if (!rawAction.elementId) {
+          console.warn('Click action missing elementId');
+          return null;
+        }
+        return {
+          type: 'click',
+          elementId: rawAction.elementId,
+          description,
+        };
+      }
+
+      case 'type': {
+        if (!rawAction.elementId || rawAction.text === undefined) {
+          console.warn('Type action missing elementId or text');
+          return null;
+        }
+        return {
+          type: 'type',
+          elementId: rawAction.elementId,
+          text: rawAction.text,
+          description,
+        };
+      }
+
+      case 'wait': {
+        if (rawAction.durationMs === undefined) {
+          console.warn('Wait action missing durationMs, using default 1000ms');
+        }
+        return {
+          type: 'wait',
+          durationMs: rawAction.durationMs || 1000,
+          description,
+        };
+      }
+
+      case 'navigate': {
+        if (!rawAction.url) {
+          console.warn('Navigate action missing url');
+          return null;
+        }
+        return {
+          type: 'navigate',
+          url: rawAction.url,
+          description,
+        };
+      }
+
+      default:
+        console.warn(`Unknown action type: ${rawAction.type}`);
+        return null;
+    }
+  }
+
+  /**
+   * Validates and returns a valid status
+   */
+  private validateStatus(status: ActionPlanStatus | undefined): ActionPlanStatus {
+    const validStatuses: ActionPlanStatus[] = [
+      'pending',
+      'in_progress',
+      'completed',
+      'failed',
+      'cancelled',
+    ];
+    return status && validStatuses.includes(status) ? status : 'pending';
+  }
+
+  /**
+   * Creates an error action plan
+   */
+  private createErrorPlan(message: string): ActionPlan {
+    return {
+      reasoning: 'Failed to generate action plan',
+      expectedOutcome: 'No actions can be taken due to error',
+      actions: [],
+      status: 'failed',
+      error: message,
+    };
+  }
+}