hiringcafe-cli 0.1.4__py3-none-any.whl

hiringcafe_cli/http_client.py

@@ -0,0 +1,245 @@
+"""Anonymous HiringCafe web and SSR HTTP client."""
+
+import json
+import os
+import random
+import time
+import urllib.parse
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from hiringcafe_cli.io_limits import read_limited
+
+BROWSER_HEADERS = {
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+    "User-Agent": (
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+        "(KHTML, like Gecko) Chrome/128.0 Safari/537.36 hiringcafe-cli/0.1"
+    ),
+}
+REQUIRED_SSR_KEYS = ("ssrHits", "ssrPage", "ssrTotalCount", "ssrPageSize", "ssrIsLastPage")
+RETRYABLE_STATUSES = {408, 429, *range(500, 600)}
+
+
+class HireCafeHTTPError(RuntimeError):
+    """A non-success HTTP response from a HiringCafe endpoint."""
+
+    def __init__(self, endpoint: str, status: int, reason: str = "") -> None:
+        """Initialize the HTTP error.
+
+        Args:
+            endpoint: Stable endpoint name for diagnostics.
+            status: HTTP response status.
+            reason: Optional response reason.
+        """
+        self.endpoint = endpoint
+        self.status = status
+        self.reason = reason
+        super().__init__(f"{endpoint} returned HTTP {status}")
+
+
+class HireCafeTransportError(RuntimeError):
+    """A transport failure before an HTTP response completed."""
+
+    def __init__(self, endpoint: str, cause: Exception) -> None:
+        """Initialize the transport error.
+
+        Args:
+            endpoint: Stable endpoint name for diagnostics.
+            cause: Original exception.
+        """
+        self.endpoint = endpoint
+        self.cause = cause
+        super().__init__(f"{endpoint} transport failed: {cause}")
+
+
+def configured_base_url() -> str:
+    """Return the configured HTTPS anonymous web base URL without a trailing slash.
+
+    Raises:
+        ValueError: If the configured URL is not HTTPS.
+    """
+    base_url = os.environ.get("HIRINGCAFE_BASE_URL", "https://hiringcafe.com").rstrip("/")
+    parsed = urllib.parse.urlsplit(base_url)
+    if parsed.scheme != "https" or not parsed.netloc or parsed.username is not None or parsed.password is not None:
+        raise ValueError("HIRINGCAFE_BASE_URL must use HTTPS")
+    return base_url
+
+
+def retryable(error: Exception) -> bool:
+    """Classify whether an anonymous GET error may be retried."""
+    return isinstance(error, HireCafeTransportError) or (
+        isinstance(error, HireCafeHTTPError) and error.status in RETRYABLE_STATUSES
+    )
+
+
+class RetryPolicy:
+    """Bounded exponential backoff with full jitter."""
+
+    def __init__(self, count: int = 2, base: float = 0.5, timeout: float = 30) -> None:
+        self.count = count
+        self.base = base
+        self.timeout = timeout
+        self.sleep = time.sleep
+
+    def delay(self, attempt: int) -> float:
+        """Return the bounded backoff for a zero-based attempt."""
+        return random.uniform(0, self.base * (2**attempt))
+
+
+def parse_ssr_page(html: str) -> dict:
+    """Parse and validate pageProps from a HiringCafe SSR response.
+
+    Args:
+        html: Complete SSR HTML document.
+
+    Returns:
+        The validated pageProps object.
+
+    Raises:
+        ValueError: If __NEXT_DATA__ is missing, malformed, or incomplete.
+    """
+    marker_start = '<script id="__NEXT_DATA__" type="application/json">'
+    fallback_start = '<script id="__NEXT_DATA__">'
+    starts = [index for index in (html.find(marker_start), html.find(fallback_start)) if index >= 0]
+    if not starts:
+        raise ValueError("missing __NEXT_DATA__")
+    start = min(starts)
+    content_start = html.index(">", start) + 1
+    end = html.find("</script>", content_start)
+    if end < 0:
+        raise ValueError("unterminated __NEXT_DATA__")
+    try:
+        payload = json.loads(html[content_start:end])
+    except json.JSONDecodeError as error:
+        raise ValueError("invalid __NEXT_DATA__ JSON") from error
+    properties = payload.get("props", {}).get("pageProps", {})
+    if not isinstance(properties, dict):
+        raise ValueError("__NEXT_DATA__ pageProps is not an object")
+    for key in REQUIRED_SSR_KEYS:
+        if key not in properties:
+            raise ValueError(f"missing SSR key: {key}")
+    return properties
+
+
+class WebClient:
+    """Client that owns every anonymous HiringCafe web URL."""
+
+    urlopen = staticmethod(urlopen)
+
+    def __init__(self, base_url: str | None = None, timeout: float = 30) -> None:
+        """Initialize the client.
+
+        Args:
+            base_url: HTTPS base URL; defaults to ``HIRINGCAFE_BASE_URL`` or production.
+            timeout: Per-request timeout in seconds.
+        """
+        self.base_url = base_url.rstrip("/") if base_url else configured_base_url()
+        self.timeout = timeout
+        self.retry_policy = RetryPolicy(timeout=timeout)
+
+    def search_page(self, search_state: dict, page: int) -> dict:
+        """Fetch one SSR search page.
+
+        Args:
+            search_state: Complete search state object.
+            page: Nonnegative page number.
+
+        Returns:
+            Validated ``props.pageProps``.
+        """
+        query = urllib.parse.urlencode({"searchState": json.dumps(search_state), "page": page})
+        return parse_ssr_page(self._get(f"{self.base_url}/?{query}", "search"))
+
+    def job_description(self, object_id: str) -> dict:
+        """Fetch a job-description JSON object.
+
+        Args:
+            object_id: Nonempty HiringCafe object ID.
+
+        Returns:
+            The response's ``job`` object.
+        """
+        query = urllib.parse.urlencode({"id": object_id})
+        payload = self._json(self._get(f"{self.base_url}/api/job-description?{query}", "job-description"))
+        job = payload.get("job")
+        if not isinstance(job, dict):
+            raise ValueError("job-description response has no job object")
+        return job
+
+    def marketplace_stage(self, object_id: str, id_token: str, stage: str) -> None:
+        """Sync a saved-job stage through the verified marketplace endpoint."""
+        body = json.dumps(
+            {"job_id": object_id, "user_token": id_token, "stage": stage},
+            separators=(",", ":"),
+        ).encode()
+        request = urllib.request.Request(
+            f"{self.base_url}/api/updateMarketplaceJobStageForUser",
+            data=body,
+            headers={**BROWSER_HEADERS, "Content-Type": "application/json", "Accept": "application/json"},
+            method="POST",
+        )
+        try:
+            with self.urlopen(request, timeout=self.timeout) as response:
+                read_limited(response, "marketplace-stage")
+        except HTTPError as error:
+            raise HireCafeHTTPError("marketplace-stage", error.code, error.reason) from error
+        except (URLError, TimeoutError, OSError) as error:
+            raise HireCafeTransportError("marketplace-stage", error) from error
+
+    def marketplace_mutation(self, endpoint: str, body: dict) -> None:
+        """POST a marketplace saved-job mutation and require success."""
+        request = urllib.request.Request(
+            f"{self.base_url}/api/{endpoint}",
+            data=json.dumps(body, separators=(",", ":")).encode(),
+            headers={**BROWSER_HEADERS, "Content-Type": "application/json", "Accept": "application/json"},
+            method="POST",
+        )
+        try:
+            with self.urlopen(request, timeout=self.timeout) as response:
+                read_limited(response, endpoint)
+        except HTTPError as error:
+            raise HireCafeHTTPError(endpoint, error.code, error.reason) from error
+        except (URLError, TimeoutError, OSError) as error:
+            raise HireCafeTransportError(endpoint, error) from error
+
+    def remove_from_list(self, object_id: str, id_token: str, stage: str) -> None:
+        """Remove a job from its old marketplace stage list."""
+        self.marketplace_mutation(
+            "removeJobFromList",
+            {"job_id": object_id, "user_token": id_token, "stage": stage, "should_delete": False},
+        )
+
+    def remove_job(self, object_id: str, id_token: str, stage: str) -> None:
+        """Delete a job through the marketplace owner endpoint."""
+        self.marketplace_mutation(
+            "removeJobFromList",
+            {"job_id": object_id, "user_token": id_token, "stage": stage, "should_delete": True},
+        )
+
+    def _get(self, url: str, endpoint: str) -> str:
+        """GET a URL and return its decoded body."""
+        request = Request(url, headers=BROWSER_HEADERS)
+        for attempt in range(self.retry_policy.count + 1):
+            try:
+                with self.urlopen(request, timeout=self.timeout) as response:
+                    return read_limited(response, endpoint).decode("utf-8")
+            except HTTPError as error:
+                wrapped = HireCafeHTTPError(endpoint, error.code, error.reason)
+            except (URLError, TimeoutError, OSError) as error:
+                wrapped = HireCafeTransportError(endpoint, error)
+            if attempt == self.retry_policy.count or not retryable(wrapped):
+                raise wrapped
+            self.retry_policy.sleep(self.retry_policy.delay(attempt))
+        raise AssertionError("unreachable")
+
+    def _json(self, body: str) -> dict:
+        """Parse a JSON object response."""
+        try:
+            value = json.loads(body)
+        except json.JSONDecodeError as error:
+            raise ValueError("invalid JSON response") from error
+        if not isinstance(value, dict):
+            raise ValueError("JSON response is not an object")
+        return value

hiringcafe_cli/io_limits.py

@@ -0,0 +1,23 @@
+"""Bounded reads for external HTTP responses."""
+
+RESPONSE_LIMIT_BYTES = 8 * 1024 * 1024
+
+
+def read_limited(response, endpoint: str, limit: int = RESPONSE_LIMIT_BYTES) -> bytes:
+    """Read an HTTP response without trusting its size.
+
+    Args:
+        response: An open ``http.client.HTTPResponse``-compatible object.
+        endpoint: Stable endpoint name used in diagnostics.
+        limit: Maximum accepted response size in bytes.
+
+    Returns:
+        The complete response body when it is within ``limit``.
+
+    Raises:
+        ValueError: If the response exceeds ``limit``.
+    """
+    body = response.read(limit + 1)
+    if len(body) > limit:
+        raise ValueError(f"{endpoint} response exceeds {limit} bytes")
+    return body

hiringcafe_cli/job.py

@@ -0,0 +1,63 @@
+"""Anonymous job-description command."""
+
+import json
+import os
+import sys
+
+from hiringcafe_cli.cache import active_cache_root, cache_read, cache_write
+from hiringcafe_cli.http_client import WebClient, configured_base_url
+
+JOB_TTL = 86400
+
+
+def show(object_id: str, no_cache: bool = False, cache_ttl: int | None = None) -> dict:
+    """Fetch and normalize a job description.
+
+    Args:
+        object_id: Nonempty HiringCafe object ID.
+
+    Returns:
+        Stable version-1 job-detail envelope.
+    """
+    cache_root = active_cache_root()
+    client = WebClient()
+    key = ("job", configured_base_url(), object_id)
+    ttl = JOB_TTL if cache_ttl is None else cache_ttl
+    enabled = no_cache is False and not os.environ.get("HIRINGCAFE_NO_CACHE")
+    raw = cache_read(key, ttl, cache_root, enabled=enabled)
+    if raw is not None:
+        job = raw
+    else:
+        job = client.job_description(object_id)
+        cache_write(key, job, ttl, cache_root, enabled=enabled)
+    if not job:
+        raise ValueError("job-description response has no job object")
+    information = job.get("job_information") or {}
+    description = information.get("description")
+    return {
+        "version": 1,
+        "job": {
+            "id": job.get("objectID", object_id),
+            "title": information.get("title"),
+            "description": " ".join(str(description).split()) if description is not None else None,
+            "url": job.get("apply_url"),
+        },
+    }
+
+
+def run(argv: object, json_output: bool) -> int:
+    """Execute job show with CLI arguments."""
+    if not argv.object_id:
+        print("hiringcafe: object ID must not be empty", file=sys.stderr)
+        return 2
+    envelope = show(
+        argv.object_id,
+        no_cache=getattr(argv, "no_cache", False),
+        cache_ttl=getattr(argv, "cache_ttl", None),
+    )
+    if json_output:
+        print(json.dumps(envelope, separators=(",", ":")))
+    else:
+        job = envelope["job"]
+        print(f"{job['title'] or 'Untitled'}\n{job['url'] or ''}\n\n{job['description'] or ''}")
+    return 0

hiringcafe_cli/probe.py

@@ -0,0 +1,140 @@
+"""Opt-in endpoint regression probe for verified anonymous HiringCafe routes."""
+
+import json
+import os
+import urllib.parse
+from html.parser import HTMLParser
+from urllib.request import urlopen
+
+from hiringcafe_cli.http_client import configured_base_url
+from hiringcafe_cli.io_limits import read_limited
+
+BASE_URL = configured_base_url()
+SEARCH_STATE = {"searchQuery": "python developer"}
+TIMEOUT_SECONDS = 30
+
+
+class _NextDataParser(HTMLParser):
+    """HTML parser that captures the ``__NEXT_DATA__`` script body."""
+
+    def __init__(self) -> None:
+        """Initialize parser state."""
+        super().__init__()
+        self.payload: str | None = None
+        self._capture = False
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        """Begin capturing the sole Next.js data script.
+
+        Args:
+            tag: Current HTML tag.
+            attrs: Tag attributes.
+        """
+        if tag == "script" and dict(attrs).get("id") == "__NEXT_DATA__":
+            self._capture = True
+
+    def handle_data(self, data: str) -> None:
+        """Collect script text.
+
+        Args:
+            data: Current text node.
+        """
+        if self._capture:
+            self.payload = (self.payload or "") + data
+
+    def handle_endtag(self, tag: str) -> None:
+        """Stop capturing at the closing script tag.
+
+        Args:
+            tag: Current HTML tag.
+        """
+        if tag == "script" and self._capture:
+            self._capture = False
+
+
+def extract_next_data(html: str) -> dict:
+    """Extract the Next.js payload from search HTML.
+
+    Args:
+        html: Complete SSR HTML response.
+
+    Returns:
+        The parsed ``__NEXT_DATA__`` object.
+
+    Raises:
+        ValueError: If the script is missing or contains invalid JSON.
+    """
+    parser = _NextDataParser()
+    parser.feed(html)
+    if parser.payload is None:
+        raise ValueError("missing __NEXT_DATA__")
+    try:
+        payload = json.loads(parser.payload)
+    except json.JSONDecodeError as error:
+        raise ValueError("invalid __NEXT_DATA__ JSON") from error
+    if not isinstance(payload, dict):
+        raise ValueError("__NEXT_DATA__ is not an object")
+    return payload
+
+
+def _get(url: str) -> dict | str:
+    """GET a verified anonymous endpoint and return decoded JSON or HTML."""
+    request = urllib.request.Request(
+        url,
+        headers={
+            "Accept": "text/html,application/json;q=0.9,*/*;q=0.8",
+            "User-Agent": "Mozilla/5.0 hiringcafe-cli/0.1 endpoint-probe",
+        },
+    )
+    with urlopen(request, timeout=TIMEOUT_SECONDS) as response:
+        body = read_limited(response, "endpoint probe").decode("utf-8")
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError:
+        return body
+
+
+def _page(page: int) -> dict:
+    """Fetch and validate one SSR search page."""
+    query = urllib.parse.urlencode({"searchState": json.dumps(SEARCH_STATE), "page": page})
+    result = _get(f"{BASE_URL}/?{query}")
+    html = result if isinstance(result, str) else ""
+    properties = extract_next_data(html).get("props", {}).get("pageProps", {})
+    required = ("ssrHits", "ssrTotalCount", "ssrPage", "ssrIsLastPage")
+    for key in required:
+        if key not in properties:
+            raise ValueError(f"missing SSR key: {key}")
+    initial_state = properties.get("initialSearchState", {})
+    if initial_state.get("searchQuery") != SEARCH_STATE["searchQuery"]:
+        raise ValueError("page metadata lost search state")
+    return properties
+
+
+def main(argv: object | None = None, json_output: bool = False) -> int:
+    """Run the endpoint probe only when explicitly enabled.
+
+    Args:
+        argv: Reserved for future CLI options.
+
+    Returns:
+        Process exit code.
+    """
+    del argv
+    if os.environ.get("LIVE") != "1":
+        print("skipped: set LIVE=1 to probe HiringCafe")
+        return 0
+
+    pages = [_page(0), _page(1)]
+    hits = pages[0]["ssrHits"]
+    if not hits or not isinstance(hits[0].get("objectID"), str):
+        raise ValueError("search page 0 has no usable objectID")
+    object_id = hits[0]["objectID"]
+    detail_query = urllib.parse.urlencode({"id": object_id})
+    detail = _get(f"{BASE_URL}/api/job-description?{detail_query}")
+    if not isinstance(detail, dict) or not isinstance(detail.get("job"), dict):
+        raise ValueError("job response has no job object")
+
+    for index in range(len(pages)):
+        print(f"search page {index}: ok")
+    print(f"job description {object_id}: ok")
+    return 0

hiringcafe_cli/saved_jobs.py

@@ -0,0 +1,101 @@
+"""Saved-job domain models and Firestore value conversion."""
+
+from datetime import datetime
+from typing import Any
+
+VALID_STAGES = ("saved", "applied", "interviewing", "offer", "rejected", "ghosted", "hidden")
+PIPELINE_STAGES = tuple(stage for stage in VALID_STAGES if stage != "hidden")
+
+
+class SavedJobError(ValueError):
+    """A saved-job document violates the verified contract."""
+
+
+def _document_id(document: dict) -> str:
+    """Extract the final Firestore document ID."""
+    name = document.get("name", "")
+    return name.rsplit("/", 1)[-1]
+
+
+def _value(value: Any) -> Any:
+    """Convert one Firestore typed value recursively."""
+    if not isinstance(value, dict):
+        return value
+    for key in ("stringValue", "integerValue", "doubleValue", "booleanValue"):
+        if key in value:
+            return value[key]
+    if "timestampValue" in value:
+        timestamp = datetime.fromisoformat(value["timestampValue"].replace("Z", "+00:00"))
+        return timestamp.isoformat().replace("+00:00", "Z")
+    if "mapValue" in value:
+        return decode_firestore_fields(value["mapValue"].get("fields", {}))
+    if "arrayValue" in value:
+        return [_value(item) for item in value["arrayValue"].get("values", [])]
+    return None
+
+
+def decode_firestore_fields(fields: dict) -> dict:
+    """Decode Firestore typed fields to plain Python values."""
+    return {key: _value(value) for key, value in fields.items()}
+
+
+def normalize_saved_job(document: dict) -> dict:
+    """Normalize a Firestore savedJobs document.
+
+    Args:
+        document: Firestore REST document.
+
+    Returns:
+        Stable saved-job representation.
+
+    Raises:
+        SavedJobError: If identity, ownership, or stage is invalid.
+    """
+    fields = decode_firestore_fields(document.get("fields", {}))
+    object_id = fields.get("objectID")
+    owner = fields.get("owner")
+    if not isinstance(object_id, str) or not object_id:
+        raise SavedJobError("saved job has no objectID")
+    if not isinstance(owner, str) or not owner:
+        raise SavedJobError("saved job has no owner")
+    stage = fields.get("stage")
+    if stage not in VALID_STAGES:
+        raise SavedJobError(f"saved job has invalid stage: {stage}")
+    job_information = fields.get("job_information") or {}
+    company = fields.get("enriched_company_data") or {}
+    processed = fields.get("v5_processed_job_data") or {}
+    return {
+        "id": object_id,
+        "savedAt": fields.get("dateSaved"),
+        "stage": stage,
+        "stageHistory": fields.get("stageHistory", []),
+        "hidden": bool(fields.get("isHidden", False)),
+        "documentId": fields.get("docID") or _document_id(document),
+        "title": job_information.get("title"),
+        "company": company.get("name", processed.get("company_name")),
+        "location": processed.get("formatted_workplace_location"),
+        "url": fields.get("apply_url"),
+    }
+
+
+def encode_firestore_value(value):
+    """Encode one plain Python value in Firestore REST representation."""
+    if value is None:
+        return {"nullValue": None}
+    if isinstance(value, bool):
+        return {"booleanValue": value}
+    if isinstance(value, int):
+        return {"integerValue": str(value)}
+    if isinstance(value, float):
+        return {"doubleValue": value}
+    if isinstance(value, str):
+        return {"stringValue": value}
+    if isinstance(value, list):
+        return {"arrayValue": {"values": [encode_firestore_value(item) for item in value]}}
+    if isinstance(value, dict):
+        if set(value) == {"arrayValue"}:
+            return value
+        if set(value) == {"appendMissingElements"}:
+            return {"arrayValue": value}
+        return {"mapValue": {"fields": {key: encode_firestore_value(item) for key, item in value.items()}}}
+    raise SavedJobError(f"unsupported Firestore value: {type(value).__name__}")