birdclaw 0.5.1 → 0.7.0

package/src/lib/xurl.ts

@@ -1,8 +1,12 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { Effect } from "effect";
+import { runEffectPromise } from "./effect-runtime";
 import type {
 	FollowDirection,
+	LiveDataSourceAccount,
 	TransportStatus,
+	XurlDmEventsResponse,
 	XurlFollowUsersResponse,
 	XurlMentionsResponse,
 	XurlMentionUser,
@@ -21,6 +25,8 @@ const MEDIA_FIELDS =
 	"variants,preview_image_url,url,duration_ms,alt_text,type,width,height,public_metrics";
 const RICH_USER_FIELDS =
 	"description,entities,location,public_metrics,profile_image_url,url,created_at,verified,verified_type";
+const DM_EVENT_FIELDS =
+	"attachments,created_at,dm_conversation_id,entities,event_type,id,participant_ids,referenced_tweets,sender_id,text";
 const THREAD_TWEET_FIELDS =
 	"created_at,conversation_id,entities,public_metrics,referenced_tweets,in_reply_to_user_id,attachments";
 // X bookmarks pagination truncates above 90 until this bug is fixed:
@@ -31,6 +37,18 @@ type TimelineCollectionEndpoint = "liked_tweets" | "bookmarks";
 type JsonCommandOptions = {
 	timeoutMs?: number;
 	deadlineMs?: number;
+	signal?: AbortSignal;
+	onAttempt?: (attempt: XurlJsonCommandAttempt) => void;
+};
+export interface XurlJsonCommandAttempt {
+	args: readonly string[];
+	attempt: number;
+	status: "ok" | "rate_limited" | "error";
+	error?: Error;
+}
+type OAuth2UsernameCandidate = {
+	app?: string;
+	username?: string;
 };
 
 let transportStatusCache:
@@ -47,11 +65,22 @@ let authenticatedUserCache:
 			value?: Record<string, unknown> | null;
 	  }
 	| undefined;
+const oauth2CandidateCache = new Map<
+	string,
+	{ expiresAt: number; value: OAuth2UsernameCandidate }
+>();
 
 function liveWritesDisabled() {
 	return process.env.BIRDCLAW_DISABLE_LIVE_WRITES === "1";
 }
 
+function e2eFakeLiveWritesEnabled() {
+	return (
+		process.env.BIRDCLAW_E2E === "1" &&
+		process.env.BIRDCLAW_E2E_FAKE_LIVE_WRITES === "1"
+	);
+}
+
 function getJsonRetryBaseDelayMs() {
 	const value = Number(process.env.BIRDCLAW_XURL_RETRY_BASE_MS ?? "2000");
 	return Number.isFinite(value) && value >= 0 ? value : 2000;
@@ -90,6 +119,10 @@ function formatXurlCommandError(error: unknown, args: string[]) {
 	return new Error(formatExecError(error, `xurl ${args.join(" ")} failed`));
 }
 
+function normalizeError(error: unknown) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+
 function parseErrorPayload(error: unknown) {
 	const stdout =
 		typeof error === "object" &&
@@ -123,6 +156,17 @@ function getRetryDelayMs(error: unknown, attempt: number) {
 	return Math.min(baseDelay * 2 ** attempt, 30_000);
 }
 
+function emitJsonCommandAttempt(
+	options: JsonCommandOptions,
+	attempt: XurlJsonCommandAttempt,
+) {
+	try {
+		options.onAttempt?.(attempt);
+	} catch {
+		// Telemetry observers must not affect xurl command behavior.
+	}
+}
+
 function capTimelineCollectionMaxResults(
 	collection: TimelineCollectionEndpoint,
 	maxResults: number,
@@ -133,28 +177,23 @@ function capTimelineCollectionMaxResults(
 		: maxResults;
 }
 
-async function sleep(ms: number) {
-	if (ms <= 0) {
-		return;
-	}
-	await new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 export function resetTransportStatusCache() {
 	transportStatusCache = undefined;
 }
 
 export function resetAuthenticatedUserCache() {
 	authenticatedUserCache = undefined;
+	oauth2CandidateCache.clear();
 }
 
-async function hasXurl(): Promise<boolean> {
-	try {
-		await execFileAsync("xurl", ["version"]);
-		return true;
-	} catch {
-		return false;
-	}
+function hasXurlEffect() {
+	return Effect.tryPromise({
+		try: () => execFileAsync("xurl", ["version"]),
+		catch: normalizeError,
+	}).pipe(
+		Effect.as(true),
+		Effect.catchAll(() => Effect.succeed(false)),
+	);
 }
 
 function isUnauthenticatedXurlStatus(status: string) {
@@ -163,164 +202,553 @@ function isUnauthenticatedXurlStatus(status: string) {
 	);
 }
 
-export async function getTransportStatus(): Promise<TransportStatus> {
-	const now = Date.now();
-	if (transportStatusCache?.value && transportStatusCache.expiresAt > now) {
-		return transportStatusCache.value;
-	}
-
-	if (transportStatusCache?.pending) {
-		return transportStatusCache.pending;
-	}
-
-	const pending: Promise<TransportStatus> = (async () => {
-		const installed = await hasXurl();
+function readTransportStatusEffect(): Effect.Effect<TransportStatus, never> {
+	return Effect.gen(function* () {
+		const installed = yield* hasXurlEffect();
 		if (!installed) {
 			return {
 				installed: false,
-				availableTransport: "local",
+				availableTransport: "local" as const,
 				statusText: "xurl not installed. local mode active.",
 			};
 		}
 
-		try {
-			const { stdout } = await execFileAsync("xurl", ["auth", "status"]);
-			const rawStatus = stdout.trim();
+		return yield* Effect.tryPromise({
+			try: () => execFileAsync("xurl", ["auth", "status"]),
+			catch: (cause) => cause,
+		}).pipe(
+			Effect.map(({ stdout }) => {
+				const rawStatus = stdout.trim();
+
+				if (isUnauthenticatedXurlStatus(rawStatus)) {
+					return {
+						installed: true,
+						availableTransport: "local" as const,
+						statusText:
+							"xurl installed but not authenticated. local (bird) mode active.",
+						rawStatus,
+					};
+				}
 
-			if (isUnauthenticatedXurlStatus(rawStatus)) {
 				return {
 					installed: true,
-					availableTransport: "local",
-					statusText:
-						"xurl installed but not authenticated. local (bird) mode active.",
+					availableTransport: "xurl" as const,
+					statusText: "xurl available",
 					rawStatus,
 				};
-			}
+			}),
+			Effect.catchAll((error) =>
+				Effect.succeed({
+					installed: true,
+					availableTransport: "local" as const,
+					statusText: `xurl detected but auth unavailable: ${
+						error instanceof Error ? error.message : "unknown error"
+					}`,
+				}),
+			),
+		);
+	});
+}
 
-			return {
-				installed: true,
-				availableTransport: "xurl",
-				statusText: "xurl available",
-				rawStatus,
-			};
-		} catch (error) {
-			return {
-				installed: true,
-				availableTransport: "local",
-				statusText: `xurl detected but auth unavailable: ${
-					error instanceof Error ? error.message : "unknown error"
-				}`,
-			};
+export function getTransportStatusEffect() {
+	return Effect.gen(function* () {
+		const now = Date.now();
+		if (transportStatusCache?.value && transportStatusCache.expiresAt > now) {
+			return transportStatusCache.value;
 		}
-	})();
 
-	transportStatusCache = {
-		expiresAt: 0,
-		pending,
-	};
+		if (transportStatusCache?.pending) {
+			const status = yield* Effect.tryPromise({
+				try: () => transportStatusCache?.pending ?? Promise.resolve(undefined),
+				catch: normalizeError,
+			});
+			if (status) return status;
+		}
 
-	try {
-		const status = await pending;
+		const pending = runEffectPromise(readTransportStatusEffect());
+
+		transportStatusCache = {
+			expiresAt: 0,
+			pending,
+		};
+
+		const status = yield* Effect.tryPromise({
+			try: () => pending,
+			catch: normalizeError,
+		}).pipe(
+			Effect.catchAll((error) =>
+				Effect.sync(() => {
+					transportStatusCache = undefined;
+				}).pipe(Effect.flatMap(() => Effect.fail(error))),
+			),
+		);
 		transportStatusCache = {
 			expiresAt: Date.now() + TRANSPORT_STATUS_TTL_MS,
 			value: status,
 		};
 		return status;
-	} catch (error) {
-		transportStatusCache = undefined;
-		throw error;
-	}
+	});
+}
+
+export function getTransportStatus(): Promise<TransportStatus> {
+	return runEffectPromise(getTransportStatusEffect());
 }
 
-async function runShortcut(
+function runShortcutEffect(args: string[]) {
+	return Effect.gen(function* () {
+		if (liveWritesDisabled()) {
+			if (e2eFakeLiveWritesEnabled()) {
+				return { ok: true, output: "e2e fake live write" };
+			}
+			return { ok: false, output: "live writes disabled" };
+		}
+
+		return yield* Effect.tryPromise({
+			try: () => execFileAsync("xurl", args),
+			catch: normalizeError,
+		}).pipe(
+			Effect.map(({ stdout, stderr }) => ({
+				ok: true,
+				output: stdout || stderr,
+			})),
+			Effect.catchAll((error) =>
+				Effect.succeed({
+					ok: false,
+					output: formatExecError(error, "xurl execution failed"),
+				}),
+			),
+		);
+	});
+}
+
+function execXurlJsonEffect(
 	args: string[],
-): Promise<{ ok: boolean; output: string }> {
-	if (liveWritesDisabled()) {
-		return { ok: true, output: "live writes disabled" };
-	}
+	timeoutMs?: number,
+	signal?: AbortSignal,
+): Effect.Effect<{ stdout: string; stderr: string }, Error> {
+	return Effect.tryPromise({
+		try: () => {
+			const controller =
+				(typeof timeoutMs === "number" &&
+					Number.isFinite(timeoutMs) &&
+					timeoutMs > 0) ||
+				signal
+					? new AbortController()
+					: undefined;
+			if (
+				typeof timeoutMs === "number" &&
+				Number.isFinite(timeoutMs) &&
+				timeoutMs <= 0
+			) {
+				throw new Error("xurl command timed out");
+			}
+			if (signal?.aborted) {
+				throw new Error("xurl command aborted");
+			}
+			const onAbort = () => controller?.abort();
+			signal?.addEventListener("abort", onAbort, { once: true });
+			const timeout =
+				controller &&
+				typeof timeoutMs === "number" &&
+				Number.isFinite(timeoutMs) &&
+				timeoutMs > 0
+					? setTimeout(() => controller.abort(), timeoutMs)
+					: undefined;
+			const result = controller
+				? execFileAsync("xurl", args, { signal: controller.signal })
+				: execFileAsync("xurl", args);
+			return result.finally(() => {
+				signal?.removeEventListener("abort", onAbort);
+				if (timeout) {
+					clearTimeout(timeout);
+				}
+			});
+		},
+		catch: normalizeError,
+	});
+}
 
-	try {
-		const { stdout, stderr } = await execFileAsync("xurl", args);
-		return { ok: true, output: stdout || stderr };
-	} catch (error) {
-		return {
-			ok: false,
-			output: formatExecError(error, "xurl execution failed"),
-		};
+function getRemainingTimeoutMs(deadlineMs?: number) {
+	if (deadlineMs === undefined) return undefined;
+	const timeoutMs = Math.max(0, deadlineMs - Date.now());
+	if (timeoutMs <= 0) {
+		throw new Error("xurl OAuth2 fallback timed out");
 	}
+	return timeoutMs;
+}
+
+function execXurlTextEffect(
+	args: string[],
+	deadlineMs?: number,
+): Effect.Effect<{ stdout: string; stderr: string }, Error> {
+	return Effect.tryPromise({
+		try: () => {
+			const timeoutMs = getRemainingTimeoutMs(deadlineMs);
+			const controller =
+				typeof timeoutMs === "number" &&
+				Number.isFinite(timeoutMs) &&
+				timeoutMs > 0
+					? new AbortController()
+					: undefined;
+			const timeout = controller
+				? setTimeout(() => controller.abort(), timeoutMs)
+				: undefined;
+			const result = controller
+				? execFileAsync("xurl", args, { signal: controller.signal })
+				: execFileAsync("xurl", args);
+			return result.finally(() => {
+				if (timeout) {
+					clearTimeout(timeout);
+				}
+			});
+		},
+		catch: normalizeError,
+	});
+}
+
+function parseJsonPayloadEffect(
+	stdout: string,
+	args: string[],
+): Effect.Effect<Record<string, unknown>, Error> {
+	return Effect.try({
+		try: () => JSON.parse(stdout) as Record<string, unknown>,
+		catch: (error) => formatXurlCommandError(error, args),
+	});
 }
 
-async function runJsonCommand(
+function runJsonCommandEffect(
 	args: string[],
 	options: JsonCommandOptions = {},
 	attempt = 0,
-) {
-	const deadlineMs =
-		options.deadlineMs ??
-		(typeof options.timeoutMs === "number" &&
-		Number.isFinite(options.timeoutMs) &&
-		options.timeoutMs > 0
-			? Date.now() + options.timeoutMs
-			: undefined);
-	const timeoutMs = deadlineMs
-		? Math.max(0, deadlineMs - Date.now())
-		: undefined;
-	const controller =
-		typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0
-			? new AbortController()
+): Effect.Effect<Record<string, unknown>, Error> {
+	return Effect.gen(function* () {
+		const deadlineMs =
+			options.deadlineMs ??
+			(typeof options.timeoutMs === "number" &&
+			Number.isFinite(options.timeoutMs) &&
+			options.timeoutMs > 0
+				? Date.now() + options.timeoutMs
+				: undefined);
+		const timeoutMs = deadlineMs
+			? Math.max(0, deadlineMs - Date.now())
 			: undefined;
-	const timeout = controller
-		? setTimeout(() => controller.abort(), timeoutMs)
+		return yield* execXurlJsonEffect(args, timeoutMs, options.signal).pipe(
+			Effect.flatMap(({ stdout }) => parseJsonPayloadEffect(stdout, args)),
+			Effect.tap(() =>
+				Effect.sync(() =>
+					emitJsonCommandAttempt(options, { args, attempt, status: "ok" }),
+				),
+			),
+			Effect.catchAll((error) => {
+				const retryDelayMs = getRetryDelayMs(error, attempt);
+				emitJsonCommandAttempt(options, {
+					args,
+					attempt,
+					status: retryDelayMs === null ? "error" : "rate_limited",
+					error,
+				});
+				if (retryDelayMs === null || attempt >= JSON_RETRY_LIMIT - 1) {
+					return Effect.fail(formatXurlCommandError(error, args));
+				}
+				if (options.signal?.aborted) {
+					return Effect.fail(formatXurlCommandError(error, args));
+				}
+				const remainingMs = deadlineMs
+					? Math.max(0, deadlineMs - Date.now())
+					: undefined;
+				if (remainingMs !== undefined && retryDelayMs >= remainingMs) {
+					return Effect.fail(formatXurlCommandError(error, args));
+				}
+
+				return Effect.sleep(retryDelayMs).pipe(
+					Effect.flatMap(() =>
+						runJsonCommandEffect(args, { ...options, deadlineMs }, attempt + 1),
+					),
+				);
+			}),
+		);
+	});
+}
+
+function cleanXurlUsernameLabel(username?: string) {
+	const label = username?.trim().replace(/^@/, "");
+	return label &&
+		label !== "-" &&
+		label !== "–" &&
+		label !== "(none)" &&
+		label.toLowerCase() !== "none" &&
+		label.toLowerCase() !== "unknown" &&
+		/^[^\s]{1,128}$/.test(label)
+		? label
 		: undefined;
+}
 
-	try {
-		const { stdout } = controller
-			? await execFileAsync("xurl", args, { signal: controller.signal })
-			: await execFileAsync("xurl", args);
-		return JSON.parse(stdout) as Record<string, unknown>;
-	} catch (error) {
-		const retryDelayMs = getRetryDelayMs(error, attempt);
-		if (retryDelayMs === null || attempt >= JSON_RETRY_LIMIT - 1) {
-			throw formatXurlCommandError(error, args);
+function comparableXurlUsername(username?: string) {
+	return cleanXurlUsernameLabel(username)?.toLowerCase();
+}
+
+function cleanXurlAppLabel(app?: string) {
+	const label = app?.trim();
+	return label && /^[^\s]{1,128}$/.test(label) ? label : undefined;
+}
+
+function parseOAuth2UsernamesFromStatus(rawStatus: string) {
+	const seen = new Set<string>();
+	const usernames: OAuth2UsernameCandidate[] = [];
+	let currentApp: string | undefined;
+	for (const line of rawStatus.split(/\r?\n/)) {
+		const appMatch = line.match(/^\s*(?:▸\s*)?([^\s]+)\s+\[client_id:/);
+		if (appMatch) {
+			currentApp = cleanXurlAppLabel(appMatch[1]);
+			continue;
 		}
-		const remainingMs = deadlineMs
-			? Math.max(0, deadlineMs - Date.now())
+		const oauthMatch = line.match(/\boauth2:\s*([^\s]+)/);
+		if (oauthMatch) {
+			const username = cleanXurlUsernameLabel(oauthMatch[1]);
+			const key = username
+				? `${currentApp ?? "default"}:${username}`
+				: undefined;
+			if (username && key && !seen.has(key)) {
+				seen.add(key);
+				usernames.push({ app: currentApp, username });
+			}
+		}
+	}
+	return usernames;
+}
+
+function readOAuth2UsernameCandidatesEffect(
+	deadlineMs?: number,
+): Effect.Effect<OAuth2UsernameCandidate[], never> {
+	return execXurlTextEffect(["auth", "status"], deadlineMs).pipe(
+		Effect.map(({ stdout }) => parseOAuth2UsernamesFromStatus(stdout)),
+		Effect.catchAll(() => Effect.succeed([])),
+	);
+}
+
+export function readXurlOAuth2AccountsEffect(): Effect.Effect<
+	LiveDataSourceAccount[],
+	never
+> {
+	return readOAuth2UsernameCandidatesEffect().pipe(
+		Effect.map((candidates) =>
+			candidates.map((candidate) => ({
+				...(candidate.app ? { app: candidate.app } : {}),
+				...(candidate.username ? { username: candidate.username } : {}),
+			})),
+		),
+	);
+}
+
+export function readXurlOAuth2Accounts(): Promise<LiveDataSourceAccount[]> {
+	return runEffectPromise(readXurlOAuth2AccountsEffect());
+}
+
+function lookupOAuth2UsernameForAccountEffect(
+	expectedUsername: string,
+	attemptedUsernames: Set<string>,
+	deadlineMs?: number,
+	knownCandidates?: OAuth2UsernameCandidate[],
+) {
+	return Effect.gen(function* () {
+		const expected = comparableXurlUsername(expectedUsername);
+		if (!expected) return undefined;
+
+		const candidates =
+			knownCandidates ??
+			(yield* readOAuth2UsernameCandidatesEffect(deadlineMs));
+		for (const candidate of candidates) {
+			const candidateKey = `${candidate.app ?? "default"}:${candidate.username}`;
+			if (attemptedUsernames.has(candidateKey)) continue;
+			const payload = yield* runJsonCommandEffect(
+				oauth2ArgsForCandidate(candidate, ["/2/users/me"]),
+				{ deadlineMs },
+			).pipe(Effect.catchAll(() => Effect.succeed(null)));
+			const user = payload ? authenticatedUserFromPayload(payload) : null;
+			const actual = comparableXurlUsername(String(user?.username ?? ""));
+			if (actual === expected) {
+				return candidate;
+			}
+		}
+
+		return undefined;
+	});
+}
+
+function oauth2ArgsForCandidate(
+	candidate: OAuth2UsernameCandidate | undefined,
+	args: string[],
+) {
+	return [
+		...(candidate?.app ? ["--app", candidate.app] : []),
+		"--auth",
+		"oauth2",
+		...(candidate?.username ? ["--username", candidate.username] : []),
+		...args,
+	];
+}
+
+function configuredOAuth2Candidate(primaryUsername: string | undefined) {
+	const app = cleanXurlAppLabel(process.env.BIRDCLAW_XURL_OAUTH2_APP);
+	const username = cleanXurlUsernameLabel(
+		process.env.BIRDCLAW_XURL_OAUTH2_USERNAME,
+	);
+	if (!app && !username) return undefined;
+	const effectiveUsername = username ?? primaryUsername;
+	if (!app && !effectiveUsername) return undefined;
+	return {
+		...(app ? { app } : {}),
+		...(effectiveUsername ? { username: effectiveUsername } : {}),
+	};
+}
+
+function runOAuth2JsonCommandEffect({
+	args,
+	username,
+	options,
+	useConfiguredCandidate = true,
+}: {
+	args: string[];
+	username?: string;
+	options?: JsonCommandOptions;
+	useConfiguredCandidate?: boolean;
+}) {
+	const primaryUsername = cleanXurlUsernameLabel(username);
+	return Effect.gen(function* () {
+		const deadlineMs =
+			options?.deadlineMs ??
+			(typeof options?.timeoutMs === "number" &&
+			Number.isFinite(options.timeoutMs) &&
+			options.timeoutMs > 0
+				? Date.now() + options.timeoutMs
+				: undefined);
+		const scopedOptions = { ...options, deadlineMs };
+		let authCandidate: OAuth2UsernameCandidate | undefined = primaryUsername
+			? { username: primaryUsername }
 			: undefined;
-		if (remainingMs !== undefined && retryDelayMs >= remainingMs) {
-			throw formatXurlCommandError(error, args);
+		const configuredCandidate = useConfiguredCandidate
+			? configuredOAuth2Candidate(primaryUsername)
+			: undefined;
+		if (configuredCandidate) {
+			authCandidate = configuredCandidate;
+		} else if (primaryUsername) {
+			const cacheKey = primaryUsername.toLowerCase();
+			const cachedCandidate = oauth2CandidateCache.get(cacheKey);
+			if (cachedCandidate && cachedCandidate.expiresAt > Date.now()) {
+				authCandidate = cachedCandidate.value;
+			} else {
+				const candidates =
+					yield* readOAuth2UsernameCandidatesEffect(deadlineMs);
+				const primaryCandidates = candidates.filter(
+					(candidate) => candidate.username === primaryUsername,
+				);
+				if (primaryCandidates.length === 1) {
+					authCandidate = primaryCandidates[0];
+				} else if (primaryCandidates.length > 1) {
+					const verifiedUsername = yield* lookupOAuth2UsernameForAccountEffect(
+						primaryUsername,
+						new Set(),
+						deadlineMs,
+						candidates,
+					);
+					authCandidate = verifiedUsername ??
+						primaryCandidates[0] ?? { username: primaryUsername };
+				} else {
+					const fallbackUsername = yield* lookupOAuth2UsernameForAccountEffect(
+						primaryUsername,
+						new Set(),
+						deadlineMs,
+						candidates,
+					);
+					if (fallbackUsername) {
+						authCandidate = fallbackUsername;
+					}
+				}
+				if (authCandidate) {
+					oauth2CandidateCache.set(cacheKey, {
+						expiresAt: Date.now() + AUTHENTICATED_USER_TTL_MS,
+						value: authCandidate,
+					});
+				}
+			}
 		}
 
-		await sleep(retryDelayMs);
-		return runJsonCommand(args, { ...options, deadlineMs }, attempt + 1);
-	} finally {
-		if (timeout) {
-			clearTimeout(timeout);
+		if (deadlineMs !== undefined && Date.now() >= deadlineMs) {
+			return yield* Effect.fail(new Error("xurl OAuth2 fallback timed out"));
 		}
-	}
+
+		return yield* runJsonCommandEffect(
+			oauth2ArgsForCandidate(authCandidate, args),
+			scopedOptions,
+		).pipe(
+			Effect.catchAll((error) => {
+				if (!primaryUsername) {
+					return Effect.fail(error);
+				}
+				oauth2CandidateCache.delete(primaryUsername.toLowerCase());
+				const attempted = new Set([
+					authCandidate
+						? `${authCandidate.app ?? "default"}:${authCandidate.username}`
+						: `default:${primaryUsername}`,
+				]);
+				if (authCandidate?.username !== primaryUsername) {
+					attempted.add(`default:${primaryUsername}`);
+				}
+				return lookupOAuth2UsernameForAccountEffect(
+					primaryUsername,
+					attempted,
+					deadlineMs,
+				).pipe(
+					Effect.flatMap((fallbackUsername) => {
+						if (!fallbackUsername) {
+							return Effect.fail(error);
+						}
+						oauth2CandidateCache.set(primaryUsername.toLowerCase(), {
+							expiresAt: Date.now() + AUTHENTICATED_USER_TTL_MS,
+							value: fallbackUsername,
+						});
+						return runJsonCommandEffect(
+							oauth2ArgsForCandidate(fallbackUsername, args),
+							scopedOptions,
+						);
+					}),
+					Effect.catchAll(() => Effect.fail(error)),
+				);
+			}),
+		);
+	});
 }
 
-async function runMutationCommand(args: string[]) {
-	if (liveWritesDisabled()) {
-		return { ok: true, output: "live writes disabled" };
-	}
+function runMutationCommandEffect(args: string[]) {
+	return Effect.gen(function* () {
+		if (liveWritesDisabled()) {
+			if (e2eFakeLiveWritesEnabled()) {
+				return { ok: true, output: "e2e fake live write" };
+			}
+			return { ok: false, output: "live writes disabled" };
+		}
 
-	try {
-		const { stdout, stderr } = await execFileAsync("xurl", args);
-		return {
-			ok: true,
-			output: stdout || stderr || "ok",
-		};
-	} catch (error) {
-		return {
-			ok: false,
-			output: formatExecError(error, "xurl execution failed"),
-		};
-	}
+		return yield* Effect.tryPromise({
+			try: () => execFileAsync("xurl", args),
+			catch: normalizeError,
+		}).pipe(
+			Effect.map(({ stdout, stderr }) => ({
+				ok: true,
+				output: stdout || stderr || "ok",
+			})),
+			Effect.catchAll((error) =>
+				Effect.succeed({
+					ok: false,
+					output: formatExecError(error, "xurl execution failed"),
+				}),
+			),
+		);
+	});
 }
 
-export async function lookupUsersByIds(ids: string[]) {
+export function lookupUsersByIdsEffect(ids: string[]) {
 	if (ids.length === 0) {
-		return [];
+		return Effect.succeed([]);
 	}
 
 	const query = new URLSearchParams({
@@ -328,14 +756,28 @@ export async function lookupUsersByIds(ids: string[]) {
 		"user.fields":
 			"description,entities,location,public_metrics,profile_image_url,url,created_at,verified,verified_type",
 	});
-	const payload = await runJsonCommand([`/2/users?${query.toString()}`]);
-	const data = payload.data;
-	return Array.isArray(data) ? (data as XurlMentionUser[]) : [];
+	return runJsonCommandEffect([`/2/users?${query.toString()}`]).pipe(
+		Effect.map((payload) =>
+			Array.isArray(payload.data) ? (payload.data as XurlMentionUser[]) : [],
+		),
+	);
 }
 
-export async function lookupUsersByHandles(handles: string[]) {
+export function lookupUsersByIds(ids: string[]) {
+	return runEffectPromise(lookupUsersByIdsEffect(ids));
+}
+
+export function lookupUsersByHandlesEffect(
+	handles: string[],
+	options: {
+		auth?: "oauth2";
+		username?: string;
+		signal?: AbortSignal;
+		useConfiguredCandidate?: boolean;
+	} = {},
+) {
 	if (handles.length === 0) {
-		return [];
+		return Effect.succeed([]);
 	}
 
 	const query = new URLSearchParams({
@@ -343,52 +785,135 @@ export async function lookupUsersByHandles(handles: string[]) {
 		"user.fields":
 			"description,entities,location,public_metrics,profile_image_url,url,created_at,verified,verified_type",
 	});
-	const payload = await runJsonCommand([`/2/users/by?${query.toString()}`]);
+	const args = [`/2/users/by?${query.toString()}`];
+	const command =
+		options.auth === "oauth2"
+			? runOAuth2JsonCommandEffect({
+					args,
+					username: options.username,
+					options: { signal: options.signal },
+					useConfiguredCandidate: options.useConfiguredCandidate,
+				})
+			: runJsonCommandEffect(args, { signal: options.signal });
+	return command.pipe(
+		Effect.map((payload) =>
+			Array.isArray(payload.data) ? (payload.data as XurlMentionUser[]) : [],
+		),
+	);
+}
+
+export function lookupUsersByHandles(
+	handles: string[],
+	options: {
+		auth?: "oauth2";
+		username?: string;
+		signal?: AbortSignal;
+		useConfiguredCandidate?: boolean;
+	} = {},
+) {
+	return runEffectPromise(lookupUsersByHandlesEffect(handles, options));
+}
+
+function authenticatedUserFromPayload(payload: Record<string, unknown>) {
 	const data = payload.data;
-	return Array.isArray(data) ? (data as XurlMentionUser[]) : [];
+	return data && typeof data === "object"
+		? (data as Record<string, unknown>)
+		: null;
 }
 
-export async function lookupAuthenticatedUser() {
-	const now = Date.now();
-	if (
-		authenticatedUserCache &&
-		"value" in authenticatedUserCache &&
-		authenticatedUserCache.expiresAt > now
-	) {
-		return authenticatedUserCache.value ?? null;
-	}
+export function lookupAuthenticatedUserFreshEffect() {
+	return runJsonCommandEffect(["whoami"]).pipe(
+		Effect.map(authenticatedUserFromPayload),
+	);
+}
 
-	if (authenticatedUserCache?.pending) {
-		return authenticatedUserCache.pending;
-	}
+export function lookupAuthenticatedOAuth2UserEffect(username?: string) {
+	return runOAuth2JsonCommandEffect({
+		args: ["whoami"],
+		username,
+	}).pipe(Effect.map(authenticatedUserFromPayload));
+}
 
-	const pending = (async () => {
-		const payload = await runJsonCommand(["whoami"]);
-		const data = payload.data;
-		return data && typeof data === "object"
-			? (data as Record<string, unknown>)
-			: null;
-	})();
-
-	authenticatedUserCache = {
-		expiresAt: 0,
-		pending,
-	};
+export function lookupAuthenticatedUserEffect() {
+	return Effect.gen(function* () {
+		const now = Date.now();
+		if (
+			authenticatedUserCache &&
+			"value" in authenticatedUserCache &&
+			authenticatedUserCache.expiresAt > now
+		) {
+			return authenticatedUserCache.value ?? null;
+		}
 
-	try {
-		const value = await pending;
+		if (authenticatedUserCache?.pending) {
+			return yield* Effect.tryPromise({
+				try: () => authenticatedUserCache?.pending ?? Promise.resolve(null),
+				catch: normalizeError,
+			});
+		}
+
+		const pending = runEffectPromise(lookupAuthenticatedUserFreshEffect());
+
+		authenticatedUserCache = {
+			expiresAt: 0,
+			pending,
+		};
+
+		const value = yield* Effect.tryPromise({
+			try: () => pending,
+			catch: normalizeError,
+		}).pipe(
+			Effect.catchAll((error) =>
+				Effect.sync(() => {
+					authenticatedUserCache = undefined;
+				}).pipe(Effect.flatMap(() => Effect.fail(error))),
+			),
+		);
 		authenticatedUserCache = {
 			expiresAt: Date.now() + AUTHENTICATED_USER_TTL_MS,
 			value,
 		};
 		return value;
-	} catch (error) {
-		authenticatedUserCache = undefined;
-		throw error;
-	}
+	});
+}
+
+export function lookupAuthenticatedUser() {
+	return runEffectPromise(lookupAuthenticatedUserEffect());
 }
 
-export async function listMentionsViaXurl({
+export function lookupAuthenticatedUserFresh() {
+	return runEffectPromise(lookupAuthenticatedUserFreshEffect());
+}
+
+function resolveUserIdEffect({
+	username,
+	userId,
+}: {
+	username?: string;
+	userId?: string;
+}) {
+	return Effect.gen(function* () {
+		if (userId) return userId;
+		if (username) {
+			const [user] = yield* lookupUsersByHandlesEffect([username]);
+			if (!user?.id) {
+				return yield* Effect.fail(
+					new Error(`Could not resolve Twitter user id for @${username}`),
+				);
+			}
+			return String(user.id);
+		}
+		const user = yield* lookupAuthenticatedUserEffect();
+		if (!user?.id) {
+			return yield* Effect.fail(
+				new Error("Could not resolve authenticated Twitter user id"),
+			);
+		}
+		return String(user.id);
+	});
+}
+
+export function listMentionsViaXurlEffect({
 	maxResults,
 	username,
 	userId,
@@ -402,45 +927,97 @@ export async function listMentionsViaXurl({
 	paginationToken?: string;
 	sinceId?: string;
 	startTime?: string;
+}): Effect.Effect<XurlMentionsResponse, Error> {
+	return Effect.gen(function* () {
+		const resolvedUserId = yield* resolveUserIdEffect({ username, userId });
+		const query = new URLSearchParams({
+			max_results: String(maxResults),
+			expansions: AUTHOR_MEDIA_EXPANSIONS,
+			"tweet.fields": "created_at,conversation_id,entities,public_metrics",
+			"media.fields": MEDIA_FIELDS,
+			"user.fields":
+				"description,entities,location,public_metrics,profile_image_url,url,created_at,verified,verified_type",
+		});
+		if (paginationToken) {
+			query.set("pagination_token", paginationToken);
+		}
+		if (sinceId) {
+			query.set("since_id", sinceId);
+		}
+		if (startTime) {
+			query.set("start_time", startTime);
+		}
+
+		const payload = yield* runOAuth2JsonCommandEffect({
+			args: [`/2/users/${resolvedUserId}/mentions?${query.toString()}`],
+			username,
+		});
+		return toXurlMentionsResponse(payload);
+	});
+}
+
+export function listMentionsViaXurl(options: {
+	maxResults: number;
+	username?: string;
+	userId?: string;
+	paginationToken?: string;
+	sinceId?: string;
+	startTime?: string;
 }): Promise<XurlMentionsResponse> {
-	let resolvedUserId = userId;
-	if (!resolvedUserId) {
-		if (username) {
-			const [user] = await lookupUsersByHandles([username]);
-			if (!user?.id) {
-				throw new Error(`Could not resolve Twitter user id for @${username}`);
-			}
-			resolvedUserId = String(user.id);
-		} else {
-			const user = await lookupAuthenticatedUser();
-			if (!user?.id) {
-				throw new Error("Could not resolve authenticated Twitter user id");
-			}
-			resolvedUserId = String(user.id);
+	return runEffectPromise(listMentionsViaXurlEffect(options));
+}
+
+export function listHomeTimelineViaXurlEffect({
+	maxResults,
+	username,
+	userId,
+	paginationToken,
+	timeoutMs,
+}: {
+	maxResults: number;
+	username?: string;
+	userId?: string;
+	paginationToken?: string;
+	timeoutMs?: number;
+}): Effect.Effect<XurlMentionsResponse, Error> {
+	return Effect.gen(function* () {
+		const resolvedUserId = yield* resolveUserIdEffect({ username, userId });
+		const query = new URLSearchParams({
+			max_results: String(maxResults),
+			expansions: AUTHOR_MEDIA_EXPANSIONS,
+			"tweet.fields":
+				"created_at,conversation_id,entities,public_metrics,referenced_tweets",
+			"media.fields": MEDIA_FIELDS,
+			"user.fields": RICH_USER_FIELDS,
+		});
+		if (paginationToken) {
+			query.set("pagination_token", paginationToken);
 		}
-	}
 
-	const query = new URLSearchParams({
-		max_results: String(maxResults),
-		expansions: AUTHOR_MEDIA_EXPANSIONS,
-		"tweet.fields": "created_at,conversation_id,entities,public_metrics",
-		"media.fields": MEDIA_FIELDS,
-		"user.fields":
-			"description,entities,location,public_metrics,profile_image_url,url,created_at,verified,verified_type",
+		const payload = yield* runOAuth2JsonCommandEffect({
+			args: [
+				`/2/users/${resolvedUserId}/timelines/reverse_chronological?${query.toString()}`,
+			],
+			username,
+			options: { timeoutMs },
+		});
+		return toXurlMentionsResponse(payload);
 	});
-	if (paginationToken) {
-		query.set("pagination_token", paginationToken);
-	}
-	if (sinceId) {
-		query.set("since_id", sinceId);
-	}
-	if (startTime) {
-		query.set("start_time", startTime);
-	}
+}
 
-	const payload = await runJsonCommand([
-		`/2/users/${resolvedUserId}/mentions?${query.toString()}`,
-	]);
+export function listHomeTimelineViaXurl(options: {
+	maxResults: number;
+	username?: string;
+	userId?: string;
+	paginationToken?: string;
+	timeoutMs?: number;
+}): Promise<XurlMentionsResponse> {
+	return runEffectPromise(listHomeTimelineViaXurlEffect(options));
+}
+
+function toXurlMentionsResponse(
+	payload: Record<string, unknown>,
+): XurlMentionsResponse {
 	return {
 		data: Array.isArray(payload.data)
 			? (payload.data as XurlMentionsResponse["data"])
@@ -456,7 +1033,7 @@ export async function listMentionsViaXurl({
 	};
 }
 
-async function listTimelineCollectionViaXurl({
+function listTimelineCollectionViaXurlEffect({
 	collection,
 	maxResults,
 	username,
@@ -470,88 +1047,128 @@ async function listTimelineCollectionViaXurl({
 	userId?: string;
 	isPaginatedWalk?: boolean;
 	paginationToken?: string;
-}): Promise<XurlMentionsResponse> {
-	let resolvedUserId = userId;
-	if (!resolvedUserId) {
-		if (username) {
-			const [user] = await lookupUsersByHandles([username]);
-			if (!user?.id) {
-				throw new Error(`Could not resolve Twitter user id for @${username}`);
-			}
-			resolvedUserId = String(user.id);
-		} else {
-			const user = await lookupAuthenticatedUser();
-			if (!user?.id) {
-				throw new Error("Could not resolve authenticated Twitter user id");
-			}
-			resolvedUserId = String(user.id);
+}): Effect.Effect<XurlMentionsResponse, Error> {
+	return Effect.gen(function* () {
+		const resolvedUserId = yield* resolveUserIdEffect({ username, userId });
+		const requestMaxResults = capTimelineCollectionMaxResults(
+			collection,
+			maxResults,
+			isPaginatedWalk,
+		);
+		const query = new URLSearchParams({
+			max_results: String(requestMaxResults),
+			expansions: AUTHOR_MEDIA_EXPANSIONS,
+			"tweet.fields":
+				"created_at,conversation_id,entities,public_metrics,referenced_tweets",
+			"media.fields": MEDIA_FIELDS,
+			"user.fields":
+				"description,entities,location,public_metrics,profile_image_url,url,created_at,verified,verified_type",
+		});
+		if (paginationToken) {
+			query.set("pagination_token", paginationToken);
 		}
-	}
 
-	const requestMaxResults = capTimelineCollectionMaxResults(
-		collection,
-		maxResults,
-		isPaginatedWalk,
-	);
-	const query = new URLSearchParams({
-		max_results: String(requestMaxResults),
-		expansions: AUTHOR_MEDIA_EXPANSIONS,
-		"tweet.fields":
-			"created_at,conversation_id,entities,public_metrics,referenced_tweets",
-		"media.fields": MEDIA_FIELDS,
-		"user.fields":
-			"description,entities,location,public_metrics,profile_image_url,url,created_at,verified,verified_type",
+		const payload = yield* runOAuth2JsonCommandEffect({
+			args: [`/2/users/${resolvedUserId}/${collection}?${query.toString()}`],
+			username,
+		});
+		return toXurlMentionsResponse(payload);
 	});
-	if (paginationToken) {
-		query.set("pagination_token", paginationToken);
-	}
-
-	const payload = await runJsonCommand([
-		"--auth",
-		"oauth2",
-		`/2/users/${resolvedUserId}/${collection}?${query.toString()}`,
-	]);
-	return {
-		data: Array.isArray(payload.data)
-			? (payload.data as XurlMentionsResponse["data"])
-			: [],
-		includes:
-			payload.includes && typeof payload.includes === "object"
-				? (payload.includes as XurlMentionsResponse["includes"])
-				: undefined,
-		meta:
-			payload.meta && typeof payload.meta === "object"
-				? (payload.meta as XurlMentionsResponse["meta"])
-				: undefined,
-	};
 }
 
-export async function listLikedTweetsViaXurl(options: {
+export function listLikedTweetsViaXurlEffect(options: {
 	maxResults: number;
 	username?: string;
 	userId?: string;
 	paginationToken?: string;
-}): Promise<XurlMentionsResponse> {
-	return listTimelineCollectionViaXurl({
+}) {
+	return listTimelineCollectionViaXurlEffect({
 		...options,
 		collection: "liked_tweets",
 	});
 }
 
-export async function listBookmarkedTweetsViaXurl(options: {
+export function listLikedTweetsViaXurl(options: {
 	maxResults: number;
 	username?: string;
 	userId?: string;
-	isPaginatedWalk?: boolean;
 	paginationToken?: string;
 }): Promise<XurlMentionsResponse> {
-	return listTimelineCollectionViaXurl({
+	return runEffectPromise(listLikedTweetsViaXurlEffect(options));
+}
+
+export function listBookmarkedTweetsViaXurlEffect(options: {
+	maxResults: number;
+	username?: string;
+	userId?: string;
+	isPaginatedWalk?: boolean;
+	paginationToken?: string;
+}) {
+	return listTimelineCollectionViaXurlEffect({
 		...options,
 		collection: "bookmarks",
 	});
 }
 
-export async function listFollowUsersViaXurl({
+export function listBookmarkedTweetsViaXurl(options: {
+	maxResults: number;
+	username?: string;
+	userId?: string;
+	isPaginatedWalk?: boolean;
+	paginationToken?: string;
+}): Promise<XurlMentionsResponse> {
+	return runEffectPromise(listBookmarkedTweetsViaXurlEffect(options));
+}
+
+export function listDirectMessageEventsViaXurlEffect({
+	maxResults,
+	username,
+	paginationToken,
+}: {
+	maxResults: number;
+	username?: string;
+	paginationToken?: string;
+}): Effect.Effect<XurlDmEventsResponse, Error> {
+	const query = new URLSearchParams({
+		max_results: String(maxResults),
+		event_types: "MessageCreate",
+		"dm_event.fields": DM_EVENT_FIELDS,
+		expansions: "sender_id,participant_ids",
+		"user.fields": RICH_USER_FIELDS,
+	});
+	if (paginationToken) {
+		query.set("pagination_token", paginationToken);
+	}
+
+	return runOAuth2JsonCommandEffect({
+		args: [`/2/dm_events?${query.toString()}`],
+		username,
+	}).pipe(
+		Effect.map((payload) => ({
+			data: Array.isArray(payload.data)
+				? (payload.data as XurlDmEventsResponse["data"])
+				: [],
+			includes:
+				payload.includes && typeof payload.includes === "object"
+					? (payload.includes as XurlDmEventsResponse["includes"])
+					: undefined,
+			meta:
+				payload.meta && typeof payload.meta === "object"
+					? (payload.meta as Record<string, unknown>)
+					: undefined,
+		})),
+	);
+}
+
+export function listDirectMessageEventsViaXurl(options: {
+	maxResults: number;
+	username?: string;
+	paginationToken?: string;
+}): Promise<XurlDmEventsResponse> {
+	return runEffectPromise(listDirectMessageEventsViaXurlEffect(options));
+}
+
+export function listFollowUsersViaXurlEffect({
 	direction,
 	maxResults,
 	username,
@@ -563,50 +1180,45 @@ export async function listFollowUsersViaXurl({
 	username?: string;
 	userId?: string;
 	paginationToken?: string;
-}): Promise<XurlFollowUsersResponse> {
-	let resolvedUserId = userId;
-	if (!resolvedUserId) {
-		if (username) {
-			const [user] = await lookupUsersByHandles([username]);
-			if (!user?.id) {
-				throw new Error(`Could not resolve Twitter user id for @${username}`);
-			}
-			resolvedUserId = String(user.id);
-		} else {
-			const user = await lookupAuthenticatedUser();
-			if (!user?.id) {
-				throw new Error("Could not resolve authenticated Twitter user id");
-			}
-			resolvedUserId = String(user.id);
+}): Effect.Effect<XurlFollowUsersResponse, Error> {
+	return Effect.gen(function* () {
+		const resolvedUserId = yield* resolveUserIdEffect({ username, userId });
+		const query = new URLSearchParams({
+			max_results: String(maxResults),
+			"user.fields":
+				"id,username,name,description,verified,protected,public_metrics,profile_image_url,created_at",
+		});
+		if (paginationToken) {
+			query.set("pagination_token", paginationToken);
 		}
-	}
 
-	const query = new URLSearchParams({
-		max_results: String(maxResults),
-		"user.fields":
-			"id,username,name,description,verified,protected,public_metrics,profile_image_url,created_at",
+		const payload = yield* runOAuth2JsonCommandEffect({
+			args: [`/2/users/${resolvedUserId}/${direction}?${query.toString()}`],
+			username,
+		});
+		return {
+			data: Array.isArray(payload.data)
+				? (payload.data as XurlMentionUser[])
+				: [],
+			meta:
+				payload.meta && typeof payload.meta === "object"
+					? (payload.meta as Record<string, unknown>)
+					: undefined,
+		};
 	});
-	if (paginationToken) {
-		query.set("pagination_token", paginationToken);
-	}
+}
 
-	const payload = await runJsonCommand([
-		"--auth",
-		"oauth2",
-		`/2/users/${resolvedUserId}/${direction}?${query.toString()}`,
-	]);
-	return {
-		data: Array.isArray(payload.data)
-			? (payload.data as XurlMentionUser[])
-			: [],
-		meta:
-			payload.meta && typeof payload.meta === "object"
-				? (payload.meta as Record<string, unknown>)
-				: undefined,
-	};
+export function listFollowUsersViaXurl(options: {
+	direction: FollowDirection;
+	maxResults: number;
+	username?: string;
+	userId?: string;
+	paginationToken?: string;
+}): Promise<XurlFollowUsersResponse> {
+	return runEffectPromise(listFollowUsersViaXurlEffect(options));
 }
 
-export async function listBlockedUsers(
+export function listBlockedUsersEffect(
 	userId: string,
 	paginationToken?: string,
 ) {
@@ -619,25 +1231,30 @@ export async function listBlockedUsers(
 		query.set("pagination_token", paginationToken);
 	}
 
-	const payload = await runJsonCommand([
-		`/2/users/${userId}/blocking?${query}`,
-	]);
-	const data = Array.isArray(payload.data)
-		? (payload.data as XurlMentionUser[])
-		: [];
-	const meta =
-		payload.meta && typeof payload.meta === "object"
-			? (payload.meta as Record<string, unknown>)
-			: null;
+	return runJsonCommandEffect([`/2/users/${userId}/blocking?${query}`]).pipe(
+		Effect.map((payload) => {
+			const data = Array.isArray(payload.data)
+				? (payload.data as XurlMentionUser[])
+				: [];
+			const meta =
+				payload.meta && typeof payload.meta === "object"
+					? (payload.meta as Record<string, unknown>)
+					: null;
 
-	return {
-		items: data,
-		nextToken:
-			typeof meta?.next_token === "string" ? String(meta.next_token) : null,
-	};
+			return {
+				items: data,
+				nextToken:
+					typeof meta?.next_token === "string" ? String(meta.next_token) : null,
+			};
+		}),
+	);
+}
+
+export function listBlockedUsers(userId: string, paginationToken?: string) {
+	return runEffectPromise(listBlockedUsersEffect(userId, paginationToken));
 }
 
-export async function listUserTweets(
+export function listUserTweetsEffect(
 	userId: string,
 	{
 		maxResults,
@@ -650,6 +1267,10 @@ export async function listUserTweets(
 		userFields,
 		mediaFields,
 		auth,
+		username,
+		signal,
+		onAttempt,
+		useConfiguredCandidate,
 	}: {
 		maxResults: number;
 		paginationToken?: string;
@@ -661,8 +1282,12 @@ export async function listUserTweets(
 		userFields?: string[];
 		mediaFields?: string[];
 		auth?: "oauth2";
+		username?: string;
+		signal?: AbortSignal;
+		onAttempt?: JsonCommandOptions["onAttempt"];
+		useConfiguredCandidate?: boolean;
 	},
-): Promise<XurlUserTweetsResponse> {
+): Effect.Effect<XurlUserTweetsResponse, Error> {
 	const query = new URLSearchParams({
 		max_results: String(maxResults),
 		expansions: MEDIA_EXPANSION,
@@ -694,34 +1319,84 @@ export async function listUserTweets(
 	}
 
 	const endpoint = `/2/users/${userId}/tweets?${query}`;
-	const payload = await runJsonCommand(
-		auth === "oauth2" ? ["--auth", "oauth2", endpoint] : [endpoint],
+	const command =
+		auth === "oauth2"
+			? runOAuth2JsonCommandEffect({
+					args: [endpoint],
+					username,
+					options: { signal, onAttempt },
+					useConfiguredCandidate,
+				})
+			: runJsonCommandEffect([endpoint], { signal, onAttempt });
+	return command.pipe(
+		Effect.map((payload) => {
+			const data = Array.isArray(payload.data)
+				? (payload.data as XurlUserTweet[])
+				: [];
+			const meta =
+				payload.meta && typeof payload.meta === "object"
+					? (payload.meta as Record<string, unknown>)
+					: null;
+			const includes =
+				payload.includes && typeof payload.includes === "object"
+					? (payload.includes as XurlUserTweetsResponse["includes"])
+					: undefined;
+
+			return {
+				items: data,
+				nextToken:
+					typeof meta?.next_token === "string" ? String(meta.next_token) : null,
+				...(includes ? { includes } : {}),
+			};
+		}),
 	);
-	const data = Array.isArray(payload.data)
-		? (payload.data as XurlUserTweet[])
-		: [];
-	const meta =
-		payload.meta && typeof payload.meta === "object"
-			? (payload.meta as Record<string, unknown>)
-			: null;
-	const includes =
-		payload.includes && typeof payload.includes === "object"
-			? (payload.includes as XurlUserTweetsResponse["includes"])
-			: undefined;
+}
+
+export function listUserTweets(
+	userId: string,
+	options: {
+		maxResults: number;
+		paginationToken?: string;
+		excludeRetweets?: boolean;
+		sinceId?: string;
+		untilId?: string;
+		tweetFields?: string[];
+		expansions?: string[];
+		userFields?: string[];
+		mediaFields?: string[];
+		auth?: "oauth2";
+		username?: string;
+		signal?: AbortSignal;
+		onAttempt?: JsonCommandOptions["onAttempt"];
+		useConfiguredCandidate?: boolean;
+	},
+): Promise<XurlUserTweetsResponse> {
+	return runEffectPromise(listUserTweetsEffect(userId, options));
+}
 
+function toXurlTweetsResponse(
+	payload: Record<string, unknown>,
+): XurlTweetsResponse {
 	return {
-		items: data,
-		nextToken:
-			typeof meta?.next_token === "string" ? String(meta.next_token) : null,
-		...(includes ? { includes } : {}),
+		data: Array.isArray(payload.data)
+			? (payload.data as XurlTweetsResponse["data"])
+			: [],
+		includes:
+			payload.includes && typeof payload.includes === "object"
+				? (payload.includes as XurlTweetsResponse["includes"])
+				: undefined,
+		meta:
+			payload.meta && typeof payload.meta === "object"
+				? (payload.meta as XurlTweetsResponse["meta"])
+				: undefined,
 	};
 }
 
-export async function lookupTweetsByIds(
+export function lookupTweetsByIdsEffect(
 	ids: string[],
-): Promise<XurlTweetsResponse> {
+): Effect.Effect<XurlTweetsResponse, Error> {
 	if (ids.length === 0) {
-		return { data: [] };
+		return Effect.succeed({ data: [] });
 	}
 
 	const query = new URLSearchParams({
@@ -734,34 +1409,35 @@ export async function lookupTweetsByIds(
 			"description,entities,location,public_metrics,profile_image_url,url,created_at,verified,verified_type",
 	});
 
-	const payload = await runJsonCommand([`/2/tweets?${query.toString()}`]);
-	return {
-		data: Array.isArray(payload.data)
-			? (payload.data as XurlTweetsResponse["data"])
-			: [],
-		includes:
-			payload.includes && typeof payload.includes === "object"
-				? (payload.includes as XurlTweetsResponse["includes"])
-				: undefined,
-		meta:
-			payload.meta && typeof payload.meta === "object"
-				? (payload.meta as XurlTweetsResponse["meta"])
-				: undefined,
-	};
+	return runJsonCommandEffect([`/2/tweets?${query.toString()}`]).pipe(
+		Effect.map(toXurlTweetsResponse),
+	);
+}
+
+export function lookupTweetsByIds(ids: string[]): Promise<XurlTweetsResponse> {
+	return runEffectPromise(lookupTweetsByIdsEffect(ids));
 }
 
-export async function searchRecentByConversationId(
+export function searchRecentByConversationIdEffect(
 	conversationId: string,
 	{
 		maxResults,
 		paginationToken,
 		timeoutMs,
+		auth,
+		username,
+		signal,
+		onAttempt,
 	}: {
 		maxResults: number;
 		paginationToken?: string;
 		timeoutMs?: number;
+		auth?: "oauth2";
+		username?: string;
+		signal?: AbortSignal;
+		onAttempt?: JsonCommandOptions["onAttempt"];
 	},
-): Promise<XurlTweetsResponse> {
+): Effect.Effect<XurlTweetsResponse, Error> {
 	const query = new URLSearchParams({
 		query: `conversation_id:${conversationId}`,
 		max_results: String(maxResults),
@@ -774,29 +1450,98 @@ export async function searchRecentByConversationId(
 		query.set("pagination_token", paginationToken);
 	}
 
-	const payload = await runJsonCommand(
-		[`/2/tweets/search/recent?${query.toString()}`],
-		{ timeoutMs },
+	const args = [`/2/tweets/search/recent?${query.toString()}`];
+	const command =
+		auth === "oauth2"
+			? runOAuth2JsonCommandEffect({
+					args,
+					username,
+					options: { timeoutMs, signal, onAttempt },
+					useConfiguredCandidate: false,
+				})
+			: runJsonCommandEffect(args, { timeoutMs, signal, onAttempt });
+	return command.pipe(Effect.map(toXurlTweetsResponse));
+}
+
+export function searchRecentByConversationId(
+	conversationId: string,
+	options: {
+		maxResults: number;
+		paginationToken?: string;
+		timeoutMs?: number;
+		auth?: "oauth2";
+		username?: string;
+		signal?: AbortSignal;
+		onAttempt?: JsonCommandOptions["onAttempt"];
+	},
+): Promise<XurlTweetsResponse> {
+	return runEffectPromise(
+		searchRecentByConversationIdEffect(conversationId, options),
 	);
-	return {
-		data: Array.isArray(payload.data)
-			? (payload.data as XurlTweetsResponse["data"])
-			: [],
-		includes:
-			payload.includes && typeof payload.includes === "object"
-				? (payload.includes as XurlTweetsResponse["includes"])
-				: undefined,
-		meta:
-			payload.meta && typeof payload.meta === "object"
-				? (payload.meta as XurlTweetsResponse["meta"])
-				: undefined,
-	};
 }
 
-export async function getTweetById(
+export function searchRecentTweetsEffect(
+	searchQuery: string,
+	{
+		maxResults,
+		paginationToken,
+		startTime,
+		endTime,
+		username,
+		timeoutMs,
+	}: {
+		maxResults: number;
+		paginationToken?: string;
+		startTime?: string;
+		endTime?: string;
+		username?: string;
+		timeoutMs?: number;
+	},
+): Effect.Effect<XurlTweetsResponse, Error> {
+	const query = new URLSearchParams({
+		query: searchQuery,
+		max_results: String(maxResults),
+		expansions: AUTHOR_MEDIA_EXPANSIONS,
+		"tweet.fields": THREAD_TWEET_FIELDS,
+		"media.fields": MEDIA_FIELDS,
+		"user.fields": RICH_USER_FIELDS,
+	});
+	if (paginationToken) {
+		query.set("pagination_token", paginationToken);
+	}
+	if (startTime) {
+		query.set("start_time", startTime);
+	}
+	if (endTime) {
+		query.set("end_time", endTime);
+	}
+
+	return runOAuth2JsonCommandEffect({
+		args: [`/2/tweets/search/recent?${query.toString()}`],
+		username,
+		options: { timeoutMs },
+		useConfiguredCandidate: false,
+	}).pipe(Effect.map(toXurlTweetsResponse));
+}
+
+export function searchRecentTweets(
+	searchQuery: string,
+	options: {
+		maxResults: number;
+		paginationToken?: string;
+		startTime?: string;
+		endTime?: string;
+		username?: string;
+		timeoutMs?: number;
+	},
+): Promise<XurlTweetsResponse> {
+	return runEffectPromise(searchRecentTweetsEffect(searchQuery, options));
+}
+
+export function getTweetByIdEffect(
 	id: string,
 	{ timeoutMs }: { timeoutMs?: number } = {},
-): Promise<XurlTweetsResponse> {
+): Effect.Effect<XurlTweetsResponse, Error> {
 	const query = new URLSearchParams({
 		expansions: AUTHOR_MEDIA_EXPANSIONS,
 		"tweet.fields": THREAD_TWEET_FIELDS,
@@ -804,55 +1549,74 @@ export async function getTweetById(
 		"user.fields": RICH_USER_FIELDS,
 	});
 
-	const payload = await runJsonCommand(
-		[`/2/tweets/${id}?${query.toString()}`],
-		{
-			timeoutMs,
-		},
+	return runJsonCommandEffect([`/2/tweets/${id}?${query.toString()}`], {
+		timeoutMs,
+	}).pipe(
+		Effect.map((payload) => {
+			const data =
+				payload.data &&
+				typeof payload.data === "object" &&
+				!Array.isArray(payload.data)
+					? [payload.data as XurlTweetsResponse["data"][number]]
+					: Array.isArray(payload.data)
+						? (payload.data as XurlTweetsResponse["data"])
+						: [];
+
+			return {
+				data,
+				includes:
+					payload.includes && typeof payload.includes === "object"
+						? (payload.includes as XurlTweetsResponse["includes"])
+						: undefined,
+				meta:
+					payload.meta && typeof payload.meta === "object"
+						? (payload.meta as XurlTweetsResponse["meta"])
+						: undefined,
+			};
+		}),
 	);
-	const data =
-		payload.data &&
-		typeof payload.data === "object" &&
-		!Array.isArray(payload.data)
-			? [payload.data as XurlTweetsResponse["data"][number]]
-			: Array.isArray(payload.data)
-				? (payload.data as XurlTweetsResponse["data"])
-				: [];
+}
 
-	return {
-		data,
-		includes:
-			payload.includes && typeof payload.includes === "object"
-				? (payload.includes as XurlTweetsResponse["includes"])
-				: undefined,
-		meta:
-			payload.meta && typeof payload.meta === "object"
-				? (payload.meta as XurlTweetsResponse["meta"])
-				: undefined,
-	};
+export function getTweetById(
+	id: string,
+	options: { timeoutMs?: number } = {},
+): Promise<XurlTweetsResponse> {
+	return runEffectPromise(getTweetByIdEffect(id, options));
+}
+
+export function postViaXurlEffect(text: string) {
+	return runShortcutEffect(["post", text]);
+}
+
+export function postViaXurl(text: string) {
+	return runEffectPromise(postViaXurlEffect(text));
 }
 
-export async function postViaXurl(text: string) {
-	return runShortcut(["post", text]);
+export function replyViaXurlEffect(tweetId: string, text: string) {
+	return runShortcutEffect(["reply", tweetId, text]);
 }
 
-export async function replyViaXurl(tweetId: string, text: string) {
-	return runShortcut(["reply", tweetId, text]);
+export function replyViaXurl(tweetId: string, text: string) {
+	return runEffectPromise(replyViaXurlEffect(tweetId, text));
 }
 
-export async function dmViaXurl(handle: string, text: string) {
-	return runShortcut([
+export function dmViaXurlEffect(handle: string, text: string) {
+	return runShortcutEffect([
 		"dm",
 		handle.startsWith("@") ? handle : `@${handle}`,
 		text,
 	]);
 }
 
-export async function blockUserViaXurl(
+export function dmViaXurl(handle: string, text: string) {
+	return runEffectPromise(dmViaXurlEffect(handle, text));
+}
+
+export function blockUserViaXurlEffect(
 	sourceUserId: string,
 	targetUserId: string,
 ) {
-	return runMutationCommand([
+	return runMutationCommandEffect([
 		"-X",
 		"POST",
 		`/2/users/${sourceUserId}/blocking`,
@@ -861,22 +1625,30 @@ export async function blockUserViaXurl(
 	]);
 }
 
-export async function unblockUserViaXurl(
+export function blockUserViaXurl(sourceUserId: string, targetUserId: string) {
+	return runEffectPromise(blockUserViaXurlEffect(sourceUserId, targetUserId));
+}
+
+export function unblockUserViaXurlEffect(
 	sourceUserId: string,
 	targetUserId: string,
 ) {
-	return runMutationCommand([
+	return runMutationCommandEffect([
 		"-X",
 		"DELETE",
 		`/2/users/${sourceUserId}/blocking/${targetUserId}`,
 	]);
 }
 
-export async function muteUserViaXurl(
+export function unblockUserViaXurl(sourceUserId: string, targetUserId: string) {
+	return runEffectPromise(unblockUserViaXurlEffect(sourceUserId, targetUserId));
+}
+
+export function muteUserViaXurlEffect(
 	sourceUserId: string,
 	targetUserId: string,
 ) {
-	return runMutationCommand([
+	return runMutationCommandEffect([
 		"-X",
 		"POST",
 		`/2/users/${sourceUserId}/muting`,
@@ -885,13 +1657,21 @@ export async function muteUserViaXurl(
 	]);
 }
 
-export async function unmuteUserViaXurl(
+export function muteUserViaXurl(sourceUserId: string, targetUserId: string) {
+	return runEffectPromise(muteUserViaXurlEffect(sourceUserId, targetUserId));
+}
+
+export function unmuteUserViaXurlEffect(
 	sourceUserId: string,
 	targetUserId: string,
 ) {
-	return runMutationCommand([
+	return runMutationCommandEffect([
 		"-X",
 		"DELETE",
 		`/2/users/${sourceUserId}/muting/${targetUserId}`,
 	]);
 }
+
+export function unmuteUserViaXurl(sourceUserId: string, targetUserId: string) {
+	return runEffectPromise(unmuteUserViaXurlEffect(sourceUserId, targetUserId));
+}