matelab-python-sdk 0.1.0a1__py3-none-any.whl

matelab/cloud_drive.py

@@ -0,0 +1,789 @@
+import json
+import math
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from enum import StrEnum
+from types import MappingProxyType
+from typing import Literal, TypeAlias, cast
+
+from pydantic import ValidationError
+
+from matelab._generated.models import BasicSuccessResponse as WireBasicSuccessResponse
+from matelab._generated.models import BindCloudDriveFileRequest as WireBindCloudDriveFileRequest
+from matelab._generated.models import CloudDriveFile as WireCloudDriveFile
+from matelab._generated.models import CloudDriveFileIdList as WireCloudDriveFileIdList
+from matelab._generated.models import CloudDriveFileListResponse as WireCloudDriveFileListResponse
+from matelab._generated.models import CloudDriveFolder as WireCloudDriveFolder
+from matelab._generated.models import CloudDriveFolderIdRequest as WireCloudDriveFolderIdRequest
+from matelab._generated.models import CloudDriveIdentityResponse as WireCloudDriveIdentityResponse
+from matelab._generated.models import CloudDriveRootPermissions as WireCloudDriveRootPermissions
+from matelab._generated.models import DeleteCloudDriveFilesRequest as WireDeleteCloudDriveFilesRequest
+from matelab._generated.models import DownloadCloudDriveFileParametersQuery as WireDownloadCloudDriveFileQuery
+from matelab._generated.models import EditCloudDriveFileRequest as WireEditCloudDriveFileRequest
+from matelab._generated.models import ListCloudDriveFilesParametersQuery as WireListCloudDriveFilesQuery
+from matelab._generated.models import MoveCloudDriveFolderRequest as WireMoveCloudDriveFolderRequest
+from matelab._generated.models import SaveCloudDriveFolderRequest as WireSaveCloudDriveFolderRequest
+from matelab._generated.models import TransferCloudDriveFilesRequest as WireTransferCloudDriveFilesRequest
+from matelab._transport import Encoding, Operation, SessionTransport, StreamOperation, multipart_fields
+from matelab.errors import MatelabError, MatelabProtocolError, MatelabUsageError, MatelabVerificationError
+from matelab.streaming import ByteRange, DownloadStream
+from matelab.uploads import StagedFile
+from matelab.users import UserRef
+
+_LIST_FILES = Operation(
+    method="GET",
+    path="/files/files",
+    encoding=Encoding.QUERY,
+    response_model=WireCloudDriveFileListResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_SAVE_FOLDER = Operation(
+    method="POST",
+    path="/files/filetype_edit",
+    encoding=Encoding.MULTIPART,
+    response_model=WireCloudDriveIdentityResponse,
+    success_codes=frozenset({0}),
+)
+_DELETE_FOLDER = Operation(
+    method="POST",
+    path="/files/filetype_del",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_MOVE_FOLDER = Operation(
+    method="POST",
+    path="/files/filetype_move",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_BIND_STAGED_FILE = Operation(
+    method="POST",
+    path="/files/file_add",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_EDIT_FILE = Operation(
+    method="POST",
+    path="/files/file_edit",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_DELETE_FILES = Operation(
+    method="POST",
+    path="/files/file_del",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_MOVE_FILES = Operation(
+    method="POST",
+    path="/files/move",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_DOWNLOAD_FILE = StreamOperation(method="GET", path="/files/url", retry_on_access_expired=True)
+_SHA256_PATTERN = re.compile(r"^[0-9a-f]{64}$")
+
+
+def _empty_mapping() -> Mapping[str, object]:
+    return MappingProxyType({})
+
+
+class CloudDriveOrder(StrEnum):
+    MODIFIED_AT = "modified_at"
+    FILENAME = "filename"
+
+
+@dataclass(frozen=True, slots=True)
+class CloudDriveRootRef:
+    """The caller's synthetic personal cloud-drive root."""
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFolderRef:
+    cloud_folder_id: int
+
+
+CloudDriveLocation: TypeAlias = CloudDriveRootRef | CloudFolderRef
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFileRef:
+    cloud_file_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class CloudDriveRootPermissions:
+    permission_mask: int
+    can_create_folder: bool
+    can_delete_folder: bool
+    can_edit_folder: bool
+    can_create_file: bool
+    can_delete_file: bool
+    can_view_file: bool
+    can_edit_file: bool
+    attributes: Mapping[str, object] = field(default_factory=_empty_mapping)
+
+
+@dataclass(frozen=True, slots=True)
+class CloudDriveRoot:
+    ref: CloudDriveRootRef
+    name: str
+    description: str
+    permissions: CloudDriveRootPermissions
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFolder:
+    ref: CloudFolderRef
+    name: str
+    parent: CloudDriveLocation
+    direct_file_count: int
+    description: str | None
+    attributes: Mapping[str, object] = field(default_factory=_empty_mapping)
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFile:
+    ref: CloudFileRef
+    location: CloudDriveLocation | None
+    filename: str
+    sha256: str = field(repr=False)
+    size: int
+    owner: UserRef
+    owner_name: str | None
+    modified_at: str | None
+    description: str
+    display_date: str
+    display_time: str
+    attributes: Mapping[str, object] = field(default_factory=_empty_mapping)
+
+
+@dataclass(frozen=True, slots=True)
+class CloudDriveQuota:
+    quota_gib: int | None
+    used_bytes: int
+
+    @property
+    def unlimited(self) -> bool:
+        return self.quota_gib is None
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFolderTree:
+    folders: tuple[CloudFolder, ...]
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFilePage:
+    files: tuple[CloudFile, ...]
+    folder: CloudDriveLocation | None
+    search: str
+    scope: Literal["selected_folder", "search_across_personal_root"]
+    page: int
+    requested_page_size: int
+    effective_page_size: int
+    total_count: int
+    has_more: bool
+    order: CloudDriveOrder
+    descending: bool
+    ordering: Literal["provider_selected_without_stable_id_tiebreaker"] = (
+        "provider_selected_without_stable_id_tiebreaker"
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class CloudDriveListing:
+    file_page: CloudFilePage
+    folder_tree: CloudFolderTree
+    quota: CloudDriveQuota
+    root: CloudDriveRoot
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFolderMetadata:
+    name: str
+    description: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFolderSaveResult:
+    folder: CloudFolderRef
+    requested: CloudFolderMetadata
+    action: Literal["created", "updated"]
+    observed: CloudFolder | None
+    confirmation: Literal["observed_matching", "observed_mismatch", "not_observed"]
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFolderMoveResult:
+    folder: CloudFolderRef
+    target: CloudDriveLocation
+    observed: CloudFolder | None
+    confirmation: Literal["observed_in_target", "observed_elsewhere", "not_observed"]
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFolderDeleteResult:
+    folder: CloudFolderRef
+    absence_confirmed: bool
+    verification: Literal["personal_folder_tree_snapshot"] = "personal_folder_tree_snapshot"
+    recoverable: Literal[False] = False
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFileBindResult:
+    staged_file: StagedFile
+    target: CloudDriveLocation
+    observed: CloudFile | None
+    cloud_file: CloudFileRef | None
+    confirmation: Literal["uniquely_observed", "not_observed", "ambiguous_observation"]
+    staging_owner_verification: Literal["provider_does_not_verify_uploader"] = "provider_does_not_verify_uploader"
+    finalize_atomicity: Literal["not_contractually_guaranteed"] = "not_contractually_guaranteed"
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFileUpdateResult:
+    file: CloudFileRef
+    requested_filename: str
+    requested_description: str
+    observed: CloudFile | None
+    confirmation: Literal["observed_matching", "observed_mismatch", "not_observed"]
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFileMoveResult:
+    files: tuple[CloudFileRef, ...]
+    target: CloudDriveLocation
+    observed_in_target: tuple[CloudFileRef, ...]
+    not_observed_in_target: tuple[CloudFileRef, ...]
+    provider_item_results: None = None
+    atomicity: Literal["provider_does_not_report_or_guarantee_batch_atomicity"] = (
+        "provider_does_not_report_or_guarantee_batch_atomicity"
+    )
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class CloudFilePermanentDeleteResult:
+    files: tuple[CloudFileRef, ...]
+    confirmed_absent: tuple[CloudFileRef, ...]
+    still_visible: tuple[CloudFileRef, ...]
+    provider_item_results: None = None
+    verification: Literal["post_delete_snapshots"] = "post_delete_snapshots"
+    atomicity: Literal["provider_does_not_report_or_guarantee_batch_atomicity"] = (
+        "provider_does_not_report_or_guarantee_batch_atomicity"
+    )
+    recoverable: Literal[False] = False
+    automatic_retry: Literal[False] = False
+
+
+class CloudDrive:
+    """Personal cloud-drive browsing, lifecycle, staging finalization, and streaming."""
+
+    def __init__(self, transport: SessionTransport) -> None:
+        self._transport: SessionTransport = transport
+
+    async def list(
+        self,
+        folder: CloudDriveLocation | None = None,
+        *,
+        page: int = 1,
+        page_size: int = 20,
+        order: CloudDriveOrder = CloudDriveOrder.MODIFIED_AT,
+        descending: bool = True,
+        search: str = "",
+    ) -> CloudDriveListing:
+        selected = folder or CloudDriveRootRef()
+        folder_id = self._location_id(selected)
+        try:
+            selected_order = CloudDriveOrder(order)
+        except (TypeError, ValueError):
+            raise MatelabUsageError("Cloud-drive order must be modified_at or filename.") from None
+        if type(cast(object, descending)) is not bool:
+            raise MatelabUsageError("Cloud-drive descending selection must be a boolean.")
+        try:
+            request = WireListCloudDriveFilesQuery.model_validate(
+                {
+                    "type_id": folder_id,
+                    "root_id": 0,
+                    "page": page,
+                    "page_size": page_size,
+                    "order_by": 0 if selected_order is CloudDriveOrder.MODIFIED_AT else 1,
+                    "order_desc": int(descending),
+                    "search": search,
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Cloud-drive list input does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_LIST_FILES, payload=request.model_dump(mode="json"))
+        return self._listing(
+            response,
+            selected=selected,
+            page=request.page,
+            page_size=request.page_size,
+            order=selected_order,
+            descending=descending,
+            search=request.search,
+        )
+
+    async def create_folder(
+        self, metadata: CloudFolderMetadata, *, parent: CloudDriveLocation | None = None
+    ) -> CloudFolderSaveResult:
+        selected_parent = parent or CloudDriveRootRef()
+        request = self._folder_request(metadata, folder=None, parent=selected_parent)
+        response = await self._transport.request(_SAVE_FOLDER, files=multipart_fields(request.model_dump(mode="json")))
+        folder = CloudFolderRef(cloud_folder_id=response.id)
+        observed = self._find_folder((await self._verified_list("cloud-drive folder creation")).folder_tree, folder)
+        return CloudFolderSaveResult(
+            folder=folder,
+            requested=metadata,
+            action="created",
+            observed=observed,
+            confirmation=self._folder_save_confirmation(observed, metadata, selected_parent),
+        )
+
+    async def update_folder(self, folder: CloudFolderRef, metadata: CloudFolderMetadata) -> CloudFolderSaveResult:
+        request = self._folder_request(metadata, folder=folder, parent=CloudDriveRootRef())
+        response = await self._transport.request(_SAVE_FOLDER, files=multipart_fields(request.model_dump(mode="json")))
+        if response.id != folder.cloud_folder_id:
+            raise MatelabProtocolError("Matelab returned a different folder identity for a cloud-drive update.")
+        observed = self._find_folder((await self._verified_list("cloud-drive folder update")).folder_tree, folder)
+        if observed is None:
+            confirmation: Literal["observed_matching", "observed_mismatch", "not_observed"] = "not_observed"
+        elif observed.name == metadata.name and (observed.description or "") == metadata.description:
+            confirmation = "observed_matching"
+        else:
+            confirmation = "observed_mismatch"
+        return CloudFolderSaveResult(
+            folder=folder, requested=metadata, action="updated", observed=observed, confirmation=confirmation
+        )
+
+    async def move_folder(
+        self, folder: CloudFolderRef, target: CloudDriveLocation | None = None
+    ) -> CloudFolderMoveResult:
+        selected_target = target or CloudDriveRootRef()
+        try:
+            request = WireMoveCloudDriveFolderRequest.model_validate(
+                {"id": self._folder_id(folder), "target": self._location_id(selected_target)}
+            )
+        except ValidationError:
+            raise MatelabUsageError("Cloud-drive folder move does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_MOVE_FOLDER, files=multipart_fields(request.model_dump(mode="json")))
+        observed = self._find_folder((await self._verified_list("cloud-drive folder move")).folder_tree, folder)
+        if observed is None:
+            confirmation: Literal["observed_in_target", "observed_elsewhere", "not_observed"] = "not_observed"
+        elif observed.parent == selected_target:
+            confirmation = "observed_in_target"
+        else:
+            confirmation = "observed_elsewhere"
+        return CloudFolderMoveResult(
+            folder=folder, target=selected_target, observed=observed, confirmation=confirmation
+        )
+
+    async def delete_folder(self, folder: CloudFolderRef) -> CloudFolderDeleteResult:
+        try:
+            request = WireCloudDriveFolderIdRequest(id=self._folder_id(folder))
+        except ValidationError:
+            raise MatelabUsageError("Cloud-drive folder identity does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_DELETE_FOLDER, files=multipart_fields(request.model_dump(mode="json")))
+        observed = self._find_folder((await self._verified_list("cloud-drive folder deletion")).folder_tree, folder)
+        return CloudFolderDeleteResult(folder=folder, absence_confirmed=observed is None)
+
+    async def bind_staged_file(
+        self, staged_file: StagedFile, *, target: CloudDriveLocation | None = None
+    ) -> CloudFileBindResult:
+        self._validate_staged_file(staged_file)
+        selected_target = target or CloudDriveRootRef()
+        try:
+            request = WireBindCloudDriveFileRequest.model_validate(
+                {"file_id": staged_file.temporary_file_id, "type_id": self._location_id(selected_target), "root_id": 0}
+            )
+        except ValidationError:
+            raise MatelabUsageError(
+                "Cloud-drive staged-file binding does not satisfy the Integration Contract."
+            ) from None
+        _ = await self._transport.request(_BIND_STAGED_FILE, files=multipart_fields(request.model_dump(mode="json")))
+        files = await self._verified_folder_files(selected_target, "cloud-drive staged-file binding")
+        matches = tuple(
+            item
+            for item in files
+            if item.filename == staged_file.filename
+            and item.sha256 == staged_file.sha256
+            and item.size == staged_file.size
+        )
+        if len(matches) == 1:
+            confirmation: Literal["uniquely_observed", "not_observed", "ambiguous_observation"] = "uniquely_observed"
+            observed = matches[0]
+        elif matches:
+            confirmation = "ambiguous_observation"
+            observed = None
+        else:
+            confirmation = "not_observed"
+            observed = None
+        return CloudFileBindResult(
+            staged_file=staged_file,
+            target=selected_target,
+            observed=observed,
+            cloud_file=observed.ref if observed is not None else None,
+            confirmation=confirmation,
+        )
+
+    async def update_file(self, file: CloudFile, *, filename: str, description: str = "") -> CloudFileUpdateResult:
+        self._validate_observed_file(file)
+        if self._extension(file.filename) != self._extension(filename):
+            raise MatelabUsageError("Cloud-drive file rename must preserve the existing filename extension.")
+        try:
+            request = WireEditCloudDriveFileRequest.model_validate(
+                {"id": file.ref.cloud_file_id, "filename": filename, "comm": description}
+            )
+        except ValidationError:
+            raise MatelabUsageError("Cloud-drive file metadata does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_EDIT_FILE, files=multipart_fields(request.model_dump(mode="json")))
+        observed = await self._verified_locate_file(
+            file.ref, location=file.location, search=filename, action="cloud-drive file update"
+        )
+        if observed is None:
+            confirmation: Literal["observed_matching", "observed_mismatch", "not_observed"] = "not_observed"
+        elif (
+            observed.filename == filename
+            and observed.description == description
+            and observed.sha256 == file.sha256
+            and observed.size == file.size
+        ):
+            confirmation = "observed_matching"
+        else:
+            confirmation = "observed_mismatch"
+        return CloudFileUpdateResult(
+            file=file.ref,
+            requested_filename=filename,
+            requested_description=description,
+            observed=observed,
+            confirmation=confirmation,
+        )
+
+    async def move_files(
+        self, files: Sequence[CloudFileRef], *, target: CloudDriveLocation | None = None
+    ) -> CloudFileMoveResult:
+        selected = self._unique_file_refs(files)
+        selected_target = target or CloudDriveRootRef()
+        encoded = self._wire_file_ids(selected)
+        try:
+            request = WireTransferCloudDriveFilesRequest(
+                files=encoded, target=self._location_id(selected_target), root_id=0
+            )
+        except ValidationError:
+            raise MatelabUsageError("Cloud-drive file move does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_MOVE_FILES, files=multipart_fields(request.model_dump(mode="json")))
+        after = await self._verified_folder_files(selected_target, "cloud-drive file move")
+        observed_ids = {item.ref.cloud_file_id for item in after}
+        observed = tuple(item for item in selected if item.cloud_file_id in observed_ids)
+        missing = tuple(item for item in selected if item.cloud_file_id not in observed_ids)
+        return CloudFileMoveResult(
+            files=selected, target=selected_target, observed_in_target=observed, not_observed_in_target=missing
+        )
+
+    async def permanently_delete_files(self, files: Sequence[CloudFile]) -> CloudFilePermanentDeleteResult:
+        selected_files = tuple(files)
+        for item in selected_files:
+            self._validate_observed_file(item)
+        refs = self._unique_file_refs(tuple(item.ref for item in selected_files))
+        if len(selected_files) != len(refs):
+            raise MatelabUsageError("Cloud-drive deletion requires distinct observed files.")
+        try:
+            request = WireDeleteCloudDriveFilesRequest(ids=self._wire_file_ids(refs))
+        except ValidationError:
+            raise MatelabUsageError("Cloud-drive file deletion does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_DELETE_FILES, files=multipart_fields(request.model_dump(mode="json")))
+        still_visible: list[CloudFileRef] = []
+        for item in selected_files:
+            observed = await self._verified_locate_file(
+                item.ref, location=item.location, search=item.filename, action="cloud-drive permanent file deletion"
+            )
+            if observed is not None:
+                still_visible.append(item.ref)
+        visible_ids = {item.cloud_file_id for item in still_visible}
+        return CloudFilePermanentDeleteResult(
+            files=refs,
+            confirmed_absent=tuple(item for item in refs if item.cloud_file_id not in visible_ids),
+            still_visible=tuple(still_visible),
+        )
+
+    async def download(
+        self, file: CloudFileRef, *, thumbnail: bool = False, preview: bool = True, byte_range: ByteRange | None = None
+    ) -> DownloadStream:
+        if type(cast(object, thumbnail)) is not bool or type(cast(object, preview)) is not bool:
+            raise MatelabUsageError("Cloud-drive thumbnail and preview selections must be booleans.")
+        try:
+            request = WireDownloadCloudDriveFileQuery.model_validate(
+                {"id": self._file_id(file), "thumb": int(thumbnail), "c": int(preview)}
+            )
+        except ValidationError:
+            raise MatelabUsageError("Cloud-drive file identity does not satisfy the Integration Contract.") from None
+        return await self._transport.stream(
+            _DOWNLOAD_FILE,
+            payload=request.model_dump(mode="json"),
+            range_header=byte_range.to_header() if byte_range is not None else None,
+        )
+
+    async def _verified_list(self, action: str) -> CloudDriveListing:
+        try:
+            return await self.list()
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but cloud-drive readback failed; the mutation may have persisted."
+            ) from exc
+
+    async def _verified_folder_files(self, location: CloudDriveLocation, action: str) -> tuple[CloudFile, ...]:
+        try:
+            return await self._folder_files(location)
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but target-folder readback failed; the mutation may have persisted."
+            ) from exc
+
+    async def _verified_locate_file(
+        self, ref: CloudFileRef, *, location: CloudDriveLocation | None, search: str, action: str
+    ) -> CloudFile | None:
+        try:
+            candidates = (
+                await self._folder_files(location) if location is not None else await self._search_files(search)
+            )
+            return next((item for item in candidates if item.ref == ref), None)
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but file readback failed; the mutation may have persisted."
+            ) from exc
+
+    async def _folder_files(self, location: CloudDriveLocation) -> tuple[CloudFile, ...]:
+        first = await self.list(location, page=1, page_size=256)
+        files = list(first.file_page.files)
+        for page_number in range(2, math.ceil(first.file_page.total_count / first.file_page.effective_page_size) + 1):
+            page = await self.list(location, page=page_number, page_size=first.file_page.effective_page_size)
+            files.extend(page.file_page.files)
+        return tuple(files)
+
+    async def _search_files(self, search: str) -> tuple[CloudFile, ...]:
+        first = await self.list(page=1, page_size=256, search=search)
+        files = list(first.file_page.files)
+        for page_number in range(2, math.ceil(first.file_page.total_count / first.file_page.effective_page_size) + 1):
+            page = await self.list(page=page_number, page_size=first.file_page.effective_page_size, search=search)
+            files.extend(page.file_page.files)
+        return tuple(files)
+
+    @staticmethod
+    def _listing(
+        response: WireCloudDriveFileListResponse,
+        *,
+        selected: CloudDriveLocation,
+        page: int,
+        page_size: int,
+        order: CloudDriveOrder,
+        descending: bool,
+        search: str,
+    ) -> CloudDriveListing:
+        normalized_page = max(1, page)
+        effective_page_size = max(10, page_size)
+        file_location = None if search else selected
+        return CloudDriveListing(
+            file_page=CloudFilePage(
+                files=tuple(CloudDrive._file(item, file_location) for item in response.files),
+                folder=file_location,
+                search=search,
+                scope="search_across_personal_root" if search else "selected_folder",
+                page=normalized_page,
+                requested_page_size=page_size,
+                effective_page_size=effective_page_size,
+                total_count=response.count,
+                has_more=normalized_page * effective_page_size < response.count,
+                order=order,
+                descending=descending,
+            ),
+            folder_tree=CloudFolderTree(folders=tuple(CloudDrive._folder(item) for item in response.types)),
+            quota=CloudDriveQuota(quota_gib=response.quota or None, used_bytes=response.used),
+            root=CloudDrive._root(response.root_type),
+        )
+
+    @staticmethod
+    def _file(item: WireCloudDriveFile, location: CloudDriveLocation | None) -> CloudFile:
+        return CloudFile(
+            ref=CloudFileRef(cloud_file_id=item.id),
+            location=location,
+            filename=item.filename,
+            sha256=item.hash.root,
+            size=int(item.size),
+            owner=UserRef(userid=item.userid),
+            owner_name=item.username,
+            modified_at=item.date_time,
+            description=item.comm,
+            display_date=item.date,
+            display_time=item.time,
+            attributes=MappingProxyType(cast(dict[str, object], dict(item.model_extra or {}))),
+        )
+
+    @staticmethod
+    def _folder(item: WireCloudDriveFolder) -> CloudFolder:
+        parent: CloudDriveLocation = (
+            CloudDriveRootRef() if item.parent == 0 else CloudFolderRef(cloud_folder_id=item.parent)
+        )
+        return CloudFolder(
+            ref=CloudFolderRef(cloud_folder_id=item.id),
+            name=item.showtext,
+            parent=parent,
+            direct_file_count=item.num,
+            description=item.comm,
+            attributes=MappingProxyType(cast(dict[str, object], dict(item.model_extra or {}))),
+        )
+
+    @staticmethod
+    def _root(item: WireCloudDriveRootPermissions) -> CloudDriveRoot:
+        return CloudDriveRoot(
+            ref=CloudDriveRootRef(),
+            name=item.showtext,
+            description=item.comm,
+            permissions=CloudDriveRootPermissions(
+                permission_mask=item.power,
+                can_create_folder=item.dir_create,
+                can_delete_folder=item.dir_delete,
+                can_edit_folder=item.dir_edit,
+                can_create_file=item.file_create,
+                can_delete_file=item.file_delete,
+                can_view_file=item.file_view,
+                can_edit_file=item.file_edit,
+                attributes=MappingProxyType(cast(dict[str, object], dict(item.model_extra or {}))),
+            ),
+        )
+
+    @staticmethod
+    def _folder_request(
+        metadata: CloudFolderMetadata, *, folder: CloudFolderRef | None, parent: CloudDriveLocation
+    ) -> WireSaveCloudDriveFolderRequest:
+        raw_metadata = cast(object, metadata)
+        if not isinstance(raw_metadata, CloudFolderMetadata):
+            raise MatelabUsageError("Cloud-drive folder metadata is invalid.")
+        try:
+            return WireSaveCloudDriveFolderRequest.model_validate(
+                {
+                    "id": folder.cloud_folder_id if folder is not None else 0,
+                    "parent": CloudDrive._location_id(parent),
+                    "root_id": 0,
+                    "showtext": raw_metadata.name,
+                    "comm": raw_metadata.description,
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Cloud-drive folder metadata does not satisfy the Integration Contract.") from None
+
+    @staticmethod
+    def _folder_save_confirmation(
+        observed: CloudFolder | None, metadata: CloudFolderMetadata, parent: CloudDriveLocation
+    ) -> Literal["observed_matching", "observed_mismatch", "not_observed"]:
+        if observed is None:
+            return "not_observed"
+        if (
+            observed.name == metadata.name
+            and (observed.description or "") == metadata.description
+            and observed.parent == parent
+        ):
+            return "observed_matching"
+        return "observed_mismatch"
+
+    @staticmethod
+    def _find_folder(tree: CloudFolderTree, ref: CloudFolderRef) -> CloudFolder | None:
+        return next((item for item in tree.folders if item.ref == ref), None)
+
+    @staticmethod
+    def _validate_staged_file(staged: StagedFile) -> None:
+        raw_staged = cast(object, staged)
+        if (
+            not isinstance(raw_staged, StagedFile)
+            or raw_staged.temporary_file_id < 1
+            or not raw_staged.binding.uid
+            or len(raw_staged.binding.uid) > 45
+            or not raw_staged.session.upload_session_id
+            or len(raw_staged.session.upload_session_id) > 45
+            or raw_staged.session.next_offset != raw_staged.size
+            or not raw_staged.filename
+            or raw_staged.size < 0
+            or _SHA256_PATTERN.fullmatch(raw_staged.sha256) is None
+            or raw_staged.completion != "provider_acknowledged_complete"
+            or raw_staged.binding_state != "staged_not_bound"
+        ):
+            raise MatelabUsageError("Completed staged-file metadata is invalid.")
+
+    @staticmethod
+    def _validate_observed_file(file: CloudFile) -> None:
+        raw_file = cast(object, file)
+        if (
+            not isinstance(raw_file, CloudFile)
+            or CloudDrive._file_id(raw_file.ref) < 1
+            or not raw_file.filename
+            or raw_file.size < 0
+            or _SHA256_PATTERN.fullmatch(raw_file.sha256) is None
+        ):
+            raise MatelabUsageError("Observed cloud-drive file metadata is invalid.")
+        if raw_file.location is not None:
+            _ = CloudDrive._location_id(raw_file.location)
+
+    @staticmethod
+    def _wire_file_ids(refs: tuple[CloudFileRef, ...]) -> str:
+        ids = [item.cloud_file_id for item in refs]
+        try:
+            wire = WireCloudDriveFileIdList.model_validate(ids)
+            payload = cast(list[object], wire.model_dump(mode="json"))
+            return json.dumps(payload, separators=(",", ":"))
+        except (ValidationError, TypeError, ValueError):
+            raise MatelabUsageError("Cloud-drive file identities do not satisfy the Integration Contract.") from None
+
+    @staticmethod
+    def _unique_file_refs(files: Sequence[CloudFileRef]) -> tuple[CloudFileRef, ...]:
+        selected = tuple(files)
+        ids = tuple(CloudDrive._file_id(item) for item in selected)
+        if not selected or len(ids) != len(set(ids)):
+            raise MatelabUsageError("Cloud-drive file selection must contain distinct positive identities.")
+        return selected
+
+    @staticmethod
+    def _location_id(location: CloudDriveLocation) -> int:
+        raw_location = cast(object, location)
+        if isinstance(raw_location, CloudDriveRootRef):
+            return 0
+        if isinstance(raw_location, CloudFolderRef):
+            return CloudDrive._folder_id(raw_location)
+        raise MatelabUsageError("Cloud-drive location identity is invalid.")
+
+    @staticmethod
+    def _folder_id(folder: CloudFolderRef) -> int:
+        raw_folder = cast(object, folder)
+        if (
+            isinstance(raw_folder, CloudFolderRef)
+            and type(raw_folder.cloud_folder_id) is int
+            and raw_folder.cloud_folder_id >= 1
+        ):
+            return raw_folder.cloud_folder_id
+        raise MatelabUsageError("Cloud-drive folder identity is invalid.")
+
+    @staticmethod
+    def _file_id(file: CloudFileRef) -> int:
+        raw_file = cast(object, file)
+        if isinstance(raw_file, CloudFileRef) and type(raw_file.cloud_file_id) is int and raw_file.cloud_file_id >= 1:
+            return raw_file.cloud_file_id
+        raise MatelabUsageError("Cloud-drive file identity is invalid.")
+
+    @staticmethod
+    def _extension(filename: str) -> str:
+        tail = filename.rpartition(".")
+        return f".{tail[2]}" if tail[0] and tail[2] else ""