feat: add Adzuna extractor with orchestrator integration (#177)

* feat(settings): add adzuna source fields and country compatibility

* feat(discovery): integrate adzuna extractor into pipeline

* feat(client): wire adzuna in source selection and run budgeting

* docs(extractors): add adzuna guide and configuration notes

* chore(workspaces): register adzuna extractor in lockfile

* fix(adzuna): run extractor via npm script instead of npx

* fix(adzuna): execute extractor via node+tsx without shell

* fix(adzuna): prefer npm run start without shell, fallback to tsx

* fix(docker): include adzuna extractor workspace in image

* chore(adzuna): reuse shared type-conversion utilities

* type-check adzuna

* formatting

* deeedooop

* better instructions

docs-site/docs/extractors/adzuna.md

@@ -0,0 +1,58 @@
+---
+id: adzuna
+title: Adzuna Extractor
+description: API-based Adzuna extraction with orchestrator ingestion and progress updates.
+sidebar_position: 6
+---
+
+## What it is
+
+Adzuna is an API-backed extractor implemented in two lean pieces:
+
+1. `extractors/adzuna/src/main.ts` fetches paginated Adzuna search results and writes `jobs.json`.
+2. `orchestrator/src/server/services/adzuna.ts` runs the extractor, parses progress lines, and maps rows into `CreateJobInput`.
+
+It de-duplicates in the existing repository path using `sourceJobId` fallback to `jobUrl`.
+
+## Why it exists
+
+Adzuna provides stable API discovery for countries that are not covered by UK-only sources. It adds a lower-maintenance source without introducing new API routes or UI sections.
+
+## How to use it
+
+1. Create an Adzuna developer account.
+2. Open [Adzuna Access Details](https://developer.adzuna.com/admin/access_details).
+3. Copy your **App ID** and **App Key**.
+4. In Job Ops, open **Settings** and paste them into `Adzuna App ID` and `Adzuna App Key` under **Environment & Accounts**.
+5. In **Pipeline Run** (Automatic tab), select a compatible country and enable **Adzuna** in Sources.
+6. Start the run; Adzuna progress appears in the existing crawl progress stream.
+
+Default controls:
+
+- `ADZUNA_APP_ID`
+- `ADZUNA_APP_KEY`
+- `ADZUNA_MAX_JOBS_PER_TERM` (default `50`)
+
+Supported countries in this integration:
+
+- United Kingdom, United States, Austria, Australia, Belgium, Brazil, Canada, Switzerland, Germany, Spain, France, India, Italy, Mexico, Netherlands, New Zealand, Poland, Singapore, South Africa.
+
+## Common problems
+
+### Adzuna is disabled in source selection
+
+- `Adzuna App ID` and `Adzuna App Key` are missing from Settings (or env).
+
+### Adzuna is skipped for my selected country
+
+- The selected country is not in the supported list above.
+
+### Adzuna fails with authorization errors
+
+- Verify `ADZUNA_APP_ID` and `ADZUNA_APP_KEY` are valid and active in your Adzuna account.
+
+## Related pages
+
+- [Extractors Overview](/docs/next/extractors/overview)
+- [Pipeline Run](/docs/next/features/pipeline-run)
+- [Settings](/docs/next/features/settings)

docs-site/docs/extractors/overview.md

@@ -13,12 +13,14 @@ This page helps you choose the right extractor for your run, understand key cons
 | --- | --- | --- | --- | --- |
 | [Gradcracker](/docs/next/extractors/gradcracker) | UK graduate roles from Gradcracker | Crawling stability depends on page structure and anti-bot behavior; tuned for low concurrency | `GRADCRACKER_SEARCH_TERMS`, `GRADCRACKER_MAX_JOBS_PER_TERM`, `JOBOPS_SKIP_APPLY_FOR_EXISTING` | Scrapes listing metadata, then detail pages and apply URL resolution |
 | [JobSpy](/docs/next/extractors/jobspy) | Multi-source discovery (Indeed, LinkedIn, Glassdoor) | Requires Python wrapper execution per term; source availability and quality vary by site/location | `JOBSPY_SITES`, `JOBSPY_SEARCH_TERMS`, `JOBSPY_RESULTS_WANTED`, `JOBSPY_HOURS_OLD`, `JOBSPY_LINKEDIN_FETCH_DESCRIPTION` | Produces JSON per term, then orchestrator normalizes and de-duplicates by `jobUrl` |
+| [Adzuna](/docs/next/extractors/adzuna) | API-based multi-country discovery with low scraping overhead | Requires valid App ID/App Key; country must be in Adzuna-supported list | `ADZUNA_APP_ID`, `ADZUNA_APP_KEY`, `ADZUNA_MAX_JOBS_PER_TERM` | API pagination to dataset output; orchestrator maps progress and de-duplicates by `sourceJobId`/`jobUrl` |
 | [UKVisaJobs](/docs/next/extractors/ukvisajobs) | UK visa sponsorship-focused roles | Requires authenticated session and periodic token/cookie refresh | `UKVISAJOBS_EMAIL`, `UKVISAJOBS_PASSWORD`, `UKVISAJOBS_MAX_JOBS`, `UKVISAJOBS_SEARCH_KEYWORD` | API pagination + dataset output; orchestrator de-dupes and may fetch missing descriptions |
 | [Manual Import](/docs/next/extractors/manual) | One-off jobs not covered by scrapers | Inference quality depends on model/provider and input quality; some URLs cannot be fetched reliably | App/API endpoints (`/api/manual-jobs/infer`, `/api/manual-jobs/import`) | Accepts text/HTML/URL, runs inference, then saves and scores job after review |
 
 ## Which extractor should I use?
 
 - Use **JobSpy** for broad first-pass sourcing across common boards.
+- Use **Adzuna** when you want API-first discovery in supported non-UK markets.
 - Use **Gradcracker** when targeting graduate pipelines in the UK.
 - Use **UKVisaJobs** for sponsorship-specific UK searches.
 - Use **Manual Import** when you already have a specific posting and need direct import.
@@ -29,5 +31,6 @@ Many runs combine sources: broad discovery first, then manual import for high-pr
 
 - [Gradcracker](/docs/next/extractors/gradcracker)
 - [JobSpy](/docs/next/extractors/jobspy)
+- [Adzuna](/docs/next/extractors/adzuna)
 - [UKVisaJobs](/docs/next/extractors/ukvisajobs)
 - [Manual Import](/docs/next/extractors/manual)