wehub-resource-sync
122 lines
6.2 KiB
JavaScript
122 lines
6.2 KiB
JavaScript
// Type catalog for the provider plugin contract.
|
|
//
|
|
// This file is documentation-only — pure JSDoc @typedef annotations. The
|
|
// project is plain ESM JavaScript with no build step; provider authors can
|
|
// reference these types via `/** @typedef {import('./_types.js').Provider} Provider */`
|
|
// at the top of a `// @ts-check`-enabled file to get IDE hints. The runtime
|
|
// contract is enforced by scan.mjs (id presence, fetch is a function, fetch
|
|
// returns an array), not by these annotations.
|
|
//
|
|
// Files prefixed with _ are never loaded as providers by scan.mjs.
|
|
|
|
/**
|
|
* Normalized job posting — the unit of currency throughout the scanner.
|
|
*
|
|
* @typedef {object} Job
|
|
* @property {string} title Required, non-empty after trim.
|
|
* @property {string} url Required, absolute URL — used as the dedup key.
|
|
* @property {string} company May be empty when the source can't expose it
|
|
* at the list-page level; populated downstream.
|
|
* @property {string} location May be empty.
|
|
* @property {string} [description] Job description text, populated ONLY when the
|
|
* provider's list payload carries it for free (no
|
|
* extra per-job request — the scanner is zero-token).
|
|
* Lever supplies it via `descriptionPlain`; most
|
|
* providers omit it. Consumed by scan.mjs's
|
|
* content_filter; an empty/absent value always
|
|
* passes the filter.
|
|
* @property {number} [postedAt] Epoch ms when the posting was published.
|
|
* Omitted when the source doesn't expose a
|
|
* usable date. scan.mjs ignores it; consumers
|
|
* like scan-ats-full.mjs use it for recency
|
|
* filtering.
|
|
* @property {number} [trustScore] 0-100 trust score from _trust-validator.mjs.
|
|
* @property {string[]} [trustFlags] Flags raised by trust validation (e.g.
|
|
* 'invalid_url', 'suspicious_domain').
|
|
* @property {'high'|'medium'|'low'} [trustLevel] Classification derived from
|
|
* trustScore.
|
|
*/
|
|
|
|
/**
|
|
* Result returned by the trust validator for a single job posting.
|
|
*
|
|
* @typedef {object} TrustResult
|
|
* @property {number} score 0-100, where 100 = fully trusted.
|
|
* @property {string[]} flags Flags raised (e.g. 'invalid_url', 'suspicious_domain').
|
|
* @property {'high'|'medium'|'low'} level Classification: 90-100 high, 60-89 medium, 0-59 low.
|
|
*/
|
|
|
|
/**
|
|
* A single `tracked_companies` entry from `portals.yml`.
|
|
*
|
|
* Provider-specific fields are opaque to scan.mjs and validated by the
|
|
* provider itself. Examples in current providers: `api`, `careers_url`.
|
|
* Providers read these directly off the entry object — no schema enforcement
|
|
* at the framework level.
|
|
*
|
|
* @typedef {object} PortalEntry
|
|
* @property {string} name User-facing label; appears in logs and placeholders.
|
|
* @property {boolean} [enabled] Default: true.
|
|
* @property {string} [careers_url] Public listing URL; consumed by detect().
|
|
* @property {string} [api] JSON API URL; used directly by greenhouse/ashby providers.
|
|
* @property {string} [provider] Explicit provider id — bypasses detect().
|
|
* @property {('http')} [transport] Default: 'http'. Reserved for future transports.
|
|
* @property {number} [max_pages] Provider-specific pagination cap (avature, workday).
|
|
* @property {string} [offset_param] avature only: pins the pagination query key and disables the
|
|
* provider's jobOffset→offset self-heal. Rarely needed — an
|
|
* escape hatch for a tenant the auto-switch can't resolve.
|
|
*/
|
|
|
|
/**
|
|
* Returned by `detect()` when a provider claims an entry. `url` is
|
|
* informational (used in logs); routing only checks for a non-null return.
|
|
*
|
|
* @typedef {object} DetectHit
|
|
* @property {string} url
|
|
*/
|
|
|
|
/**
|
|
* Options forwarded to the underlying `fetch` call.
|
|
*
|
|
* @typedef {object} FetchOptions
|
|
* @property {number} [timeoutMs]
|
|
* @property {Object<string,string>} [headers]
|
|
* @property {string} [method]
|
|
* @property {(string|null)} [body]
|
|
* @property {('error'|'follow'|'manual')} [redirect]
|
|
*/
|
|
|
|
/**
|
|
* What scan.mjs hands to provider.fetch(). For Phase A only `transport: 'http'`
|
|
* is implemented; the shape reserves room for future transports without
|
|
* breaking the contract.
|
|
*
|
|
* @typedef {object} Context
|
|
* @property {('http')} transport
|
|
* @property {(url: string, opts?: FetchOptions) => Promise<string>} fetchText
|
|
* @property {(url: string, opts?: FetchOptions) => Promise<unknown>} fetchJson
|
|
* @property {number} [maxPages] Optional pagination hint. When set (verify-portals.mjs's
|
|
* health probe passes 1), a paginating provider SHOULD stop
|
|
* after this many pages — the probe only needs the first page
|
|
* to tell a live board from a broken one, and must not walk an
|
|
* entire careers site. Providers that ignore it stay correct:
|
|
* the probe caps their requests defensively via the context's
|
|
* own fetch functions.
|
|
* @property {(ms: number) => Promise<void>} [sleep] Optional cross-provider pacing hook used by
|
|
* paginating providers (avature, workday) to throttle between page
|
|
* requests. May be absent — providers fall back to a native
|
|
* `setTimeout`-based delay.
|
|
*/
|
|
|
|
/**
|
|
* The provider contract — the default export of every providers/*.mjs file
|
|
* (excluding _-prefixed shared helpers).
|
|
*
|
|
* @typedef {object} Provider
|
|
* @property {string} id Unique across all loaded providers.
|
|
* @property {((entry: PortalEntry) => (DetectHit | null))} [detect] Optional auto-detection.
|
|
* @property {(entry: PortalEntry, ctx: Context) => Promise<Job[]>} fetch Required.
|
|
*/
|
|
|
|
export {};
|