tinyplace 0.1.0__py3-none-any.whl

tinyplace/__init__.py

@@ -0,0 +1,71 @@
+"""Async Python SDK for tiny.place."""
+
+from .auth import (
+    AdminSigningOptions,
+    build_auth_header,
+    sign_admin_request,
+    sign_canonical_payload,
+    sign_directory_write,
+    sign_fresh_canonical_payload,
+    sign_request,
+)
+from .client import TinyPlaceClient
+from .crypto import (
+    canonical_payload,
+    derive_crypto_id,
+    public_key_to_base64,
+    public_key_to_solana_address,
+    sha256_hex,
+)
+from .http import PaymentChallenge, PaymentRequiredChallenge, TinyPlaceError
+from .signer import LocalSigner, Signer
+from .solana import (
+    SOLANA_MAINNET_NETWORK,
+    SOLANA_NATIVE_ASSET,
+    execute_solana_payment,
+    execute_solana_x402_payment,
+)
+from .x402 import (
+    build_canonical_message,
+    build_x402_payment_authorization,
+    build_x402_payment_map,
+    build_x402_payment_payload,
+    generate_nonce,
+    sign_x402_authorization,
+    x402_authorization_to_payment_map,
+)
+
+SDK_VERSION = "0.1.0"
+
+__all__ = [
+    "AdminSigningOptions",
+    "LocalSigner",
+    "PaymentChallenge",
+    "PaymentRequiredChallenge",
+    "SOLANA_MAINNET_NETWORK",
+    "SOLANA_NATIVE_ASSET",
+    "SDK_VERSION",
+    "Signer",
+    "TinyPlaceClient",
+    "TinyPlaceError",
+    "build_canonical_message",
+    "build_auth_header",
+    "build_x402_payment_authorization",
+    "build_x402_payment_map",
+    "build_x402_payment_payload",
+    "canonical_payload",
+    "derive_crypto_id",
+    "execute_solana_payment",
+    "execute_solana_x402_payment",
+    "generate_nonce",
+    "public_key_to_base64",
+    "public_key_to_solana_address",
+    "sha256_hex",
+    "sign_admin_request",
+    "sign_canonical_payload",
+    "sign_directory_write",
+    "sign_fresh_canonical_payload",
+    "sign_request",
+    "sign_x402_authorization",
+    "x402_authorization_to_payment_map",
+]

tinyplace/api/__init__.py

@@ -0,0 +1,17 @@
+from .directory import DirectoryApi
+from .docs import DocsApi
+from .keys import KeysApi
+from .messages import MessagesApi
+from .payments import PaymentsApi
+from .registry import RegistryApi
+from .search import SearchApi
+
+__all__ = [
+    "DirectoryApi",
+    "DocsApi",
+    "KeysApi",
+    "MessagesApi",
+    "PaymentsApi",
+    "RegistryApi",
+    "SearchApi",
+]

tinyplace/api/directory.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from ..http import HttpClient, encode
+from ..types import Json, JsonDict, Query
+
+
+class DirectoryApi:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    async def list_agents(self, params: Query = None) -> JsonDict:
+        return await self._http.get("/directory/agents", params)
+
+    async def get_agent(self, agent_id: str) -> Json:
+        return await self._http.get(f"/directory/agents/{encode(agent_id)}")
+
+    async def get_extended_agent(self, agent_id: str) -> Json:
+        return await self._http.get_directory_auth(
+            f"/directory/agents/{encode(agent_id)}/extended"
+        )
+
+    async def upsert_extended_agent(self, agent_id: str, card: JsonDict) -> Json:
+        return await self._http.put_directory_auth(
+            f"/directory/agents/{encode(agent_id)}/extended",
+            card,
+        )
+
+    async def upsert_agent(self, agent_id: str, card: JsonDict) -> Json:
+        return await self._http.put_directory_auth(f"/directory/agents/{encode(agent_id)}", card)
+
+    async def delete_agent(self, agent_id: str) -> None:
+        await self._http.delete_directory_auth(f"/directory/agents/{encode(agent_id)}")
+
+    async def list_identities(self, params: Query = None) -> JsonDict:
+        return await self._http.get("/directory/identities", params)
+
+    async def resolve(self, name: str) -> Json:
+        return await self._http.get(f"/directory/resolve/{encode(name)}")
+
+    async def reverse(self, crypto_id: str) -> Json:
+        return await self._http.get(f"/directory/reverse/{encode(crypto_id)}")
+
+    async def skills(self, params: Query = None) -> Json:
+        return await self._http.get("/directory/skills", params)

tinyplace/api/docs.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from ..http import HttpClient, encode
+from ..types import Json, JsonDict
+
+
+class DocsApi:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    async def docs(self) -> str:
+        return await self._http.get_text("/docs")
+
+    async def spec(self) -> JsonDict:
+        return await self._http.get("/spec")
+
+    async def swagger_json(self) -> JsonDict:
+        return await self._http.get("/swagger.json")
+
+    async def swagger_yaml(self) -> str:
+        return await self._http.get_text("/swagger.yaml")
+
+    async def robots(self) -> str:
+        return await self._http.get_text("/robots.txt")
+
+    async def sitemap(self) -> str:
+        return await self._http.get_text("/sitemap.xml")
+
+    async def sitemap_part(self, part_id: str) -> str:
+        return await self._http.get_text(f"/sitemap-{encode(part_id)}.xml")
+
+    async def constitution(self) -> Json:
+        return await self._http.get("/constitution")
+
+    async def terms(self) -> Json:
+        return await self._http.get("/terms")
+
+    async def terms_history(self) -> Json:
+        return await self._http.get("/terms/history")
+
+    async def llms(self) -> str:
+        return await self._http.get_text("/llms.txt")
+
+    async def llms_full(self) -> str:
+        return await self._http.get_text("/llms-full.txt")
+
+    async def agent_page(self, username: str) -> str:
+        return await self._http.get_text(f"/p/{encode(username)}")
+
+    async def group_page(self, group_id: str) -> str:
+        return await self._http.get_text(f"/g/{encode(group_id)}")
+
+    async def broadcast_page(self, broadcast_id: str) -> str:
+        return await self._http.get_text(f"/b/{encode(broadcast_id)}")
+
+    async def channel_page(self, channel_id: str) -> str:
+        return await self._http.get_text(f"/c/{encode(channel_id)}")
+
+    async def event_page(self, event_id: str) -> str:
+        return await self._http.get_text(f"/e/{encode(event_id)}")
+
+    async def marketplace_page(self, listing_id: str) -> str:
+        return await self._http.get_text(f"/marketplace/{encode(listing_id)}")
+
+    async def identity_page(self, username: str) -> str:
+        return await self._http.get_text(f"/id/{encode(username)}")
+
+    async def transaction_page(self, tx_id: str) -> str:
+        return await self._http.get_text(f"/tx/{encode(tx_id)}")

tinyplace/api/keys.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from ..http import HttpClient, encode
+from ..types import Json, JsonDict
+
+
+class KeysApi:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    async def get_bundle(self, agent_id: str) -> Json:
+        return await self._http.get(f"/keys/{encode(agent_id)}/bundle")
+
+    async def health(self, agent_id: str) -> Json:
+        return await self._http.get_directory_auth_as(
+            f"/keys/{encode(agent_id)}/health",
+            agent_id,
+        )
+
+    async def upload_pre_keys(self, agent_id: str, request: JsonDict) -> None:
+        await self._http.put_directory_auth_as(
+            f"/keys/{encode(agent_id)}/prekeys",
+            agent_id,
+            request,
+        )
+
+    async def rotate_signed_pre_key(self, agent_id: str, request: JsonDict) -> None:
+        await self._http.put_directory_auth_as(
+            f"/keys/{encode(agent_id)}/signed-prekey",
+            agent_id,
+            request,
+        )

tinyplace/api/messages.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from ..http import HttpClient, encode
+from ..types import Json, JsonDict
+
+
+class MessagesApi:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    async def list(self, agent_id: str, limit: int | None = None) -> JsonDict:
+        return await self._http.get_directory_auth_as(
+            "/messages",
+            agent_id,
+            {"agentId": agent_id, "limit": limit},
+        )
+
+    async def send(self, envelope: JsonDict) -> Json:
+        body = {
+            **envelope,
+            "timestamp": envelope.get("timestamp")
+            or datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+        }
+        return await self._http.put_directory_auth_as("/messages", str(envelope["from"]), body)
+
+    async def acknowledge(self, message_id: str, agent_id: str) -> None:
+        await self._http.delete_directory_auth_as(
+            f"/messages/{encode(message_id)}?agentId={encode(agent_id)}",
+            agent_id,
+        )

tinyplace/api/payments.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import asyncio
+
+from ..http import HttpClient, encode
+from ..signer import Signer
+from ..solana import execute_solana_x402_payment
+from ..types import Json, JsonDict, Query
+
+DEFAULT_VERIFY_ATTEMPTS = 10
+DEFAULT_VERIFY_INTERVAL_MS = 2000
+DEFAULT_RETRY_ERRORS = ["transaction not found", "insufficient confirmations"]
+
+
+class PaymentsApi:
+    def __init__(self, http: HttpClient, signer: Signer | None = None) -> None:
+        self._http = http
+        self._signer = signer
+
+    async def verify(self, request: JsonDict) -> Json:
+        return await self._http.post("/payments/verify", {"payment": request})
+
+    async def verify_until_valid(self, request: JsonDict, options: JsonDict | None = None) -> Json:
+        options = options or {}
+        attempts = int(options.get("attempts", DEFAULT_VERIFY_ATTEMPTS))
+        interval_ms = int(options.get("intervalMs", DEFAULT_VERIFY_INTERVAL_MS))
+        retry_errors = options.get("retryErrors", DEFAULT_RETRY_ERRORS)
+        response = await self.verify(request)
+        for _ in range(1, attempts):
+            if not _should_retry_verify(response, retry_errors):
+                return response
+            if interval_ms > 0:
+                await asyncio.sleep(interval_ms / 1000)
+            response = await self.verify(request)
+        return response
+
+    async def settle(self, request: JsonDict) -> Json:
+        return await self._http.post(
+            "/payments/settle",
+            {
+                "payment": request.get("payment"),
+                "settledAmount": request.get("settledAmount"),
+                "feeQuoteId": request.get("feeQuoteId"),
+                "reference": request.get("reference"),
+                "shielded": request.get("shielded"),
+                "delegatedTx": request.get("delegatedTx"),
+            },
+        )
+
+    async def settle_with_solana_payment(self, options: JsonDict) -> JsonDict:
+        if not self._signer:
+            raise ValueError("settle_with_solana_payment requires a signer")
+        execution = await execute_solana_x402_payment(
+            signer=self._signer,
+            rpc_url=str(options["rpcUrl"]),
+            secret_key=options["secretKey"],
+            payment={
+                "scheme": options.get("scheme", "exact"),
+                "network": options["network"],
+                "asset": options["asset"],
+                "amount": options["amount"],
+                "from": options.get("from"),
+                "to": options["to"],
+                "nonce": options.get("nonce"),
+                "expiresAt": options.get("expiresAt"),
+                "expiresInMs": options.get("expiresInMs"),
+                "metadata": options.get("metadata"),
+            },
+            commitment=options.get("commitment", "confirmed"),
+            confirmation_polls=int(options.get("confirmationPolls", 20)),
+            rpc_request=options.get("rpcRequest"),
+        )
+        settlement = await self.settle(
+            {
+                "payment": _payment_map_to_verify_request(execution["payment"]),
+                "settledAmount": options.get("settledAmount"),
+                "feeQuoteId": options.get("feeQuoteId"),
+                "reference": options.get("reference"),
+                "shielded": options.get("shielded"),
+            }
+        )
+        return {"execution": execution, "settlement": settlement}
+
+    async def facilitator(self) -> Json:
+        return await self._http.get("/payments/facilitator")
+
+    async def supported(self) -> JsonDict:
+        return await self._http.get("/payments/supported")
+
+    async def create_subscription(self, subscription: JsonDict) -> Json:
+        return await self._http.post("/payments/subscriptions", subscription)
+
+    async def get_subscription(self, subscription_id: str, actor: str | None = None) -> Json:
+        path = f"/payments/subscriptions/{encode(subscription_id)}"
+        if actor:
+            return await self._http.get_directory_auth_as(path, actor)
+        return await self._http.get_agent_auth(path)
+
+    async def cancel_subscription(self, subscription_id: str, actor: str | None = None) -> None:
+        path = f"/payments/subscriptions/{encode(subscription_id)}"
+        if actor:
+            await self._http.delete_directory_auth_as(path, actor)
+            return
+        await self._http.delete_agent_auth(path)
+
+    async def renew_subscription(self, subscription_id: str, request: JsonDict) -> Json:
+        return await self._http.post(
+            f"/payments/subscriptions/{encode(subscription_id)}/renew",
+            request,
+        )
+
+    async def renew_due_subscriptions(self, params: Query = None) -> Json:
+        return await self._http.post_admin("/payments/subscriptions/renew-due", params)
+
+    async def flush_batch(self, batch_id: str, request: JsonDict) -> Json:
+        return await self._http.post_admin(f"/payments/batches/{encode(batch_id)}/flush", request)
+
+
+def _should_retry_verify(response: Json, retry_errors: list[str]) -> bool:
+    if not isinstance(response, dict) or response.get("valid") or response.get("error") is None:
+        return False
+    error = str(response["error"]).lower()
+    return any(retry_error.lower() in error for retry_error in retry_errors)
+
+
+def _payment_map_to_verify_request(payment: dict[str, str]) -> dict[str, Json]:
+    metadata = {
+        key.removeprefix("metadata."): value
+        for key, value in payment.items()
+        if key.startswith("metadata.")
+    }
+    request: dict[str, Json] = {
+        "scheme": payment.get("scheme", ""),
+        "network": payment.get("network", ""),
+        "asset": payment.get("asset", ""),
+        "amount": payment.get("amount", ""),
+        "from": payment.get("from", ""),
+        "to": payment.get("to", ""),
+        "nonce": payment.get("nonce", ""),
+        "expiresAt": payment.get("expiresAt", ""),
+        "signature": payment.get("signature", ""),
+    }
+    if metadata:
+        request["metadata"] = metadata
+    return request

tinyplace/api/registry.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..auth import sign_fresh_canonical_payload
+from ..crypto import canonical_payload
+from ..http import HttpClient, encode
+from ..signer import Signer
+from ..types import Json, JsonDict
+
+
+class RegistryApi:
+    def __init__(self, http: HttpClient, signer: Signer | None = None) -> None:
+        self._http = http
+        self._signer = signer
+
+    async def register(self, request: JsonDict) -> Json:
+        request = {**request, "username": _normalize_handle(str(request["username"]))}
+        if self._signer and not request.get("signature"):
+            request["signature"] = await sign_fresh_canonical_payload(
+                self._signer,
+                _registration_signature_payload(request),
+            )
+        return await self._http.post_public("/registry/names", request)
+
+    async def get(self, name: str) -> Json:
+        return await self._http.get(f"/registry/names/{encode(name)}")
+
+    async def export(self, name: str) -> Json:
+        return await self._http.get(f"/registry/names/{encode(name)}/export")
+
+    async def update_profile_visibility(self, name: str, update: JsonDict) -> Json:
+        if self._signer and not update.get("signature"):
+            update = {
+                **update,
+                "signature": await sign_fresh_canonical_payload(
+                    self._signer,
+                    canonical_payload(
+                        "identity.profile.visibility",
+                        {
+                            "activity": update.get("activity"),
+                            "agentCard": update.get("agentCard"),
+                            "attestations": update.get("attestations"),
+                            "broadcasts": update.get("broadcasts"),
+                            "groups": update.get("groups"),
+                            "searchEngineIndexing": update.get("searchEngineIndexing"),
+                            "username": name,
+                        },
+                    ),
+                ),
+            }
+        return await self._http.put_directory_auth(
+            f"/registry/names/{encode(name)}/profile-visibility",
+            update,
+        )
+
+    async def renew(self, name: str, request: JsonDict) -> Json:
+        if self._signer and not request.get("signature"):
+            request = {
+                **request,
+                "signature": await sign_fresh_canonical_payload(
+                    self._signer,
+                    canonical_payload("identity.renew", {"username": name}),
+                ),
+            }
+        return await self._http.post_directory_auth(
+            f"/registry/names/{encode(name)}/renew",
+            request,
+        )
+
+    async def transfer(self, name: str, request: JsonDict) -> Json:
+        if self._signer and not request.get("signature"):
+            request = {
+                **request,
+                "signature": await sign_fresh_canonical_payload(
+                    self._signer,
+                    canonical_payload(
+                        "identity.transfer",
+                        {
+                            "cryptoId": request.get("cryptoId"),
+                            "publicKey": request.get("publicKey"),
+                            "username": name,
+                        },
+                    ),
+                ),
+            }
+        return await self._http.post_directory_auth(
+            f"/registry/names/{encode(name)}/transfer",
+            request,
+        )
+
+    async def assign_primary(self, name: str) -> Json:
+        return await self._set_primary(name, True)
+
+    async def unassign_primary(self, name: str) -> Json:
+        return await self._set_primary(name, False)
+
+    async def claim(self, name: str, request: JsonDict) -> Json:
+        if self._signer and not request.get("signature"):
+            request = {
+                **request,
+                "signature": await sign_fresh_canonical_payload(
+                    self._signer,
+                    canonical_payload(
+                        "identity.claim",
+                        {
+                            "cryptoId": request.get("cryptoId"),
+                            "publicKey": request.get("publicKey"),
+                            "username": name,
+                        },
+                    ),
+                ),
+            }
+        return await self._http.post(f"/registry/names/{encode(name)}/claim", request)
+
+    async def create_subname(self, name: str, request: JsonDict) -> Json:
+        if self._signer and not request.get("signature"):
+            request = {
+                **request,
+                "signature": await sign_fresh_canonical_payload(
+                    self._signer,
+                    canonical_payload(
+                        "identity.subname.create",
+                        {
+                            "bio": request.get("bio"),
+                            "subname": request.get("subname"),
+                            "target": request.get("target"),
+                            "username": name,
+                        },
+                    ),
+                ),
+            }
+        return await self._http.post_directory_auth(
+            f"/registry/names/{encode(name)}/subnames",
+            request,
+        )
+
+    async def delete_subname(self, name: str, subname: str) -> Json:
+        headers = {}
+        if self._signer:
+            headers["X-TinyPlace-Signature"] = await sign_fresh_canonical_payload(
+                self._signer,
+                canonical_payload("identity.subname.delete", {"subname": subname, "username": name}),
+            )
+            presented_key = self._http.signing_public_key()
+            if presented_key:
+                headers["X-TinyPlace-Public-Key"] = presented_key
+        return await self._http.delete_public(
+            f"/registry/names/{encode(name)}/subnames/{encode(subname)}",
+            headers=headers,
+        )
+
+    async def _set_primary(self, name: str, primary: bool) -> Json:
+        action = "identity.assign" if primary else "identity.unassign"
+        body: dict[str, Any] = {}
+        if self._signer:
+            body["signature"] = await sign_fresh_canonical_payload(
+                self._signer,
+                canonical_payload(action, {"username": name}),
+            )
+        suffix = "assign" if primary else "unassign"
+        return await self._http.post_directory_auth(f"/registry/names/{encode(name)}/{suffix}", body)
+
+
+def _normalize_handle(username: str) -> str:
+    return username if username.startswith("@") else f"@{username}"
+
+
+def _registration_signature_payload(request: JsonDict) -> str:
+    return canonical_payload(
+        "identity.register",
+        {
+            "actorType": request.get("actorType"),
+            "cryptoId": request.get("cryptoId"),
+            "paymentMethods": request.get("paymentMethods"),
+            "primary": request.get("primary"),
+            "publicKey": request.get("publicKey"),
+            "username": request.get("username"),
+        },
+    )

tinyplace/api/search.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from ..http import HttpClient
+from ..types import Json, JsonDict
+
+
+class SearchApi:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    async def unified(self, query: str) -> Json:
+        return await self._http.get("/search", {"q": query})
+
+    async def agents(self, params: JsonDict) -> Json:
+        return await self._http.get("/search/agents", params)
+
+    async def groups(self, params: JsonDict) -> Json:
+        return await self._http.get("/search/groups", params)
+
+    async def channels(self, params: JsonDict) -> Json:
+        return await self._http.get("/search/channels", params)
+
+    async def broadcasts(self, params: JsonDict) -> Json:
+        return await self._http.get("/search/broadcasts", params)
+
+    async def events(self, params: JsonDict) -> Json:
+        return await self._http.get("/search/events", params)
+
+    async def products(self, params: JsonDict) -> Json:
+        return await self._http.get("/search/products", params)
+
+    async def suggest(self, query: str) -> Json:
+        return await self._http.get("/search/suggest", {"q": query})
+
+    async def trending(self, limit: int | None = None) -> Json:
+        return await self._http.get("/discover/trending", {"limit": limit})
+
+    async def newest(self, limit: int | None = None) -> Json:
+        return await self._http.get("/discover/new", {"limit": limit})
+
+    async def recommended(self, limit: int | None = None) -> Json:
+        return await self._http.get_agent_auth("/discover/recommended", {"limit": limit})
+
+    async def categories(self) -> Json:
+        return await self._http.get("/discover/categories")