SFClient class

High-level client for store-and-forward messaging

Provides easy-to-use API for sending messages with automatic routing via S&F servers when recipients are offline, retrieving pending messages, and managing preferences.

Constructors

SFClient({required Host host, required SFClientConfig config, PubSub? pubsub, PayloadEncryptor? encryptor})

Properties

config → SFClientConfig

final

contactPresenceChanges → Stream<PresenceChange>?

Stream of presence changes for tracked contacts

no setter

encryptor → PayloadEncryptor?

Seals and opens payloads with this identity's key. Without one, sendMessage(encrypt: true) is an error and an encrypted message cannot be retrieved.

final

hashCode → int

The hash code for this object.

no setter, inherited

host → Host

final

incomingMessages → Stream<SFMessage>

Stream of incoming messages

no setter

mailboxes → MailboxManager

Access mailbox management operations

no setter

notifications → Stream<MailboxNotification>

Stream of mailbox notifications (both private and public/shared)

no setter

peerId → PeerId

Get peer ID

no setter

pubsub → PubSub?

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

appendFeedEntry({required String path, required Uint8List content, String? entryType, PeerId? ownerPeerId, PeerId? toServer}) → Future<FeedAppendResult?>

Append an entry to a feed ownerPeerId Optional: feed owner's peer ID (for collaborative feeds). If omitted, defaults to this client's own peer ID.

batchGetFeedEntries({required List<Map<String, dynamic>> queries, PeerId? fromServer}) → Future<BatchFeedEntriesResult?>

Batch get feed entries from multiple feeds in a single request. Each query is a map with keys: ownerPeerId, path, fromSequence (optional), limit (optional). Returns results keyed by "ownerPeerId/path".

browseDirectory({String? cursor, int limit = 20, String? search, PeerId? fromServer}) → Future<DirectoryBrowseResult?>

Browse the user directory on a server

buildDocumentUri(String path) → RicochetUri

Build a document URI for a resource owned by the current user

buildMailboxUri(String path) → RicochetUri

Build a mailbox URI for a resource owned by the current user

claimMessage({required PeerId ownerPeerId, required String folderPath, PeerId? fromServer}) → Future<SFMessage?>

Claim one message from ownerPeerId's claim mailbox at folderPath (MailboxType.claim): the server deletes the oldest message and hands it to this caller alone. Returns null when none is left, which is also the answer once the mailbox has handed out its share for the hour.

createCollection({required String path, required String name, CollectionVisibility? visibility, PeerId? toServer}) → Future<CollectionInfo?>

Create a new collection on your store.

createFeed({required String path, required String title, String description = '', bool collaborative = false, PeerId? toServer}) → Future<FeedInfo?>

Create a new feed on your store

deleteCollection({required String path, PeerId? toServer}) → Future<bool>

Delete a collection from your store

deleteCollectionItem({required String path, required String key, PeerId? toServer}) → Future<bool>

Delete a collection item

deleteDocument({required String path, String? ifMatch, PeerId? toServer}) → Future<bool>

Delete a document from your own store

deleteFeed({required String path, PeerId? toServer}) → Future<bool>

Delete a feed from your store

deleteMessages(List<String> messageIds, {PeerId? serverPeerId}) → Future<DeleteMessagesAck?>

Delete messages immediately (bypasses \Deleted flag)

expungeMessages({PeerId? serverPeerId, String? folderPath}) → Future<ExpungeAck?>

Expunge messages marked with \Deleted flag (IMAP EXPUNGE)

getCollection({required PeerId ownerPeerId, required String path, PeerId? fromServer}) → Future<CollectionInfo?>

Get collection metadata

getCollectionItem({required PeerId ownerPeerId, required String path, required String key, PeerId? fromServer}) → Future<CollectionItem?>

Get a single collection item by key

getContactPresence(PeerId contact) → PresenceStatus?

Get a contact's current presence state (from local cache)

getDocument({required PeerId ownerPeerId, required String path, String? ifNoneMatch, PeerId? fromServer}) → Future<DocumentResponse?>

Get a document from a peer's store

getDocumentHistory({required PeerId ownerPeerId, required String path, int? maxVersions, PeerId? fromServer}) → Future<List<DocumentVersionInfo>?>

The kept versions of a document, newest first, with sizes but not bodies. Empty when history is off; null if the document does not exist or the request failed.

getDocumentVersion({required PeerId ownerPeerId, required String path, required int versionNumber, PeerId? fromServer}) → Future<DocumentVersionInfo?>

One kept version of a document with its body. Null if it is not kept or the request failed.

getFeed({required PeerId ownerPeerId, required String path, PeerId? fromServer}) → Future<FeedInfo?>

Get feed metadata

getFeedEntries({required PeerId ownerPeerId, required String path, int? fromSequence, int? toSequence, int? limit, String? entryType, PeerId? fromServer}) → Future<FeedEntriesResult?>

Get feed entries (range query)

getFeedEntry({required PeerId ownerPeerId, required String path, required int sequenceNumber, PeerId? fromServer}) → Future<FeedEntry?>

Get a single feed entry by sequence number

getStats() → Map<String, dynamic>

Get client statistics

headDocument({required PeerId ownerPeerId, required String path, PeerId? fromServer}) → Future<DocumentMetadata?>

Check if a document has changed (HEAD request)

isContactOnline(PeerId contact) → bool

Check if a contact is online

joinDirectory({required String displayName, String? bio, Map<String, dynamic>? extras, PeerId? toServer}) → Future<bool>

Opt in to the server's user directory

leaveDirectory({PeerId? toServer}) → Future<bool>

Opt out of the server's user directory

listCollectionKeys({required PeerId ownerPeerId, required String path, int? limit, int? offset, PeerId? fromServer}) → Future<CollectionKeysResult?>

List keys in a collection

listCollections({required PeerId ownerPeerId, PeerId? fromServer}) → Future<List<CollectionInfo>?>

List all collections for an owner

listDocuments({required PeerId ownerPeerId, String pathPrefix = '', PeerId? fromServer}) → Future<List<DocumentInfo>?>

List all documents for a peer

listFeeds({required PeerId ownerPeerId, PeerId? fromServer}) → Future<List<FeedInfo>?>

List all feeds for an owner

markMessagesDelivered(List<String> messageIds, {PeerId? serverPeerId, String? folderPath}) → Future<MarkDeliveredAck?>

Mark messages as delivered (sets \Seen flag)

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

patchDocument({required String path, required Map<String, dynamic> patch, String? ifMatch, PeerId? toServer}) → Future<DocumentPutResponse?>

Patch a document using JSON Merge Patch (RFC 7396)

putCollectionItem({required String path, required String key, required Uint8List content, String? ifMatch, PeerId? toServer}) → Future<CollectionItemResult?>

Put (create or update) a collection item

putDocument({required String path, required Uint8List content, String contentType = 'application/json', String? ifMatch, DocumentVisibility? visibility, int? history, PeerId? toServer}) → Future<DocumentPutResponse?>

Put a document to your own store

queryCollection({required PeerId ownerPeerId, required String path, Map<String, dynamic>? filter, String? sortField, bool? sortAsc, int? limit, int? offset, PeerId? fromServer}) → Future<CollectionQueryResult?>

Query a collection with JSONB filtering

queryServerCapacity(PeerId serverId) → Future<ServerCapacity?>

Query server capacity

registerPrivateNotificationHandler() → void

Register handler for private mailbox direct streams

registerServerAddress(PeerId serverId, MultiAddr addr) → void

Register a known server address so the ServerSelector can refresh peerstore TTLs when reconnection is needed after address expiry.

resolveUri(RicochetUri uri, {Duration? perServerTimeout}) → Future<ResolvedDocument?>

Resolve a Ricochet URI to its content

restoreDocumentVersion({required String path, required int versionNumber, String? ifMatch, PeerId? toServer}) → Future<DocumentPutResponse?>

Make a kept version of one of your own documents current again. It is written as a new version (DocumentPutResponse.version), so with history on the version it replaces is kept and the restore can be undone. ifMatch makes it conditional on the current ETag (409 if it changed); 404 if the version is not kept. Null if the request failed.

retrieveMessages({PeerId? targetPeerId, PeerId? fromServer, String? folderPath, int? fromSequence, int? maxMessages, MessagePriority? minPriority, bool throwOnFailure = false}) → Future<List<SFMessage>>

Retrieve pending messages from S&F server

sendMessage({required PeerId recipient, required Uint8List payload, String? folderPath, MessagePriority priority = MessagePriority.normal, Duration? expiry, bool persistent = false, bool tryDirectFirst = false, bool encrypt = false}) → Future<SendResult>

Send a message (auto-routes via S&F if recipient offline)

setCollectionVisibility({required String path, required CollectionVisibility visibility, PeerId? toServer}) → Future<CollectionFrameResponse?>

Set who may read one of your own collections.

setDocumentVisibility({required String path, required DocumentVisibility visibility, PeerId? toServer}) → Future<DocumentFrameResponse?>

Set who may read one of your own documents.

setPreferredServers(List<SFServerPreference> servers) → Future<void>

Set preferred S&F servers (MX-like)

start() → Future<void>

Start the client (enables auto-retrieval if configured)

startAutoRetrieval() → void

Start automatic message retrieval

stop() → Future<void>

Stop the client

stopAutoRetrieval() → void

Stop automatic message retrieval

subscribeToMailbox(String ownerPeerId, String folderPath) → Future<void>

Subscribe to GossipSub topic for public/shared mailbox

toString() → String

A string representation of this object.

override

trackContactPresence(PeerId contact, PeerId serverPeerId) → void

Track a contact's online/offline presence

unsubscribeFromMailbox(String ownerPeerId, String folderPath) → Future<void>

Unsubscribe from mailbox topic

untrackContactPresence(PeerId contact) → void

Stop tracking a contact's presence

updateMessageFlags(String messageId, {PeerId? serverPeerId, int addFlags = 0, int removeFlags = 0}) → Future<UpdateFlagsAck?>

Update flags on a message (IMAP STORE)

Operators

operator ==(Object other) → bool

The equality operator.

inherited