stage-cli 1.0.0__py3-none-any.whl

stage/domain/__init__.py

@@ -0,0 +1,244 @@
+from stage.domain.company import Company
+from stage.domain.coverage import (
+    CoverageClassification,
+    CoverageDisposition,
+    CoverageRow,
+    CoverageState,
+    UnregisteredCompany,
+    coverage_state,
+)
+from stage.domain.custom_board import (
+    KNOWN_FIELDS,
+    REQUIRED_FIELDS,
+    TITLE_FIELD,
+    CustomBoard,
+)
+from stage.domain.discovery import (
+    CandidateSkipped,
+    DiscoveryEvent,
+    DiscoveryFinished,
+    DiscoveryStarted,
+    PlatformCandidate,
+    PlatformProbed,
+    ProbeResult,
+    UrlResolved,
+    UrlUnrecognized,
+)
+from stage.domain.enums import (
+    UNKNOWN_TERM,
+    DegreeRequirement,
+    EmployerSize,
+    ExportFormat,
+    JobStatus,
+    Language,
+    LocationBucket,
+    Platform,
+    ProbeVerdict,
+    RemoteScope,
+    RoleCategory,
+    SourceOfRecord,
+    SyncOutcome,
+)
+from stage.domain.events import (
+    BucketPlan,
+    CompanyDeferred,
+    CompanyFailed,
+    CompanyFinished,
+    CompanyStarted,
+    CompanyUnchanged,
+    PlannedRequest,
+    RequestLogged,
+    SourceBlocked,
+    SourceCapped,
+    SourceFailed,
+    SourceFinished,
+    SourceFresh,
+    SourceResting,
+    SourceRotated,
+    SourceStarted,
+    SyncEvent,
+    SyncFinished,
+    SyncStarted,
+    UnroutableCompanies,
+)
+from stage.domain.filters import DEFAULT_LIMIT, DEFAULT_WINDOW_DAYS, JobFilters
+from stage.domain.health import (
+    MIN_VOLUME_HISTORY,
+    STALE_AFTER_DAYS,
+    UNRECORDED_VOLUME,
+    VOLUME_DROP_RATIO,
+    IntegrityFinding,
+    IntegrityRepair,
+    VisitState,
+    VolumePoint,
+    VolumeSignal,
+    VolumeVerdict,
+    assess_volume,
+    classify_visit,
+)
+from stage.domain.ids import board_key, board_of, job_id
+from stage.domain.job import Job
+from stage.domain.matching import location_agrees, term_agrees
+from stage.domain.priority import SOURCE_PRIORITY, source_rank
+from stage.domain.quarantine import (
+    DEFAULT_QUARANTINE_LIMIT,
+    QuarantinedJob,
+    QuarantineFilters,
+    RejectionReason,
+)
+from stage.domain.rate_state import (
+    BLOCK_CAP_S,
+    BREAKER_THRESHOLD,
+    RateState,
+    block_duration,
+    blocked,
+    decay,
+)
+from stage.domain.retention import (
+    CLOSED_RETENTION_DAYS,
+    OPEN_RETENTION_DAYS,
+    PurgeResult,
+    Tombstone,
+)
+from stage.domain.rotation import Rotation, RotationMember, rotate
+from stage.domain.signals import SourceSignals
+from stage.domain.sync_run import SourceRunStats, SyncRun
+from stage.domain.text import (
+    dump,
+    first_line,
+    graphemes,
+    json_safe,
+    public_https_url,
+    sanitize,
+    summary,
+    truncate,
+    web_url,
+)
+from stage.domain.validator import HttpValidator
+from stage.domain.visits import (
+    REST_AFTER_FAILURES,
+    CompanyVisit,
+    DetailFetch,
+    SourceVisit,
+    is_resting,
+    rested_until,
+)
+from stage.domain.workday import WorkdayCrawl, WorkdayCrawlStep, WorkdayFacet
+
+__all__ = [
+    "DegreeRequirement",
+    "BLOCK_CAP_S",
+    "BREAKER_THRESHOLD",
+    "BucketPlan",
+    "CLOSED_RETENTION_DAYS",
+    "DEFAULT_LIMIT",
+    "DEFAULT_QUARANTINE_LIMIT",
+    "DEFAULT_WINDOW_DAYS",
+    "UNKNOWN_TERM",
+    "CandidateSkipped",
+    "Company",
+    "CustomBoard",
+    "KNOWN_FIELDS",
+    "REQUIRED_FIELDS",
+    "TITLE_FIELD",
+    "CompanyVisit",
+    "DetailFetch",
+    "CompanyDeferred",
+    "CompanyFailed",
+    "CompanyFinished",
+    "CompanyStarted",
+    "CompanyUnchanged",
+    "DiscoveryEvent",
+    "DiscoveryFinished",
+    "DiscoveryStarted",
+    "EmployerSize",
+    "ExportFormat",
+    "HttpValidator",
+    "Job",
+    "JobFilters",
+    "JobStatus",
+    "Language",
+    "LocationBucket",
+    "Platform",
+    "PlatformCandidate",
+    "PlatformProbed",
+    "PlannedRequest",
+    "OPEN_RETENTION_DAYS",
+    "SOURCE_PRIORITY",
+    "PurgeResult",
+    "ProbeResult",
+    "ProbeVerdict",
+    "QuarantineFilters",
+    "QuarantinedJob",
+    "RateState",
+    "RejectionReason",
+    "RequestLogged",
+    "RemoteScope",
+    "RoleCategory",
+    "Rotation",
+    "RotationMember",
+    "SourceBlocked",
+    "SourceFailed",
+    "SourceFinished",
+    "SourceCapped",
+    "SourceFresh",
+    "SourceResting",
+    "SourceRotated",
+    "SourceOfRecord",
+    "SourceRunStats",
+    "REST_AFTER_FAILURES",
+    "SourceVisit",
+    "is_resting",
+    "rested_until",
+    "SourceSignals",
+    "SourceStarted",
+    "SyncEvent",
+    "SyncFinished",
+    "SyncOutcome",
+    "SyncRun",
+    "SyncStarted",
+    "Tombstone",
+    "UnroutableCompanies",
+    "UrlResolved",
+    "UrlUnrecognized",
+    "WorkdayFacet",
+    "WorkdayCrawl",
+    "WorkdayCrawlStep",
+    "block_duration",
+    "blocked",
+    "decay",
+    "rotate",
+    "MIN_VOLUME_HISTORY",
+    "STALE_AFTER_DAYS",
+    "UNRECORDED_VOLUME",
+    "VOLUME_DROP_RATIO",
+    "IntegrityFinding",
+    "IntegrityRepair",
+    "VisitState",
+    "VolumePoint",
+    "VolumeSignal",
+    "VolumeVerdict",
+    "assess_volume",
+    "board_key",
+    "board_of",
+    "classify_visit",
+    "CoverageRow",
+    "CoverageClassification",
+    "CoverageDisposition",
+    "CoverageState",
+    "UnregisteredCompany",
+    "coverage_state",
+    "dump",
+    "first_line",
+    "graphemes",
+    "job_id",
+    "json_safe",
+    "location_agrees",
+    "public_https_url",
+    "sanitize",
+    "source_rank",
+    "summary",
+    "term_agrees",
+    "truncate",
+    "web_url",
+]

stage/domain/company.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass
+from datetime import date
+
+from stage.domain.custom_board import CustomBoard
+from stage.domain.enums import Platform, SourceOfRecord
+
+
+@dataclass(frozen=True, slots=True)
+class Company:
+    name: str
+    platform: Platform
+    slug: str
+    enabled: bool = True
+    rate_profile: str | None = None
+    last_verified: date | None = None
+    source_of_record: SourceOfRecord = SourceOfRecord.MANUAL
+    workday_tenant: str | None = None
+    workday_site: str | None = None
+    workday_dc: str | None = None
+    workday_facet: str | None = None
+    oracle_host: str | None = None
+    oracle_site: str | None = None
+    oracle_keyword: str | None = None
+    name_gate_exempt: bool = False
+    notes: str | None = None
+    recheck_after: date | None = None
+    paused_until: date | None = None
+    custom: CustomBoard | None = None
+
+    def due_for_recheck(self, today: date) -> bool:
+        return self.recheck_after is not None and self.recheck_after <= today
+
+    def pause_elapsed(self, today: date) -> bool:
+        return self.paused_until is not None and self.paused_until <= today
+
+    @property
+    def registry_key(self) -> str:
+        parts = [self.platform.value, self.slug]
+        parts.extend(
+            part
+            for part in (
+                self.workday_site,
+                self.workday_dc,
+                self.oracle_host,
+                self.oracle_site,
+            )
+            if part
+        )
+        return ":".join(parts)

stage/domain/coverage.py

@@ -0,0 +1,86 @@
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+
+from stage.domain.health import VisitState, classify_visit
+
+
+class CoverageState(StrEnum):
+    PRODUCING = "producing"
+    EMPTY = "empty"
+    FAILING = "failing"
+    STALE = "stale"
+    NEVER_REACHED = "never-reached"
+    UNROUTABLE = "unroutable"
+
+
+class CoverageDisposition(StrEnum):
+    FEED_ONLY = "feed-only"
+    UNAVAILABLE = "unavailable"
+    CUSTOM_JSON_CANDIDATE = "custom-json-candidate"
+    ADAPTER_CANDIDATE = "adapter-candidate"
+    DEFERRED = "deferred"
+
+
+@dataclass(frozen=True, slots=True)
+class CoverageRow:
+    company: str
+    platform: str
+    board: str
+    state: CoverageState
+    postings: int
+    last_success_at: datetime | None
+    consecutive_failures: int
+    last_error: str
+
+    @property
+    def is_gap(self) -> bool:
+        return self.state is CoverageState.EMPTY
+
+
+@dataclass(frozen=True, slots=True)
+class UnregisteredCompany:
+    company: str
+    sources: tuple[str, ...]
+    postings: int
+    quarantined: int = 0
+    posts_internships: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class CoverageClassification:
+    company: str
+    disposition: CoverageDisposition
+    note: str
+    checked_on: datetime
+    url: str | None = None
+
+
+def coverage_state(
+    postings: int,
+    visited: bool,
+    last_success_at: datetime | None,
+    consecutive_failures: int,
+    now: datetime,
+    stale_after_days: int,
+) -> CoverageState:
+    if postings > 0:
+        return CoverageState.PRODUCING
+    if not visited:
+        return CoverageState.NEVER_REACHED
+    visit = classify_visit(last_success_at, consecutive_failures, now, stale_after_days)
+    if visit is VisitState.FAILING:
+        return CoverageState.FAILING
+    if visit is VisitState.STALE:
+        return CoverageState.STALE
+    return CoverageState.EMPTY
+
+
+__all__ = [
+    "CoverageRow",
+    "CoverageClassification",
+    "CoverageDisposition",
+    "CoverageState",
+    "UnregisteredCompany",
+    "coverage_state",
+]

stage/domain/custom_board.py

@@ -0,0 +1,92 @@
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any
+
+TITLE_FIELD = "title"
+REQUIRED_FIELDS = (TITLE_FIELD,)
+KNOWN_FIELDS = (
+    TITLE_FIELD,
+    "id",
+    "location",
+    "url",
+    "description",
+    "department",
+    "employment_type",
+    "category",
+)
+
+_EMPTY: Mapping[str, str] = MappingProxyType({})
+_EMPTY_BODY: Mapping[str, Any] = MappingProxyType({})
+
+
+@dataclass(frozen=True, slots=True)
+class CustomBoard:
+    url: str
+    jobs_path: str = ""
+    fields: Mapping[str, str] = field(default_factory=lambda: _EMPTY)
+    url_template: str = ""
+    page_param: str = ""
+    page_size: int = 0
+    page_start: int = 0
+    page_step: int = 0
+    max_pages: int = 0
+    method: str = "GET"
+    fmt: str = "json"
+    extract: str = ""
+    row_selector: str = ""
+    row_filter: str = ""
+    item_tag: str = "item"
+    handshake_url: str = ""
+    token_pattern: str = ""
+    token_header: str = ""
+    token_prefix: str = ""
+    body: Mapping[str, Any] = field(default_factory=lambda: _EMPTY_BODY)
+    headers: Mapping[str, str] = field(default_factory=lambda: _EMPTY)
+    authoritative: bool = True
+
+    def mapped(self, name: str) -> str:
+        return self.fields.get(name, "")
+
+    @property
+    def embedded(self) -> bool:
+        return bool(self.extract)
+
+    @property
+    def rss(self) -> bool:
+        return self.fmt == "rss"
+
+    @property
+    def html(self) -> bool:
+        return self.fmt == "html"
+
+    @property
+    def sitemap(self) -> bool:
+        return self.fmt == "sitemap"
+
+    @property
+    def jsonld(self) -> bool:
+        return self.fmt == "jsonld"
+
+    @property
+    def handshakes(self) -> bool:
+        return bool(self.handshake_url and self.token_pattern and self.token_header)
+
+    @property
+    def posts(self) -> bool:
+        return self.method.upper() == "POST"
+
+    @property
+    def paginated(self) -> bool:
+        return bool(self.page_param) and self.page_size > 0
+
+    def page_budget(self, default: int, ceiling: int) -> int:
+        if not self.paginated:
+            return 1
+        return min(ceiling, self.max_pages or default)
+
+    def page_value(self, index: int) -> int:
+        return self.page_start + index * (self.page_step or self.page_size)
+
+
+__all__ = ["KNOWN_FIELDS", "REQUIRED_FIELDS", "TITLE_FIELD", "CustomBoard"]

stage/domain/discovery.py

@@ -0,0 +1,94 @@
+from dataclasses import dataclass
+
+from stage.domain.enums import Platform, ProbeVerdict
+from stage.domain.events import RequestLogged
+
+
+@dataclass(frozen=True, slots=True)
+class PlatformCandidate:
+    platform: Platform
+    slug: str
+    workday_tenant: str | None = None
+    workday_site: str | None = None
+    workday_dc: str | None = None
+    oracle_host: str | None = None
+    oracle_site: str | None = None
+    resolves_board: bool = True
+
+    @property
+    def label(self) -> str:
+        if not self.resolves_board:
+            return f"{self.platform.value}/{self.slug} (front end only — board unresolved)"
+        if self.workday_tenant is not None:
+            site = self.workday_site or "?"
+            return f"{self.platform.value}/{self.workday_tenant}/{site}@{self.workday_dc or '?'}"
+        if self.oracle_host is not None:
+            return f"{self.platform.value}/{self.oracle_host}/{self.oracle_site or '?'}"
+        return f"{self.platform.value}/{self.slug}"
+
+
+@dataclass(frozen=True, slots=True)
+class ProbeResult:
+    company: str
+    candidate: PlatformCandidate
+    verdict: ProbeVerdict
+    url: str
+    board_name: str = ""
+    job_count: int | None = None
+    detail: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveryStarted:
+    companies: tuple[str, ...]
+    platforms: tuple[str, ...]
+    probes_planned: int
+
+
+@dataclass(frozen=True, slots=True)
+class CandidateSkipped:
+    company: str
+    slug: str
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class PlatformProbed:
+    result: ProbeResult
+
+
+@dataclass(frozen=True, slots=True)
+class UrlResolved:
+    url: str
+    candidate: PlatformCandidate
+    detail: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class UrlUnrecognized:
+    url: str
+    detail: str
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveryFinished:
+    matched: tuple[ProbeResult, ...]
+    unverified: tuple[ProbeResult, ...]
+    rejected: tuple[ProbeResult, ...]
+    missed: int
+    errors: int
+    requests: int
+    elapsed_ms: float
+    ceiling_hit: tuple[str, ...] = ()
+    non_json: tuple[tuple[str, int], ...] = ()
+
+
+DiscoveryEvent = (
+    DiscoveryStarted
+    | CandidateSkipped
+    | PlatformProbed
+    | RequestLogged
+    | UrlResolved
+    | UrlUnrecognized
+    | DiscoveryFinished
+)

stage/domain/enums.py

@@ -0,0 +1,114 @@
+from enum import StrEnum
+
+
+class JobStatus(StrEnum):
+    OPEN = "open"
+    CLOSED = "closed"
+
+
+class Language(StrEnum):
+    EN = "en"
+    FR = "fr"
+    BILINGUAL = "bilingual"
+
+    UNKNOWN = "unknown"
+
+
+class LocationBucket(StrEnum):
+    CANADA = "canada"
+    USA = "usa"
+    MONTREAL = "montreal"
+    INTERNATIONAL = "international"
+
+    UNKNOWN = "unknown"
+
+
+class RemoteScope(StrEnum):
+    CANADA = "remote-canada"
+    US = "remote-us"
+    UNSPECIFIED = "remote-unspecified"
+
+
+class RoleCategory(StrEnum):
+    SWE = "swe"
+    SECURITY = "security"
+    DATA = "data"
+    ML_AI = "ml-ai"
+    QUANT = "quant"
+    INFRA = "infra"
+    HARDWARE = "hardware"
+    EMBEDDED = "embedded"
+    GENERAL_CS = "general-cs"
+    UNKNOWN = "unknown"
+
+
+class DegreeRequirement(StrEnum):
+    NONE = "none"
+    BACHELORS = "bachelors"
+    MASTERS = "masters"
+    PHD = "phd"
+    UNKNOWN = "unknown"
+
+
+class Platform(StrEnum):
+    GREENHOUSE = "greenhouse"
+    LEVER = "lever"
+    ASHBY = "ashby"
+    SMARTRECRUITERS = "smartrecruiters"
+    RECRUITEE = "recruitee"
+    WORKABLE = "workable"
+    PERSONIO = "personio"
+    TEAMTAILOR = "teamtailor"
+    BREEZY = "breezy"
+    BAMBOOHR = "bamboohr"
+    JOBVITE = "jobvite"
+    JOIN = "join"
+    WORKDAY = "workday"
+    TALEO = "taleo"
+    ORACLE_CLOUD = "oracle_cloud"
+    SUCCESSFACTORS = "successfactors"
+    NJOYN = "njoyn"
+    ICIMS = "icims"
+    AVATURE = "avature"
+    PHENOM = "phenom"
+    EIGHTFOLD = "eightfold"
+    CORNERSTONE = "cornerstone"
+    COLLAGE = "collage"
+    CUSTOM_JSON = "custom_json"
+
+
+class SourceOfRecord(StrEnum):
+    OPENJOBS = "openjobs"
+    DISCOVER = "discover"
+    MANUAL = "manual"
+
+
+class ProbeVerdict(StrEnum):
+    MATCH = "match"
+    UNVERIFIED = "unverified"
+    EMPTY = "empty"
+    REJECTED = "rejected"
+    MISS = "miss"
+    ERROR = "error"
+
+
+class EmployerSize(StrEnum):
+    STARTUP = "startup"
+    MID = "mid"
+    LARGE = "large"
+
+
+class SyncOutcome(StrEnum):
+    SUCCESS = "success"
+    PARTIAL = "partial"
+    FAILURE = "failure"
+
+
+class ExportFormat(StrEnum):
+    CSV = "csv"
+    JSON = "json"
+    MD = "md"
+    PDF = "pdf"
+
+
+UNKNOWN_TERM = "unknown"