birdclaw 0.8.0 → 0.8.2

package/src/components/useTimelineRouteData.ts

@@ -6,13 +6,30 @@ import type {
 	TimelineItem,
 } from "#/lib/types";
 import {
+	fetchCachedQueryResponse,
 	fetchQueryEnvelope,
-	fetchQueryResponse,
+	invalidateCachedQueryResponse,
+	invalidateCachedQueryResponses,
 	postAction,
+	readCachedQueryEnvelope,
 } from "#/lib/api-client";
+import {
+	deleteClientCache,
+	deleteClientCacheByPrefix,
+	readClientCache,
+	writeClientCache,
+} from "#/lib/client-cache";
 import { useSelectedAccountId } from "./account-selection";
+import { useDebouncedValue } from "./useDebouncedValue";
 
 const PAGE_SIZE = 50;
+const TIMELINE_VIEW_CACHE_PREFIX = "timeline-view:";
+const TIMELINE_VIEW_CACHE_MAX_AGE_MS = 5 * 60_000;
+
+interface TimelineViewSnapshot {
+	items: TimelineItem[];
+	hasMore: boolean;
+}
 
 interface UseTimelineRouteDataOptions {
 	resource: Exclude<ResourceKind, "dms">;
@@ -23,6 +40,53 @@ interface UseTimelineRouteDataOptions {
 	bookmarkedOnly?: boolean;
 }
 
+function buildTimelineQueryUrl({
+	resource,
+	search,
+	replyFilter,
+	likedOnly,
+	bookmarkedOnly,
+	selectedAccountId,
+	refreshTick,
+	until,
+	untilId,
+}: {
+	resource: Exclude<ResourceKind, "dms">;
+	search: string;
+	replyFilter?: ReplyFilter;
+	likedOnly: boolean;
+	bookmarkedOnly: boolean;
+	selectedAccountId?: string;
+	refreshTick: number;
+	until?: string;
+	untilId?: string;
+}) {
+	const params = new URLSearchParams({
+		resource,
+		limit: String(PAGE_SIZE),
+	});
+	if (selectedAccountId) params.set("account", selectedAccountId);
+	params.set("refresh", String(refreshTick));
+	if (replyFilter) params.set("replyFilter", replyFilter);
+	if (likedOnly) params.set("liked", "true");
+	if (bookmarkedOnly) params.set("bookmarked", "true");
+	if (search.trim()) params.set("search", search.trim());
+	if (until) params.set("until", until);
+	if (untilId) params.set("untilId", untilId);
+	params.sort();
+	const base =
+		typeof window === "undefined"
+			? "http://birdclaw.local"
+			: window.location.origin;
+	return new URL(`/api/query?${params.toString()}`, base).toString();
+}
+
+function timelineViewCacheKey(requestUrl: string) {
+	const url = new URL(requestUrl, "http://birdclaw.local");
+	url.searchParams.delete("refresh");
+	return `${TIMELINE_VIEW_CACHE_PREFIX}${url.pathname}?${url.searchParams.toString()}`;
+}
+
 export function useTimelineRouteData({
 	resource,
 	search,
@@ -31,75 +95,98 @@ export function useTimelineRouteData({
 	likedOnly = false,
 	bookmarkedOnly = false,
 }: UseTimelineRouteDataOptions) {
-	const [meta, setMeta] = useState<QueryEnvelope | null>(null);
-	const [items, setItems] = useState<TimelineItem[]>([]);
-	const [loading, setLoading] = useState(true);
+	const [meta, setMeta] = useState<QueryEnvelope | null>(
+		() => readCachedQueryEnvelope() ?? null,
+	);
+	const selectedAccountId = useSelectedAccountId(meta?.accounts);
+	const debouncedSearch = useDebouncedValue(search, 180);
+	const initialRequestUrl = buildTimelineQueryUrl({
+		resource,
+		search: debouncedSearch,
+		replyFilter,
+		likedOnly,
+		bookmarkedOnly,
+		selectedAccountId,
+		refreshTick: 0,
+	});
+	const initialSnapshot = useRef(
+		readClientCache<TimelineViewSnapshot>(
+			timelineViewCacheKey(initialRequestUrl),
+			TIMELINE_VIEW_CACHE_MAX_AGE_MS,
+		),
+	);
+	const [items, setItems] = useState<TimelineItem[]>(
+		() => initialSnapshot.current?.items ?? [],
+	);
+	const [loading, setLoading] = useState(() => !initialSnapshot.current);
 	const [error, setError] = useState<string | null>(null);
 	const [replyError, setReplyError] = useState<string | null>(null);
 	const [refreshTick, setRefreshTick] = useState(0);
-	const [hasMore, setHasMore] = useState(false);
+	const [hasMore, setHasMore] = useState(
+		() => initialSnapshot.current?.hasMore ?? false,
+	);
 	const [loadingMore, setLoadingMore] = useState(false);
-	const selectedAccountId = useSelectedAccountId(meta?.accounts);
 	// Bumped whenever the active filters change. A `loadMore` request that
 	// resolves against a stale generation is discarded so its older page is
 	// never appended to a freshly loaded feed.
 	const generationRef = useRef(0);
 	const loadMoreControllerRef = useRef<AbortController | null>(null);
+	const activeRequestUrlRef = useRef(initialRequestUrl);
 
-	async function loadStatus() {
-		setMeta(await fetchQueryEnvelope());
+	async function loadStatus(force = false) {
+		setMeta(await fetchQueryEnvelope(undefined, { force }));
 	}
 
 	useEffect(() => {
 		void loadStatus();
 	}, []);
 
-	// Build the /api/query URL for the current filters. Passing the last item's
-	// (createdAt, id) requests the next (older) page via the server's keyset
-	// cursor, which is deterministic across duplicate timestamps.
-	function buildQueryUrl(until?: string, untilId?: string) {
-		const url = new URL("/api/query", window.location.origin);
-		url.searchParams.set("resource", resource);
-		url.searchParams.set("refresh", String(refreshTick));
-		url.searchParams.set("limit", String(PAGE_SIZE));
-		if (selectedAccountId) {
-			url.searchParams.set("account", selectedAccountId);
-		}
-		if (replyFilter) {
-			url.searchParams.set("replyFilter", replyFilter);
-		}
-		if (likedOnly) {
-			url.searchParams.set("liked", "true");
-		}
-		if (bookmarkedOnly) {
-			url.searchParams.set("bookmarked", "true");
-		}
-		if (search.trim()) {
-			url.searchParams.set("search", search.trim());
-		}
-		if (until) {
-			url.searchParams.set("until", until);
-		}
-		if (untilId) {
-			url.searchParams.set("untilId", untilId);
-		}
-		return url;
-	}
-
 	useEffect(() => {
 		generationRef.current += 1;
 		loadMoreControllerRef.current?.abort();
 		const controller = new AbortController();
 		let active = true;
+		const requestUrl = buildTimelineQueryUrl({
+			resource,
+			search: debouncedSearch,
+			replyFilter,
+			likedOnly,
+			bookmarkedOnly,
+			selectedAccountId,
+			refreshTick,
+		});
+		const viewCacheKey = timelineViewCacheKey(requestUrl);
+		activeRequestUrlRef.current = requestUrl;
 		setError(null);
-		setLoading(true);
 		setLoadingMore(false);
-		fetchQueryResponse(buildQueryUrl(), { signal: controller.signal })
+		const cached = readClientCache<TimelineViewSnapshot>(
+			viewCacheKey,
+			TIMELINE_VIEW_CACHE_MAX_AGE_MS,
+		);
+		if (cached) {
+			setItems(cached.items);
+			setHasMore(cached.hasMore);
+			setLoading(false);
+			return () => {
+				active = false;
+				controller.abort();
+			};
+		}
+
+		setItems([]);
+		setHasMore(false);
+		setLoading(true);
+		fetchCachedQueryResponse(requestUrl, { signal: controller.signal })
 			.then((data) => {
 				if (!active) return;
 				const next = data.items as TimelineItem[];
 				setItems(next);
-				setHasMore(next.length >= PAGE_SIZE);
+				const nextHasMore = next.length >= PAGE_SIZE;
+				setHasMore(nextHasMore);
+				writeClientCache(viewCacheKey, {
+					items: next,
+					hasMore: nextHasMore,
+				});
 			})
 			.catch((fetchError: unknown) => {
 				if (
@@ -127,12 +214,12 @@ export function useTimelineRouteData({
 		};
 	}, [
 		bookmarkedOnly,
+		debouncedSearch,
 		errorFallback,
 		likedOnly,
 		refreshTick,
 		replyFilter,
 		resource,
-		search,
 		selectedAccountId,
 	]);
 
@@ -147,7 +234,13 @@ export function useTimelineRouteData({
 		loadMoreControllerRef.current = controller;
 		setLoadingMore(true);
 		try {
-			const data = await fetchQueryResponse(buildQueryUrl(until, untilId), {
+			const nextPageUrl = new URL(
+				activeRequestUrlRef.current,
+				window.location.origin,
+			);
+			nextPageUrl.searchParams.set("until", until);
+			nextPageUrl.searchParams.set("untilId", untilId);
+			const data = await fetchCachedQueryResponse(nextPageUrl, {
 				signal: controller.signal,
 			});
 			// Discard if the filters changed (new generation) while in flight.
@@ -155,7 +248,12 @@ export function useTimelineRouteData({
 			const page = data.items as TimelineItem[];
 			setItems((prev) => {
 				const seen = new Set(prev.map((item) => item.id));
-				return [...prev, ...page.filter((item) => !seen.has(item.id))];
+				const next = [...prev, ...page.filter((item) => !seen.has(item.id))];
+				writeClientCache(timelineViewCacheKey(activeRequestUrlRef.current), {
+					items: next,
+					hasMore: page.length >= PAGE_SIZE,
+				});
+				return next;
 			});
 			setHasMore(page.length >= PAGE_SIZE);
 		} catch (loadError) {
@@ -175,12 +273,16 @@ export function useTimelineRouteData({
 	}
 
 	function retry() {
+		invalidateCachedQueryResponse(activeRequestUrlRef.current);
+		deleteClientCache(timelineViewCacheKey(activeRequestUrlRef.current));
 		setRefreshTick((value) => value + 1);
 	}
 
 	function refreshLocalView() {
+		invalidateCachedQueryResponses();
+		deleteClientCacheByPrefix(TIMELINE_VIEW_CACHE_PREFIX);
 		setRefreshTick((value) => value + 1);
-		void loadStatus();
+		void loadStatus(true);
 	}
 
 	async function replyToTweet(tweetId: string) {

package/src/lib/api-client.ts

@@ -1,5 +1,11 @@
 import { Data, Effect } from "effect";
 import { z } from "zod";
+import {
+	deleteClientCache,
+	deleteClientCacheByPrefix,
+	loadClientCache,
+	readClientCache,
+} from "./client-cache";
 import { runEffectPromise } from "./effect-runtime";
 import type {
 	DmConversationItem,
@@ -105,6 +111,15 @@ const webSyncJobSchema = z
 
 const actionResponseSchema = jsonRecordSchema;
 const SYNC_POLL_INTERVAL_MS = 500;
+const STATUS_CACHE_KEY = "api:/status";
+const QUERY_CACHE_PREFIX = "api:/query:";
+const STATUS_CACHE_MAX_AGE_MS = 60_000;
+const QUERY_CACHE_MAX_AGE_MS = 5 * 60_000;
+
+interface ClientFetchCacheOptions {
+	force?: boolean;
+	maxAgeMs?: number;
+}
 
 export class ApiFetchError extends Data.TaggedError("ApiFetchError")<{
 	readonly message: string;
@@ -148,6 +163,55 @@ function runApiEffect<T, E>(effect: Effect.Effect<T, E>) {
 	return runEffectPromise(effect);
 }
 
+function splitSignal(init?: RequestInit) {
+	if (!init) return { requestInit: undefined, signal: undefined };
+	const { signal, ...requestInit } = init;
+	return { requestInit, signal: signal ?? undefined };
+}
+
+function waitForSignal<T>(promise: Promise<T>, signal?: AbortSignal) {
+	if (!signal) return promise;
+	if (signal.aborted) {
+		return Promise.reject(
+			new DOMException("The operation was aborted.", "AbortError"),
+		);
+	}
+
+	return new Promise<T>((resolve, reject) => {
+		const onAbort = () => {
+			reject(new DOMException("The operation was aborted.", "AbortError"));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then(
+			(value) => {
+				signal.removeEventListener("abort", onAbort);
+				resolve(value);
+			},
+			(error: unknown) => {
+				signal.removeEventListener("abort", onAbort);
+				reject(error);
+			},
+		);
+	});
+}
+
+function queryCacheKey(input: RequestInfo | URL) {
+	const raw =
+		typeof input === "string"
+			? input
+			: input instanceof URL
+				? input.toString()
+				: input.url;
+	const base =
+		typeof window === "undefined"
+			? "http://birdclaw.local"
+			: window.location.origin;
+	const url = new URL(raw, base);
+	url.searchParams.delete("refresh");
+	url.searchParams.sort();
+	return `${QUERY_CACHE_PREFIX}${url.pathname}?${url.searchParams.toString()}`;
+}
+
 export function fetchJsonEffect<T>(
 	input: RequestInfo | URL,
 	init: RequestInit | undefined,
@@ -191,8 +255,27 @@ export function fetchJson<T>(
 	return runApiEffect(fetchJsonEffect(input, init, schema, fallbackMessage));
 }
 
-export function fetchQueryEnvelope(init?: RequestInit) {
-	return runApiEffect(fetchQueryEnvelopeEffect(init));
+export function readCachedQueryEnvelope() {
+	return readClientCache<QueryEnvelope>(
+		STATUS_CACHE_KEY,
+		STATUS_CACHE_MAX_AGE_MS,
+	);
+}
+
+export function fetchQueryEnvelope(
+	init?: RequestInit,
+	{
+		force = false,
+		maxAgeMs = STATUS_CACHE_MAX_AGE_MS,
+	}: ClientFetchCacheOptions = {},
+) {
+	const { requestInit, signal } = splitSignal(init);
+	const request = loadClientCache(
+		STATUS_CACHE_KEY,
+		() => runApiEffect(fetchQueryEnvelopeEffect(requestInit)),
+		{ force, maxAgeMs },
+	);
+	return waitForSignal(request, signal);
 }
 
 export function fetchQueryEnvelopeEffect(init?: RequestInit) {
@@ -211,6 +294,38 @@ export function fetchQueryResponse(
 	return runApiEffect(fetchQueryResponseEffect(input, init));
 }
 
+export function readCachedQueryResponse(input: RequestInfo | URL) {
+	return readClientCache<QueryResponse>(
+		queryCacheKey(input),
+		QUERY_CACHE_MAX_AGE_MS,
+	);
+}
+
+export function fetchCachedQueryResponse(
+	input: RequestInfo | URL,
+	init?: RequestInit,
+	{
+		force = false,
+		maxAgeMs = QUERY_CACHE_MAX_AGE_MS,
+	}: ClientFetchCacheOptions = {},
+) {
+	const { requestInit, signal } = splitSignal(init);
+	const request = loadClientCache(
+		queryCacheKey(input),
+		() => runApiEffect(fetchQueryResponseEffect(input, requestInit)),
+		{ force, maxAgeMs },
+	);
+	return waitForSignal(request, signal);
+}
+
+export function invalidateCachedQueryResponse(input: RequestInfo | URL) {
+	deleteClientCache(queryCacheKey(input));
+}
+
+export function invalidateCachedQueryResponses() {
+	deleteClientCacheByPrefix(QUERY_CACHE_PREFIX);
+}
+
 export function fetchQueryResponseEffect(
 	input: RequestInfo | URL,
 	init?: RequestInit,

package/src/lib/archive-finder.ts

@@ -8,11 +8,16 @@ import { runEffectPromise, tryPromise } from "./effect-runtime";
 import type { ArchiveCandidate } from "./types";
 
 const execAsync = promisify(exec);
+const ARCHIVE_DISCOVERY_CACHE_MS = 5 * 60_000;
 const ARCHIVE_NAME_PATTERNS = [
 	/^twitter-.*\.zip$/i,
 	/^x-.*\.zip$/i,
 	/archive.*\.zip$/i,
 ];
+let archiveDiscoveryCache:
+	| { value: ArchiveCandidate[]; updatedAt: number }
+	| undefined;
+let archiveDiscoveryInFlight: Promise<ArchiveCandidate[]> | undefined;
 
 function formatFileSize(bytes: number): string {
 	const units = ["B", "KB", "MB", "GB"];
@@ -142,6 +147,39 @@ export function findArchivesEffect(): Effect.Effect<
 	});
 }
 
+export function findArchivesCachedEffect(): Effect.Effect<
+	ArchiveCandidate[],
+	unknown
+> {
+	return Effect.suspend(() => {
+		const cached = archiveDiscoveryCache;
+		if (cached && Date.now() - cached.updatedAt < ARCHIVE_DISCOVERY_CACHE_MS) {
+			return Effect.succeed(cached.value);
+		}
+		if (archiveDiscoveryInFlight) {
+			return Effect.promise(() => archiveDiscoveryInFlight!);
+		}
+
+		const request = runEffectPromise(findArchivesEffect())
+			.then((value) => {
+				archiveDiscoveryCache = { value, updatedAt: Date.now() };
+				return value;
+			})
+			.finally(() => {
+				if (archiveDiscoveryInFlight === request) {
+					archiveDiscoveryInFlight = undefined;
+				}
+			});
+		archiveDiscoveryInFlight = request;
+		return Effect.promise(() => request);
+	});
+}
+
 export function findArchives(): Promise<ArchiveCandidate[]> {
 	return runEffectPromise(findArchivesEffect());
 }
+
+export function clearArchiveFinderCacheForTests() {
+	archiveDiscoveryCache = undefined;
+	archiveDiscoveryInFlight = undefined;
+}

package/src/lib/authored-live.ts

@@ -3,6 +3,7 @@ import { Effect } from "effect";
 import { getNativeDb } from "./db";
 import { runEffectPromise, tryPromise } from "./effect-runtime";
 import { readSyncCache, writeSyncCache } from "./sync-cache";
+import { tweetEntitiesFromXurl } from "./tweet-render";
 import type {
 	TweetEntities,
 	TweetMediaItem,
@@ -523,68 +524,7 @@ function toMentionData(tweet: XurlUserTweet, fallbackAuthorId: string) {
 }
 
 function toLocalEntities(tweet: XurlMentionData): TweetEntities {
-	const raw = tweet.entities;
-	if (!raw || typeof raw !== "object") {
-		return {};
-	}
-
-	const entities = raw as Record<string, unknown>;
-	const rawMentions = Array.isArray(entities.mentions) ? entities.mentions : [];
-	const rawUrls = Array.isArray(entities.urls) ? entities.urls : [];
-	const rawHashtags = Array.isArray(entities.hashtags) ? entities.hashtags : [];
-
-	return {
-		...(rawMentions.length
-			? {
-					mentions: rawMentions.map((mention) => {
-						const value =
-							mention && typeof mention === "object"
-								? (mention as Record<string, unknown>)
-								: {};
-						return {
-							username: String(value.username ?? ""),
-							id: typeof value.id === "string" ? String(value.id) : undefined,
-							start: Number(value.start ?? 0),
-							end: Number(value.end ?? 0),
-						};
-					}),
-				}
-			: {}),
-		...(rawUrls.length
-			? {
-					urls: rawUrls.map((url) => {
-						const value =
-							url && typeof url === "object"
-								? (url as Record<string, unknown>)
-								: {};
-						return {
-							url: String(value.url ?? ""),
-							expandedUrl: String(value.expanded_url ?? value.url ?? ""),
-							displayUrl: String(
-								value.display_url ?? value.expanded_url ?? value.url ?? "",
-							),
-							start: Number(value.start ?? 0),
-							end: Number(value.end ?? 0),
-						};
-					}),
-				}
-			: {}),
-		...(rawHashtags.length
-			? {
-					hashtags: rawHashtags.map((hashtag) => {
-						const value =
-							hashtag && typeof hashtag === "object"
-								? (hashtag as Record<string, unknown>)
-								: {};
-						return {
-							tag: String(value.tag ?? ""),
-							start: Number(value.start ?? 0),
-							end: Number(value.end ?? 0),
-						};
-					}),
-				}
-			: {}),
-	};
+	return tweetEntitiesFromXurl(tweet.entities);
 }
 
 function toMediaType(type: string): TweetMediaItem["type"] {

package/src/lib/bird.ts

@@ -29,6 +29,12 @@ interface BirdTweetAuthor {
 	name?: string;
 }
 
+interface BirdTweetArticle {
+	title?: string;
+	previewText?: string;
+	coverImageUrl?: string;
+}
+
 interface BirdTweetItem {
 	id: string;
 	text: string;
@@ -45,6 +51,7 @@ interface BirdTweetItem {
 	author?: BirdTweetAuthor;
 	authorId?: string;
 	media?: BirdTweetMedia[];
+	article?: BirdTweetArticle | null;
 }
 
 export interface BirdDmUser {
@@ -385,6 +392,29 @@ function toMediaEntities(media: BirdTweetMedia[] | undefined) {
 	};
 }
 
+function toTweetEntities(item: BirdTweetItem) {
+	const mediaEntities = toMediaEntities(item.media);
+	const title = item.article?.title?.trim();
+	if (!title) return mediaEntities;
+	const handle = item.author?.username?.replace(/^@/, "");
+	const url = handle
+		? `https://x.com/${handle}/status/${item.id}`
+		: `https://x.com/i/status/${item.id}`;
+	return {
+		...mediaEntities,
+		article: {
+			title,
+			url,
+			...(item.article?.previewText?.trim()
+				? { previewText: item.article.previewText.trim() }
+				: {}),
+			...(item.article?.coverImageUrl?.trim()
+				? { coverImageUrl: item.article.coverImageUrl.trim() }
+				: {}),
+		},
+	};
+}
+
 function toReferencedTweets(item: BirdTweetItem) {
 	const references: XurlReferencedTweet[] = [];
 	if (typeof item.inReplyToStatusId === "string" && item.inReplyToStatusId) {
@@ -434,7 +464,7 @@ function normalizeBirdTweets(items: BirdTweetItem[]): XurlMentionsResponse {
 			text: item.text,
 			created_at: toIsoTimestamp(item.createdAt),
 			conversation_id: item.conversationId ?? item.id,
-			entities: toMediaEntities(item.media),
+			entities: toTweetEntities(item),
 			referenced_tweets: toReferencedTweets(item),
 			public_metrics: {
 				reply_count: Number(item.replyCount ?? 0),
@@ -1104,6 +1134,7 @@ export const __test__ = {
 	getBirdTweetItems,
 	getBirdTweetItem,
 	toMediaEntities,
+	toTweetEntities,
 	toReferencedTweets,
 	normalizeBirdTweets,
 };