Public types - Offline Protocol

These declarations match the published v0.27.0 package. See methods, events and configuration defaults for semantics. Standard TypeScript and React Native types retain their upstream definitions.

MessagePriority

export enum MessagePriority {
  Low = 0,
  Medium = 1,
  High = 2,
  Critical = 3,
}

ProtocolState

export enum ProtocolState {
  Stopped = "Stopped",
  Running = "Running",
  Paused = "Paused",
}

AckConfig

export interface AckConfig {
  defaultTimeoutMs?: number;
  maxPendingAcks?: number;
}

RetryConfig

export interface RetryConfig {
  maxRetries?: number;
  initialDelayMs?: number;
  maxDelayMs?: number;
  backoffMultiplier?: number;
  outboxMaxLifetimeMs?: number;
  pendingMessageMaxLifetimeMs?: number;
  edgeDrivenUnreachableDm?: boolean;
}

DedupConfig

export interface DedupConfig {
  maxTrackedMessages?: number;
  retentionTimeSecs?: number;
}

MeshRelayConfig

export interface MeshRelayConfig {
  maxTtl?: number;
  denseMaxTtl?: number;
  denseDegree?: number;
  fanout?: number;
  jitterMinMs?: number;
  jitterMaxMs?: number;
  ratePerSec?: number;
  burst?: number;
  peerRatePerSec?: number;
  peerBurst?: number;
  queueCapacity?: number;
  biasMinScale?: number;
  biasMaxHandicapMs?: number;
  activityWindowMs?: number;
  activityMinForwards?: number;
  activityIdleWindows?: number;
}

MeshRelayTunables

export interface MeshRelayTunables {
  maxTtl: number;
  denseMaxTtl: number;
  denseDegree: number;
  fanout: number;
  jitterMinMs: number;
  jitterMaxMs: number;
  ratePerSec: number;
  burst: number;
  peerRatePerSec: number;
  peerBurst: number;
  queueCapacity: number;
  biasMinScale: number;
  biasMaxHandicapMs: number;
  activityWindowMs: number;
  activityMinForwards: number;
  activityIdleWindows: number;
}

MeshRelayStats

export interface MeshRelayStats {
  forwarded: number;
  transmissions: number;
  queued: number;
  awaitingTransmission: number;
  duplicatesSuppressed: number;
  coveredByANeighbor: number;
  peerRateLimited: number;
  refusedQueueFull: number;
  rateDeferred: number;
  abandonedOverdue: number;
  hopLimitReached: number;
  reachClamped: number;
  droppedForCapacity: number;
}

DedupStats

export interface DedupStats {
  totalTracked: number;
  recentTracked: number;
  capacityUsedPercent: number;
  mode: string;
}

ReliabilityConfig

export interface ReliabilityConfig {
  ack?: AckConfig;
  retry?: RetryConfig;
  dedup?: DedupConfig;
}

RelayPriority

export type RelayPriority = 'never' | 'auto' | 'always';

RelayConfig

export interface RelayConfig {
  allowRelay?: boolean;
  minBatteryForRelay?: number;
  relayPriority?: RelayPriority;
}

NetworkConfig

export interface NetworkConfig {
  initialTtl?: number;
}

BleTransportConfig

export interface BleTransportConfig {
  enabled: boolean;
}

InternetTransportConfig

export interface InternetTransportConfig {
  enabled: boolean;
  serverAddress?: string;
  autoReconnect?: boolean;
  reconnectDelay?: number;
  authToken?: string;
}

WifiDirectTransportConfig

export interface WifiDirectTransportConfig {
  enabled: boolean;
  deviceName?: string;
  autoAccept?: boolean;
  groupOwnerIntent?: number;
}

ReticulumTransportConfig

export interface ReticulumTransportConfig {
  enabled: boolean;
  daemonAddress?: string;
  autoReconnect?: boolean;
  maxReconnectAttempts?: number;
}

NostrTransportConfig

export interface NostrTransportConfig {
  enabled: boolean;
  relayUrls?: string[];
  connectionTimeout?: number;
  autoReconnect?: boolean;
  reconnectDelay?: number;
  maxReconnectAttempts?: number;
  sealingEnabled?: boolean;
  coldContactEnabled?: boolean;
  usernameDiscoveryEnabled?: boolean;
}

ContentType

export enum ContentType {
  Text = 'text',
  Image = 'image',
  Video = 'video',
  Audio = 'audio',
  VoiceNote = 'voice_note',
  VideoNote = 'video_note',
  File = 'file',
  FileChunk = 'file_chunk',
  Poll = 'poll',
}

MediaMetadata

export interface MediaMetadata {
  mimeType: string;
  fileName: string;
  fileSize: number;
  durationMs?: number;
  width?: number;
  height?: number;
  thumbnailBase64?: string;
  mediaId?: string;
  downloadUrl?: string;
  thumbnailUrl?: string;
  encryptionKey?: string;
  iv?: string;
  ciphertextHash?: string;
  stickerProvider?: string;
  stickerRemoteId?: string;
  stickerKind?: string;
}

FileTransferConfig

export interface FileTransferConfig {
  chunkSize?: number;
  maxFileSize?: number;
}

FileProgress

export interface FileProgress {
  file_id: string;
  chunks_sent: number;
  total_chunks: number;
  percentage: number;
}

TransportsConfig

export interface TransportsConfig {
  ble?: BleTransportConfig;
  internet?: InternetTransportConfig;
  wifiDirect?: WifiDirectTransportConfig;
  reticulum?: ReticulumTransportConfig;
  nostr?: NostrTransportConfig;
}

EncryptionConfig

export interface EncryptionConfig {
  enabled?: boolean;
  autoKeyExchange?: boolean;
  storePending?: boolean;
  requireEncryption?: boolean;
  compactEnvelopeEnabled?: boolean;
  richPayloadEnabled?: boolean;
  cryptoRecoveryEnabled?: boolean;
  pendingQueue?: PendingQueueConfig;
}

OverflowPolicy

export type OverflowPolicy = 'drop_oldest' | 'drop_newest';

PendingQueueConfig

export interface PendingQueueConfig {
  maxPendingPerPeer?: number;
  maxPendingGlobal?: number;
  pendingTtlMs?: number;
  overflowPolicy?: OverflowPolicy;
}

DataConfig

export interface DataConfig {
  enabled?: boolean;
}

ProtocolConfig

export interface ProtocolConfig {
  appId: string;
  profile: string;
  transports?: TransportsConfig;
  binaryWireEnabled?: boolean;
  fileTransfer?: FileTransferConfig;
  encryption?: EncryptionConfig;
  group?: {
    maxGroupMembers?: number;
    relayEnabled?: boolean;
    relayBroadcastEnabled?: boolean;
    enforceAdminCommits?: boolean;
  };
  dors?: {
    preferOnline?: boolean;
    switchHysteresis?: number;
    switchCooldownSecs?: number;
    bleToWifiRetryThreshold?: number;
    minSuccessRateBeforeEscalation?: number;
    minBleSamplesBeforeSuccessRateEscalation?: number;
    rssiSwitchThreshold?: number;
    congestionQueueThreshold?: number;
    stabilityWindowSecs?: number;
    poorSignalDurationSecs?: number;
    ttlEscalationThreshold?: number;
    congestionDurationSecs?: number;
    ttlEscalationHoldSecs?: number;
    historyWindowSize?: number;
    queueRecoveryRatio?: number;
    lowBatteryThreshold?: number;
    relayMinBatteryLevel?: number;
    relayOptimalConnectionCount?: number;
  };
  meshRelay?: MeshRelayConfig;
  relay?: RelayConfig;
  network?: NetworkConfig;
  reliability?: ReliabilityConfig;
  data?: DataConfig;
  security?: SecurityConfig;
  controlFreshnessEnforced?: boolean;
}

SecurityConfig

export interface SecurityConfig {
  controlFreshnessEnforced?: boolean;
}

TransportType

export type TransportType = 'ble' | 'internet' | 'wifiDirect' | 'reticulum' | 'nostr';

ForwardInfo

export interface ForwardInfo {
  original_sender: string;
  original_message_id: string;
  original_timestamp: number;
  forward_count: number;
}

ReplyContext

export interface ReplyContext {
  sender: string;
  text: string;
  timestamp?: number;
  reply_media_label?: string;
  reply_content_type?: string;
}

MediaMetadataEvent

export interface MediaMetadataEvent {
  mime_type?: string;
  file_name?: string;
  file_size?: number;
  duration_ms?: number;
  width?: number;
  height?: number;
  thumbnail_base64?: string;
  media_id?: string;
  download_url?: string;
  thumbnail_url?: string;
  encryption_key?: string;
  iv?: string;
  ciphertext_hash?: string;
  sticker_provider?: string;
  sticker_remote_id?: string;
  sticker_kind?: string;
}

ForwardMessageParams

export interface ForwardMessageParams {
  originalMessageJson: string;
  newRecipient: string;
  priority?: MessagePriority;
}

ForwardMessageToGroupParams

export interface ForwardMessageToGroupParams {
  originalMessageJson: string;
  groupId: string;
  priority?: MessagePriority;
}

SendMessageParams

export interface SendMessageParams {
  recipient: string;
  content: string;
  priority?: MessagePriority;
  replyToMsg?: string;
  contentType?: ContentType;
  replyContext?: ReplyContext;
  mediaMetadata?: MediaMetadata;
  forwardInfo?: ForwardInfo;
}

SendConnectionRequestParams

export interface SendConnectionRequestParams {
  recipient: string;
  senderName: string;
  keyPackage?: number[];
  initialMessage?: string;
}

AcceptConnectionRequestParams

export interface AcceptConnectionRequestParams {
  recipient: string;
  accepterName: string;
  keyPackage?: number[];
}

RejectConnectionRequestParams

export interface RejectConnectionRequestParams {
  recipient: string;
}

CancelConnectionRequestParams

export interface CancelConnectionRequestParams {
  recipient: string;
}

SendMediaParams

export interface SendMediaParams {
  recipient: string;
  fileData: string;
  fileName: string;
  contentType: ContentType;
  mediaMetadata?: MediaMetadata;
  caption?: string;
  replyToMsg?: string;
  replyContext?: ReplyContext;
  forwardInfo?: ForwardInfo;
  fileId?: string;
}

SendFileParams

export interface SendFileParams {
  recipient: string;
  fileData: string;
  fileName: string;
}

MessageSentEvent

export interface MessageSentEvent extends BaseEvent {
  type: 'message_sent';
  message_id: string;
  sender: string;
  recipient: string;
  content: string;
  priority: 'low' | 'medium' | 'high' | 'critical';
  requires_ack: boolean;
  timestamp: number;
  lamport_clock: number;
  forward_info?: ForwardInfo;
}

MessageReceivedEvent

export interface MessageReceivedEvent extends BaseEvent {
  type: 'message_received';
  message_id: string;
  sender: string;
  recipient: string;
  content: string;
  hop_count: number;
  transport: string;
  timestamp: number;
  lamport_clock: number;
  encrypted?: boolean;
  reply_to_msg?: string;
  reply_context?: ReplyContext;
  content_type?: string;
  media_metadata?: MediaMetadataEvent;
  forward_info?: ForwardInfo;
}

MessageDeliveredEvent

export interface MessageDeliveredEvent extends BaseEvent {
  type: 'message_delivered';
  message_id: string;
  latency_ms: number;
  hop_count: number;
  transport: string;
}

MessageFailedEvent

export interface MessageFailedEvent extends BaseEvent {
  type: 'message_failed';
  message_id: string;
  reason: string;
  retry_count: number;
}

DecryptionFailureCode

export type DecryptionFailureCode =
  | 'INVALID_PAYLOAD'
  | 'NOT_INITIALIZED'
  | 'INVALID_CIPHERTEXT'
  | 'IDENTITY_MISMATCH'
  | 'CRYPTO_FAILURE'
  | 'PENDING_QUEUE_DROPPED'
  | 'UNKNOWN';

MessageDecryptionFailedEvent

export interface MessageDecryptionFailedEvent extends BaseEvent {
  type: 'message_decryption_failed';
  message_id: string;
  sender: string;
  code: DecryptionFailureCode;
  reason: string;
}

TransportSwitchedEvent

export interface TransportSwitchedEvent extends BaseEvent {
  type: 'transport_switched';
  from: string | null;
  to: string;
  reason: string;
}

RelayPromotedEvent

export interface RelayPromotedEvent extends BaseEvent {
  type: 'relay_promoted';
  connection_count: number;
  battery_level: number | null;
}

RelayDemotedEvent

export interface RelayDemotedEvent extends BaseEvent {
  type: 'relay_demoted';
  reason: string;
}

RelayDemotedBatteryEvent

export interface RelayDemotedBatteryEvent extends BaseEvent {
  type: 'relay_demoted_battery';
  battery_level: number;
  min_required: number;
}

NeighborDiscoveredEvent

export interface NeighborDiscoveredEvent extends BaseEvent {
  type: 'neighbor_discovered';
  peer_id: string;
  transport: string;
  rssi?: number;
}

NeighborLostEvent

export interface NeighborLostEvent extends BaseEvent {
  type: 'neighbor_lost';
  peer_id: string;
}

IdentityReadyEvent

export interface IdentityReadyEvent extends BaseEvent {
  type: 'identity_ready';
  address: string;
}

NetworkMetricsEvent

export interface NetworkMetricsEvent extends BaseEvent {
  type: 'network_metrics';
  neighbor_count: number;
  relay_count: number;
  delivery_ratio: number;
  avg_latency_ms: number;
}

FileProgressEvent

export interface FileProgressEvent extends BaseEvent {
  type: 'file_progress';
  file_id: string;
  chunks_sent: number;
  total_chunks: number;
  percentage: number;
}

FileReceivedEvent

export interface FileReceivedEvent extends BaseEvent {
  type: 'file_received';
  file_id: string;
  file_name: string;
  file_size: number;
  sender: string;
  content_type: string;
  media_metadata?: MediaMetadataEvent;
  file_data: string;
  timestamp?: number;
  caption?: string;
  reply_to_msg?: string;
  reply_context?: ReplyContext;
  forward_info?: ForwardInfo;
}

FileReceiveFailedEvent

export interface FileReceiveFailedEvent extends BaseEvent {
  type: 'file_receive_failed';
  file_id: string;
  file_name: string;
  sender: string;
  reason: string;
}

MediaSentEvent

export interface MediaSentEvent extends BaseEvent {
  type: 'media_sent';
  file_id: string;
  content_type: string;
  recipient: string;
}

MediaSendFailedEvent

export interface MediaSendFailedEvent extends BaseEvent {
  type: 'media_send_failed';
  file_id: string;
  recipient: string;
  reason: string;
}

AckEvictedEvent

export interface AckEvictedEvent extends BaseEvent {
  type: 'ack_evicted';
  message_id: string;
  priority: string;
  reason: string;
}

FragmentAssemblyEvictedEvent

export interface FragmentAssemblyEvictedEvent extends BaseEvent {
  type: 'fragment_assembly_evicted';
  message_id: string;
  completion_percent: number;
  reason: string;
}

DiagnosticEvent

export interface DiagnosticEvent extends BaseEvent {
  type: 'diagnostic';
  level: 'info' | 'warning' | 'error';
  message: string;
  context?: Record<string, unknown>;
}

SecureSessionEstablishedEvent

export interface SecureSessionEstablishedEvent extends BaseEvent {
  type: 'secure_session_established';
  peer_id: string;
  group_id: string;
  is_session: boolean;
  initiated_by_local: boolean;
}

SecureSessionFailedEvent

export interface SecureSessionFailedEvent extends BaseEvent {
  type: 'secure_session_failed';
  peer_id: string;
  reason: string;
}

ConvergenceDiagEvent

export interface ConvergenceDiagEvent extends BaseEvent {
  type: 'convergence_diag';
  stage: string;
  peer_id: string;
  detail: string;
}

WelcomeReasonCode

export type WelcomeReasonCode =
  | 'TRANSPORT_UNAVAILABLE'
  | 'PEER_UNREACHABLE'
  | 'PEER_DISCONNECTED'
  | 'TIMEOUT'
  | 'INTERNAL_ERROR'
  | 'RETRY_EXHAUSTED';

WelcomeSendAttemptedEvent

export interface WelcomeSendAttemptedEvent extends BaseEvent {
  type: 'welcome_send_attempted';
  peer_id: string;
  message_id: string;
  group_id: string;
  attempt: number;
}

WelcomeSendSucceededEvent

export interface WelcomeSendSucceededEvent extends BaseEvent {
  type: 'welcome_send_succeeded';
  peer_id: string;
  message_id: string;
  group_id: string;
  attempt: number;
}

WelcomeSendFailedEvent

export interface WelcomeSendFailedEvent extends BaseEvent {
  type: 'welcome_send_failed';
  peer_id: string;
  message_id: string;
  group_id: string;
  attempt: number;
  reason_code: WelcomeReasonCode;
  transport_error?: string;
  retryable: boolean;
  next_retry_at?: number;
}

WelcomeSendExpiredEvent

export interface WelcomeSendExpiredEvent extends BaseEvent {
  type: 'welcome_send_expired';
  peer_id: string;
  message_id: string;
  attempt: number;
  reason_code: WelcomeReasonCode;
}

ConnectionRequestReceivedEvent

export interface ConnectionRequestReceivedEvent extends BaseEvent {
  type: 'connection_request_received';
  sender: string;
  sender_name: string;
  timestamp: number;
  key_package?: number[];
  initial_message?: string;
}

ConnectionRequestUndeliverableEvent

export interface ConnectionRequestUndeliverableEvent extends BaseEvent {
  type: 'connection_request_undeliverable';
  recipient: string;
  message_id: string;
  reason: string;
}

ConnectionAcceptedEvent

export interface ConnectionAcceptedEvent extends BaseEvent {
  type: 'connection_accepted';
  accepted_by: string;
  accepted_by_name: string;
  timestamp: number;
  key_package?: number[];
}

ConnectionRejectedEvent

export interface ConnectionRejectedEvent extends BaseEvent {
  type: 'connection_rejected';
  rejected_by: string;
}

ConnectionRequestCancelledEvent

export interface ConnectionRequestCancelledEvent extends BaseEvent {
  type: 'connection_request_cancelled';
  cancelled_by: string;
}

GroupCreatedEvent

export interface GroupCreatedEvent extends BaseEvent {
  type: 'group_created';
  group_id: string;
  name: string;
}

GroupMessageReceivedEvent

export interface GroupMessageReceivedEvent extends BaseEvent {
  type: 'group_message_received';
  group_id: string;
  sender: string;
  content: string;
  timestamp: string;
  message_id: string;
  reply_to_msg?: string;
  forward_info?: ForwardInfo;
  media_metadata?: MediaMetadataEvent;
  content_type?: string;
}

GroupMemberAddedEvent

export interface GroupMemberAddedEvent extends BaseEvent {
  type: 'group_member_added';
  group_id: string;
  user_id: string;
  added_by: string;
  group_name?: string;
  authorized?: boolean;
}

GroupMemberRemovedEvent

export interface GroupMemberRemovedEvent extends BaseEvent {
  type: 'group_member_removed';
  group_id: string;
  user_id: string;
  removed_by: string;
  authorized?: boolean;
}

GroupInfoMemberEvent

export interface GroupInfoMemberEvent {
  user_id: string;
  role: string;
  joined_at: string;
}

GroupInfoEvent

export interface GroupInfoEvent extends BaseEvent {
  type: 'group_info';
  group_id: string;
  name: string;
  created_by: string;
  created_at: string;
  members: GroupInfoMemberEvent[];
}

UserGroupSummaryEvent

export interface UserGroupSummaryEvent {
  group_id: string;
  name: string;
  created_at: string;
}

UserGroupsEvent

export interface UserGroupsEvent extends BaseEvent {
  type: 'user_groups';
  groups: UserGroupSummaryEvent[];
}

GroupErrorEvent

export interface GroupErrorEvent extends BaseEvent {
  type: 'group_error';
  reason: 'not_found' | 'sync_denied' | 'error';
  group_id?: string;
}

GroupRelaySyncChangedEvent

export interface GroupRelaySyncChangedEvent extends BaseEvent {
  type: 'group_relay_sync_changed';
  group_id: string;
  synced: boolean;
  reason: string;
}

InviteInfo

export interface InviteInfo {
  address: string;
  public_key: number[];
  petname: string | null;
  signed: boolean;
}

UsernameClaim

export interface UsernameClaim {
  address: string;
  public_key: string;
  issued_at_ms: number;
}

UsernameResolvedEvent

export interface UsernameResolvedEvent extends BaseEvent {
  type: 'username_resolved';
  username: string;
  claims: UsernameClaim[];
  rejected: number;
  truncated: number;
}

GroupMessageSentEvent

export interface GroupMessageSentEvent extends BaseEvent {
  type: 'group_message_sent';
  group_id: string;
  message_ids: string[];
  member_count: number;
}

GroupMessagePartialFailureEvent

export interface GroupMessagePartialFailureEvent extends BaseEvent {
  type: 'group_message_partial_failure';
  group_id: string;
  failed_members: string[];
  succeeded_members: string[];
}

GroupMessageDeliveryReportEvent

export interface GroupMessageDeliveryReportEvent extends BaseEvent {
  type: 'group_message_delivery_report';
  group_id: string;
  message_id: string;
  delivered: string[];
  pushed: string[];
  missed_reissued: string[];
}

GroupRichExtrasDroppedEvent

export interface GroupRichExtrasDroppedEvent extends BaseEvent {
  type: 'group_rich_extras_dropped';
  group_id: string;
  unknown_members: string[];
}

GroupUnauthorizedMembershipChangeEvent

export interface GroupUnauthorizedMembershipChangeEvent extends BaseEvent {
  type: 'group_unauthorized_membership_change';
  group_id: string;
  committer: string;
  added: string[];
  removed: string[];
  reason: string;
  enforced: boolean;
}

GroupEpochForkDetectedEvent

export interface GroupEpochForkDetectedEvent extends BaseEvent {
  type: 'group_epoch_fork_detected';
  group_id: string;
  local_epoch?: number;
}

GroupEpochForkResolvedEvent

export interface GroupEpochForkResolvedEvent extends BaseEvent {
  type: 'group_epoch_fork_resolved';
  group_id: string;
  resolved_epoch: number;
  failed_members: string[];
}

GroupRoleChangedEvent

export interface GroupRoleChangedEvent extends BaseEvent {
  type: 'group_role_changed';
  group_id: string;
  user_id: string;
  new_role: string;
  changed_by: string;
}

GroupRenamedEvent

export interface GroupRenamedEvent extends BaseEvent {
  type: 'group_renamed';
  group_id: string;
  new_name: string;
  old_name: string | null;
  renamed_by: string;
}

ServiceDiscoveredEvent

export interface ServiceDiscoveredEvent extends BaseEvent {
  type: 'service_discovered';
  query_id: string;
  service_id: string;
  version: string;
  provider_peer_id: string;
  capabilities: Record<string, string>;
  hop_count: number;
}

ServiceRequestReceivedEvent

export interface ServiceRequestReceivedEvent extends BaseEvent {
  type: 'service_request_received';
  request_id: string;
  service_id: string;
  method: string;
  body: string;
  sender: string;
}

ServiceResponseReceivedEvent

export interface ServiceResponseReceivedEvent extends BaseEvent {
  type: 'service_response_received';
  request_id: string;
  service_id: string;
  status: string;
  body: string;
  provider_peer_id: string;
}

PresenceStatus

export type PresenceStatus = 'online' | 'away' | 'offline';

PresenceSource

export type PresenceSource = 'internet' | 'reticulum' | 'peer';

PresenceUpdatedEvent

export interface PresenceUpdatedEvent extends BaseEvent {
  type: 'presence_updated';
  peer_id: string;
  status: PresenceStatus;
  timestamp: number;
  last_seen_ms?: number;
  source: PresenceSource;
}

TypingIndicatorReceivedEvent

export interface TypingIndicatorReceivedEvent extends BaseEvent {
  type: 'typing_indicator_received';
  sender: string;
  conversation_id: string;
  is_typing: boolean;
  timestamp: number;
}

ReadReceiptReceivedEvent

export interface ReadReceiptReceivedEvent extends BaseEvent {
  type: 'read_receipt_received';
  sender: string;
  message_ids: string[];
  timestamp: number;
}

MessageRelayedEvent

export interface MessageRelayedEvent extends BaseEvent {
  type: 'message_relayed';
  message_id: string;
  sender: string;
  recipient: string;
  hop_count: number;
  remaining_ttl: number;
}

MessageDeferredEvent

export interface MessageDeferredEvent extends BaseEvent {
  type: 'message_deferred';
  message_id: string;
  recipient: string;
  reason: string;
  retry_count: number;
  next_retry_at?: number;
}

MessageRetryingEvent

export interface MessageRetryingEvent extends BaseEvent {
  type: 'message_retrying';
  message_id: string;
  recipient: string;
  retry_count: number;
  next_retry_at: number;
}

MessageUndeliverableEvent

export interface MessageUndeliverableEvent extends BaseEvent {
  type: 'message_undeliverable';
  message_id: string;
  recipient: string;
  reason: string;
  file_id?: string;
}

MediaResendRequiredEvent

export interface MediaResendRequiredEvent extends BaseEvent {
  type: 'media_resend_required';
  file_id: string;
  recipient: string;
  file_name: string;
  file_size: number;
}

DorsReasonCode

export type DorsReasonCode =
  | 'INITIAL_SELECTION'
  | 'PRIMARY_SELECTED'
  | 'PRIMARY_SUCCESS'
  | 'FALLBACK_SUCCESS'
  | 'ESCALATION_APPLIED'
  | 'CURRENT_UNAVAILABLE';

DorsEscalationPhase

export type DorsEscalationPhase = 'TRIGGERED' | 'APPLIED';

DorsEscalationReasonCode

export type DorsEscalationReasonCode =
  | 'FALLBACK_SUCCESS'
  | 'RETRY_THRESHOLD'
  | 'POOR_SIGNAL'
  | 'CONGESTION'
  | 'LOW_TTL'
  | 'LOW_SUCCESS_RATE';

DorsScoreUpdatedEvent

export interface DorsScoreUpdatedEvent extends BaseEvent {
  type: 'dors_score_updated';
  scores: Array<[string, number]>;
}

DorsTransportSelectedEvent

export interface DorsTransportSelectedEvent extends BaseEvent {
  type: 'dors_transport_selected';
  from: string | null;
  transport: string;
  reason_code: DorsReasonCode;
  score?: number;
}

DorsTransportSwitchedEvent

export interface DorsTransportSwitchedEvent extends BaseEvent {
  type: 'dors_transport_switched';
  from: string | null;
  to: string;
  reason_code: DorsReasonCode;
  reason_detail?: string;
}

DorsEscalationTriggeredEvent

export interface DorsEscalationTriggeredEvent extends BaseEvent {
  type: 'dors_escalation_triggered';
  phase: DorsEscalationPhase;
  from: string;
  to: string;
  reason_code: DorsEscalationReasonCode;
  reason_detail?: string;
}

SecurityWarningCode

export type SecurityWarningCode =
  | 'SENDER_ADDRESS_MISMATCH'
  | 'TRANSPORT_IDENTITY_MISMATCH'
  | 'CONTROL_SIGNATURE_INVALID'
  | 'UNSIGNED_CONTROL_REJECTED'
  | 'MEDIA_SENDER_GROUP_MISMATCH'
  | 'PLAINTEXT_SEND'
  | 'PLAINTEXT_RECEIVE_REJECTED'
  | 'SESSION_SENDER_GROUP_MISMATCH'
  | 'SESSION_REKEY_TRIGGERED'
  | 'NOSTR_KEY_PACKAGE_SLOT_EXHAUSTED'
  | 'PUSH_KEY_PACKAGE_POOL_EXHAUSTED'
  | 'RELAY_ADDRESS_BINDING_MISMATCH'
  | 'RELAY_ADDRESS_DECLARATION_REFUSED'
  | 'GROUP_LEAF_IDENTITY_UNPROVEN'
  | 'STALE_CONTROL_FRAME'
  | 'GATEWAY_ADDRESS_BINDING_MISMATCH'
  | 'GATEWAY_ADDRESS_DECLARATION_REFUSED';

SecurityWarningEvent

export interface SecurityWarningEvent extends BaseEvent {
  type: 'security_warning';
  peer_id: string;
  reason_code: SecurityWarningCode;
  reason: string;
}

UserBlockedEvent

export interface UserBlockedEvent extends BaseEvent {
  type: 'user_blocked';
  user_id: string;
}

UserUnblockedEvent

export interface UserUnblockedEvent extends BaseEvent {
  type: 'user_unblocked';
  user_id: string;
}

DataChangedEvent

export interface DataChangedEvent extends BaseEvent {
  type: 'data_changed';
  space_id: string;
  doc_id: string;
  delta_bytes: number;
}

DataDocRemovedEvent

export interface DataDocRemovedEvent extends BaseEvent {
  type: 'data_doc_removed';
  space_id: string;
  doc_id: string;
  by: 'local' | 'peer';
}

DataDocSizeWarningEvent

export interface DataDocSizeWarningEvent extends BaseEvent {
  type: 'data_doc_size_warning';
  space_id: string;
  doc_id: string;
  compacted_bytes: number;
  cap_bytes: number;
}

DataAttachmentRequestedEvent

export interface DataAttachmentRequestedEvent extends BaseEvent {
  type: 'data_attachment_requested';
  space_id: string;
  peer_id: string;
  hash: string;
}

DataAttachmentReceivedEvent

export interface DataAttachmentReceivedEvent extends BaseEvent {
  type: 'data_attachment_received';
  space_id: string;
  peer_id: string;
  hash: string;
  data: string;
}

DataAttachmentUnavailableEvent

export interface DataAttachmentUnavailableEvent extends BaseEvent {
  type: 'data_attachment_unavailable';
  space_id: string;
  peer_id: string;
  hash: string;
  reason: string;
}

DataDocUnsyncableEvent

export interface DataDocUnsyncableEvent extends BaseEvent {
  type: 'data_doc_unsyncable';
  space_id: string;
  doc_id: string;
  bytes: number;
  reason: string;
}

InternetServerMessageEvent

export interface InternetServerMessageEvent extends BaseEvent {
  type: 'internet_server_message';
  json: string;
}

InternetStatusChangedEvent

export interface InternetStatusChangedEvent extends BaseEvent {
  type: 'internet_status_changed';
  connected: boolean;
  authenticated: boolean;
}

InternetSessionSupersededEvent

export interface InternetSessionSupersededEvent extends BaseEvent {
  type: 'internet_session_superseded';
  reason?: string;
}

MeshStoppedByUserEvent

export interface MeshStoppedByUserEvent extends BaseEvent {
  type: 'mesh_stopped_by_user';
}

RelaySyncState

export type RelaySyncState = 'synced' | 'pending' | 'unsynced';

ProtocolEvent

export type ProtocolEvent =
  | MessageSentEvent
  | MessageReceivedEvent
  | MessageDeliveredEvent
  | MessageFailedEvent
  | MessageDecryptionFailedEvent
  | TransportSwitchedEvent
  | RelayPromotedEvent
  | RelayDemotedEvent
  | RelayDemotedBatteryEvent
  | NeighborDiscoveredEvent
  | NeighborLostEvent
  | IdentityReadyEvent
  | NetworkMetricsEvent
  | FileProgressEvent
  | FileReceivedEvent
  | FileReceiveFailedEvent
  | MediaSentEvent
  | MediaSendFailedEvent
  | AckEvictedEvent
  | FragmentAssemblyEvictedEvent
  | DiagnosticEvent
  | SecureSessionEstablishedEvent
  | SecureSessionFailedEvent
  | ConvergenceDiagEvent
  | WelcomeSendAttemptedEvent
  | WelcomeSendSucceededEvent
  | WelcomeSendFailedEvent
  | WelcomeSendExpiredEvent
  | ConnectionRequestReceivedEvent
  | ConnectionRequestUndeliverableEvent
  | ConnectionAcceptedEvent
  | ConnectionRejectedEvent
  | ConnectionRequestCancelledEvent
  | GroupCreatedEvent
  | GroupMessageReceivedEvent
  | GroupMemberAddedEvent
  | GroupMemberRemovedEvent
  | GroupInfoEvent
  | UserGroupsEvent
  | GroupErrorEvent
  | GroupRelaySyncChangedEvent
  | UsernameResolvedEvent
  | GroupMessageSentEvent
  | GroupMessagePartialFailureEvent
  | GroupMessageDeliveryReportEvent
  | GroupRichExtrasDroppedEvent
  | GroupUnauthorizedMembershipChangeEvent
  | GroupEpochForkDetectedEvent
  | GroupEpochForkResolvedEvent
  | GroupRoleChangedEvent
  | GroupRenamedEvent
  | DorsScoreUpdatedEvent
  | DorsTransportSelectedEvent
  | DorsTransportSwitchedEvent
  | DorsEscalationTriggeredEvent
  | ServiceDiscoveredEvent
  | ServiceRequestReceivedEvent
  | ServiceResponseReceivedEvent
  | PresenceUpdatedEvent
  | InternetServerMessageEvent
  | InternetStatusChangedEvent
  | InternetSessionSupersededEvent
  | MeshStoppedByUserEvent
  | TypingIndicatorReceivedEvent
  | ReadReceiptReceivedEvent
  | MessageRelayedEvent
  | MessageDeferredEvent
  | MessageRetryingEvent
  | MessageUndeliverableEvent
  | MediaResendRequiredEvent
  | SecurityWarningEvent
  | UserBlockedEvent
  | UserUnblockedEvent
  | DataChangedEvent
  | DataDocRemovedEvent
  | DataDocSizeWarningEvent
  | DataAttachmentRequestedEvent
  | DataAttachmentReceivedEvent
  | DataAttachmentUnavailableEvent
  | DataDocUnsyncableEvent;

EventListener

export type EventListener<T extends ProtocolEvent = ProtocolEvent> = (event: T) => void;

EventType

export type EventType = ProtocolEvent['type'];

NodeRole

export enum NodeRole {
  Normal = 'normal',
  Relay = 'relay',
}

NetworkNode

export interface NetworkNode {
  user_id: string;
  role: NodeRole;
  connection_count: number;
  battery_level?: number;
  last_seen: number;
  transports: TransportType[];
}

NetworkLink

export interface NetworkLink {
  from: string;
  to: string;
  quality: number;
  transport: TransportType;
  rssi?: number;
}

NetworkStats

export interface NetworkStats {
  total_nodes: number;
  relay_nodes: number;
  total_connections: number;
  avg_link_quality: number;
  network_diameter?: number;
}

NetworkTopology

export interface NetworkTopology {
  timestamp: number;
  local_user_id: string;
  nodes: NetworkNode[];
  links: NetworkLink[];
  stats: NetworkStats;
}

MessageDeliveryStats

export interface MessageDeliveryStats {
  message_id: string;
  sender: string;
  recipient: string;
  sent_at: number;
  delivered_at?: number;
  hop_count: number;
  transport?: TransportType;
  retry_count: number;
  latency_ms?: number;
}

ProcessFileChunkParams

export interface ProcessFileChunkParams {
  fileId: string;
  chunkIndex: number;
  data: number[];
}

WifiDirectMessage

export interface WifiDirectMessage {
  recipientId: string;
  data: number[];
}

InternetMessage

export interface InternetMessage {
  messageId: string;
  recipientId: string;
  data: number[];
}

EstablishmentState

export type EstablishmentState =
  | 'NoKeyPackage'
  | 'HaveKeyPackage'
  | 'SessionPending'
  | 'SessionConfirmed';

MlsKeyPackage

export interface MlsKeyPackage {
  packageId: string;
  userId: string;
  keyPackageData: number[];
  createdAt: number;
  isSynced: boolean;
}

MlsEncryptedMessage

export interface MlsEncryptedMessage {
  groupId: string;
  messageType: string;
  epoch: number;
  ciphertext: number[];
  senderId: string;
  timestampMs: number;
}

MlsWelcome

export interface MlsWelcome {
  groupId: string;
  welcomeData: number[];
  inviterId: string;
  timestampMs: number;
}

MlsSessionInfo

export interface MlsSessionInfo {
  otherUserId: string;
  groupId: string;
  epoch: number;
  createdAt: number;
}

MlsGroupInfo

export interface MlsGroupInfo {
  groupId: string;
  groupName: string;
  memberIds: string[];
  epoch: number;
  createdAt: number;
}

GroupRichReadiness

export interface GroupRichReadiness {
  ready: boolean;
  unknownMembers: string[];
}

MlsCommit

export interface MlsCommit {
  groupId: string;
  commitData: number[];
  newEpoch: number;
}

MlsVerbosity

export type MlsVerbosity = 'off' | 'lifecycle' | 'diagnostic';

TelemetryConfig

export interface TelemetryConfig {
  apiKey: string;
  appId: string;
  appVersion?: string;
  debug?: boolean;
  flushIntervalMs?: number;
  maxBatchBytes?: number;
  maxBufferedRecords?: number;
  includeDeviceId?: boolean;
  scrubIds?: boolean;
  mlsVerbosity?: MlsVerbosity;
  metricsCadenceMs?: number;
  routingDiagnostic?: boolean;
  mlsSamplingBypass?: boolean;
}

TelemetryStats

export interface TelemetryStats {
  buffered: number;
  sentEvents: number;
  acceptedEvents: number;
  dropped: number;
  sessionId: string;
  lastError?: string;
  lastFlushAtMs?: number;
}

BleDiagnostics

export interface BleDiagnostics {
  fragmentFallbacks: number;
  recipientNotAmongPeers: number;
  undersizedMtuReports: number;
}

TransportMetrics

export interface TransportMetrics {
  packetsSent: number;
  packetsReceived: number;
  bytesSent: number;
  bytesReceived: number;
  errorRate: number;
  avgLatencyMs: number;
  rssi?: number;
  bandwidthBps?: number;
  congestion?: number;
  queueDepth?: number;
  batteryLevel?: number;
  isCharging?: boolean;
  relayConnectionCount?: number;
  isActiveRelay?: boolean;
  deliveryRatio?: number;
  dropRate?: number;
  averageHopCount?: number;
  energyCost?: number;
}

MeshWakeTaskData

export interface MeshWakeTaskData {
  reason: 'sticky_restart' | (string & {});
}

DataValue

export type DataValue =
  | { kind: 'null' }
  | { kind: 'bool'; value: boolean }
  | { kind: 'int'; value: number }
  | { kind: 'float'; value: number }
  | { kind: 'text'; value: string }
  | { kind: 'bytes'; value: number[] }
  | {
      kind: 'attachment';
      hash: string;
      size: number;
      name?: string;
      mime?: string;
    };

Diagnostic level compatibility

The v0.27.0 DiagnosticEvent.level declaration omits debug, which native bridges can emit. Diagnostic consumers must tolerate that runtime value.

​MessagePriority

​ProtocolState

​AckConfig

​RetryConfig

​DedupConfig

​MeshRelayConfig

​MeshRelayTunables

​MeshRelayStats

​DedupStats

​ReliabilityConfig

​RelayPriority

​RelayConfig

​NetworkConfig

​BleTransportConfig

​InternetTransportConfig

​WifiDirectTransportConfig

​ReticulumTransportConfig

​NostrTransportConfig

​ContentType

​MediaMetadata

​FileTransferConfig

​FileProgress

​TransportsConfig

​EncryptionConfig

​OverflowPolicy

​PendingQueueConfig

​DataConfig

​ProtocolConfig

​SecurityConfig

​TransportType

​ForwardInfo

​ReplyContext

​MediaMetadataEvent

​ForwardMessageParams

​ForwardMessageToGroupParams

​SendMessageParams

​SendConnectionRequestParams

​AcceptConnectionRequestParams

​RejectConnectionRequestParams

​CancelConnectionRequestParams

​SendMediaParams

​SendFileParams

​MessageSentEvent

​MessageReceivedEvent

​MessageDeliveredEvent

​MessageFailedEvent

​DecryptionFailureCode

​MessageDecryptionFailedEvent

​TransportSwitchedEvent

​RelayPromotedEvent

​RelayDemotedEvent

​RelayDemotedBatteryEvent

​NeighborDiscoveredEvent

​NeighborLostEvent

​IdentityReadyEvent

​NetworkMetricsEvent

​FileProgressEvent

​FileReceivedEvent

​FileReceiveFailedEvent

​MediaSentEvent

​MediaSendFailedEvent

​AckEvictedEvent

​FragmentAssemblyEvictedEvent

​DiagnosticEvent

​SecureSessionEstablishedEvent

​SecureSessionFailedEvent

​ConvergenceDiagEvent

​WelcomeReasonCode

​WelcomeSendAttemptedEvent

​WelcomeSendSucceededEvent

​WelcomeSendFailedEvent

​WelcomeSendExpiredEvent

​ConnectionRequestReceivedEvent

​ConnectionRequestUndeliverableEvent

​ConnectionAcceptedEvent

​ConnectionRejectedEvent

​ConnectionRequestCancelledEvent

​GroupCreatedEvent

​GroupMessageReceivedEvent

​GroupMemberAddedEvent