ctfy.sdk.resources.submissions

  1"""``client.submissions`` — graded submit, oracle verify, QA challenges."""
  2
  3from __future__ import annotations
  4
  5import builtins
  6from typing import Any
  7
  8from ctfy.core.state.models import SubmissionState
  9from ctfy.sdk._helpers import _extract_items, _raise_for_status
 10from ctfy.sdk.base import BaseHttpClient
 11from ctfy.server.models import QaChallengeView, SubmissionResponse, VerifyAnswerResponse
 12
 13
 14class SubmissionsResource:
 15    """Answer submission (graded), oracle verification (no record), and QA."""
 16
 17    def __init__(self, http: BaseHttpClient) -> None:
 18        self._http = http
 19
 20    def submit(
 21        self,
 22        instance_id: str,
 23        answer: str | builtins.list[str],
 24        *,
 25        question_id: str = "flag",
 26    ) -> SubmissionResponse:
 27        """Submit ``answer`` against ``question_id`` on ``instance_id``.
 28
 29        The server reads challenge_id, team_id and competition_id off
 30        the instance row; the calling user must be on the same team
 31        that started this instance (in the same competition).
 32
 33        ``question_id`` defaults to ``"flag"`` for single-question
 34        challenges (the most common case). Multi-question challenges
 35        (see :class:`ChallengeInfo.questions`) require an explicit id.
 36        ``answer`` is a single string for dynamic / static /
 37        single_select questions and a list of strings for multi_select.
 38        """
 39        resp = self._http.request(
 40            "POST",
 41            "/submissions",
 42            json={
 43                "instance_id": instance_id,
 44                "question_id": question_id,
 45                "answer": answer,
 46            },
 47        )
 48        _raise_for_status(resp)
 49        return SubmissionResponse.model_validate(resp.json())
 50
 51    def verify(
 52        self,
 53        instance_id: str,
 54        answer: str | builtins.list[str],
 55        *,
 56        question_id: str = "flag",
 57    ) -> VerifyAnswerResponse:
 58        """Server-side answer verification — no submission record.
 59
 60        Same grader as :meth:`submit` (mode-aware,
 61        ``$ANSWER_<UPPER_ID>`` tolerance for dynamic, set-equal for
 62        ``multi_select``, etc.) but writes nothing to the audit log.
 63        Use for oracle-style probes; for graded competitions use
 64        :meth:`submit`.
 65
 66        Returns :class:`VerifyAnswerResponse` with ``.correct`` and
 67        ``.question_id`` (the latter echoed on a correct match).
 68        """
 69        resp = self._http.request(
 70            "POST",
 71            f"/instances/{instance_id}/verify-answer",
 72            json={"question_id": question_id, "answer": answer},
 73        )
 74        _raise_for_status(resp)
 75        return VerifyAnswerResponse.model_validate(resp.json())
 76
 77    def list(
 78        self, challenge_id: str = "", offset: int = 0, limit: int = 50
 79    ) -> builtins.list[SubmissionState]:
 80        """List current team's submissions."""
 81        params: dict[str, Any] = {"offset": offset, "limit": limit}
 82        if challenge_id:
 83            params["challenge_id"] = challenge_id
 84        resp = self._http.request("GET", "/submissions", params=params)
 85        _raise_for_status(resp)
 86        return _extract_items(resp.json(), SubmissionState)
 87
 88    def submit_qa(
 89        self,
 90        challenge_id: str,
 91        competition_id: str,
 92        answer: str | builtins.list[str],
 93        *,
 94        question_id: str = "answer",
 95    ) -> SubmissionResponse:
 96        """Submit ``answer`` against a pure question-answer challenge.
 97
 98        Unlike :meth:`submit`, QA challenges have no instance — the
 99        caller passes ``challenge_id`` + ``competition_id`` explicitly,
100        and the server resolves the team for the competition via the
101        standard auth helper. ``question_id`` defaults to ``"answer"``
102        (the canonical id for MCQ items produced by ``ctfy-admin
103        challenge import``).
104        """
105        resp = self._http.request(
106            "POST",
107            "/qa/submissions",
108            json={
109                "challenge_id": challenge_id,
110                "competition_id": competition_id,
111                "question_id": question_id,
112                "answer": answer,
113            },
114        )
115        _raise_for_status(resp)
116        return SubmissionResponse.model_validate(resp.json())
117
118    def list_qa_challenges(self, competition_id: str) -> builtins.list[QaChallengeView]:
119        """All QA challenges in scope of one competition + team status.
120
121        Returns one :class:`QaChallengeView` per challenge with the
122        calling team's per-question solve / wrong-attempt state
123        pre-joined. The quiz UI renders the full surface from this
124        single response.
125        """
126        resp = self._http.request(
127            "GET", "/qa/challenges", params={"competition_id": competition_id}
128        )
129        _raise_for_status(resp)
130        data = resp.json()
131        return [QaChallengeView.model_validate(item) for item in data]