Skip to content
Meshline
SDK 0.1.0-alpha.6 · GuideView source on GitHub

Direct messages and the outbox

Establish contact authorization before sending. The client must be running to process queued sends and receive asynchronous updates. Peers need to run to exchange contact and message data, but need not remain simultaneously online for every message.

Send content

The sendText function in workflows.ts queues a message and reads its current status:

export async function sendText(client: MeshlineClient, peerAccountId: string, text: string) {
    const queued = await client.messageManager.sendMessage(peerAccountId, {
        body: { contentType: 'text/plain', text },
    });
    return client.messageManager.getSendStatus(queued.messageId);
}

A draft can contain a body, attachments, and a reply reference. Direct replies use { from, messageId }; attachments are content references whose hosting and retrieval belong to your application. Omitted attachments mean no attachments.

sendMessage() returns a durable outbox status, not remote delivery confirmation. Direct messages automatically request offline push notifications. Persisting the encrypted request precedes submission. Observe sendStatusChanged or call getSendStatus(messageId) as processing continues.

Interpret send state

State Meaning for the application
queued Saved locally and eligible for cancellation before submission.
submitting A submission is in progress.
submissionUnknown The result is uncertain; the SDK retains the original request for reconciliation.
relayAccepted The submitting relay acknowledged acceptance.
targetAccepted The destination relay accepted the message; this is not a recipient read or processing receipt.
failed Processing recorded a terminal failure; inspect errorMessage.
canceled A queued request was canceled.

Status includes message and recipient IDs, creation time, and acceptance/error details when available. getOutbox({ recipient, states }) opens a local snapshot: omitting states includes all states; states: [] includes none.

Wait for an acceptance milestone

waitForSendStatus(messageId, targetState, signal) checks retained local status and waits for later commits by the same manager. The target defaults to targetAccepted; queued and relayAccepted are also supported. Other target values throw RangeError. There is no polling, extra network request, or implicit sender startup.

export async function waitForDelivery(client: MeshlineClient, messageId: string, signal?: AbortSignal) {
    return client.messageManager.waitForSendStatus(messageId, 'targetAccepted', signal);
}

Source: workflows.ts. Pass the ID returned by sendMessage. The result contains the actual status: targetAccepted also satisfies a relayAccepted wait, and queued accepts any recorded state. failed and canceled end every wait, so inspect state before continuing as though delivery succeeded. Target acceptance is not a read or processing receipt.

An unknown or already evicted record returns undefined immediately. This has the same uncertainty as getSendStatus. A wait already observing a pending message receives its committed completion even when the same transaction evicts that terminal record. It cannot recover outcomes evicted before observation began.

Initialize the manager before waiting and keep the client or manager running for delivery progress. Stop/start preserves waits; disposal aborts and drains them. Changes made by another manager or process are not observed. There is no built-in timeout: use a caller-owned AbortController and timer when a workflow needs a deadline, and clear the timer when done. Aborting one wait leaves the send and other waiters active. Query or wait on the same message ID afterward instead of sending another message as a retry.

Cancel or recover

cancelMessage(messageId) returns whether it canceled a queued message. Once submission has begun, cancellation cannot retract remote acceptance. An AbortSignal cancels the caller's operation; it does not prove the relay rejected or rolled back a request.

For uncertain submission, keep the original database and protector. The SDK retains the original ciphertext and accepting relay identity for retry or status reconciliation, including across process restart. Sending a newly created message as a generic retry can duplicate the user's message.

Retained send history

The SDK retains the newest 1000 terminal outbox records (targetAccepted, failed, and canceled) across this account, including internal protocol messages. Retention uses createdAt descending, then ordinal message ID descending to break ties; it follows creation order, not completion order. Pending records are never evicted by this limit. Initialization and send-state transactions prune excess terminal records without removing message history. Retained records include the original encrypted request and remain queryable after restart; getOutbox includes retained direct-message terminal records unless filtered out.

getSendStatus returns undefined for unknown or evicted records. Absence does not prove success, failure, or that a message was never recorded locally. Previously discarded results cannot be reconstructed from message history alone. Use status events for progress and stored messages for history; the bounded outbox is not a permanent delivery ledger.

Receive and query

messageReceived carries received messages; timelineChanged indicates local timeline changes. Use getMessage({ sender, messageId }) for one message and getMessageHistory(peerAccountId?) for a disposable local snapshot reader. History is ordered by ascending MessageInfo.localSequence, including when messages arrive with older creation times. getMessage and messageReceived return the same persisted position. Positions belong to this database's account-message stream, may have gaps, and cannot be compared across databases or with relay timeline sequences. createdAt remains available for display. The query does not fetch missing relay history; use synchronization for a fresh pass. Contacts must be authorized at receive time. Messages discarded for missing authorization are not replayed by later contact synchronization.

Use conversations for summaries and unread counts, and storage and pagination for reader lifetimes.

All guides