typerinth
Version:
A TypeScript library for interacting with the Modrinth API.
376 lines (375 loc) • 17.2 kB
JavaScript
"use strict";
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
const MROptions_1 = require("./interfaces/MROptions");
const url_1 = require("url");
const GetProjectRoute_1 = require("./routes/projects/GetProjectRoute");
const GetMultipleProjectsRoute_1 = require("./routes/projects/GetMultipleProjectsRoute");
const CacheManager_1 = __importDefault(require("./util/CacheManager"));
const GetRandomProjects_1 = require("./routes/projects/GetRandomProjects");
const CheckProjectValidityRoute_1 = require("./routes/projects/CheckProjectValidityRoute");
const StatisticsRoute_1 = __importDefault(require("./routes/miscellaneous/StatisticsRoute"));
const SearchProjectRoute_1 = __importDefault(require("./routes/projects/SearchProjectRoute"));
const GetUserRoute_1 = __importDefault(require("./routes/users/GetUserRoute"));
const GetMultipleUsersRoute_1 = __importDefault(require("./routes/users/GetMultipleUsersRoute"));
const GetUserProjectsRoute_1 = __importDefault(require("./routes/users/GetUserProjectsRoute"));
const GetTagRoute_1 = __importDefault(require("./routes/tags/GetTagRoute"));
const GetLicenseRoute_1 = __importDefault(require("./routes/tags/GetLicenseRoute"));
const GetProjectVersionsRoute_1 = __importDefault(require("./routes/versions/GetProjectVersionsRoute"));
const GetVersionRoute_1 = __importDefault(require("./routes/versions/GetVersionRoute"));
const GetMultipleVersionsRoute_1 = __importDefault(require("./routes/versions/GetMultipleVersionsRoute"));
const GetVersionFromFileHashRoute_1 = __importDefault(require("./routes/versions/GetVersionFromFileHashRoute"));
const GetAuthUserRoute_1 = __importDefault(require("./routes/users/GetAuthUserRoute"));
const GetTokenRoute_1 = __importDefault(require("./routes/auth/GetTokenRoute"));
const GetProjectTeamMembers_1 = __importDefault(require("./routes/teams/GetProjectTeamMembers"));
const GetTeamMembers_1 = __importDefault(require("./routes/teams/GetTeamMembers"));
const GetMultipleTeamsMembers_1 = __importDefault(require("./routes/teams/GetMultipleTeamsMembers"));
const GetFollowedProjectsRoute_1 = __importDefault(require("./routes/users/GetFollowedProjectsRoute"));
/**
* The main class for the Modrinth API
*
* @example
* import { Modrinth } from "typerinth";
*
* const modrinth = new Modrinth();
*
* modrinth.search("fabric").then(console.log);
*/
class Modrinth {
options;
cacheManager;
/**
* Create a new Modrinth instance
* @param options Options for the Modrinth instance
* @example
* const modrinth = new Modrinth({
* baseUrl: 'https://api.modrinth.com',
* apiVersion: 'v2',
* userAgent: 'AppName/Version',
* cache: {
* ttl: 600,
* checkperiod: 120,
* useCache: true,
* },
* });
*/
constructor(options = {}) {
this.options = {
...(0, MROptions_1.getDefaultOptions)(),
...options,
};
this.cacheManager = new CacheManager_1.default(this.options.cache);
}
/**
* Get the options for the Modrinth instance
* @returns The options for the Modrinth instance
*/
getOptions() {
return this.options;
}
/**
* Get the base URL for the Modrinth API
* @returns The base URL for the Modrinth API
*/
getApiUrl() {
return new url_1.URL(`${this.options.baseUrl}`);
}
/**
* Search for projects
* @param query The query to search for
* @param options Options for the search
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @returns The search results
* @category Projects
* @example
* // Example using simple filters:
* import { SearchSort } from 'typerinth';
* const result = await modrinth.search('life', {
* limit: 3,
* sort: SearchSort.Downloads,
* filters: {
* projectType: 'plugin',
* versions: ['1.20', '1.21'],
* },
* });
* @example
* // Example using SearchFacets:
* const result = await modrinth.search('life', {
* limit: 3,
* index: SearchIndex.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')
* )
* ),
* });
*/
search(query, options) {
return new SearchProjectRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, query, options).getData();
}
/**
* Get a project by its ID or slug
* @param projectId The ID or slug of the project to get
* @returns The project with the given ID or slug
* @throws {} {@link ProjectNotFoundError} If the project with the given ID or slug does not exist
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Projects
*/
getProject(projectId) {
return new GetProjectRoute_1.GetProjectRoute(this.getApiUrl(), this.options.userAgent, this.cacheManager, projectId).getData();
}
/**
* Get multiple projects by their IDs or slugs
* @param projectIds The IDs or slugs of the projects to get
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Projects
*/
getProjects(projectIds) {
return new GetMultipleProjectsRoute_1.GetMultipleProjectsRoute(this.getApiUrl(), this.options.userAgent, this.cacheManager, projectIds).getData();
}
/**
* Get a random selection of projects
* @param count The number of projects to get (between 0 and 100)
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Projects
*/
getRandomProjects(count) {
return new GetRandomProjects_1.GetRandomProjects(this.getApiUrl(), this.options.userAgent, this.cacheManager, count).getData();
}
/**
* Check if a project is valid
* @param projectId The ID or slug of the project to check
* @returns Whether the project is valid
* @category Projects
*/
checkProjectValidity(projectId) {
return new CheckProjectValidityRoute_1.CheckProjectValidityRoute(this.getApiUrl(), this.options.userAgent, this.cacheManager, projectId).getData();
}
/**
* Get the versions of a project
* @param projectId The ID or slug of the project to get the versions of
* @param options Options for the search
* @throws {} {@link VersionNotFoundError} If there are no versions for the project
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Versions
*/
getProjectVersions(projectId, options = {}) {
return new GetProjectVersionsRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, projectId, options).getData();
}
/**
* Get a version of a project
* @param versionId The ID of the version to get
* @throws {} {@link VersionNotFoundError} If the version with the given ID does not exist
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Versions
*/
getVersion(versionId) {
return new GetVersionRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, versionId).getData();
}
/**
* Get multiple versions by their IDs
* @param versionIds The IDs of the versions to get
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Versions
*/
getVersions(versionIds) {
return new GetMultipleVersionsRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, versionIds).getData();
}
/**
* Get a version from a file hash
* @param fileHash The hash of the file to get the version of
* @param options Options for the search
* @returns The version with the given file hash
* @throws {} {@link VersionNotFoundError} If the version with the given file hash does not exist
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Versions
*/
getVersionFromFileHash(fileHash, options = {}) {
return new GetVersionFromFileHashRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, fileHash, options).getData();
}
/**
* Get a user by their ID or username
* @param userId The ID or username of the user to get
* @throws {} {@link UserNotFoundError} If the user with the given ID or username does not exist
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Users
*/
getUser(userId) {
return new GetUserRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, userId).getData();
}
/**
* Get multiple users by their IDs or usernames
* @param userIds The IDs or usernames of the users to get
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Users
*/
getUsers(userIds) {
return new GetMultipleUsersRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, userIds).getData();
}
/**
* Get a user's projects by their ID or username
* @param userId The ID or username of the user
* @throws {} {@link UserProjectsNotFoundError} If the user's projects do not exist
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Users
*/
getUserProjects(userId) {
return new GetUserProjectsRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, userId).getData();
}
/**
* Get the projects followed by a user
*
* **Rquires authorization** with scope:
* > `USER_READ`
* @param userId The ID or username of the user to get the followed projects of
* @param authorization The authorization header to use (if not set, the one from the options will be used)
* @throws {} {@link UserNotFoundError} If the user with the given ID or username does not exist
* @throws {} {@link ApiError} If an error occurs
* @category Users
*/
getFollowedProjects(userId, authorization) {
return new GetFollowedProjectsRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, authorization || this.options.authorization, userId).getData();
}
/**
* Get the user that is authenticated with the authorization header
*
* **Rquires authorization** with scope:
* > `USER_READ`
* @param authorization The authorization header to use (if not set, the one from the options will be used)
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @returns The authenticated user
* @category Users
*/
getAuthUser(authorization) {
return new GetAuthUserRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, authorization || this.options.authorization).getData();
}
/**
* Get the team members of a project
*
* @param projectId The ID or slug of the project to get the team members of
* @throws {} {@link ProjectNotFoundError} If the project with the given ID or slug does not exist
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @returns The team members of the project with the given ID or slug
* @category Teams
*/
getProjectTeamMembers(projectId) {
return new GetProjectTeamMembers_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, this.options.authorization, projectId).getData();
}
/**
* Get the team members of a team
*
* @param teamId The ID of the team to get the members of
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @returns The team members of the team with the given ID
* @category Teams
*/
getTeamMembers(teamId) {
return new GetTeamMembers_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, this.options.authorization, teamId).getData();
}
/**
* Get the members of multiple teams
*
* @param teamIds The IDs of the teams to get the members of
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @returns The members of the teams with the given IDs
* @category Teams
*/
getMultipleTeamMembers(teamIds) {
return new GetMultipleTeamsMembers_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, this.options.authorization, teamIds).getData();
}
/**
* Get a tag by its type
* @param tagType The type of the tag to get
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Tags
*/
getTag(tagType) {
return new GetTagRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, tagType).getData();
}
/**
* Get a license by its ID
* @param licenseId The ID of the license to get
* @throws {} {@link LicenseNotFoundError} If the license with the given ID does not exist
* @throws {} {@link ApiError} If an error occurs
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Tags
*/
getLicense(licenseId) {
return new GetLicenseRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, licenseId).getData();
}
/**
* Get the statistics for Modrinth
* @returns The statistics for Modrinth
* @throws {} {@link UnexpectedApiError} If an unexpected error occurs
* @category Miscellaneous
*/
getStatistics() {
return new StatisticsRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager).getData();
}
/**
* Get an access token from an authorization code
*
* (Rquest to `https://api.modrinth.com/_internal/oauth/token`)
*
* [Modrinth OAuth Guide](https://docs.modrinth.com/guide/oauth/)
* @param code The authorization code gotten from the authorization URL
* @param clientId The ID of the client
* @param redirectUri The uri to redirect to after getting the token (must be listed in the client's redirect URIs)
* @param clientSecret The secret of the client
* @returns The access token and other token information
* @category Auth
*/
getToken(code, clientId, redirectUri, clientSecret) {
return new GetTokenRoute_1.default(this.getApiUrl(), this.options.userAgent, this.cacheManager, clientSecret, code, clientId, redirectUri).getData();
}
/**
* Generate an authorization URL to get an authorization code
*
* [Modrinth OAuth Guide](https://docs.modrinth.com/guide/oauth/)
* @param clientId The ID of the client
* @param redirectUri The uri to redirect to with the authorization code (must be listed in the client's redirect URIs)
* @param scopes The scopes to request authorization for (must be listed in the client's scopes)
* @param state An optional state parameter to include in the URL (useful for CSRF protection)
* @returns The URL to get the authorization code
* @category Auth
*
* @example
* new Modrinth().generateAuthorizationUrl(
* CLIENT_ID,
* "https://example.com/auth/callback",
* [AuthScope.UserRead, AuthScope.PayoutsRead]
* );
*/
generateAuthorizationUrl(clientId, redirectUri, scopes, state) {
const url = new url_1.URL('https://modrinth.com/auth/authorize');
url.searchParams.append('client_id', clientId);
url.searchParams.append('redirect_uri', redirectUri);
url.searchParams.append('scope', scopes.join('+'));
if (state)
url.searchParams.append('state', state);
return url.toString();
}
}
exports.default = Modrinth;