API reference

@vaultys/peer-sdk

createPeer(options)

function createPeer(options: PeerOptions): Promise<Peer>;

Creates a peer, loads its contacts and outbox from the store, starts listening on the transport, and resumes delivery of queued messages.

PeerOptions

Option	Type	Default	Description
identity	VaultysId	required	Who the peer is. Switched to VaultysID v1. Never stored by the SDK.
transport	Transport	required	How to reach other peers, e.g. peerjsTransport()
store	Store	memoryStore()	Where contacts and the outbox live
acceptIncoming	(did) => boolean | Promise<boolean>	contacts only	Whether a peer that dialed you (and proved did) may connect
retry	{ initialMs?, maxMs? }	{ 2000, 300000 }	Backoff for redelivering queued messages
handshakeTimeoutMs	number	15000	Maximum time for the handshake
keepaliveMs	number	15000	Keepalive interval; a session closes after 3 silent intervals. 0 disables it.

Peer

Member	Description
did: string	This peer's DID
contacts: Contacts	The address book (see Contacts)
send<T>(did, body): Promise<{ id }>	Queue a message durably; resolves once it's stored. See Messaging.
protocol<T>(name): Protocol<T>	A typed, ephemeral channel. Names starting with vaultys/ are reserved.
connect(did): Promise<void>	Open (or reuse) an authenticated session
isOnline(did): boolean	Whether a session with did is open
online(): string[]	DIDs with an open session
disconnect(did): void	Close the session with did
close(): Promise<void>	Close all sessions and stop listening. Queued messages stay in the store.
on(event, listener): Unsubscribe	Listen to an event; returns a function that removes the listener
once(event, listener): Unsubscribe	Listen once
off(event, listener): void	Remove a listener

Events

Event	Payload	When
message	{ id, from, body, sentAt }	A message arrived. from is the proven DID. Each id is emitted once.
delivered	{ id, to }	The recipient acknowledged a message you sent
connection	{ did, online }	A session opened (online: true) or closed
error	PeerError	A background failure: an incoming peer you rejected, a failed handshake, a delivery error other than "unreachable"

Protocol<T>

Returned by peer.protocol<T>(name).

Member	Description
name: string	The protocol name
send(did, value: T): Promise<void>	Send now, connecting if needed. Not stored or retried; throws if the peer can't be reached.
on(handler: (from, value: T) => void): Unsubscribe	Receive values from any peer

Contacts

Member	Description
add(did, { name?, data? }): Promise<Contact>	Add or update a contact. Throws INVALID_DID for anything but a did:vaultys.
update(did, { name?, data? }): Promise<Contact>	Update an existing contact
remove(did): Promise<void>	Remove a contact
get(did): Contact | undefined	Look one up
has(did): boolean	Whether did is a contact
list(): Contact[]	All contacts

interface Contact {
  did: string;
  name?: string;
  data?: Record<string, unknown>; // your own fields; must be msgpack-serializable
  addedAt: number;
}

Errors

All SDK errors are PeerError instances with a code:

class PeerError extends Error {
  readonly code: PeerErrorCode;
}
function isPeerError(error: unknown, code?: PeerErrorCode): error is PeerError;

Code	Meaning
INVALID_DID	Not a did:vaultys identifier
UNREACHABLE	The transport couldn't reach the peer or the relay
REJECTED	The other side's policy refused you (or yours refused them)
IDENTITY_MISMATCH	Someone other than the dialed DID answered
HANDSHAKE_FAILED	Mutual authentication failed
DECRYPT_FAILED	A frame failed authentication; the session was closed
TIMEOUT	An operation took too long
CLOSED	The peer, session or transport is closed

try {
  await peer.connect(did);
} catch (error) {
  if (isPeerError(error, "UNREACHABLE")) showOffline(did);
  else throw error;
}

Stores

function memoryStore(): Store;
function indexedDBStore(dbName?: string): Store; // default "vaultys-peer"

interface Store {
  get(key: string): Promise<Uint8Array | undefined>;
  set(key: string, value: Uint8Array): Promise<void>;
  delete(key: string): Promise<void>;
  keys(prefix: string): Promise<string[]>;
}

See Storage.

Transports

function memoryNetwork(): {
  transport(): Transport;
  disconnect(did: string): void; // make `did` undialable, to simulate it going offline
};

interface Transport {
  listen(did: string, onLink: (link: Link) => void): Promise<void>;
  dial(did: string): Promise<Link>;
  close(): Promise<void>;
}

interface Link {
  send(frame: Uint8Array): void;
  onFrame(handler: (frame: Uint8Array) => void): void;
  onClose(handler: () => void): void;
  close(): void;
  readonly closed: boolean;
}

class BufferedLink implements Link {
  constructor(sendFrame: (frame: Uint8Array) => void, closeLink: () => void);
  receiveFrame(frame: Uint8Array): void; // call when a frame arrives
  receiveClose(): void;                  // call when the connection is gone
}

See Writing a transport.

Utilities

Export	Description
isVaultysDid(value): boolean	Whether a string is a did:vaultys identifier
handshake(link, identity, options)	The mutual authentication on its own, for custom tooling. Resolves with { remote, key, reader }.
Session	The encrypted session class, for custom tooling

@vaultys/peer-sdk/peerjs

function peerjsTransport(options?: PeerJSTransportOptions): Transport;

Accepts all PeerJS options, plus addressOf(did), timeoutMs (default 15000) and log(message). See Relays.

@vaultys/peer-sdk/yjs

class YjsProvider {
  constructor(peer: Peer, options: YjsProviderOptions);
  readonly doc: Y.Doc;
  readonly awareness: Awareness | null;
  readonly peers: string[];       // current members
  addPeer(did: string): void;
  removePeer(did: string): void;
  destroy(): void;
}

function ownedBy(ownerDid: string, myDid: string): (from: string) => boolean;

Option	Type	Default	Description
doc	Y.Doc	required	The document to sync
room	string	required	Room name; peers sync only within the same room
peers	string[]	[]	DIDs to sync with
awareness	Awareness | boolean	true	Presence: your instance, true to create one, or false
acceptUpdate	(from) => boolean	accept all	Ignore document updates from some members
admit	(did) => boolean	none admitted	Accept members who aren't in peers when they first send
reconnectMs	number	5000	How often to retry members who are offline; 0 disables it

See Collaboration.

@vaultys/peer-sdk/node

Export	Description
fileStore(directory): Store	A store with one file per key
installWebRTC(wrtc)	Expose a Node WebRTC implementation as the globals PeerJS needs

See Node.js.