> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xneon.org/llms.txt
> Use this file to discover all available pages before exploring further.

# @xnlc/mods: клиент Modrinth, CurseForge и FTB для Minecraft

> Библиотека для поиска, загрузки и управления модами из Modrinth, CurseForge и FTB. Унифицированный API для трех источников контента.

`@xnlc/mods` это клиент для трех крупнейших репозиториев Minecraft-контента: Modrinth, CurseForge и FTB (Feed The Beast). Предоставляет унифицированный API для поиска, получения деталей проектов, версий и зависимостей.

**Версия:** 1.0.3 | **Лицензия:** GPL-3.0 | **Реестр:** [git.xneon.org](https://git.xneon.org/api/packages/MAINER4IK/npm/)

## Установка

<CodeGroup>
  ```bash npm theme={null}
  npm install @xnlc/mods
  ```

  ```bash pnpm theme={null}
  pnpm add @xnlc/mods
  ```
</CodeGroup>

## Возможности

* Поиск модов, ресурспаков, шейдеров и модпаков в Modrinth, CurseForge и FTB
* Унифицированные типы результатов поиска (`ModSearchResult`) независимо от источника
* Пагинация, сортировка и фильтрация по загрузчикам, версиям Minecraft и категориям
* Получение полного списка версий проекта (даже при длинной истории)
* Пакетная загрузка информации о файлах по SHA1-хешам
* Проверка обновлений установленных модов
* Разрешение зависимостей модов
* Чтение зависимостей напрямую из JAR-файлов

## Modrinth API

### Поиск

```ts theme={null}
import { modrinthSearch } from "@xnlc/mods";

const response = await modrinthSearch("jei", {
  contentType: "mod",        // "mod" | "modpack" | "resourcepack" | "shader" | "datapack"
  gameVersion: "1.20.4",
  modLoader: "neoforge",     // "vanilla" | "forge" | "fabric" | "quilt" | "neoforge"
  sortBy: "downloads",       // "relevance" | "downloads" | "follows" | "newest" | "updated" | "featured" | "rating"
  page: 0,
  categories: ["utility"],
});

console.log(response.results);   // ModSearchResult[]
console.log(response.totalCount);
```

### Детали проекта

```ts theme={null}
import { modrinthGetDetails, modrinthGetVersions } from "@xnlc/mods";

const details = await modrinthGetDetails("jei");
// details.versions: полный список версий (пагинация по страницам внутри)

const versions = await modrinthGetVersions("jei");
```

### Проверка обновлений

```ts theme={null}
import { modrinthCheckUpdates } from "@xnlc/mods";

const updates = await modrinthCheckUpdates(
  ["sha1hash1", "sha1hash2"],
  ["neoforge"],
  ["1.20.4"]
);
// Record<sha1, ModVersion>
```

## CurseForge API

### Поиск

```ts theme={null}
import { curseforgeSearch } from "@xnlc/mods";

const response = await curseforgeSearch("jei", {
  contentType: "mod",
  gameVersion: "1.20.4",
  modLoader: "neoforge",
  sortBy: "downloads",
  page: 0,
});
```

### Детали и загрузка

```ts theme={null}
import { curseforgeGetDetails, curseforgeGetFileDownloadUrl } from "@xnlc/mods";

const details = await curseforgeGetDetails(238222); // numeric modId
const url = await curseforgeGetFileDownloadUrl(1234567, 238222); // fileId, modId
```

### Пакетная загрузка информации о файлах

```ts theme={null}
import { curseforgeGetFiles } from "@xnlc/mods";

const files = await curseforgeGetFiles([1234567, 1234568]);
// Record<fileId, { id, modId, fileName, downloadUrl, fileLength }>
```

### Поиск по отпечаткам

```ts theme={null}
import { curseforgeGetFingerprintsMatches } from "@xnlc/mods";

const matches = await curseforgeGetFingerprintsMatches([12345678, 87654321]);
// { exactMatches: [{ fileFingerprint, modId, fileId, sha1 }] }
```

## FTB API

### Каталог и поиск

```ts theme={null}
import { ftbSearch, ftbCatalog, ftbCatalogFacets } from "@xnlc/mods";

// Весь каталог FTB (с дисковым кэшем)
const catalog = await ftbCatalog();

// Поиск с фильтрами
const results = await ftbSearch("all", {
  page: 0,
  sortBy: "downloads",
  categories: ["Tech"],
  gameVersion: "1.21.1",
  loader: "neoforge",
});

// Фильтры каталога
const facets = await ftbCatalogFacets();
// { gameVersions: string[], categories: string[], loaders: string[] }
```

### Детали модпака

```ts theme={null}
import { ftbGetDetails, ftbGetModpackChangelog } from "@xnlc/mods";

const details = await ftbGetDetails(100); // FTB modpack ID
const changelog = await ftbGetModpackChangelog(100, 1234); // id, versionId
```

## Общие типы

Унифицированные типы для всех трех источников:

```ts theme={null}
import type {
  ModSearchResult,   // Результат поиска (источник-агностик)
  ModDetails,        // Полная информация о проекте
  ModVersion,        // Конкретная версия с файлами
  ModDependency,     // Зависимость проекта
  ModCategory,       // Категория/тег
  ContentType,       // "mod" | "modpack" | "resourcepack" | "shader" | "datapack" | "plugin" | "world"
  ModSort,           // Варианты сортировки
  ModSource,         // "modrinth" | "curseforge" | "ftb"
} from "@xnlc/mods";
```

### ContentType и ID классов CurseForge

| ContentType | CurseForge classId | Modrinth facet |
| - | - | - |
| mod | 6 | mod |
| modpack | 4471 | modpack |
| resourcepack | 12 | resourcepack |
| shader | 6552 | shader |
| datapack | 6945 | datapack |
| plugin | 5 | plugin |
| world | 17 | world |

<Note>
  Все функции автоматически обрабатывают пагинацию для проектов с большим количеством версий. Например, у проекта Jade (333+ версии на Modrinth) все версии будут загружены полностью.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.