notex-python 0.1.0__py3-none-any.whl

notex_sdk/client.py

@@ -0,0 +1,496 @@
+"""Synchronous, dependency-free client for API-key-enabled NoteX endpoints."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any, BinaryIO, Dict, Mapping, Optional, Sequence, Union
+from urllib.parse import quote, urlencode
+
+from .config import (
+    CREDITS_ME_ENDPOINT,
+    CREDITS_QUOTA_ENDPOINT,
+    DEFAULT_BASE_URL,
+    FLASHCARDS_CREATE_ENDPOINT,
+    MINDMAP_CREATE_ENDPOINT,
+    NOTE_CREATE_ENDPOINT,
+    NOTE_VALIDATE_ENDPOINT,
+    PODCAST_CREATE_ENDPOINT,
+    PRESIGNED_URL_ENDPOINT,
+    QUIZ_CREATE_ENDPOINT,
+    QUIZ_VIDEO_CREATE_ENDPOINT,
+    SHORTS_CREATE_ENDPOINT,
+    SLIDE_CREATE_ENDPOINT,
+    TASK_RESULT_ENDPOINT,
+    TRANSLATE_CREATE_ENDPOINT,
+    USER_NOTES_ENDPOINT,
+    USER_PROFILE_ENDPOINT,
+)
+from .errors import (
+    NotexAPIError,
+    NotexAuthenticationError,
+    NotexTaskError,
+    NotexUploadError,
+)
+from .models import (
+    Credits,
+    NotesPage,
+    PresignedUpload,
+    Quota,
+    SourceValidation,
+    TaskResult,
+    TaskSubmission,
+    UserProfile,
+)
+from .transport import RetryPolicy, UrllibTransport
+
+Headers = Optional[Mapping[str, str]]
+
+
+class _RedactedHeaders(dict):
+    """Request headers whose repr never exposes authentication credentials."""
+
+    _SENSITIVE_NAMES = {"authorization", "x-api-key"}
+
+    def __repr__(self) -> str:
+        redacted = {
+            key: "<redacted>" if key.lower() in self._SENSITIVE_NAMES else value
+            for key, value in self.items()
+        }
+        return repr(redacted)
+
+
+class NotexClient:
+    """A request-scoped client for one NoteX API key.
+
+    In a multi-user application, create this client from the credential
+    resolved for the current request or background job. The SDK never stores,
+    creates, lists, or deletes user API keys.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        auth_header: str = "X-API-Key",
+        timeout: float = 30.0,
+        retry_policy: Optional[RetryPolicy] = None,
+        transport: Optional[UrllibTransport] = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.auth_header = auth_header
+        self.timeout = timeout
+
+        if self.auth_header not in {"X-API-Key", "Authorization"}:
+            raise ValueError("auth_header must be 'X-API-Key' or 'Authorization'")
+        if self.api_key and not self.api_key.startswith("ntx_"):
+            raise ValueError("NoteX API keys must start with 'ntx_'")
+        self._transport = transport or UrllibTransport(timeout=timeout, retry_policy=retry_policy)
+
+    def get_credits(self, *, endpoint: str = CREDITS_ME_ENDPOINT, base_url: Optional[str] = None) -> Credits:
+        return Credits.from_response(self.request("GET", endpoint, base_url=base_url))
+
+    def get_quota(self, *, endpoint: str = CREDITS_QUOTA_ENDPOINT, base_url: Optional[str] = None) -> Quota:
+        return Quota.from_response(self.request("GET", endpoint, base_url=base_url))
+
+    def get_profile(self, *, endpoint: str = USER_PROFILE_ENDPOINT, base_url: Optional[str] = None) -> UserProfile:
+        return UserProfile.from_response(self.request("GET", endpoint, base_url=base_url))
+
+    def list_notes(
+        self,
+        *,
+        note_type: Optional[str] = None,
+        tab: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        page: Optional[int] = None,
+        sort_field: Optional[str] = None,
+        sort_order: Optional[int] = None,
+        endpoint: str = USER_NOTES_ENDPOINT,
+        base_url: Optional[str] = None,
+    ) -> NotesPage:
+        if sort_order is not None and sort_order not in {-1, 1}:
+            raise ValueError("sort_order must be 1 (ascending) or -1 (descending)")
+        if limit is not None and limit < 1:
+            raise ValueError("limit must be greater than 0")
+        if page is not None and page < 1:
+            raise ValueError("page must be greater than 0")
+        return NotesPage.from_response(
+            self.request(
+                "GET",
+                endpoint,
+                params={
+                    key: value
+                    for key, value in {
+                        "type": note_type,
+                        "tab": tab,
+                        "limit": limit,
+                        "cursor": cursor,
+                        "page": page,
+                        "sort_field": sort_field,
+                        "sort_order": sort_order,
+                    }.items()
+                    if value is not None
+                },
+                base_url=base_url,
+            )
+        )
+
+    def _request_presigned_upload(
+        self,
+        file_name: str,
+        *,
+        is_public: Optional[bool] = None,
+        endpoint: str = PRESIGNED_URL_ENDPOINT,
+        base_url: Optional[str] = None,
+    ) -> PresignedUpload:
+        self._require_text(file_name, "file_name")
+        params: Dict[str, Any] = {"file_name": file_name}
+        if is_public is not None:
+            params["is_public"] = is_public
+        return PresignedUpload.from_response(
+            self.request("GET", endpoint, params=params, base_url=base_url)
+        )
+
+    def _upload_file(
+        self,
+        upload: PresignedUpload,
+        file_path: Union[str, Path],
+        *,
+        content_type: Optional[str] = None,
+    ) -> None:
+        path = Path(file_path)
+        self._require_text(upload.upload_url, "upload_url")
+        try:
+            size = path.stat().st_size
+            headers = dict(upload.headers)
+            signed_content_type = self._get_header(headers, "Content-Type")
+            if content_type and signed_content_type and content_type != signed_content_type:
+                raise NotexUploadError(
+                    "content_type does not match the Content-Type returned by NoteX presign"
+                )
+            if content_type and not signed_content_type:
+                headers["Content-Type"] = content_type
+            if not self._get_header(headers, "Content-Length"):
+                headers["Content-Length"] = str(size)
+            with path.open("rb") as file_handle:
+                self._send(
+                    url=upload.upload_url,
+                    method=upload.method,
+                    headers=headers,
+                    content=file_handle,
+                )
+        except OSError as exc:
+            raise NotexUploadError(f"Could not read file '{path.name}' for NoteX upload") from exc
+
+    def create_note_from_file(
+        self,
+        file_path: Union[str, Path],
+        *,
+        upload_file_name: Optional[str] = None,
+        is_public: Optional[bool] = None,
+        language_hints: Optional[Sequence[str]] = None,
+        use_ocr: Optional[bool] = None,
+        summary_style: Optional[str] = None,
+        writing_style: Optional[str] = None,
+        human_style: Optional[str] = None,
+        is_record: Optional[bool] = None,
+        bot_id: Optional[str] = None,
+        record_session_id: Optional[str] = None,
+        device_meeting_id: Optional[str] = None,
+        target_language: Optional[str] = None,
+        content_type: Optional[str] = None,
+        presigned_endpoint: str = PRESIGNED_URL_ENDPOINT,
+        create_endpoint: str = NOTE_CREATE_ENDPOINT,
+        base_url: Optional[str] = None,
+        headers: Headers = None,
+    ) -> TaskSubmission:
+        """Upload a local file internally and submit asynchronous note creation.
+
+        This method returns as soon as NoteX returns a task id. It never polls
+        the task; call it from an application worker rather than a web handler.
+        """
+
+        path = Path(file_path)
+        if not path.is_file():
+            raise NotexUploadError(f"File does not exist or is not a file: {path}")
+        if upload_file_name is not None:
+            self._require_text(upload_file_name, "upload_file_name")
+        try:
+            upload = self._request_presigned_upload(
+                upload_file_name or path.name,
+                is_public=is_public,
+                endpoint=presigned_endpoint,
+                base_url=base_url,
+            )
+            self._upload_file(upload, path, content_type=content_type)
+            return self.create_note(
+                file_url=upload.file_url,
+                language_hints=language_hints,
+                use_ocr=use_ocr,
+                summary_style=summary_style,
+                writing_style=writing_style,
+                human_style=human_style,
+                is_record=is_record,
+                bot_id=bot_id,
+                record_session_id=record_session_id,
+                device_meeting_id=device_meeting_id,
+                target_language=target_language,
+                endpoint=create_endpoint,
+                base_url=base_url,
+                headers=headers,
+            )
+        except NotexAPIError:
+            raise
+        except OSError as exc:
+            raise NotexUploadError(f"Could not prepare '{path.name}' for NoteX upload") from exc
+
+    def validate_source(
+        self,
+        *,
+        web_url: Optional[str] = None,
+        file_url: Optional[str] = None,
+        endpoint: str = NOTE_VALIDATE_ENDPOINT,
+        base_url: Optional[str] = None,
+        headers: Headers = None,
+    ) -> SourceValidation:
+        return SourceValidation.from_response(
+            self.request(
+                "POST",
+                endpoint,
+                body=self._source_body(web_url=web_url, file_url=file_url),
+                base_url=base_url,
+                headers=headers,
+            )
+        )
+
+    def create_note(
+        self,
+        *,
+        web_url: Optional[str] = None,
+        file_url: Optional[str] = None,
+        language_hints: Optional[Sequence[str]] = None,
+        use_ocr: Optional[bool] = None,
+        summary_style: Optional[str] = None,
+        writing_style: Optional[str] = None,
+        human_style: Optional[str] = None,
+        is_record: Optional[bool] = None,
+        bot_id: Optional[str] = None,
+        record_session_id: Optional[str] = None,
+        device_meeting_id: Optional[str] = None,
+        target_language: Optional[str] = None,
+        endpoint: str = NOTE_CREATE_ENDPOINT,
+        base_url: Optional[str] = None,
+        headers: Headers = None,
+    ) -> TaskSubmission:
+        body = self._source_body(web_url=web_url, file_url=file_url)
+        optional_values = {
+            "language_hints": list(language_hints) if language_hints is not None else None,
+            "use_ocr": use_ocr,
+            "summary_style": summary_style,
+            "writing_style": writing_style,
+            "human_style": human_style,
+            "is_record": is_record,
+            "bot_id": bot_id,
+            "record_session_id": record_session_id,
+            "device_meeting_id": device_meeting_id,
+            "target_language": target_language,
+        }
+        body.update({key: value for key, value in optional_values.items() if value is not None})
+        return TaskSubmission.from_response(
+            self.request("POST", endpoint, body=body, base_url=base_url, headers=headers)
+        )
+
+    def create_note_from_url(self, web_url: str, **options: Any) -> TaskSubmission:
+        return self.create_note(web_url=web_url, **options)
+
+    def create_note_from_file_url(self, file_url: str, **options: Any) -> TaskSubmission:
+        return self.create_note(file_url=file_url, **options)
+
+    def create_flashcards(
+        self,
+        note_id: str,
+        *,
+        num_cards: Optional[Union[int, str]] = None,
+        set_name: Optional[str] = None,
+        difficulty: Optional[str] = None,
+        custom_prompt: Optional[str] = None,
+        community: Optional[bool] = None,
+        endpoint: str = FLASHCARDS_CREATE_ENDPOINT,
+        base_url: Optional[str] = None,
+        headers: Headers = None,
+    ) -> TaskSubmission:
+        return self._submit_form_task(endpoint, {"note_id": note_id, "num_cards": num_cards, "set_name": set_name, "difficulty": difficulty, "custom_prompt": custom_prompt, "community": community}, base_url, headers)
+
+    def create_mindmap(self, note_id: str, *, community: Optional[bool] = None, endpoint: str = MINDMAP_CREATE_ENDPOINT, base_url: Optional[str] = None, headers: Headers = None) -> TaskSubmission:
+        return self._submit_form_task(endpoint, {"note_id": note_id, "community": community}, base_url, headers)
+
+    def create_podcast(
+        self,
+        note_id: str,
+        duration: int,
+        *,
+        speakers: Optional[int] = None,
+        voice: Optional[str] = None,
+        voice1: Optional[str] = None,
+        voice2: Optional[str] = None,
+        community: Optional[bool] = None,
+        endpoint: str = PODCAST_CREATE_ENDPOINT,
+        base_url: Optional[str] = None,
+        headers: Headers = None,
+    ) -> TaskSubmission:
+        if duration <= 0:
+            raise ValueError("duration must be greater than 0")
+        return self._submit_form_task(endpoint, {"note_id": note_id, "duration": duration, "speakers": speakers, "voice": voice, "voice1": voice1, "voice2": voice2, "community": community}, base_url, headers)
+
+    def create_quiz(self, note_id: str, *, num_questions: Optional[Union[int, str]] = None, set_name: Optional[str] = None, difficulty: Optional[str] = None, custom_prompt: Optional[str] = None, community: Optional[bool] = None, endpoint: str = QUIZ_CREATE_ENDPOINT, base_url: Optional[str] = None, headers: Headers = None) -> TaskSubmission:
+        return self._submit_form_task(endpoint, {"note_id": note_id, "num_questions": num_questions, "set_name": set_name, "difficulty": difficulty, "custom_prompt": custom_prompt, "community": community}, base_url, headers)
+
+    def create_shorts(self, note_id: str, voice_id: str, *, clip_duration: Optional[int] = None, is_audio_only: Optional[bool] = None, bg_id: Optional[str] = None, endpoint: str = SHORTS_CREATE_ENDPOINT, base_url: Optional[str] = None, headers: Headers = None) -> TaskSubmission:
+        return self._submit_form_task(endpoint, {"note_id": note_id, "voice_id": voice_id, "clip_duration": clip_duration, "is_audio_only": is_audio_only, "bg_id": bg_id}, base_url, headers)
+
+    def create_quiz_video(self, note_id: str, voice_id: str, *, bg_id: Optional[str] = None, template_id: Optional[str] = None, endpoint: str = QUIZ_VIDEO_CREATE_ENDPOINT, base_url: Optional[str] = None, headers: Headers = None) -> TaskSubmission:
+        return self._submit_form_task(endpoint, {"note_id": note_id, "voice_id": voice_id, "bg_id": bg_id, "template_id": template_id}, base_url, headers)
+
+    def create_slide(self, note_id: str, template_id: str, *, language: Optional[str] = None, slide_count_range: Optional[str] = None, community: Optional[bool] = None, endpoint: str = SLIDE_CREATE_ENDPOINT, base_url: Optional[str] = None, headers: Headers = None) -> TaskSubmission:
+        return self._submit_form_task(endpoint, {"note_id": note_id, "template_id": template_id, "language": language, "slide_count_range": slide_count_range, "community": community}, base_url, headers)
+
+    def create_translation(self, note_id: str, language: str, *, only_summary: Optional[bool] = None, community: Optional[bool] = None, endpoint: str = TRANSLATE_CREATE_ENDPOINT, base_url: Optional[str] = None, headers: Headers = None) -> TaskSubmission:
+        return self._submit_form_task(endpoint, {"note_id": note_id, "language": language, "only_summary": only_summary, "community": community}, base_url, headers)
+
+    def get_task_result(self, task_id: str, *, endpoint: str = TASK_RESULT_ENDPOINT, base_url: Optional[str] = None) -> TaskResult:
+        self._require_text(task_id, "task_id")
+        return TaskResult.from_response(
+            self.request("GET", endpoint.format(task_id=quote(task_id.strip(), safe="")), base_url=base_url)
+        )
+
+    def wait_for_task(self, task_id: str, *, poll_interval: float = 5.0, timeout: float = 120.0, sleep_fn=time.sleep, endpoint: str = TASK_RESULT_ENDPOINT, base_url: Optional[str] = None) -> TaskResult:
+        if poll_interval < 0:
+            raise ValueError("poll_interval cannot be negative")
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than 0")
+        started_at = time.monotonic()
+        while True:
+            result = self.get_task_result(task_id, endpoint=endpoint, base_url=base_url)
+            if result.status == "SUCCESS":
+                return result
+            if result.status == "FAILURE":
+                raise NotexTaskError(result.error or "NoteX task failed", error_key="task_failure", body=self._task_body(result))
+            if time.monotonic() - started_at >= timeout:
+                raise NotexTaskError(f"NoteX task timed out after {timeout:g} seconds", error_key="task_timeout", body=self._task_body(result))
+            sleep_fn(poll_interval)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        body: Optional[Mapping[str, Any]] = None,
+        form: Optional[Mapping[str, Any]] = None,
+        content: Optional[bytes] = None,
+        headers: Headers = None,
+        base_url: Optional[str] = None,
+        retryable: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """Call a NoteX API endpoint with JSON, form, or binary request data."""
+
+        if not self.api_key:
+            raise NotexAuthenticationError("No NoteX API key supplied", status_code=401, error_key="not_authenticated")
+        supplied_bodies = sum(value is not None for value in (body, form, content))
+        if supplied_bodies > 1:
+            raise ValueError("use only one of body, form, or content")
+        base = (base_url or self.base_url).rstrip("/")
+        url = f"{base}/{path.lstrip('/')}"
+        if params:
+            url = f"{url}?{urlencode(self._normalize_values(params), doseq=True)}"
+        request_headers = self._auth_headers(headers)
+        encoded_content: Optional[bytes] = content
+        if body is not None:
+            request_headers.setdefault("Content-Type", "application/json")
+            encoded_content = json.dumps(body).encode("utf-8")
+        elif form is not None:
+            request_headers.setdefault("Content-Type", "application/x-www-form-urlencoded")
+            encoded_content = urlencode(self._normalize_values(form), doseq=True).encode("utf-8")
+        return self._send(
+            url=url,
+            method=method,
+            headers=request_headers,
+            content=encoded_content,
+            retryable=retryable,
+        )
+
+    def _submit_form_task(self, endpoint: str, form: Mapping[str, Any], base_url: Optional[str], headers: Headers) -> TaskSubmission:
+        self._require_text(form.get("note_id"), "note_id")
+        return TaskSubmission.from_response(
+            self.request(
+                "POST",
+                endpoint,
+                form={key: value for key, value in form.items() if value is not None},
+                base_url=base_url,
+                headers=headers,
+            )
+        )
+
+    @staticmethod
+    def _source_body(*, web_url: Optional[str], file_url: Optional[str]) -> Dict[str, Any]:
+        supplied = [value for value in (web_url, file_url) if value and value.strip()]
+        if len(supplied) != 1:
+            raise ValueError("provide exactly one of web_url or file_url")
+        return {"web_url": web_url} if web_url and web_url.strip() else {"file_url": file_url}
+
+    @staticmethod
+    def _require_text(value: Any, name: str) -> None:
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError(f"{name} is required")
+
+    @staticmethod
+    def _normalize_values(values: Mapping[str, Any]) -> Dict[str, Any]:
+        normalized: Dict[str, Any] = {}
+        for key, value in values.items():
+            if isinstance(value, bool):
+                normalized[key] = "true" if value else "false"
+            elif isinstance(value, (list, tuple)):
+                normalized[key] = ["true" if item is True else "false" if item is False else item for item in value]
+            else:
+                normalized[key] = value
+        return normalized
+
+    def _auth_headers(self, extra_headers: Headers) -> Dict[str, str]:
+        headers: Dict[str, str] = _RedactedHeaders({"Accept": "application/json"})
+        if self.auth_header == "Authorization":
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        else:
+            headers["X-API-Key"] = str(self.api_key)
+        if extra_headers:
+            headers.update(extra_headers)
+        return headers
+
+    @staticmethod
+    def _get_header(headers: Mapping[str, str], name: str) -> Optional[str]:
+        target = name.lower()
+        return next((value for key, value in headers.items() if key.lower() == target), None)
+
+    def _send(
+        self,
+        *,
+        url: str,
+        method: str,
+        headers: Mapping[str, str],
+        content: Optional[Union[bytes, BinaryIO]],
+        retryable: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        return self._transport.send(
+            url=url,
+            method=method,
+            headers=headers,
+            content=content,
+            retryable=retryable,
+        )
+
+    @staticmethod
+    def _task_body(result: TaskResult) -> Dict[str, Any]:
+        return {"status": result.status, "data": result.data, "error": result.error}

notex_sdk/config.py

@@ -0,0 +1,25 @@
+"""Centralized NoteX API defaults."""
+
+DEFAULT_BASE_URL = "https://api.notexapp.com"
+
+API_V1 = "/v1"
+API_V2 = "/v2"
+
+CREDITS_ME_ENDPOINT = f"{API_V2}/credits/me"
+CREDITS_QUOTA_ENDPOINT = f"{API_V2}/credits/quota"
+USER_PROFILE_ENDPOINT = f"{API_V1}/user/profile"
+USER_NOTES_ENDPOINT = f"{API_V2}/user/notes"
+TASK_RESULT_ENDPOINT = f"{API_V1}/create/tasks/{{task_id}}/result"
+
+PRESIGNED_URL_ENDPOINT = f"{API_V1}/presigned-url"
+NOTE_CREATE_ENDPOINT = "/v9/create/note"
+NOTE_VALIDATE_ENDPOINT = "/v9/create/validate"
+
+FLASHCARDS_CREATE_ENDPOINT = "/v6/create/flashcards"
+MINDMAP_CREATE_ENDPOINT = f"{API_V2}/create/mindmap"
+PODCAST_CREATE_ENDPOINT = f"{API_V1}/create/podcast"
+QUIZ_CREATE_ENDPOINT = "/v6/create/quiz"
+SHORTS_CREATE_ENDPOINT = f"{API_V2}/create/shorts"
+QUIZ_VIDEO_CREATE_ENDPOINT = f"{API_V2}/create/quiz-video"
+SLIDE_CREATE_ENDPOINT = f"{API_V2}/create/slide"
+TRANSLATE_CREATE_ENDPOINT = f"{API_V2}/create/translate"

notex_sdk/errors.py

@@ -0,0 +1,45 @@
+"""Error types raised by the NoteX SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+class NotexAPIError(Exception):
+    """An error returned by the NoteX API or the transport layer."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        error_key: Optional[str] = None,
+        body: Optional[Mapping[str, Any]] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_key = error_key
+        self.body = dict(body or {})
+        self.retry_after = retry_after
+
+
+class NotexAuthenticationError(NotexAPIError):
+    """The API key is missing, invalid, revoked, or expired."""
+
+
+class NotexPermissionError(NotexAPIError):
+    """The authenticated account cannot perform the requested operation."""
+
+
+class NotexUploadError(NotexAPIError):
+    """A local-file or presigned-upload operation could not be completed."""
+
+
+class NotexRateLimitError(NotexAPIError):
+    """The NoteX API rate limited the request."""
+
+
+class NotexTaskError(NotexAPIError):
+    """An asynchronous NoteX task failed or returned an invalid status."""