hyperstudy 0.3.0__tar.gz → 0.3.1__tar.gz

{hyperstudy-0.3.0 → hyperstudy-0.3.1}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v0.3.1
+
+### Features
+
+- `download_recording` / `download_recordings` now mint a signed download URL via the recordings download endpoint (using each recording's `downloadPath`) and fall back to the legacy `downloadUrl`/`url` for older GCS-only recordings. Fixes downloads failing after the backend list endpoint stopped embedding signed URLs.
+
+### Fixes
+
+- Snake_case→camelCase conversion is now recursive for the raw-dict and `**kwargs` paths: nested keys (e.g. `waiting_room_config={"max_wait_time_ms": 5000}` → `{"waitingRoomConfig": {"maxWaitTimeMs": 5000}}`) and factory `**extra` kwargs are converted. Free-form map fields (`variables`, `roles`, `globalComponents`, `globalComponentsVisibility`) preserve their user-defined keys while still converting nested schema fields. Previously nested/extra snake_case keys were silently dropped on the wire.
+- Downloads are now atomic: each file streams to `<dest>.part` and is renamed on success, so a mid-stream failure never destroys a pre-existing complete file. `skip_existing` again skips when `fileSize` is unknown (an existing file is necessarily complete).
+- `update_experiment()` with no fields now raises `ValueError` instead of issuing an empty PUT.
+- `State.id` enforces `min_length=1`; `Experiment.global_components` keys are validated against `GlobalComponentType` (rejected at construction, still serialized as strings on the wire).
+- `FocusComponent.id` is auto-generated when omitted, including direct construction without a factory helper.
+
+
 ## v0.3.0
 
 ### Features

{hyperstudy-0.3.0 → hyperstudy-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperstudy
-Version: 0.3.0
+Version: 0.3.1
 Summary: Python SDK for the HyperStudy experiment platform API
 Project-URL: Homepage, https://hyperstudy.io
 Project-URL: Documentation, https://docs.hyperstudy.io/developers/python-sdk

{hyperstudy-0.3.0 → hyperstudy-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperstudy"
-version = "0.3.0"
+version = "0.3.1"
 description = "Python SDK for the HyperStudy experiment platform API"
 readme = "README.md"
 license = "MIT"

{hyperstudy-0.3.0 → hyperstudy-0.3.1}/src/hyperstudy/_downloads.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import re
 from pathlib import Path
 from typing import Any
@@ -38,12 +39,12 @@ def build_filename(recording: dict[str, Any]) -> str:
 
 
 def download_file(url: str, dest: Path, timeout: int = 300) -> int:
-    """Stream-download *url* to *dest* and return bytes written.
+    """Stream-download *url* to *dest*; returns bytes written.
 
-    Verifies ``Content-Length`` (when the server provides it) against bytes
-    actually written. On any error — HTTP, mid-stream disconnect, or length
-    mismatch — the partial file on disk is removed so ``skip_existing``
-    logic won't mistake it for a complete download on retry.
+    Downloads to a temporary ``<dest>.part`` and atomically renames on success, so a
+    mid-stream failure (HTTP error, disconnect, length mismatch) removes only the temp
+    file and leaves any pre-existing complete file at ``dest`` intact. Verifies
+    ``Content-Length`` when provided.
     """
     resp = requests.get(url, stream=True, timeout=timeout)
     resp.raise_for_status()
@@ -57,20 +58,23 @@ def download_file(url: str, dest: Path, timeout: int = 300) -> int:
     else:
         expected = None
 
+    tmp = dest.with_name(dest.name + ".part")
     written = 0
-    # BaseException so Ctrl-C also cleans up, not just exceptions.
     try:
-        with open(dest, "wb") as fh:
+        with open(tmp, "wb") as fh:
             for chunk in resp.iter_content(chunk_size=_CHUNK_SIZE):
                 fh.write(chunk)
                 written += len(chunk)
-
         if expected is not None and written != expected:
             raise IOError(
                 f"Truncated download: wrote {written} of {expected} bytes for {dest.name}"
             )
+        os.replace(tmp, dest)   # atomic on the same filesystem
     except BaseException:
-        dest.unlink(missing_ok=True)
+        try:
+            tmp.unlink(missing_ok=True)   # remove only the temp; never the existing dest
+        except OSError:
+            pass
         raise
 
     return written

{hyperstudy-0.3.0 → hyperstudy-0.3.1}/src/hyperstudy/client.py

@@ -476,6 +476,19 @@ class HyperStudy(ExperimentMixin):
     # Recording downloads
     # ------------------------------------------------------------------
 
+    def _download_url_for(self, recording: dict[str, Any]) -> str | None:
+        """Resolve a directly-downloadable URL for a recording.
+
+        Prefers the auth'd mint endpoint (``downloadPath`` -> short-lived signed GCS
+        URL); falls back to a legacy absolute ``downloadUrl``/``url`` for old
+        GCS-only recordings.
+        """
+        download_path = recording.get("downloadPath")
+        if download_path:
+            body = self._transport.get(download_path)
+            return (body.get("data") or {}).get("url")
+        return get_download_url(recording)
+
     def download_recording(
         self,
         recording: dict[str, Any],
@@ -490,7 +503,7 @@ class HyperStudy(ExperimentMixin):
         Returns:
             Path to the downloaded file.
         """
-        url = get_download_url(recording)
+        url = self._download_url_for(recording)
         if not url:
             raise ValueError("Recording has no downloadUrl or url field")
 
@@ -564,27 +577,30 @@ class HyperStudy(ExperimentMixin):
 
         local_paths: list[str | None] = []
         statuses: list[str] = []
+        failed_count = 0
 
         for rec in tqdm(recordings, desc="Downloading recordings", disable=not progress):
             filename = build_filename(rec)
             dest = dest_dir / filename
 
-            url = get_download_url(rec)
-            if not url:
-                local_paths.append(None)
-                statuses.append("failed")
-                warnings.warn(f"Recording {rec.get('recordingId')} has no download URL")
-                continue
-
+            # Check skip before resolving the URL (avoids minting a signed URL unnecessarily).
             if skip_existing and dest.exists():
                 expected_size = rec.get("fileSize")
-                # Require positive size match; missing size → re-download to
-                # avoid trusting a truncated file from a prior failed run.
-                if expected_size is not None and dest.stat().st_size == expected_size:
+                # dest is always a fully-written file (atomic rename), so skip when size is
+                # unknown OR matches; only re-download on a definite size mismatch.
+                if expected_size is None or dest.stat().st_size == expected_size:
                     local_paths.append(str(dest.resolve()))
                     statuses.append("skipped")
                     continue
 
+            url = self._download_url_for(rec)
+            if not url:
+                local_paths.append(None)
+                statuses.append("failed")
+                failed_count += 1
+                warnings.warn(f"Recording {rec.get('recordingId')} has no download URL")
+                continue
+
             try:
                 download_file(url, dest)
                 local_paths.append(str(dest.resolve()))
@@ -592,11 +608,11 @@ class HyperStudy(ExperimentMixin):
             except Exception as exc:
                 local_paths.append(None)
                 statuses.append("failed")
+                failed_count += 1
                 warnings.warn(
                     f"Failed to download recording {rec.get('recordingId')}: {exc}"
                 )
 
-        failed_count = sum(1 for s in statuses if s == "failed")
         if failed_count:
             warnings.warn(
                 f"{failed_count}/{len(recordings)} recordings failed to download; "

{hyperstudy-0.3.0 → hyperstudy-0.3.1}/src/hyperstudy/experiments.py

@@ -10,6 +10,7 @@ from pydantic.alias_generators import to_camel
 from ._display import ExperimentInfo
 from ._http import HttpTransport
 from ._pagination import fetch_all_pages
+from .models import camelize_wire
 
 if TYPE_CHECKING:
     from .models import Experiment
@@ -37,13 +38,14 @@ def _build_experiment_payload(
     elif isinstance(experiment, BaseModel):
         payload = experiment.model_dump(by_alias=True, exclude_none=True)
     elif isinstance(experiment, dict):
-        payload = dict(experiment)
+        payload = camelize_wire(experiment)
     else:
         raise TypeError(
             f"experiment must be an Experiment or dict, got {type(experiment).__name__}"
         )
     for key, value in overrides.items():
-        payload[to_camel(key)] = value
+        ck = to_camel(key)
+        payload[ck] = camelize_wire(value, _parent_key=ck)
     return payload
 
 
@@ -182,6 +184,11 @@ class ExperimentMixin:
             Update confirmation dict.
         """
         payload = _build_experiment_payload(experiment, **kwargs)
+        if not payload:
+            raise ValueError(
+                "update_experiment requires at least one field to update "
+                "(pass experiment=... or keyword fields)."
+            )
         body = self._transport.put(f"experiments/{experiment_id}", json=payload)
         data = body.get("data", [])
         return data[0] if isinstance(data, list) and data else data

{hyperstudy-0.3.0 → hyperstudy-0.3.1}/src/hyperstudy/models.py

@@ -13,7 +13,7 @@ import uuid
 from enum import Enum
 from typing import Any, Optional
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 from pydantic.alias_generators import to_camel
 
 
@@ -21,6 +21,33 @@ def _new_id() -> str:
     return uuid.uuid4().hex[:8]
 
 
+# Fields whose IMMEDIATE child keys are user-defined names (variable names, role
+# names, component ids), NOT schema fields — their keys must NOT be camelCased.
+# Their values are still recursed into.
+_FREEFORM_MAP_FIELDS = frozenset({
+    "variables", "roles", "globalComponents", "globalComponentsVisibility",
+})
+
+
+def camelize_wire(value: Any, _parent_key: "str | None" = None) -> Any:
+    """Recursively convert snake_case dict keys to camelCase for the wire format.
+
+    Skips converting the immediate keys of free-form map fields (variables, roles,
+    globalComponents, globalComponentsVisibility) — those are user-defined names —
+    but still recurses into their values.
+    """
+    if isinstance(value, dict):
+        skip_keys = _parent_key in _FREEFORM_MAP_FIELDS
+        out: dict[str, Any] = {}
+        for k, v in value.items():
+            new_key = k if skip_keys else (to_camel(k) if isinstance(k, str) else k)
+            out[new_key] = camelize_wire(v, _parent_key=new_key)
+        return out
+    if isinstance(value, list):
+        return [camelize_wire(v, _parent_key=_parent_key) for v in value]
+    return value
+
+
 class ComponentType(str, Enum):
     """Focus component types (one per state)."""
 
@@ -78,7 +105,12 @@ class FocusComponent(_Model):
 
     type: ComponentType
     config: dict[str, Any] = Field(default_factory=dict)
-    id: Optional[str] = None
+    id: str = Field(default_factory=_new_id)
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def _default_id(cls, v: "str | None") -> str:
+        return v or _new_id()
 
 
 class TransitionRules(_Model):
@@ -91,7 +123,7 @@ class TransitionRules(_Model):
 class State(_Model):
     """An experiment state — a single screen/phase."""
 
-    id: str
+    id: str = Field(min_length=1)
     name: Optional[str] = None
     order: Optional[int] = Field(default=None, ge=0)
     focus_component: Optional[FocusComponent] = None
@@ -141,7 +173,7 @@ class Experiment(_Model):
     randomize_states: Optional[bool] = None
     states: Optional[list[State]] = None
     roles: Optional[dict[str, Role]] = None
-    global_components: Optional[dict[str, dict[str, Any]]] = None
+    global_components: Optional[dict[GlobalComponentType, dict[str, Any]]] = None
     variables: Optional[dict[str, Any]] = None
     waiting_room_config: Optional[WaitingRoomConfig] = None
     disconnect_timeout: Optional[DisconnectTimeout] = None
@@ -175,8 +207,8 @@ def show_text(text: str, *, id: Optional[str] = None, **extra: Any) -> FocusComp
     """Build a ``showtext`` focus component."""
     return FocusComponent(
         type=ComponentType.SHOW_TEXT,
-        config={**extra, "text": text},
-        id=id or _new_id(),
+        config={**camelize_wire(extra), "text": text},
+        id=id,
     )
 
 
@@ -184,8 +216,8 @@ def show_image(url: str, *, id: Optional[str] = None, **extra: Any) -> FocusComp
     """Build a ``showimage`` focus component."""
     return FocusComponent(
         type=ComponentType.SHOW_IMAGE,
-        config={**extra, "url": url},
-        id=id or _new_id(),
+        config={**camelize_wire(extra), "url": url},
+        id=id,
     )
 
 
@@ -193,8 +225,8 @@ def show_video(url: str, *, id: Optional[str] = None, **extra: Any) -> FocusComp
     """Build a ``showvideo`` focus component."""
     return FocusComponent(
         type=ComponentType.SHOW_VIDEO,
-        config={**extra, "url": url},
-        id=id or _new_id(),
+        config={**camelize_wire(extra), "url": url},
+        id=id,
     )
 
 
@@ -208,8 +240,8 @@ def vas_rating(
     """Build a ``vasrating`` (visual analog scale) focus component."""
     return FocusComponent(
         type=ComponentType.VAS_RATING,
-        config={**extra, "prompt": prompt, "outputVariable": output_variable},
-        id=id or _new_id(),
+        config={**camelize_wire(extra), "prompt": prompt, "outputVariable": output_variable},
+        id=id,
     )
 
 
@@ -223,8 +255,8 @@ def text_input(
     """Build a ``textinput`` focus component."""
     return FocusComponent(
         type=ComponentType.TEXT_INPUT,
-        config={**extra, "prompt": prompt, "outputVariable": output_variable},
-        id=id or _new_id(),
+        config={**camelize_wire(extra), "prompt": prompt, "outputVariable": output_variable},
+        id=id,
     )
 
 
@@ -240,12 +272,12 @@ def multiple_choice(
     return FocusComponent(
         type=ComponentType.MULTIPLE_CHOICE,
         config={
-            **extra,
+            **camelize_wire(extra),
             "prompt": prompt,
             "options": list(options),
             "outputVariable": output_variable,
         },
-        id=id or _new_id(),
+        id=id,
     )
 
 
@@ -253,8 +285,8 @@ def waiting(duration_ms: int, *, id: Optional[str] = None, **extra: Any) -> Focu
     """Build a ``waiting`` focus component."""
     return FocusComponent(
         type=ComponentType.WAITING,
-        config={**extra, "durationMs": int(duration_ms)},
-        id=id or _new_id(),
+        config={**camelize_wire(extra), "durationMs": int(duration_ms)},
+        id=id,
     )
 
 
@@ -270,12 +302,12 @@ def likert_scale(
     return FocusComponent(
         type=ComponentType.LIKERT_SCALE,
         config={
-            **extra,
+            **camelize_wire(extra),
             "prompt": prompt,
             "outputVariable": output_variable,
             "scalePoints": int(scale_points),
         },
-        id=id or _new_id(),
+        id=id,
     )
 
 
@@ -291,12 +323,12 @@ def ranking(
     return FocusComponent(
         type=ComponentType.RANKING,
         config={
-            **extra,
+            **camelize_wire(extra),
             "prompt": prompt,
             "options": list(options),
             "outputVariable": output_variable,
         },
-        id=id or _new_id(),
+        id=id,
     )
 
 
@@ -304,6 +336,8 @@ __all__ = [
     # Enums
     "ComponentType",
     "GlobalComponentType",
+    # Wire conversion helper
+    "camelize_wire",
     # Models
     "Experiment",
     "State",

{hyperstudy-0.3.0 → hyperstudy-0.3.1}/tests/test_client.py

@@ -357,12 +357,12 @@ def test_download_recordings_skip_existing(api_key, recordings_response, tmp_pat
 
 
 @responses.activate
-def test_download_recordings_skip_requires_known_size(
+def test_download_recordings_skip_when_filesize_unknown(
     api_key, recordings_response, tmp_path
 ):
-    """When server-side fileSize is missing, skip_existing must NOT accept a
-    stale on-disk file — it must re-download so truncated prior attempts
-    don't linger forever."""
+    """When server-side fileSize is missing, skip_existing should skip an
+    existing on-disk file. Because downloads are atomic (Fix C), any file
+    that exists is necessarily complete — truncated partials cannot remain."""
     # Strip fileSize from the video record to simulate older recordings where
     # the backend didn't store file size metadata.
     recordings_response["data"][0]["fileSize"] = None
@@ -373,16 +373,12 @@ def test_download_recordings_skip_requires_known_size(
         status=200,
     )
 
-    # Pre-create a (probably partial) video file on disk.
+    # Pre-create a complete video file on disk (atomic rename guarantees this).
+    existing_bytes = b"already-complete-video-content"
     video_path = tmp_path / "Alice_video_EG_video_001.mp4"
-    video_path.write_bytes(b"stale-partial-content")
+    video_path.write_bytes(existing_bytes)
 
-    fresh_video = b"freshly downloaded video bytes" * 20
-    responses.get(
-        recordings_response["data"][0]["downloadUrl"],
-        body=fresh_video,
-        status=200,
-    )
+    # Audio still needs to download (does not exist on disk).
     responses.get(
         recordings_response["data"][1]["downloadUrl"],
         body=b"audio",
@@ -394,8 +390,9 @@ def test_download_recordings_skip_requires_known_size(
         "exp_abc123", output_dir=str(tmp_path), progress=False, skip_existing=True
     )
 
-    assert df["download_status"].iloc[0] == "downloaded"
-    assert video_path.read_bytes() == fresh_video
+    # Video was skipped (pre-existing, no GCS call needed).
+    assert df["download_status"].iloc[0] == "skipped"
+    assert video_path.read_bytes() == existing_bytes
 
 
 def test_download_recordings_list_call_uses_long_timeout(

{hyperstudy-0.3.0 → hyperstudy-0.3.1}/tests/test_downloads.py

@@ -186,3 +186,71 @@ def test_download_file_cleans_up_on_stream_error(tmp_path):
         assert not dest.exists(), "partial file must be deleted on mid-stream error"
     finally:
         downloads_mod.requests.get = original
+
+
+# ---------------------------------------------------------------------------
+# Fix C — atomic download: pre-existing dest must survive a failed download
+# ---------------------------------------------------------------------------
+
+
+def test_download_file_atomic_preserves_existing_on_truncation(tmp_path, monkeypatch):
+    """A pre-existing complete file is NOT removed when the new download fails.
+
+    The new code streams to a .part file; on failure only the .part is removed,
+    leaving the original intact.
+    """
+    import hyperstudy._downloads as downloads_mod
+
+    dest = tmp_path / "output.mp4"
+    original_bytes = b"ORIGINAL_COMPLETE_DATA"
+    dest.write_bytes(original_bytes)
+
+    # Simulate a truncated download: Content-Length claims 100 but body is short.
+    class TruncatedResponse:
+        status_code = 200
+        headers = {"Content-Length": "100"}
+
+        def raise_for_status(self):
+            return None
+
+        def iter_content(self, chunk_size):
+            yield b"SHORT"  # only 5 bytes, not 100
+
+    monkeypatch.setattr(
+        downloads_mod.requests, "get", lambda *a, **kw: TruncatedResponse()
+    )
+
+    with pytest.raises(IOError, match="[Tt]runcated"):
+        download_file("https://example.com/trunc.mp4", dest)
+
+    # Original file must still exist with original content
+    assert dest.exists(), "pre-existing complete file was destroyed by a failed download"
+    assert dest.read_bytes() == original_bytes
+
+    # No .part file should remain
+    part = dest.with_name(dest.name + ".part")
+    assert not part.exists(), ".part file not cleaned up after failure"
+
+
+def test_download_file_no_part_file_on_success(tmp_path, monkeypatch):
+    """On success, no .part file lingers."""
+    import hyperstudy._downloads as downloads_mod
+
+    class OkResponse:
+        status_code = 200
+        headers: dict = {}
+
+        def raise_for_status(self):
+            return None
+
+        def iter_content(self, chunk_size):
+            yield b"GOOD DATA"
+
+    monkeypatch.setattr(
+        downloads_mod.requests, "get", lambda *a, **kw: OkResponse()
+    )
+    dest = tmp_path / "ok.mp4"
+    download_file("https://example.com/ok.mp4", dest)
+    assert dest.exists()
+    part = dest.with_name(dest.name + ".part")
+    assert not part.exists()

{hyperstudy-0.3.0 → hyperstudy-0.3.1}/tests/test_experiments.py

@@ -396,3 +396,79 @@ def test_get_experiment_not_found():
     client = HyperStudy(api_key="hst_test_key", base_url=BASE_URL)
     with pytest.raises(NotFoundError, match="not found"):
         client.get_experiment("exp_nonexistent")
+
+
+# ---------------------------------------------------------------------------
+# Fix A1 — recursive snake→camel on dict experiment path and overrides
+# ---------------------------------------------------------------------------
+
+
+def test_build_payload_dict_experiment_camelizes_keys():
+    """dict-form experiments have snake_case keys converted to camelCase."""
+    from hyperstudy.experiments import _build_experiment_payload
+
+    payload = _build_experiment_payload(
+        {"waiting_room_config": {"max_wait_time_ms": 5000}}
+    )
+    assert payload == {"waitingRoomConfig": {"maxWaitTimeMs": 5000}}
+    assert "waiting_room_config" not in payload
+
+
+def test_build_payload_dict_nested_list_camelized():
+    """Nested list values in dicts are also camelized."""
+    from hyperstudy.experiments import _build_experiment_payload
+
+    payload = _build_experiment_payload(
+        {
+            "states": [
+                {
+                    "id": "s1",
+                    "focus_component": {"type": "showtext", "config": {"text": "hi"}},
+                }
+            ]
+        }
+    )
+    assert "focusComponent" in payload["states"][0]
+    assert "focus_component" not in payload["states"][0]
+
+
+def test_build_payload_freeform_keys_preserved():
+    """variables keys are NOT camelized (user-defined names), but values are."""
+    from hyperstudy.experiments import _build_experiment_payload
+
+    payload = _build_experiment_payload({"variables": {"my_var_name": 1}})
+    assert payload == {"variables": {"my_var_name": 1}}
+
+
+def test_build_payload_roles_name_preserved_value_camelized():
+    """Role names (keys) are preserved; nested fields in values are camelized."""
+    from hyperstudy.experiments import _build_experiment_payload
+
+    payload = _build_experiment_payload(
+        {"roles": {"my_role": {"participant_count": 2}}}
+    )
+    assert "my_role" in payload["roles"]
+    assert payload["roles"]["my_role"] == {"participantCount": 2}
+
+
+def test_build_payload_override_value_camelized():
+    """Override values (nested dicts/lists) are also recursively camelized."""
+    from hyperstudy.experiments import _build_experiment_payload
+
+    payload = _build_experiment_payload(
+        None,
+        waiting_room_config={"max_wait_time_ms": 3000},
+    )
+    assert payload == {"waitingRoomConfig": {"maxWaitTimeMs": 3000}}
+
+
+# ---------------------------------------------------------------------------
+# Fix B — empty-PUT guard
+# ---------------------------------------------------------------------------
+
+
+def test_update_experiment_empty_raises():
+    """update_experiment with no experiment and no kwargs raises ValueError."""
+    client = HyperStudy(api_key="hst_test_key", base_url=BASE_URL)
+    with pytest.raises(ValueError, match="at least one field"):
+        client.update_experiment("exp123")

{hyperstudy-0.3.0 → hyperstudy-0.3.1}/tests/test_models.py

@@ -282,6 +282,84 @@ def test_factory_generates_id_when_omitted():
     assert a.id and b.id and a.id != b.id
 
 
+# ---------------------------------------------------------------------------
+# Fix A2 — factory **extra camelization
+# ---------------------------------------------------------------------------
+
+
+def test_factory_extra_snake_case_camelized():
+    """Extra kwargs to factories are camelized so they land correctly on the wire."""
+    c = show_text("hi", max_width=600)
+    assert "maxWidth" in c.config
+    assert c.config["maxWidth"] == 600
+    assert "max_width" not in c.config
+
+
+def test_vas_rating_factory_extra_camelized():
+    """vas_rating extra kwargs with snake_case are camelized."""
+    c = vas_rating("p", output_variable="ov", min_label="Low")
+    assert "minLabel" in c.config
+    assert c.config["minLabel"] == "Low"
+    assert "outputVariable" in c.config
+    assert "outputVariable" in c.config
+
+
+# ---------------------------------------------------------------------------
+# Fix E — schema enforcement on State.id and global_components
+# ---------------------------------------------------------------------------
+
+
+def test_state_id_empty_rejected():
+    """State.id must be non-empty (minLength:1)."""
+    with pytest.raises(ValidationError):
+        State(id="")
+
+
+def test_global_components_invalid_type_rejected():
+    """global_components keys must be GlobalComponentType values."""
+    with pytest.raises(ValidationError):
+        Experiment(name="x", global_components={"showvideo": {}})
+
+
+def test_global_components_valid_type_accepted():
+    """Valid GlobalComponentType keys are accepted."""
+    exp = Experiment(name="x", global_components={"videochat": {"option": 1}})
+    wire = exp.model_dump(by_alias=True, exclude_none=True)
+    assert wire["globalComponents"] == {"videochat": {"option": 1}}
+
+
+def test_global_components_dumps_string_keys():
+    """global_components keys must serialize as strings, not enum reprs."""
+    exp = Experiment(name="x", global_components={"textchat": {}})
+    wire = exp.model_dump(by_alias=True, exclude_none=True)
+    keys = list(wire["globalComponents"].keys())
+    assert keys == ["textchat"], f"Expected string keys but got: {keys}"
+
+
+# ---------------------------------------------------------------------------
+# Fix F — centralized FocusComponent id via before-validator
+# ---------------------------------------------------------------------------
+
+
+def test_focus_component_direct_construction_gets_id():
+    """FocusComponent(type=..., config=...) gets an auto-generated id."""
+    fc = FocusComponent(type=ComponentType.SHOW_TEXT, config={})
+    assert fc.id is not None
+    assert len(fc.id) == 8
+
+
+def test_show_text_id_auto_generated():
+    """show_text() without id= gets a non-empty id."""
+    fc = show_text("hi")
+    assert fc.id and len(fc.id) == 8
+
+
+def test_show_text_explicit_id_preserved():
+    """show_text(id='x') keeps the explicit id."""
+    fc = show_text("hi", id="x")
+    assert fc.id == "x"
+
+
 # ---------------------------------------------------------------------------
 # Schema-drift guard
 # ---------------------------------------------------------------------------

hyperstudy-0.3.1/tests/test_recordings_download.py

@@ -0,0 +1,136 @@
+import warnings
+from pathlib import Path
+
+import pytest
+import responses
+import hyperstudy
+
+BASE_URL = "https://api.hyperstudy.io/api/v3"
+
+
+# ---------------------------------------------------------------------------
+# Fix D — skip_existing when fileSize is unknown
+# ---------------------------------------------------------------------------
+
+
+@responses.activate
+def test_skip_existing_no_filesize(tmp_path):
+    """When fileSize is absent and file already exists, skip without re-downloading."""
+    # Register the list-recordings endpoint
+    responses.add(
+        responses.GET,
+        f"{BASE_URL}/data/recordings/experiment/exp1",
+        json={
+            "status": "success",
+            "metadata": {"total": 1, "limit": 50, "offset": 0, "dataType": "recordings"},
+            "data": [
+                {
+                    "recordingId": "EG_001",
+                    "participantName": "Alice",
+                    "format": "mp4",
+                    "metadata": {"type": "video"},
+                    "downloadPath": "/data/recordings/download/room_1/EG_001",
+                    # No fileSize key
+                }
+            ],
+        },
+        status=200,
+    )
+
+    dest_dir = tmp_path
+    dest = dest_dir / "Alice_video_EG_001.mp4"
+    dest.write_bytes(b"EXISTING_CONTENT")
+
+    hs = hyperstudy.HyperStudy(api_key="hst_test_" + "a" * 32)
+
+    df = hs.download_recordings("exp1", output_dir=str(dest_dir), skip_existing=True)
+
+    # No download call should have been made for the GCS URL
+    download_calls = [c for c in responses.calls if "signed" in c.request.url]
+    assert len(download_calls) == 0, "Should have skipped the download"
+
+    assert df["download_status"].iloc[0] == "skipped"
+    # Pre-existing file must be intact
+    assert dest.read_bytes() == b"EXISTING_CONTENT"
+
+
+@responses.activate
+def test_redownload_on_filesize_mismatch(tmp_path):
+    """When fileSize is present but mismatched, re-download the file."""
+    responses.add(
+        responses.GET,
+        f"{BASE_URL}/data/recordings/experiment/exp2",
+        json={
+            "status": "success",
+            "metadata": {"total": 1, "limit": 50, "offset": 0, "dataType": "recordings"},
+            "data": [
+                {
+                    "recordingId": "EG_002",
+                    "participantName": "Bob",
+                    "format": "mp4",
+                    "metadata": {"type": "video"},
+                    "downloadPath": "/data/recordings/download/room_2/EG_002",
+                    "fileSize": 9999,  # mismatch with existing file
+                }
+            ],
+        },
+        status=200,
+    )
+    # mint endpoint
+    responses.add(
+        responses.GET,
+        f"{BASE_URL}/data/recordings/download/room_2/EG_002",
+        json={"status": "success", "data": {"url": "https://signed.example/Bob.mp4"}},
+        status=200,
+    )
+    # GCS signed URL
+    new_bytes = b"NEW_DOWNLOAD_CONTENT"
+    responses.add(
+        responses.GET,
+        "https://signed.example/Bob.mp4",
+        body=new_bytes,
+        status=200,
+    )
+
+    dest_dir = tmp_path
+    dest = dest_dir / "Bob_video_EG_002.mp4"
+    dest.write_bytes(b"OLD")  # size 3, doesn't match fileSize=9999
+
+    hs = hyperstudy.HyperStudy(api_key="hst_test_" + "a" * 32)
+    df = hs.download_recordings("exp2", output_dir=str(dest_dir), skip_existing=True)
+
+    assert df["download_status"].iloc[0] == "downloaded"
+    assert dest.read_bytes() == new_bytes
+
+
+@responses.activate
+def test_download_recording_mints_signed_url(tmp_path):
+    base = "https://api.hyperstudy.io/api/v3"
+    # 1) mint endpoint returns a signed url in the envelope
+    responses.add(
+        responses.GET,
+        f"{base}/data/recordings/download/room_EXP_1_a/EG_x",
+        json={"status": "success", "data": {"url": "https://signed.example/x.mp4"}},
+        status=200,
+    )
+    # 2) the signed url serves bytes
+    responses.add(responses.GET, "https://signed.example/x.mp4", body=b"VIDEOBYTES", status=200)
+
+    hs = hyperstudy.HyperStudy(api_key="hst_test_" + "a" * 32)
+    rec = {
+        "downloadPath": "/data/recordings/download/room_EXP_1_a/EG_x",
+        "fileName": "x.mp4",
+        "participantId": "p1",
+        "recordingId": "EG_x",
+    }
+    dest = hs.download_recording(rec, output_dir=str(tmp_path))
+    assert dest.read_bytes() == b"VIDEOBYTES"
+
+
+@responses.activate
+def test_download_recording_falls_back_to_legacy_url(tmp_path):
+    responses.add(responses.GET, "https://legacy.example/y.mp4", body=b"LEGACY", status=200)
+    hs = hyperstudy.HyperStudy(api_key="hst_test_" + "a" * 32)
+    rec = {"url": "https://legacy.example/y.mp4", "fileName": "y.mp4", "recordingId": "old"}
+    dest = hs.download_recording(rec, output_dir=str(tmp_path))
+    assert dest.read_bytes() == b"LEGACY"