ctfy.sdk.competition.team

  1"""``client.competition(id).team`` — my team within one competition.
  2
  3Captain + member management for the caller's team in a single competition:
  4rename / leave / kick, plus the outgoing invite codes (``team.invites``) and
  5the incoming join-request queue (``team.requests``).
  6"""
  7
  8from __future__ import annotations
  9
 10from functools import cached_property
 11
 12from ctfy.sdk._helpers import PagedList, _extract_items, _raise_for_status
 13from ctfy.sdk.base import BaseHttpClient
 14from ctfy.server.models import TeamAffiliationSelection, TeamDetail, TeamInviteInfo
 15
 16
 17class CompetitionTeam:
 18    """The caller's team in this competition."""
 19
 20    def __init__(self, http: BaseHttpClient, competition_id: str) -> None:
 21        self._http = http
 22        self._cid = competition_id
 23
 24    def rename(self, *, name: str | None = None, description: str | None = None) -> TeamDetail:
 25        """Captain-only: rename / re-describe the team."""
 26        body: dict[str, str] = {}
 27        if name is not None:
 28            body["name"] = name
 29        if description is not None:
 30            body["description"] = description
 31        resp = self._http.request("PATCH", f"/competitions/{self._cid}/team", json=body)
 32        _raise_for_status(resp)
 33        return TeamDetail.model_validate(resp.json())
 34
 35    def affiliation(self) -> TeamAffiliationSelection:
 36        """Captain-only: the squad's institution badge and its options.
 37
 38        Three facts in one answer — what the captain chose, what it
 39        resolves to *now*, and every institution a current member
 40        publishes. The middle one can be ``None`` while the first is
 41        set: that is a choice whose backing has gone, and it reads
 42        differently from having chosen nothing.
 43        """
 44        resp = self._http.request("GET", f"/competitions/{self._cid}/team/affiliation")
 45        _raise_for_status(resp)
 46        return TeamAffiliationSelection.model_validate(resp.json())
 47
 48    def set_affiliation(self, domain: str) -> TeamAffiliationSelection:
 49        """Captain-only: publish ``domain`` beside the squad's name.
 50
 51        Refused (``409 affiliation_not_published``) unless a current
 52        member already publishes that institution on their own profile —
 53        a team cannot claim one nobody on it has shown.
 54        """
 55        resp = self._http.request(
 56            "PUT", f"/competitions/{self._cid}/team/affiliation", json={"domain": domain}
 57        )
 58        _raise_for_status(resp)
 59        return TeamAffiliationSelection.model_validate(resp.json())
 60
 61    def clear_affiliation(self) -> TeamAffiliationSelection:
 62        """Captain-only: stop publishing a badge. Never refused, and
 63        takes no domain — so it also escapes the state where the choice
 64        outlived the member who backed it."""
 65        resp = self._http.request("DELETE", f"/competitions/{self._cid}/team/affiliation")
 66        _raise_for_status(resp)
 67        return TeamAffiliationSelection.model_validate(resp.json())
 68
 69    def leave(self) -> None:
 70        """Drop your membership for this competition. If captain and others
 71        remain, captaincy transfers to the longest-tenured member; if you
 72        were the lone member the team is deleted."""
 73        resp = self._http.request("POST", f"/competitions/{self._cid}/team/leave")
 74        _raise_for_status(resp)
 75
 76    def kick(self, user_id: str) -> None:
 77        """Captain-only: remove ``user_id`` from the team. Self-kick is
 78        rejected (use :meth:`leave` instead)."""
 79        resp = self._http.request("DELETE", f"/competitions/{self._cid}/team/members/{user_id}")
 80        _raise_for_status(resp)
 81
 82    @cached_property
 83    def invites(self) -> CompetitionInvites:
 84        """Invite codes + direct email invites the captain hands out."""
 85        return CompetitionInvites(self._http, self._cid)
 86
 87    @cached_property
 88    def requests(self) -> CompetitionRequests:
 89        """Pending join requests the captain approves / rejects."""
 90        return CompetitionRequests(self._http, self._cid)
 91
 92
 93class CompetitionInvites:
 94    """Captain-only: the team's outgoing invites for this competition."""
 95
 96    def __init__(self, http: BaseHttpClient, competition_id: str) -> None:
 97        self._http = http
 98        self._cid = competition_id
 99
100    def create(self, *, max_uses: int = 1, ttl_seconds: int = 24 * 3600) -> TeamInviteInfo:
101        """Mint an invite code scoped to this comp. ``max_uses=0`` is
102        unlimited; ``ttl_seconds=0`` never expires. Others redeem it via
103        ``client.competition(id).register(mode="join", code=…)``."""
104        resp = self._http.request(
105            "POST",
106            f"/competitions/{self._cid}/invites",
107            json={"max_uses": max_uses, "ttl_seconds": ttl_seconds},
108        )
109        _raise_for_status(resp)
110        return TeamInviteInfo.model_validate(resp.json())
111
112    def list(self) -> PagedList[TeamInviteInfo]:
113        """All outstanding invites for the caller's team in this comp."""
114        resp = self._http.request("GET", f"/competitions/{self._cid}/invites")
115        _raise_for_status(resp)
116        return _extract_items(resp.json(), TeamInviteInfo)
117
118    def revoke(self, invite_id: str) -> None:
119        """Invalidate a previously-minted invite."""
120        resp = self._http.request("DELETE", f"/competitions/{self._cid}/invites/{invite_id}")
121        _raise_for_status(resp)
122
123    def send(self, email: str) -> TeamInviteInfo:
124        """Mint an invite addressed to one exact email. The lookup is
125        case-insensitive but otherwise unforgiving (no fuzzy match, no
126        enumeration vectors). The recipient accepts via
127        :meth:`Competition.accept_invite`."""
128        resp = self._http.request(
129            "POST",
130            f"/competitions/{self._cid}/invites/direct",
131            json={"email": email},
132        )
133        _raise_for_status(resp)
134        return TeamInviteInfo.model_validate(resp.json())
135
136
137class CompetitionRequests:
138    """Captain-only: incoming join requests for this competition."""
139
140    def __init__(self, http: BaseHttpClient, competition_id: str) -> None:
141        self._http = http
142        self._cid = competition_id
143
144    def approve(self, invite_id: str) -> TeamDetail:
145        """Approve a pending join request → the requester joins the team."""
146        resp = self._http.request("POST", f"/competitions/{self._cid}/invites/{invite_id}/approve")
147        _raise_for_status(resp)
148        return TeamDetail.model_validate(resp.json())
149
150    def reject(self, invite_id: str) -> None:
151        """Reject a pending join request → invite revoked. The requester
152        can re-open a fresh request afterwards."""
153        resp = self._http.request("POST", f"/competitions/{self._cid}/invites/{invite_id}/reject")
154        _raise_for_status(resp)