@mcsb/api / Exports / MojangAPI

Class: MojangAPI ​

Interface for requesting data from the Mojang API.

While the Mojang API has a rate limit for many endpoints, request debouncing currently isn't built into the Mojang API interface. (TODO)

Example

const mojang = new MojangAPI();

const uuid = (await mojang.getUuid("Technoblade"))!; // v4 UUID string
const profile = (await mojang.getProfile(uuid))!; // MojangProfile
const skinUrl = profile.properties?.[0]?.value?.textures?.SKIN?.url; // URL string

const mojang = new MojangAPI();

const uuid = (await mojang.getUuid("Technoblade"))!; // v4 UUID string
const profile = (await mojang.getProfile(uuid))!; // MojangProfile
const skinUrl = profile.properties?.[0]?.value?.textures?.SKIN?.url; // URL string

Hierarchy ​

• BaseAPI<APIOptions>

  ↳ MojangAPI

Table of contents ​

Constructors ​

• constructor

Properties ​

• options

Methods ​

• authorize
• destroy
• getBlockedServerHashes
• getProfile
• getServerNamespaces
• getUuid
• isServerBlocked
• rawRequest
• request

Constructors ​

constructor ​

• new MojangAPI(options?)

Create a new instance of MojangAPI.

Parameters ​

Overrides ​

BaseAPI<APIOptions&gt;.constructor

Defined in ​

packages/api/src/MojangAPI.ts:29

Properties ​

options ​

• Protected Readonly options: Readonly<{ deferPolicy: null | IDeferPolicy<Response> ; httpClient: HttpClient }>

The options provided to the constructor, parsed by parseOptions.

Inherited from ​

BaseAPI.options

Defined in ​

packages/api/src/BaseAPI.ts:127

Methods ​

authorize ​

▸ authorize(accessToken): MojangAPI

TODO

Parameters ​

Returns ​

MojangAPI

Defined in ​

packages/api/src/MojangAPI.ts:37

destroy ​

▸ destroy(): void

Destroy this API instance, primarily by shutting down the HttpClient. Failure to do so may leave your program hanging if you do not explicitly interrupt it.

Returns ​

void

Inherited from ​

BaseAPI.destroy

Defined in ​

packages/api/src/BaseAPI.ts:279

getBlockedServerHashes ​

▸ getBlockedServerHashes(): Promise<string[]>

Get the list of SHA1 server address hashes blocked by Mojang. For more information about how blocked server addresses are hashed and checked, see isServerBlocked and the Mojang documentation. The rate limit for this endpoint is IP-based. Its limit is currently unknown.

Returns ​

Promise<string[]>

a Promise that resolves to an array of strings, where each string is a SHA1 hash

See

• isServerBlocked
• https://wiki.vg/Mojang_API#Blocked_Servers

Throws

• Error if the request to Mojang's servers fails or has a malformed response.
• Error if the Mojang rate limit is hit.

Defined in ​

packages/api/src/MojangAPI.ts:122

getProfile ​

▸ getProfile(uuid, raw?): Promise<null | objectOutputType<{ error: ZodOptional<ZodNullable<ZodString>> ; errorMessage: ZodOptional<ZodNullable<ZodString>> ; id: ZodOptional<ZodNullable<ZodString>> ; legacy: ZodOptional<ZodNullable<ZodBoolean>> ; name: ZodOptional<ZodNullable<ZodString>> ; path: ZodOptional<ZodNullable<ZodString>> ; profileActions: ZodReadonly<ZodDefault<ZodArray<ZodString, "many">>> ; properties: ZodDefault<ZodArray<ZodObject<{ name: ZodLiteral<"textures"> ; signature: ZodOptional<ZodNullable<ZodString>> ; value: ZodEffects<ZodString, { profileId: string ; profileName: string ; signatureRequired?: null | boolean ; textures?: null | Readonly<{ CAPE: { url: string; }; SKIN?: Readonly<{ url: string; metadata?: Readonly<{ model: "classic" | "slim"; }> | null | undefined; }> | null | undefined; }> ; timestamp: UnixDate }, string> }, "strip", ZodTypeAny, { name: "textures" ; signature?: null | string ; value: { timestamp: UnixDate; profileId: string; profileName: string; signatureRequired?: boolean | null | undefined; textures?: Readonly<{ CAPE: { url: string; }; SKIN?: Readonly<{ url: string; metadata?: Readonly<...> | ... 1 more ... | undefined; }> | null | undefined; }> | null | undefined; } }, { name: "textures" ; signature?: null | string ; value: string }>, "many">> }, ZodTypeAny, "passthrough">>

Get a Minecraft account's profile. Profile data includes the player's username, skin, cape, and character shape. The rate limit for this endpoint is IP-based, and has a limit of approximately 200 requests per minute.

Parameters ​

Returns ​

Promise<null | objectOutputType<{ error: ZodOptional<ZodNullable<ZodString>> ; errorMessage: ZodOptional<ZodNullable<ZodString>> ; id: ZodOptional<ZodNullable<ZodString>> ; legacy: ZodOptional<ZodNullable<ZodBoolean>> ; name: ZodOptional<ZodNullable<ZodString>> ; path: ZodOptional<ZodNullable<ZodString>> ; profileActions: ZodReadonly<ZodDefault<ZodArray<ZodString, "many">>> ; properties: ZodDefault<ZodArray<ZodObject<{ name: ZodLiteral<"textures"> ; signature: ZodOptional<ZodNullable<ZodString>> ; value: ZodEffects<ZodString, { profileId: string ; profileName: string ; signatureRequired?: null | boolean ; textures?: null | Readonly<{ CAPE: { url: string; }; SKIN?: Readonly<{ url: string; metadata?: Readonly<{ model: "classic" | "slim"; }> | null | undefined; }> | null | undefined; }> ; timestamp: UnixDate }, string> }, "strip", ZodTypeAny, { name: "textures" ; signature?: null | string ; value: { timestamp: UnixDate; profileId: string; profileName: string; signatureRequired?: boolean | null | undefined; textures?: Readonly<{ CAPE: { url: string; }; SKIN?: Readonly<{ url: string; metadata?: Readonly<...> | ... 1 more ... | undefined; }> | null | undefined; }> | null | undefined; } }, { name: "textures" ; signature?: null | string ; value: string }>, "many">> }, ZodTypeAny, "passthrough">>

A MojangProfile object, or null if a profile couldn't be found for the given UUID.

Throws

• Error if the request to Mojang's servers fails or has a malformed response.
• Error if the Mojang rate limit is hit.

Defined in ​

packages/api/src/MojangAPI.ts:87

▸ getProfile(uuid, raw?): Promise<RawResponse>

Get a Minecraft account's profile. Profile data includes the player's username, skin, cape, and character shape. The rate limit for this endpoint is IP-based, and has a limit of approximately 200 requests per minute.

Parameters ​

Returns ​

Promise<RawResponse>

A Promise that resolves with a RawResponse containing the raw data fetched from the Mojang API.

Throws

• Error if the request to Mojang's servers fails or has a malformed response.
• Error if the Mojang rate limit is hit.

Defined in ​

packages/api/src/MojangAPI.ts:99

getServerNamespaces ​

▸ Protected getServerNamespaces(serverAddress): string[]

Gets all strings used by Minecraft to test if a given server address is blocked. Minecraft tests the server address itself along with addresses with wildcards placed in each subdomain location, except for the TLD. For example, for the server address mc.hypixel.net, the returned strings will be:

• mc.hypixel.net
• *.hypixel.net
• *.net

If an IPv4 address is supplied, the order of wildcards is reversed. For example, for the IP address 192.168.1.1, the returned strings will be:

• 192.168.1.1
• 192.168.1.*
• 192.168.*
• 192.*

This is a recursive algorithm.

Parameters ​

Returns ​

string[]

An array of strings used by Minecraft to test if a Minecraft server address is blocked. The array is in order of most specific to least specific.

Defined in ​

packages/api/src/MojangAPI.ts:191

getUuid ​

▸ getUuid(name, raw?): Promise<null | string>

Get the Minecraft account UUID for a given username. If no player has the given username, null is returned. The rate limit for this endpoint is IP-based, and has a limit of approximately 200 requests per minute.

Parameters ​

Returns ​

Promise<null | string>

A UUID v4 string, or null if an account couldn't be found for the given username.

Throws

• Error if the request to Mojang's servers fails or has a malformed response.
• Error if the Mojang rate limit is hit.

Defined in ​

packages/api/src/MojangAPI.ts:53

▸ getUuid(name, raw?): Promise<RawResponse>

Get the Minecraft account UUID for a given username. If no player has the given username, null is returned. The rate limit for this endpoint is IP-based, and has a limit of approximately 200 requests per minute.

Parameters ​

Returns ​

Promise<RawResponse>

A Promise that resolves with a RawResponse containing the raw data fetched from the Mojang API.

Throws

• Error if the request to Mojang's servers fails or has a malformed response.
• Error if the Mojang rate limit is hit.

Defined in ​

packages/api/src/MojangAPI.ts:65

isServerBlocked ​

▸ isServerBlocked(serverAddress): Promise<boolean>

Checks if a given Minecraft server address is blocked by Mojang. This is done by checking the list of blocked server hashes from the Mojang API and comparing the SHA1 hash of the provided server address against the list. If the server address hash is not found in the list, a wild card is applied to the highest specificity subdomain/octet (e.g. dev.mc.hypixel.net -> *.mc.hypixel.net, and 192.168.0.1 -> 192.168.0.*). This process continues up to the TLD/the highest octet (e.g. *.net, and 192.*). If a matching hash is found within the list then the server is blocked by Mojang and true is returned.

Parameters ​

Returns ​

Promise<boolean>

true if a Minecraft server address is blocked by Mojang, or false if not.

Throws

• Error if the request to Mojang's servers fails or has a malformed response.
• Error if the Mojang rate limit is hit.

Defined in ​

packages/api/src/MojangAPI.ts:154

rawRequest ​

▸ Protected rawRequest(url): Promise<RawResponse>

Send a request to a given URL using this APIs HttpClient provided options. If the HttpClient has a cached response, then that response is returned immediately. Otherwise, we send a new request to the URL. Before sending the request, if an IDeferPolicy was provided to options, the defer policy is polled first.

Parameters ​

Returns ​

Promise<RawResponse>

A Promise which resolves to a RawResponse from the API.

Throws

• Error if the HTTP request fails

See

request

Inherited from ​

BaseAPI.rawRequest

Defined in ​

packages/api/src/BaseAPI.ts:184

request ​

▸ Protected request<S, V>(url, raw, schema?, mutator?): Promise<RawResponse>

Send an API request to the given URL using the provided HttpClient and IDeferPolicy.

Type parameters ​

Parameters ​

Returns ​

Promise<RawResponse>

• If raw is true, the RawResponse from rawRequest is returned.
• If raw is false and the mutator argument is undefined, the API response parsed by the provided schema is returned.
• If raw is false and a mutator argument is provided, the value returned by the mutator is returned.

Throws

• Error if the HTTP request fails.
• Error if the schema parsing fails.

See

https://zod.dev/

Inherited from ​

BaseAPI.request

Defined in ​

packages/api/src/BaseAPI.ts:219

▸ Protected request<S, V>(url, raw, schema, mutator?): Promise<TypeOf<S>>

Send an API request to the given URL using the provided HttpClient and IDeferPolicy.

Type parameters ​

Parameters ​

Returns ​

Promise<TypeOf<S>>

• If raw is true, the RawResponse from rawRequest is returned.
• If raw is false and the mutator argument is undefined, the API response parsed by the provided schema is returned.
• If raw is false and a mutator argument is provided, the value returned by the mutator is returned.

Throws

• Error if the HTTP request fails.
• Error if the schema parsing fails.

See

https://zod.dev/

Inherited from ​

BaseAPI.request

Defined in ​

packages/api/src/BaseAPI.ts:239

▸ Protected request<S, V>(url, raw, schema, mutator): Promise<V>

Send an API request to the given URL using the provided HttpClient and IDeferPolicy.

Type parameters ​

Parameters ​

Returns ​

Promise<V>

• If raw is true, the RawResponse from rawRequest is returned.
• If raw is false and the mutator argument is undefined, the API response parsed by the provided schema is returned.
• If raw is false and a mutator argument is provided, the value returned by the mutator is returned.

Throws

• Error if the HTTP request fails.
• Error if the schema parsing fails.

See

https://zod.dev/

Inherited from ​

BaseAPI.request

Defined in ​

packages/api/src/BaseAPI.ts:259