appsocom 0.5.0__tar.gz

appsocom-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appsotech Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

appsocom-0.5.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: appsocom
+Version: 0.5.0
+Summary: Python server SDK for Appsocom Live video calls: join tokens, rooms, moderation and webhook verification
+Author: Appsotech Limited
+License-Expression: MIT
+Project-URL: Homepage, https://live.appsocom.com
+Project-URL: Documentation, https://docs.appsocom.dev/server-sdks
+Keywords: appsocom,video,calls,webrtc,sfu,cloudflare
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Conferencing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# appsocom (Python)
+
+Python server SDK for [Appsocom Live](https://live.appsocom.com): mint join tokens, manage rooms and participants, moderate and verify webhooks. Python 3.9+, standard library only.
+
+```bash
+pip install appsocom
+```
+
+```python
+import os
+from appsocom import SfuKit, SfuKitError, verify_webhook
+
+kit = SfuKit("https://api.appsocom.dev", os.environ["APPSOCOM_API_KEY"])  # project API key from the console
+
+tok = kit.create_token("class-1", "u_7", name="Ada", role="student", metadata={"seat": 3})
+tok["token"], tok["expiresAt"]
+
+kit.set_role("class-1", "u_9", "student")             # promote an observer
+kit.mute("class-1", "*", ["mic"], lock=True)          # mute everyone, keep them muted
+kit.set_room_metadata("class-1", {"topic": "Fractions"})
+kit.set_track_permissions("class-1", "u_7", {"allowAll": False, "allow": [{"userId": "u_1"}]})
+kit.remove_participant("class-1", "u_8", ban=True)
+```
+
+Errors raise `SfuKitError` with `.status` and `.body`.
+
+Webhooks (Flask):
+
+```python
+@app.post("/appsocom-webhooks")
+def hook():
+    event = verify_webhook(os.environ["APPSOCOM_WEBHOOK_SECRET"], request.get_data(), request.headers.get("X-SfuKit-Signature"))
+    if event is None:
+        return "", 401
+    print(event["event"], event["roomId"])
+    return "", 204
+```
+
+All methods: `create_token`, `get_room`, `list_participants`, `update_room`, `set_room_metadata`, `lock_room`, `close_room`, `update_participant`, `set_permissions`, `set_role`, `set_participant_metadata`, `set_track_permissions`, `remove_participant`, `unban`, `mute`, `admit`, `post_chat`, `lower_hands`, `get_attendance`, `get_attendance_csv`, `clear_attendance`, `start_breakouts`, `end_breakouts`, `move_to_group`, `health`, `request()`. Standalone: `sign_token`, `verify_webhook`, `sign_webhook`.
+
+Self-hosting your own deployment instead? Point `url` at it and pass its admin key; the optional `jwt_secret` signs tokens locally without an HTTP call.
+
+Docs: [docs.appsocom.dev](https://docs.appsocom.dev) · License: MIT

appsocom-0.5.0/README.md

@@ -0,0 +1,43 @@
+# appsocom (Python)
+
+Python server SDK for [Appsocom Live](https://live.appsocom.com): mint join tokens, manage rooms and participants, moderate and verify webhooks. Python 3.9+, standard library only.
+
+```bash
+pip install appsocom
+```
+
+```python
+import os
+from appsocom import SfuKit, SfuKitError, verify_webhook
+
+kit = SfuKit("https://api.appsocom.dev", os.environ["APPSOCOM_API_KEY"])  # project API key from the console
+
+tok = kit.create_token("class-1", "u_7", name="Ada", role="student", metadata={"seat": 3})
+tok["token"], tok["expiresAt"]
+
+kit.set_role("class-1", "u_9", "student")             # promote an observer
+kit.mute("class-1", "*", ["mic"], lock=True)          # mute everyone, keep them muted
+kit.set_room_metadata("class-1", {"topic": "Fractions"})
+kit.set_track_permissions("class-1", "u_7", {"allowAll": False, "allow": [{"userId": "u_1"}]})
+kit.remove_participant("class-1", "u_8", ban=True)
+```
+
+Errors raise `SfuKitError` with `.status` and `.body`.
+
+Webhooks (Flask):
+
+```python
+@app.post("/appsocom-webhooks")
+def hook():
+    event = verify_webhook(os.environ["APPSOCOM_WEBHOOK_SECRET"], request.get_data(), request.headers.get("X-SfuKit-Signature"))
+    if event is None:
+        return "", 401
+    print(event["event"], event["roomId"])
+    return "", 204
+```
+
+All methods: `create_token`, `get_room`, `list_participants`, `update_room`, `set_room_metadata`, `lock_room`, `close_room`, `update_participant`, `set_permissions`, `set_role`, `set_participant_metadata`, `set_track_permissions`, `remove_participant`, `unban`, `mute`, `admit`, `post_chat`, `lower_hands`, `get_attendance`, `get_attendance_csv`, `clear_attendance`, `start_breakouts`, `end_breakouts`, `move_to_group`, `health`, `request()`. Standalone: `sign_token`, `verify_webhook`, `sign_webhook`.
+
+Self-hosting your own deployment instead? Point `url` at it and pass its admin key; the optional `jwt_secret` signs tokens locally without an HTTP call.
+
+Docs: [docs.appsocom.dev](https://docs.appsocom.dev) · License: MIT

appsocom-0.5.0/appsocom/__init__.py

@@ -0,0 +1,500 @@
+"""sfukit server SDK for Python (standard library only).
+
+    from appsocom import SfuKit, verify_webhook
+    kit = SfuKit(url=os.environ["SFUKIT_URL"], admin_key=os.environ["SFUKIT_ADMIN_API_KEY"])
+    tok = kit.create_token(room_id="class-1", user_id="u_7", name="Ada", role="student")
+    tok["token"]
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+__all__ = ["SfuKit", "SfuKitError", "sign_token", "verify_webhook", "sign_webhook", "SIGNATURE_HEADER"]
+__version__ = "0.5.0"
+
+SIGNATURE_HEADER = "X-SfuKit-Signature"
+_ID = re.compile(r"^[A-Za-z0-9._:@-]{1,128}$")
+_ROLE = re.compile(r"^[A-Za-z0-9._-]{1,32}$")
+_ROLE_DEFAULTS = {
+    "teacher": {"mic": True, "camera": True, "screen": True, "moderate": True},
+    "student": {"mic": True, "camera": True, "screen": False, "moderate": False},
+    "observer": {"mic": False, "camera": False, "screen": False, "moderate": False},
+}
+_UNSET: Any = object()
+
+
+class SfuKitError(Exception):
+    """A non-2xx answer from the kit (or a bad argument caught before calling it, status 400)."""
+
+    def __init__(self, status: int, message: str, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+def _id(value: str) -> str:
+    if not isinstance(value, str) or not _ID.match(value):
+        raise SfuKitError(400, f'invalid id "{value}" (letters, numbers, . _ : @ -, max 128)')
+    return urllib.parse.quote(value, safe="")
+
+
+def _json(value: Any) -> str:
+    # Same bytes as JavaScript's JSON.stringify (no spaces, UTF-8 kept).
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+
+
+class SfuKit:
+    """Admin client for one sfukit deployment.
+
+    url:        where the kit's Worker routes live, e.g. "https://video.client.com"
+    admin_key:  the deployment's ADMIN_API_KEY (keep it on the server)
+    jwt_secret: the deployment's JWT_SECRET; when set, create_token() signs locally
+    """
+
+    def __init__(self, url: str, admin_key: str, jwt_secret: Optional[str] = None, timeout: float = 10.0):
+        if not url:
+            raise ValueError("url is required")
+        if not admin_key:
+            raise ValueError("admin_key is required")
+        self.url = url.rstrip("/")
+        self._admin_key = admin_key
+        self._jwt_secret = jwt_secret
+        self.timeout = timeout
+
+    # ---------- tokens ----------
+
+    def create_token(self, room_id: str, user_id: str, **options: Any) -> Dict[str, Any]:
+        """Mint a join token: {"token", "expiresAt"}.
+
+        options: name, role, permissions (dict), can_publish, metadata (dict, 4 KB),
+        max_participants (2-10000), ttl_seconds (60-86400, default 7200),
+        data_saver ("off", "low", "minimal", "audio": the preset the client starts with).
+        """
+        if self._jwt_secret:
+            return sign_token(self._jwt_secret, room_id, user_id, **options)
+        body: Dict[str, Any] = {"roomId": room_id, "userId": user_id}
+        names = {"can_publish": "canPublish", "max_participants": "maxParticipants", "ttl_seconds": "ttlSeconds", "data_saver": "dataSaver"}
+        for k, v in options.items():
+            if v is not None:
+                body[names.get(k, k)] = v
+        return self.request("POST", "/tokens", body)
+
+    # ---------- rooms ----------
+
+    def get_room(self, room_id: str) -> Dict[str, Any]:
+        """{"roomId", "room": settings, "participants": [...]}."""
+        return self.request("GET", f"/rooms/{_id(room_id)}")
+
+    def list_participants(self, room_id: str) -> List[Dict[str, Any]]:
+        return self.get_room(room_id)["participants"]
+
+    def update_room(self, room_id: str, **update: Any) -> Dict[str, Any]:
+        """locked, chat, waiting_room, spotlight (list of userIds), metadata (dict or None to clear)."""
+        body = {("waitingRoom" if k == "waiting_room" else k): v for k, v in update.items()}
+        return self.request("PATCH", f"/rooms/{_id(room_id)}", body)["room"]
+
+    def set_room_metadata(self, room_id: str, metadata: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        return self.update_room(room_id, metadata=metadata)
+
+    def lock_room(self, room_id: str, locked: bool = True) -> Dict[str, Any]:
+        return self.update_room(room_id, locked=locked)
+
+    def close_room(self, room_id: str) -> int:
+        """Disconnect everyone; returns how many connections were closed."""
+        return self.request("DELETE", f"/rooms/{_id(room_id)}")["disconnected"]
+
+    # ---------- participants ----------
+
+    def update_participant(
+        self,
+        room_id: str,
+        user_id: str,
+        *,
+        role: Optional[str] = None,
+        permissions: Any = _UNSET,
+        name: Optional[str] = None,
+        metadata: Any = _UNSET,
+        track_permissions: Any = _UNSET,
+    ) -> int:
+        """Change role/permissions/name/metadata/track permissions; pass None to clear the last three."""
+        body: Dict[str, Any] = {}
+        if role is not None:
+            body["role"] = role
+        if permissions is not _UNSET:
+            body["permissions"] = permissions
+        if name is not None:
+            body["name"] = name
+        if metadata is not _UNSET:
+            body["metadata"] = metadata
+        if track_permissions is not _UNSET:
+            body["trackPermissions"] = track_permissions
+        return self.request("PATCH", f"/rooms/{_id(room_id)}/participants/{_id(user_id)}", body)["updated"]
+
+    def set_permissions(self, room_id: str, user_id: str, permissions: Optional[Dict[str, bool]]) -> int:
+        return self.update_participant(room_id, user_id, permissions=permissions)
+
+    def set_role(self, room_id: str, user_id: str, role: str, permissions: Optional[Dict[str, bool]] = None) -> int:
+        """e.g. promote an observer: set_role(room, user, "student")."""
+        if permissions is None:
+            return self.update_participant(room_id, user_id, role=role)
+        return self.update_participant(room_id, user_id, role=role, permissions=permissions)
+
+    def set_participant_metadata(self, room_id: str, user_id: str, metadata: Optional[Dict[str, Any]]) -> int:
+        return self.update_participant(room_id, user_id, metadata=metadata)
+
+    def set_track_permissions(self, room_id: str, user_id: str, track_permissions: Optional[Dict[str, Any]]) -> int:
+        """{"allowAll": False, "allow": [{"userId": "u_1", "kinds": ["video"]}]}; None = everyone may receive."""
+        return self.update_participant(room_id, user_id, track_permissions=track_permissions)
+
+    def remove_participant(self, room_id: str, user_id: str, ban: bool = False) -> int:
+        q = "?ban=true" if ban else ""
+        return self.request("DELETE", f"/rooms/{_id(room_id)}/participants/{_id(user_id)}{q}")["disconnected"]
+
+    def unban(self, room_id: str, user_id: str) -> bool:
+        return self.request("DELETE", f"/rooms/{_id(room_id)}/bans/{_id(user_id)}")["removed"]
+
+    def mute(self, room_id: str, user_id: str, devices: Sequence[str] = ("mic",), lock: bool = False) -> int:
+        """Turn off devices of one user, or of everyone without `moderate` ("*")."""
+        body = {"userId": user_id, "devices": list(devices), "lock": lock}
+        return self.request("POST", f"/rooms/{_id(room_id)}/mute", body)["muted"]
+
+    # ---------- classroom features ----------
+
+    def admit(self, room_id: str, user_id: str) -> int:
+        return self.request("POST", f"/rooms/{_id(room_id)}/admit", {"userId": user_id})["admitted"]
+
+    def post_chat(self, room_id: str, text: str, to: Optional[str] = None) -> Any:
+        body: Dict[str, Any] = {"text": text}
+        if to:
+            body["to"] = to
+        return self.request("POST", f"/rooms/{_id(room_id)}/chat", body)["message"]
+
+    def lower_hands(self, room_id: str, user_id: Optional[str] = None) -> int:
+        if user_id:
+            return self.request("DELETE", f"/rooms/{_id(room_id)}/hands/{_id(user_id)}")["updated"]
+        return self.request("DELETE", f"/rooms/{_id(room_id)}/hands")["lowered"]
+
+    def get_attendance(self, room_id: str) -> Any:
+        return self.request("GET", f"/rooms/{_id(room_id)}/attendance")
+
+    def get_attendance_csv(self, room_id: str) -> str:
+        return self.request("GET", f"/rooms/{_id(room_id)}/attendance?format=csv", raw=True)
+
+    def clear_attendance(self, room_id: str) -> None:
+        self.request("DELETE", f"/rooms/{_id(room_id)}/attendance")
+
+    def start_breakouts(self, room_id: str, groups: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """groups: [{"name": "Group 1", "userIds": [...]}, ...]."""
+        return self.request("PUT", f"/rooms/{_id(room_id)}/breakouts", {"groups": groups})["groups"]
+
+    def end_breakouts(self, room_id: str) -> None:
+        self.request("DELETE", f"/rooms/{_id(room_id)}/breakouts")
+
+    def move_to_group(self, room_id: str, user_id: str, group: Optional[str]) -> int:
+        return self.request("POST", f"/rooms/{_id(room_id)}/move", {"userId": user_id, "group": group})["moved"]
+
+    # ---------- recording (needs the kit's STORAGE bucket; video needs the recorder bot) ----------
+
+    def start_recording(
+        self, room_id: str, video: bool = False, composite: Optional[bool] = None, max_minutes: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """Start recording to R2; video=True records audio + video with the recorder bot."""
+        body: Dict[str, Any] = {"video": video}
+        if composite is not None:
+            body["composite"] = composite
+        if max_minutes is not None:
+            body["maxMinutes"] = max_minutes
+        return self.request("POST", f"/rooms/{_id(room_id)}/recording", body)["recording"]
+
+    def recording_status(self, room_id: str) -> Optional[Dict[str, Any]]:
+        """The recording in progress, or None."""
+        return self.request("GET", f"/rooms/{_id(room_id)}/recording")["recording"]
+
+    def stop_recording(self, room_id: str) -> Dict[str, Any]:
+        """Stop recording; returns the manifest. SfuKitError 404 if nothing is recording."""
+        return self.request("DELETE", f"/rooms/{_id(room_id)}/recording")
+
+    def list_recordings(self, room_id: str) -> List[Dict[str, Any]]:
+        return self.request("GET", f"/rooms/{_id(room_id)}/recordings")["recordings"]
+
+    def download_recording(self, room_id: str, recording_id: str, file: str) -> bytes:
+        q = urllib.parse.quote
+        return self.request("GET", f"/rooms/{_id(room_id)}/recordings/{q(recording_id, safe='')}/{q(file, safe='')}", raw=bytes)
+
+    # ---------- AI lessons (an AI tutor, or an AI-taught class) ----------
+
+    def start_lesson(self, room_id: str, lesson: Optional[Dict[str, Any]] = None, mode: str = "class", **options: Any) -> Dict[str, Any]:
+        """Start an AI lesson. lesson: {"title", "subject"?, "level"?, "curriculum"?, "objectives"?, "sections" or "text"},
+        or lesson=None with planId="..." (an approved plan from the lesson library; needed when review is required).
+        options: learnerId, floor ("hands"|"teacher"|"off"), scope ("strict"|"guided"|"open"), maxMinutes, llmModel, voice, avatar…
+        Returns {"lessonId", "agentId", "participant"}."""
+        return self.request("POST", f"/rooms/{_id(room_id)}/lessons", {"mode": mode, **({"lesson": lesson} if lesson is not None else {}), **options})
+
+    def get_lesson(self, room_id: str, lesson_id: str) -> Dict[str, Any]:
+        return self.request("GET", f"/rooms/{_id(room_id)}/lessons/{_id(lesson_id)}")
+
+    def control_lesson(self, room_id: str, lesson_id: str, action: str, **args: Any) -> None:
+        """action: pause, resume, end, goto (section=), call-on (userId=), floor-policy (policy=), scope (scope=), note (text=)."""
+        self.request("POST", f"/rooms/{_id(room_id)}/lessons/{_id(lesson_id)}/control", {"action": action, **args})
+
+    def stop_lesson(self, room_id: str, lesson_id: str) -> None:
+        self.request("DELETE", f"/rooms/{_id(room_id)}/lessons/{_id(lesson_id)}")
+
+    def lesson_report(self, lesson_id: str) -> Dict[str, Any]:
+        """A finished lesson's report: summary, per-learner results and feedback, alerts, transcript."""
+        return self.request("GET", f"/lessons/{_id(lesson_id)}/report")
+
+    def learner_progress(self, learner_id: str) -> Dict[str, Any]:
+        return self.request("GET", f"/learners/{urllib.parse.quote(learner_id, safe='')}/progress")
+
+    def delete_learner_progress(self, learner_id: str) -> None:
+        self.request("DELETE", f"/learners/{urllib.parse.quote(learner_id, safe='')}/progress")
+
+    # ---------- lesson library: drafts, review, courses, timetables ----------
+
+    def lesson_settings(self) -> Dict[str, Any]:
+        """{"requireReview": bool, "defaults": {...}}. With requireReview on (the default) only approved plans are taught."""
+        return self.request("GET", "/lesson-settings")
+
+    def set_lesson_settings(self, require_review: Optional[bool] = None, defaults: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {}
+        if require_review is not None:
+            body["requireReview"] = require_review
+        if defaults is not None:
+            body["defaults"] = defaults
+        return self.request("PUT", "/lesson-settings", body)
+
+    def list_lesson_plans(self, status: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Plans in the library; status: "draft", "approved" or "archived"."""
+        return self.request("GET", "/lesson-plans" + (f"?status={urllib.parse.quote(status)}" if status else ""))["plans"]
+
+    def create_lesson_plan(self, **fields: Any) -> Dict[str, Any]:
+        """A written plan=... (saved as a draft), or material for the AI to draft from: text=, link= (Google
+        Docs/Slides), topic=, curriculum=, exam={"board", "subject", "year"}. AI drafts come back with
+        draftState "processing"; the lesson_plan_ready webhook says when they're ready to review."""
+        return self.request("POST", "/lesson-plans", fields)
+
+    def upload_lesson_material(self, files: Sequence[tuple], **fields: Any) -> Dict[str, Any]:
+        """files: [(filename, bytes), ...] (PDF, .docx, .pptx, text, Markdown, HTML, RTF, photos).
+        fields: the same options as create_lesson_plan (topic, level, language...)."""
+        boundary = "sfukit" + hashlib.sha256(str(time.time()).encode()).hexdigest()[:24]
+        parts: List[bytes] = []
+        for k, v in fields.items():
+            parts.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{k}"\r\n\r\n{v}\r\n'.encode("utf-8"))
+        for name, data in files:
+            safe = str(name).replace('"', "").replace("\r", "").replace("\n", "")
+            parts.append(f'--{boundary}\r\nContent-Disposition: form-data; name="file"; filename="{safe}"\r\nContent-Type: application/octet-stream\r\n\r\n'.encode("utf-8") + bytes(data) + b"\r\n")
+        parts.append(f"--{boundary}--\r\n".encode("utf-8"))
+        return self.request("POST", "/lesson-plans/upload", _encoded=(b"".join(parts), f"multipart/form-data; boundary={boundary}"))
+
+    def get_lesson_plan(self, plan_id: str) -> Dict[str, Any]:
+        return self.request("GET", f"/lesson-plans/{_id(plan_id)}")
+
+    def update_lesson_plan(self, plan_id: str, **changes: Any) -> Dict[str, Any]:
+        """Edit a plan. An approved plan keeps teaching its approved version until you approve again."""
+        return self.request("PUT", f"/lesson-plans/{_id(plan_id)}", changes)
+
+    def revise_lesson_plan(self, plan_id: str, instruction: str) -> Dict[str, Any]:
+        """Ask the AI to change a plan, e.g. "make section 2 simpler"."""
+        return self.request("POST", f"/lesson-plans/{_id(plan_id)}/revise", {"instruction": instruction})
+
+    def approve_lesson_plan(self, plan_id: str) -> Dict[str, Any]:
+        """Approve the plan as it is now (a new version). Start lessons with planId=... to teach it."""
+        return self.request("POST", f"/lesson-plans/{_id(plan_id)}/approve")
+
+    def lesson_plan_versions(self, plan_id: str) -> List[Dict[str, Any]]:
+        return self.request("GET", f"/lesson-plans/{_id(plan_id)}/versions")["versions"]
+
+    def trial_lesson_plan(self, plan_id: str, room_id: Optional[str] = None) -> Dict[str, Any]:
+        """A 5-minute tutor run of the plan as it is now (even unapproved), with no reports or emails."""
+        return self.request("POST", f"/lesson-plans/{_id(plan_id)}/trial", {"roomId": room_id} if room_id else {})
+
+    def archive_lesson_plan(self, plan_id: str) -> None:
+        self.request("DELETE", f"/lesson-plans/{_id(plan_id)}")
+
+    def list_courses(self) -> List[Dict[str, Any]]:
+        return self.request("GET", "/courses")["courses"]
+
+    def save_course(self, course: Dict[str, Any]) -> Dict[str, Any]:
+        """Create a course {"title", "subject"?, "level"?, "plans": [planIds in order]}, or update one that has an "id"."""
+        body = {k: v for k, v in course.items() if k != "id"}
+        if course.get("id"):
+            return self.request("PUT", f"/courses/{_id(course['id'])}", body)
+        return self.request("POST", "/courses", body)
+
+    def delete_course(self, course_id: str) -> None:
+        self.request("DELETE", f"/courses/{_id(course_id)}")
+
+    def list_timetables(self) -> List[Dict[str, Any]]:
+        return self.request("GET", "/timetables")["timetables"]
+
+    def save_timetable(self, timetable: Dict[str, Any], allow_clashes: bool = False) -> Dict[str, Any]:
+        """Create a timetable, or update one that has an "id". Two lessons in one room at once → SfuKitError 409
+        with the clashes in .body, unless allow_clashes=True."""
+        body = {k: v for k, v in timetable.items() if k != "id"}
+        q = "?allowClashes=true" if allow_clashes else ""
+        if timetable.get("id"):
+            return self.request("PUT", f"/timetables/{_id(timetable['id'])}{q}", body)
+        return self.request("POST", f"/timetables{q}", body)
+
+    def delete_timetable(self, timetable_id: str) -> None:
+        self.request("DELETE", f"/timetables/{_id(timetable_id)}")
+
+    def timetable_runs(self, days: int = 7, timetable_id: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Scheduled lessons in the next `days` days, with their status."""
+        q = {"days": str(days)}
+        if timetable_id:
+            q["timetableId"] = timetable_id
+        return self.request("GET", "/timetable-runs?" + urllib.parse.urlencode(q))["runs"]
+
+    def start_timetable_run(self, key: str) -> Dict[str, Any]:
+        return self.request("POST", f"/timetable-runs/{urllib.parse.quote(key, safe='')}/start")
+
+    def skip_timetable_run(self, key: str) -> Dict[str, Any]:
+        return self.request("POST", f"/timetable-runs/{urllib.parse.quote(key, safe='')}/skip")
+
+    def health(self) -> Dict[str, Any]:
+        return self.request("GET", "/health")
+
+    # ---------- plumbing ----------
+
+    def request(self, method: str, path: str, body: Any = None, raw: Any = False, _encoded: Optional[tuple] = None) -> Any:
+        """Call any admin endpoint (for routes this SDK doesn't wrap yet). raw=True: text, raw=bytes: bytes."""
+        headers = {"Authorization": f"Bearer {self._admin_key}", "User-Agent": f"sfukit-python/{__version__}"}
+        data = None
+        if _encoded is not None:
+            data, headers["Content-Type"] = _encoded
+        elif body is not None:
+            data = _json(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(self.url + path, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                data_out = res.read()
+                if raw is bytes:
+                    return data_out
+                text = data_out.decode("utf-8")
+        except urllib.error.HTTPError as e:
+            text = e.read().decode("utf-8", "replace")
+            try:
+                parsed: Any = json.loads(text)
+            except ValueError:
+                parsed = text
+            msg = parsed.get("error", text) if isinstance(parsed, dict) else text
+            raise SfuKitError(e.code, f"sfukit {method} {path}: {e.code} {msg}", parsed) from None
+        if raw:
+            return text
+        return json.loads(text) if text else None
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+DATA_SAVER_MODES = ("off", "low", "minimal", "audio")
+
+
+def sign_token(
+    jwt_secret: str,
+    room_id: str,
+    user_id: str,
+    *,
+    name: Optional[str] = None,
+    role: Optional[str] = None,
+    permissions: Optional[Dict[str, bool]] = None,
+    can_publish: Optional[bool] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    max_participants: Optional[int] = None,
+    ttl_seconds: Optional[int] = None,
+    data_saver: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Sign a join token with JWT_SECRET, without calling the kit (same as POST /tokens)."""
+    if not jwt_secret or len(jwt_secret) < 32:
+        raise ValueError("jwt_secret must be at least 32 characters")
+    if not _ID.match(room_id or "") or not _ID.match(user_id or ""):
+        raise ValueError("room_id and user_id must be 1-128 chars of letters, numbers, . _ : @ -")
+    if role is not None and not _ROLE.match(role):
+        raise ValueError("role must be 1-32 chars of letters, numbers, . _ -")
+    pub = True if can_publish is None else bool(can_publish)
+    perm = dict(_ROLE_DEFAULTS[role]) if role in _ROLE_DEFAULTS else {"mic": pub, "camera": pub, "screen": pub, "moderate": False}
+    for k in ("mic", "camera", "screen", "moderate"):
+        v = (permissions or {}).get(k)
+        if isinstance(v, bool):
+            perm[k] = v
+    if metadata is not None and (not isinstance(metadata, dict) or len(_json(metadata)) > 4096):
+        raise ValueError("metadata must be a dict of at most 4 KB as JSON")
+    if max_participants is not None and (
+        not isinstance(max_participants, int) or isinstance(max_participants, bool) or not 2 <= max_participants <= 10000
+    ):
+        raise ValueError("max_participants must be an integer 2-10000")
+    if data_saver is not None and data_saver not in DATA_SAVER_MODES:
+        raise ValueError('data_saver must be "off", "low", "minimal" or "audio"')
+    ttl = min(max(7200 if ttl_seconds is None else ttl_seconds, 60), 86400)
+    now = int(time.time())
+    exp = now + ttl
+    payload: Dict[str, Any] = {
+        "room": room_id,
+        "name": (name if name is not None else user_id)[:80],
+        "pub": perm["mic"] or perm["camera"] or perm["screen"],
+        "perm": perm,
+    }
+    if role:
+        payload["role"] = role
+    if max_participants is not None:
+        payload["max"] = max_participants
+    if data_saver and data_saver != "off":
+        payload["ds"] = data_saver
+    if metadata is not None:
+        payload["md"] = metadata
+    payload.update({"sub": user_id, "aud": "sfukit", "iat": now, "exp": exp})
+    signing_input = _b64url(_json({"alg": "HS256", "typ": "JWT"}).encode()) + "." + _b64url(_json(payload).encode())
+    sig = hmac.new(jwt_secret.encode(), signing_input.encode(), hashlib.sha256).digest()
+    return {"token": f"{signing_input}.{_b64url(sig)}", "expiresAt": exp}
+
+
+def verify_webhook(
+    secret: str, raw_body: Union[str, bytes], signature_header: Optional[str], tolerance_seconds: int = 300
+) -> Optional[Dict[str, Any]]:
+    """Check a webhook delivery; returns the event dict, or None if the signature is wrong or too old.
+
+    Pass the RAW body (bytes or str, not re-serialized JSON) and the X-SfuKit-Signature header.
+    `secret` is WEBHOOK_SECRET (or ADMIN_API_KEY if none was set).
+    """
+    if not secret or not signature_header:
+        return None
+    parts = {}
+    for p in signature_header.split(","):
+        k, _, v = p.partition("=")
+        parts[k.strip()] = v.strip()
+    try:
+        t = int(parts.get("t", ""))
+    except ValueError:
+        return None
+    v1 = parts.get("v1", "")
+    if not re.fullmatch(r"[0-9a-f]{64}", v1) or abs(time.time() - t) > tolerance_seconds:
+        return None
+    body = raw_body if isinstance(raw_body, bytes) else raw_body.encode("utf-8")
+    expected = hmac.new(secret.encode(), str(t).encode() + b"." + body, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, v1):
+        return None
+    try:
+        event = json.loads(body)
+    except ValueError:
+        return None
+    return event if isinstance(event, dict) else None
+
+
+def sign_webhook(secret: str, raw_body: Union[str, bytes], t: Optional[int] = None) -> str:
+    """Build a signature header (for tests of your webhook endpoint)."""
+    t = int(time.time()) if t is None else t
+    body = raw_body if isinstance(raw_body, bytes) else raw_body.encode("utf-8")
+    return f"t={t},v1=" + hmac.new(secret.encode(), str(t).encode() + b"." + body, hashlib.sha256).hexdigest()

appsocom-0.5.0/appsocom.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: appsocom
+Version: 0.5.0
+Summary: Python server SDK for Appsocom Live video calls: join tokens, rooms, moderation and webhook verification
+Author: Appsotech Limited
+License-Expression: MIT
+Project-URL: Homepage, https://live.appsocom.com
+Project-URL: Documentation, https://docs.appsocom.dev/server-sdks
+Keywords: appsocom,video,calls,webrtc,sfu,cloudflare
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Conferencing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# appsocom (Python)
+
+Python server SDK for [Appsocom Live](https://live.appsocom.com): mint join tokens, manage rooms and participants, moderate and verify webhooks. Python 3.9+, standard library only.
+
+```bash
+pip install appsocom
+```
+
+```python
+import os
+from appsocom import SfuKit, SfuKitError, verify_webhook
+
+kit = SfuKit("https://api.appsocom.dev", os.environ["APPSOCOM_API_KEY"])  # project API key from the console
+
+tok = kit.create_token("class-1", "u_7", name="Ada", role="student", metadata={"seat": 3})
+tok["token"], tok["expiresAt"]
+
+kit.set_role("class-1", "u_9", "student")             # promote an observer
+kit.mute("class-1", "*", ["mic"], lock=True)          # mute everyone, keep them muted
+kit.set_room_metadata("class-1", {"topic": "Fractions"})
+kit.set_track_permissions("class-1", "u_7", {"allowAll": False, "allow": [{"userId": "u_1"}]})
+kit.remove_participant("class-1", "u_8", ban=True)
+```
+
+Errors raise `SfuKitError` with `.status` and `.body`.
+
+Webhooks (Flask):
+
+```python
+@app.post("/appsocom-webhooks")
+def hook():
+    event = verify_webhook(os.environ["APPSOCOM_WEBHOOK_SECRET"], request.get_data(), request.headers.get("X-SfuKit-Signature"))
+    if event is None:
+        return "", 401
+    print(event["event"], event["roomId"])
+    return "", 204
+```
+
+All methods: `create_token`, `get_room`, `list_participants`, `update_room`, `set_room_metadata`, `lock_room`, `close_room`, `update_participant`, `set_permissions`, `set_role`, `set_participant_metadata`, `set_track_permissions`, `remove_participant`, `unban`, `mute`, `admit`, `post_chat`, `lower_hands`, `get_attendance`, `get_attendance_csv`, `clear_attendance`, `start_breakouts`, `end_breakouts`, `move_to_group`, `health`, `request()`. Standalone: `sign_token`, `verify_webhook`, `sign_webhook`.
+
+Self-hosting your own deployment instead? Point `url` at it and pass its admin key; the optional `jwt_secret` signs tokens locally without an HTTP call.
+
+Docs: [docs.appsocom.dev](https://docs.appsocom.dev) · License: MIT

appsocom-0.5.0/appsocom.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+appsocom/__init__.py
+appsocom.egg-info/PKG-INFO
+appsocom.egg-info/SOURCES.txt
+appsocom.egg-info/dependency_links.txt
+appsocom.egg-info/top_level.txt
+tests/test_sfukit.py

appsocom-0.5.0/appsocom.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

appsocom-0.5.0/appsocom.egg-info/top_level.txt

@@ -0,0 +1 @@
+appsocom

appsocom-0.5.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "appsocom"
+version = "0.5.0"
+description = "Python server SDK for Appsocom Live video calls: join tokens, rooms, moderation and webhook verification"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Appsotech Limited" }]
+keywords = ["appsocom", "video", "calls", "webrtc", "sfu", "cloudflare"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Communications :: Conferencing",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://live.appsocom.com"
+Documentation = "https://docs.appsocom.dev/server-sdks"
+
+[tool.setuptools]
+packages = ["appsocom"]

appsocom-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

appsocom-0.5.0/tests/test_sfukit.py

@@ -0,0 +1,142 @@
+import base64
+import hashlib
+import hmac
+import json
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from appsocom import SfuKit, SfuKitError, sign_token, sign_webhook, verify_webhook
+
+SECRET = "x" * 40
+
+
+def decode(part):
+    return json.loads(base64.urlsafe_b64decode(part + "=" * (-len(part) % 4)))
+
+
+class TokenTests(unittest.TestCase):
+    def test_signs_hs256_with_role_defaults_and_metadata(self):
+        t = sign_token(SECRET, "r1", "u1", role="student", metadata={"seat": 3}, permissions={"screen": True})
+        head, body, sig = t["token"].split(".")
+        self.assertEqual(decode(head), {"alg": "HS256", "typ": "JWT"})
+        claims = decode(body)
+        self.assertEqual(claims["sub"], "u1")
+        self.assertEqual(claims["room"], "r1")
+        self.assertEqual(claims["aud"], "sfukit")
+        self.assertEqual(claims["role"], "student")
+        self.assertEqual(claims["md"], {"seat": 3})
+        self.assertEqual(claims["perm"], {"mic": True, "camera": True, "screen": True, "moderate": False})
+        self.assertEqual(claims["exp"] - claims["iat"], 7200)
+        want = hmac.new(SECRET.encode(), f"{head}.{body}".encode(), hashlib.sha256).digest()
+        self.assertEqual(base64.urlsafe_b64encode(want).rstrip(b"=").decode(), sig)
+
+    def test_rejects_bad_input(self):
+        with self.assertRaises(ValueError):
+            sign_token("short", "r1", "u1")
+        with self.assertRaises(ValueError):
+            sign_token(SECRET, "bad room", "u1")
+        with self.assertRaises(ValueError):
+            sign_token(SECRET, "r1", "u1", max_participants=1)
+        with self.assertRaises(ValueError):
+            sign_token(SECRET, "r1", "u1", metadata={"x": "y" * 5000})
+
+    def test_client_signs_locally_with_secret(self):
+        kit = SfuKit("http://127.0.0.1:1", "k", jwt_secret=SECRET)
+        self.assertEqual(decode(kit.create_token("r1", "u1")["token"].split(".")[1])["sub"], "u1")
+
+
+class WebhookTests(unittest.TestCase):
+    def test_round_trip(self):
+        body = '{"id":"evt_1","event":"room_started"}'
+        sig = sign_webhook("s", body)
+        self.assertEqual(verify_webhook("s", body, sig)["id"], "evt_1")
+        self.assertEqual(verify_webhook("s", body.encode(), sig)["id"], "evt_1")
+        self.assertIsNone(verify_webhook("s", body + " ", sig))
+        self.assertIsNone(verify_webhook("other", body, sig))
+        self.assertIsNone(verify_webhook("s", body, None))
+        old = sign_webhook("s", body, int(time.time()) - 600)
+        self.assertIsNone(verify_webhook("s", body, old))
+
+
+class Handler(BaseHTTPRequestHandler):
+    seen = []
+
+    def log_message(self, *a):
+        pass
+
+    def _go(self):
+        n = int(self.headers.get("Content-Length") or 0)
+        body = json.loads(self.rfile.read(n)) if n else None
+        Handler.seen.append((self.command, self.path, self.headers.get("Authorization"), body))
+        if self.path.startswith("/rooms/missing"):
+            out, code = {"error": "nope"}, 404
+        elif self.command == "PATCH" and "/participants/" in self.path:
+            out, code = {"updated": 1}, 200
+        elif self.command == "PATCH":
+            out, code = {"room": {"locked": True}}, 200
+        else:
+            out, code = {"disconnected": 1, "muted": 2}, 200
+        data = json.dumps(out).encode()
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    do_GET = do_POST = do_PATCH = do_DELETE = do_PUT = _go
+
+
+class AdminTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = HTTPServer(("127.0.0.1", 0), Handler)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.kit = SfuKit(f"http://127.0.0.1:{cls.server.server_port}/", "k")
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def test_calls(self):
+        kit = self.kit
+        self.assertEqual(kit.set_role("r1", "u1", "student"), 1)
+        self.assertEqual(Handler.seen[-1], ("PATCH", "/rooms/r1/participants/u1", "Bearer k", {"role": "student"}))
+        kit.set_participant_metadata("r1", "u1", None)
+        self.assertEqual(Handler.seen[-1][3], {"metadata": None})
+        self.assertEqual(kit.mute("r1", "*", ["mic"], lock=True), 2)
+        self.assertEqual(Handler.seen[-1][3], {"userId": "*", "devices": ["mic"], "lock": True})
+        self.assertEqual(kit.remove_participant("r1", "u1", ban=True), 1)
+        self.assertEqual(Handler.seen[-1][1], "/rooms/r1/participants/u1?ban=true")
+        self.assertTrue(kit.lock_room("r1")["locked"])
+        kit.update_room("r1", waiting_room=True)
+        self.assertEqual(Handler.seen[-1][3], {"waitingRoom": True})
+
+    def test_errors(self):
+        with self.assertRaises(SfuKitError) as e:
+            self.kit.get_room("missing")
+        self.assertEqual(e.exception.status, 404)
+        self.assertIn("nope", str(e.exception))
+        with self.assertRaises(SfuKitError) as e:
+            self.kit.get_room("bad room!")
+        self.assertEqual(e.exception.status, 400)
+
+
+if __name__ == "__main__":
+    unittest.main()
+
+
+class DataSaverTokenTest(unittest.TestCase):
+    def test_data_saver_claim(self):
+        import base64
+        import json as _j
+
+        def claims(tok):
+            p = tok.split(".")[1]
+            return _j.loads(base64.urlsafe_b64decode(p + "=" * (-len(p) % 4)))
+
+        self.assertEqual(claims(sign_token(SECRET, "r1", "u1", data_saver="audio")["token"])["ds"], "audio")
+        self.assertNotIn("ds", claims(sign_token(SECRET, "r1", "u1", data_saver="off")["token"]))
+        with self.assertRaises(ValueError):
+            sign_token(SECRET, "r1", "u1", data_saver="ultra")