SDK API reference

Import

Each SDK is one package with one public module.

TrueSeal

One device in one namespace. The object outlives group membership. After a removal, leave() or destroyGroup(), the library wipes the namespace, makes a fresh identity and reports statusChanged(notJoined, reason), and the same object can pair again.

What to do. Open one object per namespace when the app starts and keep it. Never rebuild it after leaving a group.

static async open(relay: RelayAddress | string, storage: Storage, namespace: string = "default", maxPayloadBytes?: int) -> TrueSeal

Opens the device stored in storage under namespace. It returns before the relay connection is up and connects in the background, and send() works at once. maxPayloadBytes may lower the Protocol Size Limit; a higher value is clamped to it.

Values: Protocol Size Limit: 61,440 bytes (60 KiB).

Fails with invalidRelayAddress, invalidNamespace, storage, storeTooNew.

async close()

Stops the relay connection and every handler, and keeps Session State. After close(), every call fails with closed.

RelayAddress(host: string, publicKey: string, receivePort?: int, pushPort?: int)

The typed form of a Relay Address. TrueSeal.open takes it or the string the relay CLI prints. The port is never dropped.

Values: Relay Address format: trueseal://<relay public key hex>@host[:receivePort][?push=pushPort]; Default receive port: 7700; Default push port: 7701.

RelayAddress.parse(address: string) -> RelayAddress

Reads a Relay Address string into the typed form.

What to do. Use it to check a configured address before calling TrueSeal.open.

Storage

Where Session State lives. Kotlin always takes an explicit location, and Storage.android(context) builds it from an Android context. Swift takes the location as a plain URL on open; TS takes it as the storageDir option.

status: GroupStatus

Where this device is in a Sync Group. Swift observes it through @Observable, Kotlin through StateFlow, and TS through the statusChanged event.

me: Member

This device. Its id changes when the library makes a fresh identity.

members: Member[]

Every other member of the Sync Group, as a whole list and never a delta. It can briefly show a member leave and rejoin while a concurrent change is re-applied.

What to do. Render the whole list each time it changes.

connection: Connection

The relay connection. TS reports changes through the connectionChanged event.

GroupStatus: notJoined | pendingJoin | member | leaving | destroying

The device's place in a Sync Group. destroying lasts until the relay has accepted a Revoke for every member, with no timeout.

Connection: connecting | connected | disconnected | relayVersionUnsupported{min, max}

The relay connection state. relayVersionUnsupported carries the Transport Versions the relay accepts; versions are never negotiated.

Member{id, name}

A device in the Sync Group. name is a label the device chose, never authentication.

onMessage(handler: async (Message) -> void) -> Subscription

Registers the one message handler, and registering it starts receiving. The library awaits the handler and acks the message after it returns. A throw retries the message, up to the handler attempts below, then reports handlerGaveUp. Cancelling the Subscription pauses receiving.

Values: Handler attempts: 5 attempts.

Fails with messageHandlerAlreadySet.

What to do. Finish storing the message before the handler returns. Make the handler safe to run twice for one MessageId.

Message{id: MessageId, from: Member, body: bytes}

One received message. from.id is the same id as in members. body is the bytes the sender passed to send().

MessageId

An opaque message id, the same on sender and receiver. The library drops duplicates by it before the handler runs.

What to do. Store it as given. Never parse or rebuild it.

async send(body: bytes) -> MessageId

Queues body for every other member. It returns once the message is in the durable outbox, never after delivery. Bodies are opaque bytes.

Values: Protocol Size Limit: 61,440 bytes (60 KiB).

Fails with payloadTooLarge, notMember.

What to do. Keep the returned MessageId to match a later sendFailed.

startPairing() -> string

Opens the pairing window on an admitting device and returns the Pairing Token. Join requests arrive as joinRequest events.

What to do. Show the token as a QR code or copyable text on the admitting device.

async accept(request: JoinRequest)

Admits the device that sent request. The window closes after it.

Values: Maximum Group Size: 32 members.

Fails with pairingClosed, groupFull, manifestVersionExhausted.

What to do. Call it only after the user confirms the request comes from the device in front of them.

cancelPairing()

Closes the pairing window. There is no reject call; a request that was never accepted disappears when the window closes.

JoinRequest{id, name}

A device asking to join. name is a label the device chose, never authentication.

async join(token: string)

Asks to join the Sync Group behind token and moves the device to pendingJoin, which survives restarts. Once admitted, the device reports statusChanged(member, joined).

Fails with alreadyInGroup, invalidPairingToken.

cancelJoin()

Moves a pendingJoin device back to notJoined.

async remove(memberId: Member.id)

Removes another member. Any member may remove any other member. The removed device wipes and makes a fresh identity.

Fails with manifestVersionExhausted.

async leave()

Leaves the Sync Group. The device moves to leaving, then to notJoined with reason left.

Fails with manifestVersionExhausted.

async destroyGroup()

Ends the Sync Group for every member. The device stays destroying until the relay has accepted a Revoke for every member, with no timeout, then moves to notJoined with reason destroyed. Each member forwards the Revoke and wipes. An offline member wipes when it reconnects within the Relay TTL ceiling.

Values: Relay TTL ceiling: 30 days.

What to do. Show destroying until statusChanged reports notJoined, then pair again.

onEvent(listener: (event) -> void) -> Subscription

Registers an event listener. Any number may be registered. Events raised before the first listener are buffered.

onDeliveryIssue(listener: (issue) -> void) -> Subscription

Registers a delivery-issue listener. It is optional, and ignoring issues is safe. Every issue stays on the device; nothing goes back to the sender.

Subscription.cancel()

The handle every on call returns. Cancelling it removes the handler or listener.

TrueSeal.info: {sdkVersion, transportVersion, endToEndVersion}

The TrueSeal Release of this SDK and the Protocol Versions it speaks. Nothing is negotiated.

Values: TrueSeal Release: 0.6.0; Transport Version: 1; End-to-End Version: 1.

TrueSeal.maxPayloadBytes

The largest body send() accepts, in bytes.

Values: Protocol Size Limit: 61,440 bytes (60 KiB).

TrueSeal.maxGroupSize

The most devices one Sync Group holds.

Values: Maximum Group Size: 32 members.