API Reference

CloudSyncClient

The primary entry point for the SDK.

Constructor

CloudSyncClient(
    api_key: str,
    region: str = "us-east-1",
    transport: str = "websocket",
    **kwargs
) -> CloudSyncClient

Methods

connect()

Establishes a connection to the CloudSync relay server. Blocks until disconnected.

client.connect()

connect_async()

Non-blocking connection. Returns a Future.

future = client.connect_async()

disconnect()

Gracefully terminates the connection and flushes pending operations.

client.disconnect()

document(key: str) -> Document

Opens or creates a synchronized document.

doc = client.document("my-doc-key")

Parameter	Type	Description
key	str	Unique document identifier. Supports / for namespacing.

collection(prefix: str) -> Collection

Returns a queryable collection of documents sharing a key prefix.

users = client.collection("users:")
results = users.find({"role": "admin"})

status() -> ConnectionStatus

Returns the current connection state.

status = client.status()
# ConnectionStatus.CONNECTED | CONNECTING | DISCONNECTED | RECONNECTING

ping() -> float

Measures round-trip latency to the relay server in milliseconds.

latency = client.ping()
print(f"Latency: {latency:.1f}ms")

---

Document

Represents a single synchronized document.

Methods

set(data: dict) -> None

Replaces the document contents.

doc.set({"key": "value"})

get(field: str = None) -> Any

Reads the full document or a specific field.

all_data = doc.get()
single = doc.get("key")

update(field: str, value: Any) -> None

Updates a single field without replacing the entire document.

doc.update("status", "active")

delete(field: str = None) -> None

Deletes a specific field, or the entire document if no field is given.

doc.delete("old_field")
doc.delete()  # deletes entire document

on(event: str, callback: Callable) -> None

Registers an event listener.

@doc.on("change")
def on_change(event):
    print(event)

Supported events:

Event	Description
change	A field was created, updated, or deleted
sync	Full document state received from remote
conflict	A merge conflict was detected
error	An error occurred on this document

snapshot() -> dict

Returns a point-in-time copy of the document state.

data = doc.snapshot()

history(limit: int = 50) -> list[Revision]

Returns the revision history.

revisions = doc.history(limit=10)
for rev in revisions:
    print(f"{rev.timestamp} | {rev.author} | {rev.delta}")

---

Collection

A queryable set of documents sharing a key prefix.

Methods

find(query: dict = None) -> list[Document]

Queries documents in the collection.

admins = users.find({"role": "admin"})

count(query: dict = None) -> int

Returns the number of matching documents.

total = users.count()

watch() -> AsyncIterator[Event]

Watches for changes across the entire collection.

async for event in users.watch():
    print(f"Doc {event.document_key} changed")

---

Data Types

from cloudsync.types import Counter, Register, Set

# CRDT Counter — safe concurrent increment/decrement
views = Counter(0)
views.increment(1)
views.decrement(1)

# CRDT Last-Write-Wins Register
status = Register("active")
status.set("inactive")

# CRDT Observed-Remove Set
tags = Set()
tags.add("python")
tags.add("sdk")
tags.remove("sdk")

---

Next: Authentication →