SDK Reference
This page covers the main exported building blocks in @koralabs/handle-chat-sdk.
SignalProtocolStore
In-memory storage implementation for Signal session state, identity keys, pre-keys, signed pre-keys, and sessions. Use this as the local crypto store in your app, then populate or restore it from serialized data.
SignalDirectory
Helper for storing public key bundles and retrieving pre-key bundles for session setup. This is useful in local examples and controlled integrations where your app manages bundle lookup.
- createStoreBundle: creates a public bundle plus the matching local store entry.
- populateStore: loads a store entry into a SignalProtocolStore instance.
- createID: convenience helper that creates a bundle, populates a store, and registers it in a SignalDirectory.
- serializeBundle and deserializeBundle: convert bundle data to and from storage-safe values.
- serializeStore and deserializeStore: convert local cryptographic store data to and from storage-safe values.
- encryptAndBuildMessage: encrypts a string or ArrayBuffer payload for a recipient and returns both the encrypted transport message and the local processed message representation.
- readMessage: decrypts an incoming message with a session cipher and returns a processed message object. If decryption fails, it returns a readable failure placeholder instead of throwing.
- arrayBufferToBase64: converts binary data to a base64 string.
- base64ToArrayBuffer: restores binary data from a base64 string.
- ChatUser: user model used for a chat identity, including Handle-style identity details, acceptance state, device id, image, chats, and optional serialized bundle/store data.
- ChatMessage: encrypted transport message model with sender, recipient, timestamp, and Signal message payload.
- ProcessedChatMessage: local, readable message model for UI rendering and chat history.
- SessionMessage: session lifecycle message shape for create, accept, deny, fail, and end events.
- StoreEntry and SerializedStoreEntry: local cryptographic store shapes.
- FullDirectoryEntry and SerializableFullDirectoryEntry: public bundle shapes before and after serialization.
- The SDK handles encryption primitives and related data structures. Your app still needs transport and UI.
- Bundle exchange and session lifecycle delivery are application-level concerns outside the SDK itself.
- Serialized bundles and stores are designed to be saved in browser or app storage and restored later.