birdclaw 0.5.1 → 0.7.0

package/src/lib/mentions-live.ts

@@ -1,7 +1,12 @@
 import type { Database } from "./sqlite";
-import { listMentionsViaBird } from "./bird";
+import { Effect } from "effect";
+import {
+	getAuthenticatedBirdAccountEffect,
+	listMentionsViaBirdEffect,
+} from "./bird";
 import type { MentionsDataSource } from "./config";
 import { getNativeDb } from "./db";
+import { runEffectPromise, tryPromise } from "./effect-runtime";
 import { buildMediaJsonFromIncludes, countTweetMedia } from "./media-includes";
 import { serializeMentionItemsAsXurlCompatible } from "./mentions-export";
 import { listTimelineItems } from "./queries";
@@ -22,6 +27,38 @@ export const DEFAULT_MENTIONS_CACHE_TTL_MS = 2 * 60_000;
 const MIN_XURL_MENTIONS_LIMIT = 5;
 const MAX_XURL_MENTIONS_LIMIT = 100;
 type MentionSyncMode = Exclude<MentionsDataSource, "birdclaw">;
+type MentionLiveSource = Exclude<MentionSyncMode, "auto">;
+export interface MentionsProgress {
+	source: "bird" | "xurl" | "cache";
+	fetched: number;
+	total?: number;
+	page?: number;
+	maxPages?: number;
+	pageSize?: number;
+	done: boolean;
+}
+export interface SyncMentionsOptions {
+	account?: string;
+	mode?: string;
+	limit?: number;
+	maxPages?: number;
+	refresh?: boolean;
+	cacheTtlMs?: number;
+	sinceId?: string;
+	startTime?: string;
+	onProgress?: (progress: MentionsProgress) => void;
+}
+interface ExportMentionsViaCachedLiveSourceOptions {
+	mode: MentionSyncMode;
+	account?: string;
+	search?: string;
+	replyFilter?: ReplyFilter;
+	limit?: number;
+	all?: boolean;
+	maxPages?: number;
+	refresh?: boolean;
+	cacheTtlMs?: number;
+}
 type MentionScanBoundary =
 	| { kind: "auto" }
 	| { kind: "since"; sinceId: string }
@@ -29,7 +66,7 @@ type MentionScanBoundary =
 	| { kind: "unbounded" };
 interface MentionScanShape {
 	endpoint: "mentions";
-	mode: MentionSyncMode;
+	mode: MentionLiveSource;
 	accountId: string;
 	pageSize: number;
 	boundary: MentionScanBoundary;
@@ -44,6 +81,17 @@ interface MentionHighWaterValue {
 	sinceId: string;
 }
 
+function toError(error: unknown) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+
+function trySync<T>(try_: () => T) {
+	return Effect.try({
+		try: try_,
+		catch: toError,
+	});
+}
+
 function getMentionsFetchModeKey({
 	scope,
 	mode,
@@ -133,7 +181,7 @@ function getMentionHighWaterKey({
 	mode,
 	accountId,
 }: {
-	mode: MentionSyncMode;
+	mode: MentionLiveSource;
 	accountId: string;
 }) {
 	return `mentions:sync:high-water:v1:mode=${mode}:account=${encodeCacheKeyPart(accountId)}`;
@@ -234,9 +282,9 @@ function parseMaxPages(value?: number) {
 }
 
 function parseSyncMode(value?: string): MentionSyncMode {
-	const mode = value ?? "xurl";
-	if (mode !== "bird" && mode !== "xurl") {
-		throw new Error("--mode must be bird or xurl");
+	const mode = value ?? "auto";
+	if (mode !== "auto" && mode !== "bird" && mode !== "xurl") {
+		throw new Error("--mode must be auto, bird, or xurl");
 	}
 	return mode;
 }
@@ -358,7 +406,7 @@ function getNewestMentionId(payload: XurlMentionsResponse) {
 
 function readMentionHighWaterId(
 	db: Database,
-	mode: MentionSyncMode,
+	mode: MentionLiveSource,
 	accountId: string,
 ) {
 	const cached = readSyncCache<MentionHighWaterValue>(
@@ -372,7 +420,7 @@ function readMentionHighWaterId(
 
 function writeMentionHighWaterId(
 	db: Database,
-	mode: MentionSyncMode,
+	mode: MentionLiveSource,
 	accountId: string,
 	sinceId: string | undefined,
 ) {
@@ -385,18 +433,24 @@ function writeMentionHighWaterId(
 function resolveAccount(db: Database, accountId?: string) {
 	const row = accountId
 		? (db
-				.prepare("select id, handle from accounts where id = ?")
-				.get(accountId) as { id: string; handle: string } | undefined)
+				.prepare(
+					"select id, handle, external_user_id from accounts where id = ?",
+				)
+				.get(accountId) as
+				| { id: string; handle: string; external_user_id: string | null }
+				| undefined)
 		: (db
 				.prepare(
 					`
-          select id, handle
+          select id, handle, external_user_id
           from accounts
           order by is_default desc, created_at asc
           limit 1
           `,
 				)
-				.get() as { id: string; handle: string } | undefined);
+				.get() as
+				| { id: string; handle: string; external_user_id: string | null }
+				| undefined);
 
 	if (!row) {
 		throw new Error(`Unknown account: ${accountId ?? "default"}`);
@@ -405,9 +459,45 @@ function resolveAccount(db: Database, accountId?: string) {
 	return {
 		accountId: row.id,
 		username: row.handle.replace(/^@/, ""),
+		externalUserId:
+			typeof row.external_user_id === "string" &&
+			row.external_user_id.trim().length > 0
+				? row.external_user_id.trim()
+				: undefined,
 	};
 }
 
+function verifyBirdAccountMatchesEffect({
+	accountId,
+	username,
+	externalUserId,
+}: ReturnType<typeof resolveAccount>) {
+	return Effect.gen(function* () {
+		const authenticated = yield* getAuthenticatedBirdAccountEffect();
+		if (
+			externalUserId &&
+			authenticated.id &&
+			authenticated.id === externalUserId
+		) {
+			return;
+		}
+		if (externalUserId && authenticated.id) {
+			return yield* Effect.fail(
+				new Error(
+					`bird is authenticated as user ${authenticated.id}; refusing to sync into ${accountId} (${externalUserId})`,
+				),
+			);
+		}
+		if (authenticated.username.toLowerCase() !== username.toLowerCase()) {
+			return yield* Effect.fail(
+				new Error(
+					`bird is authenticated as @${authenticated.username}; refusing to sync into ${accountId} (@${username})`,
+				),
+			);
+		}
+	});
+}
+
 function findNewestArchiveMentionId(db: Database, accountId: string) {
 	const row = db
 		.prepare(
@@ -655,7 +745,7 @@ function mergeMentionPayloads(
 	};
 }
 
-async function fetchMentionsViaXurl({
+function fetchMentionsViaXurlEffect({
 	resolvedAccount,
 	limit,
 	all,
@@ -663,6 +753,7 @@ async function fetchMentionsViaXurl({
 	sinceId,
 	startPaginationToken,
 	startTime,
+	onProgress,
 }: {
 	resolvedAccount: ReturnType<typeof resolveAccount>;
 	limit: number;
@@ -671,44 +762,71 @@ async function fetchMentionsViaXurl({
 	sinceId?: string;
 	startPaginationToken?: string;
 	startTime?: string;
+	onProgress?: (progress: MentionsProgress) => void;
 }) {
-	const [accountUser] = await lookupUsersByHandles([resolvedAccount.username]);
-	if (!accountUser?.id) {
-		throw new Error(
-			`Could not resolve Twitter user id for @${resolvedAccount.username}`,
-		);
-	}
+	return Effect.gen(function* () {
+		const accountUserId =
+			resolvedAccount.externalUserId ??
+			(yield* tryPromise(() =>
+				lookupUsersByHandles([resolvedAccount.username]),
+			).pipe(Effect.map((users) => users[0]?.id)));
+		if (!accountUserId) {
+			return yield* Effect.fail(
+				new Error(
+					`Could not resolve Twitter user id for @${resolvedAccount.username}`,
+				),
+			);
+		}
 
-	const pages: XurlMentionsResponse[] = [];
-	let nextToken: string | undefined = startPaginationToken;
-	let pageCount = 0;
-	do {
-		const payload = await listMentionsViaXurl({
-			maxResults: limit,
-			username: resolvedAccount.username,
-			userId: String(accountUser.id),
-			paginationToken: nextToken,
-			...(sinceId ? { sinceId } : {}),
-			...(startTime ? { startTime } : {}),
-		});
-		pages.push(payload);
-		const metaNextToken =
-			typeof payload.meta?.next_token === "string"
-				? payload.meta.next_token
-				: undefined;
-		nextToken = metaNextToken;
-		pageCount += 1;
-	} while (
-		all &&
-		nextToken &&
-		(parsedMaxPages === null || pageCount < parsedMaxPages)
-	);
+		const pages: XurlMentionsResponse[] = [];
+		let nextToken: string | undefined = startPaginationToken;
+		let pageCount = 0;
+		do {
+			const payload = yield* tryPromise(() =>
+				listMentionsViaXurl({
+					maxResults: limit,
+					username: resolvedAccount.username,
+					userId: String(accountUserId),
+					paginationToken: nextToken,
+					...(sinceId ? { sinceId } : {}),
+					...(startTime ? { startTime } : {}),
+				}),
+			);
+			pages.push(payload);
+			const metaNextToken =
+				typeof payload.meta?.next_token === "string"
+					? payload.meta.next_token
+					: undefined;
+			nextToken = metaNextToken;
+			pageCount += 1;
+			const fetched = pages.reduce((sum, item) => sum + item.data.length, 0);
+			const done =
+				!all ||
+				!nextToken ||
+				(parsedMaxPages !== null && pageCount >= parsedMaxPages);
+			yield* Effect.sync(() =>
+				onProgress?.({
+					source: "xurl",
+					fetched,
+					total: parsedMaxPages === null ? undefined : parsedMaxPages * limit,
+					page: pageCount,
+					maxPages: parsedMaxPages ?? undefined,
+					pageSize: limit,
+					done,
+				}),
+			);
+		} while (
+			all &&
+			nextToken &&
+			(parsedMaxPages === null || pageCount < parsedMaxPages)
+		);
 
-	return mergeMentionPayloads(pages);
+		return mergeMentionPayloads(pages);
+	});
 }
 
-async function fetchMentionsViaBird({ limit }: { limit: number }) {
-	return listMentionsViaBird({ maxResults: limit });
+function fetchMentionsViaBirdEffect({ limit }: { limit: number }) {
+	return listMentionsViaBirdEffect({ maxResults: limit });
 }
 
 function isMaxPagesPartial({
@@ -725,7 +843,7 @@ function isMaxPagesPartial({
 	);
 }
 
-export async function syncMentions({
+export function syncMentionsEffect({
 	account,
 	mode,
 	limit = 20,
@@ -734,222 +852,290 @@ export async function syncMentions({
 	cacheTtlMs,
 	sinceId,
 	startTime,
-}: {
-	account?: string;
-	mode?: string;
-	limit?: number;
-	maxPages?: number;
-	refresh?: boolean;
-	cacheTtlMs?: number;
-	sinceId?: string;
-	startTime?: string;
-}) {
-	const parsedMode = parseSyncMode(mode);
-	const explicitSinceId = sinceId?.trim() || undefined;
-	const explicitStartTime = startTime?.trim() || undefined;
-	if (parsedMode === "bird" && (explicitSinceId || explicitStartTime)) {
-		throw new Error("bird mode does not support --since-id or --start-time");
-	}
-	if (parsedMode === "xurl") {
-		assertXurlLimit(limit);
-	} else {
-		assertBirdLimit(limit);
-	}
-	const parsedMaxPages = parseMaxPages(maxPages);
-	const fetchAll = parsedMode === "xurl" && parsedMaxPages !== null;
-	const db = getNativeDb();
-	const resolvedAccount = resolveAccount(db, account);
-	const cursorShape: MentionScanShape = {
-		endpoint: "mentions",
-		mode: parsedMode,
-		accountId: resolvedAccount.accountId,
-		pageSize: limit,
-		boundary: getMentionCursorBoundary({
-			explicitSinceId,
-			explicitStartTime,
-		}),
-	};
-	const cursorKey = getMentionCursorKey(cursorShape);
-	const legacyCursorKeys = getLegacyMentionCursorKeys(cursorShape);
-	const cursor =
-		parsedMode === "xurl"
-			? readMentionCursor({
-					db,
-					shape: cursorShape,
-					cursorKey,
-					legacyCursorKeys,
-				})
-			: undefined;
-	const startPaginationToken = cursor?.token;
-	const cursorSinceId =
-		cursor?.boundary?.kind === "since" ? cursor.boundary.sinceId : undefined;
-	const cursorStartTime =
-		cursor?.boundary?.kind === "start" ? cursor.boundary.startTime : undefined;
-	const committedSinceId =
-		parsedMode === "xurl" &&
-		cursorShape.boundary.kind === "auto" &&
-		!startPaginationToken
-			? readMentionHighWaterId(db, parsedMode, resolvedAccount.accountId)
-			: undefined;
-	const seededSinceId =
-		parsedMode === "xurl" &&
-		!explicitSinceId &&
-		!explicitStartTime &&
-		!startPaginationToken
-			? (committedSinceId ??
-				findNewestArchiveMentionId(db, resolvedAccount.accountId))
-			: undefined;
-	const resolvedSinceId = startPaginationToken
-		? cursorSinceId
-		: (explicitSinceId ?? seededSinceId);
-	const resolvedStartTime = startPaginationToken
-		? cursorStartTime
-		: !resolvedSinceId
-			? explicitStartTime
-			: undefined;
-	const resultShape: MentionScanShape = {
-		endpoint: "mentions",
-		mode: parsedMode,
-		accountId: resolvedAccount.accountId,
-		pageSize: limit,
-		boundary: getMentionRequestBoundary({
-			sinceId: resolvedSinceId,
-			startTime: resolvedStartTime,
-		}),
-	};
-	const resultCacheKey = getMentionResultCacheKey({
-		shape: resultShape,
-		all: fetchAll,
-		maxPages: parsedMaxPages,
-	});
-	const ttlMs = parseCacheTtlMs(cacheTtlMs);
-	const cached = startPaginationToken
-		? null
-		: readSyncCache<XurlMentionsResponse>(resultCacheKey, db);
-	const cachedPaginationToken = getCachedPaginationToken(cached);
-	const cacheAgeMs = cached
-		? Date.now() - new Date(cached.updatedAt).getTime()
-		: Number.POSITIVE_INFINITY;
-
-	if (
-		!startPaginationToken &&
-		!cachedPaginationToken &&
-		!refresh &&
-		cached &&
-		cacheAgeMs <= ttlMs
-	) {
-		mergeMentionsIntoLocalStore(
-			db,
-			resolvedAccount.accountId,
-			cached.value,
-			parsedMode,
-		);
-		return {
-			ok: true,
-			source: "cache",
-			kind: "mentions",
+	onProgress,
+}: SyncMentionsOptions) {
+	return Effect.gen(function* () {
+		const parsedMode = yield* trySync(() => parseSyncMode(mode));
+		const primaryMode: MentionLiveSource =
+			parsedMode === "auto" ? "xurl" : parsedMode;
+		const explicitSinceId = sinceId?.trim() || undefined;
+		const explicitStartTime = startTime?.trim() || undefined;
+		if (primaryMode === "bird" && (explicitSinceId || explicitStartTime)) {
+			return yield* Effect.fail(
+				new Error("bird mode does not support --since-id or --start-time"),
+			);
+		}
+		if (primaryMode === "xurl") {
+			yield* trySync(() => assertXurlLimit(limit));
+		} else {
+			yield* trySync(() => assertBirdLimit(limit));
+		}
+		const parsedMaxPages = yield* trySync(() => parseMaxPages(maxPages));
+		const fetchAll =
+			primaryMode === "xurl" &&
+			(parsedMaxPages !== null ||
+				Boolean(explicitSinceId || explicitStartTime));
+		const db = yield* trySync(() => getNativeDb());
+		const resolvedAccount = yield* trySync(() => resolveAccount(db, account));
+		const cursorShape: MentionScanShape = {
+			endpoint: "mentions",
+			mode: primaryMode,
 			accountId: resolvedAccount.accountId,
-			count: cached.value.data.length,
-			partial: isMaxPagesPartial({
-				payload: cached.value,
-				maxPages: parsedMaxPages,
+			pageSize: limit,
+			boundary: getMentionCursorBoundary({
+				explicitSinceId,
+				explicitStartTime,
 			}),
-			payload: cached.value,
 		};
-	}
-
-	if (
-		parsedMode === "xurl" &&
-		!explicitSinceId &&
-		!explicitStartTime &&
-		!startPaginationToken &&
-		!seededSinceId
-	) {
-		console.error(
-			"No local mention baseline found; syncing mentions from the newest page backwards.",
-		);
-	}
+		const cursorKey = getMentionCursorKey(cursorShape);
+		const legacyCursorKeys = getLegacyMentionCursorKeys(cursorShape);
+		const cursor =
+			primaryMode === "xurl"
+				? yield* trySync(() =>
+						readMentionCursor({
+							db,
+							shape: cursorShape,
+							cursorKey,
+							legacyCursorKeys,
+						}),
+					)
+				: undefined;
+		const startPaginationToken = cursor?.token;
+		const cursorSinceId =
+			cursor?.boundary?.kind === "since" ? cursor.boundary.sinceId : undefined;
+		const cursorStartTime =
+			cursor?.boundary?.kind === "start"
+				? cursor.boundary.startTime
+				: undefined;
+		const committedSinceId =
+			primaryMode === "xurl" &&
+			cursorShape.boundary.kind === "auto" &&
+			!startPaginationToken
+				? yield* trySync(() =>
+						readMentionHighWaterId(db, primaryMode, resolvedAccount.accountId),
+					)
+				: undefined;
+		const seededSinceId =
+			primaryMode === "xurl" &&
+			!explicitSinceId &&
+			!explicitStartTime &&
+			!startPaginationToken
+				? (committedSinceId ??
+					(yield* trySync(() =>
+						findNewestArchiveMentionId(db, resolvedAccount.accountId),
+					)))
+				: undefined;
+		const resolvedSinceId = startPaginationToken
+			? cursorSinceId
+			: (explicitSinceId ?? seededSinceId);
+		const resolvedStartTime = startPaginationToken
+			? cursorStartTime
+			: !resolvedSinceId
+				? explicitStartTime
+				: undefined;
+		const resultShape: MentionScanShape = {
+			endpoint: "mentions",
+			mode: primaryMode,
+			accountId: resolvedAccount.accountId,
+			pageSize: limit,
+			boundary: getMentionRequestBoundary({
+				sinceId: resolvedSinceId,
+				startTime: resolvedStartTime,
+			}),
+		};
+		const resultCacheKey = getMentionResultCacheKey({
+			shape: resultShape,
+			all: fetchAll,
+			maxPages: parsedMaxPages,
+		});
+		const ttlMs = parseCacheTtlMs(cacheTtlMs);
+		const cached = startPaginationToken
+			? null
+			: yield* trySync(() =>
+					readSyncCache<XurlMentionsResponse>(resultCacheKey, db),
+				);
+		const cachedPaginationToken = getCachedPaginationToken(cached);
+		const cacheAgeMs = cached
+			? Date.now() - new Date(cached.updatedAt).getTime()
+			: Number.POSITIVE_INFINITY;
 
-	const payload =
-		parsedMode === "bird"
-			? await fetchMentionsViaBird({ limit })
-			: await fetchMentionsViaXurl({
-					resolvedAccount,
-					limit,
-					all: fetchAll,
-					parsedMaxPages,
-					sinceId: resolvedSinceId,
-					startPaginationToken,
-					startTime: resolvedStartTime,
-				});
-	mergeMentionsIntoLocalStore(
-		db,
-		resolvedAccount.accountId,
-		payload,
-		parsedMode,
-	);
-	const payloadPaginationToken = getCachedPaginationToken({ value: payload });
-	if (parsedMode === "xurl") {
-		if (payloadPaginationToken) {
-			writeSyncCache(
-				cursorKey,
-				addMentionCursorState(
-					payload,
-					getMentionRequestBoundary({
-						sinceId: resolvedSinceId,
-						startTime: resolvedStartTime,
-					}),
-					maxNumericTweetId(resolvedSinceId, getNewestMentionId(payload)),
+		if (
+			!startPaginationToken &&
+			!cachedPaginationToken &&
+			!refresh &&
+			cached &&
+			cacheAgeMs <= ttlMs
+		) {
+			yield* trySync(() =>
+				mergeMentionsIntoLocalStore(
+					db,
+					resolvedAccount.accountId,
+					cached.value,
+					primaryMode,
 				),
-				db,
 			);
-			deleteSyncCache(resultCacheKey, db);
-			deleteSyncCache(
-				getMentionResultCacheKey({
-					shape: cursorShape,
-					all: fetchAll,
+			yield* Effect.sync(() =>
+				onProgress?.({
+					source: "cache",
+					fetched: cached.value.data.length,
+					total: parsedMaxPages === null ? undefined : parsedMaxPages * limit,
+					done: true,
+				}),
+			);
+			return {
+				ok: true,
+				source: "cache",
+				kind: "mentions",
+				accountId: resolvedAccount.accountId,
+				count: cached.value.data.length,
+				partial: isMaxPagesPartial({
+					payload: cached.value,
 					maxPages: parsedMaxPages,
 				}),
-				db,
+				payload: cached.value,
+			};
+		}
+
+		if (
+			primaryMode === "xurl" &&
+			!explicitSinceId &&
+			!explicitStartTime &&
+			!startPaginationToken &&
+			!seededSinceId
+		) {
+			console.error(
+				"No local mention baseline found; syncing mentions from the newest page backwards.",
 			);
-			for (const legacyKey of cursor?.legacyKeys ?? []) {
-				deleteSyncCache(legacyKey, db);
-			}
-		} else {
-			deleteSyncCache(cursorKey, db);
-			for (const legacyKey of legacyCursorKeys) {
-				deleteSyncCache(legacyKey, db);
-			}
-			if (cursorShape.boundary.kind === "auto") {
-				writeMentionHighWaterId(
-					db,
-					parsedMode,
-					resolvedAccount.accountId,
-					maxNumericTweetId(
-						resolvedSinceId,
-						cursor?.pendingNewestId,
-						getNewestMentionId(payload),
-					),
-				);
+		}
+
+		let source: MentionLiveSource = primaryMode;
+		const canFallbackToBird =
+			primaryMode === "xurl" &&
+			parsedMode === "auto" &&
+			!explicitSinceId &&
+			!explicitStartTime &&
+			!startPaginationToken;
+		const payload =
+			primaryMode === "bird"
+				? yield* fetchMentionsViaBirdEffect({ limit })
+				: yield* fetchMentionsViaXurlEffect({
+						resolvedAccount,
+						limit,
+						all: fetchAll,
+						parsedMaxPages,
+						sinceId: resolvedSinceId,
+						startPaginationToken,
+						startTime: resolvedStartTime,
+						onProgress,
+					}).pipe(
+						Effect.catchAll((error) => {
+							if (!canFallbackToBird) return Effect.fail(error);
+							source = "bird";
+							return verifyBirdAccountMatchesEffect(resolvedAccount).pipe(
+								Effect.flatMap(() => fetchMentionsViaBirdEffect({ limit })),
+							);
+						}),
+					);
+		if (source === "bird") {
+			yield* Effect.sync(() =>
+				onProgress?.({
+					source: "bird",
+					fetched: payload.data.length,
+					total: limit,
+					done: true,
+				}),
+			);
+		}
+		yield* trySync(() =>
+			mergeMentionsIntoLocalStore(
+				db,
+				resolvedAccount.accountId,
+				payload,
+				source,
+			),
+		);
+		const payloadPaginationToken = getCachedPaginationToken({ value: payload });
+		if (source === "xurl") {
+			if (payloadPaginationToken) {
+				yield* trySync(() => {
+					writeSyncCache(
+						cursorKey,
+						addMentionCursorState(
+							payload,
+							getMentionRequestBoundary({
+								sinceId: resolvedSinceId,
+								startTime: resolvedStartTime,
+							}),
+							maxNumericTweetId(resolvedSinceId, getNewestMentionId(payload)),
+						),
+						db,
+					);
+					deleteSyncCache(resultCacheKey, db);
+					deleteSyncCache(
+						getMentionResultCacheKey({
+							shape: cursorShape,
+							all: fetchAll,
+							maxPages: parsedMaxPages,
+						}),
+						db,
+					);
+					for (const legacyKey of cursor?.legacyKeys ?? []) {
+						deleteSyncCache(legacyKey, db);
+					}
+				});
+			} else {
+				yield* trySync(() => {
+					deleteSyncCache(cursorKey, db);
+					for (const legacyKey of legacyCursorKeys) {
+						deleteSyncCache(legacyKey, db);
+					}
+					if (cursorShape.boundary.kind === "auto") {
+						writeMentionHighWaterId(
+							db,
+							source,
+							resolvedAccount.accountId,
+							maxNumericTweetId(
+								resolvedSinceId,
+								cursor?.pendingNewestId,
+								getNewestMentionId(payload),
+							),
+						);
+					}
+				});
 			}
 		}
-	}
-	if (!payloadPaginationToken && !startPaginationToken) {
-		writeSyncCache(resultCacheKey, payload, db);
-	}
+		if (!payloadPaginationToken && !startPaginationToken) {
+			const writeCacheKey =
+				source === primaryMode
+					? resultCacheKey
+					: getMentionResultCacheKey({
+							shape: {
+								...resultShape,
+								mode: source,
+							},
+							all: false,
+							maxPages: null,
+						});
+			yield* trySync(() => writeSyncCache(writeCacheKey, payload, db));
+		}
 
-	return {
-		ok: true,
-		source: parsedMode,
-		kind: "mentions",
-		accountId: resolvedAccount.accountId,
-		count: payload.data.length,
-		partial: isMaxPagesPartial({ payload, maxPages: parsedMaxPages }),
-		payload,
-	};
+		return {
+			ok: true,
+			source,
+			kind: "mentions",
+			accountId: resolvedAccount.accountId,
+			count: payload.data.length,
+			partial: isMaxPagesPartial({ payload, maxPages: parsedMaxPages }),
+			payload,
+		};
+	});
+}
+
+export function syncMentions(options: SyncMentionsOptions) {
+	return runEffectPromise(syncMentionsEffect(options));
 }
 
-async function exportMentionsViaCachedLiveSource({
+function exportMentionsViaCachedLiveSourceEffect({
 	mode,
 	account,
 	search,
@@ -959,90 +1145,37 @@ async function exportMentionsViaCachedLiveSource({
 	maxPages,
 	refresh = false,
 	cacheTtlMs,
-}: {
-	mode: MentionsDataSource;
-	account?: string;
-	search?: string;
-	replyFilter?: ReplyFilter;
-	limit?: number;
-	all?: boolean;
-	maxPages?: number;
-	refresh?: boolean;
-	cacheTtlMs?: number;
-}) {
-	if (mode === "xurl") {
-		assertXurlLimit(limit);
-	} else {
-		assertBirdLimit(limit);
-	}
-	const parsedMaxPages = parseMaxPages(maxPages);
-	const fetchAll = mode === "xurl" && (all || parsedMaxPages !== null);
-
-	const db = getNativeDb();
-	const resolvedAccount = resolveAccount(db, account);
-	const cacheKey = getMentionsFetchModeKey({
-		scope: "export",
-		mode,
-		accountId: resolvedAccount.accountId,
-		pageSize: limit,
-		all: fetchAll,
-		maxPages: parsedMaxPages,
-		sinceId: null,
-		startTime: null,
-	});
-	const ttlMs = parseCacheTtlMs(cacheTtlMs);
-	const cached = readSyncCache<XurlMentionsResponse>(cacheKey, db);
-	const cacheAgeMs = cached
-		? Date.now() - new Date(cached.updatedAt).getTime()
-		: Number.POSITIVE_INFINITY;
-
-	if (!refresh && cached && cacheAgeMs <= ttlMs) {
-		if (
-			shouldReturnFilteredLocalPayload({
-				search,
-				replyFilter,
-			})
-		) {
-			return readLocalXurlCompatiblePayload({
-				accountId: resolvedAccount.accountId,
-				search,
-				replyFilter,
-				limit: fetchAll ? cached.value.data.length : limit,
-			});
-		}
-		return cached.value;
-	}
-
-	try {
-		const payload =
-			mode === "bird"
-				? await listMentionsViaBird({ maxResults: limit })
-				: await fetchMentionsViaXurl({
-						resolvedAccount,
-						limit,
-						all: fetchAll,
-						parsedMaxPages,
-					});
-		mergeMentionsIntoLocalStore(db, resolvedAccount.accountId, payload, mode);
-		writeSyncCache(cacheKey, payload, db);
-
-		if (
-			shouldReturnFilteredLocalPayload({
-				search,
-				replyFilter,
-			})
-		) {
-			return readLocalXurlCompatiblePayload({
-				accountId: resolvedAccount.accountId,
-				search,
-				replyFilter,
-				limit: fetchAll ? payload.data.length : limit,
-			});
+}: ExportMentionsViaCachedLiveSourceOptions) {
+	return Effect.gen(function* () {
+		const primaryMode: MentionLiveSource = mode === "auto" ? "xurl" : mode;
+		if (primaryMode === "xurl") {
+			yield* trySync(() => assertXurlLimit(limit));
+		} else {
+			yield* trySync(() => assertBirdLimit(limit));
 		}
-
-		return payload;
-	} catch (error) {
-		if (!refresh && cached) {
+		const parsedMaxPages = yield* trySync(() => parseMaxPages(maxPages));
+		const fetchAll = primaryMode === "xurl" && (all || parsedMaxPages !== null);
+
+		const db = yield* trySync(() => getNativeDb());
+		const resolvedAccount = yield* trySync(() => resolveAccount(db, account));
+		const cacheKey = getMentionsFetchModeKey({
+			scope: "export",
+			mode,
+			accountId: resolvedAccount.accountId,
+			pageSize: limit,
+			all: fetchAll,
+			maxPages: parsedMaxPages,
+			sinceId: null,
+			startTime: null,
+		});
+		const ttlMs = parseCacheTtlMs(cacheTtlMs);
+		const cached = yield* trySync(() =>
+			readSyncCache<XurlMentionsResponse>(cacheKey, db),
+		);
+		const cacheAgeMs = cached
+			? Date.now() - new Date(cached.updatedAt).getTime()
+			: Number.POSITIVE_INFINITY;
+		const readFilteredOrRaw = (payload: XurlMentionsResponse) => {
 			if (
 				shouldReturnFilteredLocalPayload({
 					search,
@@ -1053,35 +1186,97 @@ async function exportMentionsViaCachedLiveSource({
 					accountId: resolvedAccount.accountId,
 					search,
 					replyFilter,
-					limit: fetchAll ? cached.value.data.length : limit,
+					limit: fetchAll ? payload.data.length : limit,
 				});
 			}
-			return cached.value;
+			return payload;
+		};
+
+		if (!refresh && cached && cacheAgeMs <= ttlMs) {
+			return yield* trySync(() => readFilteredOrRaw(cached.value));
 		}
-		throw error;
-	}
+
+		let source: MentionLiveSource = primaryMode;
+		const liveResult = yield* (
+			primaryMode === "bird"
+				? fetchMentionsViaBirdEffect({ limit })
+				: fetchMentionsViaXurlEffect({
+						resolvedAccount,
+						limit,
+						all: fetchAll,
+						parsedMaxPages,
+					})
+		).pipe(
+			Effect.catchAll((error) => {
+				if (mode !== "auto" || fetchAll) return Effect.fail(error);
+				source = "bird";
+				return verifyBirdAccountMatchesEffect(resolvedAccount).pipe(
+					Effect.flatMap(() => fetchMentionsViaBirdEffect({ limit })),
+				);
+			}),
+			Effect.flatMap((payload) =>
+				trySync(() => {
+					mergeMentionsIntoLocalStore(
+						db,
+						resolvedAccount.accountId,
+						payload,
+						source,
+					);
+					writeSyncCache(cacheKey, payload, db);
+					return readFilteredOrRaw(payload);
+				}),
+			),
+			Effect.map((payload) => ({ ok: true as const, payload })),
+			Effect.catchAll((error) => {
+				if (!refresh && cached) {
+					return Effect.succeed({ ok: false as const });
+				}
+				return Effect.fail(error);
+			}),
+		);
+
+		if (!liveResult.ok) {
+			if (!cached) {
+				return yield* Effect.fail(
+					new Error("Mention export failed without cache"),
+				);
+			}
+			return yield* trySync(() => readFilteredOrRaw(cached.value));
+		}
+
+		return liveResult.payload;
+	});
 }
 
-export async function exportMentionsViaCachedXurl(
-	options: Omit<
-		Parameters<typeof exportMentionsViaCachedLiveSource>[0],
-		"mode"
-	>,
+export function exportMentionsViaCachedXurl(
+	options: Omit<ExportMentionsViaCachedLiveSourceOptions, "mode">,
 ) {
-	return exportMentionsViaCachedLiveSource({
-		...options,
-		mode: "xurl",
-	});
+	return runEffectPromise(
+		exportMentionsViaCachedLiveSourceEffect({
+			...options,
+			mode: "xurl",
+		}),
+	);
 }
 
-export async function exportMentionsViaCachedBird(
-	options: Omit<
-		Parameters<typeof exportMentionsViaCachedLiveSource>[0],
-		"mode"
-	>,
+export function exportMentionsViaCachedBird(
+	options: Omit<ExportMentionsViaCachedLiveSourceOptions, "mode">,
 ) {
-	return exportMentionsViaCachedLiveSource({
-		...options,
-		mode: "bird",
-	});
+	return runEffectPromise(
+		exportMentionsViaCachedLiveSourceEffect({
+			...options,
+			mode: "bird",
+		}),
+	);
+}
+
+export function exportMentionsViaCachedAuto(
+	options: Omit<ExportMentionsViaCachedLiveSourceOptions, "mode">,
+) {
+	return runEffectPromise(
+		exportMentionsViaCachedLiveSourceEffect({
+			...options,
+			mode: "auto",
+		}),
+	);
 }