birdclaw 0.6.0 → 0.7.0

package/src/lib/xurl.ts

@@ -4,6 +4,7 @@ import { Effect } from "effect";
 import { runEffectPromise } from "./effect-runtime";
 import type {
 	FollowDirection,
+	LiveDataSourceAccount,
 	TransportStatus,
 	XurlDmEventsResponse,
 	XurlFollowUsersResponse,
@@ -36,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:
@@ -52,6 +65,10 @@ 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";
@@ -139,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,
@@ -155,6 +183,7 @@ export function resetTransportStatusCache() {
 
 export function resetAuthenticatedUserCache() {
 	authenticatedUserCache = undefined;
+	oauth2CandidateCache.clear();
 }
 
 function hasXurlEffect() {
@@ -295,9 +324,66 @@ function runShortcutEffect(args: string[]) {
 function execXurlJsonEffect(
 	args: string[],
 	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,
+	});
+}
+
+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) &&
@@ -346,13 +432,27 @@ function runJsonCommandEffect(
 		const timeoutMs = deadlineMs
 			? Math.max(0, deadlineMs - Date.now())
 			: undefined;
-		return yield* execXurlJsonEffect(args, timeoutMs).pipe(
+		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;
@@ -370,6 +470,255 @@ function runJsonCommandEffect(
 	});
 }
 
+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;
+}
+
+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 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;
+		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,
+					});
+				}
+			}
+		}
+
+		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)),
+				);
+			}),
+		);
+	});
+}
+
 function runMutationCommandEffect(args: string[]) {
 	return Effect.gen(function* () {
 		if (liveWritesDisabled()) {
@@ -418,7 +767,15 @@ export function lookupUsersByIds(ids: string[]) {
 	return runEffectPromise(lookupUsersByIdsEffect(ids));
 }
 
-export function lookupUsersByHandlesEffect(handles: string[]) {
+export function lookupUsersByHandlesEffect(
+	handles: string[],
+	options: {
+		auth?: "oauth2";
+		username?: string;
+		signal?: AbortSignal;
+		useConfiguredCandidate?: boolean;
+	} = {},
+) {
 	if (handles.length === 0) {
 		return Effect.succeed([]);
 	}
@@ -428,15 +785,33 @@ export function lookupUsersByHandlesEffect(handles: string[]) {
 		"user.fields":
 			"description,entities,location,public_metrics,profile_image_url,url,created_at,verified,verified_type",
 	});
-	return runJsonCommandEffect([`/2/users/by?${query.toString()}`]).pipe(
+	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[]) {
-	return runEffectPromise(lookupUsersByHandlesEffect(handles));
+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>) {
@@ -452,18 +827,11 @@ export function lookupAuthenticatedUserFreshEffect() {
 	);
 }
 
-function oauth2UsernameArgs(username?: string) {
-	const normalized = username?.trim().replace(/^@/, "");
-	return normalized ? ["--username", normalized] : [];
-}
-
 export function lookupAuthenticatedOAuth2UserEffect(username?: string) {
-	return runJsonCommandEffect([
-		"--auth",
-		"oauth2",
-		...oauth2UsernameArgs(username),
-		"whoami",
-	]).pipe(Effect.map(authenticatedUserFromPayload));
+	return runOAuth2JsonCommandEffect({
+		args: ["whoami"],
+		username,
+	}).pipe(Effect.map(authenticatedUserFromPayload));
 }
 
 export function lookupAuthenticatedUserEffect() {
@@ -580,9 +948,10 @@ export function listMentionsViaXurlEffect({
 			query.set("start_time", startTime);
 		}
 
-		const payload = yield* runJsonCommandEffect([
-			`/2/users/${resolvedUserId}/mentions?${query.toString()}`,
-		]);
+		const payload = yield* runOAuth2JsonCommandEffect({
+			args: [`/2/users/${resolvedUserId}/mentions?${query.toString()}`],
+			username,
+		});
 		return toXurlMentionsResponse(payload);
 	});
 }
@@ -598,6 +967,54 @@ export function listMentionsViaXurl(options: {
 	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 payload = yield* runOAuth2JsonCommandEffect({
+			args: [
+				`/2/users/${resolvedUserId}/timelines/reverse_chronological?${query.toString()}`,
+			],
+			username,
+			options: { timeoutMs },
+		});
+		return toXurlMentionsResponse(payload);
+	});
+}
+
+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 {
@@ -651,11 +1068,10 @@ function listTimelineCollectionViaXurlEffect({
 			query.set("pagination_token", paginationToken);
 		}
 
-		const payload = yield* runJsonCommandEffect([
-			"--auth",
-			"oauth2",
-			`/2/users/${resolvedUserId}/${collection}?${query.toString()}`,
-		]);
+		const payload = yield* runOAuth2JsonCommandEffect({
+			args: [`/2/users/${resolvedUserId}/${collection}?${query.toString()}`],
+			username,
+		});
 		return toXurlMentionsResponse(payload);
 	});
 }
@@ -724,12 +1140,10 @@ export function listDirectMessageEventsViaXurlEffect({
 		query.set("pagination_token", paginationToken);
 	}
 
-	return runJsonCommandEffect([
-		"--auth",
-		"oauth2",
-		...oauth2UsernameArgs(username),
-		`/2/dm_events?${query.toString()}`,
-	]).pipe(
+	return runOAuth2JsonCommandEffect({
+		args: [`/2/dm_events?${query.toString()}`],
+		username,
+	}).pipe(
 		Effect.map((payload) => ({
 			data: Array.isArray(payload.data)
 				? (payload.data as XurlDmEventsResponse["data"])
@@ -778,11 +1192,10 @@ export function listFollowUsersViaXurlEffect({
 			query.set("pagination_token", paginationToken);
 		}
 
-		const payload = yield* runJsonCommandEffect([
-			"--auth",
-			"oauth2",
-			`/2/users/${resolvedUserId}/${direction}?${query.toString()}`,
-		]);
+		const payload = yield* runOAuth2JsonCommandEffect({
+			args: [`/2/users/${resolvedUserId}/${direction}?${query.toString()}`],
+			username,
+		});
 		return {
 			data: Array.isArray(payload.data)
 				? (payload.data as XurlMentionUser[])
@@ -854,6 +1267,10 @@ export function listUserTweetsEffect(
 		userFields,
 		mediaFields,
 		auth,
+		username,
+		signal,
+		onAttempt,
+		useConfiguredCandidate,
 	}: {
 		maxResults: number;
 		paginationToken?: string;
@@ -865,6 +1282,10 @@ export function listUserTweetsEffect(
 		userFields?: string[];
 		mediaFields?: string[];
 		auth?: "oauth2";
+		username?: string;
+		signal?: AbortSignal;
+		onAttempt?: JsonCommandOptions["onAttempt"];
+		useConfiguredCandidate?: boolean;
 	},
 ): Effect.Effect<XurlUserTweetsResponse, Error> {
 	const query = new URLSearchParams({
@@ -898,9 +1319,16 @@ export function listUserTweetsEffect(
 	}
 
 	const endpoint = `/2/users/${userId}/tweets?${query}`;
-	return runJsonCommandEffect(
-		auth === "oauth2" ? ["--auth", "oauth2", endpoint] : [endpoint],
-	).pipe(
+	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[])
@@ -937,6 +1365,10 @@ export function listUserTweets(
 		userFields?: string[];
 		mediaFields?: string[];
 		auth?: "oauth2";
+		username?: string;
+		signal?: AbortSignal;
+		onAttempt?: JsonCommandOptions["onAttempt"];
+		useConfiguredCandidate?: boolean;
 	},
 ): Promise<XurlUserTweetsResponse> {
 	return runEffectPromise(listUserTweetsEffect(userId, options));
@@ -992,10 +1424,18 @@ export function searchRecentByConversationIdEffect(
 		maxResults,
 		paginationToken,
 		timeoutMs,
+		auth,
+		username,
+		signal,
+		onAttempt,
 	}: {
 		maxResults: number;
 		paginationToken?: string;
 		timeoutMs?: number;
+		auth?: "oauth2";
+		username?: string;
+		signal?: AbortSignal;
+		onAttempt?: JsonCommandOptions["onAttempt"];
 	},
 ): Effect.Effect<XurlTweetsResponse, Error> {
 	const query = new URLSearchParams({
@@ -1010,9 +1450,17 @@ export function searchRecentByConversationIdEffect(
 		query.set("pagination_token", paginationToken);
 	}
 
-	return runJsonCommandEffect([`/2/tweets/search/recent?${query.toString()}`], {
-		timeoutMs,
-	}).pipe(Effect.map(toXurlTweetsResponse));
+	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(
@@ -1021,6 +1469,10 @@ export function searchRecentByConversationId(
 		maxResults: number;
 		paginationToken?: string;
 		timeoutMs?: number;
+		auth?: "oauth2";
+		username?: string;
+		signal?: AbortSignal;
+		onAttempt?: JsonCommandOptions["onAttempt"];
 	},
 ): Promise<XurlTweetsResponse> {
 	return runEffectPromise(
@@ -1028,6 +1480,64 @@ export function searchRecentByConversationId(
 	);
 }
 
+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 } = {},