birdclaw 0.8.2 → 0.8.3

package/src/components/links-model.ts

@@ -0,0 +1,198 @@
+import { queryKeys } from "#/lib/query-client";
+import type {
+	LinkInsightItem,
+	LinkInsightKind,
+	LinkInsightMention,
+	LinkInsightRange,
+	LinkInsightResponse,
+	LinkInsightSort,
+	LinkInsightSource,
+	ProfileRecord,
+	TweetMediaItem,
+} from "#/lib/types";
+
+export const INITIAL_VISIBLE_COMMENTS = 3;
+export const MORE_COMMENTS_BATCH = 6;
+export const LINK_INSIGHTS_LIMIT = 30;
+export const LINK_INSIGHTS_COMMENTS_LIMIT = 30;
+export const PROFILE_HYDRATION_LIMIT = 30;
+export const PROFILE_HYDRATION_DELAY_MS = 1200;
+export const LINK_INSIGHTS_CACHE_MAX_AGE_MS = 5 * 60_000;
+export const hydratingLinkProfileHandles = new Set<string>();
+
+export const ranges: Array<{ value: LinkInsightRange; label: string }> = [
+	{ value: "today", label: "Today" },
+	{ value: "week", label: "Week" },
+	{ value: "month", label: "Month" },
+	{ value: "year", label: "Year" },
+	{ value: "all", label: "All" },
+];
+
+export function itemTitle(item: LinkInsightItem) {
+	return item.title?.trim() || item.displayUrl;
+}
+
+export function itemSubtitle(item: LinkInsightItem) {
+	const description = item.description?.trim();
+	if (description) {
+		return description;
+	}
+	return item.displayUrl.split("?")[0] || item.displayUrl;
+}
+
+export function linkInsightQueryKey(
+	kind: LinkInsightKind,
+	range: LinkInsightRange,
+	sort: LinkInsightSort,
+	source: LinkInsightSource,
+) {
+	return [...queryKeys.linkInsights, { kind, range, sort, source }] as const;
+}
+
+export function linkInsightsUrl(
+	kind: LinkInsightKind,
+	range: LinkInsightRange,
+	sort: LinkInsightSort,
+	source: LinkInsightSource,
+) {
+	const url = new URL("/api/link-insights", window.location.origin);
+	url.searchParams.set("kind", kind);
+	url.searchParams.set("range", range);
+	url.searchParams.set("sort", sort);
+	url.searchParams.set("source", source);
+	url.searchParams.set("limit", String(LINK_INSIGHTS_LIMIT));
+	url.searchParams.set("commentsLimit", String(LINK_INSIGHTS_COMMENTS_LIMIT));
+	return url;
+}
+
+export async function fetchLinkInsights(
+	kind: LinkInsightKind,
+	range: LinkInsightRange,
+	sort: LinkInsightSort,
+	source: LinkInsightSource,
+	signal?: AbortSignal,
+) {
+	const response = await fetch(linkInsightsUrl(kind, range, sort, source), {
+		signal,
+	});
+	const data = (await response.json()) as LinkInsightResponse;
+	if (!response.ok) {
+		throw new Error("Link insights unavailable");
+	}
+	return data;
+}
+
+export function mentionHref(
+	mention: LinkInsightMention,
+	item: LinkInsightItem,
+) {
+	return mention.sourceUrl || mention.contentTweetUrl || item.url;
+}
+
+export function mentionCopy(mention: LinkInsightMention) {
+	return (
+		mention.commentText ||
+		mention.sharedContentText ||
+		mention.rawText ||
+		"Shared without comment"
+	);
+}
+
+export function isSameProfile(
+	left: ProfileRecord | null | undefined,
+	right: ProfileRecord | null | undefined,
+) {
+	return Boolean(left && right && left.id === right.id);
+}
+
+export function mediaImage(media: TweetMediaItem[]) {
+	return media.find((item) => item.thumbnailUrl || item.url) ?? null;
+}
+
+export function youtubeVideoId(rawUrl: string) {
+	try {
+		const url = new URL(rawUrl);
+		const host = url.hostname.toLowerCase().replace(/^www\./, "");
+		if (host === "youtu.be") {
+			return url.pathname.split("/").filter(Boolean)[0] ?? null;
+		}
+		if (!host.endsWith("youtube.com")) {
+			return null;
+		}
+		if (url.pathname === "/watch") {
+			return url.searchParams.get("v");
+		}
+		const parts = url.pathname.split("/").filter(Boolean);
+		if (parts[0] === "embed" || parts[0] === "shorts" || parts[0] === "live") {
+			return parts[1] ?? null;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+export function youtubeThumbnailUrl(rawUrl: string) {
+	const id = youtubeVideoId(rawUrl);
+	if (!id || !/^[\w-]{6,}$/.test(id)) {
+		return null;
+	}
+	return `https://i.ytimg.com/vi/${encodeURIComponent(id)}/hqdefault.jpg`;
+}
+
+export function commentCount(item: LinkInsightItem) {
+	return (
+		item.commentCount ??
+		item.mentions.filter((mention) => mention.hasComment).length
+	);
+}
+
+export function pureShareCount(item: LinkInsightItem) {
+	return (
+		item.pureShareCount ??
+		item.mentions.filter(
+			(mention) => mention.isPureShare || !mention.hasComment,
+		).length
+	);
+}
+
+export function isArchivePlaceholderProfile(profile: ProfileRecord) {
+	return (
+		/^id\d+$/i.test(profile.handle) &&
+		profile.displayName === profile.handle &&
+		profile.id === `profile_user_${profile.handle.slice(2)}`
+	);
+}
+
+export function profileNeedsHydration(
+	profile: ProfileRecord | null | undefined,
+) {
+	if (!profile?.handle || isArchivePlaceholderProfile(profile)) {
+		return false;
+	}
+	return !profile.avatarUrl || profile.followersCount === 0;
+}
+
+export function collectProfilesForHydration(data: LinkInsightResponse | null) {
+	const handles = new Set<string>();
+	for (const item of data?.items ?? []) {
+		for (const profile of [
+			item.topSharer,
+			...item.sharers,
+			...item.mentions.flatMap((mention) => [
+				mention.sharedBy,
+				mention.contentAuthor,
+				mention.participant,
+			]),
+		]) {
+			if (!profile || !profileNeedsHydration(profile)) {
+				continue;
+			}
+			handles.add(profile.handle.replace(/^@/, ""));
+			if (handles.size >= PROFILE_HYDRATION_LIMIT) {
+				return [...handles];
+			}
+		}
+	}
+	return [...handles];
+}

package/src/components/network-map-controller.ts

@@ -0,0 +1,84 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useMemo, useState } from "react";
+import { useSelectedAccountId } from "./account-selection";
+import {
+	MAP_TYPES,
+	WORLD_VIEWPORT,
+	boundsContainFeature,
+	featureMatchesSearch,
+	fetchMap,
+	type MapViewport,
+} from "./network-map-model";
+import { fetchQueryEnvelope } from "#/lib/api-client";
+import type { NetworkMapKind } from "#/lib/network-map";
+import { queryKeys } from "#/lib/query-client";
+
+export function useNetworkMapController() {
+	const queryClient = useQueryClient();
+	const [type, setType] = useState<NetworkMapKind>("all");
+	const [viewport, setViewport] = useState<MapViewport>(WORLD_VIEWPORT);
+	const [visibleSearch, setVisibleSearch] = useState("");
+	const statusQuery = useQuery({
+		queryKey: queryKeys.status,
+		queryFn: ({ signal }) => fetchQueryEnvelope({ signal }),
+	});
+	const selectedAccountId = useSelectedAccountId(statusQuery.data?.accounts);
+	const mapQueryKey = [
+		...queryKeys.networkMap,
+		{ type, selectedAccountId: selectedAccountId ?? null },
+	] as const;
+	const mapQuery = useQuery({
+		queryKey: mapQueryKey,
+		queryFn: ({ signal }) => fetchMap(type, false, selectedAccountId, signal),
+		staleTime: 5 * 60_000,
+	});
+	const refreshMutation = useMutation({
+		mutationFn: () => fetchMap(type, true, selectedAccountId),
+		onSuccess: (nextData) => {
+			queryClient.setQueryData(mapQueryKey, nextData);
+		},
+	});
+	const data = mapQuery.data ?? null;
+	const loading = mapQuery.isPending || refreshMutation.isPending;
+	const queryError = refreshMutation.error ?? mapQuery.error;
+
+	const visibleFeatures = useMemo(
+		() =>
+			(data?.features ?? [])
+				.slice()
+				.filter((feature) => boundsContainFeature(viewport.bounds, feature))
+				.sort(
+					(a, b) =>
+						b.properties.followersCount - a.properties.followersCount ||
+						a.properties.handle.localeCompare(b.properties.handle),
+				),
+		[data, viewport],
+	);
+	const filteredVisibleFeatures = useMemo(
+		() =>
+			visibleFeatures
+				.filter((feature) => featureMatchesSearch(feature, visibleSearch))
+				.slice(0, 160),
+		[visibleFeatures, visibleSearch],
+	);
+
+	return {
+		type,
+		setType,
+		viewport,
+		setViewport,
+		visibleSearch,
+		setVisibleSearch,
+		data,
+		loading,
+		error: queryError
+			? queryError instanceof Error
+				? queryError.message
+				: "Map unavailable"
+			: null,
+		refresh: refreshMutation.mutate,
+		visibleFeatures,
+		filteredVisibleFeatures,
+		mapTypes: MAP_TYPES,
+	};
+}

package/src/components/network-map-model.ts

@@ -0,0 +1,255 @@
+import type * as GeoJSON from "geojson";
+import Supercluster from "supercluster";
+import type { NetworkMapKind, NetworkMapResponse } from "#/lib/network-map";
+
+export type ReactMapboxModule = typeof import("react-map-gl/mapbox");
+export type MapFeature = NetworkMapResponse["features"][number];
+export type MapBounds = [number, number, number, number];
+
+export interface ClusterPointProperties {
+	featureIndex: number;
+	handle: string;
+	name: string;
+	avatarUrl: string | null;
+	relationship: MapFeature["properties"]["relationship"];
+	followersCount: number;
+}
+
+export interface ClusterAggregateProperties {
+	followers: number;
+	following: number;
+	mutual: number;
+}
+
+export interface ClusterFeatureProperties extends ClusterAggregateProperties {
+	cluster: true;
+	cluster_id: number;
+	point_count: number;
+	point_count_abbreviated: string | number;
+}
+
+export type ClusterPointFeature = GeoJSON.Feature<
+	GeoJSON.Point,
+	ClusterPointProperties
+>;
+export type ClusterFeature = GeoJSON.Feature<
+	GeoJSON.Point,
+	ClusterFeatureProperties
+>;
+export type ClusterResult = ClusterPointFeature | ClusterFeature;
+export type MapViewport = { bounds: MapBounds; zoom: number };
+export type MapTarget = {
+	getBounds: () => {
+		getWest: () => number;
+		getSouth: () => number;
+		getEast: () => number;
+		getNorth: () => number;
+	};
+	getZoom: () => number;
+};
+
+export type SelectedOverlay =
+	| { kind: "profile"; feature: MapFeature }
+	| {
+			kind: "cluster";
+			coordinates: [number, number];
+			count: number;
+			features: MapFeature[];
+			stats: ClusterAggregateProperties;
+	  };
+
+export const CLUSTER_LEAF_SAMPLE_SIZE = 48;
+
+export const MAP_TYPES: Array<{ value: NetworkMapKind; label: string }> = [
+	{ value: "all", label: "All" },
+	{ value: "followers", label: "Followers" },
+	{ value: "following", label: "Following" },
+	{ value: "mutual", label: "Mutual" },
+];
+
+export const WORLD_BOUNDS: MapBounds = [-180, -85, 180, 85];
+export const WORLD_VIEWPORT: MapViewport = { bounds: WORLD_BOUNDS, zoom: 1.15 };
+
+export async function fetchMap(
+	type: NetworkMapKind,
+	refresh: boolean,
+	accountId?: string,
+	signal?: AbortSignal,
+) {
+	const url = new URL("/api/network-map", window.location.origin);
+	url.searchParams.set("type", type);
+	url.searchParams.set("limit", "50000");
+	url.searchParams.set("geocodeLimit", refresh ? "80" : "12");
+	if (accountId) url.searchParams.set("account", accountId);
+	if (refresh) url.searchParams.set("refresh", "true");
+	const response = await fetch(url, { signal });
+	if (!response.ok) {
+		throw new Error(`Map request failed (${String(response.status)})`);
+	}
+	return (await response.json()) as NetworkMapResponse;
+}
+
+export function formatNumber(value: number) {
+	return new Intl.NumberFormat().format(value);
+}
+
+export function formatRelationship(
+	value: MapFeature["properties"]["relationship"],
+) {
+	if (value === "mutual") return "mutual";
+	if (value === "following") return "following";
+	return "follower";
+}
+
+export function relationshipColor(
+	relationship: MapFeature["properties"]["relationship"],
+) {
+	if (relationship === "mutual") return "#22c55e";
+	if (relationship === "following") return "#f59e0b";
+	return "#1d9bf0";
+}
+
+export function avatarInitial(feature: MapFeature) {
+	return (feature.properties.name || feature.properties.handle || "?")
+		.slice(0, 1)
+		.toUpperCase();
+}
+
+export function avatarPath(feature: MapFeature) {
+	if (!feature.properties.avatarUrl) return null;
+	const query = new URLSearchParams({
+		profileId: feature.properties.profileId,
+		v: feature.properties.avatarUrl,
+	});
+	return `/api/avatar?${query.toString()}`;
+}
+
+export function clusterGradient(stats: ClusterAggregateProperties) {
+	const total = Math.max(1, stats.followers + stats.following + stats.mutual);
+	const mutual = (stats.mutual / total) * 100;
+	const following = mutual + (stats.following / total) * 100;
+	return `conic-gradient(#22c55e 0 ${mutual}%, #f59e0b ${mutual}% ${following}%, #1d9bf0 ${following}% 100%)`;
+}
+
+export function buildClusterIndex(features: MapFeature[]) {
+	const points: ClusterPointFeature[] = features.map(
+		(feature, featureIndex) => ({
+			type: "Feature",
+			geometry: feature.geometry,
+			properties: {
+				featureIndex,
+				handle: feature.properties.handle,
+				name: feature.properties.name,
+				avatarUrl: feature.properties.avatarUrl,
+				relationship: feature.properties.relationship,
+				followersCount: feature.properties.followersCount,
+			},
+		}),
+	);
+	return new Supercluster<ClusterPointProperties, ClusterAggregateProperties>({
+		maxZoom: 18,
+		minPoints: 2,
+		radius: 64,
+		map: (props) => ({
+			followers: props.relationship === "followers" ? 1 : 0,
+			following: props.relationship === "following" ? 1 : 0,
+			mutual: props.relationship === "mutual" ? 1 : 0,
+		}),
+		reduce: (accumulated, props) => {
+			accumulated.followers += props.followers;
+			accumulated.following += props.following;
+			accumulated.mutual += props.mutual;
+		},
+	}).load(points);
+}
+
+export function isCluster(item: ClusterResult): item is ClusterFeature {
+	return "cluster" in item.properties && item.properties.cluster === true;
+}
+
+export function compareClusterFeatures(a: MapFeature, b: MapFeature) {
+	return (
+		b.properties.followersCount - a.properties.followersCount ||
+		a.properties.handle.localeCompare(b.properties.handle)
+	);
+}
+
+export function getClusterDisplayAnchor(
+	features: MapFeature[],
+	fallback: [number, number],
+): [number, number] {
+	const buckets = new Map<
+		string,
+		{ coordinates: [number, number]; count: number; followers: number }
+	>();
+	for (const feature of features) {
+		const [lng, lat] = feature.geometry.coordinates;
+		const key = `${lng.toFixed(4)},${lat.toFixed(4)}`;
+		const existing = buckets.get(key);
+		if (existing) {
+			existing.count += 1;
+			existing.followers += feature.properties.followersCount;
+		} else {
+			buckets.set(key, {
+				coordinates: [lng, lat],
+				count: 1,
+				followers: feature.properties.followersCount,
+			});
+		}
+	}
+	const best = [...buckets.values()].sort(
+		(a, b) => b.count - a.count || b.followers - a.followers,
+	)[0];
+	return best?.coordinates ?? fallback;
+}
+
+export function readViewport(target: unknown): MapViewport | null {
+	if (!target || typeof target !== "object") return null;
+	const map = target as Partial<MapTarget>;
+	if (
+		typeof map.getBounds !== "function" ||
+		typeof map.getZoom !== "function"
+	) {
+		return null;
+	}
+	const bounds = map.getBounds();
+	return {
+		bounds: [
+			bounds.getWest(),
+			bounds.getSouth(),
+			bounds.getEast(),
+			bounds.getNorth(),
+		],
+		zoom: map.getZoom(),
+	};
+}
+
+export function boundsContainFeature(bounds: MapBounds, feature: MapFeature) {
+	const [west, south, east, north] = bounds;
+	const [lng, lat] = feature.geometry.coordinates;
+	const normalizedWest = ((west + 540) % 360) - 180;
+	const normalizedEast = ((east + 540) % 360) - 180;
+	const inLatitude = lat >= Math.max(-85, south) && lat <= Math.min(85, north);
+	const inLongitude =
+		east - west >= 360
+			? true
+			: normalizedWest <= normalizedEast
+				? lng >= normalizedWest && lng <= normalizedEast
+				: lng >= normalizedWest || lng <= normalizedEast;
+	return inLatitude && inLongitude;
+}
+
+export function featureMatchesSearch(feature: MapFeature, search: string) {
+	const needle = search.trim().toLowerCase();
+	if (!needle) return true;
+	return [
+		feature.properties.name,
+		feature.properties.handle,
+		feature.properties.location,
+		feature.properties.resolvedLocation ?? "",
+		formatRelationship(feature.properties.relationship),
+	]
+		.join(" ")
+		.toLowerCase()
+		.includes(needle);
+}