Skip to content

Commit

Permalink
pre-release for 2.0.0
Browse files Browse the repository at this point in the history
  • Loading branch information
Bilal2453 committed Dec 1, 2024
1 parent 048c30b commit a15cf0b
Show file tree
Hide file tree
Showing 3 changed files with 59 additions and 4 deletions.
30 changes: 30 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Changelog

## 2.0.0

- More stable returns on `Interaction.reply` initial replies. (Commit 2b559fa)
- Add `interactionContextType` and `applicationIntegrationType` enumerators. (Commit 2b559fa)
- Add new getters: `appPermissions`, `entitlements`, `context` and `integrationOwners`. (Commits 2b559fa, 696b70d)
- Add a post-listener for `interactionCreate`, at `discordia_interactions.EventHandler.interaction_create_postlisteners`. (Commit 048c30b)
- **Breaking Change**: Partial objects are now used for `Guild`, `Channel` and `Member`, no fetching is done behind the scene anymore. (Commits 5a9180e, 696b70d)
- **Breaking Change**: `Interaction.replyDeferred` may now return a Message when `self.channel` is available. (Commit 2b559fa)
- **Breaking Change**: Remove the support for a non-array input to `Interaction.autocomplete`. (Commit 2b559fa)
- Fix `Interaction.editReply` when ID is not provided. (Commit 2b559fa)
- Fix the autocomplete resolver using the wrong wrapper table.

## 1.2.1

- Add support for interactions invoked in `GuildVoiceChannel` instances. (Commit 8832674)
- Fix fetching issue on Guild caches. (Commit 8832674)
- Fix attempts to index nil `self._channel` property. (Commit a9be099)
- Fix `self._message` being `false` instead of `nil` on fetching failure. (Commit d0f95f5)
- Fix inserting a nil Guild instance into cache when fetching fails. (Commit bfd410e)
- Fix message flags being ignored if it had some flags already set. (Commit af32efc)

## 1.1.0

- Add pre-listeners to EventHandler, allowing other extension authors to interact with the library.
- Add an assert instead of returning nil when resolving.
- Add the ability to wrap resolvers by other extensions to allow further user input.
- Add support for modal responses.
- Expose our internal EventHandler instance.
29 changes: 27 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Introduction

discordia-interactions is an extension library that enables [Discordia](https://github.com/SinisterRectus/discordia) to receive and respond to [Discord Interactions](https://discord.com/developers/docs/interactions/receiving-and-responding#interaction-response-object-interaction-callback-type).
This is done over the gateway websocket connection [Discordia](https://github.com/SinisterRectus/discordia) offers, and aims to be very extensible so other extensions and libraries can build upon without having to worry about compatibility with each other.
This is done over the gateway websocket connection that [Discordia](https://github.com/SinisterRectus/discordia) offers, and aims to be very extensible so other extensions and libraries can build upon without having to worry about compatibility with each other.

This only implements the interactions portion, for App commands such as Message Components or Slash Commands you need to use a second extension library alongside this one, for example [discordia-components](https://github.com/Bilal2453/discordia-components/) adds support for Message Components such as buttons and select menus.

Expand Down Expand Up @@ -32,9 +32,29 @@ The library is fully documented over at the [Wiki](https://github.com/Bilal2453/
This library offers multiple wrapping stages for other libraries to integrate with, allowing you to control the data flow and hook at different stages. For example I built a little Slash command library for the [Discordia Wiki bot](https://github.com/Bilal2453/discordia-wiki-bot), and [this is](https://github.com/Bilal2453/discordia-wiki-bot/blob/da42b124646bc718e17db89fac0c15456da4520f/libs/slash.lua#L140-L144) how it hooks into discordia-interactions to implement a new `slashCommand` event.
You can hook an `interactionCreate` event pre-listener, resolve user inputs to Interaction methods with your own resolver, or wrap resolved values.

## Deprecation form Discordia

When using a library, you make a contract with that library, it's that what it documents is what it will do. In Discordia for example when the wiki says
that `Guild.memberCount` is never `nil`, then you can simply trust that and never check whether the property is nil or not, because Discordia guarantees that as part of the contract it made with you.

By using any third-party extension, said contract is automatically broken. (Note: So is modifying the library internally, the same arguments can be made against any method of modifying the library! not just extensions.)

One thing that Discord broke their promises with are Partial Objects. Partial objects are normal objects but with almost none of the required properties that Discordia promises you to always have, for example `Guild.memberCount` is `nil` because Discord does not send that on partial objects. It only sends the bare minimum that represents what a thing is, Guild is for example only getting the guild ID and supported features.

Pre 2.0.0 versions tried to keep that oauth with the user by selling its soul to the devil and transparently request partial objects from the API gateway to get full ones, breaking one of the most important design philosophies of Discordia but keeping the user away from the complexity Discord introduced with partial objects.

Sadly, when Discord introduced User Installed Apps, this is no more possible to keep, because in those contexts *we cannot request objects from the API*, as they are pretty much kept a secret and only the minimum amount of information is provided, as such starting from version 2.0.0, the library breaks this contract and makes a new one with you: Any object obtained by an Interaction is partial and most likely *WILL NOT* have all of the properties set; if you want the full object request it from the API, or otherwise operate with those objects with caution.

The partial objects more specifically are `Guild`, `Channel` and `Member`. They are cached by Discordia, so iterating the Discordia cache might get you one of them, when the full version is given by Discord (if at all) then cached version is updated with the full one.
You may check if a Guild instance is partial by checking `Guild._partial` (you may only check Guild).

This change sadly adds complexity to the user, but it was absolutely required in order to support User Installed Apps and continue with the development.

## Examples

Here is a simple example that gets executed when you click a button or invoke the interaction in other means.
**Take a look at the [[examples]] directory.**

Here is a bit of a usage run down:

```lua
local discordia = require("discordia")
Expand Down Expand Up @@ -77,3 +97,8 @@ client:run("Bot TOKEN")
## Developers Notes

While it is not hard to merge this into Discordia, you are discouraged from doing that. From what I have noticed multiple people are merging this into the Discordia code instead of just using the extensions, and while they might have some reasons to do that, it will make life a lot harder for maintainability, for example when a new discordia-interactions release comes out it will become pretty much a manual job to hand pick the patches to apply, and it creates *more* incompatibility instead of solving any, this is *EXPLICITLY* an extension for good reasons, otherwise I could've simply PRed this into Discordia and called it a day, which is a lot easier to me than doing this.

### License

This project is licensed under the Apache License 2.0, see [LICENSE] for more information.
Make sure to include the original copyright notice when copying!
4 changes: 2 additions & 2 deletions package.lua
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
return {
name = "Bilal2453/discordia-interactions",
version = "1.2.1",
version = "2.0.0",
description = "A Discordia library extension that enables receiving and responding to Discord's Interactions.",
tags = { "discord", "discordia", "interactions" },
license = "Apache License 2.0",
author = { name = "Bilal Bassam", email = "[email protected]" },
author = { name = "Bilal2453", email = "[email protected]" },
homepage = "https://github.com/Bilal2453/discordia-interactions",
dependencies = { "SinisterRectus/discordia", },
files = {
Expand Down

0 comments on commit a15cf0b

Please sign in to comment.