supernote 0.13.6__py3-none-any.whl

supernote/client/api_model.py

@@ -0,0 +1,231 @@
+"""Model classes for the Supernote Service API."""
+
+from dataclasses import dataclass, field
+
+from mashumaro import field_options
+from mashumaro.config import BaseConfig
+from mashumaro.mixins.json import DataClassJSONMixin
+
+COUNTRY_CODE = 1
+BROWSER = "Chrome142"
+EQUIPMENT = 1
+LANGUAGE = "en"
+
+
+@dataclass
+class BaseResponse(DataClassJSONMixin):
+    """Base response class."""
+
+    success: bool = True
+    error_code: str = field(metadata=field_options(alias="errorCode"), default="")
+    error_msg: str = field(metadata=field_options(alias="errorMsg"), default="")
+
+
+@dataclass
+class QueryUserRequest(DataClassJSONMixin):
+    """Request to query user."""
+
+    account: str
+    country_code: int = field(
+        metadata=field_options(alias="countryCode"), default=COUNTRY_CODE
+    )
+
+    class Config(BaseConfig):
+        serialize_by_alias = True
+
+
+@dataclass(kw_only=True)
+class QueryUserResponse(BaseResponse):
+    """Response from query user call."""
+
+    user_id: str = field(metadata=field_options(alias="userId"))
+    user_name: str = field(metadata=field_options(alias="userName"))
+    birthday: str = field(metadata=field_options(alias="birthday"))
+    country_code: str = field(
+        metadata=field_options(alias="countryCode"), default=str(COUNTRY_CODE)
+    )
+    telephone: str = field(metadata=field_options(alias="telephone"), default="")
+    sex: str = ""
+    file_server: str = field(metadata=field_options(alias="fileServer"), default="")
+
+
+@dataclass
+class TokenRequest(DataClassJSONMixin):
+    """Request to token endpoint."""
+
+    class Config(BaseConfig):
+        serialize_by_alias = True
+
+
+@dataclass
+class TokenResponse(BaseResponse):
+    """Response from token endpoint."""
+
+
+@dataclass
+class UserRandomCodeRequest(DataClassJSONMixin):
+    """Request to get a random code."""
+
+    account: str
+    country_code: int = field(
+        metadata=field_options(alias="countryCode"), default=COUNTRY_CODE
+    )
+
+    class Config(BaseConfig):
+        serialize_by_alias = True
+
+
+@dataclass
+class UserRandomCodeResponse(BaseResponse):
+    """Response from login."""
+
+    random_code: str = field(metadata=field_options(alias="randomCode"), default="")
+    timestamp: str = ""
+
+
+@dataclass
+class UserLoginRequest(DataClassJSONMixin):
+    """Request to login."""
+
+    account: str
+    password: str
+    login_method: int = field(metadata=field_options(alias="loginMethod"))
+    timestamp: str
+    language: str = LANGUAGE
+    country_code: int = field(
+        metadata=field_options(alias="countryCode"), default=COUNTRY_CODE
+    )
+    browser: str = BROWSER
+    equipment: int = EQUIPMENT
+
+    class Config(BaseConfig):
+        serialize_by_alias = True
+
+
+@dataclass(kw_only=True)
+class UserLoginResponse(BaseResponse):
+    """Response from access token call."""
+
+    token: str
+
+
+@dataclass
+class UserSmsLoginRequest(DataClassJSONMixin):
+    """Request to login via sms."""
+
+    telephone: str
+    timestamp: str
+    valid_code: str = field(metadata=field_options(alias="validCode"))
+    # String like "1-{telephone}_validCode"
+    valid_code_key: str = field(metadata=field_options(alias="validCodeKey"))
+
+    country_code: int = field(
+        metadata=field_options(alias="countryCode"), default=COUNTRY_CODE
+    )
+    browser: str = BROWSER
+    equipment: int = EQUIPMENT
+
+    class Config(BaseConfig):
+        serialize_by_alias = True
+
+
+@dataclass
+class UserPreAuthRequest(DataClassJSONMixin):
+    """Request for pre-auth."""
+
+    account: str
+
+
+@dataclass
+class UserPreAuthResponse(BaseResponse):
+    """Response from pre-auth."""
+
+    token: str = ""
+
+
+@dataclass
+class UserSendSmsRequest(DataClassJSONMixin):
+    """Request to send SMS code."""
+
+    telephone: str
+    timestamp: str
+    token: str
+    sign: str
+    nationcode: int = field(
+        metadata=field_options(alias="nationcode"), default=COUNTRY_CODE
+    )
+
+    class Config(BaseConfig):
+        serialize_by_alias = True
+
+
+@dataclass
+class UserSendSmsResponse(BaseResponse):
+    """Response from send SMS."""
+
+    valid_code_key: str = field(
+        metadata=field_options(alias="validCodeKey"), default=""
+    )
+
+
+@dataclass(kw_only=True)
+class UserSmsLoginResponse(BaseResponse):
+    """Response from access token call."""
+
+    token: str
+
+
+@dataclass(kw_only=True)
+class File(DataClassJSONMixin):
+    """Representation of a file."""
+
+    id: int
+    directory_id: int = field(metadata=field_options(alias="directoryId"))
+    file_name: str = field(metadata=field_options(alias="fileName"))
+    size: int = 0
+    md5: str = ""
+    is_folder: str = field(metadata=field_options(alias="isFolder"))  # "Y" or "N"
+    create_time: int = field(metadata=field_options(alias="createTime"))
+    update_time: int = field(metadata=field_options(alias="updateTime"))
+
+
+@dataclass
+class FileListRequest(DataClassJSONMixin):
+    """Request for file list."""
+
+    directory_id: int = field(metadata=field_options(alias="directoryId"))
+    page_no: int = field(metadata=field_options(alias="pageNo"))
+    page_size: int = field(metadata=field_options(alias="pageSize"), default=20)
+    order: str = "time"
+    sequence: str = "desc"
+
+    class Config(BaseConfig):
+        serialize_by_alias = True
+
+
+@dataclass(kw_only=True)
+class FileListResponse(BaseResponse):
+    """Response from file list call."""
+
+    total: int
+    size: int
+    pages: int
+    file_list: list[File] = field(metadata=field_options(alias="userFileVOList"))
+
+
+@dataclass
+class GetFileDownloadUrlRequest(DataClassJSONMixin):
+    """Request for file download."""
+
+    file_id: int = field(metadata=field_options(alias="id"))
+    file_type: int = field(metadata=field_options(alias="type"), default=0)
+
+    class Config(BaseConfig):
+        serialize_by_alias = True
+
+
+@dataclass(kw_only=True)
+class GetFileDownloadUrlResponse(BaseResponse):
+    """Response from file download call."""
+
+    url: str

supernote/client/auth.py

@@ -0,0 +1,84 @@
+"""Library for authentication."""
+
+import logging
+import os
+import pickle
+from abc import ABC, abstractmethod
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AbstractAuth(ABC):
+    """Authentication library."""
+
+    @abstractmethod
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token."""
+
+
+class ConstantAuth(AbstractAuth):
+    """Authentication library."""
+
+    def __init__(self, access_token: str):
+        """Initialize the auth."""
+        self._access_token = access_token
+
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token."""
+        return self._access_token
+
+    @property
+    def token(self) -> str:
+        """Return the access token."""
+        return self._access_token
+
+
+class FileCacheAuth(AbstractAuth):
+    """Authentication library that caches token in a file."""
+
+    def __init__(self, cache_path: str):
+        """Initialize the auth."""
+        self._cache_path = cache_path
+        self._access_token: str | None = None
+        self._host: str | None = None
+        try:
+            self._load_from_cache()
+        except ValueError as err:
+            _LOGGER.info(f"No cached credentials found at {self._cache_path} ({err})")
+
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token."""
+        if self._access_token:
+            return self._access_token
+        raise ValueError(f"No access token found in cache: {self._cache_path}")
+
+    def get_host(self) -> str | None:
+        """Return the cached host URL."""
+        return self._host
+
+    def _load_from_cache(self) -> None:
+        if not os.path.exists(self._cache_path):
+            raise ValueError("Cache file does not exist")
+        try:
+            with open(self._cache_path, "rb") as f:
+                data = pickle.load(f)
+        except Exception as err:
+            raise ValueError(f"Failed to load token from cache: {err}")
+        if not isinstance(data, dict):
+            raise ValueError("Cache file is not a dictionary")
+        self._access_token = data["access_token"]
+        if "host" not in data:
+            raise ValueError("Cache file is missing host")
+        self._host = data["host"]
+
+    def save_credentials(self, token: str, host: str) -> None:
+        """Save access token and host to cache."""
+        self._access_token = token
+        self._host = host
+
+        # Ensure directory exists
+        os.makedirs(os.path.dirname(self._cache_path), exist_ok=True)
+
+        with open(self._cache_path, "wb") as f:
+            data = {"access_token": token, "host": host}
+            pickle.dump(data, f)

supernote/client/client.py

@@ -0,0 +1,365 @@
+"""Library for accessing backups in Supenote Cloud."""
+
+import hashlib
+import logging
+import uuid
+from typing import Any, Type, TypeVar
+
+import aiohttp
+from aiohttp import FormData
+from aiohttp.client_exceptions import ClientError
+
+from supernote.models.base import BaseResponse
+from supernote.models.system import FileChunkParams, FileChunkVO, UploadFileVO
+
+from .auth import AbstractAuth
+from .exceptions import (
+    ApiException,
+    BadRequestException,
+    ForbiddenException,
+    NotFoundException,
+    UnauthorizedException,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+__all__ = [
+    "Client",
+]
+
+
+_T = TypeVar("_T", bound=BaseResponse)
+
+CLOUD_API_URL = "https://cloud.supernote.com"
+HEADERS = {
+    "Content-Type": "application/json",
+    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36",
+}
+ACCESS_TOKEN = "x-access-token"
+XSRF_COOKIE = "XSRF-TOKEN"
+XSRF_HEADER = "X-XSRF-TOKEN"
+
+
+def _create_headers(host: str | None = None) -> dict[str, Any]:
+    headers = {
+        **HEADERS,
+    }
+    if host:
+        headers["Referer"] = host
+        headers["Origin"] = host
+    return headers
+
+
+class Client:
+    """Library that makes authenticated HTTP requests."""
+
+    def __init__(
+        self,
+        websession: aiohttp.ClientSession,
+        host: str | None = None,
+        auth: AbstractAuth | None = None,
+    ):
+        """Initialize the auth."""
+        self._websession = websession
+        self._host = host or CLOUD_API_URL
+        self._auth = auth
+        self._xsrf_token: str | None = None
+
+    @property
+    def host(self) -> str:
+        """Return the host URL."""
+        return self._host
+
+    def with_auth(self, auth: AbstractAuth) -> "Client":
+        """Return a new client with the given authentication credentials."""
+        return Client(self._websession, host=self._host, auth=auth)
+
+    def get_auth(self) -> AbstractAuth | None:
+        """Return the current authentication credentials."""
+        return self._auth
+
+    def _url(self, url: str) -> str:
+        if not (url.startswith("http://") or url.startswith("https://")):
+            if self._host.endswith("/"):
+                if url.startswith("/"):
+                    url = url[1:]
+            elif not url.startswith("/"):
+                url = f"/{url}"
+            url = f"{self._host}{url}"
+        return url
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        headers: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> aiohttp.ClientResponse:
+        """Make a request."""
+        if headers is None:
+            headers = _create_headers(self._host)
+        # Always get a fresh CSRF token
+        self._xsrf_token = await self._get_csrf_token()
+        headers[XSRF_HEADER] = self._xsrf_token
+
+        if self._auth and ACCESS_TOKEN not in headers:
+            access_token = await self._auth.async_get_access_token()
+            headers[ACCESS_TOKEN] = access_token
+        url = self._url(url)
+        _LOGGER.debug(
+            "request[%s]=%s %s %s",
+            method,
+            url,
+            kwargs.get("params"),
+            headers,
+        )
+        if method != "get" and "json" in kwargs:
+            _LOGGER.debug("request[post json]=%s", kwargs["json"])
+        response = await self._websession.request(
+            method, url, **kwargs, headers=headers
+        )
+        return response
+
+    async def get(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        """Make a get request."""
+        try:
+            resp = await self.request("get", url, **kwargs)
+        except ClientError as err:
+            raise ApiException(f"Error connecting to API: {err}") from err
+        return await self._raise_for_status(resp)
+
+    async def get_json(
+        self,
+        url: str,
+        data_cls: Type[_T],
+        **kwargs: Any,
+    ) -> _T:
+        """Make a get request and return json response."""
+        resp = await self.get(url, **kwargs)
+        try:
+            result = await resp.text()
+        except ClientError as err:
+            raise ApiException("Server returned malformed response") from err
+        _LOGGER.debug("response=%s", result)
+        try:
+            data_response = data_cls.from_json(result)
+        except (LookupError, ValueError) as err:
+            raise ApiException(f"Server return malformed response: {result}") from err
+        if not data_response.success:
+            raise ApiException(data_response.error_msg)
+        return data_response
+
+    async def post(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        """Make a post request."""
+        try:
+            resp = await self.request("post", url, **kwargs)
+        except ClientError as err:
+            raise ApiException(f"Error connecting to API: {err}") from err
+        return await self._raise_for_status(resp)
+
+    async def put(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        """Make a put request."""
+        try:
+            resp = await self.request("put", url, **kwargs)
+        except ClientError as err:
+            raise ApiException(f"Error connecting to API: {err}") from err
+        return await self._raise_for_status(resp)
+
+    async def get_content(self, url: str, **kwargs: Any) -> bytes:
+        """Make a get request and return bytes."""
+        resp = await self.get(url, **kwargs)
+        try:
+            return await resp.read()
+        except ClientError as err:
+            raise ApiException(f"Error reading response: {err}") from err
+
+    async def post_json(self, url: str, data_cls: Type[_T], **kwargs: Any) -> _T:
+        """Make a post request and return a json response."""
+        resp = await self.post(url, **kwargs)
+        try:
+            result = await resp.text()
+        except ClientError as err:
+            raise ApiException("Server returned malformed response") from err
+        try:
+            data_response = data_cls.from_json(result)
+        except (LookupError, ValueError) as err:
+            raise ApiException(
+                f"Server return malformed response type {data_cls.__name__}: {result}"
+            ) from err
+        if not data_response.success:
+            raise ApiException(data_response.error_msg)
+        return data_response
+
+    async def put_json(self, url: str, data_cls: Type[_T], **kwargs: Any) -> _T:
+        """Make a put request and return a json response."""
+        resp = await self.put(url, **kwargs)
+        try:
+            result = await resp.text()
+        except ClientError as err:
+            raise ApiException("Server returned malformed response") from err
+        try:
+            data_response = data_cls.from_json(result)
+        except (LookupError, ValueError) as err:
+            raise ApiException(
+                f"Server return malformed response type {data_cls.__name__}: {result}"
+            ) from err
+        if not data_response.success:
+            raise ApiException(data_response.error_msg)
+        return data_response
+
+    async def _get_csrf_token(self) -> str:
+        """Get the CSRF token."""
+        url = self._url("/api/csrf")
+        _LOGGER.debug("CSRF request[get]=%s %s", url, HEADERS)
+        resp = await self._websession.request("get", url, headers=HEADERS)
+        try:
+            await resp.text()
+        except ClientError as err:
+            raise ApiException("Server returned malformed response") from err
+        # Can be added back later for debugging
+        # _LOGGER.debug("CSRF response headers=%s", resp.headers)
+        token = resp.headers.get(XSRF_HEADER)
+        if token is None:
+            raise ApiException("Failed to get CSRF token from header")
+        return token
+
+    @classmethod
+    async def _raise_for_status(
+        cls, resp: aiohttp.ClientResponse
+    ) -> aiohttp.ClientResponse:
+        """Raise exceptions on failure methods."""
+        error_detail = await cls._error_detail(resp)
+        try:
+            resp.raise_for_status()
+        except aiohttp.ClientResponseError as err:
+            if err.status == 401:
+                raise UnauthorizedException(
+                    f"Unauthorized response from API ({err.status}): {error_detail}"
+                ) from err
+            if err.status == 403:
+                raise ForbiddenException(
+                    f"Forbidden response from API ({err.status}): {error_detail}"
+                ) from err
+            if err.status == 404:
+                raise NotFoundException(
+                    f"Not found response from API ({err.status}): {error_detail}"
+                ) from err
+            if err.status == 400:
+                raise BadRequestException(
+                    f"Bad request response from API ({err.status}): {error_detail}"
+                ) from err
+            error_message = f"Error response from API ({err.status}): {error_detail}"
+            raise ApiException(error_message) from err
+        except aiohttp.ClientError as err:
+            raise ApiException(f"Error from API: {err}") from err
+        return resp
+
+    @classmethod
+    async def _error_detail(cls, resp: aiohttp.ClientResponse) -> str | None:
+        """Returns an error message string from the APi response."""
+        if resp.status < 400:
+            return None
+        try:
+            result = await resp.text()
+        except ClientError:
+            return None
+        return result
+
+    async def _upload_to_oss(
+        self,
+        content: bytes,
+        filename: str,
+        full_upload_url: str | None,
+        part_upload_url: str | None,
+        chunk_size: int = 5 * 1024 * 1024,
+    ) -> None:
+        """Upload content to OSS (support single or multi-part)."""
+        size = len(content)
+
+        if size < chunk_size or part_upload_url is None:
+            if full_upload_url is None:
+                raise ValueError("No upload URL available")
+
+            # Compute MD5 of content for verification
+            content_md5 = hashlib.md5(content).hexdigest()
+
+            _LOGGER.debug(
+                "Uploading file %s in one chunk (MD5: %s)", filename, content_md5
+            )
+            data = FormData()
+            data.add_field("file", content, filename=filename)
+            # Pass empty dict to headers to avoid default application/json Content-Type
+            try:
+                resp = await self.request(
+                    "post",
+                    full_upload_url,
+                    data=data,
+                    headers={},
+                )
+            except ClientError as err:
+                raise ApiException("Failed to upload file") from err
+            # Parse the UploadFileVO response
+            try:
+                result = await resp.text()
+            except ClientError:
+                raise ApiException("Server returned malformed response")
+            _LOGGER.debug("Upload response: %s", result)
+            try:
+                upload_vo = UploadFileVO.from_json(result)
+            except (LookupError, ValueError) as err:
+                raise ApiException(
+                    f"Server returned malformed upload response: {result}"
+                ) from err
+            if not upload_vo.success:
+                raise ApiException(f"Upload failed: {upload_vo.error_msg}")
+
+            # Verify MD5 matches
+            if upload_vo.md5 != content_md5:
+                raise ApiException(
+                    f"MD5 mismatch: client={content_md5}, server={upload_vo.md5}"
+                )
+            return
+
+        upload_id = uuid.uuid4().hex
+        # Break into chunks
+        chunks = [content[i : i + chunk_size] for i in range(0, size, chunk_size)]
+        for i, chunk in enumerate(chunks):
+            chunk_md5 = hashlib.md5(chunk).hexdigest()
+            _LOGGER.debug(f"Uploading chunk {i + 1} of {size} ({len(chunk)} bytes)")
+            data = FormData()
+            data.add_field("file", chunk, filename=filename)
+            params = FileChunkParams(
+                upload_id=upload_id,
+                part_number=i + 1,
+                total_chunks=len(chunks),
+            )
+            try:
+                resp = await self.request(
+                    "post",
+                    part_upload_url,
+                    data=data,
+                    params={k: v for k, v in params.to_dict().items() if v is not None},
+                    headers={},
+                )
+            except ApiException as err:
+                raise ApiException(f"Chunk upload failed: {err}")
+            try:
+                result = await resp.text()
+            except ClientError as err:
+                raise ApiException("Failed to get chunk response") from err
+            try:
+                _LOGGER.debug("Chunk response: %s", result)
+                chunk_vo = FileChunkVO.from_json(result)
+            except (LookupError, ValueError) as err:
+                raise ApiException(
+                    f"Server returned malformed chunk response: {result}"
+                ) from err
+
+            if not chunk_vo.success:
+                raise ApiException(f"Chunk upload failed: {chunk_vo.error_msg}")
+
+            # Verify MD5 matches
+            if chunk_vo.chunk_md5 != chunk_md5:
+                raise ApiException(
+                    f"Chunk {i + 1} MD5 mismatch: client={chunk_md5}, server={chunk_vo.chunk_md5}"
+                )