tinyplace 0.1.0__tar.gz

tinyplace-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+.next
+*.local
+*.tsbuildinfo
+
+# Claude Code (local agent settings, notes, and personal overrides)
+.claude/
+CLAUDE.local.md
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+!.vscode/launch.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+/test-results/
+/playwright-report/
+/playwright/.cache/
+
+# storybook
+storybook-static
+
+# tests
+/coverage/
+contracts-sol/.test-ledger
+website/test-results
+website/playwright-report
+
+# Python SDK
+sdk/python/.venv/
+sdk/python/.pytest_cache/
+sdk/python/**/__pycache__/
+sdk/python/**/*.py[cod]

tinyplace-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: tinyplace
+Version: 0.1.0
+Summary: Async Python REST SDK for tiny.place
+Author: TinyHumans AI
+License: GPL-3.0-or-later
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: pynacl>=1.5
+Requires-Dist: solders>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tinyplace Python SDK
+
+Async Python REST SDK for [tiny.place](https://tiny.place).
+
+This package mirrors the flagship TypeScript SDK's public REST surface, but it
+does not implement Signal end-to-end encryption, browser session signing, or
+WebSocket streams. It includes native SOL x402 helpers for local validator and
+backend settlement flows.
+
+## Install
+
+```bash
+pip install tinyplace
+```
+
+For local development:
+
+```bash
+cd sdk/python
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+`pytest` runs unit tests with coverage and fails below 80%.
+
+Local backend/Solana e2e tests are opt-in:
+
+```bash
+TINYPLACE_E2E=1 \
+  API_URL=http://localhost:8080 \
+  SOLANA_RPC_URL=http://localhost:8899 \
+  pytest tests/test_e2e.py -m e2e --no-cov -vv
+```
+
+## Usage
+
+```python
+from tinyplace import LocalSigner, TinyPlaceClient
+
+
+async def main() -> None:
+    signer = LocalSigner.generate()
+    async with TinyPlaceClient(
+        base_url="https://staging-api.tiny.place",
+        signer=signer,
+    ) as client:
+        availability = await client.registry.get("@alice")
+        print(availability)
+```
+
+Most responses are returned as decoded JSON dictionaries so the SDK can track
+the backend quickly while the API is still moving.

tinyplace-0.1.0/README.md

@@ -0,0 +1,54 @@
+# tinyplace Python SDK
+
+Async Python REST SDK for [tiny.place](https://tiny.place).
+
+This package mirrors the flagship TypeScript SDK's public REST surface, but it
+does not implement Signal end-to-end encryption, browser session signing, or
+WebSocket streams. It includes native SOL x402 helpers for local validator and
+backend settlement flows.
+
+## Install
+
+```bash
+pip install tinyplace
+```
+
+For local development:
+
+```bash
+cd sdk/python
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+`pytest` runs unit tests with coverage and fails below 80%.
+
+Local backend/Solana e2e tests are opt-in:
+
+```bash
+TINYPLACE_E2E=1 \
+  API_URL=http://localhost:8080 \
+  SOLANA_RPC_URL=http://localhost:8899 \
+  pytest tests/test_e2e.py -m e2e --no-cov -vv
+```
+
+## Usage
+
+```python
+from tinyplace import LocalSigner, TinyPlaceClient
+
+
+async def main() -> None:
+    signer = LocalSigner.generate()
+    async with TinyPlaceClient(
+        base_url="https://staging-api.tiny.place",
+        signer=signer,
+    ) as client:
+        availability = await client.registry.get("@alice")
+        print(availability)
+```
+
+Most responses are returned as decoded JSON dictionaries so the SDK can track
+the backend quickly while the API is still moving.

tinyplace-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tinyplace"
+version = "0.1.0"
+description = "Async Python REST SDK for tiny.place"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "GPL-3.0-or-later" }
+authors = [{ name = "TinyHumans AI" }]
+dependencies = [
+  "aiohttp>=3.9",
+  "PyNaCl>=1.5",
+  "solders>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pytest-cov>=5.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tinyplace"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=tinyplace --cov-report=term-missing --cov-fail-under=80"
+asyncio_mode = "auto"
+markers = [
+  "e2e: tests that require a running backend and local Solana validator",
+]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+omit = ["tests/*"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true

tinyplace-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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