"""Token management (participants / invite codes) via the RemoteControl API. LS7 RemoteControl methods called here (lay these next to the API docs): - ``add_participants`` — params ``[session_key, sid, [participant dicts]]`` (+ optional ``create_token`` as 4th param) - ``list_participants`` — params ``[session_key, sid, start, limit]`` (+ optional ``conditions`` and ``language`` in the following positions) - ``delete_participants`` — params ``[session_key, sid, [token_ids]]`` Each participant is a dict with e.g. ``email``, ``firstname``, ``lastname``, ``token`` (``token`` is generated by LS on add_participants). """ from __future__ import annotations from typing import Any from .errors import LsApiError from .rpc import RpcClient from .utils import normalize_sid, raise_for_status, to_int def add_participants( client: RpcClient, session_key: str, sid: int | str, participants: list[dict[str, Any]], *, create_token: bool | None = None, ) -> Any: """Add participants (tokens) to a survey. LS7 RPC method: ``add_participants`` with params ``[session_key, sid, participants]`` (+ ``create_token`` as 4th param). Args: client: an ``RpcClient``. session_key: a valid session key. sid: survey ID. participants: list of dicts, e.g. ``[{"email": "a@b.c", "firstname": "A"}]``. create_token: optional; if False, no token is created. Returns: The LS result: per participant a dict with e.g. ``tid`` and ``token``. """ if not isinstance(participants, list) or not all(isinstance(p, dict) for p in participants): raise TypeError("participants must be a list of dicts") params: list[Any] = [session_key, normalize_sid(sid), participants] if create_token is not None: params.append(bool(create_token)) result = client.call("add_participants", params) raise_for_status(result, "add_participants") return result def list_participants( client: RpcClient, session_key: str, sid: int | str, *, start: int = 0, limit: int = 100000, conditions: dict[str, Any] | None = None, language: str | None = None, ) -> list[dict[str, Any]]: """List the participants of a survey. LS7 RPC method: ``list_participants`` with params ``[session_key, sid, start, limit]`` (+ optional ``conditions``, ``language``). Returns: List of participant dicts (``tid``, ``email``, ``token``, ``completed``, ...). """ params: list[Any] = [session_key, normalize_sid(sid), int(start), int(limit)] if conditions is not None: params.append(conditions) if language is not None: params.append(language) result = client.call("list_participants", params) raise_for_status(result, "list_participants") if isinstance(result, dict) and isinstance(result.get("participants"), list): return result["participants"] if isinstance(result, list): return [p for p in result if isinstance(p, dict)] raise LsApiError( f"list_participants did not return a list: {result!r}", method="list_participants", raw=result, ) def delete_participants( client: RpcClient, session_key: str, sid: int | str, token_ids: list[int | str], ) -> Any: """Delete participants (tokens) from a survey. LS7 RPC method: ``delete_participants`` with params ``[session_key, sid, token_ids]``. Returns: The LS result: dict with a status per token id (e.g. ``{"1": "OK"}``). """ if not isinstance(token_ids, (list, tuple)): raise TypeError("token_ids must be a list of ids") coerced = [to_int(t) if to_int(t) is not None else t for t in token_ids] params: list[Any] = [session_key, normalize_sid(sid), coerced] result = client.call("delete_participants", params) raise_for_status(result, "delete_participants") return result