lib_discord 0.1.0.pre2 → 0.1.1

data/README.md

@@ -0,0 +1,122 @@
+# lib_discord
+
+[project]: https://sr.ht/~komidore64/lib_discord
+[sources]: https://sr.ht/~komidore64/lib_discord/sources
+[mailing lists]: https://sr.ht/~komidore64/lib_discord/lists
+[bug tracker]: https://todo.sr.ht/~komidore64/lib_discord
+
+Unfancy Ruby-bindings to interact with Discord's HTTPS/REST web API.
+
+[project] -- [sources] -- [mailing lists] -- [bug tracker]
+
+[![builds.sr.ht status](https://builds.sr.ht/~komidore64/lib_discord/commits/main/.build.yml.svg)](https://builds.sr.ht/~komidore64/lib_discord/commits/main/.build.yml)
+[![Gem Version](https://badge.fury.io/rb/lib_discord.svg)](https://rubygems.org/gems/lib_discord)
+
+## Installation
+
+`lib_discord` requires an installed [Ruby runtime](https://www.ruby-lang.org/)
+`>= 3.2`.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```sh
+bundle add lib_discord
+```
+
+If bundler is not being used to manage dependencies, install the gem by
+executing:
+
+```sh
+gem install lib_discord
+```
+
+## Usage
+
+```ruby
+require "lib_discord"
+client = LibDiscord::Client.new("Bot my.amazing.bot.token")
+```
+
+Access resource types with `#[]` syntax:
+
+```ruby
+client.keys
+# =>
+# ["application",
+#  "application_command",
+#  "application_role_connection_metadata",
+#  "audit_log",
+#  "auto_moderation",
+#  "channel",
+#  "emoji",
+#  "guild",
+#  "guild_scheduled_event",
+#  "guild_template",
+#  "interaction",
+#  "invite",
+#  "poll",
+#  "stage_instance",
+#  "sticker",
+#  "user",
+#  "voice",
+#  "webhook"]
+
+client["application"]
+# => #<LibDiscord::Application: ... >
+```
+
+Use resources to make requests to Discord's API. LibDiscord resources are
+mapped to the "Resources" described in [Discord's developer documentation].
+
+```ruby
+resp = client["guild"].get_guild_channels(guild_id: "12345678901234567890")
+
+resp.code
+# => 200
+
+resp.headers
+# => Hash of HTTP response headers
+
+resp.body_parsed
+# => JSON body deserialized to a Hash
+
+resp.body_raw
+# => raw response body in String form
+```
+
+[Discord's developer documentation]: https://discord.com/developers/docs
+
+## Getting help
+
+Please use the [mailing lists] if you have questions or need help.
+
+## Contributing
+
+Bug reports and patch submissions are welcome on SourceHut via the [bug
+tracker] and [mailing lists], respectively. This project is intended to be a
+safe, welcoming space for collaboration, and contributors are expected to
+adhere to the [code of conduct].
+
+[code of conduct]: https://git.sr.ht/~komidore64/lib_discord/tree/main/item/CODE_OF_CONDUCT.md
+
+### Code style
+
+This project adheres to [Standard Ruby] style rules.
+
+Additionally, we strive for an 80 character line length, but it's not a
+hard-and-fast rule. There are occasions where breaking an expression across
+multiple lines decreases readability for no benefit other than to appease a
+linter. As such, there is no tool to enforce it. 
+
+[Standard Ruby]: https://github.com/standardrb/standard
+
+## Code of Conduct
+
+Everyone interacting in the `lib_discord` project's codebase, bug trackers,
+chat rooms, and mailing lists is expected to follow the [code of conduct].
+
+## Licenses
+
+See files in the [LICENSES] directory.
+
+[LICENSES]: https://git.sr.ht/~komidore64/lib_discord/tree/main/item/LICENSES/

data/lib/lib_discord/application.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "lib_discord/resource"
+
+module LibDiscord
+  ##
+  # Application Resource
+  #
+  # Do not instantiate an {Application} directly. Instead request one from an
+  # instance of {Client}.
+  #
+  #   client = LibDiscord::Client.new("Bot auth.token")
+  #   a = client["application"]
+  #
+  # @see https://discord.com/developers/docs/resources/application Discord
+  #   documentation "Application Resource"
+  class Application < Resource
+    ##
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/resources/application#get-current-application
+    #   Discord documentation "Get Current Application"
+    def get_current_application
+      send_request(:get, "/applications/@me")
+    end
+
+    ##
+    # @param json [Hash] JSON serializable payload
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/resources/application#edit-current-application
+    #   Discord documentation "Edit Current Application"
+    def edit_current_application(json:)
+      send_request(:patch, "/applications/@me", json:)
+    end
+  end
+end

data/lib/lib_discord/application_command.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require "lib_discord/resource"
+
+module LibDiscord
+  ##
+  # Application Commands
+  #
+  # Do not instantiate an {ApplicationCommand} directly. Instead request one
+  # from an instance of {Client}.
+  #
+  #   client = LibDiscord::Client.new("Bot auth.token")
+  #   a = client["application_command"]
+  #
+  # @see https://discord.com/developers/docs/interactions/application-commands
+  #   Discord documentation "Application Commands"
+  # @see https://discord.com/developers/docs/interactions/application-commands#permissions
+  #   Discord documentation "Permissions"
+  class ApplicationCommand < Resource
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param params [Hash] optional HTTP query parameters
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +params+ cannot be coerced into a valid query
+    #   parameters string
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#get-global-application-commands
+    #   Discord documentation "Get Global Application Commands"
+    def get_global_application_commands(application_id:, params: {})
+      send_request(:get, "/applications/#{application_id}/commands", params:)
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param json [Hash] JSON serializable payload
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#create-global-application-command
+    #   Discord documentation "Create Global Application Command"
+    def create_global_application_command(application_id:, json:)
+      send_request(:post, "/applications/#{application_id}/commands", json:)
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param command_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#get-global-application-command
+    #   Discord documentation "Get Global Application Command"
+    def get_global_application_command(application_id:, command_id:)
+      send_request(:get, "/applications/#{application_id}/commands/#{command_id}")
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param command_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param json [Hash] JSON serializable payload
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#edit-global-application-command
+    #   Discord documentation "Edit Global Application Command"
+    def edit_global_application_command(application_id:, command_id:, json:)
+      send_request(:patch, "/applications/#{application_id}/commands/#{command_id}", json:)
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param command_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#delete-global-application-command
+    #   Discord documentation "Delete Global Application Command"
+    def delete_global_application_command(application_id:, command_id:)
+      send_request(:delete, "/applications/#{application_id}/commands/#{command_id}")
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param json [Hash]
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#bulk-overwrite-global-application-commands
+    #   Discord documentation "Bulk Overwrite Global Application Commands"
+    def bulk_overwrite_global_application_commands(application_id:, json:)
+      send_request(:put, "/applications/#{application_id}/commands", json:)
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param params [Hash] optional HTTP query parameters
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times outs
+    # @raise [ConstraintError] if +params+ cannot be coerced into a valid query
+    #   parameters string
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#get-guild-application-commands
+    #   Discord documentation "Get Guild Application Commands"
+    def get_guild_application_commands(application_id:, guild_id:, params: {})
+      send_request(:get, "/applications/#{application_id}/guilds/#{guild_id}/commands", params:)
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param json [Hash]
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#create-guild-application-command
+    #   Discord documentation "Create Guild Application Command"
+    def create_guild_application_command(application_id:, guild_id:, json:)
+      send_request(:post, "/applications/#{application_id}/guilds/#{guild_id}/commands", json:)
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param command_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#get-guild-application-command
+    #   Discord documentation "Get Guild Application Command"
+    def get_guild_application_command(application_id:, guild_id:, command_id:)
+      send_request(:get, "/applications/#{application_id}/guilds/#{guild_id}/commands/#{command_id}")
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param command_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param json [Hash]
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#edit-guild-application-command
+    #   Discord documentation "Edit Guild Application Command"
+    def edit_guild_application_command(application_id:, guild_id:, command_id:, json:)
+      send_request(:patch, "/applications/#{application_id}/guilds/#{guild_id}/commands/#{command_id}", json:)
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param command_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#delete-guild-application-command
+    #   Discord documentation "Delete Guild Application Command"
+    def delete_guild_application_command(application_id:, guild_id:, command_id:)
+      send_request(:delete, "/applications/#{application_id}/guilds/#{guild_id}/commands/#{command_id}")
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param json [Hash]
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#bulk-overwrite-guild-application-commands
+    #   Discord documentation "Bulk Overwrite Guild Application Commands"
+    def bulk_overwrite_guild_application_commands(application_id:, guild_id:, json:)
+      send_request(:put, "/applications/#{application_id}/guilds/#{guild_id}/commands", json:)
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#get-guild-application-command-permissions
+    #   Discord documentation "Get Guild Application Command Permissions"
+    def get_guild_application_command_permissions(application_id:, guild_id:)
+      send_request(:get, "/applications/#{application_id}/guilds/#{guild_id}/commands/permissions")
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param command_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#get-application-command-permissions
+    #   Discord documentation "Get Application Command Permissions"
+    def get_application_command_permissions(application_id:, guild_id:, command_id:)
+      send_request(:get, "/applications/#{application_id}/guilds/#{guild_id}/commands/#{command_id}/permissions")
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param command_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param json [Hash]
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#edit-application-command-permissions
+    #   Discord documentation "Edit Application Command Permissions"
+    def edit_application_command_permissions(application_id:, guild_id:, command_id:, json:)
+      send_request(:put, "/applications/#{application_id}/guilds/#{guild_id}/commands/#{command_id}/permissions", json:)
+    end
+
+    ##
+    # @deprecated This endpoint has been disabled with
+    #   {https://discord.com/developers/docs/change-log#updated-command-permissions
+    #   updates to command permissions (Permissions v2)}. Instead, you can
+    #   {#edit_application_command_permissions edit each application command
+    #   permissions} (though you should be careful to handle any potential
+    #   {https://discord.com/developers/docs/topics/rate-limits rate limits}).
+    #
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param json [Hash]
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/interactions/application-commands#batch-edit-application-command-permissions
+    #   Discord documentation "Batch Edit Application Command Permissions"
+    def batch_edit_application_command_permissions(application_id:, guild_id:, json:)
+      send_request(:put, "/applications/#{application_id}/guilds/#{guild_id}/commands/permissions", json:)
+    end
+  end
+end

data/lib/lib_discord/application_role_connection_metadata.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "lib_discord/resource"
+
+module LibDiscord
+  ##
+  # Application Role Connection Metadata
+  #
+  # Do not instantiate an {ApplicationRoleConnectionMetadata} directly. Instead
+  # request one from an instance of {Client}.
+  #
+  #   client = LibDiscord::Client.new("Bot auth.token")
+  #   a = client["application_role_connection_metadata"]
+  #
+  # @see https://discord.com/developers/docs/resources/application-role-connection-metadata
+  #   Discord documentation "Application Role Connection Metadata"
+  class ApplicationRoleConnectionMetadata < Resource
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    #
+    # @see https://discord.com/developers/docs/resources/application-role-connection-metadata#get-application-role-connection-metadata-records
+    #   Discord documentation "Get Application Role Connection Metadata
+    #   Records"
+    def get_application_role_connection_metadata_records(application_id:)
+      send_request(:get, "/applications/#{application_id}/role-connections/metadata")
+    end
+
+    ##
+    # @param application_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param json [Hash] JSON serializable payload
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +json+ cannot be serialized to JSON
+    #
+    # @see https://discord.com/developers/docs/resources/application-role-connection-metadata#update-application-role-connection-metadata-records
+    #   Discord documentation "Update Application Role Connection Metadata
+    #   Records"
+    def update_application_role_connection_metadata_records(application_id:, json:)
+      send_request(:put, "/applications/#{application_id}/role-connections/metadata", json:)
+    end
+  end
+end

data/lib/lib_discord/audit_log.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "lib_discord/resource"
+
+module LibDiscord
+  ##
+  # Audit Logs Resource
+  #
+  # Do not instantiate an {AuditLog} directly. Instead request one from an
+  # instance of {Client}.
+  #
+  #   client = LibDiscord::Client.new("Bot auth.token")
+  #   a = client["audit_log"]
+  #
+  # @see https://discord.com/developers/docs/resources/audit-log#audit-logs-resource
+  #   Discord documentation "Audit Logs Resource"
+  class AuditLog < Resource
+    ##
+    # @param guild_id [#to_s]
+    #   {https://discord.com/developers/docs/reference#snowflakes Discord
+    #   documentation "Snowflakes"}
+    # @param params [Hash] optional HTTP query parameters
+    #
+    # @return [Response]
+    #
+    # @raise [TimeoutError] if the HTTP request times out
+    # @raise [ConstraintError] if +params+ cannot be coerced into a valid query
+    #   parameters string
+    #
+    # @see https://discord.com/developers/docs/resources/audit-log#get-guild-audit-log
+    #   Discord documentation "Get Guild Audit Log"
+    def get_guild_audit_log(guild_id:, params: {})
+      send_request(:get, "/guilds/#{guild_id}/audit-logs", params:)
+    end
+  end
+end