instantdb 0.0.1__py3-none-any.whl

instantdb/__init__.py

@@ -0,0 +1,30 @@
+"""Python SDK for InstantDB.
+
+Quick start:
+
+    from instantdb import init, id
+
+    db = init(app_id="...", admin_token="...")
+    result = db.query({"goals": {"todos": {}}})
+"""
+
+from __future__ import annotations
+
+from ._client import Instant, init
+from ._errors import InstantAPIError, InstantError
+from ._subscribe import Subscription
+from ._transact import TransactionChunk, id, lookup, tx
+from ._version import __version__
+
+__all__ = [
+    "Instant",
+    "InstantAPIError",
+    "InstantError",
+    "Subscription",
+    "TransactionChunk",
+    "__version__",
+    "id",
+    "init",
+    "lookup",
+    "tx",
+]

instantdb/_auth.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+from ._http import Config, authorized_headers, json_request
+
+
+class Auth:
+    """Auth admin operations: magic codes, tokens, users."""
+
+    def __init__(self, client: httpx.Client, config: Config):
+        self._client = client
+        self._config = config
+
+    def generate_magic_code(self, email: str) -> dict[str, Any]:
+        """Generate a magic code without sending it (use your own email provider)."""
+        return json_request(
+            self._client,
+            "POST",
+            f"{self._config.api_uri}/admin/magic_code?app_id={self._config.app_id}",
+            headers=authorized_headers(self._config),
+            json={"email": email},
+        )
+
+    def send_magic_code(self, email: str) -> dict[str, Any]:
+        """Send a magic code to the given email using Instant's email provider."""
+        return json_request(
+            self._client,
+            "POST",
+            f"{self._config.api_uri}/admin/send_magic_code?app_id={self._config.app_id}",
+            headers=authorized_headers(self._config),
+            json={"email": email},
+        )
+
+    def check_magic_code(
+        self,
+        email: str,
+        code: str,
+        extra_fields: dict[str, Any] | None = None,
+    ) -> tuple[dict[str, Any], bool]:
+        """Verify a magic code and return (user, created)."""
+        body: dict[str, Any] = {"email": email, "code": code}
+        if extra_fields:
+            body["extra-fields"] = extra_fields
+        response = json_request(
+            self._client,
+            "POST",
+            f"{self._config.api_uri}/admin/verify_magic_code?app_id={self._config.app_id}",
+            headers=authorized_headers(self._config),
+            json=body,
+        )
+        return response["user"], bool(response.get("created"))
+
+    def create_token(
+        self,
+        *,
+        email: str | None = None,
+        id: str | None = None,
+    ) -> str:
+        """Create a refresh token for the given user. Creates the user if missing."""
+        if email is None and id is None:
+            raise ValueError("create_token requires email= or id=")
+        body: dict[str, str] = {}
+        if email is not None:
+            body["email"] = email
+        if id is not None:
+            body["id"] = id
+        response = json_request(
+            self._client,
+            "POST",
+            f"{self._config.api_uri}/admin/refresh_tokens?app_id={self._config.app_id}",
+            headers=authorized_headers(self._config),
+            json=body,
+        )
+        return response["user"]["refresh_token"]
+
+    def verify_token(self, token: str) -> dict[str, Any]:
+        """Verify a refresh token and return the associated user."""
+        response = json_request(
+            self._client,
+            "POST",
+            f"{self._config.api_uri}/runtime/auth/verify_refresh_token?app_id={self._config.app_id}",
+            headers={"content-type": "application/json"},
+            json={"app-id": self._config.app_id, "refresh-token": token},
+        )
+        return response["user"]
+
+    def get_user(
+        self,
+        *,
+        email: str | None = None,
+        id: str | None = None,
+        refresh_token: str | None = None,
+    ) -> dict[str, Any]:
+        """Look up an app user by email, id, or refresh token."""
+        params = self._build_user_params(email=email, id=id, refresh_token=refresh_token)
+        qs = urlencode(params)
+        response = json_request(
+            self._client,
+            "GET",
+            f"{self._config.api_uri}/admin/users?app_id={self._config.app_id}&{qs}",
+            headers=authorized_headers(self._config),
+        )
+        return response["user"]
+
+    def delete_user(
+        self,
+        *,
+        email: str | None = None,
+        id: str | None = None,
+        refresh_token: str | None = None,
+    ) -> dict[str, Any]:
+        """Delete an app user by email, id, or refresh token. Does not delete their data."""
+        params = self._build_user_params(email=email, id=id, refresh_token=refresh_token)
+        qs = urlencode(params)
+        response = json_request(
+            self._client,
+            "DELETE",
+            f"{self._config.api_uri}/admin/users?app_id={self._config.app_id}&{qs}",
+            headers=authorized_headers(self._config),
+        )
+        return response["deleted"]
+
+    def sign_out(
+        self,
+        *,
+        email: str | None = None,
+        id: str | None = None,
+        refresh_token: str | None = None,
+    ) -> None:
+        """Invalidate all tokens for the given user."""
+        body = self._build_user_params(email=email, id=id, refresh_token=refresh_token)
+        json_request(
+            self._client,
+            "POST",
+            f"{self._config.api_uri}/admin/sign_out?app_id={self._config.app_id}",
+            headers=authorized_headers(self._config),
+            json=body,
+        )
+
+    @staticmethod
+    def _build_user_params(
+        *,
+        email: str | None,
+        id: str | None,
+        refresh_token: str | None,
+    ) -> dict[str, str]:
+        provided = {
+            "email": email,
+            "id": id,
+            "refresh_token": refresh_token,
+        }
+        params = {k: v for k, v in provided.items() if v is not None}
+        if not params:
+            raise ValueError("Must provide one of email=, id=, or refresh_token=")
+        if len(params) > 1:
+            raise ValueError("Provide only one of email=, id=, or refresh_token=")
+        return params

instantdb/_client.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import uuid
+import warnings
+from typing import Any
+
+import httpx
+
+from ._auth import Auth
+from ._http import Config, authorized_headers, json_request
+from ._rooms import Rooms
+from ._storage import Storage
+from ._subscribe import SubscribeCallback, Subscription
+from ._transact import TransactionChunk, _TxRoot, chunks_to_steps
+
+_DEFAULT_API_URI = "https://api.instantdb.com"
+
+
+def init(
+    *,
+    app_id: str,
+    admin_token: str | None = None,
+    api_uri: str | None = None,
+) -> Instant:
+    """Create a new Instant admin client.
+
+    Visit https://instantdb.com/dash to get your app id and admin token.
+    """
+    cleaned_app_id = app_id.strip() if app_id else app_id
+    if not _is_valid_uuid(cleaned_app_id):
+        warnings.warn(
+            f"Instant Admin DB must be initialized with a valid app_id. Received: {app_id!r}",
+            stacklevel=2,
+        )
+    config = Config(
+        app_id=cleaned_app_id,
+        admin_token=admin_token.strip() if admin_token else None,
+        api_uri=(api_uri or _DEFAULT_API_URI).strip(),
+    )
+    return Instant(config)
+
+
+def _is_valid_uuid(s: str | None) -> bool:
+    if not s:
+        return False
+    try:
+        uuid.UUID(s)
+        return True
+    except ValueError:
+        return False
+
+
+class Instant:
+    """The primary entrypoint for interacting with an Instant app.
+
+    Construct via `init(app_id=..., admin_token=...)` rather than directly.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        impersonation: dict[str, Any] | None = None,
+        client: httpx.Client | None = None,
+    ):
+        self._config = config
+        self._impersonation = impersonation
+        self._client = client or httpx.Client(timeout=httpx.Timeout(60.0, connect=10.0))
+        self.tx = _TxRoot()
+        self.auth = Auth(self._client, config)
+        self.storage = Storage(self._client, config, impersonation)
+        self.rooms = Rooms(self._client, config)
+
+    @property
+    def config(self) -> Config:
+        return self._config
+
+    def as_user(
+        self,
+        *,
+        email: str | None = None,
+        token: str | None = None,
+        guest: bool | None = None,
+    ) -> Instant:
+        """Scope subsequent operations to a user (or guest) for permissions purposes.
+
+        Pass exactly one of email=, token=, or guest=True.
+        """
+        opts = _impersonation_opts(email=email, token=token, guest=guest)
+        return Instant(self._config, impersonation=opts, client=self._client)
+
+    def query(
+        self,
+        query: dict[str, Any],
+        *,
+        rule_params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Run a one-shot InstaQL query."""
+        prepared = {"$$ruleParams": rule_params, **query} if rule_params is not None else query
+        return json_request(
+            self._client,
+            "POST",
+            f"{self._config.api_uri}/admin/query?app_id={self._config.app_id}",
+            headers=authorized_headers(self._config, self._impersonation),
+            json={"query": prepared, "inference?": False},
+        )
+
+    def transact(
+        self,
+        chunks: TransactionChunk | list[TransactionChunk],
+    ) -> dict[str, Any]:
+        """Apply one or more transaction chunks atomically."""
+        return json_request(
+            self._client,
+            "POST",
+            f"{self._config.api_uri}/admin/transact?app_id={self._config.app_id}",
+            headers=authorized_headers(self._config, self._impersonation),
+            json={"steps": chunks_to_steps(chunks)},
+        )
+
+    def subscribe_query(
+        self,
+        query: dict[str, Any],
+        callback: SubscribeCallback | None = None,
+        *,
+        rule_params: dict[str, Any] | None = None,
+    ) -> Subscription:
+        """Open a live SSE subscription to a query.
+
+        With no `callback`, the returned object is iterable - blocking until the
+        next payload arrives. With a `callback`, payloads are dispatched on a
+        background daemon thread. Call `.close()` (or use as a context manager)
+        to end the subscription.
+        """
+        prepared = {"$$ruleParams": rule_params, **query} if rule_params is not None else query
+        return Subscription(
+            config=self._config,
+            query=prepared,
+            impersonation=self._impersonation,
+            callback=callback,
+        )
+
+    def debug_query(
+        self,
+        query: dict[str, Any],
+        *,
+        rules: dict[str, Any] | None = None,
+        rule_params: dict[str, Any] | None = None,
+        ip: str | None = None,
+        origin: str | None = None,
+    ) -> dict[str, Any]:
+        """Run a query and also return permissions-check results for each row.
+
+        Requires `as_user` context since permissions are user-scoped.
+        """
+        prepared = {"$$ruleParams": rule_params, **query} if rule_params is not None else query
+        body: dict[str, Any] = {
+            "query": prepared,
+            "rules-override": rules,
+            "inference?": False,
+        }
+        if ip is not None:
+            body["ip-override"] = ip
+        if origin is not None:
+            body["origin-override"] = origin
+        response = json_request(
+            self._client,
+            "POST",
+            f"{self._config.api_uri}/admin/query_perms_check?app_id={self._config.app_id}",
+            headers=authorized_headers(self._config, self._impersonation),
+            json=body,
+        )
+        return {
+            "result": response.get("result"),
+            "check_results": response.get("check-results"),
+        }
+
+    def debug_transact(
+        self,
+        chunks: TransactionChunk | list[TransactionChunk],
+        *,
+        rules: dict[str, Any] | None = None,
+        ip: str | None = None,
+        origin: str | None = None,
+    ) -> dict[str, Any]:
+        """Dry-run a transaction and return permissions-check results.
+
+        Does not commit. Requires `as_user` context.
+        """
+        body: dict[str, Any] = {
+            "steps": chunks_to_steps(chunks),
+            "rules-override": rules,
+        }
+        if ip is not None:
+            body["ip-override"] = ip
+        if origin is not None:
+            body["origin-override"] = origin
+        return json_request(
+            self._client,
+            "POST",
+            f"{self._config.api_uri}/admin/transact_perms_check?app_id={self._config.app_id}",
+            headers=authorized_headers(self._config, self._impersonation),
+            json=body,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> Instant:
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+
+def _impersonation_opts(
+    *,
+    email: str | None,
+    token: str | None,
+    guest: bool | None,
+) -> dict[str, Any]:
+    provided = sum(x is not None for x in (email, token, guest))
+    if provided == 0:
+        raise ValueError("as_user requires one of email=, token=, or guest=True")
+    if provided > 1:
+        raise ValueError("as_user accepts only one of email=, token=, or guest=True")
+    if email is not None:
+        return {"email": email}
+    if token is not None:
+        return {"token": token}
+    return {"guest": bool(guest)}

instantdb/_errors.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class InstantError(Exception):
+    """Base class for all Instant SDK errors."""
+
+
+class InstantAPIError(InstantError):
+    """Raised when the Instant API returns a non-2xx response."""
+
+    def __init__(self, status: int, body: Any, message: str | None = None):
+        self.status = status
+        self.body = body
+        super().__init__(message or self._format_message())
+
+    def _format_message(self) -> str:
+        if isinstance(self.body, dict):
+            msg = self.body.get("message")
+            if msg:
+                return str(msg)
+        return f"Instant API error ({self.status}): {self.body!r}"

instantdb/_http.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._errors import InstantAPIError
+from ._version import __version__
+
+
+class Config:
+    """Resolved client configuration. Internal use only."""
+
+    __slots__ = ("app_id", "admin_token", "api_uri")
+
+    def __init__(self, app_id: str, admin_token: str | None, api_uri: str):
+        self.app_id = app_id
+        self.admin_token = admin_token
+        self.api_uri = api_uri.rstrip("/")
+
+
+def authorized_headers(
+    config: Config,
+    impersonation: dict[str, Any] | None = None,
+) -> dict[str, str]:
+    _validate_auth(config, impersonation)
+    headers: dict[str, str] = {
+        "content-type": "application/json",
+        "app-id": config.app_id,
+        "Instant-Admin-Version": __version__,
+        "Instant-Core-Version": __version__,
+    }
+    if config.admin_token:
+        headers["authorization"] = f"Bearer {config.admin_token}"
+    if impersonation:
+        if "email" in impersonation:
+            headers["as-email"] = str(impersonation["email"])
+        elif "token" in impersonation:
+            headers["as-token"] = str(impersonation["token"])
+        elif impersonation.get("guest"):
+            headers["as-guest"] = "true"
+    return headers
+
+
+def _validate_auth(config: Config, impersonation: dict[str, Any] | None) -> None:
+    if impersonation and ("token" in impersonation or "guest" in impersonation):
+        return
+    if config.admin_token:
+        return
+    if impersonation and "email" in impersonation:
+        raise ValueError(
+            "Admin token required. To impersonate users with an email you must pass "
+            "`admin_token` to `init`."
+        )
+    raise ValueError(
+        "Admin token required. To run this operation pass `admin_token` to `init`, "
+        "or use `db.as_user`."
+    )
+
+
+def json_request(
+    client: httpx.Client,
+    method: str,
+    url: str,
+    *,
+    headers: dict[str, str],
+    json: Any = None,
+    content: bytes | None = None,
+) -> Any:
+    """Make an HTTP request and return parsed JSON. Raises InstantAPIError on non-2xx."""
+    response = client.request(
+        method,
+        url,
+        headers=headers,
+        json=json if content is None else None,
+        content=content,
+    )
+    if 200 <= response.status_code < 300:
+        return response.json() if response.content else None
+    try:
+        body: Any = response.json()
+    except ValueError:
+        body = {"type": None, "message": response.text}
+    raise InstantAPIError(status=response.status_code, body=body)

instantdb/_rooms.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ._http import Config, authorized_headers, json_request
+
+
+class Rooms:
+    """Room operations: presence."""
+
+    def __init__(self, client: httpx.Client, config: Config):
+        self._client = client
+        self._config = config
+
+    def get_presence(self, room_type: str, room_id: str) -> dict[str, Any]:
+        """Get the current presence data for a room.
+
+        Returns a mapping of `peer_id` to `{"data": ..., "peer-id": ..., "user": ...}`.
+        """
+        url = (
+            f"{self._config.api_uri}/admin/rooms/presence"
+            f"?app_id={self._config.app_id}"
+            f"&room-type={quote(room_type)}"
+            f"&room-id={quote(room_id)}"
+        )
+        response = json_request(
+            self._client,
+            "GET",
+            url,
+            headers=authorized_headers(self._config),
+        )
+        return response.get("sessions") or {}

instantdb/_storage.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import IO, Any
+
+import httpx
+
+from ._http import Config, authorized_headers, json_request
+
+FileLike = bytes | bytearray | memoryview | IO[bytes] | Path
+
+
+class Storage:
+    """File storage operations."""
+
+    def __init__(
+        self,
+        client: httpx.Client,
+        config: Config,
+        impersonation: dict[str, Any] | None = None,
+    ):
+        self._client = client
+        self._config = config
+        self._impersonation = impersonation
+
+    def upload_file(
+        self,
+        path: str,
+        file: FileLike,
+        *,
+        content_type: str | None = None,
+        content_disposition: str | None = None,
+    ) -> dict[str, Any]:
+        """Upload a file to the given path.
+
+        `file` can be bytes, a binary file-like object, or a `pathlib.Path`.
+        """
+        headers = authorized_headers(self._config, self._impersonation)
+        headers["path"] = path
+        headers.pop("content-type", None)
+        if content_type:
+            headers["content-type"] = content_type
+        if content_disposition:
+            headers["content-disposition"] = content_disposition
+
+        content = _read_file(file)
+        return json_request(
+            self._client,
+            "PUT",
+            f"{self._config.api_uri}/admin/storage/upload?app_id={self._config.app_id}",
+            headers=headers,
+            content=content,
+        )
+
+
+def _read_file(file: FileLike) -> bytes:
+    if isinstance(file, (bytes, bytearray, memoryview)):
+        return bytes(file)
+    if isinstance(file, Path):
+        return file.read_bytes()
+    if hasattr(file, "read"):
+        data = file.read()
+        if isinstance(data, str):
+            raise TypeError("upload_file expects bytes, got a text-mode file")
+        return bytes(data)
+    raise TypeError(f"Unsupported file type: {type(file).__name__}")

instantdb/_subscribe.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import threading
+from collections.abc import Callable, Iterator
+from typing import Any
+
+import httpx
+from httpx_sse import EventSource
+
+from ._errors import InstantAPIError
+from ._http import Config, authorized_headers
+from ._version import __version__
+
+logger = logging.getLogger(__name__)
+
+SubscribeCallback = Callable[[dict[str, Any]], None]
+
+
+def _format_page_info(raw: dict[str, Any] | None) -> dict[str, Any] | None:
+    if not raw:
+        return None
+    out: dict[str, Any] = {}
+    for etype, info in raw.items():
+        out[etype] = {
+            "start_cursor": info.get("start-cursor"),
+            "end_cursor": info.get("end-cursor"),
+            "has_next_page": info.get("has-next-page?"),
+            "has_previous_page": info.get("has-previous-page?"),
+        }
+    return out
+
+
+class Subscription:
+    """A live subscription to an InstaQL query, backed by SSE.
+
+    Iterate (`for payload in sub`) to consume payloads synchronously, or pass a
+    `callback=` to receive them on a background thread. Either way, call
+    `sub.close()` to stop the subscription. Works as a context manager:
+
+        with db.subscribe_query({"todos": {}}) as sub:
+            for payload in sub:
+                ...
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        query: dict[str, Any],
+        impersonation: dict[str, Any] | None,
+        callback: SubscribeCallback | None = None,
+    ):
+        self._config = config
+        self._query = query
+        self._headers = authorized_headers(config, impersonation)
+        self._callback = callback
+        self._closed = False
+        self._ready_state: str = "connecting"
+        self._session_info: dict[str, str] | None = None
+        self._client: httpx.Client | None = None
+        self._response_cm: Any = None
+        self._started = False
+        self._lock = threading.Lock()
+
+        if callback is not None:
+            threading.Thread(target=self._run_callback, daemon=True).start()
+
+    @property
+    def ready_state(self) -> str:
+        return self._ready_state
+
+    @property
+    def is_closed(self) -> bool:
+        return self._ready_state == "closed"
+
+    @property
+    def session_info(self) -> dict[str, str] | None:
+        return self._session_info
+
+    def __iter__(self) -> Iterator[dict[str, Any]]:
+        return self._stream()
+
+    def __enter__(self) -> Subscription:
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            self._ready_state = "closed"
+        if self._response_cm is not None:
+            with contextlib.suppress(Exception):
+                self._response_cm.__exit__(None, None, None)
+        if self._client is not None:
+            with contextlib.suppress(Exception):
+                self._client.close()
+
+    def _run_callback(self) -> None:
+        assert self._callback is not None
+        try:
+            for payload in self._stream():
+                if self._closed:
+                    return
+                try:
+                    self._callback(payload)
+                except Exception:
+                    logger.exception("Error in subscribe_query callback")
+        except Exception:
+            logger.exception("Subscribe stream terminated unexpectedly")
+
+    def _stream(self) -> Iterator[dict[str, Any]]:
+        with self._lock:
+            if self._started:
+                raise RuntimeError(
+                    "Subscription has already started. Create a new subscription to iterate again."
+                )
+            self._started = True
+            if self._closed:
+                return
+
+        self._client = httpx.Client(timeout=httpx.Timeout(None, connect=10.0))
+        body = json.dumps(
+            {
+                "query": self._query,
+                "inference?": False,
+                "versions": {
+                    "@instantdb/admin": __version__,
+                    "@instantdb/core": __version__,
+                },
+            }
+        )
+        url = f"{self._config.api_uri}/admin/subscribe-query?app_id={self._config.app_id}"
+        sse_headers = {**self._headers, "accept": "text/event-stream"}
+
+        try:
+            self._response_cm = self._client.stream(
+                "POST",
+                url,
+                headers=sse_headers,
+                content=body,
+            )
+            response = self._response_cm.__enter__()
+        except httpx.HTTPError as e:
+            self._ready_state = "closed"
+            yield self._error_payload(
+                InstantAPIError(
+                    status=0,
+                    body={"type": None, "message": str(e)},
+                )
+            )
+            return
+
+        if response.status_code != 200:
+            try:
+                error_body: Any = json.loads(response.read())
+            except ValueError:
+                error_body = {"type": None, "message": response.text}
+            self._ready_state = "closed"
+            yield self._error_payload(InstantAPIError(status=response.status_code, body=error_body))
+            return
+
+        self._ready_state = "open"
+        try:
+            for sse in EventSource(response).iter_sse():
+                if self._closed:
+                    return
+                if not sse.data:
+                    continue
+                try:
+                    msg = json.loads(sse.data)
+                except ValueError:
+                    continue
+                payload = self._handle_message(msg)
+                if payload is not None:
+                    yield payload
+        except httpx.HTTPError as e:
+            if not self._closed:
+                yield self._error_payload(
+                    InstantAPIError(
+                        status=0,
+                        body={"type": None, "message": str(e)},
+                    )
+                )
+        finally:
+            self._ready_state = "closed"
+            self.close()
+
+    def _handle_message(self, msg: dict[str, Any]) -> dict[str, Any] | None:
+        op = msg.get("op")
+        if op == "sse-init":
+            self._session_info = {
+                "machine_id": msg.get("machine-id", ""),
+                "session_id": msg.get("session-id", ""),
+            }
+            return None
+        if op == "add-query-ok":
+            return {
+                "type": "ok",
+                "data": msg.get("result"),
+                "page_info": _format_page_info((msg.get("result-meta") or {}).get("page-info")),
+                "session_info": self._session_info,
+            }
+        if op == "refresh-ok":
+            computations = msg.get("computations") or []
+            if computations:
+                first = computations[0]
+                return {
+                    "type": "ok",
+                    "data": first.get("instaql-result"),
+                    "page_info": _format_page_info(
+                        (first.get("result-meta") or {}).get("page-info")
+                    ),
+                    "session_info": self._session_info,
+                }
+            return None
+        if op == "error":
+            return self._error_payload(
+                InstantAPIError(
+                    status=msg.get("status") or 0,
+                    body=msg,
+                )
+            )
+        return None
+
+    def _error_payload(self, error: InstantAPIError) -> dict[str, Any]:
+        return {
+            "type": "error",
+            "error": error,
+            "ready_state": self._ready_state,
+            "is_closed": self.is_closed,
+            "session_info": self._session_info,
+        }

instantdb/_transact.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+_LOOKUP_PREFIX = "lookup__"
+
+
+def id() -> str:
+    """Generate a new UUID for use as an entity id."""
+    return str(uuid.uuid4())
+
+
+def lookup(attribute: str, value: Any) -> str:
+    """Build a lookup ref for use in place of an entity id."""
+    return f"{_LOOKUP_PREFIX}{attribute}__{json.dumps(value)}"
+
+
+def _is_lookup(k: str) -> bool:
+    return isinstance(k, str) and k.startswith(_LOOKUP_PREFIX)
+
+
+def _parse_lookup(k: str) -> list[Any]:
+    parts = k.split("__")
+    _, attribute, *v_parts = parts
+    return [attribute, json.loads("__".join(v_parts))]
+
+
+class TransactionChunk:
+    """A chain of pending tx operations targeting one entity."""
+
+    __slots__ = ("_etype", "_eid", "_ops")
+
+    def __init__(self, etype: str, eid: Any, ops: list[list[Any]]):
+        self._etype = etype
+        self._eid = eid
+        self._ops = ops
+
+    def update(self, args: dict[str, Any], opts: dict[str, Any] | None = None) -> TransactionChunk:
+        return self._append("update", args, opts)
+
+    def create(self, args: dict[str, Any], opts: dict[str, Any] | None = None) -> TransactionChunk:
+        return self._append("create", args, opts)
+
+    def link(self, args: dict[str, Any]) -> TransactionChunk:
+        return self._append("link", args)
+
+    def unlink(self, args: dict[str, Any]) -> TransactionChunk:
+        return self._append("unlink", args)
+
+    def delete(self) -> TransactionChunk:
+        return self._append("delete", {})
+
+    def merge(self, args: dict[str, Any], opts: dict[str, Any] | None = None) -> TransactionChunk:
+        return self._append("merge", args, opts)
+
+    def rule_params(self, args: dict[str, Any]) -> TransactionChunk:
+        return self._append("ruleParams", args)
+
+    def _append(
+        self,
+        action: str,
+        args: dict[str, Any],
+        opts: dict[str, Any] | None = None,
+    ) -> TransactionChunk:
+        op: list[Any] = [action, self._etype, self._eid, args]
+        if opts is not None:
+            op.append(opts)
+        return TransactionChunk(self._etype, self._eid, [*self._ops, op])
+
+
+class _EtypeChunk:
+    __slots__ = ("_etype",)
+
+    def __init__(self, etype: str):
+        self._etype = etype
+
+    def __getitem__(self, eid: Any) -> TransactionChunk:
+        if _is_lookup(eid):
+            return TransactionChunk(self._etype, _parse_lookup(eid), [])
+        return TransactionChunk(self._etype, eid, [])
+
+    def lookup(self, attribute: str, value: Any) -> TransactionChunk:
+        return TransactionChunk(self._etype, [attribute, value], [])
+
+
+class _TxRoot:
+    """Entrypoint for the tx builder. Indexes/attributes produce namespace chunks."""
+
+    def __getattr__(self, etype: str) -> _EtypeChunk:
+        return _EtypeChunk(etype)
+
+    def __getitem__(self, etype: str) -> _EtypeChunk:
+        return _EtypeChunk(etype)
+
+
+tx = _TxRoot()
+
+
+def get_ops(chunk: TransactionChunk) -> list[list[Any]]:
+    return list(chunk._ops)
+
+
+def chunks_to_steps(
+    chunks: TransactionChunk | list[TransactionChunk],
+) -> list[list[Any]]:
+    """Flatten a chunk or list of chunks into the wire format expected by the server."""
+    if isinstance(chunks, TransactionChunk):
+        return get_ops(chunks)
+    steps: list[list[Any]] = []
+    for chunk in chunks:
+        steps.extend(get_ops(chunk))
+    return steps

instantdb/_version.py

@@ -0,0 +1,16 @@
+"""Single source of truth for the package version.
+
+The version is read from the package metadata, which hatchling stamps at build
+time from `client/packages/version/src/version.ts` so the Python SDK stays
+locked to the JS SDK family's version.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("instantdb")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

instantdb-0.0.1.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: instantdb
+Version: 0.0.1
+Summary: Python SDK for InstantDB, the Modern Firebase
+Project-URL: Homepage, https://instantdb.com
+Project-URL: Documentation, https://instantdb.com/docs
+Project-URL: Repository, https://github.com/instantdb/instant
+Project-URL: Issues, https://github.com/instantdb/instant/issues
+Author-email: Instant <founders@instantdb.com>
+License-Expression: Apache-2.0
+Keywords: database,graph,instant,instantdb,realtime
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx-sse>=0.4
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://instantdb.com">
+    <img alt="Shows the Instant logo" src="https://instantdb.com/img/icon/android-chrome-512x512.png" width="10%">
+  </a>
+  <h1 align="center">instantdb</h1>
+</p>
+
+<p align="center">
+  <a href="https://discord.com/invite/VU53p7uQcE">
+    <img height=20 src="https://img.shields.io/discord/1031957483243188235" />
+  </a>
+  <img src="https://img.shields.io/github/stars/instantdb/instant" alt="stars">
+</p>
+
+<p align="center">
+   <a href="https://www.instantdb.com/docs/backend">Get Started</a> ·
+   <a href="https://instantdb.com/examples">Examples</a> ·
+   <a href="https://www.instantdb.com/docs/backend">Docs</a> ·
+   <a href="https://discord.com/invite/VU53p7uQcE">Discord</a>
+</p>
+
+The Python SDK for [Instant](https://instantdb.com). This is a server SDK
+(analogous to `@instantdb/admin`) for running scripts, agents, data pipelines,
+and backend services against Instant from Python.
+
+## Install
+
+```bash
+pip install instantdb
+# or
+uv add instantdb
+```
+
+## Quick start
+
+```python
+from instantdb import init, id
+
+db = init(app_id="...", admin_token="...")
+
+# Query data
+result = db.query({"goals": {"todos": {}}})
+print(result["goals"])
+
+# Write data
+goal_id = id()
+db.transact([
+    db.tx.goals[goal_id].update({"title": "Get fit"}),
+    db.tx.todos[id()].update({"title": "Go on a run"}),
+])
+
+# Subscribe to live changes
+for payload in db.subscribe_query({"goals": {}}):
+    if payload["type"] == "error":
+        print("error:", payload["error"])
+        break
+    print("data:", payload["data"])
+```
+
+See the [backend docs](https://www.instantdb.com/docs/backend) for the full
+admin API reference. The Python SDK mirrors that surface 1:1, with naming
+Pythonized to `snake_case`.
+
+## Development
+
+Clone the [repo](https://github.com/instantdb/instant). From `client/packages/python/`:
+
+```bash
+make install   # pip install -e ".[dev]"
+make check     # ruff + mypy + pytest (~40 unit tests)
+```
+
+Pure-logic only - covers tx builder, validators, header construction. For
+end-to-end testing against a real backend, use the sandbox at
+[`client/sandbox/admin-sdk-python/`](../../sandbox/admin-sdk-python/).
+
+## Questions?
+
+If you have any questions, feel free to drop us a line on our
+[Discord](https://discord.com/invite/VU53p7uQcE).

instantdb-0.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+instantdb/__init__.py,sha256=CfzR935XZMFYnu2UmZILIyDox94YCKDQ4eU_0RUbeVE,611
+instantdb/_auth.py,sha256=zc8tdzI-dOixlSsnGgUI5v6zpx3GHG2UJb_4BB788BM,5568
+instantdb/_client.py,sha256=bh8IX7Gv0D5vBUjzkaQwrF0nTU4K25M53SMJ3YVS95M,7330
+instantdb/_errors.py,sha256=c5hSvfljRMJiPnfzx6IpCi2X40B2RakCJ7c3y0a1VsY,678
+instantdb/_http.py,sha256=nmA0iwhq2t2fKh2367skOmsSR-YhHnftAHj-NJoIhAc,2547
+instantdb/_rooms.py,sha256=drXlNdjE9T2Zeqi6_NGWu5USOdKjDQTwkdGATPKoo54,992
+instantdb/_storage.py,sha256=cxQXsJ2-zND2D5MH6gypaYr2xpPtgXPaBAUEEQ2HZ6c,1908
+instantdb/_subscribe.py,sha256=4pqzNfBoZdluVGqu94trcTK0Y9h56NEz1YzH2ZiKW9g,7778
+instantdb/_transact.py,sha256=aPteTZAY70Y4-dXFUlQpVQPfGedYdoC21XhJkAGrfr0,3369
+instantdb/_version.py,sha256=p8qkgd_X1hsJYDnkCG0hyN2hqmi3MyGhsCqElbPM5Ps,506
+instantdb-0.0.1.dist-info/METADATA,sha256=6xdz5i9J5qvQHG_9Gwm59dtr0jSM3eOyggMQBJwgu3k,3579
+instantdb-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+instantdb-0.0.1.dist-info/RECORD,,

instantdb-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any