linkedin-automation-cli 1.0.0

package/docs/superpowers/specs/2026-03-15-profile-extraction-design.md

@@ -0,0 +1,409 @@
+# LinkedIn Profile Extraction Feature Design
+
+**Date:** 2026-03-15
+**Status:** Draft
+**Author:** Claude
+
+## Overview
+
+Add a feature to extract structured profile data from LinkedIn user profiles. This enables use cases like lead qualification, contact enrichment, and CRM integration.
+
+## Requirements
+
+### Input
+- LinkedIn profile URL (e.g., `https://www.linkedin.com/in/patrick-fabre-b988ab10a/`)
+- Optional: `--include-contact` flag to extract email/phone
+
+### Output Fields
+
+| Field | Source | Use Case |
+|-------|--------|----------|
+| `full_name` | Top card | Contact |
+| `headline` | Top card | Current role |
+| `location` | Top card | Geography |
+| `current_company` | Experience section | Employer |
+| `current_title` | Experience section | Job title |
+| `years_experience` | Calculated from experience | Seniority |
+| `company_linkedin_url` | Experience section | Link to company |
+| `email` | Contact info panel | Direct contact |
+| `phone` | Contact info panel | Direct contact |
+
+### Constraints
+- Requires authenticated LinkedIn session (connect via CDP to logged-in browser)
+- Must handle LinkedIn's dynamic DOM with multi-layer selector fallbacks
+- Contact info requires clicking to reveal (optional)
+
+## Architecture
+
+```
+CLI (profile get <url>)
+        │
+        ▼
+┌─────────────────────────┐
+│   src/cli/profile.ts    │
+│  registerProfileCommands│
+└─────────────────────────┘
+        │
+        ▼
+┌─────────────────────────┐
+│ src/linkedin/profile.ts │
+│    LinkedInProfile      │
+│ - extract(url, opts)    │
+│ - uses SelectorEngine   │
+└─────────────────────────┘
+        │
+        ▼
+┌─────────────────────────┐
+│   src/types/index.ts    │
+│ ProfileData,            │
+│ ProfileExtractionResult │
+└─────────────────────────┘
+```
+
+**Naming Convention**: Class is named `LinkedInProfile` (not `LinkedInProfileScraper`) to match existing patterns: `LinkedInConnector`, `LinkedInMessages`, `LinkedInAuth`.
+
+## Data Model
+
+```typescript
+// src/types/index.ts
+
+export interface ProfileData {
+  // Top card fields
+  full_name: string;
+  headline: string;
+  location: string;
+
+  // Experience section
+  current_company: string | null;
+  current_title: string | null;
+  company_linkedin_url: string | null;
+
+  // Calculated
+  years_experience: number | null;
+
+  // Contact info (optional - requires clicking to reveal)
+  email: string | null;
+  phone: string | null;
+
+  // Reference
+  profile_url: string;  // Canonical URL after LinkedIn redirects
+}
+
+export interface ProfileExtractionOptions {
+  profileUrl: string;
+  includeContact?: boolean;
+  timeout?: number;
+}
+
+// Result type following existing pattern (ConnectionResult, MessageResult)
+export interface ProfileExtractionResult {
+  success: boolean;
+  message: string;
+  data?: ProfileData;
+  error?: string;
+}
+```
+
+## URL Validation
+
+```typescript
+// Regex pattern for LinkedIn profile URLs
+const LINKEDIN_PROFILE_URL_REGEX = /^https?:\/\/(?:www\.)?linkedin\.com\/in\/[^\/]+\/?$/;
+
+function validateProfileUrl(url: string): boolean {
+  return LINKEDIN_PROFILE_URL_REGEX.test(url);
+}
+```
+
+## CLI Interface
+
+```bash
+# Basic usage (connect to CDP on default port)
+linkedin-cli profile get https://www.linkedin.com/in/patrick-fabre-b988ab10a/
+
+# With contact info extraction
+linkedin-cli profile get https://www.linkedin.com/in/patrick-fabre-b988ab10a/ --include-contact
+
+# JSON output
+linkedin-cli profile get https://www.linkedin.com/in/patrick-fabre-b988ab10a/ --json
+
+# Custom CDP port
+linkedin-cli profile get https://www.linkedin.com/in/patrick-fabre-b988ab10a/ --cdp-port 9223
+```
+
+### Output Format (default)
+
+```
+Profile: Patrick Fabre
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Headline:      Engineering Manager at Company
+Location:      San Francisco Bay Area
+Company:       Company Name
+Title:         Engineering Manager
+Company URL:   linkedin.com/company/...
+Experience:    12 years
+Email:         (use --include-contact to reveal)
+Phone:         (use --include-contact to reveal)
+```
+
+### Output Format (--json)
+
+```json
+{
+  "full_name": "Patrick Fabre",
+  "headline": "Engineering Manager at Company",
+  "location": "San Francisco Bay Area",
+  "current_company": "Company Name",
+  "current_title": "Engineering Manager",
+  "company_linkedin_url": "https://www.linkedin.com/company/...",
+  "years_experience": 12,
+  "email": null,
+  "phone": null
+}
+```
+
+## Selectors
+
+Add to `src/linkedin/selectors.ts`:
+
+```typescript
+profile: {
+  // Top card
+  name: [
+    'h1.text-heading-xlarge',
+    '[data-testid="top-card-profile-name"]',
+    '.pv-top-card .text-heading-xlarge',
+    'section.artdeco-card h1',
+  ],
+  headline: [
+    '.text-body-medium',
+    '[data-testid="top-card-profile-headline"]',
+    '.pv-top-card .text-body-medium',
+  ],
+  location: [
+    '.text-body-small.inline.t-black--light',
+    '[data-testid="top-card-profile-location"]',
+    '.pv-top-card .text-body-small',
+  ],
+
+  // Experience section
+  experienceSection: [
+    '#experience',
+    'section[id*="experience"]',
+    '[data-testid="experience-section"]',
+  ],
+  experienceList: [
+    '.pv-profile-section__list-item',
+    '[data-testid="experience-item"]',
+    'li[class*="experience"]',
+  ],
+  experienceTitle: [
+    '.pv-entity__secondary-title',
+    '[data-testid="experience-title"]',
+    'span[aria-hidden="true"]',
+  ],
+  experienceCompany: [
+    '.pv-entity__company-summary-info',
+    '[data-testid="experience-company"]',
+    'a[href*="/company/"]',
+  ],
+  experienceDuration: [
+    '.pv-entity__date-range',
+    '[data-testid="experience-duration"]',
+    'span[class*="date-range"]',
+  ],
+  companyLink: [
+    'a[href*="/company/"]',
+    '[data-testid="company-link"]',
+  ],
+
+  // Contact info
+  contactInfoButton: [
+    'a[href*="contact-info"]',
+    'button[aria-label*="contact info" i]',
+    '[data-control-name="contact_see_more"]',
+  ],
+  contactInfoPanel: [
+    '.pv-contact-info',
+    '[data-testid="contact-info-panel"]',
+    '.artdeco-modal__content',
+  ],
+  contactInfoCloseButton: [
+    '.artdeco-modal__dismiss',
+    'button[aria-label*="Dismiss"]',
+    'button[aria-label*="Close"]',
+    '[data-testid="modal-close"]',
+  ],
+  email: [
+    'a[href^="mailto:"]',
+    '[data-testid="contact-email"]',
+    '.pv-contact-info__contact-type[href*="mailto"]',
+  ],
+  phone: [
+    'a[href^="tel:"]',
+    '[data-testid="contact-phone"]',
+    '.pv-contact-info__contact-type[href*="tel"]',
+  ],
+},
+```
+
+## Experience Duration Parsing Algorithm
+
+LinkedIn displays experience durations in formats like:
+- `"Jan 2020 - Present (5 yrs 3 mos)"`
+- `"2018 - 2022 (4 years)"`
+- `"Mar 2019 - Dec 2021 (2 yrs 10 mos)"`
+
+```typescript
+interface ParsedDuration {
+  startDate: Date;
+  endDate: Date | null; // null for "Present"
+  years: number;
+}
+
+function parseDurationString(durationText: string): ParsedDuration | null {
+  // Pattern: "Jan 2020 - Present (5 yrs 3 mos)" or "2018 - 2022 (4 years)"
+  const presentPattern = /^(\w+\s+\d{4})\s*-\s*Present\s*\((\d+)\s*yrs?\s*(?:\d+\s*mos?)?\)$/i;
+  const rangePattern = /^(\w+\s+\d{4})\s*-\s*(\w+\s+\d{4})\s*\((\d+)\s*years?\)$/i;
+  const yearOnlyPattern = /^(\d{4})\s*-\s*(\d{4})\s*\((\d+)\s*years?\)$/i;
+
+  // Try each pattern...
+  let match = durationText.match(presentPattern);
+  if (match) {
+    const startDate = parseMonthYear(match[1]);
+    const years = parseInt(match[2]);
+    return { startDate, endDate: null, years };
+  }
+
+  match = durationText.match(rangePattern);
+  if (match) {
+    const startDate = parseMonthYear(match[1]);
+    const endDate = parseMonthYear(match[2]);
+    const years = parseInt(match[3]);
+    return { startDate, endDate, years };
+  }
+
+  match = durationText.match(yearOnlyPattern);
+  if (match) {
+    const startDate = new Date(parseInt(match[1]), 0, 1);
+    const endDate = new Date(parseInt(match[2]), 11, 31);
+    const years = parseInt(match[3]);
+    return { startDate, endDate, years };
+  }
+
+  return null;
+}
+
+function calculateTotalExperience(durations: ParsedDuration[]): number {
+  // Sum years from all non-overlapping positions
+  // For simplicity, sum the "years" values (LinkedIn already calculates this)
+  return durations.reduce((total, d) => total + d.years, 0);
+}
+```
+
+**Note**: We only extract visible experience items. If "See all X experiences" button exists, we do NOT click it (avoids additional navigation delay). The `years_experience` is calculated from visible entries only.
+
+## Contact Info Modal Handling
+
+When `--include-contact` flag is used:
+
+1. **Open modal**: Click contact info button
+2. **Wait for panel**: Wait for modal/panel to appear (2000ms)
+3. **Extract data**: Get email and phone values
+4. **Close modal**: Click dismiss button or press Escape
+5. **Verify closed**: Wait for modal to disappear (1000ms)
+
+```typescript
+async extractContactInfo(page: Page): Promise<{ email: string | null; phone: string | null }> {
+  // Click contact info button
+  const contactButton = await this.findElement('profile', 'contactInfoButton');
+  if (!contactButton) {
+    return { email: null, phone: null };
+  }
+
+  await contactButton.click();
+  await page.waitForTimeout(2000);
+
+  // Extract email and phone
+  const email = await this.extractText('profile', 'email');
+  const phone = await this.extractText('profile', 'phone');
+
+  // Close modal
+  const closeButton = await this.findElement('profile', 'contactInfoCloseButton');
+  if (closeButton) {
+    await closeButton.click();
+  } else {
+    await page.keyboard.press('Escape');
+  }
+  await page.waitForTimeout(1000);
+
+  return { email, phone };
+}
+```
+
+## Files to Create/Modify
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/linkedin/profile.ts` | Create | `LinkedInProfile` class using `SelectorEngine` |
+| `src/cli/profile.ts` | Create | CLI command registration |
+| `src/linkedin/selectors.ts` | Modify | Add `profile` selector group |
+| `src/types/index.ts` | Modify | Add `ProfileData`, `ProfileExtractionOptions`, `ProfileExtractionResult` types |
+| `src/cli/index.ts` | Modify | Export `registerProfileCommands` |
+| `.env.example` | Modify | Add `PAGE_AGENT_CDP_PORT` |
+
+## Environment Variables
+
+```bash
+# .env.example
+PAGE_AGENT_CDP_PORT=9222
+```
+
+Default CDP port is `9222`. Override via `PAGE_AGENT_CDP_PORT` environment variable.
+
+## Error Handling
+
+- **Navigation timeout**: Return error with message "Profile page not found or timeout"
+- **Missing required fields**: Return error if `full_name` cannot be extracted
+- **Contact info unavailable**: Return `null` for email/phone if not found or not accessible
+- **Invalid URL**: Validate URL format before navigation
+
+## Testing Strategy
+
+1. **Unit tests**: Selector extraction logic with fixture HTML
+2. **Integration tests**: Mock Playwright page responses
+3. **E2E tests**: Test against real LinkedIn profile (requires logged-in browser)
+
+## Security Considerations
+
+- Profile data may contain PII - handle according to privacy requirements
+- Rate limiting: Respect LinkedIn's rate limits (reuse existing rate limiter from `src/utils/rate-limiter.ts`)
+- Session security: Use existing encrypted session storage
+
+## Audit Logging
+
+All profile extraction operations should be logged using the existing audit logger:
+
+```typescript
+import { getAuditLogger } from '../core/audit';
+
+// Log profile extraction attempt
+await getAuditLogger().log({
+  action: 'profile_extract',
+  details: {
+    profileUrl: options.profileUrl,
+    includeContact: options.includeContact ?? false,
+    success: result.success,
+    extractedFields: Object.keys(result.data || {}).filter(
+      k => result.data?.[k as keyof ProfileData] !== null
+    ),
+  },
+  success: result.success,
+  error: result.error,
+});
+```
+
+**Audit events to log:**
+- `profile_extract` - Profile extraction attempt (success or failure)
+- Include which fields were successfully extracted
+- Include error message on failure

package/eslint.config.mjs

@@ -0,0 +1,58 @@
+import eslint from '@eslint/js';
+import tseslint from '@typescript-eslint/eslint-plugin';
+import parser from '@typescript-eslint/parser';
+import prettierConfig from 'eslint-config-prettier';
+
+export default [
+  eslint.configs.recommended,
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      parser: parser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+      },
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        exports: 'readonly',
+        module: 'readonly',
+        require: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        AbortSignal: 'readonly',
+        document: 'readonly',
+        Element: 'readonly',
+        HTMLElement: 'readonly',
+        window: 'readonly',
+        navigator: 'readonly',
+        localStorage: 'readonly',
+        Notification: 'readonly',
+        fetch: 'readonly',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': ['error', {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+      }],
+      'no-useless-escape': 'off',
+      '@typescript-eslint/no-var-requires': 'off',
+    },
+  },
+  prettierConfig,
+  {
+    ignores: ['node_modules/', 'dist/', 'coverage/', '*.js'],
+  },
+];

package/go.mod

@@ -0,0 +1,9 @@
+module github.com/thaddeus-git/linkedin-cli
+
+go 1.21
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/cobra v1.10.2 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
+)

package/go.sum

@@ -0,0 +1,10 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=