@quilibrium/quorum-shared 2.1.0-1

package/src/transport/websocket.ts

@@ -0,0 +1,212 @@
+/**
+ * WebSocket client interface
+ *
+ * Platform-agnostic WebSocket connection management.
+ * Handles connection, reconnection, and message routing.
+ *
+ * IMPORTANT: This handles transport only. Encryption is handled separately
+ * by the CryptoProvider before/after message transmission.
+ */
+
+// ============ Connection State ============
+
+export type WebSocketConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
+
+// ============ Message Types ============
+
+/**
+ * Encrypted message received from WebSocket
+ * The content is a SealedMessage containing the encrypted envelope.
+ * All cryptographic material (ephemeral key, identity key) comes from the envelope itself.
+ */
+export interface EncryptedWebSocketMessage {
+  /** The encrypted message content (JSON string of SealedMessage) */
+  encryptedContent: string;
+  /** The inbox address this message was sent to */
+  inboxAddress: string;
+  /** Server timestamp */
+  timestamp: number;
+}
+
+/**
+ * SealedMessage format from the network
+ * Contains an encrypted envelope that can be unsealed with device keys.
+ * The ephemeral_public_key is used along with the inbox private key to decrypt.
+ */
+export interface SealedMessage {
+  /** The inbox address the message was sent to */
+  inbox_address: string;
+  /** Sender's ephemeral public key (used for decryption) */
+  ephemeral_public_key: string;
+  /** The encrypted envelope (contains identity key, message, return inbox info) */
+  envelope: string;
+  /** Optional inbox public key for verification */
+  inbox_public_key?: string;
+  /** Optional inbox signature for verification */
+  inbox_signature?: string;
+}
+
+/**
+ * UnsealedEnvelope - the decrypted content of a SealedMessage
+ * Contains all the data needed to establish a session and decrypt the message.
+ */
+export interface UnsealedEnvelope {
+  /** Sender's user address */
+  user_address: string;
+  /** Sender's display name */
+  display_name?: string;
+  /** Sender's icon URL */
+  user_icon?: string;
+  /** Inbox address for sending replies */
+  return_inbox_address: string;
+  /** Encryption key for the return inbox */
+  return_inbox_encryption_key: string;
+  /** Public key for the return inbox */
+  return_inbox_public_key: string;
+  /** Private key for the return inbox (only for sender's own use) */
+  return_inbox_private_key: string;
+  /** Sender's identity public key (for X3DH) */
+  identity_public_key: string;
+  /** Session/conversation tag */
+  tag: string;
+  /** The encrypted/signed message content */
+  message: string;
+  /** Message type */
+  type: string;
+  /** The ephemeral public key used to seal this message */
+  ephemeral_public_key: string;
+}
+
+/**
+ * Outbound message to send via WebSocket
+ */
+export interface OutboundWebSocketMessage {
+  /** Message type (e.g., 'message', 'listen', 'unlisten') */
+  type: string;
+  /** Message payload */
+  payload: unknown;
+}
+
+/**
+ * Listen/subscribe message for inbox addresses
+ */
+export interface ListenMessage {
+  type: 'listen';
+  inbox_addresses: string[];
+}
+
+/**
+ * Unlisten/unsubscribe message
+ */
+export interface UnlistenMessage {
+  type: 'unlisten';
+  inbox_addresses: string[];
+}
+
+// ============ Configuration ============
+
+export interface WebSocketClientOptions {
+  /** WebSocket server URL */
+  url: string;
+  /** Interval between reconnection attempts (ms). Default: 1000 */
+  reconnectInterval?: number;
+  /** Maximum reconnection attempts. Default: Infinity */
+  maxReconnectAttempts?: number;
+  /** Queue processing interval (ms). Default: 1000 */
+  queueProcessInterval?: number;
+}
+
+// ============ Event Handlers ============
+
+export type MessageHandler = (message: EncryptedWebSocketMessage) => Promise<void>;
+export type StateChangeHandler = (state: WebSocketConnectionState) => void;
+export type ErrorHandler = (error: Error) => void;
+
+// ============ WebSocket Client Interface ============
+
+/**
+ * WebSocketClient - Platform-agnostic WebSocket interface
+ *
+ * Features:
+ * - Automatic reconnection with configurable interval
+ * - Dual queue system (inbound/outbound)
+ * - Inbox address subscription management
+ * - Message handler registration
+ *
+ * Implementations:
+ * - Browser/Electron: Uses native WebSocket API
+ * - React Native: Uses React Native WebSocket
+ */
+export interface WebSocketClient {
+  /**
+   * Current connection state
+   */
+  readonly state: WebSocketConnectionState;
+
+  /**
+   * Whether currently connected
+   */
+  readonly isConnected: boolean;
+
+  /**
+   * Connect to the WebSocket server
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Disconnect from the WebSocket server
+   */
+  disconnect(): void;
+
+  /**
+   * Send a message (must be already serialized)
+   * Messages are queued if not connected and sent when connection is established
+   */
+  send(message: string): Promise<void>;
+
+  /**
+   * Enqueue an outbound message with async preparation
+   * Useful when message needs async work before sending
+   */
+  enqueueOutbound(prepareMessage: () => Promise<string[]>): void;
+
+  /**
+   * Subscribe to messages for inbox addresses
+   */
+  subscribe(inboxAddresses: string[]): Promise<void>;
+
+  /**
+   * Unsubscribe from inbox addresses
+   */
+  unsubscribe(inboxAddresses: string[]): Promise<void>;
+
+  /**
+   * Set the message handler for incoming messages
+   * Only one handler can be set at a time
+   */
+  setMessageHandler(handler: MessageHandler): void;
+
+  /**
+   * Set the resubscribe callback (called after reconnection)
+   */
+  setResubscribeHandler(handler: () => Promise<void>): void;
+
+  /**
+   * Add a connection state change listener
+   * @returns Unsubscribe function
+   */
+  onStateChange(handler: StateChangeHandler): () => void;
+
+  /**
+   * Add an error listener
+   * @returns Unsubscribe function
+   */
+  onError(handler: ErrorHandler): () => void;
+}
+
+// ============ Factory Function Type ============
+
+/**
+ * Factory function to create a WebSocket client
+ */
+export type CreateWebSocketClient = (options: WebSocketClientOptions) => WebSocketClient;

package/src/types/bookmark.ts

@@ -0,0 +1,29 @@
+/**
+ * Bookmark types for Quorum
+ */
+
+export type Bookmark = {
+  bookmarkId: string;
+  messageId: string;
+  spaceId?: string;
+  channelId?: string;
+  conversationId?: string;
+  sourceType: 'channel' | 'dm';
+  createdAt: number;
+  cachedPreview: {
+    senderAddress: string;
+    senderName: string;
+    textSnippet: string;
+    messageDate: number;
+    sourceName: string;
+    contentType: 'text' | 'image' | 'sticker';
+    imageUrl?: string;
+    thumbnailUrl?: string;
+    stickerId?: string;
+  };
+};
+
+export const BOOKMARKS_CONFIG = {
+  MAX_BOOKMARKS: 200,
+  PREVIEW_SNIPPET_LENGTH: 150,
+} as const;

package/src/types/conversation.ts

@@ -0,0 +1,25 @@
+/**
+ * Conversation (DM) types for Quorum
+ */
+
+export type ConversationSource = 'quorum' | 'farcaster';
+
+export type Conversation = {
+  conversationId: string;
+  type: 'direct' | 'group';
+  timestamp: number;
+  address: string;
+  icon: string;
+  displayName: string;
+  lastReadTimestamp?: number;
+  isRepudiable?: boolean;
+  saveEditHistory?: boolean;
+  lastMessageId?: string;
+  // Farcaster-specific fields
+  source?: ConversationSource;  // 'quorum' (E2EE) or 'farcaster' (direct cast)
+  farcasterConversationId?: string;  // Farcaster conversation ID (e.g., "123-456")
+  farcasterFid?: number;  // Counterparty's Farcaster FID (for 1:1 DMs)
+  farcasterUsername?: string;  // Counterparty's Farcaster username
+  farcasterParticipantFids?: number[];  // All participant FIDs except current user (for group chats)
+  unreadCount?: number;  // Farcaster unread count
+};

package/src/types/index.ts

@@ -0,0 +1,57 @@
+/**
+ * @quorum/shared types
+ *
+ * All type definitions shared between mobile and desktop apps
+ */
+
+// Space types
+export type {
+  Permission,
+  Role,
+  Emoji,
+  Sticker,
+  Group,
+  Channel,
+  Space,
+} from './space';
+
+// Message types
+export type {
+  MessageSendStatus,
+  PostMessage,
+  UpdateProfileMessage,
+  RemoveMessage,
+  EventMessage,
+  EmbedMessage,
+  ReactionMessage,
+  RemoveReactionMessage,
+  JoinMessage,
+  LeaveMessage,
+  KickMessage,
+  MuteMessage,
+  StickerMessage,
+  PinMessage,
+  DeleteConversationMessage,
+  EditMessage,
+  MessageContent,
+  Reaction,
+  Mentions,
+  Message,
+} from './message';
+
+// Conversation types
+export type { Conversation, ConversationSource } from './conversation';
+
+// User types
+export type {
+  FolderColor,
+  NavItem,
+  NotificationSettings,
+  UserConfig,
+  UserProfile,
+  SpaceMember,
+} from './user';
+
+// Bookmark types
+export type { Bookmark } from './bookmark';
+export { BOOKMARKS_CONFIG } from './bookmark';

package/src/types/message.ts

@@ -0,0 +1,178 @@
+/**
+ * Message-related types for Quorum
+ */
+
+/** Client-side ephemeral status - NEVER persist to storage or include in network payload */
+export type MessageSendStatus = 'sending' | 'sent' | 'failed';
+
+export type PostMessage = {
+  senderId: string;
+  type: 'post';
+  text: string | string[];
+  repliesToMessageId?: string;
+};
+
+export type UpdateProfileMessage = {
+  senderId: string;
+  type: 'update-profile';
+  displayName: string;
+  userIcon: string;
+};
+
+export type RemoveMessage = {
+  senderId: string;
+  type: 'remove-message';
+  removeMessageId: string;
+};
+
+export type EventMessage = {
+  senderId: string;
+  type: 'event';
+  text: string;
+  repliesToMessageId?: string;
+};
+
+export type EmbedMessage = {
+  senderId: string;
+  type: 'embed';
+  imageUrl?: string;
+  thumbnailUrl?: string;
+  videoUrl?: string;
+  width?: string;
+  height?: string;
+  isLargeGif?: boolean;
+  repliesToMessageId?: string;
+};
+
+export type ReactionMessage = {
+  senderId: string;
+  type: 'reaction';
+  reaction: string;
+  messageId: string;
+};
+
+export type RemoveReactionMessage = {
+  senderId: string;
+  type: 'remove-reaction';
+  reaction: string;
+  messageId: string;
+};
+
+export type JoinMessage = {
+  senderId: string;
+  type: 'join';
+};
+
+export type LeaveMessage = {
+  senderId: string;
+  type: 'leave';
+};
+
+export type KickMessage = {
+  senderId: string;
+  type: 'kick';
+};
+
+export type MuteMessage = {
+  senderId: string;
+  type: 'mute';
+  targetUserId: string;
+  muteId: string;
+  timestamp: number;
+  action: 'mute' | 'unmute';
+  duration?: number;
+};
+
+export type StickerMessage = {
+  senderId: string;
+  type: 'sticker';
+  stickerId: string;
+  repliesToMessageId?: string;
+};
+
+export type PinMessage = {
+  senderId: string;
+  type: 'pin';
+  targetMessageId: string;
+  action: 'pin' | 'unpin';
+};
+
+export type DeleteConversationMessage = {
+  senderId: string;
+  type: 'delete-conversation';
+};
+
+export type EditMessage = {
+  senderId: string;
+  type: 'edit-message';
+  originalMessageId: string;
+  editedText: string | string[];
+  editedAt: number;
+  editNonce: string;
+  editSignature?: string;
+};
+
+export type MessageContent =
+  | PostMessage
+  | EventMessage
+  | EmbedMessage
+  | ReactionMessage
+  | RemoveReactionMessage
+  | RemoveMessage
+  | JoinMessage
+  | LeaveMessage
+  | KickMessage
+  | MuteMessage
+  | UpdateProfileMessage
+  | StickerMessage
+  | PinMessage
+  | DeleteConversationMessage
+  | EditMessage;
+
+export type Reaction = {
+  emojiId: string;
+  spaceId: string;
+  emojiName: string;
+  count: number;
+  memberIds: string[];
+};
+
+export type Mentions = {
+  memberIds: string[];
+  roleIds: string[];
+  channelIds: string[];
+  everyone?: boolean;
+  totalMentionCount?: number;
+};
+
+export type Message = {
+  channelId: string;
+  spaceId: string;
+  messageId: string;
+  digestAlgorithm: string;
+  nonce: string;
+  createdDate: number;
+  modifiedDate: number;
+  lastModifiedHash: string;
+  content: MessageContent;
+  reactions: Reaction[];
+  mentions: Mentions;
+  replyMetadata?: {
+    parentAuthor: string;
+    parentChannelId: string;
+  };
+  publicKey?: string;
+  signature?: string;
+  isPinned?: boolean;
+  pinnedAt?: number;
+  pinnedBy?: string;
+  edits?: Array<{
+    text: string | string[];
+    modifiedDate: number;
+    lastModifiedHash: string;
+  }>;
+  /** Client-side ephemeral - NEVER persist or transmit */
+  sendStatus?: MessageSendStatus;
+  /** Client-side ephemeral - sanitized error message for display */
+  sendError?: string;
+};

package/src/types/space.ts

@@ -0,0 +1,75 @@
+/**
+ * Space-related types for Quorum
+ */
+
+export type Permission = 'message:delete' | 'message:pin' | 'mention:everyone' | 'user:mute';
+
+export type Role = {
+  roleId: string;
+  displayName: string;
+  roleTag: string;
+  color: string;
+  members: string[];
+  permissions: Permission[];
+  isPublic?: boolean;
+};
+
+export type Emoji = {
+  name: string;
+  id: string;
+  imgUrl: string;
+};
+
+export type Sticker = {
+  name: string;
+  id: string;
+  imgUrl: string;
+};
+
+export type Group = {
+  groupName: string;
+  channels: Channel[];
+  icon?: string;
+  iconColor?: string;
+  iconVariant?: 'outline' | 'filled';
+};
+
+export type Channel = {
+  channelId: string;
+  spaceId: string;
+  channelName: string;
+  channelTopic: string;
+  channelKey?: string;
+  createdDate: number;
+  modifiedDate: number;
+  mentionCount?: number;
+  mentions?: string;
+  isReadOnly?: boolean;
+  managerRoleIds?: string[];
+  isPinned?: boolean;
+  pinnedAt?: number;
+  icon?: string;
+  iconColor?: string;
+  iconVariant?: 'outline' | 'filled';
+};
+
+export type Space = {
+  spaceId: string;
+  spaceName: string;
+  description?: string;
+  vanityUrl: string;
+  inviteUrl: string;
+  iconUrl: string;
+  bannerUrl: string;
+  defaultChannelId: string;
+  hubAddress: string;
+  createdDate: number;
+  modifiedDate: number;
+  isRepudiable: boolean;
+  isPublic: boolean;
+  saveEditHistory?: boolean;
+  groups: Group[];
+  roles: Role[];
+  emojis: Emoji[];
+  stickers: Sticker[];
+};

package/src/types/user.ts

@@ -0,0 +1,72 @@
+/**
+ * User-related types for Quorum
+ */
+
+import type { Bookmark } from './bookmark';
+
+export type FolderColor = string;
+
+export type NavItem =
+  | { type: 'space'; id: string }
+  | {
+      type: 'folder';
+      id: string;
+      name: string;
+      spaceIds: string[];
+      icon?: string;
+      color?: FolderColor;
+      createdDate: number;
+      modifiedDate: number;
+    };
+
+export type NotificationSettings = {
+  enabled?: boolean;
+  mentions?: boolean;
+  replies?: boolean;
+  all?: boolean;
+};
+
+export type UserConfig = {
+  address: string;
+  spaceIds: string[];
+  items?: NavItem[];
+  timestamp?: number;
+  nonRepudiable?: boolean;
+  allowSync?: boolean;
+  name?: string;
+  profile_image?: string;
+  spaceKeys?: {
+    spaceId: string;
+    encryptionState: {
+      conversationId: string;
+      inboxId: string;
+      state: string;
+      timestamp: number;
+    };
+    keys: {
+      keyId: string;
+      address?: string;
+      publicKey: string;
+      privateKey: string;
+      spaceId: string;
+    }[];
+  }[];
+  notificationSettings?: {
+    [spaceId: string]: NotificationSettings;
+  };
+  bookmarks?: Bookmark[];
+  deletedBookmarkIds?: string[];
+};
+
+export type UserProfile = {
+  address: string;
+  name?: string;
+  display_name?: string;
+  profile_image?: string;
+  bio?: string;
+};
+
+export type SpaceMember = UserProfile & {
+  inbox_address: string;
+  isKicked?: boolean;
+};