@serverkgg/bridge 0.0.12 → 0.0.13

package/src/catalogs/curseforge.ts

@@ -0,0 +1,461 @@
+import type { BridgeContext } from "../context";
+import { BridgeFailureCode, BridgeFailureError, BridgeNetError, BridgeSecretError } from "../core";
+import { BridgeHttpMethod } from "../protocol";
+
+export const CURSEFORGE_API = "https://api.curseforge.com/v1";
+
+export const CURSEFORGE_DOWNLOAD = "https://edge.forgecdn.net";
+
+export const CURSEFORGE_CDN_SUFFIX = ".forgecdn.net";
+
+export const CURSEFORGE_SECRET = "CURSEFORGE_API_KEY";
+
+export const CURSEFORGE_SEARCH_CEILING = 10_000;
+
+export const CURSEFORGE_SERVER_TAG = "server";
+
+export const CURSEFORGE_CLIENT_TAG = "client";
+
+const SEARCH_CACHE_SECONDS = 60;
+
+const PROJECT_CACHE_SECONDS = 600;
+
+const CATEGORY_CACHE_SECONDS = 86_400;
+
+const BATCH = 100;
+
+const SPLIT_ID_LENGTH = 7;
+
+const SPLIT_ID_FOLDER = 4;
+
+const LEGACY_ID_DIVISOR = 1000;
+
+const REJECTED_STATUSES = [
+	401,
+	403,
+];
+
+const THROTTLED_STATUSES = [
+	429,
+	503,
+];
+
+export enum CurseforgeHash {
+	Md5 = 2,
+	Sha1 = 1,
+}
+
+export enum CurseforgeReleaseType {
+	Alpha = 3,
+	Beta = 2,
+	Release = 1,
+}
+
+export enum CurseforgeDependency {
+	EmbeddedLibrary = 1,
+	Include = 6,
+	Incompatible = 5,
+	Optional = 2,
+	Required = 3,
+	Tool = 4,
+}
+
+export enum CurseforgeSort {
+	Author = "5",
+	Featured = "1",
+	LastUpdated = "3",
+	Name = "4",
+	Popularity = "2",
+	TotalDownloads = "6",
+}
+
+export enum CurseforgeSortOrder {
+	Asc = "asc",
+	Desc = "desc",
+}
+
+export interface CurseforgeAuthor {
+	name: string;
+}
+
+export interface CurseforgeCategory {
+	id: number;
+	name: string;
+	classId?: number | null;
+	isClass?: boolean | null;
+}
+
+export interface CurseforgeMod {
+	id: number;
+	classId: number | null;
+	name: string;
+	slug: string;
+	summary: string;
+	downloadCount: number;
+	authors: CurseforgeAuthor[];
+	categories: CurseforgeCategory[];
+	dateModified: string | null;
+	allowModDistribution: boolean | null;
+	logo: {
+		thumbnailUrl: string | null;
+	} | null;
+	links: {
+		websiteUrl: string | null;
+	} | null;
+}
+
+export interface CurseforgeHashEntry {
+	value: string;
+	algo: number;
+}
+
+export interface CurseforgeDependencyEntry {
+	modId: number;
+	relationType: number;
+}
+
+export interface CurseforgeFile {
+	id: number;
+	modId: number;
+	fileName: string;
+	displayName: string;
+	downloadUrl: string | null;
+	fileLength: number;
+	fileDate: string | null;
+	isAvailable: boolean;
+	isServerPack?: boolean;
+	serverPackFileId?: number | null;
+	parentProjectFileId?: number | null;
+	releaseType: number;
+	gameVersions: string[];
+	hashes: CurseforgeHashEntry[];
+	dependencies: CurseforgeDependencyEntry[];
+}
+
+export interface CurseforgePagination {
+	index: number;
+	pageSize: number;
+	resultCount: number;
+	totalCount: number;
+}
+
+export interface CurseforgeSearchPage {
+	data: CurseforgeMod[];
+	pagination: CurseforgePagination;
+}
+
+export interface CurseforgeFilesPage {
+	data: CurseforgeFile[];
+	pagination: CurseforgePagination;
+}
+
+export interface CurseforgeSearchQuery {
+	query?: string;
+	classId?: number;
+	categoryId?: number;
+	gameVersion?: string;
+	modLoaderType?: number;
+	sort?: CurseforgeSort;
+	sortOrder?: CurseforgeSortOrder;
+	index?: number;
+	pageSize?: number;
+}
+
+export interface CurseforgeModFilesQuery {
+	gameVersion?: string;
+	modLoaderType?: number;
+	index?: number;
+	pageSize?: number;
+}
+
+export interface CurseforgeCatalogOptions {
+	gameId: number;
+	searchCacheSeconds?: number;
+	projectCacheSeconds?: number;
+	categoryCacheSeconds?: number;
+}
+
+export interface CurseforgeCatalog {
+	ready(): boolean;
+	search(query?: CurseforgeSearchQuery): Promise<CurseforgeSearchPage>;
+	mod(modId: string | number): Promise<CurseforgeMod>;
+	mods(modIds: number[]): Promise<CurseforgeMod[]>;
+	modFiles(modId: string | number, query?: CurseforgeModFilesQuery): Promise<CurseforgeFilesPage>;
+	file(modId: string | number, fileId: string | number): Promise<CurseforgeFile>;
+	files(fileIds: number[]): Promise<CurseforgeFile[]>;
+	categories(classId?: number): Promise<CurseforgeCategory[]>;
+}
+
+export const curseforgeSha1 = (file: CurseforgeFile) => {
+	return file.hashes.find((hash) => hash.algo === CurseforgeHash.Sha1)?.value.toLowerCase() ?? null;
+};
+
+const pathSegment = (segment: string) => {
+	return encodeURIComponent(decodeURIComponent(segment));
+};
+
+export const curseforgeDownloadUrl = (file: CurseforgeFile): string | null => {
+	if (!file.downloadUrl || !URL.canParse(file.downloadUrl)) {
+		return null;
+	}
+
+	const remote = new URL(file.downloadUrl);
+
+	if (remote.protocol !== "https:" || !remote.hostname.endsWith(CURSEFORGE_CDN_SUFFIX)) {
+		return null;
+	}
+
+	try {
+		return `${remote.origin}${remote.pathname.split("/").map(pathSegment).join("/")}`;
+	} catch {
+		return null;
+	}
+};
+
+export const curseforgeFallbackUrl = (fileId: number, fileName: string) => {
+	const id = String(fileId);
+	const folder =
+		id.length >= SPLIT_ID_LENGTH ? id.slice(0, SPLIT_ID_FOLDER) : String(Math.floor(fileId / LEGACY_ID_DIVISOR));
+	const remainder = id.length >= SPLIT_ID_LENGTH ? id.slice(SPLIT_ID_FOLDER) : id;
+
+	return `${CURSEFORGE_DOWNLOAD}/files/${folder}/${remainder}/${encodeURIComponent(fileName)}`;
+};
+
+export const isCurseforgeServerFile = (file: CurseforgeFile) => {
+	let client = false;
+
+	for (const tag of file.gameVersions) {
+		const lowered = tag.toLowerCase();
+
+		if (lowered === CURSEFORGE_SERVER_TAG) {
+			return true;
+		}
+
+		if (lowered === CURSEFORGE_CLIENT_TAG) {
+			client = true;
+		}
+	}
+
+	return !client;
+};
+
+export interface CurseforgeSelect {
+	gameVersion?: string | null;
+	stableOnly?: boolean;
+	serverOnly?: boolean;
+}
+
+export const selectCurseforgeFile = (files: CurseforgeFile[], select: CurseforgeSelect = {}): CurseforgeFile | null => {
+	let usable = files.filter((file) => file.isAvailable);
+
+	if (select.serverOnly === true) {
+		usable = usable.filter(isCurseforgeServerFile);
+	}
+
+	if (select.stableOnly === true) {
+		const stable = usable.filter((file) => file.releaseType === CurseforgeReleaseType.Release);
+
+		usable = stable.length > 0 ? stable : usable;
+	}
+
+	const newest = [
+		...usable,
+	].sort((left, right) => right.id - left.id);
+
+	if (newest.length === 0) {
+		return null;
+	}
+
+	if (!select.gameVersion) {
+		return newest.at(0) ?? null;
+	}
+
+	return newest.find((file) => file.gameVersions.includes(select.gameVersion ?? "")) ?? newest.at(0) ?? null;
+};
+
+const appendOptional = (search: URLSearchParams, optional: Record<string, string | number | undefined>) => {
+	for (const [key, value] of Object.entries(optional)) {
+		if (value !== undefined && String(value).length > 0) {
+			search.set(key, String(value));
+		}
+	}
+};
+
+const ALPHABETICAL_SORTS = [
+	CurseforgeSort.Name,
+	CurseforgeSort.Author,
+];
+
+const defaultSortOrder = (sort: CurseforgeSort) => {
+	return ALPHABETICAL_SORTS.includes(sort) ? CurseforgeSortOrder.Asc : CurseforgeSortOrder.Desc;
+};
+
+const searchQuery = (gameId: number, query: CurseforgeSearchQuery) => {
+	const search = new URLSearchParams({
+		gameId: String(gameId),
+	});
+
+	appendOptional(search, {
+		searchFilter: query.query,
+		classId: query.classId,
+		categoryId: query.categoryId,
+		gameVersion: query.gameVersion,
+		modLoaderType: query.modLoaderType,
+		sortField: query.sort,
+		index: query.index,
+		pageSize: query.pageSize,
+	});
+
+	if (query.sort !== undefined) {
+		search.set("sortOrder", query.sortOrder ?? defaultSortOrder(query.sort));
+	}
+
+	return search.toString();
+};
+
+const modFilesQuery = (query: CurseforgeModFilesQuery) => {
+	const search = new URLSearchParams();
+
+	appendOptional(search, {
+		gameVersion: query.gameVersion,
+		modLoaderType: query.modLoaderType,
+		index: query.index,
+		pageSize: query.pageSize,
+	});
+
+	return search.toString();
+};
+
+export const createCurseforgeCatalog = (
+	context: BridgeContext,
+	options: CurseforgeCatalogOptions,
+): CurseforgeCatalog => {
+	const projectCacheSeconds = options.projectCacheSeconds ?? PROJECT_CACHE_SECONDS;
+	const searchCacheSeconds = options.searchCacheSeconds ?? SEARCH_CACHE_SECONDS;
+	const categoryCacheSeconds = options.categoryCacheSeconds ?? CATEGORY_CACHE_SECONDS;
+
+	const request = async <Result>(url: string, cacheSeconds: number, body?: unknown): Promise<Result> => {
+		const key = context.secret(CURSEFORGE_SECRET);
+
+		if (!key) {
+			throw new BridgeSecretError(CURSEFORGE_SECRET, "curseforge needs an api key before it can be searched");
+		}
+
+		try {
+			return await context.net.json<Result>(url, {
+				headers: {
+					"x-api-key": key,
+				},
+				cacheSeconds,
+				...(body === undefined
+					? {}
+					: {
+							body: JSON.stringify(body),
+							httpMethod: BridgeHttpMethod.Post,
+						}),
+			});
+		} catch (error) {
+			if (!(error instanceof BridgeNetError) || error.status === null) {
+				throw error;
+			}
+
+			if (REJECTED_STATUSES.includes(error.status)) {
+				throw new BridgeSecretError(CURSEFORGE_SECRET, `curseforge rejected the configured key — ${error.message}`);
+			}
+
+			if (THROTTLED_STATUSES.includes(error.status)) {
+				throw new BridgeFailureError(
+					BridgeFailureCode.CatalogRateLimited,
+					"curseforge asked us to slow down, wait a moment and try again",
+				);
+			}
+
+			throw error;
+		}
+	};
+
+	const batched = async <Entry>(url: string, field: string, ids: number[]): Promise<Entry[]> => {
+		const wanted = [
+			...new Set(ids),
+		].sort((left, right) => left - right);
+		const entries: Entry[] = [];
+
+		for (let cursor = 0; cursor < wanted.length; cursor += BATCH) {
+			const page = await request<{
+				data: Entry[];
+			}>(url, projectCacheSeconds, {
+				[field]: wanted.slice(cursor, cursor + BATCH),
+			});
+
+			entries.push(...page.data);
+		}
+
+		return entries;
+	};
+
+	return {
+		ready() {
+			return context.secret(CURSEFORGE_SECRET) !== null;
+		},
+
+		async search(query = {}) {
+			return await request<CurseforgeSearchPage>(
+				`${CURSEFORGE_API}/mods/search?${searchQuery(options.gameId, query)}`,
+				searchCacheSeconds,
+			);
+		},
+
+		async mod(modId) {
+			const single = await request<{
+				data: CurseforgeMod;
+			}>(`${CURSEFORGE_API}/mods/${encodeURIComponent(String(modId))}`, projectCacheSeconds);
+
+			return single.data;
+		},
+
+		async mods(modIds) {
+			return await batched<CurseforgeMod>(`${CURSEFORGE_API}/mods`, "modIds", modIds);
+		},
+
+		async modFiles(modId, query = {}) {
+			const search = modFilesQuery(query);
+			const suffix = search.length > 0 ? `?${search}` : "";
+
+			return await request<CurseforgeFilesPage>(
+				`${CURSEFORGE_API}/mods/${encodeURIComponent(String(modId))}/files${suffix}`,
+				projectCacheSeconds,
+			);
+		},
+
+		async file(modId, fileId) {
+			const single = await request<{
+				data: CurseforgeFile;
+			}>(
+				`${CURSEFORGE_API}/mods/${encodeURIComponent(String(modId))}/files/${encodeURIComponent(String(fileId))}`,
+				projectCacheSeconds,
+			);
+
+			return single.data;
+		},
+
+		async files(fileIds) {
+			return await batched<CurseforgeFile>(`${CURSEFORGE_API}/mods/files`, "fileIds", fileIds);
+		},
+
+		async categories(classId) {
+			const search = new URLSearchParams({
+				gameId: String(options.gameId),
+			});
+
+			if (classId !== undefined) {
+				search.set("classId", String(classId));
+			}
+
+			const page = await request<{
+				data: CurseforgeCategory[];
+			}>(`${CURSEFORGE_API}/categories?${search.toString()}`, categoryCacheSeconds);
+
+			return page.data;
+		},
+	};
+};

package/src/catalogs/index.ts

@@ -0,0 +1,2 @@
+export * from "./curseforge";
+export * from "./thunderstore";

package/src/catalogs/thunderstore.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { parseThunderstoreManifest, thunderstoreDependency, thunderstoreDownloadUrl } from "./thunderstore";
+
+describe("thunderstoreDownloadUrl", () => {
+	test("points straight at the cdn so no redirect has to be followed", () => {
+		expect(thunderstoreDownloadUrl("denikson-BepInExPack_Valheim-5.4.2202")).toBe(
+			"https://gcdn.thunderstore.io/live/repository/packages/denikson-BepInExPack_Valheim-5.4.2202.zip",
+		);
+	});
+
+	test("escapes a package name", () => {
+		expect(thunderstoreDownloadUrl("a b-c-1.0.0")).toContain("a%20b-c-1.0.0.zip");
+	});
+});
+
+describe("parseThunderstoreManifest", () => {
+	test("reads name, version and dependencies", () => {
+		expect(
+			parseThunderstoreManifest(
+				JSON.stringify({
+					name: "MyMod",
+					version_number: "1.2.3",
+					description: "does things",
+					dependencies: [
+						"denikson-BepInExPack_Valheim-5.4.2202",
+					],
+				}),
+			),
+		).toEqual({
+			name: "MyMod",
+			version_number: "1.2.3",
+			description: "does things",
+			dependencies: [
+				"denikson-BepInExPack_Valheim-5.4.2202",
+			],
+		});
+	});
+
+	test("defaults missing dependencies to an empty list", () => {
+		expect(
+			parseThunderstoreManifest(
+				JSON.stringify({
+					name: "MyMod",
+					version_number: "1.0.0",
+				}),
+			)?.dependencies,
+		).toEqual([]);
+	});
+
+	test("drops entries that are not strings", () => {
+		expect(
+			parseThunderstoreManifest(
+				JSON.stringify({
+					name: "MyMod",
+					version_number: "1.0.0",
+					dependencies: [
+						"a-b-1.0.0",
+						7,
+					],
+				}),
+			)?.dependencies,
+		).toEqual([
+			"a-b-1.0.0",
+		]);
+	});
+
+	test("returns null for anything that is not a manifest", () => {
+		expect(parseThunderstoreManifest("")).toBeNull();
+		expect(parseThunderstoreManifest("[]")).toBeNull();
+		expect(
+			parseThunderstoreManifest(
+				JSON.stringify({
+					name: "MyMod",
+				}),
+			),
+		).toBeNull();
+	});
+});
+
+describe("thunderstoreDependency", () => {
+	test("splits a dependency reference into its three parts", () => {
+		expect(thunderstoreDependency("denikson-BepInExPack_Valheim-5.4.2202")).toEqual({
+			namespace: "denikson",
+			name: "BepInExPack_Valheim",
+			version: "5.4.2202",
+			fullName: "denikson-BepInExPack_Valheim-5.4.2202",
+		});
+	});
+
+	test("returns null for a reference it cannot split", () => {
+		expect(thunderstoreDependency("denikson-BepInExPack")).toBeNull();
+		expect(thunderstoreDependency("a-b-c-d")).toBeNull();
+	});
+});