feat(doi): add DOI-based path access for commands

Support accessing repositories using DOI strings with optional subpaths
across ls, download, metadata, and file-metadata commands.

- Implement GET v3/doi/{id}/ API model and client calls
- Parse and resolve DOI paths into respective folder and files
- Extract common folder and file resolution logic to shared helpers
- Update README with example DOI-based shell commands

mdrsclient/api/__init__.py

@@ -1,9 +1,11 @@
+from mdrsclient.api.doi import DoiApi
 from mdrsclient.api.files import FilesApi
 from mdrsclient.api.folders import FoldersApi
 from mdrsclient.api.laboratories import LaboratoriesApi
 from mdrsclient.api.users import UsersApi
 
 __all__ = [
+    "DoiApi",
     "FilesApi",
     "FoldersApi",
     "LaboratoriesApi",

mdrsclient/api/doi.py

@@ -0,0 +1,40 @@
+from typing import Final
+
+from pydantic import TypeAdapter
+from pydantic.dataclasses import dataclass
+
+from mdrsclient.api.base import BaseApi
+from mdrsclient.api.utils import token_check
+
+
+@dataclass(frozen=True)
+class DoiFolderRef:
+    """Nested folder reference returned inside a DOI response.
+
+    The DOI endpoint only returns the folder ``id``; ``laboratory_id`` must be
+    obtained by subsequently calling the folder retrieve endpoint.
+    """
+
+    id: str
+
+
+@dataclass(frozen=True)
+class DoiResponse:
+    """Response from GET v3/doi/{id}/."""
+
+    # The internal DOI suffix ID returned as a string (e.g. "20260429-001").
+    id: str
+    doi: str
+    folder: DoiFolderRef
+
+
+class DoiApi(BaseApi):
+    ENTRYPOINT: Final[str] = "v3/doi/"
+
+    def retrieve(self, doi_id: str) -> DoiResponse:
+        """Retrieve the folder associated with a DOI suffix ID (GET v3/doi/{id}/)."""
+        url = self.ENTRYPOINT + doi_id + "/"
+        token_check(self.connection)
+        response = self.connection.get(url)
+        self._raise_response_error(response)
+        return TypeAdapter(DoiResponse).validate_python(response.json())