Nyxx Discord API Wrapper

The nyxx ecosystem includes several specialized packages to extend your bot's functionality:

• nyxx_commands: A command framework for handling both simple & complex commands.
• nyxx_extensions: Provides pagination, emoji utilities, and other miscellaneous helpers.
• nyxx_lavalink: Provides Lavalink support for playing audio in voice channels.

In Nyxx, the API is structured around three interconnected concepts:

1. Entities: Classes representing API structures (often subclasses of SnowflakeEntity). They contain structured data and provide convenience methods that act on that data. Many entity methods are shortcuts to corresponding Manager methods.
2. Managers: Specialized objects that contain the logic for parsing related Models and provide the actual Dart APIs for interacting with Discord endpoints.
3. Models: Immutable structures containing data returned by the API.

Key Behavior: Immutability Entities are immutable. Methods that appear to 'update' an entity (such as WritableSnowflakeEntity.update) do not modify the existing instance. Instead, they return a new instance containing the updated data. You must use the returned instance for any subsequent operations.

The ApplicationCommandBuilder is a shared builder used for different types of commands (Chat, User, or Message commands). The specific behavior is determined by the ApplicationCommandBuilder.type field.

Because certain fields are only compatible with specific command types, you should use the provided named constructors instead of the default constructor. These named constructors ensure that only the allowed fields for that specific command type are accessible, preventing invalid API requests.

Builders in Nyxx follow a predictable naming convention based on the model they correspond to:

• CreateBuilder: Named as {Model}Builder (e.g., GuildCreateBuilder).
• UpdateBuilder: Named as {Model}UpdateBuilder (e.g., GuildUpdateBuilder).

The type argument used in the builder (e.g., Builder<Model>) indicates which model the builder is intended to produce. Note that some builders are "upload-only" and do not correspond to a specific model; in these cases, the builder uses itself as its own type argument.

Events received from Discord's Gateway API fall into two categories:

1. Session State Events (GatewayEvent subclasses): These are primarily used by nyxx internally to manage the connection. You can listen to them via Gateway.messages by looking for EventReceived events.
2. State Change Events (DispatchEvent subclasses): These represent actual data changes in Discord, such as a new Message being created or a User updating their Activity.

To listen for DispatchEvents, you should use:

• The Gateway.events stream.
• Or the event-specific convenience streams provided on NyxxGateway (e.g., client.onXXXEvent).

Note: The Gateway.messages stream only emits RawDispatchEvents that have not yet been parsed into high-level objects.

Managers are the primary interface for interacting with Discord's HTTP endpoints. They act as a bridge between the raw Discord API and your Dart code by providing:

1. Deserialization: Converting JSON responses from Discord into typed [Models].
2. API Wrappers: Providing Dart methods that correspond to specific Discord HTTP endpoints.
3. Caching: Managing local [Cache]s for the [Entities] they oversee.

Managers are typically organized around specific [Entity] types (e.g., a Guild Manager for Guild entities), though some may simply group related endpoints together.

A partial entity is a lightweight reference to an entity that contains only its ID. You can use a partial entity to call methods that only require an ID (like fetching related resources) without performing a full GET request to fetch the entity's complete model first.

To create a partial entity, use the [] operator on a Manager and provide the entity's Snowflake ID.

To convert a partial entity into a full model (fetching the complete data from the API), use the .get() method on the partial entity.

// Accessing a partial Guild to fetch its channels without fetching the Guild model first
client.guilds[GUILD_ID].fetchChannels();

// To get the full Guild model from the partial entity:
// client.guilds[GUILD_ID].get();

To create a custom plugin, create a subclass of NyxxPlugin and specify the type of client it is compatible with using the type parameter.

If your plugin requires state that is unique to each client instance, you should:

1. Create a subclass of NyxxPluginState to hold that state.
2. Override NyxxPlugin.createState to return an instance of your state subclass.

You can then override methods in both NyxxPlugin and NyxxPluginState to execute logic at specific points in the client's lifecycle, such as intercepting HTTP requests or Gateway events.

Nyxx uses builders to construct models that are serialized and sent to the Discord API. Builders generally fall into two categories:

1. CreateBuilders: Used for creating new instances. These often contain required fields that must be provided to successfully create the entity.
2. UpdateBuilders: Used to update existing instances. These generally consist of optional fields, allowing you to modify only specific parts of an entity.

Builders are typically named after the [Model] they represent. For example, a UserCreateBuilder would be used to create a user, while a UserUpdateBuilder would be used to update one.