@mattplays/minecraft-api

This package is a wrapper for the official Minecraft API

Usage no npm install needed!

<script type="module">
  import mattplaysMinecraftApi from 'https://cdn.skypack.dev/@mattplays/minecraft-api';
</script>

README

MinecraftAPI

This package is a wrapper for the official Minecraft API

  1. Minecraft
    1. Usage
    2. Functions
      1. GetAPIStatus
        1. Output
        2. Usage
      2. Authenticate
        1. Inputs
        2. Output
        3. Usage
      3. Refresh
        1. Inputs
        2. Output
        3. Usage
      4. Validate
        1. Inputs
        2. Output
        3. Usage
      5. Signout
        1. Inputs
        2. Output
        3. Usage
      6. Invalidate
        1. Inputs
        2. Output
        3. Usage
      7. UsernametoUUID
        1. Input
        2. Output
        3. Usage
      8. UsernamesToUUIDs
        1. Input
        2. Output
        3. Usage
      9. UUIDToNameHistory
        1. Input
        2. Output
        3. Usage
      10. UUIDToSkin
        1. Input
        2. Output
        3. Usage
      11. GetBlockedServers
        1. Output
        2. Usage
      12. GetStatistics
        1. Output
        2. Usage
      13. GetPlayerInfo
        1. Input
        2. Output
        3. Usage
      14. GetPlayerNameChangeInfo
        1. Input
        2. Output
        3. Usage
      15. CheckNameAvailability
        1. Inputs
        2. Output
        3. Usage
      16. ChangeName
        1. Inputs
        2. Output
        3. Usage
      17. ChangeSkin
        1. Inputs
        2. Output
        3. Usage
      18. ResetSkin
        1. Inputs
        2. Output
        3. Usage
    3. Return Types
      1. ServerStatusResponse
      2. AuthenticationResponse
        1. AuthenticationProperty
        2. AuthenticationProfile
      3. RefreshResponse
      4. UUIDResponse
      5. ProfileInfoResponse
      6. ProfileNameChangeInfoResponse

Minecraft

This is an Offical API Offical Docs

Usage

const {MinecraftAPI} = require("@mattplays/minecraft-api")
const API = new MinecraftAPI();

Functions

GetAPIStatus

Returns status of various Mojang services. Possible values are green (no issues), yellow (some issues), red (service unavailable).

Output

The GetAPIStatus function returns a Promise<ServerStatusResponse> type

Usage
const API = new MinecraftAPI();
API.GetAPIStatus().then((data) => {
// Your Code Here :D
}).catch((err) => {
    // Handle error Here D:
});;

Authenticate

Authenticates a user using their password.

Inputs
Parameter Type Required Description
username string Yes The user's username
password string Yes The user's password
##### Output
The Authenticate function returns a Promise<AuthenticationResponse> type
##### Usage
```javascript
const API = new MinecraftAPI();
API.Authenticate("Notch", "MINECRAFTROCKS").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});;
```
#### Refresh
Refreshes a valid accessToken. It can be used to keep a user logged in between gaming sessions and is preferred over storing the user's password in a file see lastlogin.
##### Inputs
Parameter Type Required Description
accessToken string Yes The user's accessToken
clientToken string Yes The clientToken that was used to obtain accessToken in the first place
profileIdentifier string Yes a hexidecimal profile identifier
playerName string Yes The user's username
##### Output
The Refresh function returns a Promise<RefreshResponse> type
##### Usage
```javascript
const API = new MinecraftAPI();
API.Refresh("DUMMY_ACCESS-TOKEN", "DUMMY_CLIENT-TOKEN", "DUMMY_PROFILEIDENTIFIER", "DUMMY_PLAYERNAME").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### Validate
Checks if an accessToken is usable for authentication with a Minecraft server. The Minecraft Launcher (as of version 1.6.13) calls this endpoint on startup to verify that its saved token is still usable, and calls /refresh if this returns an error.

Note that an accessToken may be unusable for authentication with a Minecraft server, but still be good enough for /refresh. This mainly happens when one has used another client (e.g. played Minecraft on another PC with the same account). It seems only the most recently obtained accessToken for a given account can reliably be used for authentication (the next-to-last token also seems to remain valid, but don't rely on it).

/validate may be called with or without a clientToken. If a clientToken is provided, it should match the one used to obtain the accessToken. The Minecraft Launcher does send a clientToken to /validate.

Inputs
Parameter Type Required Description
accessToken string Yes The user's accessToken
clientToken string No The clientToken that was used to obtain accessToken in the first place
##### Output
The Validate functions returns an empty payload (Promise<any>)
##### Usage
```javascript
const API = new MinecraftAPI();
API.Validate("DUMMY_ACCESS-TOKEN").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### Signout
Invalidates accessTokens using an account's username and password.
##### Inputs
Parameter Type Required Description
------------- ------------- ------------- -------------
username string Yes The user's username
password string Yes The user's password
##### Output
The Signout function returns an empty payload if successful (Promise<any>)
##### Usage
```javascript
const API = new MinecraftAPI();
API.Signout("Notch", "Minecraft-ROCKS").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### Invalidate
Invalidates accessTokens using a client/access token pair.
##### Inputs
Parameter Type Required Description
------------- ------------- ------------- -------------
accessToken string Yes The user's accessToken
clientToken string Yes The clientToken that was used to obtain accessToken in the first place
##### Output
The Invalidate function returns an empty payload if successful (Promise<any>)
##### Usage
```javascript
const API = new MinecraftAPI();
API.Invalidate("DUMMMY_ACCESS-TOKEN", "DUMMY_CLIENT-TOKEN").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### UsernameToUUID
This will return the UUID of the username.
##### Input
Parameter Type Required Description
------------- ------------- ------------- -------------
username string Yes The user's username
##### Output
The UsernameToUUID function returns a Promise<UUIDResponse> type
##### Usage
```javascript
const API = new MinecraftAPI();
API.UsernameToUUID("Notch").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### UsernamesToUUIDs
This will return player UUIDs and some extras.
##### Input
Parameter Type Required Description
------------- ------------- ------------- -------------
usernames string[] Yes List of Usernames
##### Output
The UsernameToUUID function returns a Promise<UUIDResponse> type
##### Usage
```javascript
const API = new MinecraftAPI();
API.UsernamesToUUIDs(["Notch", "jeb_"]).then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### UUIDToNameHistory
Returns all the usernames this user has used in the past and the one they are using currently. The UUID must be given either without, or correctly formatted hyphens.
##### Input
Parameter Type Required Description
------------- ------------- ------------- -------------
uuid string Yes The user's UUID
##### Output
The UUIDToNameHistory function returns
```javascript
Promise<{name: string, changedToAt: number}[]>
```
##### Usage
```javascript
const API = new MinecraftAPI();
API.UUIDToNameHistory("069a79f444e94726a5befca90e38aaf5").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### UUIDToSkin
This will return the player's username plus any additional information about them (e.g. skins). Example This has no ratelimit.
##### Inputs
Parameter Type Required Description
------------- ------------- ------------- -------------
uuid string Yes The user's UUID
##### Output
The UUIDToSkin function returns
```javascript
Promise<{id: string, name: string, properties: {name: string, value: string, signature: string}[], legacy: boolean}>
```
##### Usage
```javascript
const API = new MinecraftAPI();
API.UUIDToSkin("4566e69fc90748ee8d71d7ba5aa00d20").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### GetBlockedServers
Returns a list of SHA1 hashes used to check server addresses against when the client tries to connect.

Clients check the lowercase name, using the ISO-8859-1 charset, against this list. They will also attempt to check subdomains, replacing each level with a *. Specifically, it splits based off of the . in the domain, goes through each section removing one at a time. For instance, for mc.example.com, it would try mc.example.com, *.example.com, and *.com. With IP addresses (verified by having 4 split sections, with each section being a valid integer between 0 and 255, inclusive) substitution starts from the end, so for 192.168.0.1, it would try 192.168.0.1, 192.168.0.*, 192.168.*, and 192.*.

This check is done by the bootstrap class in netty. The default netty class is overridden by one in the com.mojang:netty dependency loaded by the launcher. This allows it to affect any version that used netty (1.7+)

Output

The GetBlockedServers function returns a Promise<string[]> type

Usage
const API = new MinecraftAPI();
API.GetBlockedServers().then((data) => {
// Your Code Here :D
}).catch((err) => {
    // Handle error Here D:
});

GetStatistics

Get statistics on the sales of Minecraft.

Input
Parameter Type Required Description
metricKeys ["item_sold_minecraft", "prepaid_card_redeemed_minecraft"] Yes The Statistics you want
##### Output
The GetStatistics function returns a
```javascript
Promise<{
total: number,
last24h: number,
saleVelocityPerSeconds: number,
}>
```
##### Usage
```javascript
const API = new MinecraftAPI();
API.GetStatistics(["item_sold_minecraft"]).then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### GetProfileInfo
This API endpoint fetches information about the current account including UUID, username, skins, and capes.
##### Input
Parameter Type Required Description
------------- ------------- ------------- -------------
accessToken string Yes The user's accessToken
##### Output
The GetProfileInfo function returns a Promise<ProfileInfoResponse> type
##### Usage
```javascript
const API = new MinecraftAPI();
API.GetProfileInfo("DUMMY_ACCESS-TOKEN").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### GetProfileNameChangeInfo
This API endpoint fetches information about the profile name such as the date the name was changed and the date the account was created.
##### Input
Parameter Type Required Description
------------- ------------- ------------- -------------
accessToken string Yes The user's accessToken
##### Output
The GetProfileNameChangeInfo function returns a Promise<ProfileNameChangeInfoResponse> type
##### Usage
```javascript
const API = new MinecraftAPI();
API.GetProfileNameChangeInfo("DUMMY_ACCESS-TOKEN").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### CheckNameAvailability
This API endpoints check if the given name is available.
##### Inputs
Parameter Type Required Description
------------- ------------- ------------- -------------
name string Yes The username you want to check availability of
accessToken string Yes The user's accessToken
##### Output
The CheckNameAvailability function returns a
```javascript
Promise<{
status: "DUPLICATE" "AVAILABLE"
}>
```
##### Usage
```javascript
const API = new MinecraftAPI();
API.CheckNameAvailability("Notch", "DUMMY_ACCESS-TOKEN").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### ChangeName
This will set the name for the account that the access token in the Authorization header belongs to.
##### Inputs
Parameter Type Required Description
------------- ------------- ------------- -------------
newName string Yes The username you want
accessToken string Yes The user's accessToken
##### Output
The ChangeName function returns a Promise<ProfileInfoResponse> type if successful or Promise<ChangeNameError> type if not.
##### Usage
```javascript
const API = new MinecraftAPI();
API.ChangeName("Notch", "DUMMY_ACCESS-TOKEN").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### ChangeSkin
This will set the skin for the selected profile, but Mojang's servers will fetch the skin from a URL.
##### Inputs
Parameter Type Required Description
------------- ------------- ------------- -------------
variant "classic" \| "slim" Yes The skin type
url string Yes The URL to the skin
accessToken string Yes The user's accessToken
##### Output
Upon error, the server will send back a JSON with the error. (Success is a blank payload) Promise<any>
##### Usage
```javascript
const API = new MinecraftAPI();
API.ChangeSkin("slim", "https://thereisaskinhere.com/minecraft/totallyarealskin.png", "DUMMY_ACCESS-TOKEN").then((data) => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
#### ResetSkin
Resets the user's skin to the default one.
##### Inputs
Parameter Type Required Description
------------- ------------- ------------- -------------
uuid string Yes The Unique User Identifier of the User
accessToken string Yes The user's accessToken
##### Output
No response unless an error occurred.
##### Usage
```javascript
const API = new MinecraftAPI();
API.ResetSkin("DUMMY_ACCESS-TOKEN", "069a79f444e94726a5befca90e38aaf5").then(() => {
// Your Code Here :D
}).catch((err) => {
// Handle error Here D:
});
```
### Return Types
#### ServerStatusResponse
```typescript
export interface ServerStatusResponse {
"minecraft.net": "green" "yellow" "red",
"session.minecraft.net": "green" "yellow" "red",
"account.mojang.com": "green" "yellow" "red",
"authserver.mojang.com": "green" "yellow" "red",
"api.mojang.com": "green" "yellow" "red",
"textures.minecraft.net": "green" "yellow" "red",
"mojang.com": "green" "yellow" "red"
}
```
#### AuthenticationResponse
```typescript
export interface AuthenticationResponse {
user: {
username: string,
properties: AuthenticationProperty[],
id: string,
},
clientToken: string,
accessToken: string,
availableProfiles: AuthenticationProfile[],
selectedProfile: AuthenticationProfile
}
```
##### AuthenticationProperty
```typescript
interface AuthenticationProperty {
name: string,
value: string
}
```
##### AuthenticationProfile
```typescript
interface AuthenticationProfile {
name: string,
id: string
}
```
#### RefreshResponse
```typescript
export interface RefreshResponse {
accessToken: string,
clientToken: string,
selectedProfile: {id: string, name: string},
user: {id: string, properties: {name: string, value: string}[]}
}
```
#### UUIDResponse
```typescript
export interface UUIDReponse {
name: string,
id: string,
}
```
#### ProfileInfoResponse
```typescript
export interface ProfileInfoResponse {
id: string,
name: string,
skins: {id: string, state: string, url: string, variant: string}[],
capes: [];
}
```
#### ProfileNameChangeInfoResponse
```typescript
export interface ProfileNameChangeInfoResponse {
changedAt: string,
createdAt: string,
nameChangeAllowed: boolean;
}
```