Typerinth

This library is a wrapper around the Modrinth API, a platform for Minecraft mods, modpacks, and other content. It is not an official package by Modrinth and not affiliated with Modrinth in any way.

Table of Contents

• Installation
• Usage
  • Options
  • Projects
    • Search
    • Get a project by its ID or slug
    • Get multiple projects by their IDs or slugs
    • Get a random selection of projects
    • Check if a project id or slug is valid
  • Versions
    • Get the versions of a project
    • Get a version by its ID
    • Get multiple versions by their IDs
    • Get the version from a file hash
  • Users
    • Get a user by their ID or username
    • Get multiple users by their IDs or usernames
    • Get a user's projects
    • Get the authenticated user
  • Teams
    • Get a project's team members
    • Get a team's members
    • Get the members of mutliple teams
  • Tags
    • Get tags by its type
    • Get a License by its ID
  • Auth
    • Generate an authorization URL to get an authorization code
    • Get an access token from an authorization code
  • Miscellanous
    • Get statistics
• Examples
• Coverage
• License

Installation

Simply execute the following command in your commandline:

npm install typerinth

Usage

Import the package like this:

import { Modrinth } from 'typerinth';
const modrinth = new Modrinth();

Options

You can change the options to tune typerinth to your liking:

import { Modrinth } from 'typerinth';
const modrinth = new Modrinth({
    userAgent: 'AppName/Version',
    cache: new NodeCache({ stdTTL: 300 }),
});

Once you have done this, you can use all the following methods as you like.

Please note that these are only some methods. You can find a full list of all methods here.

---

Projects

Search

Simple Search

You can perform a basic search using the search method, with options like limit and sort:

import { SearchSort } from 'typerinth';
const result = await modrinth.search('life', {
    limit: 3,
    sort: SearchSort.Downloads,
});

If you want to filter the results further, you can use the filters option for simple filtering, or facets for more advanced filtering. Note that if you use facets, they will override the filters.

Search with Filters

Filters allow for straightforward filtering by things like project type or compatible versions:

import { SearchSort } from 'typerinth';
const result = await modrinth.search('life', {
    limit: 3,
    sort: SearchSort.Downloads,
    filters: {
        projectType: 'plugin',
        versions: ['1.20', '1.21'],
    },
});

Search with Facets

Facet-based searching is closer to the official Modrinth API and more flexible, though slightly more complex.

1. Facet: Represents a single filter condition. It consists of:
   • FacetType: The category of the filter (e.g., versions, categories, etc.).
   • FacetOperation: The comparison method (like EQUALS).
   • Value: The actual value to filter by.
2. FacetGroup: Combines multiple Facets with a logical OR. If any of the Facets in the group match, the result is included. A FacetGroup can also just have one Facet.
3. SearchFacets: Combines multiple FacetGroups with a logical AND.

Here’s an example where we search for projects related to "life", filtering them to show only results that:

• Belong to the "forge" category AND
• Are compatible with Minecraft version "1.16.5" OR "1.20.1".

import { SearchSort, SearchFacets, FacetGroup, Facet } from 'typerinth';
const result = await modrinth.search('life', {
    limit: 3,
    sort: SearchSort.Downloads,
    facets: new SearchFacets(
        new FacetGroup(
            new Facet(FacetType.Categories, FacetOperation.EQUALS, 'forge')
        ),
        new FacetGroup(
            new Facet(FacetType.Versions, FacetOperation.EQUALS, '1.16.5'),
            new Facet(FacetType.Versions, FacetOperation.EQUALS, '1.17.1')
        )
    ),
});

> Typedoc

Get a project by its ID or slug

const project = await modrinth.getProject('project-id');

> Typedoc

Get multiple projects by their IDs or slugs

const projects = await modrinth.getProjects(['project-id-1', 'project-id-2']);

> Typedoc

Get a random selection of projects

const projects = await modrinth.getRandomProjects(5);

> Typedoc

Check if a project ID or slug is valid

const isValid = await modrinth.checkProjectValidity('project-id');

> Typedoc

---

Versions

Get the versions of a project

const versions = await modrinth.getProjectVersions('project-id', {
    loaders: ['forge'],
    gameVersions: ['1.16.5'],
});

> Typedoc

Get a version by its ID

const version = await modrinth.getVersion('version-id');

> Typedoc

Get multiple versions by their IDs

const versions = await modrinth.getVersions(['version-id-1', 'version-id-2']);

> Typedoc

Get the version from a file hash

const version = await modrinth.getVersionFromFileHash('file-hash');

> Typedoc

---

Users

Get a user by their ID or username

const user = await modrinth.getUser('user-id');

> Typedoc

Get multiple users by their IDs or usernames

const users = await modrinth.getUsers(['user-id-1', 'user-id-2']);

> Typedoc

Get a user's projects

const projects = await modrinth.getUserProjects('user-id');

> Typedoc

Get the authenticated user

This method returns the user that is authenticated by the authorization header

const projects = await modrinth.getAuthUser();

> Typedoc

---

Teams

Get a project's team members

const members = await modrinth.getProjectTeamMembers('project-id');

Get a team's members

const members = await modrinth.getTeamMembers('team-id');

Get the members of mutliple teams

const members = await modrinth.getMultipleTeamMembers([
    'team-1-id',
    'team-2-id',
]);

---

Tags

Get tags

Gets tags as described in the Modrinth API documentation.

import { TagType } from 'typerinth';
const tags = await modrinth.getTag(TagType.Loader);

> Typedoc

Get a License by its ID

const license = await modrinth.getLicense('license-id');

> Typedoc

---

Auth

Generate an authorization URL to get an authorization code

const url = modrinth.generateAuthorizationUrl(
    CLIENT_ID,
    'http://localhost:3000/callback',
    [AuthScope.UserRead, AuthScope.PayoutsRead]
);

> Typedoc

Get an access token from an authorization code

const token = await modrinth.getToken(
    'YNJZ3OPwkgC7B4svVFv6PTDWdLNajGZx,
    CLIENT_ID,
    'http://localhost:3000/callback'
);

> Typedoc

---

Miscellanous

Get statistics

const stats = await modrinth.getStatistics();

> Typedoc

Examples

• OAuth flow example - A simple example on how to implement a secure OAuth 2.0 login flow using Typerinth

Coverage

You can find a list of the endpoints covered by this library in the coverage.md file.

License

This project is licensed under the MIT License - see the LICENSE file for details.