"""The JSON routes the tabs use: roles, companies, sources, applications, agents. `/api/jobs*`, `/api/schedules*`, `/api/notices` and `/ws/jobs` are `pipeline.web`'s and `/api/account*` is `auth`'s, both wired in `app/main.py`. This is roledesk's own API, over the same store. Every refusal is `{"detail": ""}`, which `api()` in `static/app.js` turns into a toast. """ from __future__ import annotations from typing import Annotated, Any, Literal from fastapi import APIRouter, HTTPException, Query, Response from pydantic import BaseModel, Field from app import jobs from app.models import ( AFFINITY, Agent, Application, Company, Gate, Role, ScoredRole, Status, Subscription, Weights, company_key, ) from app.storage import Store from app.web.deps import ConfigDep, StoreDep from desk.tools import agent, scrape from pipeline import Job from pipeline.web import QueueDep router = APIRouter(prefix="/api", tags=["roledesk"]) # ------------------------------------------------------------------- roles class VoteBody(BaseModel): value: Literal[-1, 0, 1] @router.get("/roles/{uid}") def get_role(uid: str, store: StoreDep) -> Role: """One role, open or closed, for the read page.""" role = store.role(uid) if role is None: raise HTTPException(404, f"no such role: {uid}") return role @router.post("/roles/{uid}/vote") def vote_role(uid: str, body: VoteBody, store: StoreDep) -> Role: """1 like, 0 neither way, -1 pass. The role stays listed either way; the vote moves it in a ranking, see `Store.roles`.""" try: return store.set_vote(uid, body.value) except KeyError: raise HTTPException(404, f"no such role: {uid}") from None @router.delete("/roles/{uid}/vote") def unvote_role(uid: str, store: StoreDep) -> Role: """Unjudged again: what pressing the stance a role already has does.""" try: return store.set_vote(uid, None) except KeyError: raise HTTPException(404, f"no such role: {uid}") from None class RolesPage(BaseModel): """One page of roles, and how many the same filters match in all.""" items: list[ScoredRole] total: int @router.get("/roles") def list_roles( store: StoreDep, q: str = "", company: str = "", place: str = "", function: str = "", remote: str = "", days: int | None = None, show_muted: bool = False, agent: int | None = None, gated: bool = False, judged: Literal["", "liked", "unjudged", "passed"] = "", offset: Annotated[int, Query(ge=0)] = 0, limit: Annotated[int, Query(ge=1, le=1000)] = 60, ) -> RolesPage: """Open roles, newest first, `limit` of them from `offset`, with the total. See `Store.roles` for what each filter does. A muted company's roles are left out unless `show_muted` is set. With `agent`, ordered by that agent's score moved by the role's vote, and carrying `score` and `gated_reason`; a gated role only with `gated=1`. `judged` keeps the liked, the unjudged or the passed.""" if agent is not None and store.agent(agent) is None: raise HTTPException(404, f"no such agent: {agent}") filters: dict[str, Any] = { "q": q or None, "company": company or None, "place": place or None, "function": function or None, "remote": remote or None, "days": days, "hide_muted": not show_muted, "agent": agent, "gated": gated, "judged": judged or None} return RolesPage(items=store.roles(limit=limit, offset=offset, **filters), total=store.count_roles(**filters)) # ------------------------------------------------- roles: text and summary #: What the read page toasts when a posting page gave nothing readable, by #: `desk.tools.failures` category. _UNREADABLE = { "timeout": "The posting page took too long to answer. Try again in a minute.", "unreachable": "The posting page could not be reached.", "rate_limited": "The posting site is refusing requests for now. Try again later.", "server_error": "The posting site answered with an error. Try again later.", "not_found": "The posting page is gone, so the role has probably closed.", "denied": "The posting site refused to show the page.", "consent_wall": "The posting page showed a consent banner instead of the posting.", "js_required": "The posting page only renders in a browser. Open it with the link instead.", "empty": "The posting page had no readable text on it.", } def _known_role(store: Store, uid: str) -> Role: role = store.role(uid) if role is None: raise HTTPException(404, f"no such role: {uid}") return role @router.post("/roles/{uid}/text") def fetch_text(uid: str, store: StoreDep) -> Role: """Fetch the posting page once and keep it as plain text, for a role whose description is a teaser. Synchronous: one request the person asked for, and on demand rather than in the pull because each fetch of a Jobindex redirect counts as a click in its statistics.""" role = _known_role(store, uid) if role.article_text: raise HTTPException(409, "The posting text is already fetched.") if not role.original_url: raise HTTPException(422, "This role has no link to fetch the posting from.") got = scrape.scrape(role.original_url) text = got.content.plain_text.strip() if got.content is not None else "" if not text: raise HTTPException(422, _UNREADABLE.get( got.failure, "Nothing readable came back from the posting page.")) updated = store.set_article_text(uid, text) if updated is None: raise HTTPException(404, f"no such role: {uid}") return updated @router.post("/roles/{uid}/summarise", status_code=202) def summarise_role(uid: str, store: StoreDep, config: ConfigDep, queue: QueueDep) -> Job: """Queue a summary of one role, whatever its rank and whether or not the pull summarises (`summarise.enabled`). The job's batch is this uid alone. Pressed twice, the second press gets the first one's job.""" role = _known_role(store, uid) if role.summary: raise HTTPException(409, "This role already has a summary.") if not (role.article_text.strip() or role.description.strip()): raise HTTPException(422, "This role has no text to summarise. Fetch the posting first.") if not agent.backend(config.agent): raise HTTPException(422, "No model is reachable from here, so nothing can " "write a summary. Set up the API key or Claude Code.") job = queue.enqueue(f"{jobs.summarise.TASK.kind}_batch", {"uids": [uid]}, label=f"Summarising {role.title or uid}", dedup_key=f"summarise:{uid}") if job is None: raise HTTPException(409, "The summary would not start.") return job # --------------------------------------------------------------- companies class CompanyOut(BaseModel): """A company row plus what only the store can join in: the ats host it is read from (empty for a company known only from a search), the id of that board's subscription, whether it is on, and how many of its roles are still open.""" key: str name: str board: str subscription_id: int | None = None on: bool | None = None affinity: int open_roles: int def _company_boards(store: Store) -> dict[str, tuple[int, str, bool]]: """`company_key -> (subscription id, ats host, on)`, read off each company's own subscription. Same join as `Store.company_boards`, with the id and switch state a company row needs to draw its own on/off control rather than fetching `/api/sources` as well.""" boards: dict[str, tuple[int, str, bool]] = {} for sub in store.subscriptions(source="ats"): boards.setdefault(company_key(sub.company), (sub.id, sub.board, bool(sub.subscribed and sub.fetch))) return boards @router.get("/companies") def list_companies(store: StoreDep) -> list[CompanyOut]: boards = _company_boards(store) counts = store.open_role_counts() out = [] for c in store.companies(): sub_id, host, on = boards.get(c.key, (None, "", None)) out.append(CompanyOut(key=c.key, name=c.name, board=host, subscription_id=sub_id, on=on, affinity=c.affinity, open_roles=counts.get(c.key, 0))) return out class AffinityBody(BaseModel): affinity: int @router.post("/companies/{key}/affinity") def set_affinity(key: str, body: AffinityBody, store: StoreDep, queue: QueueDep) -> Company: """A change here is not seen in Best match until `score` has run: the queue dedupes to a live job of that kind, so several clicks are one run.""" if body.affinity not in AFFINITY: raise HTTPException(422, "affinity is -1, 0, 1 or 2") try: company = store.update_company(key, affinity=body.affinity) except KeyError: raise HTTPException(404, f"no such company: {key}") from None queue.enqueue("score") return company # ----------------------------------------------------------------- sources class SourceOut(BaseModel): """A board or a saved search, with what it brings in: its open roles, and the countries they are in, most first.""" id: int source: str target: str label: str provider: str params: dict[str, Any] on: bool open_roles: int countries: list[tuple[str, int]] class SourcesOut(BaseModel): searches: list[SourceOut] boards: list[SourceOut] #: Whether an adzuna search can run: a key in the config or the environment. adzuna_key: bool def _source_out(sub: Subscription, countries: dict[str, int]) -> SourceOut: return SourceOut( id=sub.id, source=sub.source, target=sub.target, label=sub.label, provider=sub.board, params=sub.params, on=bool(sub.subscribed and sub.fetch), open_roles=sum(countries.values()), countries=sorted(countries.items(), key=lambda kv: -kv[1])) def _one_source(store: Store, sub_id: int) -> SourceOut: sub = store.subscription(sub_id) if sub is None: raise HTTPException(404, f"no such board or search: {sub_id}") return _source_out(sub, store.open_countries_by_subscription().get(sub_id, {})) @router.get("/sources") def list_sources(store: StoreDep, config: ConfigDep) -> SourcesOut: """Every board, and every search not removed. A board switched off stays listed, so it can be switched back on.""" counts = store.open_countries_by_subscription() searches = [_source_out(s, counts.get(s.id, {})) for s in store.subscriptions(source="search") if s.show] boards = [_source_out(s, counts.get(s.id, {})) for s in store.subscriptions(source="ats")] return SourcesOut(searches=searches, boards=boards, adzuna_key=jobs.sources.has_key(config, "adzuna")) class SwitchBody(BaseModel): on: bool @router.post("/sources/{sub_id}/switch") def switch_source(sub_id: int, body: SwitchBody, store: StoreDep) -> dict[str, Any]: """On or off for the next pull. Off closes the open roles at once; on reopens the ones the next pull still finds.""" if store.subscription(sub_id) is None: raise HTTPException(404, f"no such board or search: {sub_id}") _, closed = jobs.sources.set_fetch(store, sub_id, body.on) return {"source": _one_source(store, sub_id), "closed": closed} class SearchBody(BaseModel): provider: str name: str = "" q: str = "" area: int = 0 country: str = "" where: str = "" pages: Annotated[int, Field(ge=0, le=10)] = 0 def _params(body: SearchBody) -> dict[str, Any]: try: return jobs.sources.search_params(body.provider, body.q, area=body.area, country=body.country, where=body.where, pages=body.pages) except ValueError as exc: raise HTTPException(422, str(exc)) from exc @router.post("/searches/try") def try_search(body: SearchBody, config: ConfigDep) -> dict[str, Any]: """Run a search once without saving it: how many it finds, whether that is every match, and the first ten, so a query can be tuned before it is kept.""" try: rows, complete = jobs.sources.try_search(config, body.provider, body.name, _params(body)) except ValueError as exc: raise HTTPException(422, str(exc)) from exc sample = [{k: r.get(k) for k in ("title", "company", "place", "url")} for r in rows[:10]] return {"found": len(rows), "complete": complete, "sample": sample} @router.post("/searches") def save_search(body: SearchBody, store: StoreDep, config: ConfigDep) -> dict[str, Any]: """Save a search, or update the one of that provider and name. It is run once first and refused if it finds nothing.""" try: sub, found, complete = jobs.sources.save_search(config, store, body.provider, body.name, _params(body)) except ValueError as exc: raise HTTPException(422, str(exc)) from exc return {"source": _one_source(store, sub.id), "found": found, "complete": complete} @router.delete("/searches/{sub_id}") def remove_search(sub_id: int, store: StoreDep) -> dict[str, Any]: try: _, closed = jobs.sources.remove_search(store, sub_id) except KeyError: raise HTTPException(404, f"no such search: {sub_id}") from None return {"closed": closed} class BoardBody(BaseModel): board: str name: str @router.post("/boards", status_code=201) def add_board(body: BoardBody, store: StoreDep) -> dict[str, Any]: """Follow a company's ATS board. It is fetched first, and refused if it does not answer or lists nothing.""" try: sub, found = jobs.sources.add_board(store, body.board, body.name) except ValueError as exc: raise HTTPException(422, str(exc)) from exc return {"source": _one_source(store, sub.id), "found": found} @router.get("/prune") def prune_preview(store: StoreDep, region: str = "europe") -> dict[str, Any]: """The boards a prune would switch off: every one on, none of whose open roles is in the region.""" try: _, plan = jobs.sources.prune_plan(store, region) except ValueError as exc: raise HTTPException(422, str(exc)) from exc return {"region": region, "boards": [{"id": sub.id, "label": sub.label, "target": sub.target, "open_roles": n} for sub, n in plan]} class PruneBody(BaseModel): region: str = "europe" @router.post("/prune") def prune(body: PruneBody, store: StoreDep) -> dict[str, Any]: try: return jobs.sources.prune(store, body.region) except ValueError as exc: raise HTTPException(422, str(exc)) from exc # ----------------------------------------------------------- applications class SaveBody(BaseModel): role_uid: str status: Status = "saved" @router.post("/applications", status_code=201) def save_role(body: SaveBody, store: StoreDep) -> Application: """Track one role: the ★ on a role. Pressing it twice does not double-track it: the existing row comes back rather than a second one starting at `saved` over whatever status it has since moved to.""" existing = next((a for a in store.applications() if a.role_uid == body.role_uid), None) if existing is not None: return existing role = store.role(body.role_uid) if role is None: raise HTTPException(404, f"no such role: {body.role_uid}") application = Application( role_uid=role.uid, company_key=role.company_key, role_title=role.title, url=role.original_url, status=body.status, source=role.source) return store.save_application(application) @router.delete("/applications/{app_id}", status_code=204) def unsave_role(app_id: str, store: StoreDep) -> Response: """The ★ pressed again. Only while the application is still `saved`: once it has moved on, it is history, and withdrawn is the status for that.""" application = store.application(app_id) if application is None: raise HTTPException(404, f"no such application: {app_id}") if application.status != "saved": raise HTTPException(409, f"This application is at {application.status} already, " "so it stays. Set it to withdrawn instead.") store.delete_application(app_id) return Response(status_code=204) @router.get("/applications") def list_applications(store: StoreDep) -> list[Application]: """Every tracked application, with the role title and company key it was saved with — enough for the page to list them without a join; the company's full name comes from `/api/companies`, already on the page.""" return store.applications() class StatusBody(BaseModel): status: Status @router.post("/applications/{app_id}/status") def set_status(app_id: str, body: StatusBody, store: StoreDep) -> Application: try: return store.set_application_status(app_id, body.status) except ValueError as exc: raise HTTPException(422, str(exc)) from exc except KeyError: raise HTTPException(404, f"no such application: {app_id}") from None # ------------------------------------------------------------------ agents @router.get("/agents") def list_agents(store: StoreDep) -> list[Agent]: return store.agents() class AgentBody(BaseModel): """Create when `id` is missing, replace that agent's fields when given.""" id: int | None = None name: str = Field(min_length=1) intent: str = "" gates: list[Gate] = [] weights: Weights = Weights() enabled: bool = True @router.post("/agents") def save_agent(body: AgentBody, store: StoreDep) -> Agent: """Scores are not recomputed here: that is the `score` task, which the page starts after a save.""" try: return store.save_agent(body.name, body.intent, body.gates, body.weights, body.enabled, agent_id=body.id) except ValueError as exc: raise HTTPException(409, str(exc)) from exc except KeyError: raise HTTPException(404, f"no such agent: {body.id}") from None @router.delete("/agents/{agent_id}", status_code=204) def delete_agent(agent_id: int, store: StoreDep) -> Response: if not store.delete_agent(agent_id): raise HTTPException(404, f"no such agent: {agent_id}") return Response(status_code=204)