v3.0.0-beta.1 | Component data serialization, removed old declarations

Overview

Added component data serialization, few minor additions and finally removed old declarations.

It has been 84 years...
As a reminder, while the major changes are done, some smaller changes and/or deprecations might be necessary in the future, to always improve the development experience, adopt newer features and better practices.

While there is no complete migration guide, you are welcome to ask in the support server.

Note about the previous release

The meaning of CommandScope#GLOBAL was changed in the previous release; You can learn more about it in the "Breaking changes" section.

Removed all deprecated declarations (#212)

If you're having compilation errors, downgrade to 3.0.0-alpha.24 and:

• Do a full recompile to see the deprecation warnings,
• Or, use your IDE to inspect your project.

Support for component data serialization (#231)

This enables you to pass any data to your component and timeout handlers, as long as they are serializable.

Any serialization library can be used, Jackson, Gson, kotlinx.serialization, Protobuf, Java's serialization (???), you name it.

Breaking changes

• The String arg parameter have been replaced with a data argument of type SerializedComponentData
• A SerializedComponentData serialize(R) method has been added
• A new migration script has been added, if you are using a migration tool already, you do not need to do anything

New features

• Added @SerializableComponentData and @SerializableTimeoutData
  • Can be used instead of @ComponentData/@TimeoutData to (de)serialize objects using GlobalComponentDataSerializer
  • GlobalComponentDataSerializer has a default instance, which can be overridden by creating your own instance.

Breaking changes

Components

• Require >=42.7.5 of the PostgreSQL first party driver (required by #231)
  • You can still use H2, which does not require a minimum version
  • You will be warned when using a third party PostgreSQL driver

Deprecations

Misc

• Deprecated typeReferenceOf
  • Replaced by jackson-module-kotlin's jacksonTypeRef

Changes

Dependencies

• Added jackson-module-kotlin v2.17.2, same version as what JDA uses
  • Required by #231

New features

Misc

• Added static factories for KotlinTypeToken
  • Similar to Gson's TypeToken static methods, or the Jackson ObjectMapper's methods returning TypeReferences
• Added ParameterWrapper#typeToken
  • Return a KotlinTypeToken, a more general purpose object

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-alpha.24...v3.0.0-beta.1

Installation

As a reminder, the minimum Java version supported is Java 17.

Kotlin Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.freya022:BotCommands:3.0.0-beta.1")
}

Maven

<dependency>
    <groupId>io.github.freya022</groupId>
    <artifactId>BotCommands</artifactId>
    <version>3.0.0-beta.1</version>
</dependency>

v3.0.0-alpha.24 | User-installable apps, jda-emojis

Overview

Added user-installable apps and jda-emojis.

Note: This should be the last V3 alpha.

User-installable apps (#163)

These will allow you to use interactions anywhere on Discord, by installing them on users directly instead of guilds.
You can read more about them on the JDA release notes.

After installing your app on the user, allowing a command to be installed on the user requires you to add USER_INSTALL to the integrationTypes property of your top level command.

Then, you can define the contexts property (again, on the top-level command), this property defines where the command can be used (Guild, Bot DMs, Friend DMs, Group DMs).

You can also check out the wiki for more details.

Breaking changes

• Meaning of CommandScope#GLOBAL has changed, it previously meant having a command accessible on both the installed Guild, and the Bot's DMs
  However, since then, it only specifies the scope on which the command is added.

  If you have used this scope, you will likely get a warning which recommends you to use the "Guild" variant of the event,
  to fix this and restore previous behavior, you will need to add InteractionContextType.GUILD and InteractionContextType.BOT_DM in the contexts property, alongside your existing scope = CommandScope.GLOBAL.

  Kotlin example:

  @TopLevelSlashCommandData(scope = CommandScope.GLOBAL)
  @JDASlashCommand(name = "foo")
  fun onSlashFoo(event: GlobalSlashEvent) {
      
  }

  when updating to 3.0.0-alpha.24, becomes:

  // Same as @TopLevelSlashCommandData(scope = CommandScope.GLOBAL, contexts = [InteractionContextType.GUILD, InteractionContextType.BOT_DM])
  @TopLevelSlashCommandData(contexts = [InteractionContextType.GUILD, InteractionContextType.BOT_DM])
  @JDASlashCommand(name = "foo")
  fun onSlashFoo(event: GlobalSlashEvent) {
      
  }

Deprecations

• Deprecated CommandScope#GLOBAL_NO_DM, set contexts on your top-level command to InteractionContextType.GUILD instead
• Deprecated CommandScope in code-declared commands, use interaction contexts instead

New features

• Can now set interaction contexts (where a command can run)
• Can now set integration types (where a command can be installed)
• Default integration types and interaction contexts can be changed
  • In GuildApplicationCommandManager for guild-scoped commands
  • In GlobalApplicationCommandManager for global-scoped commands
  • These defaults apply for both annotated and code-declared commands

Added jda-emojis (#229)

This library was added to allow a more seamless usage of emojis in your JDA code.

When you previously had to take the proper Unicode manually, or using JEmoji and converting to JDA's UnicodeEmoji, you can now directly take the same emoji Discord supports, from Emojis (in the dev.freya02.jda.emojis.unicode package) or UnicodeEmojis.

Remember, if you are converting from JEmoji to jda-emojis, you will find the emoji names using Discord's names.

Check out the wiki for more details.

Deprecations

• ButtonContent: fromUnicode, fromShortcode

New features

• Added an withEmoji overload with JDA's Emoji in ButtonContent/ButtonFactory (when building a button)

New features

Components

• Added withDisabled on ButtonContent and ButtonFactory
  • This allows disabling a component before it is built

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-alpha.23...v3.0.0-alpha.24

v3.0.0-alpha.23 | Improved dynamic DI, simplified runtime filters, and general improvements

Overview

Improved built-in DI capabilities, simplified runtime filters, and general usability improvements.

Replaced DynamicSupplier with user-defined service suppliers (#225, #226)

This aims to allow defining services earlier in the loading process, for example, when initializing the framework, or while discovering classes.

One use case is to define services when discovering an interface with a given annotation; a similar example in Spring would be JPA repositories (using @Repository on an interface that gets implemented automatically).

Breaking changes

• Removed DynamicSupplier

Deprecations

• Deprecated instance suppliers
  • InstanceSupplier
  • BServiceConfig#instanceSupplierMap
  • BServiceConfigBuilder#registerInstanceSupplier

Changes

• Passed a ServiceContainer in ClassGraphProcessor methods
• Annotations are no longer read from classes supplied by InstanceSuppliers
  • This shouldn't affect anyone as you would use a service factory instead

New features

• Added ServiceSupplier
  • This lets you configure a service with a bit more depth
• Added DefaultServiceContainer#putSuppliedService(ServiceSupplier)
  • You should be able to call this from a ClassGraphProcessor, for example, if you want to register proxied interfaces as services
• Added BServiceConfigBuilder#registerServiceSupplier(...)

Removed append attributes from @UserPermission, @BotPermissions and @Test (#227)

You will now have to annotate the affected function directly, to clarify what affects a function, however, to reduce repetition, you can use them as meta-annotations, combine them and override them.

Breaking changes

• Removed the append attribute
• Removed the CLASS target
• If findAllAnnotations encounters the target annotation, this will override meta-annotations (children annotations) if directOverrides is true
• findAllAnnotations has no defined order anymore

Changes

• Added the ANNOTATION_CLASS target

Slightly simplified filters (#228)

A rejection handler is no longer mandatory, however, you can keep using it if you wish, by calling it yourself.

Breaking changes

• You no longer need to make rejection handlers
  • Instead of returning arbitrary data, you handle the rejection in the filter directly, and return a string for logging purposes
  • I recommend using a separate function/class to reduce maintenance
• The global property of filters is now abstract
  • Clarifies which filter is global or command-specific

Breaking changes

Built-in dependency injection

• Removed ServiceContainer#lazyService
  • This already existed as lazy

Changes

Dependencies

• Kotlin: 2.0.0 -> 2.1.0
• kotlinx-coroutines: 1.9.2 -> 1.10.1
• (Optional) Spring boot: 3.2.12 -> 3.4.2
• kotlinx-datetime: 0.5.0 -> 0.6.1
• ClassGraph: 4.8.175 -> 4.8.179
• Caffeine: 3.1.8 -> 3.2.0
• slf4j-api: 2.0.13 -> 2.0.16
• kotlin-logging: 7.0.0 -> 7.0.3
• (Optional) HikariCP: 5.1.0 -> 6.2.1

App emojis

• Throw exception if not enough slots are available

New features

App emojis

• Added BAppEmojisConfig#deleteOnOutOfSlots
  • If there are not enough slots, it will delete the oldest application emojis that aren't required by the bot

Localization

• Added LocalizationContext#fromLocaleProviders
  • This helps you create a localization context using the same locales as using the events would
  • This can be useful when replying in an interaction filter
• Adding a / prefix to your template key will make the library ignore any set prefix
  • Example: /my.command.responses.ok will stay as my.command.responses.ok even if a prefix is set

Components

• Added a few helpers to create IdentifiableComponent from JDA components
• Added a few helpers to remove stored components using JDA components

Misc

• Added a few utilities to convert from/to Kotlin/Java functions in ReflectionUtils

Bug fixes

Built-in dependency injection

• Fixed using LazyService in Java constructors

App emojis

• Fixed app emojis being enabled by default on Spring apps

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-alpha.22...v3.0.0-alpha.23

v3.0.0-alpha.22 | App emoji registry, QoL additions and fixes

Overview

Added an application emoji registry, some quality of life additions and fixes.

Application emoji registry (opt-in, #221)

This adds support for automatic loading and setup of your bot's application emojis.
The emojis are loaded from the classpath, typically in your resources folder,
and are pushed to Discord before JDA logs in, meaning the emojis are always present when the bot can respond.

More details on the wiki.

New Features

• Added a appEmojis configuration function
  • This is where you enable the application emoji registry and loading
  • Enable it with botcommands.app.emojis.enable in Spring properties
• Added AppEmojisRegistry and
  • This is where you will get your emojis, after they are loaded
• Added @AppEmojiContainer
  • Declares a class holding ApplicationEmoji properties
  • Java user can use eagerly-loaded emojis
  • Kotlin users can use both eager and lazy emojis

Breaking changes

Misc

• Methods in AnnotationUtils visible to Java users now accepts KAnnotatedElement instead of AnnotatedElement
  • These methods were made to be used with functions managed by the framework, such as command functions, and are KFunctions

Changes

Dependencies

• JDA: 5.2.1 -> 5.2.2

Run-time filters

• Allowed using @Filter as a meta-annotation

New features

Application commands

• Added ApplicationCommandsContext#findTopLevelSlashCommand
  • Gets a TopLevelSlashCommandInfo from a guild (or global scope) and name

Command introspection

• Added a few helpers to retrieve annotations from command functions
  • Identical to the AnnotationUtils functions, but adding convenience

Event listeners

• Added ignoredIntents to @BEventListener
  • Allows you to ignore specific missing intents for an event listener
  • This is useful especially for message listeners, where missing the DIRECT_MESSAGES intent can be intended

Bug fixes

Application commands

• Fixed missing description on annotated commands
• Fixed the default command cache on macOS (#223)

Run-time filters

• Fixed detection of run-time filters when using Spring

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-alpha.21...v3.0.0-alpha.22

v3.0.0-alpha.21 | Easier localization data formats, Spring dev tools, blocking events and fixes

Overview

Added easier localization data format support, support for Spring devtools, blocking events and fixes.

Jackson-based localization map readers (#218)

A general-purpose localization map reader based on Jackson was added, so you can add support for any data format supported by Jackson.

Breaking changes

• Removed DefaultJsonLocalizationMapReader
  • Replaced by a JacksonLocalizationMapReader, using the JSON data format
  • Also changed the bean name to reflect the change, should not affect anyone

New features

• Added JacksonLocalizationMapReader
  • This easily lets you register readers for any data format supported by Jackson
  • Supports changing the produced LocalizationTemplates
  • Support changing the ClassLoader used to load resources
    • This should only be useful when working across named modules

Spring developer tools support (#219)

This allows you to reload your entire application without restarting the entire JVM, leading to faster reload times.

You can configure a few properties with the jda.devtools.* prefix.

Blocking event listeners (#220)

You are now able to listen to events in the same thread they were fired in.

Breaking changes

• Moved EventDispatcher to the core.hooks package

Deprecations

• Deprecated the async property of @BEventListener
  • Replaced by the mode property, can be changed to SHARED, ASYNC or BLOCKING

Additions

• You are now able to listen to events on the same thread they were fired on, using mode = RunMode.BLOCKING.

Breaking changes

Rate limiting

• (Java only) Static factories are now prefixed with create
  • This was necessary as you could not use default due to it being a context-less Java keyword

JDAService

• (Java only) Static factories are now prefixed with create
  • This was necessary as you could not use default due to it being a context-less Java keyword

Changes

Dependencies

• JDA: 5.1.1 -> 5.2.1
• Spring boot (optional): 3.2.2 -> 3.2.12
• JEmoji: 1.3.3 -> 1.6.0
  • You can safely remove this dependency if you do not wish to resolve Unicode emojis from shortcodes
  • Note: If you were using JEmoji's Emoji#getUnicode(), you will need to replace it with getEmoji(), this a bug fix

Application commands

• Default application commands cache is now in standard data directories for Linux and macOS (#217)
  • Linux: $XGD_DATA_HOME/.local/share/BotCommands (fallbacks to $HOME/.local/share/BotCommands, source)
  • macOS: ~/Library/Application Support/io.github.freya022.BotCommands (source 1, source 2)

Default rate limiter

• PriorityGlobalRestRateLimiter now immediately forwards interaction requests (Global RL doesn't apply on them)

New features

Events

• Added PreFirstGatewayConnectEvent
  • This event is suited for usages when you need to run logic after loading all services,
    and after the token was validated, but before JDA actual logs in the gateway and starts receiving events.

Rate limiting

• Added Kotlin extensions when defining bucket refill

Extensions

• Added emoji helpers, to get emojis lazily and convert between JEmoji and JDA emojis
  • lazyUnicodeEmoji
  • Emoji#asUnicodeEmoji
  • EmojiUtils#asUnicodeEmoji
• Added more OrNull extensions for JDA and Guild

Resolvers

• Added KotlinTypeToken to construct a KType wrapper, as an alternative for parametrized types in resolvers

Bug fixes

Spring

• Fixed metadata files

Resolvers

• Improved equality checks between Kotlin and Java equivalents (like k.c.List and j.u.List)

Application commands

• Fixed top-level slash command descriptions sometimes using a subcommand description

JDAService

• Fixed a false positive mismatch due to JDA returning both old and renamed intents as enabled

Default rate limiter

• Fixed the PriorityGlobalRestRateLimiter "discarding" requests when all tokens were used, until they were refilled
• Fixed the PriorityGlobalRestRateLimiter sending requests in the wrong order due to priority ties being broken arbitrarily

Extensions

• Fixed deleteDelayed

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-alpha.20...v3.0.0-alpha.21

v3.0.0-alpha.20 | Default persistent timeout, improved introspection/resolver, fixes

Overview

Added a default persistent component timeout, improved introspection API/resolvers, and a bunch of fixes.

Breaking changes

Autocomplete

• Autocomplete handlers can now only get parameters that are present on the slash command

Deprecations

Components

• Deprecated Components.defaultTimeout
  • Renamed to Components.defaultEphemeralTimeout
  • Now nullable

Resolvers

• All resolve and resolveSuspend functions were deprecated
  • New overloads were added, which accepts different kinds of options instead of the commands
  • You can still get the command back from the executable property

Introspection API

• Deprecated getting parameters and option by name
  • You can still use the collection methods to achieve the same result

Changes

Text commands

• Go to next text command variation if a value is null and required
  • Aligns with documented behavior on TextParameterResolver#resolve

New features

Components

• Added a default persistent component timeout (Components.defaultPersistentTimeout)
  • Set to null by default

Commands

• Add support for inline classes in annotated commands

Bug fixes

Default DI

• Fixed DefaultServiceContainer#getServiceNamesForAnnotation returning services which were unavailable

Misc

• Fixed inability to scan nested JARs
  • Such as Spring Boot JARs

Components

• Fixed inability to create select menus

Don't hesitate to check out the examples and the wiki.

Full Changelog: v3.0.0-alpha.19...v3.0.0-alpha.20

v3.0.0-alpha.19 | Configurable command cache and QoL improvements

Overview

Added a configurable command cache, components which reset their timeout on use, and a bunch of QoL changes.

Common interfaces for command builders (#194)

Option aggregate builders now share the same methods as command builder to declare options.

Breaking changes

• (In aggregate) nestedOptionVararg -> optionVararg
• (In aggregate) nestedAggregate -> aggregate
• inlineClassOption and inlineClassOptionVararg were moved to extensions
• Moved some classes related to option builders
  • This shouldn't affect most users as the types should not be used explicitly outside of extensions, you can re-import at worst

Changes

• Command, option and aggregate builders are now interfaces

Additions

• Added support for value classes in annotated options of user/message context commands
• Added inlineClassAggregate, lets you add any option inside an inline class aggregator
  • Basically, no longer limited to an option/vararg

Priority parameter on ParameterResolverFactory (#197)

This enables overriding existing parameters resolvers.

To override a built-in resolver with your own, set your factory's (or the @Resolver annotation) priority to higher than 0.

Note: Spring users may see a warning related to annotation property aliasing, you can ignore it.
This is due to @BService and @ResolverFactory both having a priority property.

Additions

• Added ParameterResolverFactory#priority
• Added a priority property for @Resolver

Changes

• Resolvers are now chosen based off their compatibility and priority
  • Errors if both have same priority

New way of getting custom text command prefixes (#198)

You can now get custom text command prefixes based on a given GuildMessageChannel,
methods to get the supported/preferred prefixes now accurately return the prefixes used in other places.

Possible breaking changes - If you had prefixes set with `SettingsProvider`

Retrieving allowed prefixes of a command in a specific channel has slightly changed:

Previous behavior

• If ping-as-prefix is enabled, and the command starts with the bot's mention, then the command is accepted
• Else, the prefixes are gathered, and if it starts with any, the command is accepted:
  • If a SettingsProvider is available, from SettingProvider#getPrefixes(Guild)
  • Else, from BTextConfig#prefixes

New behavior

The command is accepted if any prefix given by TextCommandsContext#getPrefixes(GuildMessageChannel) matches:

• If a TextPrefixSupplier is available, from TextPrefixSupplier#getPrefixes(GuildMessageChannel)
• If a SettingsProvider is available, from SettingProvider#getPrefixes(Guild) (now deprecated)
• Else, from BTextConfig#prefixes + the bot's mention if BTextConfig#usePingAsPrefix is enabled

Deprecations

• SettingsProvider
• SettingsProvider#getPrefixes(Guild)
• TextCommandsContext#prefixes
• TextCommandsContext#isPingAsPrefix
• TextCommandsContext#getPreferredPrefix(JDA)

Changes

• The prefix used in the content of the built-in help command is now determined by TextCommandsContext#getPreferredPrefix(GuildMessageChannel)

Additions

• Added TextPrefixSupplier
  • Returns the allowed prefixes for a given GuildMessageChannel
  • Returns the preferred prefix for a given GuildMessageChannel

Configurable application commands cache (#201)

This allows you to configure the path in which files are written, or to switch to a database storage,
but also disable caching.

Deprecations

• Deprecated BApplicationConfig#onlineAppCommandCheckEnabled
  • Moved to ApplicationCommandsCacheConfig#checkOnline
• Deprecated BApplicationConfig#logApplicationData
  • Moved to ApplicationCommandsCacheConfig#logDataIf
• Deprecated BApplicationConfig#diffEngine
  • Moved to ApplicationCommandsCacheConfig#diffEngine

Changes

• If the application commands cache folder is not writable, an in-memory cache is used.

Additions

• Added BApplicationConfig#fileCache, databaseCache and disableCache
  • All of these have the properties that were deprecated
  • fileCache lets you configure where the cache is, may be useful for Docker containers
  • (Recommended) databaseCache reuses the existing ConnectionSupplier, more resilient to write errors, no extra files in containers
  • disableCache always updates commands on startup, not recommended

Added more component delete methods and resetTimeoutOnUse (#202)

Breaking changes

• deleteComponentsById now takes integers instead of strings
  • These are the integers returned by the internalId property
  • Useful if you need cheap storage of used component IDs, used in paginators for example
  • If you need to delete components by their String ID, use deleteComponents with IdentifiableComponent.fromId

Additions

• Added resetTimeoutOnUse
  • Resets the timeout everytime the component is used
  • Can be set on a component group, using any component inside that group resets the timeout
• Added a BContext property in component factories
• Added static methods to make fake IdentifiableComponents
• Added deleteComponents taking IdentifiableComponents
• Added deleteRows taking Collection<LayoutComponent>
  • Useful when deleting components from a JDA Message

Misc

• Added a new example for resetTimeoutOnUse

Prioritized rate limiter (#205)

Added a RestRateLimiter implementation which enforces the 50 requests/s,
preventing cloudflare bans (as best as it can, depends on your host).

This rate limiter is used by default when using the new factories in JDAService,
which I highly recommend using.

Changes

• If the default RestRateLimiter is used, application commands are pushed at a rate of 20 requests/s

Additions

• Added PriorityGlobalRestRateLimiter
  • Enforces 50 requests/s
  • There may be a lot of command updates, so their requests have lower priority
  • Prevents CF bans on large bots as all requests are fired at once due to each request being on its own bucket

Single-shard and sharded factories in JDAService (#206)

Static factories similar to JDA's were added,
they configure the event manager and rest config,
but also the intents and cache flags.

Example

Before

public class Bot extends JDAService {
    @Override
    public void createJDA(BReadyEvent event, IEventManager eventManager) {
        JDABuilder.createLight(token, getIntents())
                .setEventManager(eventManager)
                .enableCache(getCacheFlags())
                .setRestConfig(getDefaultRestConfig()) // new
                // Other configuration, such as activity, member cache policy...
                .build();
    }
}

After

public class Bot extends JDAService {
    @Override
    public void createJDA(BReadyEvent event, IEventManager eventManager) {
        light(token)
                // Other configuration, such as activity, member cache policy...
                .build();
    }
}

Ability to read meta-annotations recursively (#207)

This allows combining one or more annotations on a single annotation.

Breaking changes

• @Filter can no longer be used on classes

Changes

• Custom condition annotations and their checkers no longer need to be in the search path
• Most, if not all, annotations can be used as meta-annotations
• The following annotations can be read multiple times, when they are used indirectly (as meta-annotations):
  • @DeclarationFilter
  • @Filter
  • @ChannelTypes
  • @MentionsString
    Be aware that such annotations are overridden if the same annotation is used directly

Refactor rate limiters to allow easier use of proxied buckets (#208)

These changes improve the customization of rate limiters and how the bucket keys and configurations are retrieved.

Breaking changes

• Renamed Cooldown#rateLimitScope => scope
• Removed BucketFactory
  • Utility methods were moved to Buckets
  • Replaced with BucketConfigurationSupplier
• Removed RateLimiterFactory
  • Registering a rate limiter only requires the "group" (name) and a RateLimiter
• Renamed DefaultBucketAccessor -> InMemoryBucketAccessor
• Moved DefaultRateLimiter to internal package
  • Use RateLimiter#createDefault instead
• The rateLimitReference method while building a component, now accepts a ComponentRateLimitReference
  • You can create one with the createRateLimitReference method of your component factory

Additions

• Added RateLimiter#createDefaultProxied
  • Allows you to give a Bucket4J ProxyManager to use store buckets remotely, such as in a database
• Added BucketConfigurationSupplier
  • Lets you return different buckets based on the execution context
  • You can use Buckets + BucketConfigurationSupplier#constant (BucketConfiguration#toSupplier in Kotlin) to always use the same "bucket configuration"
• Added ProxyBucketAccessor
  • Uses a BucketKeySupplier for the... bucket key, yea
• Added AnnotatedRateLimiterFactory
  • Lets you configure which RateLimiter to use on annotated rate limits / cooldown

Examples

Command rate limiting, with code-declaration:

v3.0.0-alpha.18 | Hotfix for Spring startup

Overview

Hotfix for an issue preventing Spring apps from starting up

Deprecations

• Deprecated BServiceConfig#serviceAnnotations

Fixes

• Fixed an issue preventing Spring apps from starting up

Don't hesitate to check out the wiki.

Full Changelog: v3.0.0-alpha.17...v3.0.0-alpha.18

v3.0.0-alpha.17 | Improved Spring support, text/app command switch and command update logs

Overview

Improved Spring support, added text/application command switches and improved application command update logs.

Add Spring auto configuration (#190)

You no longer need to use the annotation, nor be forced to make a meta-annotation to prevent annotation overriding.

Simply adding the library to your project will load it,
you can avoid running it with the exclude value of your @SpringBootApplication.

Add Spring configuration metadata (#188)

You can now benefit from autocomplete and hints in your application.properties/application.yaml.

If you're interested in how that's done: Annotation processor

Breaking changes

• Renamed botcommands.database.queryLogThresholdMillis to botcommands.database.queryLogThreshold
  • Uses Java's Duration, Spring supports the ISO-8601 format, a simplified format or milliseconds
• Changed how maps are read from properties
  • Use the standard format, [property key].[map key]=[map value]
  • Affects botcommands.application.localizations

Additions

• Added metadata for Spring configuration properties (More info)
  • Note: Description is a copy of the docs due to https://youtrack.jetbrains.com/issue/IDEA-356678

Fixes

• Fix configuring botcommands.text.dmClosedEmoji

Deprecations

• Deprecated @EnableBotCommands
  • Remove it and it works.

Add switches to disable application / text commands (#186)

At least you have the choice to not use them, right?

Additions

• Added an enable properties to BApplicationConfig and BTextConfig, as well as their Spring properties.
• Added @RequireApplicationCommands and @RequireTextCommands, you can use these to disable services that depend on them.

Improve command diff and their logs (#191)

The new application command diff engine will give you more accurate details over what changed on your application commands.

The new engine is used by default, and will log the differences if TRACE logs are enabled for io.github.freya022.botcommands.internal.commands.application.diff.DiffLogger
or any package it is in.

Deprecations

• BDebugConfig#enableApplicationDiffsLogs
  • Only used for the old diff engine

Changes

• New application command diff engine by default
  • Only logs what changed, with more accuracy, logs on TRACE

Additions

• BApplicationConfig#diffEngine
  • Lets you switch back in case there's a bug
• BApplicationConfig#logApplicationCommandData
  • Logs the raw JSON when commands needs to be updated

Deprecations

Configuration

• Deprecated BDebugConfig#enabledMissingLocalizationLogs
  • Replaced by BApplicationConfig#logMissingLocalizationKeys
• Deprecated BDebugConfig
• Deprecated BComponentsConfig#useComponents
  • Renamed to BComponentsConfig#enable

Fixes

Spring configuration

• Fixed default configs being returned with manual getters (such as from BContext or BConfig)

Text commands

• Fixed help command being disabled if another Spring bean was declared but disabled

Application commands

• Fix global commands always updating

Don't hesitate to check out the changelogs and the wiki.

Full Changelog: v3.0.0-alpha.16...v3.0.0-alpha.17

v3.0.0-alpha.16 | Improved localization, command introspection and RestResult

Overview

Improved localization support, added an API to inspect commands and improved RestAction exception handling in Kotlin, among other features and changes.

Add localized reply functions to events (#177)

All interaction events, InteractionHook and BaseCommandEvent (incl CommandEvent) now have several functions
to reply using the user locale, guild locale, or any locale.

By default, the localization bundles used are those registered in BLocalizationConfig#responseBundles,
you can set a specific bundle, and set a localization prefix,
by setting localizationBundle and localizationPrefix on your event.

In interactions, the user and guild locales can be customized by implementing UserLocaleProvider and GuildLocaleProvider respectively.

In text commands, the locale can be customized by implementing TextCommandLocaleProvider.

Use locale providers for AppLocalizationContext/TextLocalizationContext

Using the same providers from the above feature, injected localization contexts will use their returned locales.

Previously it would always use Interaction#userLocale/guildLocale or Guild#locale,
it will now use UserLocaleProvider/GuildLocaleProvider and TextCommandLocaleProvider.

This allows you to customize the locale without reimplementing your own localization.

Note: I recommend using the localized reply methods on the event itself.

Added API to introspect commands, parameters and options (#178)

You can now retrieve details, parameters and options of text and application commands.

Breaking changes

• ComponentDescriptor is no longer passed in ComponentParameterResolver
• ModalHandlerInfo is no longer passed in ModalParameterResolver
• TextCommandVariation and SlashCommandInfo has moved to the API package
• Parameters of TextParameterResolver#getHelpContent changed
  • Old: (parameter: KParameter, event: BaseCommandEvent, isID: Boolean)
  • New: (option: TextCommandOption, event: BaseCommandEvent)

Added annotated application command declaration filters (#185)

Old ways to restrict commands to a guild have been deprecated,
and replaced with an annotation set on each application command.

This enables having such filters be more visible, instead of being tucked away in two interfaces.

Deprecations

• Deprecated CommandList, SettingsProvider#getGuildCommands and ApplicationCommand#getGuildsForCommandId

Addition

• Added @DeclarationFilter and CommandDeclarationFilter
  • Run on annotated application commands when pushed to a guild

Reworked getting framework messages (#181)

Breaking changes

• Renamed DefaultMessagesSupplier to DefaultMessagesFactory
  • Has a default instance, can be overridden
• Added methods to get instances from Interaction and MessageReceivedEvent
  • Uses UserLocaleProvider and TextCommandLocaleProvider by default

Deprecations

• Deprecated DefaultMessages getters in BContext

Additions

• Added getters in LocalizableAction (i.e., for text commands and interactions)

Added usability getters for text/application commands (#182)

You can now use getUsability on TextCommandInfo/ApplicationCommandInfo,
this allows checking if a given command is visible and/or usable.

Also added support for any NSFW channels in text commands, previously it only supported text and news channels.

Improved text command patterns (commit)

Patterns of text command options can now specify pattern flags in Pattern.compile;
Using embedded flag expressions is no longer necessary, but can still be used.

Unicode character classes (incl. unicode casing) are also now used on all patterns.

Improved text option resolvers (#184)

Deprecations

• Deprecated TextParameterResolver#requiredGroups

Changes

• The pattern of resolvers is wrapped in a non-capturing group to prevent conflicts
• Improved detection of mentions
  • Correctly reads either the full mention or the ID

Added a BotOwners service (#183)

This service should now be used to check bot owners, it will take owner IDs from BConfig#predefinedOwnerIds,
if not set, will retrieve owners from Discord.

Deprecations

• Deprecated BConfig#ownerIds
  • Renamed to predefinedOwnerIds, as these IDs do not always represent the real owners.
• Deprecated BConfig#addOwners, renamed to BConfig#addPredefinedOwners
• Deprecated BConfig#isOwner, BContext#isOwner, BContext#ownerIds

Now using command IDs to differentiate top-level commands (#179)

This allows two commands with the same top-level name, in both the global and the guild scope.

Breaking changes

• Removed ApplicationCommandMap
  • Good riddance
• ApplicationCommandsContext#findLive[Type]Command -> find[Type]Command
• ApplicationCommandsContext#getLiveApplicationCommandsMap -> getApplicationCommands
• ApplicationCommandsContext#getEffectiveApplicationCommandsMap -> getEffectiveApplicationCommands

Additions

• Added ApplicationCommandsContext#getApplicationCommandById
  • Finds by id, group, subcommand, and type

Replaced functional RestAction handling from Result to RestResult (#180)

Now allows properly ignoring error responses from rest actions,
under the condition that the value never tries to get returned (i.e., you can still use onSuccess).

See example here

Breaking changes

• RestAction#awaitCatching now returns RestResult
• Result extensions moved to RestResult
  • To have a RestResult, use runCatchingRest

Changes

• ignore properly ignores error responses
  • getOrThrow still throws, use getOrNull or onSuccess
• orThrow throws if the exception has not been ignored

Additions

• Added runCatchingRest
• Added RestResult#recover, creates a new RestResult if the exception matches, with a new value or exception.

Breaking changes

Components

• Components that can be grouped implement IGroupHolder
  • Allows to not group groups
  • Technically breaking, but you shouldn't see anything

Text commands

• Removed Consumer parameter from BaseCommandEvent#sendWithEmbedFooterIcon
  • It was unused anyway, as the RestAction is returned

Deprecations

Application commands

• Deprecated BConfig#disableAutocompleteCache
  • Moved to application configs
• Deprecated BContext#invalidateAutocompleteCache
  • Moved to ApplicationCommandContext

Text commands

• Deprecated text command related properties in BContext, moved to TextCommandsContext

Misc

• Deprecated BContext#getEffectiveLocale and SettingsProvider#getLocale
  • Prefer using locale getters such as UserLocaleProvider/GuildLocaleProvider/TextCommandLocaleProvider

Components

• Deprecated EphemeralHandlerBuilder/PersistentHandlerBuilder and bindTo overloads which configured those
  • This should not affect anyone as they are extra steps for no reason
• Deprecated type-safe bindTo and timeout extensions
  • Replaced with bindWith and timeoutWith
  • Should help with importing the functions
• Deprecated oneUse
  • Renamed to singleUse

Changes

Dependencies

• JDA: 5.0.0-beta.24 -> 5.0.0
• jda-ktx: 0.11.0-beta.20 -> 0.12.0
• kotlinx.coroutines: 1.8.0 -> 1.8.1
• jackson-databind: 2.17.1 -> 2.17.2
• (JDA alignment) trove4j (changed artifact id from trove4j to core): 3.0.3 -> 3.1.0
• kotlin-logging-jvm: 6.0.9 -> 7.0.0

Text commands

• Load and log on initialization

Misc

• Use timeout of CoroutineEventManager by default for each listener
• Exceptions are sent to all bot owners

Additions

Built-in resolvers

• Added a UserSnowflake resolver for text/application commands, and components.

Text commands

• Added back text command support for enum resolver
• Added default provider for DefaultEmbedSupplier/DefaultEmbedFooterIconSupplier
• Added emoji for "Closed DMs"
  • Used when an internal reply method cannot send a DM to a user
• Injecting a TextSuggestionSupplier will return the default text suggestion supplier if nothing else is available

Application commands

• Added ApplicationCommandResolverData
  • Allows you to inspect the command builder when getting a resolver

Components

• Added bindWith and timeoutWith extensions to allow unbound callable references
  • Allows bindWith(MyClass::myFunction, arg1, arg2...), useful when you don't have the instance
• Added metadata to top-level application commands
  • id, version and convenience methods, such as getting a command as a mention

Misc

• Added KLogger#[Level]Null
  • Logs and returns null
• Added ban/bulk-ban extensions with Kotlin Duration
• Added BContext#getExceptionContext
  • Allows getting the same message content as if it was sent automatically

Fixes

Application commands

• Always update global commands (in addition ...