birdclaw 0.1.0

package/src/lib/avatar-cache.ts

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { getBirdclawPaths } from "./config";
+import { getNativeDb } from "./db";
+
+const AVATAR_SIZE_SUFFIX =
+	/(?:(?:_normal|_bigger|_mini))(?=\.(?:jpg|jpeg|png|webp|gif)(?:$|\?))/i;
+
+function sanitizeFileToken(value: string) {
+	return value.replace(/[^a-zA-Z0-9_-]+/g, "_");
+}
+
+function getAvatarCacheDir() {
+	const { mediaThumbsDir } = getBirdclawPaths();
+	const dir = path.join(mediaThumbsDir, "avatars");
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+function getExtensionFromContentType(contentType: string | null) {
+	const mime = contentType?.split(";")[0].trim().toLowerCase() ?? "";
+	if (mime === "image/png") return ".png";
+	if (mime === "image/webp") return ".webp";
+	if (mime === "image/gif") return ".gif";
+	if (mime === "image/svg+xml") return ".svg";
+	return ".jpg";
+}
+
+function getContentTypeFromExtension(extension: string) {
+	switch (extension.toLowerCase()) {
+		case ".png":
+			return "image/png";
+		case ".webp":
+			return "image/webp";
+		case ".gif":
+			return "image/gif";
+		case ".svg":
+			return "image/svg+xml";
+		default:
+			return "image/jpeg";
+	}
+}
+
+function getExtensionFromAvatarUrl(avatarUrl: string) {
+	try {
+		const url = new URL(avatarUrl);
+		const extension = path.extname(url.pathname).toLowerCase();
+		if (extension === ".png" || extension === ".webp" || extension === ".gif") {
+			return extension;
+		}
+		return extension === ".svg" ? ".svg" : ".jpg";
+	} catch {
+		return ".jpg";
+	}
+}
+
+function decodeDataUrl(dataUrl: string) {
+	if (!dataUrl.startsWith("data:")) {
+		throw new Error("Invalid avatar data URL");
+	}
+
+	const separatorIndex = dataUrl.indexOf(",");
+	if (separatorIndex < 0) {
+		throw new Error("Invalid avatar data URL");
+	}
+
+	const metadata = dataUrl.slice(5, separatorIndex);
+	const payload = dataUrl.slice(separatorIndex + 1);
+	const contentType = metadata.split(";")[0] || "application/octet-stream";
+	const isBase64 = metadata.includes(";base64");
+	return {
+		contentType,
+		buffer: isBase64
+			? Buffer.from(payload, "base64")
+			: Buffer.from(decodeURIComponent(payload), "utf8"),
+	};
+}
+
+function getAvatarUrlForProfile(profileId: string) {
+	const row = getNativeDb()
+		.prepare("select avatar_url from profiles where id = ?")
+		.get(profileId) as { avatar_url: string | null } | undefined;
+	return row?.avatar_url ?? null;
+}
+
+export function normalizeAvatarUrl(value: unknown) {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		return null;
+	}
+
+	const trimmed = value.trim();
+	if (trimmed.startsWith("data:image/")) {
+		return trimmed;
+	}
+
+	try {
+		const url = new URL(trimmed);
+		url.pathname = url.pathname.replace(AVATAR_SIZE_SUFFIX, "");
+		return url.toString();
+	} catch {
+		return trimmed;
+	}
+}
+
+export function getAvatarCachePath(profileId: string, avatarUrl: string) {
+	const normalizedAvatarUrl = normalizeAvatarUrl(avatarUrl);
+	if (!normalizedAvatarUrl) {
+		throw new Error("Missing avatar URL");
+	}
+
+	const hash = createHash("sha1").update(normalizedAvatarUrl).digest("hex");
+	const extension = normalizedAvatarUrl.startsWith("data:")
+		? getExtensionFromContentType(
+				/^data:([^;,]+)/i.exec(normalizedAvatarUrl)?.[1] ?? null,
+			)
+		: getExtensionFromAvatarUrl(normalizedAvatarUrl);
+
+	return path.join(
+		getAvatarCacheDir(),
+		`${sanitizeFileToken(profileId)}-${hash}${extension}`,
+	);
+}
+
+async function fetchRemoteAvatar(avatarUrl: string) {
+	const response = await fetch(avatarUrl, {
+		headers: {
+			"user-agent": "birdclaw/avatar-cache",
+		},
+	});
+	if (!response.ok) {
+		throw new Error(`Avatar fetch failed with ${response.status}`);
+	}
+
+	const buffer = Buffer.from(await response.arrayBuffer());
+	return {
+		contentType: response.headers.get("content-type") ?? "image/jpeg",
+		buffer,
+	};
+}
+
+export async function readCachedAvatar(profileId: string) {
+	const avatarUrl = getAvatarUrlForProfile(profileId);
+	if (!avatarUrl) {
+		return null;
+	}
+
+	const normalizedAvatarUrl = normalizeAvatarUrl(avatarUrl);
+	if (!normalizedAvatarUrl) {
+		return null;
+	}
+
+	const cachePath = getAvatarCachePath(profileId, normalizedAvatarUrl);
+	const cachedExtension = path.extname(cachePath);
+
+	try {
+		return {
+			buffer: readFileSync(cachePath),
+			contentType: getContentTypeFromExtension(cachedExtension),
+			cachePath,
+			avatarUrl: normalizedAvatarUrl,
+		};
+	} catch {
+		const payload = normalizedAvatarUrl.startsWith("data:")
+			? decodeDataUrl(normalizedAvatarUrl)
+			: await fetchRemoteAvatar(normalizedAvatarUrl);
+
+		writeFileSync(cachePath, payload.buffer);
+		return {
+			buffer: payload.buffer,
+			contentType: payload.contentType,
+			cachePath,
+			avatarUrl: normalizedAvatarUrl,
+		};
+	}
+}
+
+export const __test__ = {
+	decodeDataUrl,
+	getAvatarCacheDir,
+	getContentTypeFromExtension,
+	getExtensionFromAvatarUrl,
+	sanitizeFileToken,
+};

package/src/lib/bird-actions.ts

@@ -0,0 +1,200 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getBirdCommand } from "./config";
+import type { XurlMentionUser } from "./types";
+
+const execFileAsync = promisify(execFile);
+
+function liveWritesDisabled() {
+	return process.env.BIRDCLAW_DISABLE_LIVE_WRITES === "1";
+}
+
+function stripAnsi(value: string) {
+	// ANSI escape parsing needs a constructor to avoid literal control characters.
+	return value.replace(new RegExp("\\u001b\\[[0-9;]*m", "g"), "");
+}
+
+function formatExecError(error: unknown, fallback: string) {
+	if (!(error instanceof Error)) {
+		return fallback;
+	}
+
+	const parts = [error.message];
+	if (
+		"stdout" in error &&
+		typeof error.stdout === "string" &&
+		error.stdout.trim().length > 0
+	) {
+		parts.push(stripAnsi(error.stdout).trim());
+	}
+	if (
+		"stderr" in error &&
+		typeof error.stderr === "string" &&
+		error.stderr.trim().length > 0
+	) {
+		parts.push(stripAnsi(error.stderr).trim());
+	}
+
+	return parts.join("\n");
+}
+
+function normalizeOutput(stdout?: string, stderr?: string) {
+	return stripAnsi(stdout || stderr || "ok").trim();
+}
+
+async function runBirdCommand(args: string[]) {
+	const birdCommand = getBirdCommand();
+	return execFileAsync(birdCommand, args);
+}
+
+async function runBirdJsonCommand(args: string[]) {
+	const { stdout } = await runBirdCommand(args);
+	return JSON.parse(stripAnsi(stdout)) as Record<string, unknown>;
+}
+
+export async function readBirdStatusViaBird(query: string) {
+	try {
+		const payload = await runBirdJsonCommand(["status", query, "--json"]);
+		return payload;
+	} catch {
+		return null;
+	}
+}
+
+function toBirdLookupUser(payload: Record<string, unknown>): XurlMentionUser {
+	const user =
+		payload.user && typeof payload.user === "object"
+			? (payload.user as Record<string, unknown>)
+			: null;
+	if (!user) {
+		throw new Error("bird user payload missing user object");
+	}
+
+	const id = typeof user.id === "string" ? user.id : "";
+	const username =
+		typeof user.username === "string"
+			? user.username.replace(/^@/, "").trim()
+			: "";
+	if (!id || !username) {
+		throw new Error("bird user payload missing id or username");
+	}
+
+	const followersCount = Number(user.followersCount ?? 0);
+	return {
+		id,
+		name:
+			typeof user.name === "string" && user.name.trim().length > 0
+				? user.name
+				: username,
+		username,
+		description:
+			typeof user.description === "string" ? user.description : undefined,
+		profile_image_url:
+			typeof user.profileImageUrl === "string"
+				? user.profileImageUrl
+				: undefined,
+		public_metrics: {
+			followers_count: Number.isFinite(followersCount) ? followersCount : 0,
+		},
+		created_at: typeof user.createdAt === "string" ? user.createdAt : undefined,
+	};
+}
+
+export async function lookupProfileViaBird(query: string) {
+	try {
+		const payload = await runBirdJsonCommand([
+			"user",
+			query,
+			"-n",
+			"1",
+			"--json",
+		]);
+		return toBirdLookupUser(payload);
+	} catch {
+		return null;
+	}
+}
+
+async function runVerifiedBirdMutation({
+	action,
+	query,
+	verifyField,
+	expectedValue,
+}: {
+	action: "block" | "unblock" | "mute" | "unmute";
+	query: string;
+	verifyField: "blocking" | "muting";
+	expectedValue: boolean;
+}) {
+	if (liveWritesDisabled()) {
+		return { ok: true, output: "live writes disabled" };
+	}
+
+	let baseOutput = "";
+	try {
+		const { stdout, stderr } = await runBirdCommand([action, query]);
+		baseOutput = normalizeOutput(stdout, stderr);
+	} catch (error) {
+		return {
+			ok: false,
+			output: formatExecError(error, `bird ${action} failed`),
+		};
+	}
+
+	const status = await readBirdStatusViaBird(query);
+	if (!status || typeof status[verifyField] !== "boolean") {
+		return {
+			ok: false,
+			output: `${baseOutput}; bird status verify unavailable`,
+		};
+	}
+
+	const actualValue = Boolean(status[verifyField]);
+	if (actualValue !== expectedValue) {
+		return {
+			ok: false,
+			output: `${baseOutput}; bird status verify ${verifyField}=${String(actualValue)}`,
+		};
+	}
+
+	return {
+		ok: true,
+		output: `${baseOutput}; verified ${verifyField}=${String(actualValue)}`,
+	};
+}
+
+export async function blockUserViaBird(query: string) {
+	return runVerifiedBirdMutation({
+		action: "block",
+		query,
+		verifyField: "blocking",
+		expectedValue: true,
+	});
+}
+
+export async function unblockUserViaBird(query: string) {
+	return runVerifiedBirdMutation({
+		action: "unblock",
+		query,
+		verifyField: "blocking",
+		expectedValue: false,
+	});
+}
+
+export async function muteUserViaBird(query: string) {
+	return runVerifiedBirdMutation({
+		action: "mute",
+		query,
+		verifyField: "muting",
+		expectedValue: true,
+	});
+}
+
+export async function unmuteUserViaBird(query: string) {
+	return runVerifiedBirdMutation({
+		action: "unmute",
+		query,
+		verifyField: "muting",
+		expectedValue: false,
+	});
+}

package/src/lib/bird.ts

@@ -0,0 +1,183 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getBirdCommand } from "./config";
+import type {
+	XurlMentionData,
+	XurlMentionsResponse,
+	XurlMentionUser,
+} from "./types";
+
+const execFileAsync = promisify(execFile);
+
+interface BirdMentionMedia {
+	type?: string;
+	url?: string;
+}
+
+interface BirdMentionAuthor {
+	username?: string;
+	name?: string;
+}
+
+interface BirdMentionItem {
+	id: string;
+	text: string;
+	createdAt: string;
+	replyCount?: number;
+	retweetCount?: number;
+	likeCount?: number;
+	conversationId?: string;
+	inReplyToStatusId?: string;
+	author?: BirdMentionAuthor;
+	authorId?: string;
+	media?: BirdMentionMedia[];
+}
+
+export interface BirdDmUser {
+	id: string;
+	username?: string;
+	name?: string;
+	profileImageUrl?: string;
+}
+
+export interface BirdDmEvent {
+	id: string;
+	conversationId?: string;
+	text: string;
+	createdAt?: string;
+	senderId?: string;
+	recipientId?: string;
+	sender?: BirdDmUser;
+	recipient?: BirdDmUser;
+}
+
+export interface BirdDmConversation {
+	id: string;
+	participants: BirdDmUser[];
+	messages: BirdDmEvent[];
+	lastMessageAt?: string;
+	lastMessagePreview?: string;
+}
+
+export interface BirdDmsResponse {
+	success: true;
+	conversations: BirdDmConversation[];
+	events: BirdDmEvent[];
+}
+
+function toIsoTimestamp(value: string) {
+	const parsed = new Date(value);
+	if (Number.isNaN(parsed.getTime())) {
+		return value;
+	}
+	return parsed.toISOString();
+}
+
+function toMediaEntities(media: BirdMentionMedia[] | undefined) {
+	if (!Array.isArray(media) || media.length === 0) {
+		return undefined;
+	}
+
+	return {
+		urls: media
+			.filter((item) => typeof item?.url === "string" && item.url.length > 0)
+			.map((item, index) => ({
+				start: index,
+				end: index,
+				url: item.url as string,
+				expanded_url: item.url as string,
+				display_url: item.url as string,
+				media_key: `bird_media_${index}`,
+			})),
+	};
+}
+
+function normalizeBirdMentions(items: BirdMentionItem[]): XurlMentionsResponse {
+	const users = new Map<string, XurlMentionUser>();
+	const data = items.map((item): XurlMentionData => {
+		const authorId = String(
+			item.authorId ?? item.author?.username ?? "unknown",
+		);
+		if (!users.has(authorId)) {
+			users.set(authorId, {
+				id: authorId,
+				username: item.author?.username ?? `user_${authorId}`,
+				name: item.author?.name ?? item.author?.username ?? `user_${authorId}`,
+			});
+		}
+
+		return {
+			id: item.id,
+			author_id: authorId,
+			text: item.text,
+			created_at: toIsoTimestamp(item.createdAt),
+			conversation_id: item.conversationId ?? item.id,
+			entities: toMediaEntities(item.media),
+			public_metrics: {
+				reply_count: Number(item.replyCount ?? 0),
+				retweet_count: Number(item.retweetCount ?? 0),
+				like_count: Number(item.likeCount ?? 0),
+			},
+			edit_history_tweet_ids: [item.id],
+		};
+	});
+
+	return {
+		data,
+		includes:
+			users.size > 0 ? { users: Array.from(users.values()) } : undefined,
+		meta: {
+			result_count: data.length,
+			page_count: 1,
+			next_token: null,
+			...(data[0] ? { newest_id: data[0].id } : {}),
+			...(data.at(-1) ? { oldest_id: data.at(-1)?.id } : {}),
+		},
+	};
+}
+
+export async function listMentionsViaBird({
+	maxResults,
+}: {
+	maxResults: number;
+}): Promise<XurlMentionsResponse> {
+	const birdCommand = getBirdCommand();
+	const { stdout } = await execFileAsync(birdCommand, [
+		"mentions",
+		"-n",
+		String(maxResults),
+		"--json",
+	]);
+	const payload = JSON.parse(stdout) as unknown;
+	if (!Array.isArray(payload)) {
+		throw new Error("bird mentions returned unexpected JSON");
+	}
+
+	return normalizeBirdMentions(payload as BirdMentionItem[]);
+}
+
+export async function listDirectMessagesViaBird({
+	maxResults,
+}: {
+	maxResults: number;
+}): Promise<BirdDmsResponse> {
+	const birdCommand = getBirdCommand();
+	const { stdout } = await execFileAsync(birdCommand, [
+		"dms",
+		"-n",
+		String(maxResults),
+		"--json",
+	]);
+	const payload = JSON.parse(stdout) as unknown;
+	if (
+		!payload ||
+		typeof payload !== "object" ||
+		(payload as { success?: unknown }).success !== true ||
+		!Array.isArray((payload as { conversations?: unknown }).conversations) ||
+		!Array.isArray((payload as { events?: unknown }).events)
+	) {
+		throw new Error("bird dms returned unexpected JSON");
+	}
+
+	return payload as BirdDmsResponse;
+}

package/src/lib/blocklist.ts

@@ -0,0 +1,119 @@
+import { readFile } from "node:fs/promises";
+import { addBlock } from "./blocks";
+
+export interface BlocklistImportItem {
+	query: string;
+	ok: boolean;
+	blockedAt?: string;
+	handle?: string;
+	error?: string;
+}
+
+export interface BlocklistImportResult {
+	ok: boolean;
+	accountId: string;
+	path: string;
+	requestedCount: number;
+	blockedCount: number;
+	failedCount: number;
+	items: BlocklistImportItem[];
+}
+
+function stripInlineCode(value: string) {
+	const match = value.match(/`([^`]+)`/);
+	return match?.[1] ?? value;
+}
+
+function extractQueryFromLine(value: string) {
+	const trimmed = value.trim();
+	if (!trimmed || trimmed.startsWith("#")) {
+		return null;
+	}
+
+	if (
+		!trimmed.startsWith("@") &&
+		!trimmed.startsWith("-") &&
+		!trimmed.startsWith("*") &&
+		!trimmed.startsWith("+") &&
+		!trimmed.startsWith("`") &&
+		!trimmed.startsWith("http") &&
+		trimmed.split(/\s+/).length > 1
+	) {
+		return null;
+	}
+
+	const withoutBullet = trimmed.replace(/^(?:[-*+]|\d+\.)\s+/, "");
+	const withoutCode = stripInlineCode(withoutBullet).trim();
+	if (!withoutCode) {
+		return null;
+	}
+
+	if (/^(?:https?:\/\/)/i.test(withoutCode)) {
+		return withoutCode.split(/\s+/)[0] ?? null;
+	}
+
+	return (
+		withoutCode
+			.split(/[,\s:;]+/)[0]
+			?.replace(/^["'`]+|["'`,.]+$/g, "")
+			.trim() ?? null
+	);
+}
+
+export function parseBlocklistText(text: string) {
+	const items: string[] = [];
+	const seen = new Set<string>();
+
+	for (const line of text.split(/\r?\n/)) {
+		const query = extractQueryFromLine(line);
+		if (!query || seen.has(query)) {
+			continue;
+		}
+		seen.add(query);
+		items.push(query);
+	}
+
+	return items;
+}
+
+export async function importBlocklist(accountId: string, filePath: string) {
+	const text = await readFile(filePath, "utf8");
+	const queries = parseBlocklistText(text);
+	const items: BlocklistImportItem[] = [];
+
+	for (const query of queries) {
+		try {
+			const result = await addBlock(accountId, query);
+			if (!result.ok) {
+				items.push({
+					query,
+					ok: false,
+					error: result.transport.output || "block failed",
+				});
+				continue;
+			}
+			items.push({
+				query,
+				ok: true,
+				blockedAt: result.blockedAt,
+				handle: result.profile.handle,
+			});
+		} catch (error) {
+			items.push({
+				query,
+				ok: false,
+				error: error instanceof Error ? error.message : "block failed",
+			});
+		}
+	}
+
+	return {
+		ok: items.every((item) => item.ok),
+		accountId,
+		path: filePath,
+		requestedCount: queries.length,
+		blockedCount: items.filter((item) => item.ok).length,
+		failedCount: items.filter((item) => !item.ok).length,
+		items,
+	} satisfies BlocklistImportResult;
+}