client.kv

See the Storage guide for usage and patterns. For files, use client.storage.

Methods

set(collection, id, value, opts?)

set<T>(collection: string, id: string, value: T, opts?: { encrypt?: boolean }): Promise<void>

Stores value under collection/id. Encrypted at rest by default; pass { encrypt: false } to store plaintext. Needs an unlocked identity for encrypted writes.

get(collection, id)

get<T>(collection: string, id: string): Promise<T | null>

Returns the value (transparently decrypted) or null if absent.

delete(collection, id)

delete(collection: string, id: string): Promise<boolean>

Removes the key; resolves to whether it existed.

list(collection)

list(collection: string): Promise<string[]>

Returns the ids in a collection (not values). There is no server-side query — filter client-side after fetching (see Querying).

on(event, handler)

on(event: "change", handler: (e: StorageChangeEvent) => void): () => void

Subscribes to the realtime change feed for the signed-in user (across devices). Returns an unsubscribe function. Requires a WebSocket global.

interface StorageChangeEvent<T = unknown> {
  collection: string;
  id: string;
  type: "set" | "delete";
  data: T | null; // decrypted value on "set"; null on "delete"
}

query(...)

Reserved. Server-side query is intentionally unsupported (encrypted-at-rest); calling it throws. Use list() + client-side filtering.

Errors

Message contains	Meaning
not signed in	No active session — sign in first.
identity	Encrypted op needs an unlocked identity — login() or unlock().