API Types

When it comes to working with low level API, dealing with raw JSON payloads and handling API payloads manually can be an overwhelming task.

To ease you in this case, Library provides easy to use type defintions for Revolt API that only allow you to properly typehint your application but also get cutting edge autocompletion in your code editor.

Enumerations

This section documents various enumerations from the Revolt API. All these are type aliases of typing.Literal.

luster.types.EventTypeSend

The types of websocket events that are sent by the client.

luster.types.EventTypeRecv

The types of websocket events that are received by the client.

luster.types.EventType

The types of websocket events. This is equivalent to typing.Union of EventTypeSend and EventTypeRecv.

luster.types.ErrorId

The error labels often sent in ErrorEvent websocket event.

luster.types.WebsocketVersion

The versions for Revolt websocket protocol.

luster.types.WebsocketFormat

The formats used for packets transport in Revolt websocket protocol.

luster.types.FileType

The types of file.

luster.types.FileTag

The tags or buckets that a file can be uploaded to.

luster.types.PresenceType

The presence states of a user.

luster.types.RelationshipStatus

The status of a relationship.

luster.types.UserRemoveField

The fields that can be removed from a user object by editing it.

luster.types.ChannelTypeServer

The channel types related to a server.

luster.types.ChannelTypePrivate

The channel types for private channels.

luster.types.ChannelType

All channel types.

luster.types.ChannelRemoveField

The fields that can be removed from channel object by editing it.

luster.types.ServerRemoveField

The fields that can be removed from server object by editing it.

API Models

This section documents type definitions for various API models. All these type definitions are subclasses of typing.TypedDict.

NodeInfo

class luster.types.NodeInfo

Represents the Revolt node info often returned by fetch_api_info() route.

app: str

The URL pointing to client serving this node.

features: luster.types.node_info.NodeInfoFeatures

The features enabled on this Revolt node.

revolt: str

Revolt API version.

vapid: str

The web push VAPID public key.

ws: str

The URL used for connecting to websocket.

NodeInfoFeatures

class luster.types.NodeInfoFeatures

Represents the features of a Revold node retrieved from NodeInfo

autumn: luster.types.node_info.NodeInfoAutumnFeature

The file server configuration.

captcha: luster.types.node_info.NodeInfoCaptchaFeature

The human captcha (hCaptcha) configuration.

email: bool

Whether email verification is enabled.

invite_only: bool

Whether the server is invite only.

january: luster.types.node_info.NodeInfoJanuaryFeature

The proxy service configuration.

voso: luster.types.node_info.NodeInfoVosoFeature

The voice server configuration.

NodeInfoCaptchaFeature

class luster.types.NodeInfoCaptchaFeature

Represents the hCaptcha configuration found in NodeInfoFeatures.captcha field.

enabled: bool

Whether human captcha is enabled.

key: str

The client key used for solving the captcha.

NodeInfoAutumnFeature

class luster.types.NodeInfoAutumnFeature

Represents the configuration for Autumn file server found in NodeInfoFeatures.autumn field.

enabled: bool

Whether the service is enabled.

url: str

The URL pointing to this service.

NodeInfoJanuaryFeature

class luster.types.NodeInfoJanuaryFeature

Represents the configuration for January proxy service configuration found in NodeInfoFeatures.january field.

enabled: bool

Whether the service is enabled.

url: str

The URL pointing to this service.

NodeInfoVosoFeature

class luster.types.NodeInfoVosoFeature

Represents the configuration for Voso voice service configuration found in NodeInfoFeatures.voso field.

enabled: bool

Whether the service is enabled.

url: str

The URL pointing to this service.

User

class luster.types.User

Represents a user’s structure.

avatar: NotRequired[Optional[File]]

The user’s avatar.

badges: NotRequired[Optional[int]]

The bitfield value for user profile badges.

bot: NotRequired[Optional[PartialUserBot]]

If the user is a bot, includes the partial bot information.

flags: NotRequired[Optional[int]]

The enum of user’s flags.

online: NotRequired[Optional[bool]]

Whether the user is currently online.

privileged: bool

Whether this user is privileged.

profile: NotRequired[Optional[Profile]]

The user’s profile.

relations: NotRequired[Optional[List[Relationship]]]

The user’s relationships with other users.

relationship: NotRequired[Optional[RelationshipStatus]]

The user’s relationship with other users or themselves.

status: NotRequired[Optional[Status]]

The user’s current activity status.

username: str

The user’s username.

Status

class luster.types.Status

Represents the status of a user.

presence: NotRequired[Optional[PresenceType]]

The current presence state of the user.

text: NotRequired[Optional[str]]

The custom status text.

Profile

class luster.types.Profile

Represents the profile of a user.

background: typing_extensions.NotRequired[Optional[luster.types.file.File]]

The custom banner background of user.

content: typing_extensions.NotRequired[Optional[str]]

The user’s bio.

PartialUserBot

class luster.types.PartialUserBot

Represents a “partial” bot attached to User.bot

owner: str

The ID of bot’s owner.

Relationship

class luster.types.Relationship

Represents a relationship of a user with another user.

status: RelationshipStatus

The current relationship status.

Server

class luster.types.Server

Represents a server.

analytics: typing_extensions.NotRequired[bool]

Whether analytics are enabled for this server.

banner: typing_extensions.NotRequired[Optional[luster.types.file.File]]

The banner of this server.

categories: typing_extensions.NotRequired[Optional[List[luster.types.channels.Category]]]

The list of categories in this server.

channels: List[str]

The list of IDs of channels in this server.

default_permissions: int

Default permissions bitfield for server and channels.

description: typing_extensions.NotRequired[Optional[str]]

The description of server.

discoverable: typing_extensions.NotRequired[bool]

Whether this server is discoverable.

flags: typing_extensions.NotRequired[Optional[int]]

The enum for server flags.

icon: typing_extensions.NotRequired[Optional[luster.types.file.File]]

The icon of this server.

name: str

The name of server.

nsfw: typing_extensions.NotRequired[bool]

Whether this server is marked as NSFW.

owner: str

The ID of user who owns the server.

roles: Dict[str, luster.types.roles.Role]

The server roles, the key is ID of role with value being the role.

system_messages: typing_extensions.NotRequired[Optional[luster.types.servers.SystemMessages]]

The system messages channels in this server.

SystemMessages

class luster.types.SystemMessages

Represents the system messages channels in a Server.

user_banned: typing_extensions.NotRequired[Optional[str]]

The ID of channel in which message is sent when a user is banned.

user_joined: typing_extensions.NotRequired[Optional[str]]

The ID of channel in which message is sent when a user joins.

user_kicked: typing_extensions.NotRequired[Optional[str]]

The ID of channel in which message is sent when a user is kicked.

user_left: typing_extensions.NotRequired[Optional[str]]

The ID of channel in which message is sent when a user leaves.

Category

class luster.types.Category

Represents a category for other channels.

channels: List[str]

The list of IDs for channels that are in this category.

id: str

The ID of this category.

title: str

The title of this category.

Role

class luster.types.Role

Represents a role in a server.

colour: typing_extensions.NotRequired[Optional[str]]

The color of this role, this can be any valid CSS color.

hoist: typing_extensions.NotRequired[bool]

Whether this role is hoisted.

name: str

The name of this role.

permissions: luster.types.roles.Permissions

The permissions of this role.

rank: typing_extensions.NotRequired[int]

The ranking of this role in hierarchy.

Permissions

class luster.types.Permissions

Represents the permission mapping with allow and deny keys.

a: int

The bitwise value for allowed permissions.

d: int

The bitwise for denied permissions.

SavedMessages

class luster.types.SavedMessages

Represents a channel type for saving messages, known as “Saved Notes” in the UI.

channel_type: Literal['SavedMessages']

The type of this channel.

user: str

The user that this channel belongs to.

DirectMessage

class luster.types.DirectMessage

Represents a direct message between two users.

active: bool

Whether this channel is active on both sides.

channel_type: Literal['DirectMessage']

The type of this channel.

last_message_id: typing_extensions.NotRequired[Optional[str]]

The ID of last message sent in this channel.

recipients: List[str]

An array with two elements representing IDs of users included in this channel.

Group

class luster.types.Group

Represents a group channel between two or more users.

channel_type: Literal['Group']

The type of this channel.

description: typing_extensions.NotRequired[Optional[str]]

The description of this group.

icon: typing_extensions.NotRequired[Optional[luster.types.file.File]]

The icon of this group.

last_message_id: typing_extensions.NotRequired[Optional[str]]

The ID of last message sent in this channel.

name: str

The name of this group.

nsfw: bool

Whether this group is marked as NSFW.

owner: str

The ID of user who owns this group.

permissions: int

The permissions assigned to members of this group except owner.

recipients: List[str]

An array of IDs of users included in this channel.

TextChannel

class luster.types.TextChannel

Represents a text channel in a server.

channel_type: Literal['TextChannel']

The type of this channel.

last_message_id: typing_extensions.NotRequired[Optional[str]]

The ID of last message sent in this channel.

VoiceChannel

class luster.types.VoiceChannel

Represents a voice channel in a server.

channel_type: Literal['VoiceChannel']

The type of this channel.

ServerChannel

luster.types.ServerChannel

A type alias for typing.Union of various Server channels.

This currently includes:

• TextChannel

• VoiceChannel

PrivateChannel

luster.types.PrivateChannel

A type alias for typing.Union of various private channel types.

This currently includes:

• SavedMessages

• DirectMessages

• Group

Channel

luster.types.Channel

A type alias for typing.Union of all channel types mentioned above.

HTTP Routes

This section documents type definitions for various HTTP routes. All these type definitions are subclasses of typing.TypedDict.

QueryNodeResponse

class luster.types.QueryNodeResponse

Represents the response of HTTPHandler.query_node() or HTTPHandler.fetch_node_info() route.

This is equivalent to NodeInfo.

FetchSelfResponse

class luster.types.FetchSelfResponse

Represents the response for HTTPHandler.fetch_self() route.

This is equivalent to User.

EditUserJSON

class luster.types.EditUserJSON

Represents the JSON body for HTTPHandler.edit_user() route.

avatar: NotRequired[str]

The attachment ID for new avatar.

profile: NotRequired[Profile]

The payload to change the user profile.

remove: NotRequired[List[UserRemoveField]]

The list of fields to remove from user.

status: NotRequired[Status]

The payload to change the status.

EditUserResponse

class luster.types.EditUserResponse

Represents the response for HTTPHandler.edit_user() route.

This is equivalent to User.

FetchUserResponse

class luster.types.FetchUserResponse

Represents the response for HTTPHandler.fetch_user() route.

This is equivalent to User.

ChangeUsernameJSON

class luster.types.ChangeUsernameJSON

Represents the JSON body for HTTPHandler.change_username() route.

password: str

The current account password.

username: str

The new username

ChangeUsernameResponse

class luster.types.ChangeUsernameResponse

Represents the response for HTTPHandler.change_username() route.

This is equivalent to User.

FetchProfileResponse

class luster.types.FetchProfileResponse

Represents the response for HTTPHandler.fetch_profile() route.

This is equivalent to Profile.

UploadFileResponse

class luster.types.UploadFileResponse

Represents the response of HTTPHandler.upload_file().

id: str

The ID of uploaded file.

CreateServerJSON

class luster.types.CreateServerJSON

Represents the JSON body for luster.HTTPHandler.create_server() route.

description: typing_extensions.NotRequired[Optional[str]]

The description of server.

name: str

The name of server.

nsfw: typing_extensions.NotRequired[bool]

Whether to mark server as NSFW.

CreateServerResponse

class luster.types.CreateServerResponse

Represents the response for luster.HTTPHandler.create_server() route.

channels: List[Union[luster.types.channels.TextChannel, luster.types.channels.VoiceChannel]]

The server’s channels.

server: luster.types.servers.Server

The created server.

FetchServerResponse

class luster.types.FetchServerResponse

Represents the response for luster.HTTPHandler.fetch_server() route.

This is equivalent to Server type.

EditServerJSON

class luster.types.EditServerJSON

Represents the JSON body for luster.HTTPHandler.edit_server() route.

analytics: bool

Whether to enable or disable analytics data.

banner: str

The attachment ID for server’s banner.

categories: List[Category]

The channel categories in this server.

description: str

The description of server.

icon: str

The attachment ID for server’s icon.

name: str

The name of server.

remove: List[ServerRemoveField]

The fields to remove from server object.

system_messages: SystemMessages

The system message channels in this server.

EditServerResponse

class luster.types.EditServerResponse

Represents the response for luster.HTTPHandler.edit_server() route.

This is equivalent to Server type.

DeleteServerResponse

luster.types.DeleteServerResponse

A type alias representing response of luster.HTTPHandler.delete_server() route.

MarkServerAsReadResponse

luster.types.MarkServerAsReadResponse

A type alias representing response of luster.HTTPHandler.mark_server_as_read() route.

CreateServerChannelJSON

class luster.types.CreateServerChannelJSON

Represents the JSON body for luster.HTTPHandler.create_server_channel() route.

channel_type: NotRequired[ChannelTypeServer]

Text).

Type

The type of channel to create (default

description: NotRequired[Optional[str]]

The description/topic of channel.

name: str

The name of channel.

nsfw: NotRequired[bool]

Whether to mark channel as NSFW.

CreateServerChannelResponse

luster.types.CreateServerChannelResponse

A type alias representing response of luster.HTTPHandler.create_server_channel() route.

FetchDirectMessageChannelsResponse

luster.types.FetchDirectMessageChannelsResponse

A type alias representing the response of luster.HTTPHandler.fetch_direct_message_channels() route.

This is equivalent to typing.List of DirectMessage and Group.

OpenDirectMessageResponse

luster.types.OpenDirectMessageResponse

A type alias representing the response of luster.HTTPHandler.open_direct_message() route.

This is equivalent to typing.Union of DirectMessage and SavedMessages.

FetchChannelResponse

luster.types.FetchChannelResponse

A type alias representing the response of luster.HTTPHandler.fetch_channel() route.

This is equivalent to Channel.

DeleteChannelResponse

luster.types.DeleteChannelResponse

A type alias representing the response of luster.HTTPHandler.close_channel() route.

This is equivalent to Literal[None].

EditChannelJSON

class luster.types.EditChannelJSON

Represents the JSON body for luster.HTTPHandler.edit_channel() route.

description: NotRequired[str]

The description of channel.

icon: NotRequired[str]

The attachment ID for channel icon.

name: NotRequired[str]

The name of channel.

nsfw: NotRequired[bool]

Whether to mark the channel as NSFW.

remove: NotRequired[List[ChannelRemoveField]]

The list of fields to remove.

EditChannelResponse

luster.types.EditChannelResponse

A type alias representing the response of luster.HTTPHandler.edit_channel() route.

This is equivalent to Channel.

CreateGroupJSON

class luster.types.CreateGroupJSON

Represents the JSON body for luster.HTTPHandler.create_group() route.

description: typing_extensions.NotRequired[Optional[str]]

The description of group.

name: str

The name of group.

nsfw: typing_extensions.NotRequired[bool]

Whether this group is NSFW.

users: List[str]

The list of users to add to group.

CreateGroupResponse

class luster.types.CreateGroupResponse

Represents the response of luster.HTTPHandler.create_group() route.

This is equivalent to Group.

FetchGroupMembersResponse

luster.types.FetchGroupMembersResponse

A type alias representing the response of luster.HTTPHandler.fetch_group_members() route.

AddGroupMemberResponse

luster.types.AddGroupMemberResponse

A type alias representing the response of luster.HTTPHandler.add_group_member() route.

RemoveGroupMemberResponse

luster.types.RemoveGroupMemberResponse

A type alias representing the response of luster.HTTPHandler.remove_group_member() route.

SetChannelRolePermissionJSON

class luster.types.SetChannelRolePermissionJSON

Represents the JSON body for luster.HTTPHandler.set_channel_role_permission() route.

permissions: luster.types.roles.RequestPermissions

The new permissions for the role.

SetChannelRolePermissionResponse

luster.types.SetChannelRolePermissionResponse

A type alias representing the response of luster.HTTPHandler.set_channel_role_permission().

SetChannelDefaultPermissionJSON

class luster.types.SetChannelDefaultPermissionJSON

Represents the JSON body for luster.HTTPHandler.set_channel_default_permission() route.

permissions: luster.types.roles.RequestPermissions

The new permissions for the default role.

SetChannelDefaultPermissionResponse

luster.types.SetChannelDefaultPermissionResponse

A type alias representing the response of luster.HTTPHandler.set_channel_default_permission().

SetServerRolePermissionJSON

class luster.types.SetServerRolePermissionJSON

Represents the JSON body for luster.HTTPHandler.set_server_role_permission() route.

permissions: luster.types.roles.RequestPermissions

The new permissions.

SetServerRolePermissionResponse

luster.types.SetServerRolePermissionResponse

A type alias representing the response of luster.HTTPHandler.set_server_role_permission().

SetServerDefaultPermissionJSON

class luster.types.SetServerDefaultPermissionJSON

Represents the JSON body for lustr.HTTPHandler.set_server_default_permission() route.

permissions: int

The permissions bitwise value.

SetServerDefaultPermissionResponse

luster.types.SetServerDefaultPermissionResponse

A type alias representing the response of luster.HTTPHandler.set_server_default_permission().

Websocket Events

This section documents type definitions for various websocket events. All these type definitions are subclasses of typing.TypedDict.

AuthenticateEvent

class luster.types.AuthenticateEvent

Represents an event used for authenticating the session.

token: str

The token used for authentication.

type: Literal['Authenticate']

The type of event.

PingEvent

class luster.types.PingEvent

Represents an event used for pinging the websocket to keep the connection open.

data: int

The data to send and receive in Pong event.

type: Literal['Ping']

The type of event.

BeginTypingEvent

class luster.types.AuthenticateEvent

Represents an event used for authenticating the session.

token: str

The token used for authentication.

type: Literal['Authenticate']

The type of event.

EndTypingEvent

class luster.types.EndTypingEvent

Represents an event used for ending typing indicating in a channel.

channel_id: str

The channel ID to end typing indicator in.

type: Literal['EndTyping']

The type of event.

ErrorEvent

class luster.types.ErrorEvent

Represents an event indicating that an error happened.

error: ErrorId

The ID of error.

type: Literal['Error']

The type of event.

AuthenticatedEvent

class luster.types.AuthenticatedEvent

Represents an event indicating that session was authenticated.

type: Literal['Authenticated']

The type of event.

PongEvent

class luster.types.PongEvent

Represents an event indicating acknowledgment of Ping event.

data: int

The data sent during Ping.

type: Literal['Pong']

The type of event.

BulkEvent

class luster.types.BulkEvent

Represents an event indicating that multiple events occured.

type: Literal['Bulk']

The type of event.

v: List[luster.types.websocket.BaseWebsocketEvent]

The list of events that occured.

ReadyEvent

class luster.types.ReadyEvent

Represents an event indicating that client is ready.

channels: List[Union[luster.types.channels.TextChannel, luster.types.channels.VoiceChannel, luster.types.channels.SavedMessages, luster.types.channels.DirectMessage, luster.types.channels.Group]]

The list of channels.

emojis: typing_extensions.NotRequired[List[Any]]

The list of servers.

servers: List[luster.types.servers.Server]

The list of servers.

type: Literal['Ready']

The type of event.

users: List[luster.types.users.User]

The list of users the client can see.

UserUpdateEvent

class luster.types.UserUpdateEvent

Represents an event indicating that a user was updated.

data: UserUpdateEventData

The fields that were updated.

id: str

The ID of user that was updated.

type: Literal['UserUpdate']

The type of event.

UserUpdateEventData

class luster.types.UserUpdateEventData

Represents the data inside a UserUpdateEvent.

This is equivalent to a “partial” user. All the fields in this type are optional.

avatar: luster.types.file.File

The avatar of this user.

badges: Optional[int]

The user’s badges.

flags: Optional[int]

The user’s flags.

online: bool

Whether this user is online.

privileged: bool

Whether this user is privileged.

profile: luster.types.users.Profile

The profile of this user.

status: luster.types.users.Status

The user’s current status.

username: str

The username of user.

UserRelationshipEvent

class luster.types.UserRelationshipEvent

Represents an event indicating update of relationship with another user.

id: str

The ID of your user.

status: RelationshipStatus

The new relationship status.

type: Literal['UserRelationship']

The type of event.

user: User

The user with which relationship has changed.

This user object represents the user before the relationship status has been updated.

ServerCreateEvent

class luster.types.ServerCreateEvent

Represents an event indicating creation/joining of a server.

channels: List[Union[luster.types.channels.TextChannel, luster.types.channels.VoiceChannel]]

The channels of this server.

id: str

The ID of joined server.

server: luster.types.servers.Server

The joined server.

type: Literal['ServerCreate']

The type of event.

ServerUpdateEvent

class luster.types.ServerUpdateEvent

Represents an event indicating update of a server.

data: ServerUpdateEventData

The partial server object representing the details that were updated.

id: str

The ID of server that was updated.

type: Literal['ServerUpdate']

The type of event.

ServerUpdateEventData

class luster.types.ServerUpdateEventData

Represents the data inside a ServerUpdateEvent.

This is equivalent to a “partial” server. All the fields in this type are optional.

analytics: bool

Whether analytics are enabled for this server.

banner: luster.types.file.File

The banner of server.

categories: List[luster.types.channels.Category]

The categories of server.

channel_ids: List[str]

The list of IDs of channels in this server.

description: str

The description of server.

discoverable: bool

Whether this server is discoverable.

icon: luster.types.file.File

The icon of user.

name: str

The name of user.

nsfw: bool

Whether this server is marked as NSFW.

system_messages: luster.types.servers.SystemMessages

The channel assignments for system messages in the server.

ServerDeleteEvent

class luster.types.ServerDeleteEvent

Represents an event indicating deletion/leaving of a server.

id: str

The ID of server that was deleted/left.

type: Literal['ServerDelete']

The type of event.

ChannelCreateEvent

class luster.types.ChannelCreateEvent

Represents an event indicating creation of a channel.

channel_type: str

The type of created channel.

type: Literal['ChannelCreate']

The type of event.

ChannelUpdateEvent

class luster.types.ChannelUpdateEvent

Represents an event indicating update of a channel.

data: ChannelUpdateEventData

The updated data.

id: str

The ID of channel.

type: Literal['ChannelCreate']

The type of event.

ChannelUpdateEventData

class luster.types.ChannelUpdateEventData

Represents the updated data in a ChannelUpdateEvent.

active: bool

Whether this channel is active on both sides.

default_permissions: luster.types.roles.Permissions

The default permissions for this channel.

description: Optional[str]

The description of channel.

icon: Optional[luster.types.file.File]

The icon of channel.

name: str

The name of channel.

nsfw: bool

Whether this group is marked as NSFW.

recipients: List[str]

An array of IDs of users included in this channel.

role_permissions: Dict[str, luster.types.roles.Permissions]

A mapping with key being role ID and value being role Permissions.

ChannelDeleteEvent

class luster.types.ChannelDeleteEvent

Represents an event indicating deletion of a channel.

id: str

The deleted channel’s ID.

type: Literal['ChannelDelete']

The type of event.

ChannelGroupJoinEvent

class luster.types.ChannelGroupJoinEvent

Represents an event indicating a user joining a group.

id: str

The ID of channel.

type: Literal['ChannelGroupJoin']

The type of event.

user: str

The ID of user that joined.

ChannelGroupLeaveEvent

class luster.types.ChannelGroupLeaveEvent

Represents an event indicating a user leaving a group.

id: str

The ID of channel.

type: Literal['ChannelGroupLeave']

The type of event.

user: str

The ID of user that left.

ServerRoleUpdateEvent

class luster.types.ServerRoleUpdateEvent

Represents an event indicating update of a server role.

data: ServerRoleUpdateEventData

The updated data.

id: str

The ID of server for which the role is updated.

role_id: str

The ID of role.

type: Literal['ServerRoleUpdate']

The type of event.

ServerRoleUpdateEventData

class luster.types.ServerRoleUpdateEventData

Represents the data of ServerRoleUpdateEvent.

This is roughly equivalent to a role but all fields are optional.

color: str

The color for this role in any CSS compliant format.

hoist: bool

Whether the role is shown separate from others.

name: str

The name of role.

permissions: luster.types.roles.Permissions

The permissions of role.

rank: int

The rank of role.

ServerRoleDeleteEvent

class luster.types.ServerRoleDeleteEvent

Represents an event indicating deletion of a server role.

id: str

The ID of server for which the role is deleted.

role_id: str

The ID of role.

type: Literal['ServerRoleDelete']

The type of event.