Metadata-Version: 2.4
Name: jobhunt-linkedin-helper
Version: 0.2.0
Summary: Standalone local fetch helper for hosted JobHunt — handles LinkedIn, Bayt, Indeed, and Glassdoor from your own IP
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: python-jobspy>=1.1.82
Description-Content-Type: text/markdown

# JobHunt Local Fetch Helper

`jobhunt-linkedin-helper` is the standalone local companion for hosted JobHunt deployments.

It keeps LinkedIn, Bayt, Indeed, and Glassdoor fetching on the user's own machine instead of the shared server IP, which makes the hosted product safer and more reliable.

## What it does

- pairs with your hosted JobHunt server using a short-lived code
- stores only a revocable device token on disk
- starts the bundled LinkedIn scraper locally when needed
- runs Bayt / Indeed / Glassdoor fetches locally via JobSpy
- polls the server for local fetch tasks
- returns raw jobs back to JobHunt for normal scoring and deduping

## Install

**For end users (hosted JobHunt)**

1. Download the `.whl` from your JobHunt admin or the project releases page.
2. Install it (Python 3.11+ required. Node.js 20+ is needed for LinkedIn support):
   ```bash
   uv tool install jobhunt-linkedin-helper.whl
   # or: pip install jobhunt-linkedin-helper.whl
   ```
3. Run it with your pairing code (see [Run](#run) below).

The CLI bootstraps the bundled LinkedIn scraper automatically on first launch when LinkedIn support is needed — no separate `node server.js` step needed.

**For local development (from this repo)**

```bash
uv tool install ./linkedin-helper
```

**Building a distributable wheel**

```bash
cd linkedin-helper
./build.sh
# outputs dist/jobhunt_linkedin_helper-*.whl
```

Upload the wheel wherever you host downloads and set `VITE_LINKEDIN_HELPER_DOWNLOAD_URL` in your frontend `.env`.

## Run

First pairing:

```bash
jobhunt-linkedin-helper \
  --server-url https://your-jobhunt-domain.com \
  --pairing-code JHLI-XXXX-XXXX
```

After pairing, the helper remembers its device token and future runs only need:

```bash
jobhunt-linkedin-helper --server-url https://your-jobhunt-domain.com
```

## Notes

- The helper starts its own bundled LinkedIn scraper automatically. Users should not need a separate `node server.js` command.
- Bayt / Indeed / Glassdoor use JobSpy inside the same helper package.
- On first launch, the helper bootstraps its LinkedIn scraper dependencies with `npm install` if needed.
- If you only use Bayt / Indeed / Glassdoor, Python is enough. LinkedIn support still expects `node` and `npm` to be available on the local machine.

## Options

| Flag | Default | Description |
|---|---|---|
| `--server-url` | `http://127.0.0.1:8000` | Hosted JobHunt URL |
| `--pairing-code` | — | One-time code from the JobHunt UI |
| `--device-name` | hostname | Friendly device label shown in JobHunt |
| `--token-file` | `~/.jobhunt/linkedin-local-agent.json` | Where the helper stores its device token |
| `--poll-seconds` | `8` | How often to poll when idle |
| `--once` | off | Claim one task and exit |
| `--scraper-port` | `3001` | Port used by the helper-managed local scraper |
| `--no-managed-scraper` | off | Skip starting the bundled scraper and use `--scraper-url` instead |
| `--scraper-url` | `http://127.0.0.1:3001` | External scraper URL when `--no-managed-scraper` is used |
| `--skip-scraper-bootstrap` | off | Skip automatic `npm install` for advanced/dev usage |
