birdclaw 0.4.0 → 0.5.0

package/src/lib/xurl.ts

@@ -1,17 +1,37 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import type {
+	FollowDirection,
 	TransportStatus,
+	XurlFollowUsersResponse,
 	XurlMentionsResponse,
 	XurlMentionUser,
 	XurlTweetsResponse,
 	XurlUserTweet,
+	XurlUserTweetsResponse,
 } from "./types";
 
 const execFileAsync = promisify(execFile);
 const TRANSPORT_STATUS_TTL_MS = 5 * 60_000;
 const AUTHENTICATED_USER_TTL_MS = 60_000;
 const JSON_RETRY_LIMIT = 6;
+const MEDIA_EXPANSION = "attachments.media_keys";
+const AUTHOR_MEDIA_EXPANSIONS = `author_id,${MEDIA_EXPANSION}`;
+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 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:
+// https://devcommunity.x.com/t/bookmarks-api-v2-stops-paginating-after-3-pages-no-next-token-returned/257339
+const BOOKMARKS_MAX_RESULTS_CAP = 90;
+
+type TimelineCollectionEndpoint = "liked_tweets" | "bookmarks";
+type JsonCommandOptions = {
+	timeoutMs?: number;
+	deadlineMs?: number;
+};
 
 let transportStatusCache:
 	| {
@@ -66,6 +86,10 @@ function formatExecError(error: unknown, fallback: string) {
 	return parts.join("\n");
 }
 
+function formatXurlCommandError(error: unknown, args: string[]) {
+	return new Error(formatExecError(error, `xurl ${args.join(" ")} failed`));
+}
+
 function parseErrorPayload(error: unknown) {
 	const stdout =
 		typeof error === "object" &&
@@ -99,6 +123,16 @@ function getRetryDelayMs(error: unknown, attempt: number) {
 	return Math.min(baseDelay * 2 ** attempt, 30_000);
 }
 
+function capTimelineCollectionMaxResults(
+	collection: TimelineCollectionEndpoint,
+	maxResults: number,
+	isPaginatedWalk: boolean,
+) {
+	return collection === "bookmarks" && isPaginatedWalk
+		? Math.min(maxResults, BOOKMARKS_MAX_RESULTS_CAP)
+		: maxResults;
+}
+
 async function sleep(ms: number) {
 	if (ms <= 0) {
 		return;
@@ -123,6 +157,12 @@ async function hasXurl(): Promise<boolean> {
 	}
 }
 
+function isUnauthenticatedXurlStatus(status: string) {
+	return /no apps registered|no authenticated user|not authenticated|not logged in/i.test(
+		status,
+	);
+}
+
 export async function getTransportStatus(): Promise<TransportStatus> {
 	const now = Date.now();
 	if (transportStatusCache?.value && transportStatusCache.expiresAt > now) {
@@ -145,11 +185,23 @@ export async function getTransportStatus(): Promise<TransportStatus> {
 
 		try {
 			const { stdout } = await execFileAsync("xurl", ["auth", "status"]);
+			const rawStatus = stdout.trim();
+
+			if (isUnauthenticatedXurlStatus(rawStatus)) {
+				return {
+					installed: true,
+					availableTransport: "local",
+					statusText:
+						"xurl installed but not authenticated. local (bird) mode active.",
+					rawStatus,
+				};
+			}
+
 			return {
 				installed: true,
 				availableTransport: "xurl",
 				statusText: "xurl available",
-				rawStatus: stdout.trim(),
+				rawStatus,
 			};
 		} catch (error) {
 			return {
@@ -198,18 +250,52 @@ async function runShortcut(
 	}
 }
 
-async function runJsonCommand(args: string[], attempt = 0) {
+async function runJsonCommand(
+	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()
+			: undefined;
+	const timeout = controller
+		? setTimeout(() => controller.abort(), timeoutMs)
+		: undefined;
+
 	try {
-		const { stdout } = await execFileAsync("xurl", args);
+		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 error;
+			throw formatXurlCommandError(error, args);
+		}
+		const remainingMs = deadlineMs
+			? Math.max(0, deadlineMs - Date.now())
+			: undefined;
+		if (remainingMs !== undefined && retryDelayMs >= remainingMs) {
+			throw formatXurlCommandError(error, args);
 		}
 
 		await sleep(retryDelayMs);
-		return runJsonCommand(args, attempt + 1);
+		return runJsonCommand(args, { ...options, deadlineMs }, attempt + 1);
+	} finally {
+		if (timeout) {
+			clearTimeout(timeout);
+		}
 	}
 }
 
@@ -307,11 +393,15 @@ export async function listMentionsViaXurl({
 	username,
 	userId,
 	paginationToken,
+	sinceId,
+	startTime,
 }: {
 	maxResults: number;
 	username?: string;
 	userId?: string;
 	paginationToken?: string;
+	sinceId?: string;
+	startTime?: string;
 }): Promise<XurlMentionsResponse> {
 	let resolvedUserId = userId;
 	if (!resolvedUserId) {
@@ -332,14 +422,21 @@ export async function listMentionsViaXurl({
 
 	const query = new URLSearchParams({
 		max_results: String(maxResults),
-		expansions: "author_id",
+		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 = await runJsonCommand([
 		`/2/users/${resolvedUserId}/mentions?${query.toString()}`,
@@ -364,12 +461,14 @@ async function listTimelineCollectionViaXurl({
 	maxResults,
 	username,
 	userId,
+	isPaginatedWalk = false,
 	paginationToken,
 }: {
-	collection: "liked_tweets" | "bookmarks";
+	collection: TimelineCollectionEndpoint;
 	maxResults: number;
 	username?: string;
 	userId?: string;
+	isPaginatedWalk?: boolean;
 	paginationToken?: string;
 }): Promise<XurlMentionsResponse> {
 	let resolvedUserId = userId;
@@ -389,11 +488,17 @@ async function listTimelineCollectionViaXurl({
 		}
 	}
 
+	const requestMaxResults = capTimelineCollectionMaxResults(
+		collection,
+		maxResults,
+		isPaginatedWalk,
+	);
 	const query = new URLSearchParams({
-		max_results: String(maxResults),
-		expansions: "author_id",
+		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",
 	});
@@ -437,6 +542,7 @@ export async function listBookmarkedTweetsViaXurl(options: {
 	maxResults: number;
 	username?: string;
 	userId?: string;
+	isPaginatedWalk?: boolean;
 	paginationToken?: string;
 }): Promise<XurlMentionsResponse> {
 	return listTimelineCollectionViaXurl({
@@ -445,6 +551,61 @@ export async function listBookmarkedTweetsViaXurl(options: {
 	});
 }
 
+export async function listFollowUsersViaXurl({
+	direction,
+	maxResults,
+	username,
+	userId,
+	paginationToken,
+}: {
+	direction: FollowDirection;
+	maxResults: number;
+	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);
+		}
+	}
+
+	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 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 async function listBlockedUsers(
 	userId: string,
 	paginationToken?: string,
@@ -482,17 +643,49 @@ export async function listUserTweets(
 		maxResults,
 		paginationToken,
 		excludeRetweets = true,
+		sinceId,
+		untilId,
+		tweetFields,
+		expansions,
+		userFields,
+		mediaFields,
+		auth,
 	}: {
 		maxResults: number;
 		paginationToken?: string;
 		excludeRetweets?: boolean;
+		sinceId?: string;
+		untilId?: string;
+		tweetFields?: string[];
+		expansions?: string[];
+		userFields?: string[];
+		mediaFields?: string[];
+		auth?: "oauth2";
 	},
-) {
+): Promise<XurlUserTweetsResponse> {
 	const query = new URLSearchParams({
 		max_results: String(maxResults),
+		expansions: MEDIA_EXPANSION,
 		"tweet.fields":
+			tweetFields?.join(",") ??
 			"created_at,conversation_id,public_metrics,referenced_tweets",
+		"media.fields": MEDIA_FIELDS,
 	});
+	if (expansions && expansions.length > 0) {
+		query.set("expansions", expansions.join(","));
+	}
+	if (userFields && userFields.length > 0) {
+		query.set("user.fields", userFields.join(","));
+	}
+	if (mediaFields && mediaFields.length > 0) {
+		query.set("media.fields", mediaFields.join(","));
+	}
+	if (sinceId) {
+		query.set("since_id", sinceId);
+	}
+	if (untilId) {
+		query.set("until_id", untilId);
+	}
 	if (excludeRetweets) {
 		query.set("exclude", "retweets");
 	}
@@ -500,7 +693,10 @@ export async function listUserTweets(
 		query.set("pagination_token", paginationToken);
 	}
 
-	const payload = await runJsonCommand([`/2/users/${userId}/tweets?${query}`]);
+	const endpoint = `/2/users/${userId}/tweets?${query}`;
+	const payload = await runJsonCommand(
+		auth === "oauth2" ? ["--auth", "oauth2", endpoint] : [endpoint],
+	);
 	const data = Array.isArray(payload.data)
 		? (payload.data as XurlUserTweet[])
 		: [];
@@ -508,11 +704,16 @@ export async function listUserTweets(
 		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 } : {}),
 	};
 }
 
@@ -525,9 +726,10 @@ export async function lookupTweetsByIds(
 
 	const query = new URLSearchParams({
 		ids: ids.join(","),
-		expansions: "author_id",
+		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",
 	});
@@ -548,6 +750,88 @@ export async function lookupTweetsByIds(
 	};
 }
 
+export async function searchRecentByConversationId(
+	conversationId: string,
+	{
+		maxResults,
+		paginationToken,
+		timeoutMs,
+	}: {
+		maxResults: number;
+		paginationToken?: string;
+		timeoutMs?: number;
+	},
+): Promise<XurlTweetsResponse> {
+	const query = new URLSearchParams({
+		query: `conversation_id:${conversationId}`,
+		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);
+	}
+
+	const payload = await runJsonCommand(
+		[`/2/tweets/search/recent?${query.toString()}`],
+		{ timeoutMs },
+	);
+	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(
+	id: string,
+	{ timeoutMs }: { timeoutMs?: number } = {},
+): Promise<XurlTweetsResponse> {
+	const query = new URLSearchParams({
+		expansions: AUTHOR_MEDIA_EXPANSIONS,
+		"tweet.fields": THREAD_TWEET_FIELDS,
+		"media.fields": MEDIA_FIELDS,
+		"user.fields": RICH_USER_FIELDS,
+	});
+
+	const payload = await runJsonCommand(
+		[`/2/tweets/${id}?${query.toString()}`],
+		{
+			timeoutMs,
+		},
+	);
+	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 async function postViaXurl(text: string) {
 	return runShortcut(["post", text]);
 }