The Roles tab is news's feed row: the title opens /roles/{uid}, company,
place and age under it, the badges, a one-line excerpt (summary, else the
description's opening), and ▲ ● ▼ ★ on the right, under the text at 640px.
The company affinity control leaves the row. A passed role and a hidden
company's are dimmed and stay. The filter bar is one row: order, search and
a Filters <details> holding the rest, with a judged select and "Show hidden
companies". The list loads 60 and appends on an IntersectionObserver
sentinel; back from a read page restores the filters, rows and scroll.
GET /api/roles takes offset, defaults to 60 and answers {items, total}.
judged= is a WHERE on roles.vote. Under a ranking the served score and the
order are the stored score moved by the vote (x0.5 pass, x1.2 like, capped
at 1), so a vote shows at once without a rescore. POST and DELETE
/api/roles/{uid}/vote set and clear it; pressing the pressed stance clears.
★ saves; pressed again it calls DELETE /api/applications/{id}, which drops
the application while it is still saved and answers 409 after. save_role no
longer writes the placeholder next step.
The read page (role.html, role.js) is news's reader: a bar with back,
▲ ● ▼ ★ and ↗, the company with its affinity control, place, badges, salary,
summary, the text (fetched posting, else description) and the link out.
It offers Fetch the posting for a teaser and Summarise without a summary,
against the /text and /summarise routes B4 adds. The vote and star buttons
are judge.js, shared by the feed and the reader.
Applications: titles open the read page, the Next column is gone, a Saved
column instead, and the lede says what the page is for.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
394 lines
14 KiB
Python
394 lines
14 KiB
Python
"""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": "<sentence>"}`, 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,
|
|
)
|
|
from app.storage import Store
|
|
from app.web.deps import ConfigDep, StoreDep
|
|
|
|
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))
|
|
|
|
|
|
# --------------------------------------------------------------- companies
|
|
|
|
class CompanyOut(BaseModel):
|
|
"""A company row plus the two things only the store can join in: the ats
|
|
host it is read from, and how many of its roles are still open."""
|
|
|
|
key: str
|
|
name: str
|
|
board: str
|
|
affinity: int
|
|
open_roles: int
|
|
|
|
|
|
@router.get("/companies")
|
|
def list_companies(store: StoreDep) -> list[CompanyOut]:
|
|
boards = store.company_boards()
|
|
counts = store.open_role_counts()
|
|
return [CompanyOut(key=c.key, name=c.name, board=boards.get(c.key, ""),
|
|
affinity=c.affinity, open_roles=counts.get(c.key, 0))
|
|
for c in store.companies()]
|
|
|
|
|
|
class AffinityBody(BaseModel):
|
|
affinity: int
|
|
|
|
|
|
@router.post("/companies/{key}/affinity")
|
|
def set_affinity(key: str, body: AffinityBody, store: StoreDep) -> Company:
|
|
if body.affinity not in AFFINITY:
|
|
raise HTTPException(422, "affinity is -1, 0, 1 or 2")
|
|
try:
|
|
return store.update_company(key, affinity=body.affinity)
|
|
except KeyError:
|
|
raise HTTPException(404, f"no such company: {key}") from None
|
|
|
|
|
|
# ----------------------------------------------------------------- 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)
|