jobspy-js 1.5.0 → 1.7.0

package/AGENTS.md

@@ -0,0 +1,93 @@
+# AGENTS.md — AI Agent Guidelines
+
+This file instructs AI coding agents (GitHub Copilot, Cursor, Claude, etc.) on how to contribute to this project correctly.
+
+---
+
+## Mandatory: Update README and CHANGELOG on Every Meaningful Change
+
+Whenever you make a change that affects user-visible behaviour — a new feature, a bug fix, a breaking change, a new CLI flag, a new API parameter, or a change to an existing interface — you **must** update both files as part of the same task:
+
+1. **[CHANGELOG.md](CHANGELOG.md)** — record the change under `[Unreleased]`.
+2. **[README.md](README.md)** — update any affected section (feature list, tables, examples, structure diagram).
+
+Do not skip these updates. Do not leave them as a separate follow-up task.
+
+---
+
+## CHANGELOG Rules
+
+Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) conventions:
+
+- All unreleased work goes under `## [Unreleased]` at the top.
+- Use these subsection headers: `Added`, `Changed`, `Fixed`, `Removed`, `Security`, `Deprecated`.
+- Write entries from the **user's point of view** — describe what they can now do, not what lines changed.
+- When a version is released, rename `[Unreleased]` to `## [x.y.z] — YYYY-MM-DD` and add a new empty `[Unreleased]` block above it.
+- Update the comparison links at the bottom of the file whenever a new version is cut.
+
+### Entry format
+
+```markdown
+## [Unreleased]
+
+### Added
+- **Short feature name** — one-sentence description of what was added and why it is useful.
+
+### Fixed
+- Brief description of the bug and what was corrected.
+```
+
+---
+
+## README Rules
+
+The README is the primary user-facing documentation. Keep it accurate and complete:
+
+| Section to update | When |
+|---|---|
+| **Features** bullet list | new capability added |
+| **SDK — Parameters table** (`scrapeJobs` params) | new/changed param |
+| **Authentication / Credentials** section | credential-related changes |
+| **CLI — Quick Start** examples | new common use-case |
+| **CLI — All CLI Options** table | new/changed CLI flag |
+| **Config File — Profile Options** table | new/changed profile key |
+| **Project Structure** tree | new source file added |
+| **Supported Sites** table | new scraper |
+
+Do not add a new CLI flag or SDK parameter without adding it to the corresponding table in README.md.
+
+---
+
+## Code Change Guidelines
+
+### Types first
+New user-facing features start in `src/types.ts`. Add interfaces and fields there before implementing them elsewhere, so TypeScript catches all callsites.
+
+### Credential / auth changes
+- Load credentials via `src/credentials.ts` — do not read `process.env` directly in scrapers.
+- Credentials should only be *used* when `useCreds === true`. Never auto-login without explicit opt-in.
+- Always test anonymous scraping first; authenticated fallback is a last resort.
+
+### Scraper changes
+- The constructor signature for scrapers is `{ proxies?, credentials?, useCreds? }` — maintain this shape.
+- `SCRAPER_MAP` in `src/scraper.ts` must reflect the current constructor signature type.
+- New scrapers must implement `scrape(input)` and should implement `fetchJob(id, format)` if single-job fetching is possible.
+
+### CLI changes
+- New options must be added in three places: the `program.option(...)` chain, the `o = { ... }` merge object, and the `scrapeJobs(...)` call.
+- Profile config keys use `snake_case`; CLI flags use `--kebab-case`; the merge object uses `camelCase`.
+
+### Testing
+- Run `pnpm build` after changes to confirm TypeScript compiles cleanly.
+- Add / update tests in `tests/` for any logic in `src/state.ts`, `src/credentials.ts`, or `src/utils.ts`.
+
+---
+
+## Release Checklist
+
+When cutting a new version:
+
+1. Move `[Unreleased]` entries in `CHANGELOG.md` to a new dated version block.
+2. Bump `version` in `package.json`.
+3. Update CHANGELOG comparison links at the bottom.
+4. Commit with message: `chore: release vX.Y.Z`.

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Added
+- **Provider credentials** — per-provider username/password support for all scrapers via env vars (`LINKEDIN_USERNAME` / `LINKEDIN_PASSWORD`, `INDEED_USERNAME` / `INDEED_PASSWORD`, `GLASSDOOR_USERNAME` / `GLASSDOOR_PASSWORD`, `ZIPRECRUITER_*`, `BAYT_*`, `NAUKRI_*`, `BDJOBS_*`), CLI flags (`--linkedin-username`, `--linkedin-password`, …), or `credentials` object in `ScrapeJobsParams`.
+- **`--creds` CLI flag** — opt-in authenticated scraping fallback (also `JOBSPY_CREDS=1` env var). Credentials are loaded but only *used* when this flag is set.
+- **LinkedIn login fallback** — on 429 throttle or auth-wall redirect, the LinkedIn scraper automatically attempts a form-based session login and retries the blocked request when `--creds` is active.
+- `src/credentials.ts` — new module that merges credentials from three priority layers: env vars → per-parameter fields → explicit `credentials` object.
+- `ProviderCredentials` and `ProviderCreds` types exported from `types.ts`.
+- `use_creds`, `credentials`, and all `*_username`/`*_password` fields added to `ScrapeJobsParams` and `ScraperInput`.
+- `--init` profiles now include commented-out credential examples.
+
+---
+
+## [1.6.0] — 2026-03-02
+
+### Added
+- **`fetchJobDetails(site, id, options)`** — fetch full job details by provider-specific ID for *any* supported site (`indeed`, `linkedin`, `glassdoor`, `zip_recruiter`, `bayt`, `naukri`, `bdjobs`). Equivalent to `fetchLinkedInJob` but provider-agnostic.
+- **`--id <jobId>` CLI flag** — fetch full job details from any provider by ID (requires `-s/--site`).
+- Abstract `fetchJob(id, format)` method on the base `Scraper` class; subclasses override per provider.
+
+### Changed
+- LinkedIn scraper now distinguishes between a true auth-wall redirect (no job content) and a page that merely references the signup URL — prevents false-positive empty results.
+- LinkedIn auth-wall check uses `show-more-less-html__markup` presence as a page-content signal.
+
+---
+
+## [1.5.0] — 2026-02-27
+
+### Added
+- **`fetchLinkedInJob(idOrUrl, options)`** — fetch full details for a single LinkedIn job by numeric ID or full URL. Returns description, job level, job type, job function, company industry, company logo, and direct application URL.
+- **`--describe <jobId>` CLI flag** — fetch and pretty-print LinkedIn job details from the command line.
+- **Unified `jobspy.json` config file** — single file stores both search profiles (`config.profiles`) and dedup state (`state.profiles`). Replaces the previous separate state file.
+- **`--init` CLI flag** — generates a `jobspy.json` with two sample profiles (`frontend`, `backend`).
+- **`--list-profiles` CLI flag** — lists all profiles with last-run timestamp, sites, and search term.
+- **`--profile <name>` CLI flag** — run a named search profile from `jobspy.json`; CLI flags override profile values.
+- **`--all` CLI flag** — skip dedup filtering for one run while still updating state.
+- **Dedup / incremental runs** — `scrapeJobs()` with a profile name automatically tracks seen URLs and date watermarks per provider. Only new jobs are returned on subsequent runs.
+- `profile` and `skip_dedup` fields in `ScrapeJobsParams`.
+- `ScrapeJobsResult` now includes `totalScraped`, `newCount`, and `profile` metadata.
+- `src/state.ts` — state file I/O, `filterNewJobs()`, `updateProviderState()`, `mergeParams()`.
+
+### Changed
+- CLI option merging: profile config values are used as defaults; CLI flags always take precedence.
+
+---
+
+## [1.3.0] — 2026-02-21
+
+### Changed
+- **Dual ESM/CJS output** — Vite build now emits both `.js` (ESM) and `.cjs` (CommonJS) bundles for broad compatibility with Node.js consumers.
+- Updated `package.json` exports map with `import`/`require` conditions.
+
+---
+
+## [1.2.0] — 2026-02-21
+
+### Added
+- **`SDK.md`** — comprehensive SDK reference covering all parameters, types, enums, output fields, proxy configuration, country support, and advanced examples.
+
+---
+
+## [1.1.0] — 2026-02-18
+
+### Added
+- **Google Careers scraper** (`google_careers`) — scrapes jobs posted at Google the company via plain HTTP; parses `AF_initDataCallback` JSON payload.
+- **Playwright support for Google Jobs** (`google`) — headless Chromium execution via `@playwright/test` to handle JavaScript-rendered job listings.
+
+### Fixed
+- ZipRecruiter scraper — corrected JSON extraction and pagination.
+- BDJobs scraper — fixed request parameters and result parsing.
+
+---
+
+## [1.0.1] — 2026-02-18
+
+### Changed
+- Refactored source structure for improved readability and maintainability (module split, consistent naming).
+- Added `release` script to `package.json`.
+
+---
+
+## [1.0.0] — 2026-02-17
+
+### Added
+- Initial TypeScript port of [JobSpy](https://github.com/speedyapply/JobSpy) (Python).
+- **9 scrapers**: LinkedIn (HTML), Indeed (GraphQL), Glassdoor (GraphQL), Google Jobs (Playwright), Google Careers (HTTP), ZipRecruiter, Bayt, Naukri (REST), BDJobs (REST).
+- **Three interfaces**: SDK (`scrapeJobs()`), CLI (`jobspy`), MCP server.
+- [wreq-js](https://github.com/nicehash/wreq-js) browser TLS fingerprint emulation (JA3/JA4, Chrome/Firefox/Safari).
+- Concurrent multi-site scraping via `Promise.allSettled`.
+- Proxy rotation support.
+- Salary extraction from job descriptions.
+- 60+ country support for Indeed and Glassdoor regional domains.
+- `JobPost`, `ScraperInput`, `JobResponse`, and all supporting types.
+
+[Unreleased]: https://github.com/borgius/jobspy-js/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/borgius/jobspy-js/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/borgius/jobspy-js/compare/v1.3.0...v1.5.0
+[1.3.0]: https://github.com/borgius/jobspy-js/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/borgius/jobspy-js/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/borgius/jobspy-js/compare/v1.0.1...v1.1.0
+[1.0.1]: https://github.com/borgius/jobspy-js/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/borgius/jobspy-js/releases/tag/v1.0.0

package/README.md

@@ -15,6 +15,7 @@ Uses [wreq-js](https://github.com/nicehash/wreq-js) for browser TLS fingerprint
 - **Concurrent scraping** — all sites scraped in parallel
 - **Salary extraction** — parses compensation from descriptions when not provided directly
 - **60+ countries** — Indeed/Glassdoor regional domain support
+- **Credential fallback** — optional per-provider login (env vars or CLI flags) when anonymous scraping is blocked
 
 ## Supported Sites
 
@@ -46,7 +47,7 @@ npm install jobspy-js
 > **Full SDK reference:** See [SDK.md](https://github.com/borgius/jobspy-js/blob/master/SDK.md) for complete documentation — all parameters, types, enums, output fields, proxy configuration, country support, and advanced examples.
 
 ```ts
-import { scrapeJobs, fetchLinkedInJob } from "jobspy-js";
+import { scrapeJobs, fetchLinkedInJob, fetchJobDetails } from "jobspy-js";
 
 // Scrape multiple job boards
 const result = await scrapeJobs({
@@ -64,6 +65,10 @@ for (const job of result.jobs) {
 // Fetch details for a single LinkedIn job
 const details = await fetchLinkedInJob("4127292817");
 console.log(details.description);
+
+// Fetch full job details by ID for any provider
+const job = await fetchJobDetails("indeed", "fdde406379455a1e");
+console.log(job.description);
 ```
 
 ### Parameters
@@ -85,6 +90,14 @@ console.log(details.description);
 | `enforce_annual_salary` | `boolean` | `false` | Convert all salaries to annual |
 | `profile` | `string` | — | Named profile for dedup tracking |
 | `skip_dedup` | `boolean` | `false` | Skip dedup filtering (still updates state) |
+| `use_creds` | `boolean` | `false` | Enable credential fallback when anonymous scraping is blocked (also: `JOBSPY_CREDS=1`) |
+| `credentials` | `ProviderCredentials` | — | Explicit credentials object (see [Authentication](#authentication--credentials)) |
+| `linkedin_username` | `string` | — | LinkedIn username/email (also: `LINKEDIN_USERNAME`) |
+| `linkedin_password` | `string` | — | LinkedIn password (also: `LINKEDIN_PASSWORD`) |
+| `indeed_username` | `string` | — | Indeed username/email (also: `INDEED_USERNAME`) |
+| `indeed_password` | `string` | — | Indeed password (also: `INDEED_PASSWORD`) |
+| `glassdoor_username` | `string` | — | Glassdoor username/email (also: `GLASSDOOR_USERNAME`) |
+| `glassdoor_password` | `string` | — | Glassdoor password (also: `GLASSDOOR_PASSWORD`) |
 
 ### fetchLinkedInJob()
 
@@ -107,7 +120,103 @@ Options: `{ format?: "markdown"|"html"|"plain", proxies?: string|string[] }`
 
 > **Full reference:** See [SDK.md](https://github.com/borgius/jobspy-js/blob/master/SDK.md#fetchlinkedinjob) for all fields and examples.
 
-## CLI
+### fetchJobDetails()
+
+Fetch full details for a single job by ID on **any** provider:
+
+```ts
+import { fetchJobDetails } from "jobspy-js";
+
+// Works with any supported site
+const job = await fetchJobDetails("indeed", "fdde406379455a1e");
+// also: fetchJobDetails("linkedin", "4127292817")
+// also: fetchJobDetails("glassdoor", "123456789")
+// also: fetchJobDetails("zip_recruiter", "some-listing-key")
+// also: fetchJobDetails("bayt", "/en/job-title-1234567")
+// also: fetchJobDetails("naukri", "123456789")
+// also: fetchJobDetails("bdjobs", "123456")
+
+console.log(job.description);  // full job description
+console.log(job.title);        // job title
+console.log(job.company);      // company name
+```
+
+Options: `{ format?: "markdown"|"html"|"plain", proxies?: string|string[], country?: string }`
+
+> **Full reference:** See [SDK.md](https://github.com/borgius/jobspy-js/blob/master/SDK.md#fetchjobdetails) for all fields and examples.
+## Authentication / Credentials
+
+All providers support optional authenticated scraping as a fallback for when anonymous access is blocked (e.g. LinkedIn 429s or auth-wall redirects). Credentials are **never used unless explicitly enabled**.
+
+### Enable credential fallback
+
+```bash
+# Via env var
+JOBSPY_CREDS=1 jobspy -s linkedin -q "engineer"
+
+# Via CLI flag
+jobspy -s linkedin -q "engineer" --creds
+```
+
+Or in the SDK:
+
+```ts
+const result = await scrapeJobs({
+  site_name: ["linkedin"],
+  search_term: "engineer",
+  use_creds: true,
+  linkedin_username: process.env.LINKEDIN_USERNAME,
+  linkedin_password: process.env.LINKEDIN_PASSWORD,
+});
+```
+
+### Setting credentials
+
+Credentials are resolved in this priority order (highest wins):
+
+1. **Explicit `credentials` object** in `ScrapeJobsParams`
+2. **Per-field params** (`linkedin_username`, `linkedin_password`, …)
+3. **Environment variables**
+
+#### Environment variables
+
+| Provider | Username env var | Password env var |
+|----------|-----------------|------------------|
+| LinkedIn | `LINKEDIN_USERNAME` | `LINKEDIN_PASSWORD` |
+| Indeed | `INDEED_USERNAME` | `INDEED_PASSWORD` |
+| Glassdoor | `GLASSDOOR_USERNAME` | `GLASSDOOR_PASSWORD` |
+| ZipRecruiter | `ZIPRECRUITER_USERNAME` | `ZIPRECRUITER_PASSWORD` |
+| Bayt | `BAYT_USERNAME` | `BAYT_PASSWORD` |
+| Naukri | `NAUKRI_USERNAME` | `NAUKRI_PASSWORD` |
+| BDJobs | `BDJOBS_USERNAME` | `BDJOBS_PASSWORD` |
+
+#### CLI flags
+
+```bash
+jobspy -s linkedin -q "engineer" --creds \
+  --linkedin-username me@email.com \
+  --linkedin-password secret
+```
+
+#### `jobspy.json` profile
+
+```json
+{
+  "config": {
+    "profiles": {
+      "frontend": {
+        "site": ["linkedin", "indeed"],
+        "search_term": "react developer",
+        "creds": true,
+        "linkedin_username": "me@email.com",
+        "linkedin_password": "secret"
+      }
+    }
+  }
+}
+```
+
+> **Security note:** Prefer environment variables over storing passwords in `jobspy.json`. The state section of that file is committed by some users.
 
 ### Quick Start
 
@@ -127,6 +236,14 @@ jobspy -s google_careers -q "software engineer" -l "USA" -n 10
 # Fetch full details for a single LinkedIn job
 jobspy --describe 4127292817
 jobspy --describe https://www.linkedin.com/jobs/view/4127292817
+
+# Fetch full job details by ID for any provider
+jobspy -s indeed --id fdde406379455a1e
+jobspy -s glassdoor --id 123456789
+
+# Use credential fallback (anonymous scraping blocked)
+JOBSPY_CREDS=1 LINKEDIN_USERNAME=me@email.com LINKEDIN_PASSWORD=secret jobspy -s linkedin -q "engineer"
+jobspy -s linkedin -q "engineer" --creds --linkedin-username me@email.com --linkedin-password secret
 ```
 
 ### All CLI Options
@@ -147,6 +264,7 @@ jobspy --describe https://www.linkedin.com/jobs/view/4127292817
 | `-p, --proxies <proxies...>` | | — | Proxy servers |
 | `--format <format>` | | `markdown` | Description format: `markdown`, `html`, `plain` |
 | `--linkedin-fetch-description` | | `false` | Fetch full LinkedIn descriptions |
+| `--indeed-fetch-description` | | `false` | Fetch full Indeed job pages/Direct-link descriptions |
 | `--linkedin-company-ids <ids...>` | | — | Filter by LinkedIn company IDs |
 | `--offset <offset>` | | `0` | Pagination offset |
 | `--hours-old <hours>` | | — | Only jobs posted within N hours |
@@ -158,6 +276,21 @@ jobspy --describe https://www.linkedin.com/jobs/view/4127292817
 | `--list-profiles` | | — | List all saved profiles |
 | `--init` | | — | Generate a `jobspy.json` with sample profiles |
 | `--describe <jobId>` | | — | Fetch full LinkedIn job details by ID or URL |
+| `--id <jobId>` | | — | Fetch full job details by ID (requires `-s/--site`) |
+| **Credentials** | | | |
+| `--creds` | | `false` | Enable credential fallback when anonymous scraping is blocked (also: `JOBSPY_CREDS=1`) |
+| `--linkedin-username <user>` | | — | LinkedIn username/email (also: `LINKEDIN_USERNAME`) |
+| `--linkedin-password <pass>` | | — | LinkedIn password (also: `LINKEDIN_PASSWORD`) |
+| `--indeed-username <user>` | | — | Indeed username/email (also: `INDEED_USERNAME`) |
+| `--indeed-password <pass>` | | — | Indeed password (also: `INDEED_PASSWORD`) |
+| `--glassdoor-username <user>` | | — | Glassdoor username/email (also: `GLASSDOOR_USERNAME`) |
+| `--glassdoor-password <pass>` | | — | Glassdoor password (also: `GLASSDOOR_PASSWORD`) |
+| `--ziprecruiter-username <user>` | | — | ZipRecruiter username/email (also: `ZIPRECRUITER_USERNAME`) |
+| `--ziprecruiter-password <pass>` | | — | ZipRecruiter password (also: `ZIPRECRUITER_PASSWORD`) |
+| `--bayt-username <user>` | | — | Bayt username/email (also: `BAYT_USERNAME`) |
+| `--bayt-password <pass>` | | — | Bayt password (also: `BAYT_PASSWORD`) |
+| `--naukri-username <user>` | | — | Naukri username/email (also: `NAUKRI_USERNAME`) |
+| `--naukri-password <pass>` | | — | Naukri password (also: `NAUKRI_PASSWORD`) |
 
 ## Config File (`jobspy.json`)
 
@@ -187,6 +320,7 @@ This creates a `jobspy.json` in the current directory with two sample profiles:
         "country": "usa",
         "format": "markdown",
         "linkedin_fetch_description": true,
+        "indeed_fetch_description": false,
         "hours_old": 72,
         "enforce_annual_salary": true,
         "verbose": 1,
@@ -202,6 +336,7 @@ This creates a `jobspy.json` in the current directory with two sample profiles:
         "job_type": "fulltime",
         "results": 50,
         "hours_old": 48,
+        "indeed_fetch_description": false,
         "output": "backend-jobs.json"
       }
     }
@@ -238,6 +373,13 @@ Each profile in `config.profiles` supports the following keys:
 | `enforce_annual_salary` | `boolean` | Normalize salaries to annual |
 | `verbose` | `number` | Log verbosity level |
 | `output` | `string` | Output file path |
+| `creds` | `boolean` | Enable credential fallback (also: `JOBSPY_CREDS=1`) |
+| `linkedin_username` | `string` | LinkedIn username/email (also: `LINKEDIN_USERNAME`) |
+| `linkedin_password` | `string` | LinkedIn password (also: `LINKEDIN_PASSWORD`) |
+| `indeed_username` | `string` | Indeed username/email (also: `INDEED_USERNAME`) |
+| `indeed_password` | `string` | Indeed password (also: `INDEED_PASSWORD`) |
+| `glassdoor_username` | `string` | Glassdoor username/email (also: `GLASSDOOR_USERNAME`) |
+| `glassdoor_password` | `string` | Glassdoor password (also: `GLASSDOOR_PASSWORD`) |
 
 ### Running Profiles
 
@@ -404,6 +546,7 @@ npm test
 src/
 ├── index.ts              # SDK entry point
 ├── scraper.ts            # Main scrapeJobs() orchestrator
+├── credentials.ts        # Credential loader (env → params → object merge)
 ├── state.ts              # Profile state, dedup logic, file I/O
 ├── types.ts              # All types, enums, country config
 ├── utils.ts              # Logger, proxy rotation, HTML helpers
@@ -412,7 +555,7 @@ src/
 └── scrapers/
     ├── base.ts           # Abstract Scraper base class
     ├── indeed/           # GraphQL API
-    ├── linkedin/         # HTML scraping
+    ├── linkedin/         # HTML scraping + optional login fallback
     ├── glassdoor/        # GraphQL API
     ├── google/           # Playwright headless Chrome
     ├── google-careers/   # Plain HTTP; AF_initDataCallback JSON parsing

package/SDK.md

@@ -11,6 +11,10 @@ Comprehensive SDK documentation for [jobspy-js](https://github.com/borgius/jobsp
 - [fetchLinkedInJob()](#fetchlinkedinjob)
   - [Parameters](#fetchlinkedinjob-parameters)
   - [Return Value](#fetchlinkedinjob-return-value)
+- [fetchJobDetails()](#fetchjobdetails)
+  - [Parameters](#fetchjobdetails-parameters)
+  - [Return Value](#fetchjobdetails-return-value)
+  - [Supported Sites](#fetchjobdetails-supported-sites)
 - [Types & Enums](#types--enums)
   - [Site](#site)
   - [JobType](#jobtype)
@@ -35,6 +39,7 @@ Comprehensive SDK documentation for [jobspy-js](https://github.com/borgius/jobsp
   - [Pagination with Offset](#pagination-with-offset)
   - [Recent Jobs Only](#recent-jobs-only)
   - [Fetch Single LinkedIn Job](#fetch-single-linkedin-job)
+  - [Fetch Job by ID (Any Provider)](#fetch-job-by-id-any-provider)
 - [Error Handling](#error-handling)
 - [Exports](#exports)
 
@@ -92,6 +97,7 @@ interface ScrapeJobsParams {
   proxies?:                     string | string[];
   description_format?:          string;
   linkedin_fetch_description?:  boolean;
+  indeed_fetch_description?:    boolean;
   linkedin_company_ids?:        number[];
   offset?:                      number;
   hours_old?:                   number;
@@ -115,6 +121,7 @@ interface ScrapeJobsParams {
 | `proxies` | `string \| string[]` | — | Proxy server(s) for rotating requests. See [Proxy Configuration](#proxy-configuration). |
 | `description_format` | `string` | `"markdown"` | Format for job descriptions: `"markdown"`, `"html"`, or `"plain"`. |
 | `linkedin_fetch_description` | `boolean` | `false` | Fetch full job descriptions from LinkedIn (requires an extra HTTP request per job — slower). |
+| `indeed_fetch_description` | `boolean` | `false` | Visit the Indeed job page or direct link to scrape the full description. |
 | `linkedin_company_ids` | `number[]` | — | Filter LinkedIn results to specific company IDs. |
 | `offset` | `number` | `0` | Skip the first N results (pagination offset). |
 | `hours_old` | `number` | — | Only return jobs posted within the last N hours. |
@@ -189,6 +196,73 @@ interface LinkedInJobDetails {
 
 ---
 
+## fetchJobDetails()
+
+Fetch full details for a single job by ID on **any** supported provider. This is a universal alternative to `fetchLinkedInJob()` that works across all scrapers.
+
+```ts
+import { fetchJobDetails } from "jobspy-js";
+
+const job = await fetchJobDetails("indeed", "fdde406379455a1e");
+console.log(job.title);        // job title
+console.log(job.company);      // company name
+console.log(job.description);  // full description
+```
+
+### fetchJobDetails Parameters
+
+```ts
+fetchJobDetails(
+  site: string,              // Site name (e.g. "indeed", "linkedin", "glassdoor")
+  jobId: string,             // Provider-specific job ID
+  options?: {
+    format?: string;              // "markdown" (default), "html", or "plain"
+    proxies?: string | string[];  // Proxy server(s)
+    country?: string;             // Country code (default: "usa")
+  },
+): Promise<FlatJobRecord | null>
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `site` | `string` | — | Site name: `"indeed"`, `"linkedin"`, `"glassdoor"`, `"zip_recruiter"`, `"bayt"`, `"naukri"`, `"bdjobs"` |
+| `jobId` | `string` | — | Provider-specific job ID (as returned in search results) |
+| `options.format` | `string` | `"markdown"` | Description format: `"markdown"`, `"html"`, or `"plain"` |
+| `options.proxies` | `string \| string[]` | — | Proxy server(s) for the request |
+| `options.country` | `string` | `"usa"` | Country for Indeed/Glassdoor |
+
+### fetchJobDetails Return Value
+
+Returns a `FlatJobRecord` (same shape as search results) or `null` if the job wasn't found. The record includes all available fields for the job:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Prefixed job ID (e.g. `"in-fdde406379455a1e"`) |
+| `site` | `string` | Site name |
+| `title` | `string` | Job title |
+| `company` | `string` | Company name |
+| `description` | `string` | Full job description |
+| `job_url` | `string` | Job listing URL |
+| `location` | `string` | Formatted location |
+| `date_posted` | `string` | When the job was posted |
+| ... | | All other standard `FlatJobRecord` fields |
+
+### fetchJobDetails Supported Sites
+
+| Site | Job ID Format | Notes |
+|------|--------------|-------|
+| `indeed` | Indeed job key (e.g. `"fdde406379455a1e"`) | Fetches full description from job page |
+| `linkedin` | LinkedIn job ID (e.g. `"4127292817"`) | Uses existing LinkedIn detail fetcher |
+| `glassdoor` | Glassdoor listing ID | Requires CSRF token initialization |
+| `zip_recruiter` | ZipRecruiter listing key | Parses full HTML description |
+| `bayt` | Bayt job path (e.g. `"/en/job-title-1234567"`) | Scrapes job detail page |
+| `naukri` | Naukri job ID | Uses REST API |
+| `bdjobs` | BDJobs job ID | Extracts from detail page |
+| `google` | — | Not supported (returns error) |
+| `google_careers` | — | Not supported (returns error) |
+
+---
+
 ## Types & Enums
 
 All types and enums are exported from the package root:
@@ -636,6 +710,28 @@ const job2 = await fetchLinkedInJob(
 );
 ```
 
+### Fetch Job by ID (Any Provider)
+
+```ts
+import { fetchJobDetails } from "jobspy-js";
+
+// Fetch an Indeed job by ID
+const job = await fetchJobDetails("indeed", "fdde406379455a1e");
+console.log(job.title);       // job title
+console.log(job.description); // full description
+
+// Fetch a Glassdoor job with HTML format
+const job2 = await fetchJobDetails("glassdoor", "123456789", {
+  format: "html",
+  country: "uk",
+});
+
+// Fetch a ZipRecruiter job via proxy
+const job3 = await fetchJobDetails("zip_recruiter", "listing-key", {
+  proxies: "user:pass@proxy.example.com:8080",
+});
+```
+
 ---
 
 ## Error Handling
@@ -675,7 +771,7 @@ Everything exported from `"jobspy-js"`:
 
 ```ts
 // Main functions
-export { scrapeJobs, fetchLinkedInJob } from "./scraper";
+export { scrapeJobs, fetchLinkedInJob, fetchJobDetails } from "./scraper";
 
 // Enums
 export { Site, JobType, CompensationInterval, DescriptionFormat, SalarySource } from "./types";