xfeed 0.1.0

package/src/experiments/use-timeline-query.ts

@@ -0,0 +1,201 @@
+/**
+ * useTimelineQuery - TanStack Query hook for timeline fetching
+ *
+ * Features:
+ * - Infinite query for cursor-based pagination
+ * - Shows "Refresh for new posts" banner after 5 minutes
+ * - Deduplication across pages
+ */
+
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import type { XClient } from "@/api/client";
+import type { ApiError, TweetData } from "@/api/types";
+
+import { queryKeys } from "./query-client";
+
+export type TimelineTab = "for_you" | "following";
+
+interface TimelinePage {
+  tweets: TweetData[];
+  nextCursor?: string;
+}
+
+interface UseTimelineQueryOptions {
+  client: XClient;
+  initialTab?: TimelineTab;
+  /** Time in ms before showing refresh banner (default: 300000 = 5 minutes) */
+  refreshBannerDelay?: number;
+}
+
+interface UseTimelineQueryResult {
+  /** Currently active tab */
+  tab: TimelineTab;
+  /** Switch to a different tab */
+  setTab: (tab: TimelineTab) => void;
+  /** Flattened list of posts with deduplication */
+  posts: TweetData[];
+  /** Whether initial data is loading */
+  isLoading: boolean;
+  /** Whether more data is being loaded (pagination) */
+  isFetchingNextPage: boolean;
+  /** Whether there are more posts to load */
+  hasNextPage: boolean;
+  /** Error if fetch failed */
+  error: ApiError | null;
+  /** Fetch next page of results */
+  fetchNextPage: () => void;
+  /** Manually refresh timeline */
+  refresh: () => void;
+  /** Whether to show the refresh banner */
+  showRefreshBanner: boolean;
+  /** Whether refresh is in progress */
+  isRefetching: boolean;
+}
+
+/**
+ * Fetch timeline page from X API
+ */
+async function fetchTimelinePage(
+  client: XClient,
+  tab: TimelineTab,
+  cursor?: string
+): Promise<TimelinePage> {
+  // Use V2 for initial fetch (returns ApiError), V1 for pagination
+  const result = cursor
+    ? tab === "for_you"
+      ? await client.getHomeTimeline(30, cursor)
+      : await client.getHomeLatestTimeline(30, cursor)
+    : tab === "for_you"
+      ? await client.getHomeTimelineV2(30)
+      : await client.getHomeLatestTimelineV2(30);
+
+  if (!result.success) {
+    // Normalize V1 string errors to ApiError
+    const error: ApiError =
+      typeof result.error === "string"
+        ? { type: "unknown", message: result.error }
+        : result.error;
+    throw error;
+  }
+
+  return {
+    tweets: result.tweets,
+    nextCursor: result.nextCursor,
+  };
+}
+
+/**
+ * Deduplicate tweets across all pages
+ */
+function deduplicateTweets(pages: TimelinePage[]): TweetData[] {
+  const seen = new Set<string>();
+  const result: TweetData[] = [];
+
+  for (const page of pages) {
+    for (const tweet of page.tweets) {
+      if (!seen.has(tweet.id)) {
+        seen.add(tweet.id);
+        result.push(tweet);
+      }
+    }
+  }
+
+  return result;
+}
+
+const DEFAULT_REFRESH_BANNER_DELAY = 5 * 60 * 1000; // 5 minutes
+
+export function useTimelineQuery({
+  client,
+  initialTab = "for_you",
+  refreshBannerDelay = DEFAULT_REFRESH_BANNER_DELAY,
+}: UseTimelineQueryOptions): UseTimelineQueryResult {
+  const [tab, setTabState] = useState<TimelineTab>(initialTab);
+  const [showRefreshBanner, setShowRefreshBanner] = useState(false);
+  const bannerTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Main infinite query for timeline
+  const {
+    data,
+    isLoading,
+    isFetchingNextPage,
+    hasNextPage,
+    error,
+    fetchNextPage,
+    refetch,
+    isRefetching,
+  } = useInfiniteQuery({
+    queryKey: queryKeys.timeline.byTab(tab),
+    queryFn: async ({ pageParam }) => {
+      return fetchTimelinePage(client, tab, pageParam);
+    },
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+    initialPageParam: undefined as string | undefined,
+    staleTime: 0,
+  });
+
+  // Start/reset banner timer when data loads or refreshes
+  const resetBannerTimer = useCallback(() => {
+    // Clear existing timer
+    if (bannerTimerRef.current) {
+      clearTimeout(bannerTimerRef.current);
+    }
+    // Hide banner
+    setShowRefreshBanner(false);
+    // Start new timer
+    bannerTimerRef.current = setTimeout(() => {
+      setShowRefreshBanner(true);
+    }, refreshBannerDelay);
+  }, [refreshBannerDelay]);
+
+  // Reset timer when data changes (initial load or refresh)
+  useEffect(() => {
+    if (data?.pages?.length) {
+      resetBannerTimer();
+    }
+    return () => {
+      if (bannerTimerRef.current) {
+        clearTimeout(bannerTimerRef.current);
+      }
+    };
+  }, [data?.pages, resetBannerTimer]);
+
+  // Flatten and deduplicate tweets from all pages
+  const posts = useMemo(() => {
+    if (!data?.pages) return [];
+    return deduplicateTweets(data.pages);
+  }, [data?.pages]);
+
+  // Handle tab switch
+  const setTab = useCallback(
+    (newTab: TimelineTab) => {
+      if (newTab !== tab) {
+        setTabState(newTab);
+        resetBannerTimer();
+      }
+    },
+    [tab, resetBannerTimer]
+  );
+
+  // Manual refresh
+  const refresh = useCallback(() => {
+    setShowRefreshBanner(false);
+    refetch();
+  }, [refetch]);
+
+  return {
+    tab,
+    setTab,
+    posts,
+    isLoading,
+    isFetchingNextPage,
+    hasNextPage: hasNextPage ?? false,
+    error: error as ApiError | null,
+    fetchNextPage,
+    refresh,
+    showRefreshBanner,
+    isRefetching,
+  };
+}

package/src/hooks/useActions.ts

@@ -0,0 +1,354 @@
+/**
+ * useActions - Hook for tweet action mutations (like, bookmark)
+ *
+ * Provides toggle functions with optimistic updates and error handling.
+ */
+
+import { useState, useCallback, useRef } from "react";
+
+import type { XClient } from "@/api/client";
+import type { TweetData } from "@/api/types";
+
+export interface BookmarkMutationFns {
+  /** Add a bookmark with optimistic cache update */
+  addBookmark: (tweet: TweetData) => void;
+  /** Remove a bookmark with optimistic cache update */
+  removeBookmark: (
+    tweetId: string,
+    folderId?: string,
+    tweet?: TweetData
+  ) => void;
+  /** Check if a bookmark operation is pending */
+  isPending: (tweetId: string) => boolean;
+  /** Check if a tweet was just bookmarked (for visual feedback) */
+  isJustBookmarked: (tweetId: string) => boolean;
+}
+
+export interface UseActionsOptions {
+  client: XClient;
+  /** Callback when an action fails - use to show error message */
+  onError?: (error: string) => void;
+  /** Callback when an action succeeds - use to show success message */
+  onSuccess?: (message: string) => void;
+  /** Callback when bookmark state changes - use to sync bookmark list */
+  onBookmarkChange?: (tweetId: string, isBookmarked: boolean) => void;
+  /** Optional TanStack Query bookmark mutation for optimistic cache updates */
+  bookmarkMutation?: BookmarkMutationFns;
+  /** Current folder ID for bookmark cache updates */
+  currentFolderId?: string;
+}
+
+export interface TweetActionState {
+  /** Whether the tweet is liked by the current user */
+  liked: boolean;
+  /** Whether the tweet is bookmarked by the current user */
+  bookmarked: boolean;
+  /** Whether a like action is in progress */
+  likePending: boolean;
+  /** Whether a bookmark action is in progress */
+  bookmarkPending: boolean;
+  /** True briefly after liking (for visual feedback) */
+  justLiked: boolean;
+  /** True briefly after bookmarking (for visual feedback) */
+  justBookmarked: boolean;
+}
+
+export interface UseActionsResult {
+  /** Get current action state for a tweet */
+  getState: (tweetId: string) => TweetActionState;
+  /** Toggle like state for a tweet */
+  toggleLike: (tweet: TweetData) => Promise<void>;
+  /** Toggle bookmark state for a tweet */
+  toggleBookmark: (tweet: TweetData) => Promise<void>;
+  /** Initialize state for a tweet (e.g., from API response) */
+  initState: (tweetId: string, liked: boolean, bookmarked: boolean) => void;
+}
+
+const DEFAULT_STATE: TweetActionState = {
+  liked: false,
+  bookmarked: false,
+  likePending: false,
+  bookmarkPending: false,
+  justLiked: false,
+  justBookmarked: false,
+};
+
+/** Duration for "just acted" visual feedback in ms */
+const JUST_ACTED_DURATION = 600;
+
+export function useActions({
+  client,
+  onError,
+  onSuccess,
+  onBookmarkChange,
+  bookmarkMutation,
+  currentFolderId,
+}: UseActionsOptions): UseActionsResult {
+  // Track action states by tweet ID
+  const [states, setStates] = useState<Map<string, TweetActionState>>(
+    new Map()
+  );
+
+  // Track timeouts for clearing "just acted" states
+  const justLikedTimeouts = useRef<Map<string, ReturnType<typeof setTimeout>>>(
+    new Map()
+  );
+  const justBookmarkedTimeouts = useRef<
+    Map<string, ReturnType<typeof setTimeout>>
+  >(new Map());
+
+  const getState = useCallback(
+    (tweetId: string): TweetActionState => {
+      const baseState = states.get(tweetId) ?? DEFAULT_STATE;
+
+      // If using TanStack Query mutation, overlay its pending/justBookmarked state
+      if (bookmarkMutation) {
+        return {
+          ...baseState,
+          bookmarkPending: bookmarkMutation.isPending(tweetId),
+          justBookmarked: bookmarkMutation.isJustBookmarked(tweetId),
+        };
+      }
+
+      return baseState;
+    },
+    [states, bookmarkMutation]
+  );
+
+  const updateState = useCallback(
+    (tweetId: string, updates: Partial<TweetActionState>) => {
+      setStates((prev) => {
+        const newMap = new Map(prev);
+        const current = prev.get(tweetId) ?? DEFAULT_STATE;
+        newMap.set(tweetId, { ...current, ...updates });
+        return newMap;
+      });
+    },
+    []
+  );
+
+  const initState = useCallback(
+    (tweetId: string, liked: boolean, bookmarked: boolean) => {
+      setStates((prev) => {
+        // Only initialize if no state exists yet for this tweet
+        // This preserves user actions (like/bookmark) when navigating back
+        if (prev.has(tweetId)) {
+          return prev;
+        }
+        const newMap = new Map(prev);
+        newMap.set(tweetId, { ...DEFAULT_STATE, liked, bookmarked });
+        return newMap;
+      });
+    },
+    []
+  );
+
+  const toggleLike = useCallback(
+    async (tweet: TweetData) => {
+      const currentState = states.get(tweet.id) ?? DEFAULT_STATE;
+
+      // Prevent double-clicks
+      if (currentState.likePending) return;
+
+      const wasLiked = currentState.liked;
+      const newLiked = !wasLiked;
+
+      // Optimistic update
+      updateState(tweet.id, { liked: newLiked, likePending: true });
+
+      try {
+        const result = newLiked
+          ? await client.likeTweet(tweet.id)
+          : await client.unlikeTweet(tweet.id);
+
+        if (result.success) {
+          // Set justLiked for visual feedback (only when liking)
+          if (newLiked) {
+            // Clear any existing timeout
+            const existingTimeout = justLikedTimeouts.current.get(tweet.id);
+            if (existingTimeout) clearTimeout(existingTimeout);
+
+            updateState(tweet.id, { likePending: false, justLiked: true });
+
+            // Auto-clear justLiked after duration
+            const timeout = setTimeout(() => {
+              updateState(tweet.id, { justLiked: false });
+              justLikedTimeouts.current.delete(tweet.id);
+            }, JUST_ACTED_DURATION);
+            justLikedTimeouts.current.set(tweet.id, timeout);
+          } else {
+            updateState(tweet.id, { likePending: false });
+          }
+          onSuccess?.(newLiked ? "Liked" : "Unliked");
+        } else {
+          // Check if error indicates the tweet was already in the target state
+          const lowerError = result.error.toLowerCase();
+          const alreadyLiked = lowerError.includes("already favorited");
+          const notLiked = lowerError.includes("not found");
+          const tweetDeleted =
+            lowerError.includes("deleted") ||
+            lowerError.includes("unavailable") ||
+            lowerError.includes("no status found");
+
+          if (alreadyLiked && newLiked) {
+            // We tried to like but it was already liked - sync state
+            updateState(tweet.id, { liked: true, likePending: false });
+            onSuccess?.("Already liked");
+          } else if (notLiked && !newLiked) {
+            // We tried to unlike but it wasn't liked - sync state
+            updateState(tweet.id, { liked: false, likePending: false });
+            onSuccess?.("Already unliked");
+          } else if (tweetDeleted) {
+            // Tweet was deleted - clear state and show friendly message
+            updateState(tweet.id, { liked: false, likePending: false });
+            onError?.("Tweet no longer available");
+          } else {
+            // Real error - revert
+            updateState(tweet.id, { liked: wasLiked, likePending: false });
+            onError?.(result.error);
+          }
+        }
+      } catch (error) {
+        // Revert on error
+        updateState(tweet.id, { liked: wasLiked, likePending: false });
+        onError?.(error instanceof Error ? error.message : String(error));
+      }
+    },
+    [client, states, updateState, onError, onSuccess]
+  );
+
+  const toggleBookmark = useCallback(
+    async (tweet: TweetData) => {
+      const currentState = states.get(tweet.id) ?? DEFAULT_STATE;
+
+      // If using TanStack Query mutation, delegate to it
+      if (bookmarkMutation) {
+        // Prevent double-clicks
+        if (bookmarkMutation.isPending(tweet.id)) return;
+
+        const wasBookmarked = currentState.bookmarked;
+        const newBookmarked = !wasBookmarked;
+
+        // Update local state for UI (bookmarked flag)
+        updateState(tweet.id, { bookmarked: newBookmarked });
+
+        // Use mutation for API call + cache updates
+        if (newBookmarked) {
+          bookmarkMutation.addBookmark(tweet);
+        } else {
+          bookmarkMutation.removeBookmark(tweet.id, currentFolderId, tweet);
+        }
+
+        // Notify about bookmark change (for legacy sync if needed)
+        onBookmarkChange?.(tweet.id, newBookmarked);
+        return;
+      }
+
+      // Fallback: Original implementation without TanStack Query
+      // Prevent double-clicks
+      if (currentState.bookmarkPending) return;
+
+      const wasBookmarked = currentState.bookmarked;
+      const newBookmarked = !wasBookmarked;
+
+      // Optimistic update
+      updateState(tweet.id, {
+        bookmarked: newBookmarked,
+        bookmarkPending: true,
+      });
+
+      try {
+        const result = newBookmarked
+          ? await client.createBookmark(tweet.id)
+          : await client.deleteBookmark(tweet.id);
+
+        if (result.success) {
+          // Set justBookmarked for visual feedback (only when bookmarking)
+          if (newBookmarked) {
+            // Clear any existing timeout
+            const existingTimeout = justBookmarkedTimeouts.current.get(
+              tweet.id
+            );
+            if (existingTimeout) clearTimeout(existingTimeout);
+
+            updateState(tweet.id, {
+              bookmarkPending: false,
+              justBookmarked: true,
+            });
+
+            // Auto-clear justBookmarked after duration
+            const timeout = setTimeout(() => {
+              updateState(tweet.id, { justBookmarked: false });
+              justBookmarkedTimeouts.current.delete(tweet.id);
+            }, JUST_ACTED_DURATION);
+            justBookmarkedTimeouts.current.set(tweet.id, timeout);
+          } else {
+            updateState(tweet.id, { bookmarkPending: false });
+          }
+          onSuccess?.(newBookmarked ? "Bookmarked" : "Removed bookmark");
+          onBookmarkChange?.(tweet.id, newBookmarked);
+        } else {
+          // Check if error indicates the tweet was already in the target state
+          const lowerError = result.error.toLowerCase();
+          const alreadyBookmarked = lowerError.includes("already bookmarked");
+          const notBookmarked = lowerError.includes("not found");
+          const tweetDeleted =
+            lowerError.includes("deleted") ||
+            lowerError.includes("unavailable") ||
+            lowerError.includes("no status found");
+
+          if (alreadyBookmarked && newBookmarked) {
+            // We tried to bookmark but it was already bookmarked - sync state
+            updateState(tweet.id, { bookmarked: true, bookmarkPending: false });
+            onSuccess?.("Already bookmarked");
+          } else if (notBookmarked && !newBookmarked) {
+            // We tried to unbookmark but it wasn't bookmarked - sync state
+            updateState(tweet.id, {
+              bookmarked: false,
+              bookmarkPending: false,
+            });
+            onSuccess?.("Already removed");
+          } else if (tweetDeleted) {
+            // Tweet was deleted - clear state and show friendly message
+            updateState(tweet.id, {
+              bookmarked: false,
+              bookmarkPending: false,
+            });
+            onError?.("Tweet no longer available");
+          } else {
+            // Real error - revert
+            updateState(tweet.id, {
+              bookmarked: wasBookmarked,
+              bookmarkPending: false,
+            });
+            onError?.(result.error);
+          }
+        }
+      } catch (error) {
+        // Revert on error
+        updateState(tweet.id, {
+          bookmarked: wasBookmarked,
+          bookmarkPending: false,
+        });
+        onError?.(error instanceof Error ? error.message : String(error));
+      }
+    },
+    [
+      client,
+      states,
+      updateState,
+      onError,
+      onSuccess,
+      onBookmarkChange,
+      bookmarkMutation,
+      currentFolderId,
+    ]
+  );
+
+  return {
+    getState,
+    toggleLike,
+    toggleBookmark,
+    initState,
+  };
+}

package/src/hooks/useBookmarkFolders.ts

@@ -0,0 +1,70 @@
+/**
+ * useBookmarkFolders - Hook for fetching bookmark folder list
+ */
+
+import { useState, useEffect, useCallback } from "react";
+
+import type { XClient } from "@/api/client";
+import type { BookmarkFolder } from "@/api/types";
+
+export interface UseBookmarkFoldersOptions {
+  client: XClient;
+  /** Whether to fetch folders on mount (default: true) */
+  enabled?: boolean;
+}
+
+export interface UseBookmarkFoldersResult {
+  /** List of bookmark folders */
+  folders: BookmarkFolder[];
+  /** Whether data is currently loading */
+  loading: boolean;
+  /** Error message if fetch failed */
+  error: string | null;
+  /** Manually trigger a refresh */
+  refresh: () => void;
+}
+
+export function useBookmarkFolders({
+  client,
+  enabled = true,
+}: UseBookmarkFoldersOptions): UseBookmarkFoldersResult {
+  const [folders, setFolders] = useState<BookmarkFolder[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [refreshCounter, setRefreshCounter] = useState(0);
+
+  const fetchFolders = useCallback(async () => {
+    if (!enabled) return;
+
+    setLoading(true);
+    setError(null);
+
+    const result = await client.getBookmarkFolders();
+
+    if (result.success) {
+      setFolders(result.folders);
+    } else {
+      setError(result.error);
+    }
+
+    setLoading(false);
+  }, [client, enabled]);
+
+  // Fetch on mount and when refresh is triggered
+  useEffect(() => {
+    if (enabled) {
+      fetchFolders();
+    }
+  }, [fetchFolders, refreshCounter, enabled]);
+
+  const refresh = useCallback(() => {
+    setRefreshCounter((prev) => prev + 1);
+  }, []);
+
+  return {
+    folders,
+    loading,
+    error,
+    refresh,
+  };
+}