linkedin-automation-cli 1.0.0

package/dist/utils/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":";;;AAqEA,wCAKC;AA1ED,yCAA+C;AAQ/C,MAAa,WAAW;IACd,QAAQ,GAA0B,IAAI,GAAG,EAAE,CAAC;IAEpD,gBAAe,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,UAAU,CACd,UAA8B,EAAE;QAEhC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,SAAS,CAAC;QAC3C,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;QAC9C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;QAE9D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,WAAW,GAAG,GAAG,GAAG,QAAQ,CAAC;QAEnC,wCAAwC;QACxC,IAAI,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAEjD,4CAA4C;QAC5C,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC;QAEzD,uBAAuB;QACvB,IAAI,UAAU,CAAC,MAAM,IAAI,WAAW,EAAE,CAAC;YACrC,MAAM,eAAe,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YACtC,MAAM,UAAU,GAAG,eAAe,GAAG,QAAQ,GAAG,GAAG,CAAC;YAEpD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QACxC,CAAC;QAED,sBAAsB;QACtB,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QAEtC,oBAAoB;QACpB,MAAM,MAAM,GAAG,IAAA,sBAAc,GAAE,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,kBAAkB,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,IAAI,CAAC,CAAC;QAE/F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,YAAY,CAAC,UAA8B,EAAE;QACjD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAE9C,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACzC,MAAM,MAAM,GAAG,IAAA,sBAAc,GAAE,CAAC;YAChC,MAAM,CAAC,GAAG,CAAC,iBAAiB,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE,IAAI,CAAC,CAAC;YAEvE,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;CACF;AAxDD,kCAwDC;AAED,qBAAqB;AACrB,IAAI,WAAW,GAAuB,IAAI,CAAC;AAE3C,SAAgB,cAAc;IAC5B,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/utils/retry.d.ts

@@ -0,0 +1,18 @@
+export interface RetryOptions {
+    maxAttempts?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    backoffMultiplier?: number;
+    retryableErrors?: string[];
+    onRetry?: (attempt: number, error: Error, delay: number) => void;
+}
+export declare class RetryableError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Wrap a function to add retry behavior
+ */
+export declare function withRetryWrapper<T extends (...args: any[]) => Promise<any>>(fn: T, options?: RetryOptions): (...args: Parameters<T>) => Promise<ReturnType<T>>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAClE;AAED,qBAAa,cAAe,SAAQ,KAAK;aAGrB,KAAK,CAAC,EAAE,KAAK;gBAD7B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,KAAK,YAAA;CAKhC;AAED,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CA8C/F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACzE,EAAE,EAAE,CAAC,EACL,OAAO,GAAE,YAAiB,GACzB,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAEpD"}

package/dist/utils/retry.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryableError = void 0;
+exports.withRetry = withRetry;
+exports.withRetryWrapper = withRetryWrapper;
+const config_1 = require("../core/config");
+class RetryableError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'RetryableError';
+    }
+}
+exports.RetryableError = RetryableError;
+async function withRetry(fn, options = {}) {
+    const config = (0, config_1.getConfig)().get();
+    const { maxAttempts = 3, baseDelay = config.rateLimit, maxDelay = 30000, backoffMultiplier = 2, retryableErrors = ['network', 'timeout', 'rate', 'limit', '429', '503', '504'], onRetry, } = options;
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Check if this is a retryable error
+            const isRetryable = retryableErrors.some((pattern) => lastError.message.toLowerCase().includes(pattern.toLowerCase()));
+            if (!isRetryable || attempt === maxAttempts) {
+                throw new RetryableError(`Failed after ${attempt} attempt(s): ${lastError.message}`, lastError);
+            }
+            // Calculate delay with exponential backoff and jitter
+            const delay = Math.min(baseDelay * Math.pow(backoffMultiplier, attempt - 1), maxDelay);
+            const jitter = Math.random() * 1000; // Add up to 1s of jitter
+            const totalDelay = delay + jitter;
+            if (onRetry) {
+                onRetry(attempt, lastError, totalDelay);
+            }
+            await new Promise((resolve) => setTimeout(resolve, totalDelay));
+        }
+    }
+    throw new RetryableError('Unexpected exit from retry loop', lastError);
+}
+/**
+ * Wrap a function to add retry behavior
+ */
+function withRetryWrapper(fn, options = {}) {
+    return (...args) => withRetry(() => fn(...args), options);
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":";;;AAqBA,8BA8CC;AAKD,4CAKC;AA7ED,2CAA2C;AAW3C,MAAa,cAAe,SAAQ,KAAK;IAGrB;IAFlB,YACE,OAAe,EACC,KAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,UAAK,GAAL,KAAK,CAAQ;QAG7B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AARD,wCAQC;AAEM,KAAK,UAAU,SAAS,CAAI,EAAoB,EAAE,UAAwB,EAAE;IACjF,MAAM,MAAM,GAAG,IAAA,kBAAS,GAAE,CAAC,GAAG,EAAE,CAAC;IAEjC,MAAM,EACJ,WAAW,GAAG,CAAC,EACf,SAAS,GAAG,MAAM,CAAC,SAAS,EAC5B,QAAQ,GAAG,KAAK,EAChB,iBAAiB,GAAG,CAAC,EACrB,eAAe,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAC9E,OAAO,GACR,GAAG,OAAO,CAAC;IAEZ,IAAI,SAAS,GAAiB,IAAI,CAAC;IAEnC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACxD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAEtE,qCAAqC;YACrC,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CACnD,SAAU,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CACjE,CAAC;YAEF,IAAI,CAAC,WAAW,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;gBAC5C,MAAM,IAAI,cAAc,CACtB,gBAAgB,OAAO,gBAAgB,SAAS,CAAC,OAAO,EAAE,EAC1D,SAAS,CACV,CAAC;YACJ,CAAC;YAED,sDAAsD;YACtD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,OAAO,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;YACvF,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,yBAAyB;YAC9D,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,CAAC;YAElC,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;YAC1C,CAAC;YAED,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,MAAM,IAAI,cAAc,CAAC,iCAAiC,EAAE,SAAU,CAAC,CAAC;AAC1E,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAC9B,EAAK,EACL,UAAwB,EAAE;IAE1B,OAAO,CAAC,GAAG,IAAmB,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;AAC3E,CAAC"}

package/docs/connection-command.md

@@ -0,0 +1,52 @@
+# 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.

package/docs/plans/2025-03-03-linkedin-cli-design.md

@@ -0,0 +1,280 @@
+# LinkedIn CLI Design Document
+
+**Date:** 2025-03-03  
+**Status:** Approved  
+**Milestone:** 1 (Single user, CLI-only)
+
+## Overview
+
+A Go-based CLI tool that provides LinkedIn-specific automation on top of PinchTab. Designed for sales teams, starting with single-user personal use.
+
+## Goals
+
+- Send connection requests with personalized notes
+- Send direct messages to existing connections
+- Respect LinkedIn rate limits to avoid account restrictions
+- Simple CLI interface with profile management
+- Single binary deployment (no dependencies)
+
+## Non-Goals (Milestone 1)
+
+- Multi-user/multi-tenant support
+- Web UI or API server
+- Database persistence
+- Automated retry logic
+- Complex queue management
+
+## Architecture
+
+### Technology Stack
+
+- **Language:** Go 1.21+
+- **Browser Control:** PinchTab (HTTP API)
+- **CLI Framework:** Cobra
+- **Configuration:** JSON files
+- **Rate Limiting:** In-memory with JSON persistence
+
+### Package Structure
+
+```
+linkedin-cli/
+├── cmd/linkedin/           # Main entry point
+│   └── main.go
+├── internal/
+│   ├── cmd/                # Cobra commands
+│   │   ├── auth.go         # Authentication flow
+│   │   ├── connect.go      # Connection requests
+│   │   ├── message.go      # Direct messages
+│   │   ├── queue.go        # Batch processing
+│   │   ├── profiles.go     # Profile management
+│   │   └── root.go         # Root command setup
+│   ├── config/             # Configuration management
+│   │   ├── config.go       # Global config
+│   │   └── profile.go      # Profile storage
+│   ├── pinchtab/           # PinchTab HTTP client
+│   │   ├── client.go       # HTTP client
+│   │   ├── types.go        # API types
+│   │   └── actions.go      # Action builders
+│   ├── linkedin/           # LinkedIn-specific logic
+│   │   ├── selectors.go    # DOM selectors
+│   │   ├── navigator.go    # Page navigation
+│   │   └── validator.go    # URL validation
+│   └── ratelimit/          # Rate limiting
+       ├── limiter.go       # Limiter implementation
+       └── limits.go        # Limit definitions
+```
+
+## CLI Interface
+
+### Commands
+
+```bash
+# Profile management
+linkedin auth --profile <name>           # Interactive login
+linkedin profiles list                   # List profiles
+linkedin profiles remove <name>          # Delete profile
+
+# Connection requests
+linkedin connect --profile <name> \
+  --url <linkedin-url> \
+  --message <note>
+
+# Direct messages
+linkedin message --profile <name> \
+  --url <linkedin-url> \
+  --message <text>
+
+# Batch processing
+linkedin queue --profile <name> \
+  --file <csv-file>
+
+# Global flags
+--dry-run              # Show what would happen
+--verbose              # Detailed logging
+--yes                  # Skip confirmations
+```
+
+### Environment Variables
+
+```bash
+LINKEDIN_PROFILE       # Default profile name
+PINCHTAB_HOST          # PinchTab server (default: localhost:9867)
+```
+
+### Exit Codes
+
+- `0`: Success
+- `1`: General error
+- `2`: Rate limit exceeded
+- `3`: PinchTab not available
+- `4`: LinkedIn restriction detected
+- `5`: Invalid arguments
+
+## Data Flow
+
+### Connection Request Flow
+
+1. Parse CLI arguments and flags
+2. Load profile configuration
+3. Check rate limits (connections: 20/day, 100/week)
+4. Start PinchTab instance with profile
+5. Navigate to target LinkedIn URL
+6. Wait 3s for accessibility tree
+7. Locate "Connect" button via selector
+8. Execute `humanClick` (with randomization)
+9. If note modal appears:
+   - Find textarea
+   - Execute `humanType` with message
+   - Click "Send"
+10. Verify success (confirmation message or absence of error)
+11. Log action to rate limiter
+12. Return result
+
+### Direct Message Flow
+
+1. Parse CLI arguments
+2. Load profile and check rate limits (messages: 50/day)
+3. Navigate to conversation or profile
+4. Find message input
+5. Execute `humanType` with message
+6. Send (Enter key or click send button)
+7. Verify delivery
+8. Log action
+
+## Configuration
+
+### Profile Storage
+
+Location: `~/.linkedin-cli/profiles/<name>.json`
+
+```json
+{
+  "name": "john",
+  "pinchtab_profile": "linkedin-john",
+  "created_at": "2025-03-03T10:00:00Z",
+  "last_used": "2025-03-03T14:30:00Z"
+}
+```
+
+### Rate Limit State
+
+Location: `~/.linkedin-cli/ratelimit.json`
+
+```json
+{
+  "john": {
+    "connections": {
+      "today": 15,
+      "this_week": 87,
+      "last_action": "2025-03-03T14:30:00Z"
+    },
+    "messages": {
+      "today": 23,
+      "last_action": "2025-03-03T14:25:00Z"
+    }
+  }
+}
+```
+
+## Rate Limiting
+
+### Limits (LinkedIn-Safe)
+
+| Action | Daily | Weekly | Notes |
+|--------|-------|--------|-------|
+| Connection requests | 20 | 100 | Rolling windows |
+| Messages | 50 | - | Per profile |
+
+### Behavior
+
+- Counters reset automatically based on last action timestamp
+- Warnings at 80% of daily limit
+- Hard stop at 100% (exit code 2)
+- Human-like delays: 3-8 seconds between actions
+
+## Error Handling
+
+### Safety Mechanisms
+
+1. **Dry-run mode**: Preview actions without executing
+2. **Confirmation prompts**: Require explicit confirmation (bypass with `--yes`)
+3. **Circuit breaker**: Stop after 3 consecutive failures
+4. **LinkedIn detection**: Detect restriction messages, pause for 48 hours
+
+### Error Types
+
+- **PinchTab unavailable**: Clear error, suggest starting PinchTab
+- **Profile not found**: List available profiles
+- **Rate limit exceeded**: Show reset time
+- **Element not found**: Screenshot for debugging, retry once
+- **LinkedIn restriction**: Immediate stop, guidance on next steps
+
+## LinkedIn Selectors
+
+Selectors are defined in `internal/linkedin/selectors.go` and should be:
+- Based on accessibility attributes when possible
+- Fallback to stable CSS selectors
+- Documented with expected element text
+
+Example:
+```go
+var ConnectButton = Selector{
+    A11y:    "role='button' name='Connect'",
+    CSS:     "button[aria-label*='Connect']",
+    Text:    "Connect",
+}
+```
+
+## Testing Strategy
+
+### Unit Tests
+
+- `pinchtab/` package: Mock PinchTab server
+- `ratelimit/` package: Test calculations and resets
+- `linkedin/` package: Test URL validation
+
+### Integration Tests (Manual)
+
+- Auth flow with real LinkedIn
+- Connect/message on test accounts
+- Document expected behavior
+
+### No Automated E2E
+
+- LinkedIn blocks automation (can't run in CI)
+- Requires real accounts
+- `--dry-run` mode for validation
+
+## Future Milestones
+
+### Milestone 2: Multi-User
+
+- Multiple profiles with isolated sessions
+- Basic queue persistence
+- Configuration file support
+
+### Milestone 3: Team Features
+
+- Shared lead database (SQLite)
+- Campaign templates
+- Basic analytics
+
+### Milestone 4: Scale
+
+- Web UI for management
+- API server
+- Queue workers
+- Analytics dashboard
+
+## Dependencies
+
+- `github.com/spf13/cobra` - CLI framework
+- Standard library only for core functionality
+
+## Open Questions
+
+None at this time.
+
+## Approval
+
+Design approved on 2025-03-03.