notex-python 0.1.0__py3-none-any.whl

notex_sdk/models.py

@@ -0,0 +1,429 @@
+"""Small, dependency-free typed models for NoteX API responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, List, Literal, Mapping, Optional
+
+TaskStatus = Literal["PENDING", "PROCESSING", "SUCCESS", "FAILURE"]
+
+
+def _data(response: Mapping[str, Any]) -> Mapping[str, Any]:
+    value = response.get("data", {})
+    if not isinstance(value, Mapping):
+        raise ValueError("NoteX response field 'data' must be an object")
+    return value
+
+
+@dataclass(frozen=True)
+class Credits:
+    balance: Optional[int]
+    total_credits: Optional[int]
+    reward_credits: Optional[int]
+    purchased_credits: Optional[int]
+    plan_code: Optional[str]
+    plan_name: Optional[str]
+    user_id: Optional[str]
+    user_name: Optional[str]
+    user_type: Optional[str]
+    role: Optional[str]
+    has_paid: Optional[bool]
+    has_purchased: Optional[bool]
+    meeting_access: Optional[bool]
+    renew_date: Optional[str]
+    enterprise: Mapping[str, Any]
+    raw: Mapping[str, Any]
+
+    @classmethod
+    def from_response(cls, response: Mapping[str, Any]) -> "Credits":
+        data = _data(response)
+        balance = cls._optional_int(data, "balance", "total_credits")
+        enterprise = data.get("enterprise")
+        return cls(
+            balance=balance,
+            total_credits=cls._optional_int(data, "total_credits", "balance"),
+            reward_credits=cls._optional_int(data, "reward_credits"),
+            purchased_credits=cls._optional_int(data, "purchased_credits"),
+            plan_code=cls._optional_text(data, "plan_code"),
+            plan_name=cls._optional_text(data, "plan_name"),
+            user_id=cls._optional_text(data, "user_id"),
+            user_name=cls._optional_text(data, "user_name"),
+            user_type=cls._optional_text(data, "user_type"),
+            role=cls._optional_text(data, "role"),
+            has_paid=cls._optional_bool(data, "is_paid_user", "hasPaid"),
+            has_purchased=cls._optional_bool(data, "has_purchased", "hasPurchased"),
+            meeting_access=cls._optional_bool(data, "meeting_access"),
+            renew_date=cls._optional_text(data, "renew_date"),
+            enterprise=dict(enterprise) if isinstance(enterprise, Mapping) else {},
+            raw=dict(data),
+        )
+
+    @staticmethod
+    def _optional_int(data: Mapping[str, Any], *keys: str) -> Optional[int]:
+        value = next((data[key] for key in keys if data.get(key) is not None), None)
+        return int(value) if value is not None else None
+
+    @staticmethod
+    def _optional_text(data: Mapping[str, Any], *keys: str) -> Optional[str]:
+        value = next((data[key] for key in keys if data.get(key) is not None), None)
+        return str(value) if value is not None else None
+
+    @staticmethod
+    def _optional_bool(data: Mapping[str, Any], *keys: str) -> Optional[bool]:
+        value = next((data[key] for key in keys if data.get(key) is not None), None)
+        return bool(value) if value is not None else None
+
+
+@dataclass(frozen=True)
+class Quota:
+    data: Mapping[str, Any]
+
+    @classmethod
+    def from_response(cls, response: Mapping[str, Any]) -> "Quota":
+        return cls(data=dict(_data(response)))
+
+
+@dataclass(frozen=True)
+class UserProfile:
+    user_id: str
+    email: str
+    name: str
+    image: Optional[str]
+    role: str
+    preferences: Mapping[str, Any]
+    created_at: Optional[str]
+
+    @classmethod
+    def from_response(cls, response: Mapping[str, Any]) -> "UserProfile":
+        data = _data(response)
+        required = ("user_id", "email", "name", "role")
+        missing = [field for field in required if field not in data]
+        if missing:
+            raise ValueError(f"NoteX profile response is missing: {', '.join(missing)}")
+        return cls(
+            user_id=str(data["user_id"]),
+            email=str(data["email"]),
+            name=str(data["name"]),
+            image=str(data["image"]) if data.get("image") is not None else None,
+            role=str(data["role"]),
+            preferences=dict(data.get("preferences") or {}),
+            created_at=str(data["createdAt"]) if data.get("createdAt") is not None else None,
+        )
+
+
+@dataclass(frozen=True)
+class NoteItem:
+    note_id: str
+    title: str
+    folder_id: Optional[str]
+    type: str
+    created_at: str
+    updated_at: str
+    duration: Optional[int]
+    short_summary: Optional[str]
+    is_public: Optional[bool]
+    is_password_protected: Optional[bool]
+    share_link: Optional[str]
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> "NoteItem":
+        required = ("note_id", "title", "type", "createdAt", "updatedAt")
+        missing = [field for field in required if field not in value]
+        if missing:
+            raise ValueError(f"NoteX note is missing: {', '.join(missing)}")
+        return cls(
+            note_id=str(value["note_id"]),
+            title=str(value["title"]),
+            folder_id=str(value["folder_id"]) if value.get("folder_id") is not None else None,
+            type=str(value["type"]),
+            created_at=str(value["createdAt"]),
+            updated_at=str(value["updatedAt"]),
+            duration=int(value["duration"]) if value.get("duration") is not None else None,
+            short_summary=(str(value["short_summary"]) if value.get("short_summary") is not None else None),
+            is_public=bool(value["is_public"]) if value.get("is_public") is not None else None,
+            is_password_protected=(
+                bool(value["is_password_protected"])
+                if value.get("is_password_protected") is not None
+                else None
+            ),
+            share_link=str(value["share_link"]) if value.get("share_link") is not None else None,
+        )
+
+
+@dataclass(frozen=True)
+class NotesPage:
+    items: List[NoteItem]
+    total: Optional[int]
+    next_cursor: Optional[str]
+    has_more: Optional[bool]
+    page: Optional[int]
+    limit: Optional[int]
+
+    @classmethod
+    def from_response(cls, response: Mapping[str, Any]) -> "NotesPage":
+        raw_data = response.get("data", [])
+        if isinstance(raw_data, list):
+            raw_items = raw_data
+            metadata: Mapping[str, Any] = {}
+        elif isinstance(raw_data, Mapping):
+            metadata = raw_data
+            raw_items = raw_data.get("notes", raw_data.get("items", []))
+        else:
+            raise ValueError("NoteX notes response field 'data' must be an object or list")
+        if not isinstance(raw_items, list):
+            raise ValueError("NoteX notes response field 'notes' must be a list")
+        return cls(
+            items=[NoteItem.from_mapping(item) for item in raw_items if isinstance(item, Mapping)],
+            total=(
+                int(metadata["total_notes"])
+                if metadata.get("total_notes") is not None
+                else int(metadata["total"]) if metadata.get("total") is not None else None
+            ),
+            next_cursor=(
+                str(metadata["next_cursor"])
+                if metadata.get("next_cursor") is not None
+                else None
+            ),
+            has_more=bool(metadata["has_more"]) if metadata.get("has_more") is not None else None,
+            page=int(metadata["page"]) if metadata.get("page") is not None else None,
+            limit=int(metadata["limit"]) if metadata.get("limit") is not None else None,
+        )
+
+
+@dataclass(frozen=True)
+class PresignedUpload:
+    """Internal normalized result of the presigned URL API."""
+
+    upload_url: str
+    file_url: str
+    file_name: Optional[str]
+    full_path: Optional[str]
+    method: str
+    headers: Mapping[str, str]
+    expires_at: Optional[str]
+
+    @classmethod
+    def from_response(cls, response: Mapping[str, Any]) -> "PresignedUpload":
+        data = _data(response)
+        upload_url = data.get("upload_url") or data.get("presigned_url")
+        file_url = data.get("file_url") or data.get("full_path")
+        if not upload_url or not file_url:
+            raise ValueError("NoteX presigned upload response must include upload_url and file_url")
+        raw_headers = data.get("headers") or {}
+        if not isinstance(raw_headers, Mapping):
+            raise ValueError("NoteX presigned upload response field 'headers' must be an object")
+        method = str(data.get("method") or "PUT").upper()
+        if method != "PUT":
+            raise ValueError(f"Unsupported NoteX presigned upload method: {method}")
+        return cls(
+            upload_url=str(upload_url),
+            file_url=str(file_url),
+            file_name=str(data["file_name"]) if data.get("file_name") is not None else None,
+            full_path=str(data["full_path"]) if data.get("full_path") is not None else None,
+            method=method,
+            headers={str(key): str(value) for key, value in raw_headers.items()},
+            expires_at=str(data["expires_at"]) if data.get("expires_at") is not None else None,
+        )
+
+
+@dataclass(frozen=True)
+class SourceValidation:
+    data: Mapping[str, Any]
+
+    @classmethod
+    def from_response(cls, response: Mapping[str, Any]) -> "SourceValidation":
+        return cls(data=dict(_data(response)))
+
+
+@dataclass(frozen=True)
+class TaskSubmission:
+    task_id: str
+    status: Optional[str]
+    user_id: Optional[str]
+
+    @classmethod
+    def from_response(cls, response: Mapping[str, Any]) -> "TaskSubmission":
+        data = _data(response)
+        if not data.get("task_id"):
+            raise ValueError("NoteX task submission response is missing 'task_id'")
+        return cls(
+            task_id=str(data["task_id"]),
+            status=str(response["status"]) if response.get("status") is not None else None,
+            user_id=str(data["user_id"]) if data.get("user_id") is not None else None,
+        )
+
+
+@dataclass(frozen=True)
+class TaskResult:
+    status: TaskStatus
+    data: Optional[Mapping[str, Any]]
+    error: Optional[str]
+
+    @classmethod
+    def from_response(cls, response: Mapping[str, Any]) -> "TaskResult":
+        status = str(response.get("status", "")).upper()
+        if status not in {"PENDING", "PROCESSING", "SUCCESS", "FAILURE"}:
+            raise ValueError(f"Unknown NoteX task status: {status or '<missing>'}")
+        value = response.get("data")
+        return cls(
+            status=status,  # type: ignore[arg-type]
+            data=dict(value) if isinstance(value, Mapping) else None,
+            error=str(response["error"]) if response.get("error") is not None else None,
+        )
+
+    def success_data(self) -> Mapping[str, Any]:
+        if self.status != "SUCCESS" or self.data is None:
+            raise ValueError("Task result is not a successful response with data")
+        return self.data
+
+
+@dataclass(frozen=True)
+class GeneratedNote:
+    note_id: str
+    title: Optional[str]
+    summary: Optional[str]
+
+    @classmethod
+    def from_task_result(cls, result: TaskResult) -> "GeneratedNote":
+        data = result.success_data()
+        if not data.get("note_id"):
+            raise ValueError("Generated note result is missing 'note_id'")
+        return cls(
+            note_id=str(data["note_id"]),
+            title=str(data["title"]) if data.get("title") is not None else None,
+            summary=str(data["summary"]) if data.get("summary") is not None else None,
+        )
+
+
+@dataclass(frozen=True)
+class Flashcard:
+    front: str
+    back: str
+
+
+@dataclass(frozen=True)
+class FlashcardSet:
+    flashcard_set_id: str
+    set_name: Optional[str]
+    cards: List[Flashcard]
+
+    @classmethod
+    def from_task_result(cls, result: TaskResult) -> "FlashcardSet":
+        data = result.success_data()
+        cards = data.get("cards")
+        if not data.get("flashcard_set_id") or not isinstance(cards, list):
+            raise ValueError("Flashcard task result has an invalid shape")
+        return cls(
+            flashcard_set_id=str(data["flashcard_set_id"]),
+            set_name=str(data["set_name"]) if data.get("set_name") is not None else None,
+            cards=[Flashcard(front=str(card["front"]), back=str(card["back"])) for card in cards if isinstance(card, Mapping) and "front" in card and "back" in card],
+        )
+
+
+@dataclass(frozen=True)
+class QuizQuestion:
+    question: str
+    options: List[str]
+    answer: str
+
+
+@dataclass(frozen=True)
+class QuizSet:
+    quiz_set_id: str
+    set_name: Optional[str]
+    questions: List[QuizQuestion]
+
+    @classmethod
+    def from_task_result(cls, result: TaskResult) -> "QuizSet":
+        data = result.success_data()
+        questions = data.get("questions")
+        if not data.get("quiz_set_id") or not isinstance(questions, list):
+            raise ValueError("Quiz task result has an invalid shape")
+        return cls(
+            quiz_set_id=str(data["quiz_set_id"]),
+            set_name=str(data["set_name"]) if data.get("set_name") is not None else None,
+            questions=[
+                QuizQuestion(
+                    question=str(question["question"]),
+                    options=[str(option) for option in question.get("options", [])],
+                    answer=str(question["answer"]),
+                )
+                for question in questions
+                if isinstance(question, Mapping) and "question" in question and "answer" in question
+            ],
+        )
+
+
+@dataclass(frozen=True)
+class MindmapNode:
+    title: str
+    children: List["MindmapNode"]
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> "MindmapNode":
+        if "title" not in value:
+            raise ValueError("Mindmap node is missing 'title'")
+        children = value.get("children", [])
+        if not isinstance(children, list):
+            raise ValueError("Mindmap node field 'children' must be a list")
+        return cls(
+            title=str(value["title"]),
+            children=[cls.from_mapping(child) for child in children if isinstance(child, Mapping)],
+        )
+
+
+@dataclass(frozen=True)
+class Mindmap:
+    note_id: str
+    root: MindmapNode
+
+    @classmethod
+    def from_task_result(cls, result: TaskResult) -> "Mindmap":
+        data = result.success_data()
+        if not data.get("note_id") or not isinstance(data.get("mindmap"), Mapping):
+            raise ValueError("Mindmap task result has an invalid shape")
+        return cls(note_id=str(data["note_id"]), root=MindmapNode.from_mapping(data["mindmap"]))
+
+
+@dataclass(frozen=True)
+class Podcast:
+    note_id: str
+    podcast_url: str
+
+    @classmethod
+    def from_task_result(cls, result: TaskResult) -> "Podcast":
+        data = result.success_data()
+        if not data.get("note_id") or not data.get("podcast_url"):
+            raise ValueError("Podcast task result has an invalid shape")
+        return cls(note_id=str(data["note_id"]), podcast_url=str(data["podcast_url"]))
+
+
+@dataclass(frozen=True)
+class Video:
+    note_id: str
+    video_url: str
+
+    @classmethod
+    def from_task_result(cls, result: TaskResult) -> "Video":
+        data = result.success_data()
+        if not data.get("note_id") or not data.get("video_url"):
+            raise ValueError("Video task result has an invalid shape")
+        return cls(note_id=str(data["note_id"]), video_url=str(data["video_url"]))
+
+
+@dataclass(frozen=True)
+class SlideDeck:
+    note_id: str
+    slide_url: str
+    slide_pdf_url: Optional[str]
+
+    @classmethod
+    def from_task_result(cls, result: TaskResult) -> "SlideDeck":
+        data = result.success_data()
+        if not data.get("note_id") or not data.get("slide_url"):
+            raise ValueError("Slide task result has an invalid shape")
+        return cls(
+            note_id=str(data["note_id"]),
+            slide_url=str(data["slide_url"]),
+            slide_pdf_url=str(data["slide_pdf_url"]) if data.get("slide_pdf_url") is not None else None,
+        )

notex_sdk/py.typed

@@ -0,0 +1 @@
+

notex_sdk/transport.py

@@ -0,0 +1,140 @@
+"""HTTP transport and retry policy kept separate from NoteX endpoint logic."""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from typing import Any, BinaryIO, Dict, FrozenSet, Mapping, Optional, Union
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from .errors import (
+    NotexAPIError,
+    NotexAuthenticationError,
+    NotexPermissionError,
+    NotexRateLimitError,
+)
+
+RequestContent = Optional[Union[bytes, BinaryIO]]
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Retry only operations that are safe to repeat by default."""
+
+    max_attempts: int = 3
+    initial_delay: float = 0.5
+    max_delay: float = 5.0
+    retry_status_codes: FrozenSet[int] = frozenset({429, 500, 502, 503, 504})
+    retry_methods: FrozenSet[str] = frozenset({"GET", "HEAD"})
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be at least 1")
+        if self.initial_delay < 0 or self.max_delay < 0:
+            raise ValueError("retry delays cannot be negative")
+
+
+class UrllibTransport:
+    """Small standard-library transport with injectable retry behavior."""
+
+    def __init__(
+        self,
+        *,
+        timeout: float = 30.0,
+        retry_policy: Optional[RetryPolicy] = None,
+        sleep_fn=time.sleep,
+    ) -> None:
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than 0")
+        self.timeout = timeout
+        self.retry_policy = retry_policy or RetryPolicy()
+        self._sleep = sleep_fn
+
+    def send(
+        self,
+        *,
+        url: str,
+        method: str,
+        headers: Mapping[str, str],
+        content: RequestContent = None,
+        retryable: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        normalized_method = method.upper()
+        can_retry = (
+            retryable if retryable is not None else normalized_method in self.retry_policy.retry_methods
+        )
+        # A streamed body cannot be replayed safely without reopening its file.
+        if content is not None and not isinstance(content, bytes):
+            can_retry = False
+        attempts = self.retry_policy.max_attempts if can_retry else 1
+
+        for attempt in range(1, attempts + 1):
+            request = Request(url, data=content, headers=dict(headers), method=normalized_method)
+            try:
+                with urlopen(request, timeout=self.timeout) as response:
+                    return self.decode_json(response.read())
+            except HTTPError as exc:
+                payload = self.decode_json(exc.read())
+                retry_after = self._retry_after(exc.headers.get("Retry-After"))
+                if exc.code in self.retry_policy.retry_status_codes and attempt < attempts:
+                    self._sleep(self._delay(attempt, retry_after))
+                    continue
+                raise self._http_error(exc, payload, retry_after) from exc
+            except URLError as exc:
+                if attempt < attempts:
+                    self._sleep(self._delay(attempt, None))
+                    continue
+                raise NotexAPIError(f"Could not connect to NoteX API: {exc.reason}") from exc
+
+        raise AssertionError("retry loop ended unexpectedly")
+
+    def _delay(self, attempt: int, retry_after: Optional[float]) -> float:
+        if retry_after is not None:
+            # Servers use this header to control when a request may be retried.
+            # Do not shorten it: doing so can create another rate-limit response.
+            return retry_after
+        return min(self.retry_policy.initial_delay * (2 ** (attempt - 1)), self.retry_policy.max_delay)
+
+    @staticmethod
+    def _retry_after(value: Optional[str]) -> Optional[float]:
+        if not value:
+            return None
+        try:
+            return max(0.0, float(value))
+        except ValueError:
+            try:
+                return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
+            except (TypeError, ValueError):
+                return None
+
+    @staticmethod
+    def _http_error(
+        error: HTTPError,
+        payload: Mapping[str, Any],
+        retry_after: Optional[float],
+    ) -> NotexAPIError:
+        error_type = {
+            401: NotexAuthenticationError,
+            403: NotexPermissionError,
+            429: NotexRateLimitError,
+        }.get(error.code, NotexAPIError)
+        return error_type(
+            str(payload.get("message") or error.reason or "NoteX API request failed"),
+            status_code=error.code,
+            error_key=payload.get("error_key"),
+            body=payload,
+            retry_after=retry_after,
+        )
+
+    @staticmethod
+    def decode_json(raw_body: bytes) -> Dict[str, Any]:
+        if not raw_body:
+            return {}
+        try:
+            value = json.loads(raw_body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return {"message": raw_body.decode("utf-8", errors="replace")}
+        return value if isinstance(value, dict) else {"data": value}