hyperstudy 0.1.0__tar.gz → 0.2.0__tar.gz

hyperstudy-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,polars]"
+
+      - name: Lint
+        run: ruff check src/
+
+      - name: Run tests
+        run: pytest --cov=hyperstudy --cov-report=term-missing -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      attestations: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Generate Sigstore attestations
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

{hyperstudy-0.1.0 → hyperstudy-0.2.0}/.github/workflows/sync-release-notes.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Checkout hyperstudy-docs
         uses: actions/checkout@v4
         with:
-          repository: ljchang/hyperstudy-docs
+          repository: hyperstudyio/hyperstudy-docs
           token: ${{ secrets.DOCS_REPO_TOKEN }}
           path: docs-repo
 

{hyperstudy-0.1.0 → hyperstudy-0.2.0}/.github/workflows/test.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v4

{hyperstudy-0.1.0 → hyperstudy-0.2.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v0.2.0
+
+### Features
+
+- Convenience methods for common event categories: `get_questionnaire`, `get_instructions`, `get_consent`
+- Deployment management: `list_deployments`, `get_deployment`, `get_deployment_sessions`
+- API warning surfacing: backend `_warnings` metadata now emitted via Python's `warnings` module
+- `get_all_data` now includes `ratings_sparse`, `questionnaire`, `instructions`, and `consent`
+
+### Breaking Changes
+
+- `get_all_data` return keys changed: `"ratings"` split into `"ratings_continuous"` and `"ratings_sparse"`
+
 ## v0.1.0
 
 Initial release.

{hyperstudy-0.1.0 → hyperstudy-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperstudy
-Version: 0.1.0
+Version: 0.2.0
 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
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.9
 Requires-Dist: pandas>=1.5.0
@@ -70,15 +71,20 @@ events = hs.get_events("participant_id", scope="participant", room_id="room_id")
 All data retrieval methods follow the same pattern:
 
 ```python
-events      = hs.get_events("exp_id")
-recordings  = hs.get_recordings("exp_id")
-chat        = hs.get_chat("exp_id")
-videochat   = hs.get_videochat("exp_id")
-sync        = hs.get_sync("exp_id")
-ratings     = hs.get_ratings("exp_id", kind="continuous")
-components  = hs.get_components("exp_id")
-participants = hs.get_participants("exp_id")
-rooms       = hs.get_rooms("exp_id")
+events        = hs.get_events("exp_id")
+recordings    = hs.get_recordings("exp_id")
+chat          = hs.get_chat("exp_id")
+videochat     = hs.get_videochat("exp_id")
+sync          = hs.get_sync("exp_id")
+ratings       = hs.get_ratings("exp_id", kind="continuous")
+components    = hs.get_components("exp_id")
+participants  = hs.get_participants("exp_id")
+rooms         = hs.get_rooms("exp_id")
+
+# Convenience methods for common event categories
+questionnaire = hs.get_questionnaire("exp_id")
+instructions  = hs.get_instructions("exp_id")
+consent       = hs.get_consent("exp_id")
 ```
 
 ### Output Formats
@@ -125,11 +131,27 @@ hs.update_experiment("exp_id", name="Updated Name")
 hs.delete_experiment("exp_id")
 ```
 
+## Deployments
+
+```python
+# List deployments
+deployments = hs.list_deployments()
+deployments = hs.list_deployments(experiment_id="exp_id", status="active")
+
+# Get deployment details
+dep = hs.get_deployment("deployment_id")
+
+# List sessions/rooms for a deployment
+sessions = hs.get_deployment_sessions("deployment_id")
+```
+
 ## All Data for a Participant
 
 ```python
 data = hs.get_all_data("participant_id", room_id="room_id")
-# Returns: {"events": DataFrame, "recordings": DataFrame, "chat": DataFrame, ...}
+# Returns dict with keys: events, recordings, chat, videochat, sync,
+# ratings_continuous, ratings_sparse, components, questionnaire,
+# instructions, consent
 ```
 
 ## API Key
@@ -143,7 +165,7 @@ Full documentation: [docs.hyperstudy.io/developers/python-sdk](https://docs.hype
 ## Development
 
 ```bash
-git clone https://github.com/ljchang/hyperstudy-pythonsdk.git
+git clone https://github.com/hyperstudyio/hyperstudy-pythonsdk.git
 cd hyperstudy-pythonsdk
 pip install -e ".[dev,polars]"
 pytest --cov=hyperstudy

{hyperstudy-0.1.0 → hyperstudy-0.2.0}/README.md

@@ -37,15 +37,20 @@ events = hs.get_events("participant_id", scope="participant", room_id="room_id")
 All data retrieval methods follow the same pattern:
 
 ```python
-events      = hs.get_events("exp_id")
-recordings  = hs.get_recordings("exp_id")
-chat        = hs.get_chat("exp_id")
-videochat   = hs.get_videochat("exp_id")
-sync        = hs.get_sync("exp_id")
-ratings     = hs.get_ratings("exp_id", kind="continuous")
-components  = hs.get_components("exp_id")
-participants = hs.get_participants("exp_id")
-rooms       = hs.get_rooms("exp_id")
+events        = hs.get_events("exp_id")
+recordings    = hs.get_recordings("exp_id")
+chat          = hs.get_chat("exp_id")
+videochat     = hs.get_videochat("exp_id")
+sync          = hs.get_sync("exp_id")
+ratings       = hs.get_ratings("exp_id", kind="continuous")
+components    = hs.get_components("exp_id")
+participants  = hs.get_participants("exp_id")
+rooms         = hs.get_rooms("exp_id")
+
+# Convenience methods for common event categories
+questionnaire = hs.get_questionnaire("exp_id")
+instructions  = hs.get_instructions("exp_id")
+consent       = hs.get_consent("exp_id")
 ```
 
 ### Output Formats
@@ -92,11 +97,27 @@ hs.update_experiment("exp_id", name="Updated Name")
 hs.delete_experiment("exp_id")
 ```
 
+## Deployments
+
+```python
+# List deployments
+deployments = hs.list_deployments()
+deployments = hs.list_deployments(experiment_id="exp_id", status="active")
+
+# Get deployment details
+dep = hs.get_deployment("deployment_id")
+
+# List sessions/rooms for a deployment
+sessions = hs.get_deployment_sessions("deployment_id")
+```
+
 ## All Data for a Participant
 
 ```python
 data = hs.get_all_data("participant_id", room_id="room_id")
-# Returns: {"events": DataFrame, "recordings": DataFrame, "chat": DataFrame, ...}
+# Returns dict with keys: events, recordings, chat, videochat, sync,
+# ratings_continuous, ratings_sparse, components, questionnaire,
+# instructions, consent
 ```
 
 ## API Key
@@ -110,7 +131,7 @@ Full documentation: [docs.hyperstudy.io/developers/python-sdk](https://docs.hype
 ## Development
 
 ```bash
-git clone https://github.com/ljchang/hyperstudy-pythonsdk.git
+git clone https://github.com/hyperstudyio/hyperstudy-pythonsdk.git
 cd hyperstudy-pythonsdk
 pip install -e ".[dev,polars]"
 pytest --cov=hyperstudy

{hyperstudy-0.1.0 → hyperstudy-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperstudy"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python SDK for the HyperStudy experiment platform API"
 readme = "README.md"
 license = "MIT"
@@ -21,6 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering",
 ]
 dependencies = [

{hyperstudy-0.1.0 → hyperstudy-0.2.0}/src/hyperstudy/__init__.py

@@ -19,7 +19,7 @@ from .exceptions import (
     ValidationError,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     "HyperStudy",

{hyperstudy-0.1.0 → hyperstudy-0.2.0}/src/hyperstudy/_http.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+import warnings
 from typing import Any
 
 import requests
@@ -125,4 +126,8 @@ class HttpTransport:
                 status_code=resp.status_code,
             )
 
+        # Surface API warnings (e.g. missing Firestore indexes)
+        for w in body.get("metadata", {}).get("_warnings", []):
+            warnings.warn(w, stacklevel=4)
+
         return body

{hyperstudy-0.1.0 → hyperstudy-0.2.0}/src/hyperstudy/client.py

@@ -277,6 +277,151 @@ class HyperStudy(ExperimentMixin):
             output=output, progress=progress,
         )
 
+    # ------------------------------------------------------------------
+    # Convenience: category-filtered events
+    # ------------------------------------------------------------------
+
+    def get_questionnaire(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        sort: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch questionnaire responses.
+
+        Convenience wrapper around :meth:`get_events` with
+        ``category="questionnaire"``.
+        """
+        return self._fetch_data(
+            "events", scope_id,
+            scope=scope, room_id=room_id,
+            start_time=start_time, end_time=end_time,
+            category="questionnaire", sort=sort, order=order,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
+    def get_instructions(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        sort: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch instruction / comprehension-check events.
+
+        Fetches ``pre_experiment`` events and filters to those whose
+        ``eventType`` starts with ``"instructions."``.
+        """
+        return self._fetch_and_filter(
+            "instructions.", scope_id,
+            scope=scope, room_id=room_id,
+            start_time=start_time, end_time=end_time,
+            sort=sort, order=order,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
+    def get_consent(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        sort: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch consent events.
+
+        Fetches ``pre_experiment`` events and filters to those whose
+        ``eventType`` starts with ``"consent."``.
+        """
+        return self._fetch_and_filter(
+            "consent.", scope_id,
+            scope=scope, room_id=room_id,
+            start_time=start_time, end_time=end_time,
+            sort=sort, order=order,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
+    # ------------------------------------------------------------------
+    # Deployments
+    # ------------------------------------------------------------------
+
+    def list_deployments(
+        self,
+        *,
+        experiment_id: str | None = None,
+        status: str | None = None,
+        output: str = "pandas",
+    ):
+        """List deployments for the authenticated user.
+
+        Args:
+            experiment_id: Filter by experiment.
+            status: Filter by deployment status.
+            output: ``"pandas"`` (default), ``"polars"``, or ``"dict"``.
+        """
+        params: dict[str, Any] = {}
+        if experiment_id:
+            params["experimentId"] = experiment_id
+        if status:
+            params["status"] = status
+
+        body = self._transport.get("deployments", params=params or None)
+        data = body.get("data", [])
+        return self._convert_output(data, output)
+
+    def get_deployment(self, deployment_id: str) -> dict[str, Any]:
+        """Get deployment details.
+
+        Returns:
+            Deployment dict.
+        """
+        body = self._transport.get(f"deployments/{deployment_id}")
+        data = body.get("data", [])
+        return data[0] if isinstance(data, list) and data else data
+
+    def get_deployment_sessions(
+        self,
+        deployment_id: str,
+        *,
+        output: str = "pandas",
+    ):
+        """List rooms/sessions for a deployment.
+
+        Args:
+            deployment_id: Deployment ID.
+            output: ``"pandas"`` (default), ``"polars"``, or ``"dict"``.
+        """
+        body = self._transport.get(f"deployments/{deployment_id}/sessions")
+        data = body.get("data", [])
+        return self._convert_output(data, output)
+
     # ------------------------------------------------------------------
     # Convenience: all data for a participant
     # ------------------------------------------------------------------
@@ -300,14 +445,55 @@ class HyperStudy(ExperimentMixin):
             "chat": self.get_chat(participant_id, **common),
             "videochat": self.get_videochat(participant_id, **common),
             "sync": self.get_sync(participant_id, **common),
-            "ratings": self.get_ratings(participant_id, kind="continuous", **common),
+            "ratings_continuous": self.get_ratings(participant_id, kind="continuous", **common),
+            "ratings_sparse": self.get_ratings(participant_id, kind="sparse", **common),
             "components": self.get_components(participant_id, **common),
+            "questionnaire": self.get_questionnaire(participant_id, **common),
+            "instructions": self.get_instructions(participant_id, **common),
+            "consent": self.get_consent(participant_id, **common),
         }
 
     # ------------------------------------------------------------------
     # Internal helpers
     # ------------------------------------------------------------------
 
+    def _fetch_and_filter(
+        self,
+        event_type_prefix: str,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        sort: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch pre_experiment events and filter by eventType prefix.
+
+        Used by :meth:`get_instructions` and :meth:`get_consent` which
+        share the ``pre_experiment`` category but need client-side
+        filtering on the ``eventType`` field.
+        """
+        # Always fetch as dicts so we can filter before conversion
+        raw = self._fetch_data(
+            "events", scope_id,
+            scope=scope, room_id=room_id,
+            start_time=start_time, end_time=end_time,
+            category="pre_experiment", sort=sort, order=order,
+            limit=limit, offset=offset,
+            output="dict", progress=progress,
+        )
+        filtered = [
+            e for e in raw
+            if e.get("eventType", "").startswith(event_type_prefix)
+        ]
+        return self._convert_output(filtered, output)
+
     def _fetch_data(
         self,
         data_type: str,

{hyperstudy-0.1.0 → hyperstudy-0.2.0}/tests/conftest.py

@@ -51,6 +51,31 @@ def paginated_page2():
     return load_fixture("paginated_page2.json")
 
 
+@pytest.fixture
+def pre_experiment_response():
+    return load_fixture("pre_experiment_response.json")
+
+
+@pytest.fixture
+def deployments_list_response():
+    return load_fixture("deployments_list_response.json")
+
+
+@pytest.fixture
+def deployment_single_response():
+    return load_fixture("deployment_single_response.json")
+
+
+@pytest.fixture
+def deployment_sessions_response():
+    return load_fixture("deployment_sessions_response.json")
+
+
+@pytest.fixture
+def warnings_response():
+    return load_fixture("warnings_response.json")
+
+
 @pytest.fixture
 def error_401():
     return load_fixture("error_401.json")

hyperstudy-0.2.0/tests/fixtures/deployment_sessions_response.json

@@ -0,0 +1,26 @@
+{
+  "status": "success",
+  "metadata": {
+    "dataType": "sessions",
+    "scope": "deployment",
+    "scopeId": "dep_001"
+  },
+  "data": [
+    {
+      "id": "room_001",
+      "experimentId": "exp_abc123",
+      "deploymentId": "dep_001",
+      "status": "completed",
+      "participantCount": 2,
+      "createdAt": "2024-06-10T14:00:00.000Z"
+    },
+    {
+      "id": "room_002",
+      "experimentId": "exp_abc123",
+      "deploymentId": "dep_001",
+      "status": "completed",
+      "participantCount": 2,
+      "createdAt": "2024-06-11T14:00:00.000Z"
+    }
+  ]
+}

hyperstudy-0.2.0/tests/fixtures/deployment_single_response.json

@@ -0,0 +1,20 @@
+{
+  "status": "success",
+  "metadata": {
+    "dataType": "deployment",
+    "scope": "deployment",
+    "scopeId": "dep_001"
+  },
+  "data": {
+    "id": "dep_001",
+    "experimentId": "exp_abc123",
+    "name": "Pilot Study",
+    "status": "active",
+    "ownerId": "user_abc",
+    "ownerName": "Test User",
+    "participantCount": 24,
+    "maxParticipants": 100,
+    "createdAt": "2024-06-01T10:00:00.000Z",
+    "updatedAt": "2024-06-15T10:00:00.000Z"
+  }
+}

hyperstudy-0.2.0/tests/fixtures/deployments_list_response.json

@@ -0,0 +1,28 @@
+{
+  "status": "success",
+  "metadata": {
+    "dataType": "deployments",
+    "scope": "user",
+    "scopeId": "user_abc"
+  },
+  "data": [
+    {
+      "id": "dep_001",
+      "experimentId": "exp_abc123",
+      "name": "Pilot Study",
+      "status": "active",
+      "ownerId": "user_abc",
+      "ownerName": "Test User",
+      "createdAt": "2024-06-01T10:00:00.000Z"
+    },
+    {
+      "id": "dep_002",
+      "experimentId": "exp_abc123",
+      "name": "Main Study",
+      "status": "completed",
+      "ownerId": "user_abc",
+      "ownerName": "Test User",
+      "createdAt": "2024-07-01T10:00:00.000Z"
+    }
+  ]
+}

hyperstudy-0.2.0/tests/fixtures/pre_experiment_response.json

@@ -0,0 +1,69 @@
+{
+  "status": "success",
+  "metadata": {
+    "dataType": "events",
+    "scope": "experiment",
+    "scopeId": "exp_abc123",
+    "timestamp": "2024-06-15T10:00:00.000Z",
+    "query": {
+      "category": "pre_experiment",
+      "limit": 1000,
+      "offset": 0,
+      "sort": "timestamp",
+      "order": "asc"
+    },
+    "pagination": {
+      "total": 4,
+      "returned": 4,
+      "hasMore": false,
+      "limit": 1000,
+      "offset": 0
+    }
+  },
+  "data": [
+    {
+      "id": "evt_010",
+      "experimentId": "exp_abc123",
+      "roomId": "room_xyz",
+      "participantId": "user_1",
+      "onset": 0,
+      "timestamp": "2024-06-15T09:59:50.000Z",
+      "category": "pre_experiment",
+      "eventType": "consent.accepted",
+      "content": "agreed"
+    },
+    {
+      "id": "evt_011",
+      "experimentId": "exp_abc123",
+      "roomId": "room_xyz",
+      "participantId": "user_1",
+      "onset": 500,
+      "timestamp": "2024-06-15T09:59:50.500Z",
+      "category": "pre_experiment",
+      "eventType": "instructions.page_view",
+      "content": "page_1"
+    },
+    {
+      "id": "evt_012",
+      "experimentId": "exp_abc123",
+      "roomId": "room_xyz",
+      "participantId": "user_1",
+      "onset": 2000,
+      "timestamp": "2024-06-15T09:59:52.000Z",
+      "category": "pre_experiment",
+      "eventType": "instructions.comprehension_check",
+      "content": "correct"
+    },
+    {
+      "id": "evt_013",
+      "experimentId": "exp_abc123",
+      "roomId": "room_xyz",
+      "participantId": "user_2",
+      "onset": 0,
+      "timestamp": "2024-06-15T09:59:50.000Z",
+      "category": "pre_experiment",
+      "eventType": "consent.accepted",
+      "content": "agreed"
+    }
+  ]
+}

hyperstudy-0.2.0/tests/fixtures/warnings_response.json

@@ -0,0 +1,19 @@
+{
+  "status": "success",
+  "metadata": {
+    "dataType": "events",
+    "scope": "experiment",
+    "scopeId": "exp_abc123",
+    "pagination": {
+      "total": 0,
+      "returned": 0,
+      "hasMore": false,
+      "limit": 1000,
+      "offset": 0
+    },
+    "_warnings": [
+      "MISSING_INDEX: Query for experiment/exp_abc123 requires a composite Firestore index. Results may be incomplete."
+    ]
+  },
+  "data": []
+}

{hyperstudy-0.1.0 → hyperstudy-0.2.0}/tests/test_client.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+import warnings
 
 import pandas as pd
 import pytest
@@ -200,22 +201,29 @@ def test_get_sync_with_aggregation(api_key, events_response):
 
 
 @responses.activate
-def test_get_all_data(api_key, events_response):
+def test_get_all_data(api_key, events_response, pre_experiment_response):
     """get_all_data returns a dict of DataFrames."""
     # Mock all data type endpoints for participant scope
     for dtype in ("events", "recordings", "chat", "videochat", "sync",
-                  "ratings/continuous", "components"):
+                  "ratings/continuous", "ratings/sparse", "components"):
         responses.get(
             f"{BASE_URL}/data/{dtype}/participant/user_1",
             json=events_response,
             status=200,
         )
+    # Questionnaire, instructions, consent all hit the events endpoint
+    # with different category params — responses matches by URL, so we
+    # need a single mock for the events endpoint that handles all calls.
+    # The events endpoint is already mocked above, so the category-filtered
+    # calls will also match it.
     client = HyperStudy(api_key=api_key, base_url=BASE_URL)
     result = client.get_all_data("user_1", room_id="room_xyz")
 
     assert isinstance(result, dict)
     assert set(result.keys()) == {
-        "events", "recordings", "chat", "videochat", "sync", "ratings", "components"
+        "events", "recordings", "chat", "videochat", "sync",
+        "ratings_continuous", "ratings_sparse", "components",
+        "questionnaire", "instructions", "consent",
     }
     for v in result.values():
         assert isinstance(v, pd.DataFrame)
@@ -263,3 +271,162 @@ def test_invalid_scope_raises_value_error(api_key):
     client = HyperStudy(api_key=api_key, base_url=BASE_URL)
     with pytest.raises(ValueError, match="invalid"):
         client.get_events("exp_abc123", scope="invalid", limit=100)
+
+
+# ------------------------------------------------------------------
+# Convenience methods — questionnaire, instructions, consent
+# ------------------------------------------------------------------
+
+
+@responses.activate
+def test_get_questionnaire(api_key, events_response):
+    """get_questionnaire passes category=questionnaire in the URL."""
+    responses.get(
+        f"{BASE_URL}/data/events/experiment/exp_abc123",
+        json=events_response,
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    df = client.get_questionnaire("exp_abc123", limit=1000)
+    assert isinstance(df, pd.DataFrame)
+    assert "category=questionnaire" in responses.calls[0].request.url
+
+
+@responses.activate
+def test_get_instructions_filters_by_event_type(api_key, pre_experiment_response):
+    """get_instructions fetches pre_experiment events and filters to instructions."""
+    responses.get(
+        f"{BASE_URL}/data/events/experiment/exp_abc123",
+        json=pre_experiment_response,
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    df = client.get_instructions("exp_abc123", limit=1000)
+
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 2  # 2 instruction events out of 4 pre_experiment
+    assert "category=pre_experiment" in responses.calls[0].request.url
+    assert all(et.startswith("instructions.") for et in df["eventType"])
+
+
+@responses.activate
+def test_get_consent_filters_by_event_type(api_key, pre_experiment_response):
+    """get_consent fetches pre_experiment events and filters to consent."""
+    responses.get(
+        f"{BASE_URL}/data/events/experiment/exp_abc123",
+        json=pre_experiment_response,
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    df = client.get_consent("exp_abc123", limit=1000)
+
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 2  # 2 consent events out of 4 pre_experiment
+    assert all(et.startswith("consent.") for et in df["eventType"])
+
+
+@responses.activate
+def test_get_instructions_dict_output(api_key, pre_experiment_response):
+    """get_instructions with output='dict' returns filtered list."""
+    responses.get(
+        f"{BASE_URL}/data/events/experiment/exp_abc123",
+        json=pre_experiment_response,
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    data = client.get_instructions("exp_abc123", output="dict", limit=1000)
+
+    assert isinstance(data, list)
+    assert len(data) == 2
+    assert all(e["eventType"].startswith("instructions.") for e in data)
+
+
+# ------------------------------------------------------------------
+# Deployments
+# ------------------------------------------------------------------
+
+
+@responses.activate
+def test_list_deployments(api_key, deployments_list_response):
+    """list_deployments hits /deployments and returns a DataFrame."""
+    responses.get(
+        f"{BASE_URL}/deployments",
+        json=deployments_list_response,
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    df = client.list_deployments()
+
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 2
+    assert "dep_001" in df["id"].values
+
+
+@responses.activate
+def test_list_deployments_with_filters(api_key, deployments_list_response):
+    """list_deployments passes experiment_id and status as query params."""
+    responses.get(
+        f"{BASE_URL}/deployments",
+        json=deployments_list_response,
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    client.list_deployments(experiment_id="exp_abc123", status="active")
+
+    url = responses.calls[0].request.url
+    assert "experimentId=exp_abc123" in url
+    assert "status=active" in url
+
+
+@responses.activate
+def test_get_deployment(api_key, deployment_single_response):
+    """get_deployment returns a single deployment dict."""
+    responses.get(
+        f"{BASE_URL}/deployments/dep_001",
+        json=deployment_single_response,
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    result = client.get_deployment("dep_001")
+
+    assert isinstance(result, dict)
+    assert result["id"] == "dep_001"
+    assert result["name"] == "Pilot Study"
+
+
+@responses.activate
+def test_get_deployment_sessions(api_key, deployment_sessions_response):
+    """get_deployment_sessions returns sessions as a DataFrame."""
+    responses.get(
+        f"{BASE_URL}/deployments/dep_001/sessions",
+        json=deployment_sessions_response,
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    df = client.get_deployment_sessions("dep_001")
+
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 2
+    assert "room_001" in df["id"].values
+
+
+# ------------------------------------------------------------------
+# API warnings
+# ------------------------------------------------------------------
+
+
+@responses.activate
+def test_api_warnings_surfaced(api_key, warnings_response):
+    """API _warnings in metadata are surfaced via Python warnings."""
+    responses.get(
+        f"{BASE_URL}/data/events/experiment/exp_abc123",
+        json=warnings_response,
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        client.get_events("exp_abc123", limit=1000)
+
+    assert len(caught) == 1
+    assert "MISSING_INDEX" in str(caught[0].message)

hyperstudy-0.1.0/.github/workflows/publish.yml

@@ -1,27 +0,0 @@
-name: Publish to PyPI
-
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      id-token: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Install build tools
-        run: pip install build
-
-      - name: Build package
-        run: python -m build
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1