ctfy.sdk.admin_resources.teams

  1"""``client.admin.teams`` — the organiser's write surface on a squad.
  2
  3Distinct from ``client.admin.registrations``, which is the *eligibility*
  4view: roster, verdict, export. This is enforcement — deciding a team is
  5out of the event, and putting them back.
  6
  7The two look adjacent and are not substitutes. A review verdict decides
  8prizes and never blocks play; a disqualification blocks every progress
  9path and removes the team from the ranking. A team can be approved and
 10disqualified at once, which is the ordinary shape of "clean at sign-up,
 11caught on day two".
 12
 13Gated server-side on ``require_competition_admin`` — a reviewer's grant
 14rules on eligibility, and removing a team from a running event is a
 15heavier decision than the role was cut for.
 16"""
 17
 18from __future__ import annotations
 19
 20import builtins
 21
 22from ctfy.sdk._helpers import _raise_for_status
 23from ctfy.sdk.base import BaseHttpClient
 24from ctfy.server.models import AdminTeamRow, TeamDetail, TeamStandingInfo
 25
 26
 27class AdminTeamsResource:
 28    def __init__(self, http: BaseHttpClient) -> None:
 29        self._http = http
 30
 31    def list(self, competition_id: str) -> builtins.list[AdminTeamRow]:
 32        """Every team in one competition, with its standing.
 33
 34        Deliberately not the review roster: that decrypts every member's
 35        personal details and lands an audit row for the bulk read.
 36        Managing a roster needs names and membership, not phone numbers.
 37        """
 38        resp = self._http.request("GET", f"/admin/competitions/{competition_id}/teams")
 39        _raise_for_status(resp)
 40        return [AdminTeamRow.model_validate(row) for row in resp.json()]
 41
 42    def rename(
 43        self, competition_id: str, team_id: str, *, name: str = "", description: str = ""
 44    ) -> TeamDetail:
 45        """Rename or re-describe a team on the organiser's authority.
 46
 47        For the team whose captain is unreachable, and for the name an
 48        organiser has to change without asking. Empty strings are sent
 49        as-is; omit a field to leave it alone.
 50        """
 51        body: dict[str, str] = {}
 52        if name:
 53            body["name"] = name
 54        if description:
 55            body["description"] = description
 56        resp = self._http.request(
 57            "PATCH", f"/admin/competitions/{competition_id}/teams/{team_id}", json=body
 58        )
 59        _raise_for_status(resp)
 60        return TeamDetail.model_validate(resp.json())
 61
 62    def set_captain(self, competition_id: str, team_id: str, *, user_id: str) -> TeamDetail:
 63        """Hand a team to a different one of its members.
 64
 65        The reason this resource exists. Every write a team makes about
 66        itself is captain-only, so a captain who withdraws or loses their
 67        account strands the whole squad — and the platform's only other
 68        transfer happens when a captain leaves *voluntarily*, which is
 69        exactly the case that does not apply. The target must already be
 70        on the team.
 71        """
 72        resp = self._http.request(
 73            "POST",
 74            f"/admin/competitions/{competition_id}/teams/{team_id}/captain",
 75            json={"user_id": user_id},
 76        )
 77        _raise_for_status(resp)
 78        return TeamDetail.model_validate(resp.json())
 79
 80    def remove_member(self, competition_id: str, team_id: str, user_id: str) -> TeamDetail:
 81        """Drop a member from a team.
 82
 83        Goes through the same atomic op as the captain's kick, so the
 84        behaviour is identical: the member holds **no** membership for
 85        this competition afterwards — they are out of the event, not
 86        moved to another team — and a team losing its last member is
 87        collected. Removing every member is therefore also how a team is
 88        dissolved. They re-enter through the normal Solo / Create / Join
 89        wizard while registration is open.
 90        """
 91        resp = self._http.request(
 92            "DELETE",
 93            f"/admin/competitions/{competition_id}/teams/{team_id}/members/{user_id}",
 94        )
 95        _raise_for_status(resp)
 96        return TeamDetail.model_validate(resp.json())
 97
 98    def disqualify(self, competition_id: str, team_id: str, *, reason: str) -> TeamStandingInfo:
 99        """Remove a team from the event.
100
101        ``reason`` is mandatory and must be at least 10 characters: it is
102        shown to the team when their next submission is refused, and it
103        is the record an appeal is argued from. Idempotent — calling it
104        again re-stamps the reason rather than failing.
105        """
106        resp = self._http.request(
107            "POST",
108            f"/admin/competitions/{competition_id}/teams/{team_id}/disqualify",
109            json={"reason": reason},
110        )
111        _raise_for_status(resp)
112        return TeamStandingInfo.model_validate(resp.json())
113
114    def reinstate(self, competition_id: str, team_id: str) -> TeamStandingInfo:
115        """Put a team back in the event.
116
117        The original reason is deliberately kept: a successful appeal
118        should not erase the record of the ruling it overturned. Only the
119        timestamp decides standing. A no-op on a team that is already in.
120        """
121        resp = self._http.request(
122            "DELETE",
123            f"/admin/competitions/{competition_id}/teams/{team_id}/disqualify",
124        )
125        _raise_for_status(resp)
126        return TeamStandingInfo.model_validate(resp.json())