clarity-api-sdk-python 0.3.38__tar.gz → 0.4.1__tar.gz

{clarity_api_sdk_python-0.3.38 → clarity_api_sdk_python-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clarity-api-sdk-python
-Version: 0.3.38
+Version: 0.4.1
 Summary: A Python SDK to connect to the CTI Clarity API server.
 Author-email: "Chesapeake Technology Inc." <support@chesapeaketech.com>
 Project-URL: Homepage, https://github.com/chesapeake-tech/clarity-api-sdk-python

{clarity_api_sdk_python-0.3.38 → clarity_api_sdk_python-0.4.1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "clarity-api-sdk-python"
-version = "0.3.38"
+version = "0.4.1"
 authors = [
   { name="Chesapeake Technology Inc.", email="support@chesapeaketech.com" },
 ]

{clarity_api_sdk_python-0.3.38 → clarity_api_sdk_python-0.4.1}/src/clarity_api_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clarity-api-sdk-python
-Version: 0.3.38
+Version: 0.4.1
 Summary: A Python SDK to connect to the CTI Clarity API server.
 Author-email: "Chesapeake Technology Inc." <support@chesapeaketech.com>
 Project-URL: Homepage, https://github.com/chesapeake-tech/clarity-api-sdk-python

{clarity_api_sdk_python-0.3.38 → clarity_api_sdk_python-0.4.1}/src/clarity_api_sdk_python.egg-info/SOURCES.txt

@@ -51,6 +51,8 @@ src/cti/model/source.py
 src/cti/model/survey.py
 src/cti/model/target.py
 src/cti/model/tow_system.py
+src/cti/model/user_layer.py
 tests/test_cli.py
+tests/test_raw_file_device_mapping_model.py
 tests/test_sdk_async_methods.py
 tests/test_sdk_methods.py

{clarity_api_sdk_python-0.3.38 → clarity_api_sdk_python-0.4.1}/src/cti/api/sonar_wiz_api.py

@@ -99,6 +99,10 @@ from cti.model.target import TargetUpdate
 from cti.model.tow_system import TowSystem
 from cti.model.tow_system import TowSystemCreate
 from cti.model.tow_system import TowSystemUpdate
+from cti.model.user_layer import UserLayer
+from cti.model.user_layer import UserLayerCreate
+from cti.model.user_layer import UserLayerUpdate
+from cti.model.user_layer import UserLayerWithUpload
 
 from .client import ClarityApiClient
 
@@ -353,13 +357,37 @@ class SonarWizApi:
         response.raise_for_status()
         return RawFileDeviceMapping.model_validate(response.json())
 
-    def list_raw_file_device_mappings(self) -> list[RawFileDeviceMapping]:
-        """List all raw file device mappings.
+    def get_raw_file_device_mappings(
+        self,
+        *,
+        raw_file_id: UUID | str | None = None,
+        device_id: UUID | str | None = None,
+    ) -> list[RawFileDeviceMapping]:
+        """Get raw file device mappings filtered by raw file or device.
+
+        At least one of ``raw_file_id`` / ``device_id`` must be provided —
+        the server requires a filter and returns 400 otherwise.
+
+        Args:
+            raw_file_id: Match only mappings for this raw file.
+            device_id: Match only mappings for this device.
 
         Returns:
-            List of raw file device mapping instances.
+            List of matching raw file device mappings (empty if none match).
+
+        Raises:
+            ValueError: If neither ``raw_file_id`` nor ``device_id`` is given.
         """
-        response = self._client.get("/api/v1/raw-file-device-mappings")
+        if raw_file_id is None and device_id is None:
+            raise ValueError(
+                "At least one of raw_file_id or device_id must be provided."
+            )
+        params: dict[str, str] = {}
+        if raw_file_id is not None:
+            params["raw_file_id"] = str(raw_file_id)
+        if device_id is not None:
+            params["device_id"] = str(device_id)
+        response = self._client.get("/api/v1/raw-file-device-mappings", params=params)
         response.raise_for_status()
         return [RawFileDeviceMapping.model_validate(item) for item in response.json()]
 
@@ -1975,13 +2003,34 @@ class SonarWizApi:
         response.raise_for_status()
         return ProcessingLog.model_validate(response.json())
 
-    def list_processing_logs(self) -> list[ProcessingLog]:
-        """List all processing logs.
+    def list_processing_logs(
+        self,
+        *,
+        raw_file_id: UUID | str | None = None,
+        survey_id: UUID | str | None = None,
+        processing_step: str | None = None,
+    ) -> list[ProcessingLog]:
+        """List processing logs, optionally filtered.
+
+        Filters compose: each provided filter narrows the result set.
+
+        Args:
+            raw_file_id: Match only logs for this raw file.
+            survey_id: Match only logs for this survey.
+            processing_step: Match only logs with this processing step
+                (e.g. ``"scan"``, ``"ingest"``, ``"products"``).
 
         Returns:
-            List of processing log instances.
+            List of matching processing logs (empty list if none match).
         """
-        response = self._client.get("/api/v1/processing-logs")
+        params: dict[str, str] = {}
+        if raw_file_id is not None:
+            params["raw_file_id"] = str(raw_file_id)
+        if survey_id is not None:
+            params["survey_id"] = str(survey_id)
+        if processing_step is not None:
+            params["processing_step"] = processing_step
+        response = self._client.get("/api/v1/processing-logs", params=params or None)
         response.raise_for_status()
         return [ProcessingLog.model_validate(item) for item in response.json()]
 
@@ -2004,6 +2053,81 @@ class SonarWizApi:
         response.raise_for_status()
         return ProcessingLog.model_validate(response.json())
 
+    # ── User Layers ──────────────────────────────────────────────────────
+
+    def create_user_layer(self, user_layer: UserLayerCreate) -> UserLayerWithUpload:
+        """Create a new user layer and initiate upload.
+
+        Args:
+            user_layer: User layer creation data.
+
+        Returns:
+            Created user layer instance with upload information.
+        """
+        response = self._client.post(
+            "/api/v1/user-layers/upload",
+            json=user_layer.model_dump(mode="json"),
+        )
+        response.raise_for_status()
+        return UserLayerWithUpload.model_validate(response.json())
+
+    def get_user_layer(self, user_layer_id: UUID) -> UserLayer:
+        """Fetch a user layer by ID.
+
+        Args:
+            user_layer_id: User layer UUID to fetch.
+
+        Returns:
+            UserLayer instance.
+        """
+        response = self._client.get(f"/api/v1/user-layers/{user_layer_id}")
+        response.raise_for_status()
+        return UserLayer.model_validate(response.json())
+
+    def list_user_layers(self, project_id: UUID) -> list[UserLayer]:
+        """List all user layers for a project.
+
+        Args:
+            project_id: Project UUID to filter by.
+
+        Returns:
+            List of user layer instances.
+        """
+        response = self._client.get(
+            "/api/v1/user-layers",
+            params={"project_id": str(project_id)},
+        )
+        response.raise_for_status()
+        return [UserLayer.model_validate(item) for item in response.json()]
+
+    def update_user_layer(
+        self, user_layer_id: UUID, user_layer: UserLayerUpdate
+    ) -> UserLayer:
+        """Update a user layer.
+
+        Args:
+            user_layer_id: User layer UUID to update.
+            user_layer: User layer update data.
+
+        Returns:
+            Updated user layer instance.
+        """
+        response = self._client.patch(
+            f"/api/v1/user-layers/{user_layer_id}",
+            json=user_layer.model_dump(mode="json", exclude_none=True),
+        )
+        response.raise_for_status()
+        return UserLayer.model_validate(response.json())
+
+    def delete_user_layer(self, user_layer_id: UUID) -> None:
+        """Delete a user layer.
+
+        Args:
+            user_layer_id: User layer UUID to delete.
+        """
+        response = self._client.delete(f"/api/v1/user-layers/{user_layer_id}")
+        response.raise_for_status()
+
     # ── Processing Jobs ──────────────────────────────────────────────────
 
     def create_job(self, job_data: ProcessingJobCreate) -> ProcessingJob:

{clarity_api_sdk_python-0.3.38 → clarity_api_sdk_python-0.4.1}/src/cti/api/sonar_wiz_async_api.py

@@ -97,6 +97,10 @@ from cti.model.target import TargetUpdate
 from cti.model.tow_system import TowSystem
 from cti.model.tow_system import TowSystemCreate
 from cti.model.tow_system import TowSystemUpdate
+from cti.model.user_layer import UserLayer
+from cti.model.user_layer import UserLayerCreate
+from cti.model.user_layer import UserLayerUpdate
+from cti.model.user_layer import UserLayerWithUpload
 
 from .async_client import ClarityApiAsyncClient
 
@@ -353,13 +357,39 @@ class SonarWizAsyncApi:
         response.raise_for_status()
         return RawFileDeviceMapping.model_validate(response.json())
 
-    async def list_raw_file_device_mappings(self) -> list[RawFileDeviceMapping]:
-        """List all raw file device mappings.
+    async def get_raw_file_device_mappings(
+        self,
+        *,
+        raw_file_id: UUID | str | None = None,
+        device_id: UUID | str | None = None,
+    ) -> list[RawFileDeviceMapping]:
+        """Get raw file device mappings filtered by raw file or device.
+
+        At least one of ``raw_file_id`` / ``device_id`` must be provided —
+        the server requires a filter and returns 400 otherwise.
+
+        Args:
+            raw_file_id: Match only mappings for this raw file.
+            device_id: Match only mappings for this device.
 
         Returns:
-            List of raw file device mapping instances.
+            List of matching raw file device mappings (empty if none match).
+
+        Raises:
+            ValueError: If neither ``raw_file_id`` nor ``device_id`` is given.
         """
-        response = await self._client.get("/api/v1/raw-file-device-mappings")
+        if raw_file_id is None and device_id is None:
+            raise ValueError(
+                "At least one of raw_file_id or device_id must be provided."
+            )
+        params: dict[str, str] = {}
+        if raw_file_id is not None:
+            params["raw_file_id"] = str(raw_file_id)
+        if device_id is not None:
+            params["device_id"] = str(device_id)
+        response = await self._client.get(
+            "/api/v1/raw-file-device-mappings", params=params
+        )
         response.raise_for_status()
         return [RawFileDeviceMapping.model_validate(item) for item in response.json()]
 
@@ -2023,13 +2053,36 @@ class SonarWizAsyncApi:
         response.raise_for_status()
         return ProcessingLog.model_validate(response.json())
 
-    async def list_processing_logs(self) -> list[ProcessingLog]:
-        """List all processing logs.
+    async def list_processing_logs(
+        self,
+        *,
+        raw_file_id: UUID | str | None = None,
+        survey_id: UUID | str | None = None,
+        processing_step: str | None = None,
+    ) -> list[ProcessingLog]:
+        """List processing logs, optionally filtered.
+
+        Filters compose: each provided filter narrows the result set.
+
+        Args:
+            raw_file_id: Match only logs for this raw file.
+            survey_id: Match only logs for this survey.
+            processing_step: Match only logs with this processing step
+                (e.g. ``"scan"``, ``"ingest"``, ``"products"``).
 
         Returns:
-            List of processing log instances.
+            List of matching processing logs (empty list if none match).
         """
-        response = await self._client.get("/api/v1/processing-logs")
+        params: dict[str, str] = {}
+        if raw_file_id is not None:
+            params["raw_file_id"] = str(raw_file_id)
+        if survey_id is not None:
+            params["survey_id"] = str(survey_id)
+        if processing_step is not None:
+            params["processing_step"] = processing_step
+        response = await self._client.get(
+            "/api/v1/processing-logs", params=params or None
+        )
         response.raise_for_status()
         return [ProcessingLog.model_validate(item) for item in response.json()]
 
@@ -2052,6 +2105,83 @@ class SonarWizAsyncApi:
         response.raise_for_status()
         return ProcessingLog.model_validate(response.json())
 
+    # ── User Layers ──────────────────────────────────────────────────────
+
+    async def create_user_layer(
+        self, user_layer: UserLayerCreate
+    ) -> UserLayerWithUpload:
+        """Create a new user layer and initiate upload.
+
+        Args:
+            user_layer: User layer creation data.
+
+        Returns:
+            Created user layer instance with upload information.
+        """
+        response = await self._client.post(
+            "/api/v1/user-layers/upload",
+            json=user_layer.model_dump(mode="json"),
+        )
+        response.raise_for_status()
+        return UserLayerWithUpload.model_validate(response.json())
+
+    async def get_user_layer(self, user_layer_id: UUID) -> UserLayer:
+        """Fetch a user layer by ID.
+
+        Args:
+            user_layer_id: User layer UUID to fetch.
+
+        Returns:
+            UserLayer instance.
+        """
+        response = await self._client.get(f"/api/v1/user-layers/{user_layer_id}")
+        response.raise_for_status()
+        return UserLayer.model_validate(response.json())
+
+    async def list_user_layers(self, project_id: UUID) -> list[UserLayer]:
+        """List all user layers for a project.
+
+        Args:
+            project_id: Project UUID to filter by.
+
+        Returns:
+            List of user layer instances.
+        """
+        response = await self._client.get(
+            "/api/v1/user-layers",
+            params={"project_id": str(project_id)},
+        )
+        response.raise_for_status()
+        return [UserLayer.model_validate(item) for item in response.json()]
+
+    async def update_user_layer(
+        self, user_layer_id: UUID, user_layer: UserLayerUpdate
+    ) -> UserLayer:
+        """Update a user layer.
+
+        Args:
+            user_layer_id: User layer UUID to update.
+            user_layer: User layer update data.
+
+        Returns:
+            Updated user layer instance.
+        """
+        response = await self._client.patch(
+            f"/api/v1/user-layers/{user_layer_id}",
+            json=user_layer.model_dump(mode="json", exclude_none=True),
+        )
+        response.raise_for_status()
+        return UserLayer.model_validate(response.json())
+
+    async def delete_user_layer(self, user_layer_id: UUID) -> None:
+        """Delete a user layer.
+
+        Args:
+            user_layer_id: User layer UUID to delete.
+        """
+        response = await self._client.delete(f"/api/v1/user-layers/{user_layer_id}")
+        response.raise_for_status()
+
     # ── Processing Jobs ──────────────────────────────────────────────────
 
     async def create_job(self, job_data: ProcessingJobCreate) -> ProcessingJob:

{clarity_api_sdk_python-0.3.38 → clarity_api_sdk_python-0.4.1}/src/cti/cli/main.py

@@ -59,10 +59,14 @@ def upload(
         False, "--no-mappings", help="Skip automatic device mapping creation"
     ),
     sidescan_stream: str = typer.Option(
-        "0", "--sidescan-stream", help="Source stream identifier for sidescan device"
+        "xtf://sidescan(source=ping_header,pair=0)",
+        "--sidescan-stream",
+        help="Source URI for the sidescan stream identifier",
     ),
     gnss_stream: str = typer.Option(
-        "1", "--gnss-stream", help="Source stream identifier for GNSS device"
+        "xtf://position(source=ping_header,description=ship_position)",
+        "--gnss-stream",
+        help="Source URI for the GNSS stream identifier",
     ),
     output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ) -> None:
@@ -71,7 +75,22 @@ def upload(
     After uploading, automatically creates device mappings linking the file
     to the survey's sidescan and GNSS devices. Use --no-mappings to skip.
     """
-    from cti.model.raw_file_device_mapping import RawFileDeviceMappingCreate
+    from cti.model.raw_file_device_mapping import (
+        RawFileDeviceMappingCreate,
+        SourceSelection,
+        StreamIdentifier,
+    )
+
+    def _identifier_from_uri(uri: str, roles: tuple[str, ...]) -> StreamIdentifier:
+        return StreamIdentifier(
+            source=SourceSelection(available=[uri], selected=uri),
+            fields_by_source={
+                uri: {
+                    role: SourceSelection(available=[role], selected=role)
+                    for role in roles
+                }
+            },
+        )
 
     if not file.exists():
         typer.echo(f"Error: file not found: {file}", err=True)
@@ -115,9 +134,13 @@ def upload(
                 if not dt:
                     continue
                 if dt.enum_name == "sidescan_sonar":
-                    stream_id = sidescan_stream
+                    stream_id = _identifier_from_uri(
+                        sidescan_stream, ("samples", "timestamp")
+                    )
                 elif dt.enum_name == "gnss_gps_position_sensor":
-                    stream_id = gnss_stream
+                    stream_id = _identifier_from_uri(
+                        gnss_stream, ("position", "timestamp")
+                    )
                 else:
                     continue
 
@@ -130,7 +153,9 @@ def upload(
                         input_timezone=tz,
                     )
                 )
-                typer.echo(f"Mapped: {device.name} → stream {stream_id}")
+                typer.echo(
+                    f"Mapped: {device.name} → stream {stream_id.source.selected}"
+                )
                 mappings_created += 1
 
             if mappings_created == 0:

{clarity_api_sdk_python-0.3.38 → clarity_api_sdk_python-0.4.1}/src/cti/model/raw_file_device_mapping.py

@@ -7,20 +7,61 @@ from uuid import UUID
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 
+class SourceSelection(BaseModel):
+    """An ``{available, selected}`` pair.
+
+    Used at both levels of ``StreamIdentifier``: outer source URI and
+    inner field-role selection.
+
+    Attributes:
+        available: All candidate values produced by the scan.
+        selected: The currently chosen value; must be one of ``available``.
+    """
+
+    available: list[str]
+    selected: str
+
+
+class StreamIdentifier(BaseModel):
+    """Two-level source / field selection persisted on RawFileDeviceMapping.
+
+    Mirrors the shape produced by the engine's manifest serializer for
+    one stream descriptor (see clarity-engine
+    ``pipeline/ingest/manifest_serializer.py``):
+
+    - ``source`` — which packet-level source within the file feeds this
+      device (e.g., ``xtf://sidescan(source=ping_header,pair=0)``).
+    - ``fields_by_source`` — for each available source URI, which raw
+      field provides each role (``samples``, ``timestamp``, ``position``,
+      …).
+
+    Attributes:
+        source: Outer source-URI selection.
+        fields_by_source: Per-source role → field selection. Outer key is
+            the source URI; inner key is the role name.
+    """
+
+    source: SourceSelection
+    fields_by_source: dict[str, dict[str, SourceSelection]]
+
+
 class RawFileDeviceMappingBase(BaseModel):
     """Base model for raw file device mapping.
 
     Attributes:
         raw_file_id: Foreign key reference to RawFile.
         device_id: Foreign key reference to Device.
-        source_stream_identifier: Identifier for the source stream.
+        source_stream_identifier: Two-level source / field-role selection.
+        auto_mapped: True for system-generated mappings, False for user
+            overrides. Defaults to True.
         input_srid: Spatial reference ID for the input data.
         input_timezone: IANA timezone name for the input data (e.g. Etc/UTC).
     """
 
     raw_file_id: UUID
     device_id: UUID
-    source_stream_identifier: str
+    source_stream_identifier: StreamIdentifier
+    auto_mapped: bool = True
     input_srid: int = Field(ge=2000, le=900913)
     input_timezone: str
 

clarity_api_sdk_python-0.4.1/src/cti/model/user_layer.py

@@ -0,0 +1,125 @@
+"""Pydantic models for user layer. User-uploaded geospatial layers associated with a project."""
+
+from datetime import datetime
+from enum import Enum
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+
+
+class UserLayerState(str, Enum):
+    """Status of a user layer."""
+
+    UPLOADING = "uploading"
+    READY = "ready"
+    ERROR = "error"
+
+
+class UserLayerType(str, Enum):
+    """Supported user layer file types."""
+
+    GEOJSON = "geojson"
+    KML = "kml"
+    KMZ = "kmz"
+    SHAPEFILE = "shapefile"
+    GPX = "gpx"
+    CSV = "csv"
+    GEOTIFF = "geotiff"
+    BAG = "bag"
+    LAS = "las"
+    LAZ = "laz"
+    PLY = "ply"
+    PCD = "pcd"
+    MAGNETOMETRY = "magnetometry"
+
+
+class UserLayerBase(BaseModel):
+    """Base model for user layer data.
+
+    Attributes:
+        project_id: Foreign key reference to Project.
+        layer_name: Display name for the layer.
+        layer_type: Type of the user layer file.
+        file_name: Name of the uploaded file.
+        file_size: Size of the uploaded file in bytes.
+        style: Optional styling configuration for the layer.
+        metadata: Optional metadata for the layer.
+        sort_order: Display sort order.
+    """
+
+    project_id: UUID
+    layer_name: str
+    layer_type: UserLayerType
+    file_name: str | None = None
+    file_size: int | None = None
+    style: dict | None = None
+    metadata: dict | None = None
+    sort_order: int = 0
+
+
+class UserLayerCreate(UserLayerBase):
+    """Model for creating a user layer."""
+
+
+class UserLayerUpdate(BaseModel):
+    """Model for updating a user layer.
+
+    Attributes:
+        layer_name: Optional updated display name.
+        style: Optional updated styling configuration.
+        metadata: Optional updated metadata.
+        sort_order: Optional updated sort order.
+        state: Optional updated state.
+    """
+
+    layer_name: str | None = None
+    style: dict | None = None
+    metadata: dict | None = None
+    sort_order: int | None = None
+    state: UserLayerState | None = None
+
+
+class UserLayer(UserLayerBase):
+    """Model for user layer data with database fields.
+
+    Attributes:
+        user_layer_id: Unique identifier for the user layer.
+        user_id: ID of the user who created the layer.
+        state: Upload state (uploading, ready, error).
+        uri: URI for the layer file storage location.
+        upload_id: S3 multipart upload ID (present while uploading, cleared when complete).
+        created_date: Timestamp when the layer was created.
+        updated_date: Timestamp when the layer was last updated.
+        updated_by: ID of the user who last updated the layer.
+    """
+
+    user_layer_id: UUID
+    user_id: str
+    state: UserLayerState = UserLayerState.UPLOADING
+    uri: str | None = None
+    upload_id: str | None = None
+    created_date: datetime
+    updated_date: datetime
+    updated_by: str
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class UserLayerWithUpload(UserLayer):
+    """UserLayer response for the create-with-upload endpoint.
+
+    The endpoint initiates an S3 multipart upload before returning, so `uri`
+    and `upload_id` are guaranteed to be present. Overrides those fields to
+    be non-nullable so callers don't have to defensively check.
+
+    Attributes:
+        uri: S3 URI for the layer file storage location. Always populated.
+        upload_id: S3 multipart upload ID. Always populated; clients pass it
+            to subsequent part-upload and complete-upload calls.
+    """
+
+    # Tightening parent's `str | None` to required `str`. Pyright flags the
+    # type narrowing as an override issue; Pydantic treats the bare field
+    # annotation as required at runtime, which is what we want.
+    uri: str  # type: ignore[assignment]
+    upload_id: str  # type: ignore[assignment]

clarity_api_sdk_python-0.4.1/tests/test_raw_file_device_mapping_model.py

@@ -0,0 +1,110 @@
+"""Round-trip tests for the RawFileDeviceMapping SDK Pydantic model.
+
+Phase II Step 10 reshaped ``source_stream_identifier`` from a free-form
+string to a nested ``StreamIdentifier``. These tests pin the wire shape
+the engine and server already agree on so future drift fails loudly.
+
+See clarity-server#104 / #105 and
+designs/spec-file-prescan-stream-mapping.md §lines 489–495, 939–953.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+import pytest
+from pydantic import ValidationError
+
+from cti.model.raw_file_device_mapping import (
+    RawFileDeviceMappingCreate,
+    SourceSelection,
+    StreamIdentifier,
+)
+
+
+_SOURCE_URI = "xtf://sidescan(source=ping_header,pair=0)"
+_SAMPLE_IDENTIFIER_DICT = {
+    "source": {"available": [_SOURCE_URI], "selected": _SOURCE_URI},
+    "fields_by_source": {
+        _SOURCE_URI: {
+            "samples": {"available": ["samples"], "selected": "samples"},
+            "timestamp": {"available": ["timestamp"], "selected": "timestamp"},
+        }
+    },
+}
+
+
+def test_stream_identifier_round_trips_from_dict() -> None:
+    """A dict in the manifest-serializer shape parses and serializes back unchanged."""
+    ident = StreamIdentifier.model_validate(_SAMPLE_IDENTIFIER_DICT)
+
+    assert isinstance(ident.source, SourceSelection)
+    assert ident.source.selected == _SOURCE_URI
+    assert ident.fields_by_source[_SOURCE_URI]["samples"].selected == "samples"
+
+    assert ident.model_dump() == _SAMPLE_IDENTIFIER_DICT
+
+
+def test_create_payload_round_trips_through_json() -> None:
+    """End-to-end: build a Create model, serialize to JSON, parse it back."""
+    payload = RawFileDeviceMappingCreate(
+        raw_file_id=uuid4(),
+        device_id=uuid4(),
+        source_stream_identifier=StreamIdentifier.model_validate(
+            _SAMPLE_IDENTIFIER_DICT
+        ),
+        input_srid=4326,
+        input_timezone="Etc/UTC",
+    )
+
+    parsed = RawFileDeviceMappingCreate.model_validate_json(payload.model_dump_json())
+    assert parsed == payload
+    assert parsed.auto_mapped is True
+
+
+def test_auto_mapped_defaults_to_true_when_omitted() -> None:
+    """``auto_mapped`` is a system-generated default, not required from clients."""
+    payload = RawFileDeviceMappingCreate.model_validate(
+        {
+            "raw_file_id": str(uuid4()),
+            "device_id": str(uuid4()),
+            "source_stream_identifier": _SAMPLE_IDENTIFIER_DICT,
+            "input_srid": 4326,
+            "input_timezone": "Etc/UTC",
+        }
+    )
+    assert payload.auto_mapped is True
+
+
+def test_auto_mapped_false_persists_for_user_overrides() -> None:
+    """User-supplied overrides must round-trip ``auto_mapped: false``."""
+    payload = RawFileDeviceMappingCreate.model_validate(
+        {
+            "raw_file_id": str(uuid4()),
+            "device_id": str(uuid4()),
+            "source_stream_identifier": _SAMPLE_IDENTIFIER_DICT,
+            "auto_mapped": False,
+            "input_srid": 4326,
+            "input_timezone": "Etc/UTC",
+        }
+    )
+    assert payload.auto_mapped is False
+
+
+def test_string_source_stream_identifier_is_rejected() -> None:
+    """The pre-Phase-II free-form string form must no longer validate.
+
+    Pins the breaking change so a future regression that loosens the type
+    back to ``str`` fails this test instead of silently re-allowing
+    unstructured identifiers.
+    """
+    with pytest.raises(ValidationError):
+        RawFileDeviceMappingCreate.model_validate(
+            {
+                "raw_file_id": str(uuid4()),
+                "device_id": str(uuid4()),
+                "source_stream_identifier": "channel-0",
+                "input_srid": 4326,
+                "input_timezone": "Etc/UTC",
+            }
+        )

{clarity_api_sdk_python-0.3.38 → clarity_api_sdk_python-0.4.1}/tests/test_sdk_async_methods.py

@@ -18,11 +18,16 @@ from .conftest import (
     RAW_FILE_ID,
     SURVEY_ID,
     make_job_json,
+    make_processing_log_json,
+    make_raw_file_device_mapping_json,
     make_raw_file_json,
     make_raw_file_with_upload_json,
 )
 
 
+DEVICE_ID = UUID("00000000-0000-0000-0000-000000000099")
+
+
 def _mock_response(
     json_data: dict, status_code: int = 200, headers: dict | None = None
 ) -> MagicMock:
@@ -219,3 +224,148 @@ async def test_wait_for_job_raises_on_timeout():
         with patch.object(loop, "time", side_effect=mock_time):
             with pytest.raises(TimeoutError, match="did not complete"):
                 await api.wait_for_job(job_id=JOB_ID, timeout=10)
+
+
+# ── list_processing_logs filter kwargs (WI-0106 A1) ─────────────────────
+
+
+@pytest.mark.asyncio
+async def test_list_processing_logs_no_filters_omits_params():
+    """No kwargs → request sent with params=None (preserves existing behavior)."""
+    client = AsyncMock()
+    client.get.return_value = _mock_response([make_processing_log_json()])
+
+    api = SonarWizAsyncApi(client)
+    logs = await api.list_processing_logs()
+
+    assert len(logs) == 1
+    client.get.assert_awaited_once_with("/api/v1/processing-logs", params=None)
+
+
+@pytest.mark.asyncio
+async def test_list_processing_logs_all_filters_passed_as_query_params():
+    """All three filters compose into the query string; UUIDs stringified."""
+    client = AsyncMock()
+    client.get.return_value = _mock_response(
+        [make_processing_log_json(processing_step="scan", result='{"streams":[]}')]
+    )
+
+    api = SonarWizAsyncApi(client)
+    logs = await api.list_processing_logs(
+        raw_file_id=RAW_FILE_ID,
+        survey_id=SURVEY_ID,
+        processing_step="scan",
+    )
+
+    client.get.assert_awaited_once_with(
+        "/api/v1/processing-logs",
+        params={
+            "raw_file_id": str(RAW_FILE_ID),
+            "survey_id": str(SURVEY_ID),
+            "processing_step": "scan",
+        },
+    )
+    assert logs[0].processing_step == "scan"
+    assert logs[0].result == '{"streams":[]}'
+    assert logs[0].processing_hash == "a" * 64
+
+
+@pytest.mark.asyncio
+async def test_list_processing_logs_partial_filter_only_includes_provided():
+    """Unset filters are omitted from the query string."""
+    client = AsyncMock()
+    client.get.return_value = _mock_response([])
+
+    api = SonarWizAsyncApi(client)
+    logs = await api.list_processing_logs(
+        raw_file_id=RAW_FILE_ID, processing_step="scan"
+    )
+
+    client.get.assert_awaited_once_with(
+        "/api/v1/processing-logs",
+        params={"raw_file_id": str(RAW_FILE_ID), "processing_step": "scan"},
+    )
+    assert logs == []
+
+
+@pytest.mark.asyncio
+async def test_list_processing_logs_accepts_string_uuid():
+    """String UUIDs are accepted and stringified the same way."""
+    client = AsyncMock()
+    client.get.return_value = _mock_response([])
+
+    api = SonarWizAsyncApi(client)
+    await api.list_processing_logs(raw_file_id=str(RAW_FILE_ID))
+
+    client.get.assert_awaited_once_with(
+        "/api/v1/processing-logs",
+        params={"raw_file_id": str(RAW_FILE_ID)},
+    )
+
+
+# ── get_raw_file_device_mappings filter kwargs (#23) ────────────────────
+
+
+@pytest.mark.asyncio
+async def test_get_raw_file_device_mappings_requires_a_filter():
+    """Calling with neither filter raises ValueError before touching the wire."""
+    client = AsyncMock()
+    api = SonarWizAsyncApi(client)
+
+    with pytest.raises(ValueError, match="raw_file_id or device_id"):
+        await api.get_raw_file_device_mappings()
+
+    client.get.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_get_raw_file_device_mappings_filters_by_raw_file_id():
+    """raw_file_id filter is sent as a query param; UUID stringified."""
+    client = AsyncMock()
+    client.get.return_value = _mock_response(
+        [make_raw_file_device_mapping_json(device_id=DEVICE_ID)]
+    )
+
+    api = SonarWizAsyncApi(client)
+    mappings = await api.get_raw_file_device_mappings(raw_file_id=RAW_FILE_ID)
+
+    client.get.assert_awaited_once_with(
+        "/api/v1/raw-file-device-mappings",
+        params={"raw_file_id": str(RAW_FILE_ID)},
+    )
+    assert len(mappings) == 1
+    assert mappings[0].raw_file_id == RAW_FILE_ID
+    assert mappings[0].device_id == DEVICE_ID
+
+
+@pytest.mark.asyncio
+async def test_get_raw_file_device_mappings_filters_by_device_id():
+    """device_id filter is sent alone when raw_file_id is omitted."""
+    client = AsyncMock()
+    client.get.return_value = _mock_response([])
+
+    api = SonarWizAsyncApi(client)
+    mappings = await api.get_raw_file_device_mappings(device_id=DEVICE_ID)
+
+    client.get.assert_awaited_once_with(
+        "/api/v1/raw-file-device-mappings",
+        params={"device_id": str(DEVICE_ID)},
+    )
+    assert mappings == []
+
+
+@pytest.mark.asyncio
+async def test_get_raw_file_device_mappings_accepts_string_uuids():
+    """String UUIDs are accepted and stringified the same way."""
+    client = AsyncMock()
+    client.get.return_value = _mock_response([])
+
+    api = SonarWizAsyncApi(client)
+    await api.get_raw_file_device_mappings(
+        raw_file_id=str(RAW_FILE_ID), device_id=str(DEVICE_ID)
+    )
+
+    client.get.assert_awaited_once_with(
+        "/api/v1/raw-file-device-mappings",
+        params={"raw_file_id": str(RAW_FILE_ID), "device_id": str(DEVICE_ID)},
+    )

{clarity_api_sdk_python-0.3.38 → clarity_api_sdk_python-0.4.1}/tests/test_sdk_methods.py

@@ -19,11 +19,16 @@ from .conftest import (
     RAW_FILE_ID,
     SURVEY_ID,
     make_job_json,
+    make_processing_log_json,
+    make_raw_file_device_mapping_json,
     make_raw_file_json,
     make_raw_file_with_upload_json,
 )
 
 
+DEVICE_ID = UUID("00000000-0000-0000-0000-000000000099")
+
+
 def _mock_response(
     json_data: dict, status_code: int = 200, headers: dict | None = None
 ) -> MagicMock:
@@ -262,3 +267,121 @@ class TestWaitForJob:
                 mock_mono.side_effect = [0.0, 0.0, 0.0, 100.0]
                 with pytest.raises(TimeoutError, match="did not complete"):
                     api.wait_for_job(job_id=JOB_ID, timeout=10)
+
+
+# ── list_processing_logs filter kwargs (WI-0106 A1) ─────────────────────
+
+
+def test_list_processing_logs_no_filters_omits_params():
+    """No kwargs → request sent with params=None."""
+    client = MagicMock()
+    client.get.return_value = _mock_response([make_processing_log_json()])
+
+    api = SonarWizApi(client)
+    logs = api.list_processing_logs()
+
+    assert len(logs) == 1
+    client.get.assert_called_once_with("/api/v1/processing-logs", params=None)
+
+
+def test_list_processing_logs_all_filters_passed_as_query_params():
+    """All three filters compose into the query string."""
+    client = MagicMock()
+    client.get.return_value = _mock_response(
+        [make_processing_log_json(processing_step="scan")]
+    )
+
+    api = SonarWizApi(client)
+    api.list_processing_logs(
+        raw_file_id=RAW_FILE_ID,
+        survey_id=SURVEY_ID,
+        processing_step="scan",
+    )
+
+    client.get.assert_called_once_with(
+        "/api/v1/processing-logs",
+        params={
+            "raw_file_id": str(RAW_FILE_ID),
+            "survey_id": str(SURVEY_ID),
+            "processing_step": "scan",
+        },
+    )
+
+
+def test_list_processing_logs_partial_filter_only_includes_provided():
+    """Unset filters are omitted from the query string."""
+    client = MagicMock()
+    client.get.return_value = _mock_response([])
+
+    api = SonarWizApi(client)
+    logs = api.list_processing_logs(survey_id=SURVEY_ID)
+
+    client.get.assert_called_once_with(
+        "/api/v1/processing-logs",
+        params={"survey_id": str(SURVEY_ID)},
+    )
+    assert logs == []
+
+
+# ── get_raw_file_device_mappings filter kwargs (#23) ────────────────────
+
+
+def test_get_raw_file_device_mappings_requires_a_filter():
+    """Calling with neither filter raises ValueError before touching the wire."""
+    client = MagicMock()
+    api = SonarWizApi(client)
+
+    with pytest.raises(ValueError, match="raw_file_id or device_id"):
+        api.get_raw_file_device_mappings()
+
+    client.get.assert_not_called()
+
+
+def test_get_raw_file_device_mappings_filters_by_raw_file_id():
+    """raw_file_id filter is sent as a query param; UUID stringified."""
+    client = MagicMock()
+    client.get.return_value = _mock_response(
+        [make_raw_file_device_mapping_json(device_id=DEVICE_ID)]
+    )
+
+    api = SonarWizApi(client)
+    mappings = api.get_raw_file_device_mappings(raw_file_id=RAW_FILE_ID)
+
+    client.get.assert_called_once_with(
+        "/api/v1/raw-file-device-mappings",
+        params={"raw_file_id": str(RAW_FILE_ID)},
+    )
+    assert len(mappings) == 1
+    assert mappings[0].raw_file_id == RAW_FILE_ID
+    assert mappings[0].device_id == DEVICE_ID
+
+
+def test_get_raw_file_device_mappings_filters_by_device_id():
+    """device_id filter is sent alone when raw_file_id is omitted."""
+    client = MagicMock()
+    client.get.return_value = _mock_response([])
+
+    api = SonarWizApi(client)
+    mappings = api.get_raw_file_device_mappings(device_id=DEVICE_ID)
+
+    client.get.assert_called_once_with(
+        "/api/v1/raw-file-device-mappings",
+        params={"device_id": str(DEVICE_ID)},
+    )
+    assert mappings == []
+
+
+def test_get_raw_file_device_mappings_accepts_string_uuids():
+    """String UUIDs are accepted and stringified the same way."""
+    client = MagicMock()
+    client.get.return_value = _mock_response([])
+
+    api = SonarWizApi(client)
+    api.get_raw_file_device_mappings(
+        raw_file_id=str(RAW_FILE_ID), device_id=str(DEVICE_ID)
+    )
+
+    client.get.assert_called_once_with(
+        "/api/v1/raw-file-device-mappings",
+        params={"raw_file_id": str(RAW_FILE_ID), "device_id": str(DEVICE_ID)},
+    )