polympics | polympics

Intro

Creating a client

The first thing you need to do to use the API is create an API client. There are 3 types of client:

Unauthenticated
App-authenticated
User-authenticated

Creating an unauthenticated client is very simple:

const client = polympics.UnauthenticatedClient();

However, if you want to do anything other than read-only operations, you’ll need to authenticate. To use app credentials, see the following example:

const credentials = { username: 'A3', password: 'YOUR-TOKEN-HERE'};
const client = polympics.AppClient({ credentials: credentials });

Creating a user-authenticated client is very similar:

const credentials = Credentials('S4', 'YOUR-TOKEN-HERE');
const client = polympics.UserClient({ credentials: credentials });

All three clients take an additional parameter, apiUrl. This is location at which the API is hosted, for example http://127.0.0.1:8000 or https://api.polytopia.fun.

Getting an account

You can get an account by Discord ID using getAccount. For example:

const account = await client.getAccount('12345678901234');
console.log(account.name);
console.log(account.permissions);
console.log(account.team.name);

Note that Discord IDs are strings, because they require more precision than JavaScript's default numeric type has.

Getting a team

You can get a team by ID using getTeam. For example:

const team = await client.getTeam(31);
console.log(team.name);
console.log(team.memberCount);

Getting an award

You can get an award by ID using getAward. For example:

const award = await client.getAward(14);
console.log(award.title);
console.log(award.imageUrl);

Listing all accounts

You can list all accounts using listAccounts. For example:

const accountPaginator = client.listAccounts();
for (const account of await accountPaginator.nextPage()) {
    console.log(account.name);
}

Note that this will only fetch the first page of results (20, by default). To fetch more, you should call nextPage() repeatedly until it returns an empty array. You can also get a specific page:

const accountPaginator = client.listAccounts();
const data = await accountPaginator.getPage(4);
console.log(data.result);    // Total result count.
for (const account of data.data) {
    console.log(account.name);
}

You can use the search and team options to narrow down results:

const accountPaginator = client.listAccounts({
    team: team, search: 'bob'
});
console.log(`Members from team ${team.name} with "bob" in their name:`);
for (const account of await accountPaginator.nextPage()) {
    console.log(account.name);
}

Listing all teams

You can list all teams using listTeams. For example:

const teamPaginator = client.listTeams();
for (const team of await teamPaginator.nextPage()) {
    console.log(team.name);
}

This supports the same pagination system as listAccounts, as well as the search option.

Creating an account

Registering a user is a simple call to createAccount:

const team = await client.getTeam(5);
const account = await client.createAccount({
    id: '1234567',
    name: 'Artemis',
    discriminator: '8472',
    avatarUrl: 'https://picsum.photos/200',
    team: team
});
console.assert(account.name === 'Artemis');
console.assert(account.team.id === 5);

Note that this requires an AppClient or UserClient with the manageAccountDetails permission.

You can also chose the permissions to grant the user:

await client.createAccount({
    id: '1234567',
    name: 'Artemis',
    discriminator: '8472',
    permissions: polympics.PolympicsPermissions.manageTeams
        & polympics.PolympicsPermissions.manageAccountDetails
});

Note, when granting permissions to a user:

You must be authenticated.
You cannot grant permissions you do not have.
You cannot grant authenticate_users, since that’s not a permission users can have.
You cannot grant permissions unless you have the manage_permissions permission, except as stated below:
You can grant the manage_own_team permission to other members of your own team (as long as you also have manage_own_team).

Editing an account

Editing a user's account can be done with updateAccount:

let account = await client.getAccount('41129492792313');
account = await client.updateAccount(account, {
    name: 'Artemis', discriminator: '3910'
});
console.assert(account.name === 'Artemis');

This requires an AppClient or UserClient with the manageAccountDetails permission.

You can similarly update a user's team:

account = await client.updateAccount(account, { team: team });

This requires an AppClient or UserClient with the manageAccountTeams permission, or a UserClient authenticated with the given account.

By setting team to null, you can remove a user from a team;

account = await client.updateAccount(account, { team: null });

This requires permissions as explained above for adding a user to a team, with the addition that you can remove a user from a team if you are a member of that team and have the manageOwnTeam permission.

You can also update user permissions with the grantPermissions and revokePermissions options, subject to the rules outlined in "Creating an account".

Example:

account = await client.updateAccount(account, {
    grantPermissions: polympics.PolympicsPermissions.manageOwnTeam,
    revokePermissions: polympics.PolympicsPermissions.manageTeams
});

Using the discordToken option, you can update a user's name, discriminator and avatar URL to match Discord. This requires no permissions, since user tokens can be authenticated with Discord.

Example:

account = await client.updateAccount(account, { discordToken: token });

Deleting an account

You can delete a user's account with the deleteAccount method:

const account = await client.g, for the team's name:
```js
teametAccount('124214913289');
await client.deleteAccount(account);

This requires an AppClient or UserClient with the manageAccountDetails permission, or just a UserClient associated with the account being deleted.

Creating a team

You can create a team using the createTeam method. It accepts one parameter, name, for the team's name:

const team = await client.createTeam({ name: 'Gods of Olympus' });
console.assert(team.name === 'Gods of Olympus');

This requires an AppClient or UserClient with the manageTeams permission.

Editing a team

You can edit a team using the updateTeam method. It accepts the same name parameter as createTeam:

let team = await client.getTeam(13);
team = await client.updateTeam(team, { name: 'Cool Kidz' });
console.assert(team.name === 'Cool Kidz');

This requires an AppClient or UserClient with the manageTeams permission, or just a UserClient with the manageOwnTeam permission who is a member of the given team.

Deleting a team

You can delete a team with the deleteTeam method:

let team = await client.getTeam(28);
await client.deleteTeam(team);

This requires an AppClient or UserClient with the manageTeams permission, or just a UserClient with the manageOwnTeam permission who is a member of the given team.