From e1b14d80146a35eca603128b23c1c7e8aed3252e Mon Sep 17 00:00:00 2001 From: Bilal2453 Date: Sun, 1 Dec 2024 11:07:54 +0300 Subject: [PATCH] pre-release for 2.0.0 --- CHANGELOG.md | 30 ++++++++++++++++++++++++++++++ README.md | 29 +++++++++++++++++++++++++++-- libs/containers/Interaction.lua | 1 + package.lua | 4 ++-- 4 files changed, 60 insertions(+), 4 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..e70a9cb --- /dev/null +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index 1e6dfac..f70c7b6 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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") @@ -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! diff --git a/libs/containers/Interaction.lua b/libs/containers/Interaction.lua index 66dd837..939295c 100644 --- a/libs/containers/Interaction.lua +++ b/libs/containers/Interaction.lua @@ -65,6 +65,7 @@ local getter = get ---@param data table ---@param parent Client ---@protected +--- function Interaction:__init(data, parent) Snowflake.__init(self, data, parent) self._data = data.data diff --git a/package.lua b/package.lua index ec77712..7169def 100644 --- a/package.lua +++ b/package.lua @@ -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 = "belal2453@gmail.com" }, + author = { name = "Bilal2453", email = "belal2453@gmail.com" }, homepage = "https://github.com/Bilal2453/discordia-interactions", dependencies = { "SinisterRectus/discordia", }, files = {