"""Workable: `workable:`, paged ten roles at a time with a stated total. Written from one real board, Hugging Face's, on 2026-09-28, when the first board with roles was seen; jobhunt-hq did not read Workable. The list carries no text. The text is read per role by `detail`, `GET /api/v2/accounts/{slug}/jobs/{shortcode}` (checked 2026-09-30, Hugging Face's DB4D7C0EC8): the list's fields again, and `description`, `requirements` and `benefits` as HTML. The list gives the numeric `id` and the `shortcode`; the role's `source_id` is the number, so the row keeps the `shortcode` for this request. The API answers 429 to a run of requests; the runner spaces the reads and stops on one. """ from __future__ import annotations import html import json from collections.abc import Callable from typing import Any from desk.sources import strip_html from ._contract import Ask, Fields, Place, Reads from ._shared import Get, Page, Row, add_place, only, parse_dt, path_slug_ok NAME = "workable" LABEL = "Workable" RANK = 40 PATTERNS = ( r"apply\.workable\.com/(?:api/v\d/accounts/)?([A-Za-z0-9_-]+)", r"https?://(?!apply\.|www\.)([a-z0-9-]+)\.workable\.com", ) READS = Reads( scope="board", listing="paged", page_size=10, text="detail", complete="stated", places="many", fields=Fields(posted="trusted", remote="stated", employment="stated"), robots=("read: apply.workable.com's robots.txt disallows nothing (an empty Disallow), so " "POST /api/v3/accounts//jobs and /api/v2/accounts//jobs/ " "are allowed (checked 2026-09-30)"), ) _API = "apply.workable.com" # No probe: Workable's API sits behind a rate limit that a run of guesses # trips, and a Workable site links its board plainly anyway. def slug_ok(slug: str) -> bool: return path_slug_ok(slug) def allowed(slug: str) -> Callable[[str], bool]: return only(_API) def careers_url(slug: str) -> str: return f"https://{_API}/{slug}" def page(get: Get, slug: str, cursor: Any, ask: Ask = Ask()) -> Page: """One POST of the list; the next page is the same POST with `{"token": nextPage}`, and the last page has no `nextPage`.""" url = f"https://{_API}/api/v3/accounts/{slug}/jobs" data = json.loads(get(url, method="POST", payload={"token": cursor} if cursor else {})) return data, data.get("results") or [], data.get("total"), data.get("nextPage") or None def parse(body: bytes, slug: str) -> list[Row]: return rows(json.loads(body), slug) def _places(job: dict[str, Any], remote: bool) -> list[Place]: """Every place of a role. `locations` lists them (city, region, country; `hidden` ones are stated too), and `location` is the first alone, the fallback for a role that lists none. A place is remote when the role is.""" found: list[Place] = [] listed = [loc for loc in job.get("locations") or [] if isinstance(loc, dict)] for loc in listed or [job.get("location") or {}]: parts: list[str] = [] for part in (loc.get("city"), loc.get("region"), loc.get("country")): part = str(part or "").strip() if part and part not in parts: parts.append(part) text = ", ".join(parts) add_place(found, {"text": text, "remote": remote}) return found def rows(data: dict[str, Any], slug: str) -> list[Row]: """One page of POST https://apply.workable.com/api/v3/accounts/{slug}/jobs -> `{"total": int, "results": [...], "nextPage": token}`, as Hugging Face's board answered on 2026-09-28. A result carries no URL and no text: the job page is `https://apply.workable.com/{slug}/j/{shortcode}/`, and the description is only on the per-job endpoint, which `detail` reads, so `description` stays empty here. The `shortcode` is kept in the row for it. `location` is the first place and `locations` all of them; `department` is a list; `remote` is a flag beside `workplace` (remote, hybrid, on_site); `type` is the hours or the contract (full, part, ...).""" out = [] for j in data.get("results") or []: title = (j.get("title") or "").strip() shortcode = (j.get("shortcode") or "").strip() if not title or not shortcode: continue workplace = str(j.get("workplace") or "").strip() remote = bool(j.get("remote")) or workplace == "remote" places = _places(j, remote) dept = j.get("department") or "" if isinstance(dept, list): dept = ", ".join(d for d in dept if d) out.append({ "source_id": str(j.get("id") or shortcode), "shortcode": shortcode, "title": title, "places": places, "location": "; ".join(p["text"] for p in places), "url": f"https://{_API}/{slug}/j/{shortcode}/", "posted": parse_dt(j.get("published")), "department": dept.strip(), "description": "", "remote": workplace or j.get("remote"), "salary_text": "", # Workable's list endpoint states no pay at all "employment": str(j.get("type") or "").strip() or None, }) return out #: The parts of a role's ad that make its description, in reading order. _PARTS = ("description", "requirements", "benefits") def detail(get: Get, slug: str, row: Row) -> dict[str, Any]: """`/api/v2/accounts/{slug}/jobs/{shortcode}` -> the HTML of `description`, `requirements` and `benefits`, joined as one text. An answer with none of the three keys is not a role and raises, so the role is asked again on a later pull.""" shortcode = str(row.get("shortcode") or "") if not path_slug_ok(shortcode): raise ValueError(f"no Workable shortcode in the row: {shortcode!r}") data = json.loads(get(f"https://{_API}/api/v2/accounts/{slug}/jobs/{shortcode}")) if not isinstance(data, dict) or not any(k in data for k in _PARTS): raise ValueError("not a Workable role: no description") parts = [] for key in _PARTS: text = " ".join(html.unescape(strip_html(str(data.get(key) or ""))).split()) if text: parts.append(text) return {"description": " ".join(parts)}