Manage social/gaming party systems in JavaScript
Install the package using your favourite package manager.
npm install party-principal
const { PartyClient } = require("party-principal");
const client = new PartyClient();
// Register users
client.users.register([{ id: "flutter" }, { id: "twilight" }]);
// Create a party
const myParty = client.parties.create({
id: "my-party",
members: [client.users.get("flutter")],
});
// Handle party invites
const invite = myParty.members.get("flutter").invite(client.users.get("twilight"));
invite.accept();
// Create custom metadata for a user
myParty.members.get("flutter").setMeta({ level: 10 });
myParty.members.get("flutter").meta; // -> { level: 10 }
// Handle party leadership transfers
myParty.transferTo("twilight");
myParty.members.get("twilight").promote("flutter");
// Listen to party creations
client.on("partyCreate", (party) => {
console.log(`Party ${party.id} created!`);
});
All methods on PartyMember are "secure", which means that party-principal will check their permissions before executing them. For example, if you try to kick another member from the party while not being the party leader, party-principal will throw an error.
partyMember.leader; // -> false
// ❌ This will throw an error
partyMember.kick(otherMember);
// âś… Bypass this by running it on the party instead
partyMember.party.members.delete(otherMember);
This way, you can directly run .kick()
without checking if the user is a party leader.
You can access the client using .client
on any class in party-principal (except for the client, of course).
declare namespace "party-principal" {
type UserMeta: ...;
type PartyMeta: ...;
type InviteMeta: ...;
}
Managers (BaseManager
, PartyManager
, PartyMemberManager
, UserInvitesManager
, and UserManager
) extends
@discordjs/collection
for storing data. See the
documentation for Collections.
Some managers offer .delete()
overrides which can take in the structure its managing instead of the key (the ID).
const user = client.users.get("flutter");
client.users.delete(user);
// or
client.users.delete("flutter");
It's not recommended to use set an existing value in a manager to undefined (.set("id", undefined)
). Instead, use
.delete()
to ensure proper side effects are executed.
Can be accessed through PartyClient.parties
.
Can be accessed through Party.members
.
type UserResolvable = User | string; // if a string is passed, it will be resolved to the user with that ID
Adds user(s) to the party.
Can be accessed through User.invites
.
Creates an invite.
interface InviteOptions {
id?: string;
meta?: InviteMeta;
invitee: User;
inviter: PartyMember;
expiresAt?: Date | null;
}
Can be accessed through PartyClient.users
.
Registers a global user.
interface UserOptions {
id: string;
meta?: UserMeta;
}
Can be fetched through User.invites.get()
.
The invite's ID.
The invite's metadata. Set metadata with .setMeta()
.
The user who was invited.
The party member who invited the user.
Whether the invite was accepted, denied, or is still pending.
When the invite expires. If null, the invite will never expire.
Whether the invite has expired.
Whether the invite has been used.
Sets the invite's metadata.
Accepts the invite.
Denies the invite.
Can be fetched through Client.parties.get()
.
The party's ID.
The party's metadata. Set metadata with .setMeta()
.
The party's members.
The party leader.
Sets the party's metadata.
Transfers party leadership to another member.
Can be fetched through Party.members.get()
.
The party member's ID.
The party member's global user object.
The party the member is in.
Whether the party member is the party leader.
Leaves the party. Returns whether the member was successfully removed from the party.
interface PartyMemberInviteOptions {
id?: string;
expiresAt?: Date;
meta?: InviteMeta;
}
Invites a user to the party.
Kicks a member from the party. Throws a MissingPermissionError
if the member is not the party leader.
Promotes a member to party leader. Throws a MissingPermissionError
if the member is not the party leader.
Can be fetched through Client.users.get()
.
The user's ID.
The user's metadata. Set metadata with .setMeta()
.
The user's invites.
The party the user is in. If null, the user is not in a party.
The party member object of the user. If null, the user is not in a party.
Sets the user's metadata.
PartyClient
exposes a Node.js EventEmitter
. Listen to an event using .on("eventName", (...params) => ...)
.
Envoked when a party is created.
Envoked when a party is deleted.
Envoked when a party member joins a party.
Envoked when a party member leaves a party.
Envoked whenever a party member is kicked from a party.
Please note that member: PartyMember
will not be an actual member anymore and any methods on it should not be called.
Envoked whenever a party member promotes another member.
Please note that member: PartyMember
will not be an actual member anymore and any methods on it should not be called.
Envoked when an invite is created.
Envoked when an invite is used.
Envoked when an invite is deleted, such as when it has been expired, used, or manually deleted.
The type of metadata for a user. Can be configured by modifying the namespace.
The type of metadata for a party. Can be configured by modifying the namespace.
The type of metadata for an invite. Can be configured by modifying the namespace.
A user or a user ID.
All errors extends the native Error
class.
Thrown when a method belonging to a User or PartyMember is called that requires a permission they do not have.
Apache License 2.0