feature: chances of execution

README.md

@@ -9,7 +9,7 @@ The usage is very simple yet powerful:
 ```csharp
 ...
 using Navigator;
-...
+... 
 
 var builder = WebApplication.CreateBuilder(args);
 
@@ -19,14 +19,13 @@ builder.Services.AddNavigator(options =>
 {
     options.SetWebHookBaseUrl(builder.Configuration["BASE_WEBHOOK_URL"]!);
     options.SetTelegramToken(builder.Configuration["TELEGRAM_TOKEN"]!);
-    options.EnableTypingNotification();
 });
 
 var app = builder.Build();
 
 var bot = app.GetBot();
 
-// This action will be triggered if the user sends a message in the style of `/join <text>`.
+// This action will be triggered if the user sends a message in the style of `/join <text> <text>`.
 bot.OnCommand("join", async (INavigatorClient client, Chat chat, string[] parameters) =>
 {
     var result = string.Join(',', parameters);
@@ -39,6 +38,35 @@ app.MapNavigator();
 app.Run();
 ```
 
+# Getting Started
+
+After installing the [package](https://www.nuget.org/packages/Navigator/) you can start using it by first configuring Navigator:
+
+```csharp
+builder.Services.AddNavigator(options =>
+{
+    // Configuration here!
+});
+```
+
+Inside the AddNavigator method you can define the following options:
+
+- The WebHook base URL:`options.SetWebHookBaseUrl(string)`
+- The Telegram token: `options.SetTelegramToken(string)`
+- Optionally, the WebHook endpoint: `options.SetWebHookEndpoint(string)`
+- Optionally, allow multiple actions for the same update: `options.EnableMultipleActionsUsage()`
+- Optionally, enable the sending of chat actions (e.g. typing) notifications: `options.EnableChatActionNotification()`
+
+Continue by defining the actions of your bot using the different helper methods (see source code for more details). Here is a short example:
+
+Finally add the following line to map the endpoint to the navigator framework:
+
+```csharp
+app.MapNavigator();
+```
+
+This will start the server and will listen for incoming requests from Telegram. Your bot is good to go!
+
 # Examples
 
 Some examples can be found in the [samples](https://github.com/navigatorframework/navigator/src/) repository.

src/Navigator/Actions/BotActionInformation.cs

@@ -12,6 +12,11 @@ public record BotActionInformation
     /// </summary>
     public required UpdateCategory Category;
 
+    /// <summary>
+    ///     The chance of the <see cref="BotAction" /> being executed. Optional.
+    /// </summary>
+    public required double? Chances;
+
     /// <summary>
     ///     The <see cref="ChatAction" /> associtated with the <see cref="BotAction" />. Optional.
     /// </summary>

src/Navigator/Actions/Builder/BotActionBuilder.cs

@@ -27,6 +27,7 @@ public BotActionBuilder()
     private ushort Priority { get; set; }
     private TimeSpan? Cooldown { get; set; }
     private ChatAction? ChatAction { get; set; }
+    private double? Chance { get; set; }
 
     /// <summary>
     ///     Builds the bot action.
@@ -38,6 +39,7 @@ public BotAction Build()
         {
             ChatAction = ChatAction,
             Category = Category,
+            Chances = Chance,
             ConditionInputTypes = ConditionInputTypes,
             HandlerInputTypes = HandlerInputTypes,
             Name = Name ?? $"{_id}",
@@ -106,6 +108,17 @@ public BotActionBuilder SetCategory(UpdateCategory category)
         return this;
     }
 
+    /// <summary>
+    ///     Sets the chance of the <see cref="BotAction" /> being executed.
+    /// </summary>
+    /// <param name="chance">The chance to be set.</param>
+    /// <returns>An instance of <see cref="BotActionBuilder" /> to be able to continue configuring the <see cref="BotAction" />.</returns>
+    public BotActionBuilder WithChances(double chance)
+    {
+        Chance = chance;
+        return this;
+    }
+
     /// <summary>
     ///     Sets the priority of the <see cref="BotAction" />.
     /// </summary>

src/Navigator/Strategy/NavigatorStrategy.cs

@@ -177,6 +177,14 @@ private async IAsyncEnumerable<BotAction> FilterActionsThatCanHandleUpdate(IEnum
     /// <param name="update">The <see cref="Update" /> object that triggered the execution of the <see cref="BotAction" />.</param>
     private async Task ExecuteAction(BotAction action, Update update)
     {
+        if (action.Information.Chances is not null && Random.Shared.NextDouble() < action.Information.Chances)
+        {
+            _logger.LogDebug("Discarding action {ActionName} because of configured chances ({Chances})", action.Information.Name,
+                action.Information.Chances);
+
+            return;
+        }
+
         var numberOfInputs = action.Information.HandlerInputTypes.Length;
         object?[] arguments = new object[numberOfInputs];
 

src/Sample/Program.cs

@@ -9,7 +9,6 @@
 using Navigator.Configuration.Options;
 using Telegram.Bot;
 using Telegram.Bot.Types;
-using Chat = Navigator.Entities.Chat;
 
 var builder = WebApplication.CreateBuilder(args);
 
@@ -44,7 +43,7 @@
     var text = $"message received: {message.MessageId}";
 
     await client.SendTextMessageAsync(chat, text);
-}).WithCooldown(TimeSpan.FromSeconds(30));
+}).WithChances(0.5).WithCooldown(TimeSpan.FromSeconds(30));
 
 app.MapNavigator();