linkedin-automation-cli 1.0.0

package/NPM_PUBLISHING.md

@@ -0,0 +1,230 @@
+# npm Publishing Guide
+
+This guide walks you through publishing the LinkedIn Automation CLI to npm.
+
+## Prerequisites
+
+1. **npm account**: You mentioned you have one - great!
+2. **Logged in to npm**: Run `npm login` if you haven't already
+
+## Initial Setup (One-Time)
+
+### 1. Login to npm
+
+```bash
+npm login
+```
+
+You'll be prompted for:
+- Username
+- Password
+- Email
+- OTP (if you have 2FA enabled)
+
+### 2. Verify Login
+
+```bash
+npm whoami
+```
+
+Should return your npm username.
+
+## Publishing a New Version
+
+### Step 1: Run Full Test Suite
+
+```bash
+# Run all quality checks
+npm run typecheck      # TypeScript compilation check
+npm run lint           # ESLint
+npm run format:check   # Prettier format check
+npm run test:coverage  # Tests with coverage (requires 80%+)
+```
+
+**All must pass** before publishing.
+
+### Step 2: Build the Project
+
+```bash
+npm run build
+```
+
+Verify the output:
+```bash
+ls -la dist/
+node dist/index.js --help
+```
+
+### Step 3: Bump Version
+
+npm uses [Semantic Versioning](https://semver.org/):
+
+```bash
+# Choose one based on your changes:
+npm version patch  # Bug fix: 0.1.0 → 0.1.1
+npm version minor  # New feature: 0.1.0 → 0.2.0
+npm version major  # Breaking change: 0.1.0 → 1.0.0
+```
+
+This will:
+- Update version in package.json
+- Create a git commit
+- Create a git tag (e.g., v0.1.0)
+
+### Step 4: Push to GitHub
+
+```bash
+git push origin main
+git push origin v0.1.0  # Replace with your version tag
+```
+
+Pushing the tag triggers the GitHub Actions publish workflow automatically!
+
+### Step 5: Manual Publish (Alternative)
+
+If you want to publish manually instead of using GitHub Actions:
+
+```bash
+# Dry run first (see what will be published)
+npm publish --dry-run
+
+# Actual publish
+npm publish --access public
+```
+
+### Step 6: Verify Publication
+
+```bash
+# Check on npm registry
+npm view linkedin-automation-cli
+
+# Or visit in browser
+# https://www.npmjs.com/package/linkedin-automation-cli
+```
+
+## Installation Test
+
+After publishing, test installation:
+
+```bash
+# In a fresh directory
+npm install -g linkedin-automation-cli
+linkedin-automation --help
+```
+
+## CI/CD Automatic Publishing
+
+The project includes a GitHub Actions workflow (`.github/workflows/publish.yml`) that automatically publishes when you push a version tag.
+
+### Required GitHub Secret
+
+You need to add your npm token to GitHub:
+
+1. Get your npm token:
+   ```bash
+   npm token create --read-only
+   ```
+
+2. In GitHub, go to your repo → Settings → Secrets and variables → Actions
+
+3. Add a new secret:
+   - Name: `NPM_TOKEN`
+   - Value: Your npm token from step 1
+
+### Automatic Release Flow
+
+```bash
+# Just bump version and push tag
+npm version minor
+git push && git push --tags
+```
+
+GitHub Actions will:
+1. Run full CI (typecheck, lint, test, coverage)
+2. Build the project
+3. Publish to npm
+4. Create a GitHub Release
+
+## Troubleshooting
+
+### "EPUBLISHCONFLICT: Cannot publish"
+
+You're trying to publish a version that already exists. Bump the version:
+
+```bash
+npm version patch
+```
+
+### "E404: Not found"
+
+Package name might be taken. Check:
+```bash
+npm view linkedin-automation-cli
+```
+
+### 2FA Issues
+
+If npm requires 2FA for publishing:
+
+```bash
+# Publish with OTP
+npm publish --otp=123456
+```
+
+Or configure npm to require 2FA only for login:
+```bash
+npm profile set-lifecycle-script 2fa
+```
+
+### Coverage Below 80%
+
+If tests don't meet the 80% threshold:
+
+```bash
+# See detailed coverage report
+npm run test:coverage
+
+# Open HTML report
+open coverage/index.html
+```
+
+Add more tests for uncovered code.
+
+## Version Naming Examples
+
+| Scenario | Command | Result |
+|----------|---------|--------|
+| Bug fix | `npm version patch` | 0.1.0 → 0.1.1 |
+| New feature | `npm version minor` | 0.1.0 → 0.2.0 |
+| Breaking change | `npm version major` | 0.1.0 → 1.0.0 |
+| Pre-release | `npm version prerelease` | 0.1.0 → 0.1.1-0 |
+
+## Best Practices
+
+1. **Never skip tests** - Always run full CI before publishing
+2. **Use semantic versioning** - Communicates breaking changes to users
+3. **Write changelog** - Document what changed in each version
+4. **Test installation** - Verify published package works
+5. **Tag releases** - GitHub releases help track versions
+
+## Unpublishing (Emergency Only)
+
+```bash
+# Only within 72 hours of publishing
+npm unpublish linkedin-automation-cli@0.1.0
+```
+
+npm has strict unpublish policies. Use only for mistakes or security issues.
+
+---
+
+**Quick Reference:**
+
+```bash
+# Full publish workflow
+npm run test:coverage && \
+npm run build && \
+npm version minor && \
+git push && git push --tags
+# GitHub Actions handles the rest!
+```

package/README.md

@@ -0,0 +1,295 @@
+# LinkedIn Automation CLI
+
+A TypeScript CLI tool for LinkedIn automation using Playwright. Designed for sales representatives to manage LinkedIn messaging efficiently.
+
+## Features
+
+- **Authentication**: Secure login with 2FA/TOTP support (Microsoft Authenticator)
+- **Message Management**: List conversations, read threads, send replies
+- **Templates**: Template-based message drafting with variable substitution
+- **Session Persistence**: Encrypted session storage for seamless re-authentication
+- **Rate Limiting**: Built-in protection against LinkedIn rate limits
+- **Audit Logging**: Complete audit trail of all actions
+
+## Installation
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd linkedin-automation-cli
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Link for global access (optional)
+npm link
+```
+
+## Quick Start
+
+### 1. Login to LinkedIn
+
+```bash
+# Interactive login (will prompt for email, password, and 2FA if needed)
+linkedin-cli auth login
+
+# Or provide email inline
+linkedin-cli auth login --email your@email.com
+```
+
+### 2. List Conversations
+
+```bash
+# List recent conversations
+linkedin-cli messages list
+
+# Show only unread
+linkedin-cli messages list --unread
+
+# Limit to 10 results
+linkedin-cli messages list --limit 10
+```
+
+### 3. Read a Conversation
+
+```bash
+linkedin-cli messages show --thread 1234567890
+```
+
+### 4. Send a Reply
+
+```bash
+# Send a message inline
+linkedin-cli reply send --thread 1234567890 --message "Thanks for your message!"
+
+# Send from file
+linkedin-cli reply send --thread 1234567890 --file message.txt
+
+# Dry run (simulate without sending)
+linkedin-cli reply send --thread 1234567890 --message "Test" --dry-run
+```
+
+### 5. Use Templates
+
+```bash
+# List available templates
+linkedin-cli templates list
+
+# Generate a message from template
+linkedin-cli draft --thread 1234567890 --template welcome --var firstName=John --var company=Acme
+
+# Preview without sending
+linkedin-cli draft --thread 1234567890 --template welcome --var firstName=John --preview
+```
+
+## Configuration
+
+Configuration is stored in `~/.linkedin-cli/config.json`:
+
+```bash
+# View current config
+linkedin-cli config --get
+
+# Set values
+linkedin-cli config --set headless=false
+linkedin-cli config --set rateLimit=10000
+```
+
+### Available Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `headless` | `true` | Run browser in headless mode |
+| `rateLimit` | `5000` | Delay between actions (ms) |
+| `sessionTimeout` | `86400000` | Session validity (24 hours) |
+| `dryRun` | `false` | Default dry-run mode |
+
+## Templates
+
+Templates use Handlebars-style variable substitution:
+
+```
+Hi {{firstName}},
+
+Thanks for connecting! I noticed you're working at {{company}}.
+
+Best regards,
+{{senderName}}
+```
+
+### Creating Custom Templates
+
+1. Create a file in `~/.linkedin-cli/templates/custom/`:
+
+```bash
+mkdir -p ~/.linkedin-cli/templates/custom
+cat > ~/.linkedin-cli/templates/custom/intro.txt << 'EOF'
+---
+name: Introduction
+description: Brief introduction template
+category: welcome
+---
+
+Hi {{firstName}},
+
+I'm {{senderName}} from {{company}}. I came across your profile and was impressed by your experience in {{industry}}.
+
+I'd love to connect and learn more about your work.
+
+Best regards,
+{{senderName}}
+EOF
+```
+
+2. Use the template:
+
+```bash
+linkedin-cli draft --thread 1234567890 --template intro --var firstName=John --var industry=Tech
+```
+
+## Security
+
+- **Encrypted Storage**: Sessions and credentials are encrypted using AES-256-GCM
+- **Machine-Bound**: Encryption keys are derived from machine-specific data
+- **No Credential Storage**: Passwords are never stored; only session cookies
+- **Audit Logging**: All actions are logged to `~/.linkedin-cli/audit.log`
+
+## Troubleshooting
+
+### Login Issues
+
+```bash
+# Check auth status
+linkedin-cli auth status
+
+# Re-login if needed
+linkedin-cli auth logout
+linkedin-cli auth login
+```
+
+### Rate Limiting
+
+If you encounter rate limiting:
+
+```bash
+# Increase rate limit delay
+linkedin-cli config --set rateLimit=10000
+
+# Use non-headless mode to see what's happening
+linkedin-cli messages list --headless false
+```
+
+### Selector Failures
+
+If LinkedIn UI changes cause failures:
+
+1. Check the audit log: `cat ~/.linkedin-cli/audit.log`
+2. Run with non-headless mode to see the current state
+3. The multi-layer selector system will attempt fallbacks automatically
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run watch
+
+# Run locally
+node dist/index.js --help
+```
+
+### Quality Checks
+
+```bash
+# Type check
+npm run typecheck
+
+# Lint
+npm run lint
+npm run lint:fix  # Auto-fix issues
+
+# Format
+npm run format:check
+npm run format    # Auto-format code
+
+# Run tests
+npm run test           # Run tests
+npm run test:watch     # Watch mode
+npm run test:coverage  # With coverage report
+```
+
+### Pre-commit Hooks
+
+Husky runs automatically before each commit:
+- ESLint validation
+- Prettier format check
+
+If the hook fails, fix the issues and re-commit.
+
+### Testing
+
+Tests are written with Vitest and located alongside source files:
+
+```
+src/
+├── core/
+│   ├── storage.ts
+│   └── storage.test.ts
+├── templates/
+│   ├── engine.ts
+│   └── engine.test.ts
+```
+
+Coverage threshold: 80% minimum across all files.
+
+## Publishing
+
+See [NPM_PUBLISHING.md](./NPM_PUBLISHING.md) for detailed publishing instructions.
+
+### Quick Publish
+
+```bash
+# Run all checks
+npm run test:coverage
+npm run build
+
+# Bump version (choose: patch, minor, major)
+npm version patch
+
+# Push (triggers auto-publish via GitHub Actions)
+git push && git push --tags
+```
+
+### Manual Publish
+
+```bash
+npm login              # One-time setup
+npm publish --dry-run  # Preview
+npm publish --access public
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please ensure:
+- TypeScript compiles without errors
+- Follow existing code style
+- Add tests for new features
+- Update documentation
+
+---
+
+**Disclaimer**: This tool is for legitimate sales and business development purposes. Users are responsible for complying with LinkedIn's Terms of Service and applicable laws. Use responsibly and respect rate limits to avoid account restrictions.

package/TESTING-GUIDE.md

@@ -0,0 +1,151 @@
+# LinkedIn CLI Testing Guide
+
+## 🧪 Safe Testing Protocol
+
+### Step 1: Dry Run Mode (Safe)
+Test all commands without actually connecting to LinkedIn:
+
+```bash
+# Test help commands
+node ./dist/index.js --help
+node ./dist/index.js auth --help
+node ./dist/index.js messages --help
+node ./dist/index.js connect --help
+```
+
+### Step 2: Configuration Test
+```bash
+# View default config
+node ./dist/index.js config --get
+
+# Set dry-run mode for safety
+node ./dist/index.js config --set dryRun=true
+```
+
+### Step 3: Authentication Test (Requires Credentials)
+
+**Option A: Interactive Login (Recommended)**
+```bash
+# Run in non-headless mode so you can see what's happening
+node ./dist/index.js auth login --headless false
+```
+
+**Option B: With Email Provided**
+```bash
+node ./dist/index.js auth login --email your@email.com --headless false
+```
+
+**What you'll see:**
+1. Browser opens
+2. LinkedIn login page loads
+3. You'll enter password manually (secure)
+4. If 2FA is enabled, you'll enter the TOTP code
+5. Session is saved securely
+
+### Step 4: Verify Authentication
+```bash
+node ./dist/index.js auth status
+```
+
+### Step 5: Test Messages (Read-Only)
+```bash
+# List recent conversations
+node ./dist/index.js messages list --limit 5
+
+# Read a specific thread
+node ./dist/index.js messages show --thread <THREAD_ID>
+```
+
+### Step 6: Test Reply (With Dry Run)
+```bash
+# Dry run - simulates sending without actually sending
+node ./dist/index.js reply send --thread <THREAD_ID> --message "Test message" --dry-run
+```
+
+### Step 7: Test Connection Request (With Dry Run)
+```bash
+# Dry run connection request
+node ./dist/index.js connect send https://www.linkedin.com/in/some-profile/ --note "Hi, I'd like to connect" --dry-run
+```
+
+---
+
+## 🔐 Security Notes
+
+1. **Passwords are NEVER stored** - Only session cookies are saved
+2. **Encrypted storage** - Sessions use AES-256-GCM encryption
+3. **Machine-bound** - Sessions can't be copied to other machines
+4. **Audit logging** - All actions are logged to `~/.linkedin-cli/audit.log`
+
+---
+
+## 🚨 Safety Checklist
+
+Before running any command that modifies data:
+- [ ] Use `--dry-run` flag first
+- [ ] Review the action in the output
+- [ ] Check audit log: `cat ~/.linkedin-cli/audit.log`
+- [ ] Start with `--limit 1` for list commands
+
+---
+
+## 📊 Test Checklist
+
+Let's test together:
+
+### Phase 1: Basic Tests (No Credentials Needed)
+- [ ] CLI help works
+- [ ] Config can be read
+- [ ] All command groups show help
+
+### Phase 2: Authentication (Requires Your Input)
+- [ ] Browser opens
+- [ ] Can login to LinkedIn
+- [ ] Session is saved
+- [ ] Status shows logged in
+
+### Phase 3: Read Operations (Safe)
+- [ ] Can list messages
+- [ ] Can read conversation threads
+- [ ] Data displays correctly
+
+### Phase 4: Write Operations (Use Dry-Run First!)
+- [ ] Dry-run reply works
+- [ ] Dry-run connection works
+- [ ] Audit log captures actions
+
+---
+
+## 🔍 Troubleshooting
+
+### Issue: "Not logged in"
+**Solution:** Run `node ./dist/index.js auth login` first
+
+### Issue: Browser doesn't open
+**Solution:** Check Playwright installation:
+```bash
+npx playwright install chromium
+```
+
+### Issue: Session expires quickly
+**Solution:** LinkedIn sessions expire after ~24 hours. Just run auth login again.
+
+### Issue: Rate limiting
+**Solution:** Increase rate limit delay:
+```bash
+node ./dist/index.js config --set rateLimit=10000
+```
+
+---
+
+## 📞 Next Steps
+
+Ready to test? Let's start with **Phase 1** (no credentials needed), then move to **Phase 2** when you're ready to login!
+
+**Commands to run now:**
+```bash
+cd /Users/thaddeus/projects/linkedin-automation/.worktrees/linkedin-automation-cli
+node ./dist/index.js --help
+node ./dist/index.js auth --help
+node ./dist/index.js config --get
+```

package/cmd/linkedin/main.go

@@ -0,0 +1,9 @@
+package main
+
+import (
+	"github.com/thaddeus-git/linkedin-cli/internal/cmd"
+)
+
+func main() {
+	cmd.Execute()
+}