mosir-sdk-python 0.1.1__py3-none-any.whl

mosir_sdk/client.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Awaitable, Mapping
+from typing import Any, Literal, TypeAlias, cast
+
+import httpx
+from graphql import OperationDefinitionNode, OperationType, get_operation_ast, parse
+from httpx_sse import aconnect_sse
+
+from ._operations import OPERATION_REGISTRY, OperationSpec
+from .exceptions import GraphQLRequestError, GraphQLTransportError
+
+DEFAULT_ENDPOINT = "https://beta.mosir.app/api/v1"
+JSONMapping: TypeAlias = dict[str, Any]
+PreviewImageKind: TypeAlias = Literal["post", "profile", "post_collection"]
+
+MEDIA_PROFILE_FALLBACK_ORDER = [
+    "QUALITY",
+    "COMPATIBLE",
+    "THUMBNAIL",
+    "ANIMATED_COMPATIBLE",
+    "ANIMATED_THUMBNAIL",
+]
+
+PREVIEW_IMAGE_ROUTE_MAP: dict[PreviewImageKind, str] = {
+    "post": "postopengraph",
+    "profile": "profileopengraph",
+    "post_collection": "collectionopengraph",
+}
+
+
+class AsyncMosirClient:
+    """Async client for the Mosir public GraphQL API.
+
+    Wrapped snake_case methods are resolved dynamically from `public.operations.graphql`.
+    For example: `get_post(...)`, `get_notifications(...)`, `post_updated(...)`.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: str | None = None,
+        endpoint: str = DEFAULT_ENDPOINT,
+        headers: Mapping[str, str] | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.token = token
+        self.endpoint = endpoint
+        self._default_headers = dict(headers or {})
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+
+    async def __aenter__(self) -> AsyncMosirClient:
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
+        await self.aclose()
+
+    def __getattr__(self, name: str) -> Any:
+        spec = OPERATION_REGISTRY.get(name)
+        if spec is None:
+            raise AttributeError(f"{type(self).__name__!s} has no attribute {name!r}")
+
+        if spec.operation_type == "subscription":
+            def subscription_method(**variables: Any) -> AsyncIterator[JSONMapping]:
+                return self.subscribe_operation(name, **variables)
+
+            return subscription_method
+
+        async def operation_method(**variables: Any) -> JSONMapping:
+            return await self.operation(name, **variables)
+
+        return operation_method
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    def select_media_file(
+        self,
+        media: Mapping[str, Any],
+        *,
+        profile: str | None = None,
+    ) -> JSONMapping | None:
+        return select_media_file(media, profile=profile)
+
+    async def fetch_media(
+        self,
+        media: Mapping[str, Any],
+        *,
+        profile: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> bytes:
+        file = select_media_file(media, profile=profile)
+        if file is None:
+            raise ValueError("No media file is available for the requested media object.")
+
+        response = await self._client.get(file["url"], headers=self._build_headers(headers))
+        response.raise_for_status()
+        return response.content
+
+    def get_preview_image_url(self, kind: PreviewImageKind, resource_id: str) -> str:
+        return get_preview_image_url(kind, resource_id, endpoint=self.endpoint)
+
+    async def fetch_preview_image(
+        self,
+        kind: PreviewImageKind,
+        resource_id: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+    ) -> bytes:
+        response = await self._client.get(
+            get_preview_image_url(kind, resource_id, endpoint=self.endpoint),
+            headers=self._build_headers(headers),
+        )
+        response.raise_for_status()
+        return response.content
+
+    async def request(
+        self,
+        document: str,
+        variables: Mapping[str, Any] | None = None,
+        *,
+        operation_name: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> JSONMapping:
+        operation = _get_operation(document, operation_name)
+        if operation.operation is OperationType.SUBSCRIPTION:
+            raise ValueError("Use subscribe(...) for subscription operations.")
+
+        response = await self._client.post(
+            self.endpoint,
+            json=_build_payload(document, variables, operation_name),
+            headers=self._build_headers(headers),
+        )
+        return _parse_json_response(response)
+
+    def execute(
+        self,
+        document: str,
+        variables: Mapping[str, Any] | None = None,
+        *,
+        operation_name: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Awaitable[JSONMapping] | AsyncIterator[JSONMapping]:
+        operation = _get_operation(document, operation_name)
+        if operation.operation is OperationType.SUBSCRIPTION:
+            return self.subscribe(
+                document,
+                variables,
+                operation_name=operation_name,
+                headers=headers,
+            )
+        return self.request(
+            document,
+            variables,
+            operation_name=operation_name,
+            headers=headers,
+        )
+
+    async def operation(self, name: str, /, **variables: Any) -> JSONMapping:
+        spec = _get_operation_spec(name)
+        if spec.operation_type == "subscription":
+            raise ValueError(f"Operation {name!r} is a subscription. Use subscribe_operation(...).")
+
+        return await self.request(
+            spec.document,
+            _normalize_variables(variables, spec.variable_map) or None,
+            operation_name=spec.operation_name,
+        )
+
+    def subscribe_operation(self, name: str, /, **variables: Any) -> AsyncIterator[JSONMapping]:
+        spec = _get_operation_spec(name)
+        if spec.operation_type != "subscription":
+            raise ValueError(f"Operation {name!r} is not a subscription. Use operation(...).")
+
+        return self.subscribe(
+            spec.document,
+            _normalize_variables(variables, spec.variable_map) or None,
+            operation_name=spec.operation_name,
+        )
+
+    def subscribe(
+        self,
+        document: str,
+        variables: Mapping[str, Any] | None = None,
+        *,
+        operation_name: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> AsyncIterator[JSONMapping]:
+        operation = _get_operation(document, operation_name)
+        if operation.operation is not OperationType.SUBSCRIPTION:
+            raise ValueError("Use request(...) for query and mutation operations.")
+
+        async def iterator() -> AsyncIterator[JSONMapping]:
+            async with aconnect_sse(
+                self._client,
+                "POST",
+                self.endpoint,
+                json=_build_payload(document, variables, operation_name),
+                headers=self._build_headers(headers),
+            ) as event_source:
+                async for event in event_source.aiter_sse():
+                    if event.event == "complete":
+                        break
+                    if not event.data:
+                        continue
+
+                    payload = json.loads(event.data)
+                    errors = payload.get("errors")
+                    if errors:
+                        raise GraphQLRequestError(errors)
+
+                    data = payload.get("data")
+                    if data is not None:
+                        if not isinstance(data, dict):
+                            raise GraphQLTransportError("Expected a GraphQL data object in the SSE payload.")
+                        yield cast(JSONMapping, data)
+
+        return iterator()
+
+    def _build_headers(self, headers: Mapping[str, str] | None = None) -> dict[str, str]:
+        merged = dict(self._default_headers)
+        if self.token:
+            merged["Authorization"] = f"Bearer {self.token}"
+        if headers:
+            merged.update(headers)
+        return merged
+
+
+def select_media_file(
+    media: Mapping[str, Any],
+    *,
+    profile: str | None = None,
+) -> JSONMapping | None:
+    raw_files = media.get("files")
+    if not isinstance(raw_files, list):
+        return None
+
+    files: list[JSONMapping] = [file for file in raw_files if isinstance(file, dict)]
+    if profile is not None:
+        return next((file for file in files if file.get("profile") == profile), None)
+
+    for candidate_profile in MEDIA_PROFILE_FALLBACK_ORDER:
+        candidate = next((file for file in files if file.get("profile") == candidate_profile), None)
+        if candidate is not None:
+            return candidate
+
+    return files[0] if files else None
+
+
+def get_preview_image_url(
+    kind: PreviewImageKind,
+    resource_id: str,
+    *,
+    endpoint: str = DEFAULT_ENDPOINT,
+) -> str:
+    base_url = httpx.URL(endpoint)
+    return str(base_url.copy_with(path=f"/ogi/{PREVIEW_IMAGE_ROUTE_MAP[kind]}/{resource_id}", query=None))
+
+
+def _get_operation_spec(name: str) -> OperationSpec:
+    spec = OPERATION_REGISTRY.get(name)
+    if spec is None:
+        raise KeyError(f"Unknown Mosir operation: {name}")
+    return spec
+
+
+def _normalize_variables(variables: Mapping[str, Any], variable_map: Mapping[str, str]) -> dict[str, Any]:
+    normalized: dict[str, Any] = {}
+    for key, value in variables.items():
+        normalized[variable_map.get(key, key)] = value
+    return normalized
+
+
+def _build_payload(
+    document: str,
+    variables: Mapping[str, Any] | None,
+    operation_name: str | None,
+) -> JSONMapping:
+    payload: JSONMapping = {"query": document}
+    if variables is not None:
+        payload["variables"] = dict(variables)
+    if operation_name is not None:
+        payload["operationName"] = operation_name
+    return payload
+
+
+def _get_operation(document: str, operation_name: str | None) -> OperationDefinitionNode:
+    operation = get_operation_ast(parse(document), operation_name)
+    if operation is None:
+        raise ValueError(
+            "Unable to resolve GraphQL operation. Provide a single operation document or pass operation_name.",
+        )
+    return operation
+
+
+def _parse_json_response(response: httpx.Response) -> JSONMapping:
+    try:
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        raise GraphQLTransportError(str(exc)) from exc
+
+    payload = response.json()
+    if not isinstance(payload, dict):
+        raise GraphQLTransportError("Expected a JSON object response from the Mosir API.")
+
+    errors = payload.get("errors")
+    if isinstance(errors, list) and errors:
+        raise GraphQLRequestError(errors)
+
+    data = payload.get("data")
+    if not isinstance(data, dict):
+        raise GraphQLTransportError("Expected a GraphQL data object in the response.")
+
+    return cast(JSONMapping, data)

mosir_sdk/exceptions.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class MosirSdkError(Exception):
+    """Base exception for mosir-sdk-python."""
+
+
+class GraphQLRequestError(MosirSdkError):
+    """Raised when the Mosir API returns GraphQL errors."""
+
+    def __init__(self, errors: list[dict[str, Any]]) -> None:
+        self.errors = errors
+        message = "\n".join(str(error.get("message", error)) for error in errors)
+        super().__init__(message)
+
+
+class GraphQLTransportError(MosirSdkError):
+    """Raised when the Mosir API returns a non-GraphQL transport failure."""

mosir_sdk/py.typed

@@ -0,0 +1 @@
+# PEP 561 typing marker - this package provides inline type information

mosir_sdk_python-0.1.1.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: mosir-sdk-python
+Version: 0.1.1
+Summary: Python SDK for the Mosir public GraphQL API
+Author-email: catLee <leemiyinghao@gmx.com>
+License-Expression: LGPL-3.0-or-later
+Project-URL: Homepage, https://beta.mosir.app
+Project-URL: Repository, https://github.com/mosir-social/mosir-sdk-python
+Project-URL: Issues, https://github.com/mosir-social/mosir-sdk-python/issues
+Project-URL: Documentation, https://github.com/mosir-social/mosir-sdk-python#readme
+Keywords: graphql,httpx,mosir,sdk,sse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: graphql-core>=3.2.8
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: httpx-sse>=0.4.3
+Requires-Dist: pydantic>=2.13.4
+Dynamic: license-file
+
+# mosir-sdk-python
+
+Python SDK for the Mosir public GraphQL API.
+
+## Install
+
+For package users:
+
+```bash
+pip install mosir-sdk-python
+```
+
+or:
+
+```bash
+uv add mosir-sdk-python
+```
+
+For local development in this repository:
+
+```bash
+uv sync
+```
+
+## Quick example
+
+### Anonymous/public request
+
+Only public data needs no token.
+
+```python
+import asyncio
+
+from mosir_sdk import AsyncMosirClient
+
+
+async def main() -> None:
+    async with AsyncMosirClient() as client:
+        post = await client.get_post(post_id="VLO8u7UXqclQ7byjfMEX0")
+        print(post["getPost"]["content"])
+
+
+asyncio.run(main())
+```
+
+### Authenticated request
+
+Use a token for authenticated operations such as notifications.
+
+```python
+import asyncio
+import os
+
+from mosir_sdk import AsyncMosirClient
+
+
+async def main() -> None:
+    async with AsyncMosirClient(token=os.getenv("MOSIR_API_TOKEN")) as client:
+        notifications = await client.get_notifications(limit=20)
+        print(notifications["getNotifications"])
+
+
+asyncio.run(main())
+```
+
+## More examples
+
+### Fetch media bytes from a `Media` result
+
+```python
+import asyncio
+
+from mosir_sdk import AsyncMosirClient
+
+
+async def main() -> None:
+    async with AsyncMosirClient() as client:
+        post = await client.get_post(post_id="VLO8u7UXqclQ7byjfMEX0")
+        media = post["getPost"]["attachments"][0]["media"]
+        media_bytes = await client.fetch_media(media)
+        print(len(media_bytes))
+
+
+asyncio.run(main())
+```
+
+### Fetch preview image for a post, profile, or collection
+
+```python
+import asyncio
+
+from mosir_sdk import AsyncMosirClient
+
+
+async def main() -> None:
+    async with AsyncMosirClient() as client:
+        print(client.get_preview_image_url("post", "VLO8u7UXqclQ7byjfMEX0"))
+        preview_bytes = await client.fetch_preview_image("post", "VLO8u7UXqclQ7byjfMEX0")
+        print(len(preview_bytes))
+
+
+asyncio.run(main())
+```
+
+### SSE subscription example
+
+Subscriptions let your app receive updates from Mosir in near real time without polling.
+This SDK uses **SSE** (Server-Sent Events) for subscriptions.
+
+A good example is a Discord bot:
+- subscribe to `post_created_by_author(...)`
+- when a creator publishes something new, turn it into a message
+- send that message into a Discord channel
+
+That way the bot reacts immediately instead of polling the API on a timer.
+SSE works especially well for long-running workers, bots, and notification bridges that only need a one-way event stream from the server.
+For public subscriptions like `post_created_by_author(...)`, a token is not required.
+
+Note: each SSE connection lasts at most 1 hour. In practice, network conditions may cause it to end earlier.
+If you build a bot, worker, or relay process, make sure you implement reconnect logic.
+
+```python
+import asyncio
+
+from mosir_sdk import AsyncMosirClient
+
+
+async def main() -> None:
+    async with AsyncMosirClient() as client:
+        profile = await client.get_account_profile(username="leemiyinghao")
+        author_id = profile["getAccountProfile"]["id"]
+
+        async for event in client.post_created_by_author(
+            author_id=author_id,
+            post_type="POST",
+        ):
+            print(event["postCreatedByAuthor"]["id"])
+            print(event["postCreatedByAuthor"]["content"])
+            break
+
+
+asyncio.run(main())
+```
+
+## Notes
+
+- default endpoint: `https://beta.mosir.app/api/v1`
+- `token` is optional for public data and required only for authenticated operations
+- the same applies to subscriptions: public subscription data does not require a token
+- snake_case methods are resolved dynamically from the operation registry, for example:
+  - `get_post(...)`
+  - `get_notifications(...)`
+  - `post_created_by_author(...)`
+- media helpers are available through:
+  - `select_media_file(...)`
+  - `await client.fetch_media(...)`
+- preview image helpers are available through:
+  - `get_preview_image_url(...)`
+  - `await client.fetch_preview_image(...)`
+- explicit operation access is also available:
+  - `await client.operation("get_post", post_id="...")`
+  - `client.subscribe_operation("post_created_by_author", author_id="...", post_type="POST")`
+    - you can resolve `author_id` first with `get_account_profile(username="...")`
+- raw GraphQL is still available through:
+  - `await client.request(...)`
+  - `client.subscribe(...)`
+
+## Release / publish prep
+
+Build and validate distributions before uploading to PyPI:
+
+```bash
+task build
+task package-check
+```
+
+Typical upload flow:
+
+```bash
+uvx twine upload dist/*
+```
+
+## Tasks
+
+```bash
+task install
+task codegen
+task pyright
+task test
+task build
+task package-check
+task smoke
+```

mosir_sdk_python-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+mosir_sdk/__init__.py,sha256=zAHqq4ZfG9OqxjqNKc7nSkeEVvAJXy4miiAOv6N6a0w,546
+mosir_sdk/_operations.py,sha256=k4-BNV_qMkaJ-dS4F6RkvEbU9XUbieUIlccOxVMrutk,76276
+mosir_sdk/client.py,sha256=y4j64VS1feg1XKzEqG0lafwlt0YlkfpvS9lCCwFRBwg,10908
+mosir_sdk/exceptions.py,sha256=mDZuuaZBFeusqy5Y830apnRu8qrzN4DXY40aUmnJgbc,575
+mosir_sdk/py.typed,sha256=8XG5_343HVYG5_KTfJYlLN8t_rutGmYhYSWg4qouK9c,71
+mosir_sdk_python-0.1.1.dist-info/licenses/LICENSE,sha256=MP2OqI_9a49LYoeAOA4qxz2fPZ7GQdE79HJI-G1kQ_k,42334
+mosir_sdk_python-0.1.1.dist-info/METADATA,sha256=8NofNhCAMDi0sr58a9wX3ZRi9PKZECpK57pqcBq1Vok,5685
+mosir_sdk_python-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mosir_sdk_python-0.1.1.dist-info/top_level.txt,sha256=8q5l5z4w40BiueoupsZf55CU3O2Pcq8mRBRDYIu38AU,10
+mosir_sdk_python-0.1.1.dist-info/RECORD,,

mosir_sdk_python-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+