job-scout ·

TypeScript-first job scraping library with stable support for LinkedIn, Indeed, Bayt, and Naukri, plus experimental support for ZipRecruiter, Glassdoor, Google Jobs, and BDJobs.

Install

npm install job-scout

Node >=20 is required.

Quick Start

import { scoutJobs } from 'job-scout'

const jobs = await scoutJobs(
	{
		sites: ['indeed', 'linkedin', 'google'],
		query: 'software engineer',
		location: 'Ambon, Indonesia',
		pagination: { limitPerSite: 20 },
		filters: { postedWithinHours: 72 },
		google: {
			query: 'software engineer jobs near Ambon, Indonesia since yesterday',
		},
		indeed: { country: 'indonesia' },
		enrichment: { enabled: true, mode: 'low' },
		linkedin: {
			fetchDescription: true,
			enrichment: {
				fields: { emails: true, skills: true },
				exposeMeta: true,
			},
		},
	},
	{
		transport: {
			timeoutMs: 20_000,
		},
		experimental: {
			experimentalSites: {
				google: true,
			},
		},
		logging: {
			level: 'warn',
		},
	},
)

console.log(jobs.length)
console.log(jobs[0])

Client API

import { createClient } from 'job-scout'

const client = createClient({
	transport: { timeoutMs: 20_000 },
	logging: { level: 'warn' },
})

const jobs = await client.scoutJobs({
	sites: ['indeed'],
	query: 'backend engineer',
	location: 'Austin, TX',
	indeed: { country: 'usa' },
})

Public API

• createClient(config?: JobScoutConfig): JobScoutClient
• scoutJobs(request: JobSearchRequest, config?: JobScoutConfig): Promise<Job[]>
• scoutJobRows(request: JobSearchRequest, config?: JobScoutConfig): Promise<JobRow[]>
• toJobRows(jobs: Job[]): JobRow[]

Request Model

JobSearchRequest supports:

• sites: JobSite[] (required, non-empty)
  • Stable by default: indeed | linkedin | bayt | naukri
  • Experimental (opt-in required): zipRecruiter | glassdoor | google | bdjobs
• query?: string
• location?: string
• pagination?: { limitPerSite?: number; offset?: number }
• filters?: { distanceMiles?: number; remote?: boolean; easyApply?: boolean; employmentType?: ...; postedWithinHours?: number }
• enrichment?: EnrichmentConfig
• linkedin?: { fetchDescription?: boolean; companyIds?: number[]; enrichment?: EnrichmentConfig }
• indeed?: { country?: string }
• google?: { query?: string }

EnrichmentConfig supports:

• enabled?: boolean (default false)
• mode?: 'off' | 'low' | 'medium' | 'high'
• budget?: { maxExtraRequestsPerJob?: number; maxPagesPerDomain?: number; requestTimeoutMs?: number }
• sources?: { jobDetailPage?: boolean; externalApplyPage?: boolean; companyPages?: boolean }
• fields?: { emails?: boolean; skills?: boolean; seniority?: boolean; companyWebsite?: boolean; workMode?: boolean; companySize?: boolean }
• exposeMeta?: boolean (default false, adds job.enrichmentMeta)

Constraint rules are enforced at compile time (TypeScript) and runtime:

• Experimental sites must be explicitly enabled with config.experimental.experimentalSites.<site> = true.
• If sites includes google, google.query is required.
• For Indeed, use only one filter group at a time:
  • filters.postedWithinHours
  • filters.easyApply
  • filters.employmentType/filters.remote
• For LinkedIn, filters.postedWithinHours and filters.easyApply cannot both be enabled.

Configuration

JobScoutConfig:

• transport: proxies, user agent, CA cert path, timeout
• performance: global/site concurrency, retry policy, adaptive concurrency
• experimental: { experimentalSites: Record<Site, boolean> } (partial overrides allowed; missing keys default to false)
• output: description format, salary annualization, salary fallback behavior
• logging: error | warn | info | debug

Testing

Unit tests:

bun run test

Live integration tests:

JOBSCOUT_TEST_PROXIES="host1:port1,host2:port2" \
bun run test:integration:live

Full suite:

bun run test:all

Release

This package is published through GitHub Actions using npm trusted publishing (OIDC).

Publish a new version

1. Update the version in package.json.
2. Commit and push the version change.
3. Create and push a matching tag:

git tag v<package-version>
git push origin v<package-version>

The publish workflow verifies that v<package-version> exactly matches package.json and then runs:

• bun run typecheck
• bun run test
• bun run build
• npm publish --provenance --access public