Skip to content
ContractSpec
Start here

Package manual · integrations

·Intelligence, research and applications

integration.job-sources

Named France, ATS, and job-board connectors for governed OSINT ingestion.

integrationsintegrationv2.0.5experimentalservernode
@lssm-tech/integration.job-sources
bun add @lssm-tech/integration.job-sources
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Governed connectors for La Bonne Alternance, French apprenticeship sites, Ashby, Flatchr, Greenhouse, iCIMS, Jobaffinity, Lever, Recruitee, SmartRecruiters, Taleez, Teamtailor, WeRecruit, Workable, Workday, and Indeed France.

The package exposes an executable capability matrix. supported means the deterministic connector path exists; live qualification remains separate. La Bonne Alternance commercial use and Indeed France are permission-blocked by default.

Direct-first acquisition routing

Connectors may resolve an immutable JobAcquisitionPlanV1 for each exact installation request. createRoutedJobSourceAcquisitionV1 always executes its priority-zero direct-fetch route first. It escalates only explicit retryable_transport or render_required failures to a later source-qualified connection. Rate limits, authentication, policy, budget, source restrictions, cancellation, unknown failures, and ambiguous effects stop routing. Provider rotation is therefore never an access-control or rate-limit bypass.

createWebAccessJobSourceRouteExecutorV1 binds those routes to the existing Bright Data, Browserbase, Massive, Firecrawl, Oxylabs, Reworkd, and Apify adapters. Reworkd requires an exact qualified scraping-group dataset profile. Apify runs one qualified Actor, polls the same run within fixed bounds, and reads its resulting dataset without replaying the Actor. Authority resolution must return the plan's exact policy and budget references before an adapter is called. Every attempt, provider-reported request/cost usage, and selected route receives a deterministic replay receipt. An indirect provider 404 or 410 can never become job-closure evidence; closure remains bound to a direct detail recheck. The Web Access bridge also requires an injected acquisition rate gate, and the exact source rate policy, installation revision, and opaque credential reference participate in the request digest.

InMemoryJobSourceAcquisitionRateGateV1 is the conservative reference for a single worker process. It keys spacing and concurrency by installation or egress profile exactly as the source policy requires, honors cancellation, and returns a terminal rate_limited classification rather than rotating providers. It is not a substitute for a shared durable gate when multiple worker replicas serve the same source or egress identity.

jobSourceCapabilityMatrixV1 is the canonical 17-source × 7-capability truth table and never promotes deterministic fixtures into live receipts. Documented API adapters, Lever cursor ingestion, generic structured-page parsing, tenant-specific browser flows, and permission-blocked sources are reported separately; a generic parser fixture does not qualify a source-specific connector.

renderJobSourceCapabilityMatrixMarkdownV1 feeds the repository-level generated job intelligence matrix; bun run osint:job-matrices:check prevents drift.

jobSourceLiveQualificationPlanV1 and verifyJobSourceLiveQualificationReceiptsV1 provide the separate exact-SHA live evidence plane. Partial receipt sets project passed, failed, and blocked cells without mutating deterministic truth or promoting permission-blocked sources. bun run live:lever exercises the public Lever installation through the hardened direct-fetch adapter and production connector. It requires an explicit live confirmation, complete scope, release SHA, policy authorization and expiry, site, and region. Public discovery, listing, detail, cursor, revalidation, and application discovery can pass; closure remains blocked until an observed live transition supplies real closure evidence. The command also requires the claimed release SHA to equal the current git rev-parse HEAD so a syntactically valid but unrelated digest cannot become qualification evidence.

bun run live:public-source exposes the same ceremony for any named connector: an exact source key and canonical installation URL select the existing connector, while the common runner derives discovery, listing, detail, incremental, revalidation, closure, and application receipts from the executable matrix. Missing credentials, cursors, permission, application URLs, or observed closure transitions stay explicit blockers. SmartRecruiters detail normalization accepts the vendor's live postingUrl and applyUrl shape as well as list-response ref links.

bun run live:public-batch consumes a strict, secret-free V1 manifest and produces one deduplicated receipt set and summary. The repository qualification manifest lives at docs/evidence/osint/job-source-public-live-manifest-v1.json. Unknown fields, duplicate sources, credential-bearing URLs, permission-blocked sources, or unpaired closure evidence are rejected before network execution. Every live command also requires a clean worktree in addition to exact Git HEAD equality.

An optional live closure probe requires both a bounded external listing ID and an immutable prior-publication evidence reference. It can pass only when the same source returns a current 404 or 410 with closure evidence. An absent prior reference, ambiguous transport outcome, still-open listing, or unrelated status cannot promote closure.

The Flatchr adapter follows the documented public /company/{slug}.json feed and preserves nested vacancy identifiers and application URLs. The Workable adapter uses the vendor-documented public account endpoint /api/accounts/{subdomain}?details=true. The documented Flatchr detail endpoint is used for direct revalidation and explicit 404/410 closure evidence. Flatchr cursor paths remain gated because the public feed exposes no qualified cursor or change token.

When Flatchr omits the optional apply_url, the connector derives the source-owned careers detail URL from the qualified vacancy ID. This preserves a public application entry without inventing an external destination or relaxing the canonical host boundary.

Authenticated Taleez and Teamtailor listing/detail adapters bind bounded pagination, source-specific payloads, and opaque credential references. Their deterministic fixtures do not replace a credentialed live receipt. The managed worker requires an explicitly injected credential-aware acquisition adapter and never copies the credential reference into a generic provider payload.

JobAffinity uses the same credential boundary for its Basic-auth REST feed. Pagination accepts only the API-provided, same-origin /restapi/v1/job?pagecursor=... link; arbitrary cursor URLs and cross-origin resource links are rejected.

Taleez hasMore/page state, Teamtailor page[after], Lever skip, SmartRecruiters offset/limit totals, JobAffinity _next, and credentialed Workable paging.next are extracted into durable checkpoints. Unverified cursor paths remain gated. Flatchr and Workable bind source-specific detail URLs, direct revalidation, explicit closure evidence, and response-schema drift comparison. Workable's public account feed remains the anonymous default; its SPI pagination and detail routes require an opaque credential reference. JobAffinity, Taleez, and Teamtailor application discovery accepts only source-provided, canonical-host application URLs.

Credential-free Workable detail revalidation uses the vendor-advertised /jobs/view/{shortcode}.md representation linked from each public job page. The bounded Markdown parser accepts only the H1 title and source-owned Apply link; credentialed installations continue to use SPI detail routes.

Every source has an executable conservative rate policy forwarded to the acquisition port. Policies bound concurrency, request spacing, retryable statuses, and Retry-After handling. The JobAffinity policy preserves its documented 45 requests/minute per-IP ceiling and Workable preserves 10 requests per 10 seconds.

The France-first direct HTML wave includes public ISCOD and CmonAlternance listing cards plus direct detail rechecks. Both parsers bind only canonical source hosts and qualified detail paths, decode stable public fields, and reject cross-origin links. Incremental ingestion remains gated because neither public page currently exposes a qualified cursor or change token.

ISCOD discovery tracks the current /offres-emploi-en-alternance/ listing path. A failed live discovery request marks every dependent supported capability failed while retaining closure as a separate transition blocker; downstream cells are never left looking merely unevaluated after their prerequisite failed.

CmonAlternance discovery uses the server-rendered /public/ latest-offers surface. The JavaScript /public/OFFRES search page is Algolia-backed and does not fabricate listing cards during direct HTML acquisition; full-index access requires a separately qualified search adapter.

Documented public-board adapters normalize vendor-specific listing shapes for Ashby, Greenhouse, Lever, Recruitee, and SmartRecruiters. Lever global/EU routing and numeric pagination cursors are explicit. Other ATS connectors use qualified structured-page/JSON-LD acquisition and remain subject to their matrix and live-receipt state.

Greenhouse accepts both the legacy boards.greenhouse.io and current job-boards.greenhouse.io public job hosts while keeping acquisition on boards-api.greenhouse.io. The public absolute_url is the qualified hosted application entry and never widens the accepted host set.

Recruitee list responses expose offers[], while current detail responses wrap the same public job under offer. The connector flattens that source-specific envelope before normalization and preserves careers_apply_url as the hosted application entry.

iCIMS and Workday use tenant-bound public career pages with source-specific structured-data fixtures, safe same-origin detail routing, and browser fallback. WeRecruit uses the same public-page path; its customer API remains account-gated because WeRecruit supplies API documentation only on request. None of these three sources advertises a qualified public change token here, so incremental ingestion remains explicitly gated while successful scans and direct detail rechecks qualify revalidation and closure evidence.

Current WeRecruit career pages expose a source-owned window.allOffers JSON payload for listings and HTML-encoded application/ld+json on detail pages. The direct parser consumes those public artifacts first; browser fallback remains available when an installation omits them.

Donor collector reconciliation

@lssm-tech/integration.job-sources/manifest reconciles an external donor collector registry with the 17-key matrix. Every donor key has exactly one disposition: mapped_to_target_key, planned_port (owner slice, or the explicit unassigned gap), source_placeholder_candidate or retired (each a coordinator proposal with a reason and evidence), or excluded_provenance_only. Rights (authorized, permission_required, commercial_redisplay_unqualified, credential_contract_required, unknown) and an opaque credential contract gate admitCollectorV1. Admission never enables a writer. A donor manifest qualification, a scheduler leaf-hash match or a revision role is source-hash evidence and never counts as rights or writer qualification. Absent donor manifest fields stay present: false. Reports are byte-stable; a changed donor digest marks a row needs_reconciliation, and a missing manifest makes the report incomplete.

Rights come from recorded receipts (rights-receipt:D-138 covers the donor audit's registry-enabled, authorized providers only); removing a receipt reverts its rows to unknown. Restrictions (permission_required, commercial_redisplay_unqualified) and credential contracts keep refusing after a receipt. A source the agent cannot act on or apply through is OFF (off_agent_cannot_apply, closed reason) and is refused with COLLECTOR_SOURCE_OFF whatever its rights. Each row has a collectorClass (ats, company_career_site, generic_career_site, source_feed_api, manual_provenance).

Public job inventory collectors (./public-job-inventory)

Keyless public collectors behind the scheduled job-inventory service (deploy/job-inventory), ported from the focused production-collectors (D-233: public employer boards only, no aggregator, no keyed API):

ProviderReadCensus
Greenhouse, Lever (global then EU host), Ashby, SmartRecruiters, Recruitee, Workablepublic board JSON APIcomplete board listing
Personiopublic XML feed (job pages for closure, robots honoured)complete feed
Teamtailorsitemap plus JSON-LD job pages, robots honouredsitemap
Workdaycareer site CXS API (POST .../jobs, detail per posting), robots honoured; 400 details per scan in a window that advances every six hours; multi-location postings kept at their first in-scope locationnever at the 2,000 listing cap
Career pageschema.org JobPosting (JSON-LD, then microdata) on the listing page, linked pages and the site's sitemaps, robots honoured; 100 pages per scan, rotatingnever (postings age out)

Each listing is normalized to the domain vocabulary, never guessed:

  • contract (permanent, fixed, internship, apprenticeship, freelance) and working schedule from stated labels (FR/EN/DE/ES/IT); schedule-only labels such as FullTime state no contract;
  • workplace from provider fields, else remote/hybrid stated in the location;
  • salary from structured provider pay (Lever, Ashby, Recruitee, JSON-LD), else pay stated explicitly in Lever's salary description or the posting text (description-pay.ts, port of hirly.description-pay.v2: a pay word, a currency and an explicit unit are required; a bare $ is the posting country's dollar in the US, Canada, Australia, Singapore and Mexico and names nothing elsewhere; multiplied units such as semi-monthly state nothing);
  • seniority from a stated level field matched whole against the focused vocabulary (ambiguous labels such as Associate or Mid-Senior level state none), else an explicit title word (Staff only before an engineering or design role), with seniorityBasis;
  • contract: VIE/VIA labels are fixed-term; seasonal labels (Seasonal, CDD saisonnier, Job d'été) are seasonal (D-251) under the enrichment stage's subject guard (seasonalContractStatedV1: Seasonal planning or Recrutement saisonnier state no contract), and a stated fixed term is refined to seasonal by a later seasonal label or by a title that states the season (CDD + Vendeur saisonnier H/F); student-job labels state none;
  • country from stated codes, else the location text (CLDR names, cities, US state codes with homonym rules), else the focused collectors' generated city catalog (city-country-aliases.ts, 29,457 names, generic and ambiguous names excluded) when the line's places name one country;
  • stated pay, seniority and schedule are persisted by the osint-worker run in public_job_inventory.posting_stated_facts (osint-store writePublicJobStatedFactsV1, read with readPublicJobStatedFactsV1 and merged into a record by withPublicJobStatedFactsV1);
  • an apply URL on every listing: the stated one, else the public posting page where the candidate applies (as the focused applyUrls).

Run health (health.ts) reports outcomes per provider, failures, incomplete reasons, failing boards and alerts. Board registration (registration-plan.ts, donor-registry.ts, the osint-worker register-boards.ts command) is idempotent and has a dry run.

Relationships

THIS PACKAGEintegration.job-sources36 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

5 declarations

Declared capabilities

Integration Job Sources

Named France, ATS, and job-board connectors for governed OSINT ingestion.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • cleanrimraf dist .turbo
  • lint:checknode ../../../scripts/biome.cjs check .
  • live:leverbun run scripts/live-lever.ts
  • live:public-batchbun run scripts/live-public-batch.ts
  • live:public-sourcebun run scripts/live-public-source.ts
  • testbun test
  • typechecktsgo --noEmit
  • discovery:censusbun run scripts/discovery-census.ts
  • discovery:discoverbun run scripts/discovery-discover.ts
  • discovery:registerbun run scripts/discovery-register.ts
  • discovery:healthbun run scripts/discovery-health.ts
  • discovery:coveragebun run scripts/discovery-coverage.ts
  • discovery:collectbun run scripts/discovery-collect.ts