datadid-sdk-python 1.0.0__py3-none-any.whl

src/did/client.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from ..errors import DataDIDApiError
+from .types import (
+    CreateDIDResponse,
+    DeleteDIDResponse,
+    DIDChainInfo,
+    DIDClientOptions,
+    DIDInfoResponse,
+    SigMsgResponse,
+)
+
+_PRODUCTION_URL = "https://prodidapi.memolabs.org"
+_TESTNET_URL = "https://testdidapi.memolabs.org"
+
+
+class DIDClient:
+    """
+    Async REST client for the DataDID DID API (prodidapi).
+
+    Wraps DID creation/deletion and file operations.
+    DID operations use a sign-then-submit pattern:
+      1. Call get_create_message() to get a message string
+      2. Sign that message with your wallet (off-chain, free)
+      3. Call create_did() with the signature — the server pays gas
+    """
+
+    def __init__(self, options: DIDClientOptions) -> None:
+        self._base_url: str = options.base_url.rstrip("/")
+
+    @classmethod
+    def production(cls) -> DIDClient:
+        """Create a client pointing to production (https://prodidapi.memolabs.org)."""
+        return cls(DIDClientOptions(base_url=_PRODUCTION_URL))
+
+    @classmethod
+    def testnet(cls) -> DIDClient:
+        """Create a client pointing to testnet (https://testdidapi.memolabs.org)."""
+        return cls(DIDClientOptions(base_url=_TESTNET_URL))
+
+    # ── DID endpoints ────────────────────────────────────────────
+
+    async def get_create_message(self, address: str) -> str:
+        """
+        Get the message you need to sign before creating a DID.
+        Sign the returned msg with your wallet, then pass the signature to create_did().
+
+        GET /did/createsigmsg
+        """
+        data = await self._request("GET", f"/did/createsigmsg?address={address}")
+        return data.get("msg", "") if isinstance(data, dict) else str(data)
+
+    async def create_did(self, sig: str, address: str) -> str:
+        """
+        Create a new DID. Call get_create_message() first to get the message to sign.
+
+        POST /did/create
+        """
+        data = await self._request("POST", "/did/create", {"sig": sig, "address": address})
+        return data.get("did", "") if isinstance(data, dict) else str(data)
+
+    async def create_did_admin(self, address: str) -> str:
+        """
+        Admin-only: create a DID for an address without requiring a signature.
+
+        POST /did/createadmin
+        """
+        data = await self._request("POST", "/did/createadmin", {"address": address})
+        return data.get("did", "") if isinstance(data, dict) else str(data)
+
+    async def create_ton_did(self, address: str) -> str:
+        """
+        Create a Ton-network DID for an address.
+
+        POST /did/createton
+        """
+        data = await self._request("POST", "/did/createton", {"address": address})
+        return data.get("did", "") if isinstance(data, dict) else str(data)
+
+    async def get_did_exists(self, address: str) -> Any:
+        """
+        Check whether a DID exists for the given address.
+
+        GET /did/exist
+        """
+        return await self._request("GET", f"/did/exist?address={address}")
+
+    async def get_did_info(self, address: str) -> DIDInfoResponse:
+        """
+        Get DID info (DID string + per-chain balance/address details).
+
+        GET /did/info
+        """
+        data = await self._request("GET", f"/did/info?address={address}")
+        chain_list = [
+            DIDChainInfo(
+                address=item.get("address", ""),
+                balance=item.get("balance", ""),
+                chain=item.get("chain", ""),
+            )
+            for item in (data.get("info") or [])
+        ]
+        return DIDInfoResponse(did=data.get("did", ""), info=chain_list)
+
+    async def get_delete_message(self, did: str) -> str:
+        """
+        Get the message you need to sign before deleting a DID.
+        Sign the returned msg with your wallet, then pass the signature to delete_did().
+
+        GET /did/deletesigmsg
+        """
+        data = await self._request("GET", f"/did/deletesigmsg?did={did}")
+        return data.get("msg", "") if isinstance(data, dict) else str(data)
+
+    async def delete_did(self, sig: str, did: str) -> DeleteDIDResponse:
+        """
+        Delete a DID. Call get_delete_message() first to get the message to sign.
+
+        POST /did/delete
+        """
+        data = await self._request("POST", "/did/delete", {"sig": sig, "did": did})
+        return DeleteDIDResponse(
+            did=data.get("did", ""),
+            status=data.get("status", ""),
+        )
+
+    # ── File endpoints ───────────────────────────────────────────
+
+    async def upload_file(self, data: str, address: str) -> None:
+        """
+        Upload a file.
+
+        POST /file/upload
+        """
+        await self._request("POST", "/file/upload", {"data": data, "address": address})
+
+    async def list_files(self, address: str) -> Any:
+        """
+        List files for an address.
+
+        GET /file/list
+        """
+        return await self._request("GET", f"/file/list?address={address}")
+
+    async def download_file(self, address: str) -> Any:
+        """
+        Download a file for an address.
+
+        GET /file/download
+        """
+        return await self._request("GET", f"/file/download?address={address}")
+
+    # ── MFile endpoints ──────────────────────────────────────────
+
+    async def create_mfile_upload(self, data: str, address: str) -> str:
+        """
+        Start an mfile upload — returns a message to sign.
+        Pass the signature to confirm_mfile_upload() to complete the upload.
+
+        POST /mfile/upload/create
+        """
+        result = await self._request(
+            "POST", "/mfile/upload/create", {"data": data, "address": address}
+        )
+        return str(result)
+
+    async def confirm_mfile_upload(self, sig: str, address: str) -> str:
+        """
+        Confirm an mfile upload with your signature.
+
+        POST /mfile/upload/confirm
+        """
+        result = await self._request(
+            "POST", "/mfile/upload/confirm", {"sig": sig, "address": address}
+        )
+        return str(result)
+
+    async def download_mfile(self, mdid: str, address: str) -> Any:
+        """
+        Download a file by its mfile DID.
+
+        GET /mfile/download
+        """
+        return await self._request("GET", f"/mfile/download?mdid={mdid}&address={address}")
+
+    # ── Internal helpers ─────────────────────────────────────────
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        headers: dict[str, str] = {}
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+
+        async with httpx.AsyncClient() as http:
+            response = await http.request(method, url, headers=headers, json=body)
+
+        try:
+            json_body = response.json()
+        except Exception:
+            if not response.is_success:
+                raise DataDIDApiError(
+                    f"HTTP {response.status_code} {response.reason_phrase}",
+                    response.status_code,
+                )
+            return None
+
+        if not response.is_success:
+            raise DataDIDApiError(
+                json_body.get("message")
+                or json_body.get("error")
+                or f"HTTP {response.status_code}",
+                response.status_code,
+                json_body,
+            )
+
+        return json_body

src/did/types.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass, field
+from typing import List
+
+
+@dataclass
+class DIDClientOptions:
+    """Options for creating a DIDClient."""
+
+    base_url: str
+    """Base URL of the DID API server."""
+
+
+@dataclass
+class SigMsgResponse:
+    """Response from GET /did/createsigmsg and GET /did/deletesigmsg."""
+
+    msg: str
+
+
+@dataclass
+class CreateDIDResponse:
+    """Response from POST /did/create, POST /did/createadmin, POST /did/createton."""
+
+    did: str
+
+
+@dataclass
+class DeleteDIDResponse:
+    """Response from POST /did/delete."""
+
+    did: str
+    status: str
+
+
+@dataclass
+class DIDChainInfo:
+    """Chain-specific info within a DID info response."""
+
+    address: str
+    balance: str
+    chain: str
+
+
+@dataclass
+class DIDInfoResponse:
+    """Response from GET /did/info."""
+
+    did: str
+    info: List[DIDChainInfo] = field(default_factory=list)

src/errors.py

@@ -0,0 +1,15 @@
+from typing import Any
+
+
+class DataDIDApiError(Exception):
+    """Error raised when a DataDID API call fails."""
+
+    def __init__(self, message: str, status_code: int, response_body: Any = None) -> None:
+        super().__init__(message)
+        self.status_code: int = status_code
+        """HTTP status code (e.g. 401, 500)."""
+        self.response_body: Any = response_body
+        """Raw response body from the server."""
+
+    def __repr__(self) -> str:
+        return f"DataDIDApiError(message={str(self)!r}, status_code={self.status_code!r})"