@quilibrium/quorum-shared 2.1.0-1

package/src/hooks/keys.ts

@@ -0,0 +1,62 @@
+/**
+ * Query key factories for React Query
+ *
+ * Consistent key structure across platforms for cache management
+ */
+
+export const queryKeys = {
+  // Spaces
+  spaces: {
+    all: ['spaces'] as const,
+    detail: (spaceId: string) => ['spaces', spaceId] as const,
+    members: (spaceId: string) => ['spaces', spaceId, 'members'] as const,
+    member: (spaceId: string, address: string) =>
+      ['spaces', spaceId, 'members', address] as const,
+  },
+
+  // Channels
+  channels: {
+    bySpace: (spaceId: string) => ['channels', spaceId] as const,
+    detail: (spaceId: string, channelId: string) =>
+      ['channels', spaceId, channelId] as const,
+  },
+
+  // Messages
+  messages: {
+    infinite: (spaceId: string, channelId: string) =>
+      ['messages', 'infinite', spaceId, channelId] as const,
+    detail: (spaceId: string, channelId: string, messageId: string) =>
+      ['messages', spaceId, channelId, messageId] as const,
+    pinned: (spaceId: string, channelId: string) =>
+      ['messages', 'pinned', spaceId, channelId] as const,
+  },
+
+  // Conversations (DMs)
+  conversations: {
+    all: (type: 'direct' | 'group') => ['conversations', type] as const,
+    detail: (conversationId: string) => ['conversations', conversationId] as const,
+    messages: (conversationId: string) =>
+      ['conversations', conversationId, 'messages'] as const,
+  },
+
+  // User
+  user: {
+    config: (address: string) => ['user', 'config', address] as const,
+    profile: (address: string) => ['user', 'profile', address] as const,
+  },
+
+  // Bookmarks
+  bookmarks: {
+    all: ['bookmarks'] as const,
+    bySource: (sourceType: 'channel' | 'dm') =>
+      ['bookmarks', sourceType] as const,
+    bySpace: (spaceId: string) => ['bookmarks', 'space', spaceId] as const,
+    check: (messageId: string) => ['bookmarks', 'check', messageId] as const,
+  },
+} as const;
+
+// Type helpers for extracting key types
+export type SpacesKey = typeof queryKeys.spaces.all;
+export type SpaceDetailKey = ReturnType<typeof queryKeys.spaces.detail>;
+export type ChannelsKey = ReturnType<typeof queryKeys.channels.bySpace>;
+export type MessagesInfiniteKey = ReturnType<typeof queryKeys.messages.infinite>;

package/src/hooks/mutations/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Mutation hooks exports
+ */
+
+export { useSendMessage } from './useSendMessage';
+export type { UseSendMessageOptions } from './useSendMessage';
+
+export { useAddReaction, useRemoveReaction } from './useReaction';
+export type { UseReactionOptions } from './useReaction';
+
+export { useEditMessage } from './useEditMessage';
+export type { UseEditMessageOptions } from './useEditMessage';
+
+export { useDeleteMessage } from './useDeleteMessage';
+export type { UseDeleteMessageOptions } from './useDeleteMessage';

package/src/hooks/mutations/useDeleteMessage.ts

@@ -0,0 +1,67 @@
+/**
+ * useDeleteMessage mutation hook
+ *
+ * Delete a message with optimistic updates
+ */
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import type { StorageAdapter, GetMessagesResult } from '../../storage';
+import type { QuorumApiClient, DeleteMessageParams } from '../../api';
+import { queryKeys } from '../keys';
+
+export interface UseDeleteMessageOptions {
+  storage: StorageAdapter;
+  apiClient: QuorumApiClient;
+}
+
+export function useDeleteMessage({ storage, apiClient }: UseDeleteMessageOptions) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (params: DeleteMessageParams): Promise<void> => {
+      return apiClient.deleteMessage(params);
+    },
+
+    onMutate: async (params) => {
+      const key = queryKeys.messages.infinite(params.spaceId, params.channelId);
+
+      await queryClient.cancelQueries({ queryKey: key });
+      const previousData = queryClient.getQueryData(key);
+
+      // Optimistically remove message
+      queryClient.setQueryData(key, (old: { pages: GetMessagesResult[]; pageParams: unknown[] } | undefined) => {
+        if (!old) return old;
+
+        return {
+          ...old,
+          pages: old.pages.map((page) => ({
+            ...page,
+            messages: page.messages.filter(
+              (message) => message.messageId !== params.messageId
+            ),
+          })),
+        };
+      });
+
+      return { previousData };
+    },
+
+    onError: (err, params, context) => {
+      if (context?.previousData) {
+        const key = queryKeys.messages.infinite(params.spaceId, params.channelId);
+        queryClient.setQueryData(key, context.previousData);
+      }
+    },
+
+    onSuccess: async (_, params) => {
+      // Remove from storage
+      await storage.deleteMessage(params.messageId);
+    },
+
+    onSettled: (data, err, params) => {
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.messages.infinite(params.spaceId, params.channelId),
+      });
+    },
+  });
+}

package/src/hooks/mutations/useEditMessage.ts

@@ -0,0 +1,87 @@
+/**
+ * useEditMessage mutation hook
+ *
+ * Edit a message with optimistic updates
+ */
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import type { Message, PostMessage } from '../../types';
+import type { StorageAdapter, GetMessagesResult } from '../../storage';
+import type { QuorumApiClient, EditMessageParams } from '../../api';
+import { queryKeys } from '../keys';
+
+export interface UseEditMessageOptions {
+  storage: StorageAdapter;
+  apiClient: QuorumApiClient;
+}
+
+export function useEditMessage({ storage, apiClient }: UseEditMessageOptions) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (params: EditMessageParams): Promise<Message> => {
+      return apiClient.editMessage(params);
+    },
+
+    onMutate: async (params) => {
+      const key = queryKeys.messages.infinite(params.spaceId, params.channelId);
+
+      await queryClient.cancelQueries({ queryKey: key });
+      const previousData = queryClient.getQueryData(key);
+
+      // Optimistically update message
+      queryClient.setQueryData(key, (old: { pages: GetMessagesResult[]; pageParams: unknown[] } | undefined) => {
+        if (!old) return old;
+
+        return {
+          ...old,
+          pages: old.pages.map((page) => ({
+            ...page,
+            messages: page.messages.map((message) => {
+              if (message.messageId !== params.messageId) return message;
+
+              // Only update if it's a post message
+              if (message.content.type !== 'post') return message;
+
+              return {
+                ...message,
+                modifiedDate: Date.now(),
+                content: {
+                  ...message.content,
+                  text: params.text,
+                } as PostMessage,
+              };
+            }),
+          })),
+        };
+      });
+
+      return { previousData };
+    },
+
+    onError: (err, params, context) => {
+      if (context?.previousData) {
+        const key = queryKeys.messages.infinite(params.spaceId, params.channelId);
+        queryClient.setQueryData(key, context.previousData);
+      }
+    },
+
+    onSuccess: async (message) => {
+      // Persist updated message to storage
+      await storage.saveMessage(
+        message,
+        message.modifiedDate,
+        message.content.senderId,
+        'space',
+        '',
+        ''
+      );
+    },
+
+    onSettled: (data, err, params) => {
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.messages.infinite(params.spaceId, params.channelId),
+      });
+    },
+  });
+}

package/src/hooks/mutations/useReaction.ts

@@ -0,0 +1,163 @@
+/**
+ * useReaction mutation hooks
+ *
+ * Add and remove reactions with optimistic updates
+ */
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import type { Message, Reaction } from '../../types';
+import type { StorageAdapter, GetMessagesResult } from '../../storage';
+import type { QuorumApiClient, AddReactionParams, RemoveReactionParams } from '../../api';
+import { queryKeys } from '../keys';
+
+export interface UseReactionOptions {
+  storage: StorageAdapter;
+  apiClient: QuorumApiClient;
+  currentUserId: string;
+}
+
+export function useAddReaction({
+  storage,
+  apiClient,
+  currentUserId,
+}: UseReactionOptions) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (params: AddReactionParams): Promise<void> => {
+      return apiClient.addReaction(params);
+    },
+
+    onMutate: async (params) => {
+      const key = queryKeys.messages.infinite(params.spaceId, params.channelId);
+
+      await queryClient.cancelQueries({ queryKey: key });
+      const previousData = queryClient.getQueryData(key);
+
+      // Optimistically add reaction
+      queryClient.setQueryData(key, (old: { pages: GetMessagesResult[]; pageParams: unknown[] } | undefined) => {
+        if (!old) return old;
+
+        return {
+          ...old,
+          pages: old.pages.map((page) => ({
+            ...page,
+            messages: page.messages.map((message) => {
+              if (message.messageId !== params.messageId) return message;
+
+              const existingReaction = message.reactions.find(
+                (r) => r.emojiName === params.reaction
+              );
+
+              if (existingReaction) {
+                // Add user to existing reaction
+                return {
+                  ...message,
+                  reactions: message.reactions.map((r) =>
+                    r.emojiName === params.reaction
+                      ? {
+                          ...r,
+                          count: r.count + 1,
+                          memberIds: [...r.memberIds, currentUserId],
+                        }
+                      : r
+                  ),
+                };
+              } else {
+                // Create new reaction
+                const newReaction: Reaction = {
+                  emojiId: params.reaction,
+                  emojiName: params.reaction,
+                  spaceId: params.spaceId,
+                  count: 1,
+                  memberIds: [currentUserId],
+                };
+                return {
+                  ...message,
+                  reactions: [...message.reactions, newReaction],
+                };
+              }
+            }),
+          })),
+        };
+      });
+
+      return { previousData };
+    },
+
+    onError: (err, params, context) => {
+      if (context?.previousData) {
+        const key = queryKeys.messages.infinite(params.spaceId, params.channelId);
+        queryClient.setQueryData(key, context.previousData);
+      }
+    },
+  });
+}
+
+export function useRemoveReaction({
+  storage,
+  apiClient,
+  currentUserId,
+}: UseReactionOptions) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (params: RemoveReactionParams): Promise<void> => {
+      return apiClient.removeReaction(params);
+    },
+
+    onMutate: async (params) => {
+      const key = queryKeys.messages.infinite(params.spaceId, params.channelId);
+
+      await queryClient.cancelQueries({ queryKey: key });
+      const previousData = queryClient.getQueryData(key);
+
+      // Optimistically remove reaction
+      queryClient.setQueryData(key, (old: { pages: GetMessagesResult[]; pageParams: unknown[] } | undefined) => {
+        if (!old) return old;
+
+        return {
+          ...old,
+          pages: old.pages.map((page) => ({
+            ...page,
+            messages: page.messages.map((message) => {
+              if (message.messageId !== params.messageId) return message;
+
+              return {
+                ...message,
+                reactions: message.reactions
+                  .map((r) => {
+                    if (r.emojiName !== params.reaction) return r;
+
+                    const newMemberIds = r.memberIds.filter(
+                      (id) => id !== currentUserId
+                    );
+
+                    if (newMemberIds.length === 0) {
+                      return null; // Remove reaction entirely
+                    }
+
+                    return {
+                      ...r,
+                      count: newMemberIds.length,
+                      memberIds: newMemberIds,
+                    };
+                  })
+                  .filter((r): r is Reaction => r !== null),
+              };
+            }),
+          })),
+        };
+      });
+
+      return { previousData };
+    },
+
+    onError: (err, params, context) => {
+      if (context?.previousData) {
+        const key = queryKeys.messages.infinite(params.spaceId, params.channelId);
+        queryClient.setQueryData(key, context.previousData);
+      }
+    },
+  });
+}

package/src/hooks/mutations/useSendMessage.ts

@@ -0,0 +1,131 @@
+/**
+ * useSendMessage mutation hook
+ *
+ * Sends a message with optimistic updates
+ */
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import type { Message } from '../../types';
+import type { StorageAdapter, GetMessagesResult } from '../../storage';
+import type { QuorumApiClient, SendMessageParams } from '../../api';
+import { queryKeys } from '../keys';
+
+export interface UseSendMessageOptions {
+  storage: StorageAdapter;
+  apiClient: QuorumApiClient;
+  currentUserId: string;
+}
+
+export function useSendMessage({
+  storage,
+  apiClient,
+  currentUserId,
+}: UseSendMessageOptions) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (params: SendMessageParams): Promise<Message> => {
+      return apiClient.sendMessage(params);
+    },
+
+    onMutate: async (params) => {
+      const key = queryKeys.messages.infinite(params.spaceId, params.channelId);
+
+      // Cancel outgoing refetches
+      await queryClient.cancelQueries({ queryKey: key });
+
+      // Snapshot previous value
+      const previousData = queryClient.getQueryData(key);
+
+      // Create optimistic message
+      const optimisticMessage: Message = {
+        messageId: `temp-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+        channelId: params.channelId,
+        spaceId: params.spaceId,
+        digestAlgorithm: '',
+        nonce: '',
+        createdDate: Date.now(),
+        modifiedDate: Date.now(),
+        lastModifiedHash: '',
+        content: {
+          type: 'post',
+          senderId: currentUserId,
+          text: params.text,
+          repliesToMessageId: params.repliesToMessageId,
+        },
+        reactions: [],
+        mentions: { memberIds: [], roleIds: [], channelIds: [] },
+        sendStatus: 'sending',
+      };
+
+      // Optimistically add to cache
+      queryClient.setQueryData(key, (old: { pages: GetMessagesResult[]; pageParams: unknown[] } | undefined) => {
+        if (!old) return old;
+
+        return {
+          ...old,
+          pages: old.pages.map((page, index) => {
+            if (index === 0) {
+              return {
+                ...page,
+                messages: [optimisticMessage, ...page.messages],
+              };
+            }
+            return page;
+          }),
+        };
+      });
+
+      return { previousData, optimisticMessage };
+    },
+
+    onError: (err, params, context) => {
+      // Rollback on error
+      if (context?.previousData) {
+        const key = queryKeys.messages.infinite(params.spaceId, params.channelId);
+        queryClient.setQueryData(key, context.previousData);
+      }
+    },
+
+    onSuccess: async (message, params, context) => {
+      // Replace optimistic message with real one
+      const key = queryKeys.messages.infinite(params.spaceId, params.channelId);
+
+      queryClient.setQueryData(key, (old: { pages: GetMessagesResult[]; pageParams: unknown[] } | undefined) => {
+        if (!old) return old;
+
+        return {
+          ...old,
+          pages: old.pages.map((page, index) => {
+            if (index === 0) {
+              return {
+                ...page,
+                messages: page.messages.map((m) =>
+                  m.messageId === context?.optimisticMessage.messageId ? message : m
+                ),
+              };
+            }
+            return page;
+          }),
+        };
+      });
+
+      // Persist to storage
+      await storage.saveMessage(
+        message,
+        message.createdDate,
+        currentUserId,
+        'space',
+        '',
+        ''
+      );
+    },
+
+    onSettled: (data, err, params) => {
+      // Always refetch after mutation
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.messages.infinite(params.spaceId, params.channelId),
+      });
+    },
+  });
+}

package/src/hooks/useChannels.ts

@@ -0,0 +1,49 @@
+/**
+ * useChannels hook
+ *
+ * Fetches and caches channel data for a space
+ */
+
+import { useQuery } from '@tanstack/react-query';
+import type { Channel } from '../types';
+import type { StorageAdapter } from '../storage';
+import { queryKeys } from './keys';
+
+export interface UseChannelsOptions {
+  storage: StorageAdapter;
+  spaceId: string | undefined;
+  enabled?: boolean;
+}
+
+export function useChannels({ storage, spaceId, enabled = true }: UseChannelsOptions) {
+  return useQuery({
+    queryKey: queryKeys.channels.bySpace(spaceId ?? ''),
+    queryFn: async (): Promise<Channel[]> => {
+      if (!spaceId) return [];
+      return storage.getChannels(spaceId);
+    },
+    enabled: enabled && !!spaceId,
+    staleTime: 1000 * 60 * 5, // 5 minutes
+  });
+}
+
+/**
+ * Helper to extract channels from a space's groups
+ */
+export function flattenChannels(groups: { channels: Channel[] }[]): Channel[] {
+  return groups.flatMap((group) => group.channels);
+}
+
+/**
+ * Find a channel by ID within groups
+ */
+export function findChannel(
+  groups: { channels: Channel[] }[],
+  channelId: string
+): Channel | undefined {
+  for (const group of groups) {
+    const channel = group.channels.find((c) => c.channelId === channelId);
+    if (channel) return channel;
+  }
+  return undefined;
+}

package/src/hooks/useMessages.ts

@@ -0,0 +1,77 @@
+/**
+ * useMessages hook
+ *
+ * Infinite query for paginated message loading
+ */
+
+import { useInfiniteQuery, useQueryClient } from '@tanstack/react-query';
+import type { Message } from '../types';
+import type { StorageAdapter, GetMessagesResult } from '../storage';
+import { queryKeys } from './keys';
+
+export interface UseMessagesOptions {
+  storage: StorageAdapter;
+  spaceId: string | undefined;
+  channelId: string | undefined;
+  enabled?: boolean;
+  limit?: number;
+}
+
+export function useMessages({
+  storage,
+  spaceId,
+  channelId,
+  enabled = true,
+  limit = 50,
+}: UseMessagesOptions) {
+  return useInfiniteQuery({
+    queryKey: queryKeys.messages.infinite(spaceId ?? '', channelId ?? ''),
+    queryFn: async ({ pageParam }): Promise<GetMessagesResult> => {
+      if (!spaceId || !channelId) {
+        return { messages: [], nextCursor: null, prevCursor: null };
+      }
+      return storage.getMessages({
+        spaceId,
+        channelId,
+        cursor: pageParam as number | undefined,
+        direction: 'backward',
+        limit,
+      });
+    },
+    getNextPageParam: (lastPage) => lastPage.prevCursor,
+    getPreviousPageParam: (firstPage) => firstPage.nextCursor,
+    initialPageParam: undefined as number | undefined,
+    enabled: enabled && !!spaceId && !!channelId,
+    staleTime: 1000 * 30, // 30 seconds
+  });
+}
+
+/**
+ * Flatten paginated messages into a single array
+ */
+export function flattenMessages(
+  pages: GetMessagesResult[] | undefined
+): Message[] {
+  if (!pages) return [];
+  return pages.flatMap((page) => page.messages);
+}
+
+/**
+ * Hook to invalidate message cache
+ */
+export function useInvalidateMessages() {
+  const queryClient = useQueryClient();
+
+  return {
+    invalidateChannel: (spaceId: string, channelId: string) => {
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.messages.infinite(spaceId, channelId),
+      });
+    },
+    invalidateSpace: (spaceId: string) => {
+      queryClient.invalidateQueries({
+        queryKey: ['messages', 'infinite', spaceId],
+      });
+    },
+  };
+}