supernote 0.13.6__py3-none-any.whl

supernote/client/device.py

@@ -0,0 +1,361 @@
+import hashlib
+import logging
+from pathlib import Path
+
+from supernote.models.file_common import FileUploadApplyLocalVO
+from supernote.models.file_device import (
+    CapacityLocalDTO,
+    CapacityLocalVO,
+    CreateFolderLocalDTO,
+    CreateFolderLocalVO,
+    DeleteFolderLocalDTO,
+    DeleteFolderLocalVO,
+    FileCopyLocalDTO,
+    FileCopyLocalVO,
+    FileDownloadLocalDTO,
+    FileDownloadLocalVO,
+    FileMoveLocalDTO,
+    FileMoveLocalVO,
+    FileQueryByPathLocalDTO,
+    FileQueryByPathLocalVO,
+    FileQueryLocalDTO,
+    FileQueryLocalVO,
+    FileUploadApplyLocalDTO,
+    FileUploadFinishLocalDTO,
+    FileUploadFinishLocalVO,
+    ListFolderLocalDTO,
+    ListFolderLocalVO,
+    ListFolderV2DTO,
+    PdfDTO,
+    PdfVO,
+    PngDTO,
+    PngVO,
+    SynchronousEndLocalDTO,
+    SynchronousEndLocalVO,
+    SynchronousStartLocalDTO,
+    SynchronousStartLocalVO,
+)
+
+from .client import Client
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class DeviceClient:
+    """Client for Device (V2/V3) APIs."""
+
+    def __init__(self, client: Client) -> None:
+        """Initialize the DeviceClient."""
+        self._client = client
+
+    async def create_folder(
+        self, path: str, equipment_no: str, autorename: bool = False
+    ) -> CreateFolderLocalVO:
+        """Create a folder (V2)."""
+        dto = CreateFolderLocalDTO(
+            path=path, equipment_no=equipment_no, autorename=autorename
+        )
+        return await self._client.post_json(
+            "/api/file/2/files/create_folder_v2",
+            CreateFolderLocalVO,
+            json=dto.to_dict(),
+        )
+
+    async def list_folder(
+        self,
+        path: str | None = None,
+        folder_id: int | None = None,
+        equipment_no: str | None = None,
+        recursive: bool = False,
+    ) -> ListFolderLocalVO:
+        """List folder contents.
+
+        This supports both V2 and V3 APIs. You can either specify path or folder_id.
+
+        Args:
+            path: Path to list contents of.
+            folder_id: ID of folder to list contents of.
+            equipment_no: Equipment number.
+            recursive: Whether to list recursively.
+
+        Returns:
+            ListFolderLocalVO
+        """
+        if path is not None:
+            dto_v2 = ListFolderV2DTO(
+                path=path, equipment_no=equipment_no or "WEB", recursive=recursive
+            )
+            return await self._client.post_json(
+                "/api/file/2/files/list_folder",
+                ListFolderLocalVO,
+                json=dto_v2.to_dict(),
+            )
+        if folder_id is not None:
+            # List folder contents using v3/device API
+            dto_v3 = ListFolderLocalDTO(
+                id=folder_id,
+                equipment_no=equipment_no or "WEB",
+                recursive=recursive,
+            )
+            return await self._client.post_json(
+                "/api/file/3/files/list_folder_v3",
+                ListFolderLocalVO,
+                json=dto_v3.to_dict(),
+            )
+        raise ValueError("path or folder_id must be specified")
+
+    async def delete(self, id: int, equipment_no: str) -> DeleteFolderLocalVO:
+        """Delete a folder or file (V3)."""
+        dto = DeleteFolderLocalDTO(id=id, equipment_no=equipment_no)
+        return await self._client.post_json(
+            "/api/file/3/files/delete_folder_v3",
+            DeleteFolderLocalVO,
+            json=dto.to_dict(),
+        )
+
+    async def delete_by_path(
+        self, path: str, equipment_no: str | None = None
+    ) -> DeleteFolderLocalVO:
+        """Delete a folder or file by path (V3)."""
+        if equipment_no is None:
+            equipment_no = "WEB"
+        info = await self.query_by_path(path, equipment_no)
+        if not info.entries_vo:
+            raise FileNotFoundError(f"File or folder not found: {path}")
+        return await self.delete(int(info.entries_vo.id), equipment_no)
+
+    async def move(
+        self, id: int, to_path: str, equipment_no: str, autorename: bool = False
+    ) -> FileMoveLocalVO:
+        """Move a folder or file (V3)."""
+        dto = FileMoveLocalDTO(
+            id=id, to_path=to_path, equipment_no=equipment_no, autorename=autorename
+        )
+        return await self._client.post_json(
+            "/api/file/3/files/move_v3", FileMoveLocalVO, json=dto.to_dict()
+        )
+
+    async def copy(
+        self, id: int, to_path: str, equipment_no: str, autorename: bool = False
+    ) -> FileCopyLocalVO:
+        """Copy a folder or file (V3)."""
+        dto = FileCopyLocalDTO(
+            id=id, to_path=to_path, equipment_no=equipment_no, autorename=autorename
+        )
+        return await self._client.post_json(
+            "/api/file/3/files/copy_v3", FileCopyLocalVO, json=dto.to_dict()
+        )
+
+    async def upload_content(
+        self,
+        path: str,
+        content: bytes,
+        equipment_no: str | None = None,
+        chunk_size: int = 5 * 1024 * 1024,
+    ) -> FileUploadFinishLocalVO:
+        """Create a file (convenience method wrapping upload flow).
+
+        Args:
+            path: Full cloud path (e.g. /Folder/file.txt)
+            content: File content (string or bytes)
+            equipment_no: Equipment number
+            chunk_size: Upload chunk size/part size
+
+        Returns:
+            FileUploadFinishLocalVO containing file upload finish response
+        """
+        if equipment_no is None:
+            equipment_no = "WEB"
+        filename = Path(path).name
+        size = len(content)
+
+        # First upload the upload url
+        _LOGGER.debug("Initiating upload for file %s", path)
+        apply = await self.upload_apply(filename, path, size, equipment_no)
+
+        md5 = hashlib.md5(content).hexdigest()
+
+        await self._client._upload_to_oss(
+            content,
+            filename,
+            apply.full_upload_url,
+            apply.part_upload_url,
+            chunk_size,
+        )
+
+        _LOGGER.debug("Finishing upload for file %s", path)
+
+        parent = str(Path(path).parent)
+        if parent == ".":
+            parent = ""
+        parent_path_str = parent.strip("/")
+
+        return await self.upload_finish(
+            file_name=filename,
+            path=parent_path_str,
+            content_hash=md5,
+            equipment_no=equipment_no,
+            inner_name=apply.inner_name,
+        )
+
+    async def upload_apply(
+        self, file_name: str, path: str, size: int, equipment_no: str
+    ) -> FileUploadApplyLocalVO:
+        """Apply for file upload."""
+        dto = FileUploadApplyLocalDTO(
+            file_name=file_name, path=path, size=str(size), equipment_no=equipment_no
+        )
+        return await self._client.post_json(
+            "/api/file/3/files/upload/apply", FileUploadApplyLocalVO, json=dto.to_dict()
+        )
+
+    async def upload_finish(
+        self,
+        file_name: str,
+        path: str,
+        content_hash: str,
+        equipment_no: str,
+        inner_name: str | None = None,
+    ) -> FileUploadFinishLocalVO:
+        """Finish file upload."""
+        dto = FileUploadFinishLocalDTO(
+            file_name=file_name,
+            path=path,
+            content_hash=content_hash,
+            equipment_no=equipment_no,
+            inner_name=inner_name,
+        )
+        return await self._client.post_json(
+            "/api/file/2/files/upload/finish",
+            FileUploadFinishLocalVO,
+            json=dto.to_dict(),
+        )
+
+    async def download_content(
+        self,
+        path: str | None = None,
+        file_id: int | None = None,
+        equipment_no: str = "",
+        offset: int = 0,
+        length: int = -1,
+    ) -> bytes:
+        """Download file content, optionally with range.
+
+        Args:
+           path: File path (e.g. /Folder/file.pdf) (optional if file_id provided)
+           file_id: File ID (optional if path provided)
+           equipment_no: Equipment number
+           offset: Start byte offset
+           length: Number of bytes to read (-1 for until end)
+
+        Returns:
+            File content bytes
+        """
+        if equipment_no == "":
+            equipment_no = "WEB"
+
+        if file_id is None:
+            if path is None:
+                raise ValueError("Either path or file_id must be provided")
+            # Resolve path to ID
+            info = await self.query_by_path(path, equipment_no)
+            if not info.entries_vo:
+                raise FileNotFoundError(f"File not found: {path}")
+            # The API returns id as str, we need int for download_v3
+            file_id = int(info.entries_vo.id)
+
+        download_info = await self.download_v3(file_id, equipment_no)
+        url = download_info.url
+
+        headers = {}
+        if offset > 0 or length != -1:
+            end = ""
+            if length != -1:
+                end = str(offset + length - 1)
+            headers["Range"] = f"bytes={offset}-{end}"
+
+        return await self._client.get_content(url, headers=headers)
+
+    async def download_v3(self, file_id: int, equipment_no: str) -> FileDownloadLocalVO:
+        """Get download URL (V3)."""
+        dto = FileDownloadLocalDTO(id=file_id, equipment_no=equipment_no)
+        return await self._client.post_json(
+            "/api/file/3/files/download_v3", FileDownloadLocalVO, json=dto.to_dict()
+        )
+
+    async def get_capacity(self, equipment_no: str = "") -> CapacityLocalVO:
+        """Get storage capacity (Device)."""
+        dto = CapacityLocalDTO(equipment_no=equipment_no)
+        return await self._client.post_json(
+            "/api/file/2/users/get_space_usage", CapacityLocalVO, json=dto.to_dict()
+        )
+
+    async def query_by_path(
+        self, path: str, equipment_no: str
+    ) -> FileQueryByPathLocalVO:
+        """Query file info by path (V3)."""
+        dto = FileQueryByPathLocalDTO(path=path, equipment_no=equipment_no)
+        return await self._client.post_json(
+            "/api/file/3/files/query/by/path_v3",
+            FileQueryByPathLocalVO,
+            json=dto.to_dict(),
+        )
+
+    async def query_by_id(self, file_id: int, equipment_no: str) -> FileQueryLocalVO:
+        """Query file info by ID (V3)."""
+        dto = FileQueryLocalDTO(id=str(file_id), equipment_no=equipment_no)
+        return await self._client.post_json(
+            "/api/file/3/files/query_v3", FileQueryLocalVO, json=dto.to_dict()
+        )
+
+    async def sync_start(self, equipment_no: str) -> SynchronousStartLocalVO:
+        """Start sync session."""
+        dto = SynchronousStartLocalDTO(equipment_no=equipment_no)
+        return await self._client.post_json(
+            "/api/file/2/files/synchronous/start",
+            SynchronousStartLocalVO,
+            json=dto.to_dict(),
+        )
+
+    async def sync_end(self, equipment_no: str) -> SynchronousEndLocalVO:
+        """End sync session."""
+        dto = SynchronousEndLocalDTO(equipment_no=equipment_no)
+        return await self._client.post_json(
+            "/api/file/2/files/synchronous/end",
+            SynchronousEndLocalVO,
+            json=dto.to_dict(),
+        )
+
+    async def note_to_png(self, file_id: int) -> PngVO:
+        """Convert a note to PNG (Device API)."""
+        dto = PngDTO(id=file_id)
+        return await self._client.post_json(
+            "/api/file/note/to/png", PngVO, json=dto.to_dict()
+        )
+
+    async def note_to_pdf(
+        self, file_id: int, page_no_list: list[int] | None = None
+    ) -> PdfVO:
+        """Convert a note to PDF (Device API)."""
+        dto = PdfDTO(id=file_id, page_no_list=page_no_list or [])
+        return await self._client.post_json(
+            "/api/file/note/to/pdf", PdfVO, json=dto.to_dict()
+        )
+
+    async def get_note_png_pages(self, file_id: int) -> list[bytes]:
+        """Convenience method to get PNG content for all pages of a note."""
+        conversion = await self.note_to_png(file_id)
+        pages = []
+        for page_vo in conversion.png_page_vo_list:
+            content = await self._client.get_content(page_vo.url)
+            pages.append(content)
+        return pages
+
+    async def get_note_pdf(
+        self, file_id: int, page_no_list: list[int] | None = None
+    ) -> bytes:
+        """Convenience method to get PDF content for a note."""
+        conversion = await self.note_to_pdf(file_id, page_no_list)
+        if not conversion.url:
+            raise ValueError("Conversion failed: no URL returned")
+        return await self._client.get_content(conversion.url)

supernote/client/exceptions.py

@@ -0,0 +1,33 @@
+"""Exceptions for supernote cloud."""
+
+
+class SupernoteException(Exception):
+    """Base exception for supernote cloud."""
+
+
+class SmsVerificationRequired(SupernoteException):
+    """Exception raised when SMS verification is required."""
+
+    def __init__(self, message: str, timestamp: str):
+        super().__init__(message)
+        self.timestamp = timestamp
+
+
+class ApiException(SupernoteException):
+    """API exception."""
+
+
+class ForbiddenException(ApiException):
+    """API exception."""
+
+
+class UnauthorizedException(ApiException):
+    """Authentication exception."""
+
+
+class NotFoundException(ApiException):
+    """Resource not found (404)."""
+
+
+class BadRequestException(ApiException):
+    """Bad request (400)."""

supernote/client/extended.py

@@ -0,0 +1,20 @@
+"""Client for Extended (Web) APIs."""
+
+from supernote.models.extended import WebSummaryListRequestDTO, WebSummaryListVO
+
+from . import Client
+
+
+class ExtendedClient:
+    """Client for Server Extension APIs."""
+
+    def __init__(self, client: Client):
+        """Initialize the extended client."""
+        self._client = client
+
+    async def list_summaries(self, file_id: int) -> WebSummaryListVO:
+        """List summaries for a file (Extension)."""
+        dto = WebSummaryListRequestDTO(file_id=file_id)
+        return await self._client.post_json(
+            "/api/extended/file/summary/list", WebSummaryListVO, json=dto.to_dict()
+        )

supernote/client/hashing.py

@@ -0,0 +1,50 @@
+"""Module for hashing utilities."""
+
+import hashlib
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _sha256_string(s: str) -> str:
+    """Return SHA256 hex digest of a string."""
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def _md5_string(s: str) -> str:
+    """Return MD5 hex digest of a string."""
+    return hashlib.md5(s.encode("utf-8")).hexdigest()
+
+
+def hash_with_salt(content: str, salt: str) -> str:
+    """Hash content with salt using SHA256."""
+    return _sha256_string(f"{content}{salt}")
+
+
+def hash_password(password_text: str, rc: str) -> str:
+    """Encode password using MD5 and SHA256."""
+    md5 = _md5_string(password_text)
+    return hash_with_salt(md5, rc)
+
+
+def get_token_salt(token: str) -> str:
+    """Extract real key (salt) from token.
+
+    This is the dynamic key selection mechanism used during the SMS authentication
+    flow. It takes the last character of the token and interprets it as an integer
+    index n. It then splits the token string by hyphens - and returns the n-th
+    component from the split parts.
+    """
+    if not token:
+        raise ValueError("Token cannot be empty")
+    last_char = token[-1]
+    try:
+        index = int(last_char)
+    except ValueError:
+        raise ValueError(f"Last character of token must be an integer: {token}")
+    parts = token.split("-")
+    if 0 <= index < len(parts):
+        return parts[index]
+    raise ValueError(
+        f"Invalid token format (index out of bounds, index={index}, token={token})"
+    )

supernote/client/login_client.py

@@ -0,0 +1,154 @@
+"""Library for authenticating with the Supernote (Private) Cloud Server."""
+
+import logging
+from typing import TypeVar
+
+from mashumaro.mixins.json import DataClassJSONMixin
+
+from supernote.models.auth import (
+    LoginDTO,
+    LoginMethod,
+    LoginVO,
+    QueryTokenDTO,
+    QueryTokenVO,
+    RandomCodeDTO,
+    RandomCodeVO,
+    SendSmsDTO,
+    SendSmsVO,
+    SmsLoginDTO,
+    SmsLoginVO,
+    UserPreAuthRequest,
+    UserPreAuthResponse,
+)
+
+from .client import Client
+from .exceptions import ApiException, SmsVerificationRequired
+from .hashing import get_token_salt, hash_password, hash_with_salt
+
+_LOGGER = logging.getLogger(__name__)
+
+
+_T = TypeVar("_T", bound=DataClassJSONMixin)
+
+__all__ = [
+    "LoginClient",
+]
+
+
+class LoginClient:
+    """A client library for logging in."""
+
+    def __init__(self, client: Client):
+        """Initialize the client."""
+        self._client = client
+
+    async def login(self, email: str, password: str) -> str:
+        """Log in and return an access token."""
+        await self._token()
+        random_code_response = await self._get_random_code(email)
+        encoded_password = hash_password(password, random_code_response.random_code)
+        access_token_response = await self._get_access_token(
+            email, encoded_password, random_code_response.timestamp
+        )
+        return access_token_response.token
+
+    async def login_equipment(
+        self, email: str, password: str, equipment_no: str
+    ) -> LoginVO:
+        """Log in via equipment endpoint and return full login response."""
+        await self._token()
+        random_code_response = await self._get_random_code(email)
+        encoded_password = hash_password(password, random_code_response.random_code)
+
+        payload = LoginDTO(
+            account=email,
+            password=encoded_password,
+            login_method=LoginMethod.PHONE if email.isdigit() else LoginMethod.EMAIL,
+            timestamp=random_code_response.timestamp,
+            equipment_no=equipment_no,
+        ).to_dict()
+
+        return await self._client.post_json(
+            "/api/official/user/account/login/equipment", LoginVO, json=payload
+        )
+
+    async def sms_login(self, telephone: str, code: str, timestamp: str) -> str:
+        """Log in via SMS code."""
+        # Always get a fresh CSRF token for the SMS login request
+        await self._client._get_csrf_token()
+
+        payload = SmsLoginDTO(
+            telephone=telephone,
+            timestamp=timestamp,
+            valid_code=code,
+            valid_code_key=f"1-{telephone}_validCode",
+        ).to_dict()
+
+        response = await self._client.post_json(
+            "/api/official/user/sms/login", SmsLoginVO, json=payload
+        )
+        return response.token
+
+    async def request_sms_code(self, telephone: str, country_code: int = 1) -> None:
+        """Request an SMS verification code."""
+        # Pre-authentication step to obtain a token
+        account_with_code = f"{country_code}{telephone}"
+        pre_auth_payload = UserPreAuthRequest(account=account_with_code).to_dict()
+
+        # Always get a fresh CSRF token
+        await self._client._get_csrf_token()
+
+        pre_auth_response = await self._client.post_json(
+            "/api/user/validcode/pre-auth", UserPreAuthResponse, json=pre_auth_payload
+        )
+
+        # Calculate signature needed to send the random code over SMS
+        token_salt = get_token_salt(pre_auth_response.token)
+        sign = hash_with_salt(account_with_code, token_salt)
+
+        # Obtain a random code timestamp and send SMS
+        random_code_resp = await self._get_random_code(telephone)
+        timestamp = random_code_resp.timestamp
+
+        sms_payload = SendSmsDTO(
+            telephone=telephone,
+            timestamp=timestamp,
+            token=pre_auth_response.token,
+            sign=sign,
+            nationcode=country_code,
+        ).to_dict()
+        await self._client.post_json(
+            "/api/user/sms/validcode/send", SendSmsVO, json=sms_payload
+        )
+
+    async def _token(self) -> None:
+        """Get a random code."""
+        await self._client.post_json(
+            "/api/user/query/token", QueryTokenVO, json=QueryTokenDTO().to_dict()
+        )
+
+    async def _get_random_code(self, email: str) -> RandomCodeVO:
+        """Get a random code."""
+        payload = RandomCodeDTO(account=email).to_dict()
+        return await self._client.post_json(
+            "/api/official/user/query/random/code", RandomCodeVO, json=payload
+        )
+
+    async def _get_access_token(
+        self, email: str, encoded_password: str, random_code_timestamp: str
+    ) -> LoginVO:
+        """Get an access token."""
+        payload = LoginDTO(
+            account=email,
+            password=encoded_password,
+            login_method=LoginMethod.PHONE if email.isdigit() else LoginMethod.EMAIL,
+            timestamp=random_code_timestamp,
+        ).to_dict()
+        try:
+            return await self._client.post_json(
+                "/api/official/user/account/login/new", LoginVO, json=payload
+            )
+        except ApiException as err:
+            if "verification code" in str(err):
+                raise SmsVerificationRequired(str(err), random_code_timestamp) from err
+            raise