@mattplays/minecraft-api v0.0.2

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](https://wiki.vg/Mojang_API)

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

Output

The Authenticate function returns a Promise<AuthenticationResponse> type

Usage

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](https://wiki.vg/Lastlogin).

Inputs

Output

The Refresh function returns a Promise<RefreshResponse> type

Usage

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

Output

The Validate functions returns an empty payload (Promise<any>)

Usage

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

Output

The Signout function returns an empty payload if successful (Promise<any>)

Usage

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

Output

The Invalidate function returns an empty payload if successful (Promise<any>)

Usage

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

Output

The UsernameToUUID function returns a Promise<UUIDResponse> type

Usage

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

Output

The UsernameToUUID function returns a Promise<UUIDResponse> type

Usage

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

Output

The UUIDToNameHistory function returns

Promise<{name: string, changedToAt: number}[]>

Usage

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](https://sessionserver.mojang.com/session/minecraft/profile/4566e69fc90748ee8d71d7ba5aa00d20) This has no ratelimit.

Inputs

Output

The UUIDToSkin function returns

Promise<{id: string, name: string, properties: {name: string, value: string, signature: string}[], legacy: boolean}>

Usage

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

Output

The GetStatistics function returns a

Promise<{
    total: number, 
    last24h: number, 
    saleVelocityPerSeconds: number,
}>

Usage

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

Output

The GetProfileInfo function returns a Promise<ProfileInfoResponse> type

Usage

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

Output

The GetProfileNameChangeInfo function returns a Promise<ProfileNameChangeInfoResponse> type

Usage

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

Output

The CheckNameAvailability function returns a

Promise<{
    status: "DUPLICATE" | "AVAILABLE"
}>

Usage

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

Output

The ChangeName function returns a Promise<ProfileInfoResponse> type if successful or Promise<ChangeNameError> type if not.

Usage

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

Output

Upon error, the server will send back a JSON with the error. (Success is a blank payload) Promise<any>

Usage

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

Output

No response unless an error occurred.

Usage

const API = new MinecraftAPI();
API.ResetSkin("DUMMY_ACCESS-TOKEN", "069a79f444e94726a5befca90e38aaf5").then(() => {
    // Your Code Here :D
}).catch((err) => {
    // Handle error Here D:
});

Return Types

ServerStatusResponse

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

export interface AuthenticationResponse {
    user: {
        username: string,
        properties: AuthenticationProperty[],
        id: string,
    },
    clientToken: string,
    accessToken: string,
    availableProfiles: AuthenticationProfile[],
    selectedProfile: AuthenticationProfile
}

AuthenticationProperty

interface AuthenticationProperty {
    name: string,
    value: string
}

AuthenticationProfile

interface AuthenticationProfile  {
    name: string,
    id: string
}

RefreshResponse

export interface RefreshResponse {
    accessToken: string,
    clientToken: string,
    selectedProfile: {id: string, name: string},
    user: {id: string, properties: {name: string, value: string}[]}
}

UUIDResponse

export interface UUIDReponse {
    name: string,
    id: string,
}

ProfileInfoResponse

export interface ProfileInfoResponse {
    id: string,
    name: string,
    skins:  {id: string, state: string, url: string, variant: string}[],
    capes: [];
}

ProfileNameChangeInfoResponse

export interface ProfileNameChangeInfoResponse {
    changedAt: string,
    createdAt: string,
    nameChangeAllowed: boolean;
}