Building blocks

The supported surface is the Client facade — client.auth, client.kv, client.storage, client.message, client.space. This page catalogs the lower-level exports the SDK is composed from. They’re public so power users can compose their own flows, but you rarely need them directly, and their shapes can change between minor versions ahead of 1.0.

Caution

Reach for these only when the facade can’t express what you need. Prefer the namespaced API in day-to-day app code.

Transport

WSTransport

Raw WebSocket transport: owns the socket lifecycle, auto-reconnect, outbound frame buffering, and a ping/pong heartbeat. Frames are encrypted a layer up.

new WSTransport({
  url: string;
  urlProvider?: () => string | Promise<string>; // fresh URL before each RECONNECT (single-use tickets)
  id?: string;                  // scopes events on the shared EventCore bus; unique id if omitted
  autoReconnect?: boolean;      // default true
  reconnectDelay?: number;      // ms, default 3000
  maxReconnectAttempts?: number;// default 5 (0 = unlimited)
  maxQueueSize?: number;        // default 100
  heartbeatInterval?: number;   // ms, default 30000 (0 = off)
  heartbeatTimeout?: number;    // ms, default 10000
  pingFrame?: string;           // default "ping"
  pongFrame?: string;           // default "pong"
  terminalCloseCodes?: number[];// a close with one of these codes does not reconnect
});

connect(): Promise<void>;
disconnect(): void;
resume(): void;                 // restart after a terminal close
send(frame: string): void;      // throws if the offline queue is full
isConnected(): boolean;
isConnecting(): boolean;
queuedFrames(): number;
reconnectAttemptCount(): number;
// extends EventCore: on/off/emit

Events

EventCore

Process-global event hub used internally for connection lifecycle. Events (the EventCoreEvents enum): connected, disconnected, reconnecting, error, data_received, data_sent, message, get_history, received_history, plus the offline lifecycle events online, offline, syncing, sync_progress, sync_complete and sync_error.

EventCore.on(event: EventCoreEvents, handler): void;
EventCore.off(event: EventCoreEvents, handler): void;
EventCore.emit(event: EventCoreEvents, data: unknown): void;

Messaging

Message

A serializable message body with an id, timestamp, and auto-computed checksum.

new Message(body);                  // or new Message({ body, id?, status?, checksum? })
message.id; message.timestamp; message.status; message.checksum;
message.body;                       // get deserializes; set serializes + checksums (max 3 MiB)
message.serialize(): string;
Message.deserialize(data: string): Message;
message.verifyChecksum(): void;     // throws on mismatch

Note

Message unwraps any object with a body key. When you send structured payloads, avoid the reserved top-level keys body, id, timestamp, status, and checksum.

Packet

Routing envelope around a Message: subject, source, target, optional headers, ttl, and signature.

new Packet({ subject, source, target, id?, message?, headers?, ttl?, timestamp?, signature? });
packet.serialize(): string;
Packet.deserialize(data: string): Packet;
packet.isExpired(): boolean;

Packet encryption

PacketCipher

The pluggable packet-encryption interface. Implementations: DoubleRatchetCipher (per-peer, forward-secret) and SpacePacketCipher (group-key sealing).

interface PacketCipher {
  seal(serializedMessage: string, packet: Packet): Promise<SealedHeaders>;
  handles(headers: PacketHeaders): boolean;
  open(headers: PacketHeaders): Promise<string | null>; // null if not for us
}

Spaces

These power client.space and the keeper-admitted, server-blind group-key distribution described in Spaces.

SpaceKeyring

Holds per-epoch group keys and coordinates distribution: a newcomer posts a join request, a key-holder ECIES-wraps the key to the newcomer’s identity key, the newcomer unwraps it. The relay only ever sees opaque blobs.

const k = new SpaceKeyring({ spaceId, memberId, identityEcdhPub, ownPrivateKey, transport, … });
k.currentEpoch(): number;
k.keyForEpoch(epoch: number): Uint8Array | undefined;
k.bootstrapNew(): Promise<void>;          // creator mints epoch-0 key
k.requestKey(desiredEpoch?: number): Promise<void>;
k.pullKeys(): Promise<number>;            // unwrap blobs addressed to us
k.admit(memberId, identityEcdhPub): Promise<void>;
k.admitPending(): Promise<string[]>;
k.rotate(roster?): Promise<number>;       // new epoch
k.invite(username): Promise<void>;
// KEEPER_MEMBER_ID ("__keeper__") — reserved id for the app's keeper member

KeyringClient

HTTP implementation of the keyring transport (postJoinRequest, fetchBlobs, postWrappedKey, fetchPending, fetchRoster, rotate, invite, fetchMetadata), plus the membership-log routes (fetchLog, postLogEntry, probeState) and the invite-link and role routes (createInviteLink, listInviteLinks, revokeInviteLink, redeemInvite, setMemberRole, members). A non-2xx answer from the log routes throws KeyringHttpError.

new KeyringClient({
  spaceId: string; httpBaseUrl: string; fetch: typeof fetch;
  fetchWithRecovery?: typeof fetch;  // fetch + silent 401 recovery; defaults to fetch
});

SpacePacketCipher

A PacketCipher that seals each message under the current epoch’s group key.

new SpacePacketCipher(keys: EpochKeyProvider, contentType?: string);

Personal storage

PersonalSpaceClient

A ZK-gated HTTP client for the personal key/value space (an alternative to the session-based client.kv for callers that prove per-op). Each call fetches a challenge nonce, generates a Groth16 proof for the preimagePoK circuit, and sends it with the operation. Depends on snarkjs.

new PersonalSpaceClient({ baseUrl, commitment, secret, salt, ecdsaPub, ecdsaPubHash, circuits }); // circuits: defaultCircuitUrls(baseUrl)
put(key: string, value: unknown): Promise<void>;
get<T>(key: string): Promise<T | null>;
delete(key: string): Promise<boolean>;
list(): Promise<string[]>;

Zero-knowledge verification

groth16-verifier

An edge/serverless-compatible Groth16 verifier driving bn128.wasm directly (no snarkjs/ffjavascript). Exported from every build, including the edge/serverless one — it’s how proofs are verified at the edge.

initBn128Wasm(wasmModule?: WebAssembly.Module): Promise<Bn128WasmInstance>;
verifyGroth16(
  instance: WebAssembly.Instance, memory: WebAssembly.Memory, initialPFree: number,
  verificationKey: VerificationKey, proof: Groth16Proof, publicSignals: string[],
): Promise<boolean>; // false on structural failure; throws only on WASM faults
// PREIMAGE_POK_VERIFICATION_KEY — the verification key for the preimagePoK circuit

Utilities

Logger plus byte/serialization helpers, exported from the package root.

new Logger(prefix?: string, level?: string, showCaller?: boolean);
// .info .warn .error .debug .verbose .success .setLevel(level)

generateId(): string;                 // base58-encoded UUID
serialize<T>(data: T): string;        // base58
deserialize<T>(s: string): T;

// byte helpers
toHex / fromHex / toBase64 / fromBase64 / toBase64Url / fromBase64Url
concatBytes / utf8Encode / utf8Decode

// method decorators
Retry(retries?, delay?)
Ready(readyProp?)

Shared types

Re-exported from the package root. Grouped by domain:

Domain	Types
Identity	ZkIdentity, AuthUser, UserIdentity, Session, AuthType, OAuthProvider
Permissions	Permission, Role, ACL, ACLEntry, Participant, PermissionCheckRequest, PermissionCheckResult
Crypto	Keypair, DehydratedKeypair, PublicKeyJWK, ECDHCurve
Messaging	MessageEvent, Subscription, WSMessage, WSMessageType
Zero-knowledge	Groth16Proof, VerificationKey, CircuitUrls, PREIMAGE_POK_VERIFICATION_KEY
Spaces	SpaceKeyCache, SpaceDeps, SpaceFileMetadata, SpaceMessageEvent, KeyringClientDeps, SpaceKeyringDeps, MemberView, MembershipEntry, ChatKeyCert
Storage	FileManifest, ChunkManifest, FileStat