Struct SoftchatAccount 

pub struct SoftchatAccount { /* private fields */ }

Android-facing owner of one identity and one Rust-managed account database.

Implementations

impl AccountRuntimeHandle

pub fn open( secret_key_bytes: Vec<u8>, database_directory: String, ) -> Result<Self, SoftchatError>

Open one Rust-owned SQLite account runtime.

Android supplies a private per-account file path and retains lifecycle, HTTP, files, background scheduling, and UI ownership. Relay transport can be host-driven or delegated to the optional managed resource.

Errors

Returns a stable identity, account, schema, path, or persistence error.

pub fn account_id(&self) -> String

Return the non-secret account partition.

pub fn public_key(&self) -> Result<String, SoftchatError>

Return the canonical public key that owns this account.

Errors

Returns SoftchatError::AccountClosed after explicit close.

pub fn database_filename(&self) -> String

Return the derived account database filename without exposing a path.

pub fn descriptor(&self) -> Result<AccountDescriptor, SoftchatError>

Return the validated non-secret account identity and storage filename.

This compact snapshot lets authored facades initialize without repeating native calls or querying SQLite metadata.

Errors

Returns SoftchatError::AccountClosed after explicit close.

pub fn close_account(&self)

Irreversibly close this account authority.

The authored facade immediately releases the generated object after this call, which closes SQLite and removes the same-path registry entry. Repeated close calls are harmless.

pub fn set_log_level(&self, level: AccountLogLevel) -> Result<(), SoftchatError>

Change the bounded account diagnostic threshold.

Off keeps the disabled hot path to one relaxed atomic load. Enabling diagnostics records one lifecycle event; no secret, event identifier, URL, frame, or caller content is retained.

Errors

Returns SoftchatError::AccountClosed after explicit close.

pub fn drain_log_events( &self, limit: u32, ) -> Result<AccountLogBatch, SoftchatError>

Drain at most 64 structured account diagnostics in sequence order.

The ring is process-memory-only and retains at most 256 events. The returned drop count reports overwritten events since the previous drain.

Errors

Returns a stable bound error. A final drain remains valid immediately after close_account so the authored facade can deliver account.close before releasing the generated handle.

pub fn get_or_create_conversation( &self, member_public_keys: Vec<String>, now: i64, ) -> Result<ConversationRecord, SoftchatError>

Create or return one conversation from remote member keys.

The local account key is derived internally and included exactly once.

Errors

Returns a stable account, key, bound, or persistence error.

pub fn conversation( &self, conversation_id: String, ) -> Result<Option<ConversationRecord>, SoftchatError>

Return one complete conversation by stable ID.

Errors

Returns a stable account, key, or persistence error.

pub fn conversation_page( &self, archived: bool, cursor: Option<ConversationCursor>, limit: u32, ) -> Result<ConversationPage, SoftchatError>

Return one bounded stable page of complete conversations.

Errors

Returns a stable cursor, bound, account, or persistence error.

pub fn message( &self, message_id: String, ) -> Result<Option<AccountMessageView>, SoftchatError>

Return one complete effective message by ID.

Errors

Returns a stable ID, account, or persistence error.

pub fn messages_by_ids( &self, message_ids: Vec<String>, ) -> Result<Vec<AccountMessageView>, SoftchatError>

Return up to 512 unique exact messages in caller order, omitting unknown IDs.

Includes effective edits, reactions, and deletion tombstones from one database snapshot. Empty input returns an empty result.

Errors

Returns a stable ID, duplicate, bound, account, or persistence error.

pub fn message_page( &self, conversation_id: String, cursor: Option<MessageCursor>, limit: u32, ) -> Result<MessagePage, SoftchatError>

Return one bounded lossless tuple-cursor message page.

Errors

Returns a stable ID, cursor, bound, account, or persistence error.

pub fn message_replies( &self, message_id: String, cursor: Option<MessageCursor>, limit: u32, ) -> Result<MessagePage, SoftchatError>

Return a newest-first tuple-cursor page of direct replies in the root conversation.

Unrelated messages and forwards do not consume the page. Includes deletion tombstones; an unknown root returns an empty page. Limits and cursors match message_page.

Errors

Returns a stable ID, cursor, bound, account, or persistence error.

pub fn message_context( &self, message_id: String, before: u32, after: u32, ) -> Result<Vec<AccountMessageView>, SoftchatError>

Return a bounded context centered on one stored message.

Errors

Returns a stable ID, bound, account, or persistence error.

pub fn search_messages( &self, conversation_id: String, query: String, limit: u32, ) -> Result<Vec<AccountMessageView>, SoftchatError>

Search effective live message text through the Rust-owned FTS index.

Empty conversation_id searches the whole account.

Errors

Returns a stable query, bound, account, or persistence error.

pub fn message_local_extras( &self, message_id: String, ) -> Result<Option<MessageLocalExtras>, SoftchatError>

Return sparse account-local transcript and waveform data for one message.

Errors

Returns a stable message, account, or persistence error.

pub fn set_message_local_extras( &self, message_id: String, transcript: Option<String>, waveform: Vec<u8>, now: i64, ) -> Result<AccountMutationResult, SoftchatError>

Replace sparse account-local transcript and normalized waveform data.

Errors

Returns a stable message, bound, account, or persistence error.

pub fn conversation_count(&self, archived: bool) -> Result<u32, SoftchatError>

Return the exact number of archived or active conversations.

Errors

Returns a stable persistence error.

pub fn has_unread(&self, include_archived: bool) -> Result<bool, SoftchatError>

Return whether another participant has an unread live message.

Errors

Returns a stable account or persistence error.

pub fn search_conversations( &self, query: String, archived: Option<bool>, limit: u32, ) -> Result<Vec<ConversationRecord>, SoftchatError>

Search complete conversation views by subject, member key, or known name. Matching ignores ASCII case; other Unicode characters remain literal.

An empty archived filter searches both active and archived conversations.

Errors

Returns a stable search, bound, account, or persistence error.

pub fn send_message( &self, command_id: String, conversation_id: String, content: MessageContentInput, reply_to_message_id: String, draft_to_consume: Option<AccountDraft>, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Send one atomic idempotent chat command.

Rust resolves participants, relay selection, notification recipients, local echo, wrappers, and delivery intents from durable account state. The host persists its exact portable composer snapshot before passing it in draft_to_consume. When present, the same SQLite transaction clears it only if the stored semantic draft still matches. A newer draft is preserved, including when its autosave wins the race before this command acquires SQLite. An idempotent replay returns before draft matching.

Errors

Returns a stable command, conversation, content, relay, or persistence error.

pub fn forward_message( &self, command_id: String, message_id: String, destination_conversation_id: String, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Forward one stored authenticated message to another conversation.

Replaying a committed command returns its original operation even if the source message was subsequently deleted.

Errors

Returns a stable command, message, conversation, relay, or persistence error.

pub fn set_conversation_subject( &self, command_id: String, conversation_id: String, subject: String, icon: Option<AttachmentMetadata>, emoji_tags: Vec<Vec<String>>, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Publish one conversation subject update.

Errors

Returns a stable command, conversation, subject, relay, or persistence error.

pub fn toggle_message_reaction( &self, command_id: String, message_id: String, reaction: MessageReactionInput, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Toggle one reaction by the local account on a stored message.

A committed command replays its original result without toggling again, including after later reactions or deletion of the parent message. Removal addresses all active local copies of the value, independently of the bounded message view. More than 256 matching copies returns InvalidAccountOperation without a partial deletion or revision change.

Errors

Returns a stable command, message, reaction, authorization, or persistence error.

pub fn edit_message( &self, command_id: String, message_id: String, replacement: MessageContentInput, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Replace text and emoji on one locally authored stored message.

Replaying a committed command with the same payload returns its existing operation even if the original message has subsequently been deleted. A different payload for that command remains a command conflict.

Errors

Returns a stable command, authorization, content, or persistence error.

pub fn delete_message( &self, command_id: String, message_id: String, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Delete one locally authored stored message.

Errors

Returns a stable command, authorization, message, or persistence error.

pub fn delete_messages( &self, command_id: String, message_ids: Vec<String>, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Delete a bounded set of locally authored messages from one conversation atomically.

One idempotent command authors one deletion rumor containing every target. Either the complete command is committed and projected or no target is changed.

Errors

Returns a stable command, bound, authorization, message, conversation, or persistence error.

pub fn typing_changed( &self, command_id: String, conversation_id: String, is_typing: bool, now: i64, ) -> Result<Option<ProductOperationResult>, SoftchatError>

Publish an ephemeral typing event when enabled by account settings.

Returning None means no wire event was required.

Errors

Returns a stable command, conversation, settings, or persistence error.

pub fn set_conversation_archived( &self, conversation_id: String, archived: bool, now: i64, ) -> Result<AccountMutationResult, SoftchatError>

Set the local archived state for one conversation.

Errors

Returns a stable conversation or persistence error.

pub fn set_conversation_pinned( &self, conversation_id: String, pinned: bool, now: i64, ) -> Result<AccountMutationResult, SoftchatError>

Set the local pinned state for one conversation.

Errors

Returns a stable conversation or persistence error.

pub fn mark_conversation_read( &self, command_id: String, conversation_id: String, boundary: MessageCursor, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Mark one conversation read through an exact stable message cursor.

The cursor timestamp must match its stored message. State preview, signing and commit share one account lock so concurrent changes retain a complete cross-device snapshot. Committed commands replay before preparing another snapshot, preserving later read-state updates and the current account revision.

Errors

Returns a stable conversation, timestamp, or persistence error.

pub fn mark_conversation_unread( &self, command_id: String, conversation_id: String, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Mark one conversation unread without destroying its prior read boundary.

State preview, signing and commit share one account lock. Committed commands replay without preparing or changing current state.

Errors

Returns a stable conversation or persistence error.

pub fn account_read_state(&self) -> Result<Vec<AccountReadState>, SoftchatError>

Return the complete effective cross-device read-state snapshot.

Errors

Returns a stable account or persistence error.

pub fn save_conversation_draft( &self, conversation_id: String, draft: Option<AccountDraft>, now: i64, ) -> Result<AccountMutationResult, SoftchatError>

Save or clear one portable conversation draft.

Errors

Returns a stable draft, conversation, or persistence error.

pub fn account_settings(&self) -> Result<AccountSettings, SoftchatError>

Return the complete versioned account settings.

Errors

Returns a stable settings or persistence error.

pub fn apply_account_settings_patch( &self, command_id: String, patch_json: String, now: i64, ) -> Result<AccountSettingsMutation, SoftchatError>

Apply one JSON merge patch while retaining unknown settings fields.

The account lock spans preview, signing and commit so concurrent patches preserve each other’s independent fields.

Replaying a committed bounded patch returns current settings without merging it again, creating another operation or advancing the revision.

The authored Android facade exposes typed patch values; JSON remains a private FFI representation.

Errors

Returns a stable settings, timestamp, or persistence error.

pub fn profile( &self, public_key: String, ) -> Result<AccountProfile, SoftchatError>

Return one effective authenticated/local profile.

Errors

Returns a stable key, account, or persistence error.

pub fn profiles( &self, public_keys: Vec<String>, ) -> Result<Vec<AccountProfile>, SoftchatError>

Resolve effective authenticated/local profiles for exact keys in input order.

At most 512 keys are accepted. Unknown keys return empty profile values carrying their canonical public key, so consumers never need per-row fallback queries or a second profile cache.

Errors

Returns a stable key, bound, account, or persistence error.

pub fn profile_page( &self, limit: u32, offset: u32, ) -> Result<Vec<AccountProfile>, SoftchatError>

Return one bounded stable profile page.

Errors

Returns a stable bound, account, or persistence error.

pub fn follows(&self) -> Result<Vec<Contact>, SoftchatError>

Return the effective private follow list authored by this account.

Errors

Returns a stable account, contact-list, or persistence error.

pub fn search_profiles( &self, query: String, limit: u32, ) -> Result<Vec<AccountProfile>, SoftchatError>

Search effective profiles by public key, authenticated metadata, or local label. Matching ignores ASCII case; other Unicode characters remain literal.

Errors

Returns a stable search, bound, account, or persistence error.

pub fn update_profile( &self, command_id: String, patch_json: String, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Merge and publish a private profile patch.

Missing fields remain unchanged, JSON null clears a field, and a concrete value replaces it. Authenticated fields unknown to this SDK version are retained automatically.

Errors

Returns a stable command, profile, recipient, relay, or persistence error.

pub fn replace_follows( &self, command_id: String, contacts: Vec<Contact>, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Publish a complete private follow-list replacement.

Errors

Returns a stable command, contact, relay, or persistence error.

pub fn follow( &self, command_id: String, contact: Contact, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Add or replace one entry in the private follow list atomically.

Rust reads the current authenticated list, applies the keyed update, authors its self-copy, and commits the outgoing operation while holding one account-database lock. Concurrent callers cannot lose updates.

Errors

Returns a stable command, contact, relay, or persistence error.

pub fn unfollow( &self, command_id: String, public_key: String, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Remove one public key from the private follow list atomically.

Removing an absent key is a valid idempotent replacement. Reusing the same command ID with a different resulting list is still rejected.

Errors

Returns a stable command, key, relay, or persistence error.

pub fn register_push_token( &self, command_id: String, platform: PushPlatform, token: String, installation_id: String, now: i64, ) -> Result<ProductOperationResult, SoftchatError>

Register an FCM or APNs token through its released NIP-78 wire profile.

Errors

Returns a stable command, token, relay, signing, or persistence error.

pub fn media_gallery( &self, conversation_id: String, before: Option<MessageCursor>, limit: u32, ) -> Result<Vec<AccountMediaItem>, SoftchatError>

Return a bounded account or conversation media gallery.

limit is a soft attachment count from 1 through 100. The final message’s attachment group is returned in full so a message cursor cannot skip its remainder. At most limit + 31 items are returned. Deleted messages are excluded.

Errors

Returns a stable cursor, bound, account, or persistence error.

pub fn prepare_media_message( &self, command_id: String, conversation_id: String, content: MessageContentInput, reply_to_message_id: String, sources: Vec<MediaPreparationInput>, draft_to_consume: Option<AccountDraft>, now: i64, ) -> Result<PendingMediaMessage, SoftchatError>

Persist one attachment-dependent message before Android starts file or HTTP work.

The host persists its exact portable composer snapshot before passing it in draft_to_consume. When present, preparation clears it in the same transaction only while the stored semantic draft still matches. A newer autosave and every idempotent replay are preserved.

Errors

Returns a stable command, conversation, content, media, or persistence error.

pub fn pending_media_message( &self, command_id: String, ) -> Result<Option<PendingMediaMessage>, SoftchatError>

Return one durable attachment-dependent message intent.

Errors

Returns a stable command, media, or persistence error.

pub fn cancel_pending_media_message( &self, command_id: String, now: i64, ) -> Result<PendingMediaMessage, SoftchatError>

Cancel one unpublished attachment-dependent message and its unfinished transfers.

Cancellation is idempotent and may retire a permanently failed message. Completed attachment operations remain immutable, while every unfinished dependency loses its lease and becomes cancelled in the same transaction.

Errors

Returns a stable command, media, timestamp, account, or persistence error.

pub fn pending_media_messages( &self, limit: u32, ) -> Result<Vec<PendingMediaMessage>, SoftchatError>

Return a bounded newest-update-first page of attachment-dependent messages.

Errors

Returns a stable bound, media, or persistence error.

pub fn prepare_asset_replacement( &self, command_id: String, target: AssetReplacementTarget, conversation_id: String, source_fingerprint: String, now: i64, ) -> Result<PendingAssetReplacement, SoftchatError>

Persist one public asset replacement before Android starts file or HTTP work.

The upload is intentionally public because profile and subject icon readers receive only a URL. Rust retains the dependent profile or subject command and completes it idempotently after the upload.

Guide

Errors

Returns a stable command, target, conversation, media, or persistence error.

pub fn pending_asset_replacement( &self, command_id: String, ) -> Result<Option<PendingAssetReplacement>, SoftchatError>

Return one durable upload-dependent asset replacement.

Guide

Errors

Returns a stable command, media, or persistence error.

pub fn pending_asset_replacements( &self, limit: u32, ) -> Result<Vec<PendingAssetReplacement>, SoftchatError>

Return a bounded newest-update-first page of asset replacements.

Guide

Errors

Returns a stable bound, media, or persistence error.

pub fn prepare_media_operation( &self, command_id: String, conversation_id: String, direction: String, source_fingerprint: String, now: i64, ) -> Result<AccountMediaOperation, SoftchatError>

Prepare one idempotent logical media operation.

Errors

Returns a stable command, media, conversation, or persistence error.

pub fn prepare_media_download( &self, message_id: String, attachment_url: String, now: i64, ) -> Result<AccountMediaOperation, SoftchatError>

Prepare or return the stable download for one authenticated attachment.

Rust resolves the message, validates the attachment URL, and derives the idempotency key and source fingerprint. Android receives only the logical operation and performs the file/HTTP effect.

Errors

Returns a stable message, media, or persistence error.

pub fn prepare_conversation_icon_download( &self, conversation_id: String, now: i64, ) -> Result<AccountMediaOperation, SoftchatError>

Prepare or return the stable download for the current authenticated conversation icon.

Rust resolves the effective subject event and retains its complete imeta integrity metadata. Public icons require the downloaded-object SHA-256 (x); encrypted icons may rely on final AEAD authentication. The operation is bound to that exact subject version, so completion is rejected only when a later authenticated subject explicitly changes the icon. Text- or emoji-only subjects inherit it.

Errors

Returns a stable conversation, media, or persistence error.

pub fn restart_media_download( &self, operation_id: String, now: i64, ) -> Result<AccountMediaOperation, SoftchatError>

Restart an authenticated download after cache eviction or user retry.

Completed uploads and non-download operations are rejected. Running, prepared, and retryable downloads are returned without modification. A terminal conversation-icon download whose authenticated source was superseded remains terminal; callers prepare the current icon instead.

Errors

Returns a stable media or persistence error.

pub fn complete_media_operation( &self, operation_id: String, lease_id: String, attachment: AttachmentMetadata, byte_count: u64, now: i64, ) -> Result<MediaCompletionResult, SoftchatError>

Commit final authenticated attachment metadata.

An exact retry of an already committed completion returns the persisted result before freshness checks. Freshness gates only the first running conversation-icon transition, so a lost success response remains safe to retry after a later subject changes the icon.

Errors

Returns SoftchatError::InvalidAttachmentMetadata when attachment is malformed, SoftchatError::InvalidMediaOperation when the operation or lease is stale, or a stable persistence error.

pub fn recover_pending_media_messages( &self, limit: u32, now: i64, ) -> Result<Vec<ProductOperationResult>, SoftchatError>

Recover every ready attachment-dependent message after process death.

Errors

Returns a stable media, messaging, relay, or persistence error.

pub fn recover_pending_asset_replacements( &self, limit: u32, now: i64, ) -> Result<Vec<ProductOperationResult>, SoftchatError>

Recover every ready upload-dependent asset replacement after process death.

Guide

Errors

Returns a stable media, profile, subject, relay, or persistence error.

pub fn claim_media_operation( &self, operation_id: String, lease_id: String, now: i64, lease_duration_seconds: u32, ) -> Result<Option<AccountMediaLease>, SoftchatError>

Claim one exact recoverable media operation with a bounded lease.

Expired leases are recovered transactionally before selection.

Errors

Returns a stable media-operation or persistence error.

pub fn finish_media_operation_lease( &self, operation_id: String, lease_id: String, retryable: bool, error_category: String, now: i64, ) -> Result<AccountMediaOperation, SoftchatError>

Finish one matching media lease with a redacted failure category.

Errors

Returns a stable media-operation or persistence error.

pub fn create_media_upload_authorization( &self, method: String, url: String, payload_sha256: String, now: i64, ) -> Result<FfiHttpAuthorizationPlan, SoftchatError>

Create a signed NIP-98 upload plan from a streaming SHA-256.

Android executes the exact HTTP request and must mint a new plan after any redirect.

Errors

Returns a stable HTTP, hash, timestamp, or account lifecycle error.

pub fn transition_media_operation( &self, operation_id: String, transition: String, error_category: String, now: i64, ) -> Result<AccountMediaOperation, SoftchatError>

Apply one retry/failure/cancel transition to logical media state.

Errors

Returns a stable media transition or persistence error.

pub fn message_downloads( &self, message_id: String, ) -> Result<Vec<AccountMediaOperation>, SoftchatError>

Return existing downloads for the current attachments of one live message, in attachment order.

This read creates no operation, changes no revision and schedules no work. Unknown or deleted messages return an empty result; unrelated recent transfers cannot hide a cached attachment.

Errors

Returns a stable ID, account, or persistence error.

pub fn media_operations( &self, limit: u32, ) -> Result<Vec<AccountMediaOperation>, SoftchatError>

Return a bounded newest-update-first media-operation page.

Errors

Returns a stable bound or persistence error.

pub fn media_operations_by_ids( &self, operation_ids: Vec<String>, ) -> Result<Vec<AccountMediaOperation>, SoftchatError>

Return existing logical media operations for one bounded exact ID set.

Results preserve caller order. Missing IDs are omitted, while duplicate, malformed, or oversized input fails before any row is returned.

Errors

Returns a stable bound, media-operation, or persistence error.

pub fn recoverable_media_operations( &self, cursor: Option<String>, limit: u32, ) -> Result<AccountMediaOperationPage, SoftchatError>

Return one stable ID-ordered page of non-terminal media operations.

Platform executors must follow next_cursor to exhaustion during startup recovery instead of assuming that a newest-first UI page contains every durable operation.

Errors

Returns a stable cursor, bound, media-operation, or persistence error.

pub fn media_operation( &self, operation_id: String, ) -> Result<Option<AccountMediaOperation>, SoftchatError>

Return one exact logical media operation.

Errors

Returns a stable media-operation or persistence error.

pub fn database_info(&self) -> Result<AccountDatabaseInfo, SoftchatError>

Return schema, revision, and WAL information.

Errors

Returns a stable persistence error if metadata cannot be read.

pub fn account_diagnostics(&self) -> Result<AccountDiagnostics, SoftchatError>

Return redacted bounded account health for support and recovery UI.

Errors

Returns a stable persistence error.

pub fn reset_account_sync( &self, now: i64, ) -> Result<AccountTransportBatch, SoftchatError>

Forget durable synchronization checkpoints while retaining event truth.

The active platform transport must be restarted after this call so its next Rust-owned synchronization begins from complete retained history.

Errors

Returns a stable sync or persistence error.

pub fn start_account_transport( &self, run_id: String, ) -> Result<AccountTransportBatch, SoftchatError>

Start one correlated Rust-owned account transport run.

A host using the low-level boundary executes only the returned WebSocket actions. A second active run must be explicitly cancelled first.

Errors

Returns a stable account, relay, filter, or lifecycle error.

pub fn apply_account_transport_result( &self, transport_result: AccountTransportResult, now: i64, ) -> Result<AccountTransportBatch, SoftchatError>

Apply one exact correlated system result idempotently.

Repeating the same result returns the originally committed action batch. A conflicting reuse or unknown action fails closed without consuming the active run. If an otherwise valid transition cannot commit, its database work is rolled back and the process-local run is retired; the host must start a fresh run.

Errors

Returns a stable system-action, relay, delivery, ingestion, or persistence error.

pub fn wake_account_transport( &self, now: i64, ) -> Result<AccountTransportBatch, SoftchatError>

Recheck durable outgoing work without waiting for the current receive deadline.

Android calls this after observing a newer durable account revision. Existing receive actions remain correlated and active; only newly available ordered effects are returned.

Errors

Returns a stable lifecycle, delivery, relay, or persistence error.

pub fn cancel_account_transport( &self, ) -> Result<AccountTransportBatch, SoftchatError>

Cancel the active account transport and release unfinished leases.

Errors

Returns a stable lifecycle, delivery, or persistence error.

pub fn ingest( &self, events: Vec<SignedEvent>, received_at: i64, ) -> Result<StoredIngestion, SoftchatError>

Authenticate and atomically persist one bounded incoming batch.

Errors

Returns stable event, envelope, projection, account, or persistence errors. No partial transaction is committed.

pub fn ingest_event_jsons( &self, event_jsons: Vec<String>, received_at: i64, ) -> Result<StoredIngestion, SoftchatError>

Parse, authenticate, unwrap, and commit a bounded system event batch.

This is the Android push/notification boundary. Product code receives only authored message and conversation values, never raw Nostr types.

Errors

Returns a stable event, envelope, account, projection, or persistence error with no partial commit.

pub fn enqueue_rumor( &self, operation_id: String, rumor: RumorEvent, recipients: Vec<String>, notification_recipients: Vec<String>, relay_urls: Vec<String>, kind: Nip59EnvelopeKind, now: i64, ) -> Result<AccountOperationResult, SoftchatError>

Create and atomically enqueue one private rumor operation.

Errors

Returns stable identity, event, envelope, account, relay, delivery, or persistence errors.

pub fn media_upload_url(&self) -> Result<String, SoftchatError>

Return the effective HTTPS upload endpoint for this account.

A validated explicit account setting wins. Otherwise the endpoint is derived from the selected relay host using the released /api/v2/files profile. Android does not duplicate this policy.

Errors

Returns a stable settings, relay-catalog, or HTTP-authorization error.

pub fn enqueue_signed( &self, operation_id: String, events: Vec<SignedEvent>, relay_urls: Vec<String>, now: i64, ) -> Result<AccountOperationResult, SoftchatError>

Atomically enqueue already signed direct protocol events.

Errors

Returns stable identity, event, account, relay, or persistence errors.

pub fn recover_signed_outbox_batch( &self, operation_id: String, event_batch_json: String, now: i64, ) -> Result<AccountOperationResult, SoftchatError>

Verify and recover one bounded JSON array of already signed events.

This narrow migration boundary lets a platform extract an opaque batch from retired storage without decoding protocol fields. Every event ID and signature is verified before one idempotent outgoing transaction is committed. The caller retains and owns the retired storage.

Errors

Returns stable event, operation, relay, timestamp, or persistence errors. Malformed, empty, oversized, duplicate, or forged batches commit nothing.

pub fn claim_deliveries( &self, lease_id: String, relay_url: String, now: i64, lease_duration_seconds: u32, ) -> Result<Option<ClaimedDelivery>, SoftchatError>

Atomically claim bounded relay work and return exact payloads.

Errors

Returns a stable delivery or persistence error.

pub fn mark_socket_written( &self, claim: DeliveryClaim, intent_ids: Vec<String>, ) -> Result<AccountMutationResult, SoftchatError>

Persist that selected lease payloads were written to a socket.

Errors

Returns a stable delivery or persistence error for stale state.

pub fn apply_relay_results( &self, claim: DeliveryClaim, results: Vec<RelayDeliveryResult>, ) -> Result<AccountMutationResult, SoftchatError>

Persist correlated relay outcomes.

Errors

Returns a stable delivery or persistence error for stale state.

pub fn release_claim( &self, claim: DeliveryClaim, ) -> Result<AccountMutationResult, SoftchatError>

Release unfinished work after transport loss or cancellation.

Errors

Returns a stable delivery or persistence error for stale state.

pub fn operation( &self, operation_id: String, ) -> Result<OperationSnapshot, SoftchatError>

Return one durable operation’s aggregate state.

Errors

Returns a stable account or persistence error for unknown state.

pub fn operation_page( &self, limit: u32, ) -> Result<Vec<OperationSnapshot>, SoftchatError>

Return a bounded newest-first page of durable outgoing operations.

Errors

Returns a stable bound, account, or persistence error.

pub fn retry_operation( &self, operation_id: String, ) -> Result<AccountOperationResult, SoftchatError>

Explicitly retry the rejected copies of one durable operation.

Errors

Returns a stable account or delivery-state error.

pub fn cancel_operation( &self, operation_id: String, ) -> Result<AccountOperationResult, SoftchatError>

Cancel every unclaimed copy that is still safe to cancel.

Errors

Returns a stable account or delivery-state error.

pub fn relay_catalog(&self) -> Result<Vec<RelayCatalogEntry>, SoftchatError>

Return the complete durable relay catalog.

Errors

Returns a stable relay-catalog or persistence error.

pub fn inbox_filters( &self, since_timestamp: Option<i64>, ) -> Result<Vec<String>, SoftchatError>

Return the canonical authenticated inbox filter for this account.

Android passes the returned JSON directly to crate::RelaySession. The filter accepts durable and ephemeral NIP-59 gift wraps addressed to the account. An optional lower bound supports live subscriptions without making Android construct or validate protocol JSON.

Errors

Returns a stable filter or timestamp error.

pub fn reconcile_account_relays( &self, discovered: Vec<DnsRelayRecord>, refreshed_at: i64, fallback_url: String, dns_authenticated: bool, ) -> Result<StoredRelayCatalogPlan, SoftchatError>

Reconcile and atomically persist authenticated relay discovery.

Errors

Returns a stable relay-catalog or persistence error.

pub fn add_account_relay( &self, relay_url: String, created_at: i64, ) -> Result<RelayCatalogMutation, SoftchatError>

Add and atomically persist one custom relay.

Errors

Returns a stable relay-catalog or persistence error.

pub fn exclude_account_relay( &self, relay_url: String, now: i64, ) -> Result<RelayCatalogMutation, SoftchatError>

Exclude and atomically persist one relay.

Errors

Returns a stable relay-catalog or persistence error.

pub fn restore_account_relays( &self, now: i64, ) -> Result<RelayCatalogMutation, SoftchatError>

Restore and atomically persist automatic relays.

Errors

Returns a stable relay-catalog or persistence error.

pub fn set_account_active_relay( &self, relay_url: String, now: i64, ) -> Result<RelayCatalogMutation, SoftchatError>

Select and atomically persist one active relay.

Errors

Returns a stable relay-catalog or persistence error.

pub fn account_relay_failover_candidates( &self, failed_url: String, ) -> Result<Vec<String>, SoftchatError>

Return failover candidates from durable relay state.

Errors

Returns a stable relay-catalog or persistence error.

pub fn rotate_failed_account_relay( &self, failed_url: String, now: i64, ) -> Result<RelayFailoverMutation, SoftchatError>

Atomically select the next relay and rebind unfinished work.

Errors

Returns a stable catalog, delivery-state, or persistence error.

pub fn list_conversations( &self, limit: u32, offset: u32, ) -> Result<Vec<ConversationSummary>, SoftchatError>

Return a bounded newest-first conversation page.

Errors

Returns a stable account or persistence error.

pub fn list_conversation_views( &self, limit: u32, offset: u32, ) -> Result<Vec<ConversationView>, SoftchatError>

Return complete bounded conversation-list use cases in one native call.

Errors

Returns a stable account or persistence error.

pub fn list_messages( &self, conversation_id: String, before_created_at: Option<i64>, limit: u32, ) -> Result<Vec<AccountMessage>, SoftchatError>

Return a bounded newest-first message page.

Errors

Returns a stable account or persistence error.

pub fn list_projections( &self, kind: Option<ProjectionKind>, logical_event_id: String, conversation_id: String, target_event_id: String, author_public_key: String, before_created_at: Option<i64>, limit: u32, offset: u32, ) -> Result<Vec<AccountProjection>, SoftchatError>

Return a bounded newest-first authenticated projection page.

Empty string filters are ignored.

Errors

Returns a stable account, event, or persistence error.

pub fn list_event_nodes( &self, kind: Option<ProjectionKind>, logical_event_id: String, conversation_id: String, target_event_id: String, author_public_key: String, before_created_at: Option<i64>, limit: u32, offset: u32, ) -> Result<Vec<AccountEventNode>, SoftchatError>

Return bounded authenticated projections with use-case state.

Errors

Returns a stable account, event, or persistence error.

pub fn list_known_public_keys( &self, limit: u32, offset: u32, ) -> Result<Vec<String>, SoftchatError>

Return bounded canonical public keys known to authenticated state.

Errors

Returns a stable account or persistence error.

pub fn put_local_contact( &self, contact: LocalContactRecord, ) -> Result<AccountMutationResult, SoftchatError>

Insert or replace one bounded Android-local contact.

Errors

Returns a stable account or persistence error.

pub fn remove_local_contact( &self, public_key: String, ) -> Result<AccountMutationResult, SoftchatError>

Remove one Android-local contact idempotently.

Errors

Returns a stable account or persistence error.

pub fn local_contacts( &self, limit: u32, offset: u32, ) -> Result<Vec<LocalContactRecord>, SoftchatError>

Return a bounded stable page of Android-local contacts.

Errors

Returns a stable account or persistence error.

pub fn replace_stickers( &self, stickers: Vec<StickerRecord>, ) -> Result<AccountMutationResult, SoftchatError>

Replace the complete bounded account sticker cache.

Errors

Returns a stable account or persistence error.

pub fn stickers(&self) -> Result<Vec<StickerRecord>, SoftchatError>

Return the complete bounded account sticker cache.

Errors

Returns a stable persistence error.

pub fn put_link_preview( &self, preview: LinkPreviewRecord, ) -> Result<AccountMutationResult, SoftchatError>

Insert or replace one account link-preview cache result.

Errors

Returns a stable account or persistence error.

pub fn link_preview( &self, url: String, ) -> Result<Option<LinkPreviewRecord>, SoftchatError>

Return one account link-preview cache result.

Errors

Returns a stable account or persistence error.

pub fn clear_account(&self) -> Result<AccountMutationResult, SoftchatError>

Clear every account-owned durable row and process-local coordinator.

The account binding and revision remain valid. Settings and relay catalog return to safe defaults. Active sync engines, transport state, and authored typing state are discarded only after SQLite commits.

Errors

Returns a stable persistence error.

pub fn event_json(&self, event_id: String) -> Result<String, SoftchatError>

Return exact canonical signed-event JSON by ID.

Errors

Returns a stable event or persistence error.

pub fn event_jsons( &self, event_ids: Vec<String>, ) -> Result<Vec<StoredEventJson>, SoftchatError>

Return exact canonical JSON for bounded synchronization resend IDs.

Errors

Returns a stable event, account, or persistence error.

pub fn sync_fingerprints( &self, since_timestamp: Option<i64>, until_timestamp: i64, limit: u32, ) -> Result<Vec<NegentropyItem>, SoftchatError>

Load a bounded Rust-owned synchronization fingerprint snapshot.

Errors

Returns a stable sync or persistence error.

pub fn sync_checkpoint( &self, sync_id: String, ) -> Result<Option<i64>, SoftchatError>

Return a durable synchronization checkpoint, when present.

Errors

Returns a stable sync or persistence error.

pub fn save_sync_checkpoint( &self, sync_id: String, checkpoint_timestamp: i64, now: i64, ) -> Result<AccountMutationResult, SoftchatError>

Commit one synchronization checkpoint and increment account revision.

Errors

Returns a stable sync or persistence error.

pub fn start_sync( &self, sync_id: String, neg_subscription_id: String, event_subscription_id: String, now: i64, overlap_seconds: u32, frame_size_limit: u64, ) -> Result<SyncAction, SoftchatError>

Start one sync and return its first transport action.

Fingerprint snapshot loading is completed inside Rust before this method returns, so Android never receives a database action.

Errors

Returns a stable sync, Negentropy, or persistence error.

pub fn reconcile_sync( &self, sync_id: String, subscription_id: String, message: Vec<u8>, frame_size_limit: u64, ) -> Result<Vec<SyncAction>, SoftchatError>

Consume one correlated NEG-MSG and return transport-only actions.

Errors

Returns a stable sync, Negentropy, or persistence error.

pub fn receive_sync_frame( &self, sync_id: String, frame_json: String, frame_size_limit: u64, ) -> Result<Option<Vec<SyncAction>>, SoftchatError>

Route one complete relay text frame to Negentropy when applicable.

Ordinary Nostr relay frames return None and must be passed to RelaySession.receive. Correlated NEG-MSG is parsed, bounded, and reconciled entirely in Rust.

Errors

Returns a stable sync error for malformed, stale, or relay-error frames.

pub fn ingest_sync_events( &self, sync_id: String, subscription_id: String, events: Vec<SignedEvent>, received_at: i64, ) -> Result<StoredIngestion, SoftchatError>

Authenticate and commit requested sync events before marking progress.

Errors

Returns a stable sync, event, envelope, projection, or persistence error. Sync state does not advance unless the database commits.

pub fn finish_sync_fetch( &self, sync_id: String, subscription_id: String, frame_size_limit: u64, ) -> Result<Vec<SyncAction>, SoftchatError>

Finish a requested-event subscription after every event committed.

Errors

Returns a stable sync, Negentropy, or persistence error.

pub fn sync_resend_payloads( &self, event_ids: Vec<String>, ) -> Result<Vec<StoredEventJson>, SoftchatError>

Return exact locally stored payloads requested by a resend action.

Errors

Returns a stable event, account, or persistence error.

pub fn sync_snapshot( &self, sync_id: String, ) -> Result<SyncEngineSnapshot, SoftchatError>

Return one active synchronization snapshot.

Errors

Returns a stable sync error for an unknown ID.

pub fn cancel_sync( &self, sync_id: String, ) -> Result<SyncEngineSnapshot, SoftchatError>

Cancel and remove one active synchronization coordinator.

Errors

Returns a stable sync error for an unknown ID.

Trait Implementations

impl Debug for AccountRuntimeHandle

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for AccountRuntimeHandle

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<UT> LiftRef<UT> for AccountRuntimeHandle

type LiftType = Arc<AccountRuntimeHandle>

impl<UT> LowerError<UT> for AccountRuntimeHandle

fn lower_error(obj: Self) -> RustBuffer

Lower this value for scaffolding function return

impl<UT> LowerReturn<UT> for AccountRuntimeHandle

type ReturnType = <Arc<AccountRuntimeHandle> as LowerReturn<UniFfiTag>>::ReturnType

The type that should be returned by scaffolding functions for this type.

fn lower_return(obj: Self) -> Result<Self::ReturnType, RustCallError>

Lower the return value from an scaffolding call

fn handle_failed_lift( error: LiftArgsError, ) -> Result<Self::ReturnType, RustCallError>

Lower the return value for failed argument lifts

impl<UT> TypeId<UT> for AccountRuntimeHandle

const TYPE_ID_META: MetadataBuffer