[PM-17562] Update documentation for event integrations (#5924)

* [PM-17562] Update documentation for event integrations

* Fix SonarQube suggestion, bring ASB event listener in line with integration listener

* Apply suggestions from code review

Co-authored-by: Matt Bishop <mbishop@bitwarden.com>

* Updates to README - PR fixes, additional context, tense alignment

* Fix the formatting for inlined code snippets

* Add links to different sections; remove inline code formatting in favor of single bacticks for JSON

---------

Co-authored-by: Matt Bishop <mbishop@bitwarden.com>

src/Core/AdminConsole/Models/Data/EventIntegrations/IIntegrationMessage.cs

@@ -0,0 +1,15 @@
+#nullable enable
+
+using Bit.Core.Enums;
+
+namespace Bit.Core.AdminConsole.Models.Data.EventIntegrations;
+
+public interface IIntegrationMessage
+{
+    IntegrationType IntegrationType { get; }
+    string MessageId { get; set; }
+    int RetryCount { get; }
+    DateTime? DelayUntilDate { get; }
+    void ApplyRetry(DateTime? handlerDelayUntilDate);
+    string ToJson();
+}

src/Core/AdminConsole/Models/Data/EventIntegrations/IntegrationHandlerResult.cs

@@ -0,0 +1,18 @@
+#nullable enable
+
+namespace Bit.Core.AdminConsole.Models.Data.EventIntegrations;
+
+public class IntegrationHandlerResult
+{
+    public IntegrationHandlerResult(bool success, IIntegrationMessage message)
+    {
+        Success = success;
+        Message = message;
+    }
+
+    public bool Success { get; set; } = false;
+    public bool Retryable { get; set; } = false;
+    public IIntegrationMessage Message { get; set; }
+    public DateTime? DelayUntilDate { get; set; }
+    public string FailureReason { get; set; } = string.Empty;
+}

src/Core/AdminConsole/Models/Data/EventIntegrations/IntegrationMessage.cs

@@ -0,0 +1,46 @@
+#nullable enable
+
+using System.Text.Json;
+using Bit.Core.Enums;
+
+namespace Bit.Core.AdminConsole.Models.Data.EventIntegrations;
+
+public class IntegrationMessage : IIntegrationMessage
+{
+    public IntegrationType IntegrationType { get; set; }
+    public required string MessageId { get; set; }
+    public required string RenderedTemplate { get; set; }
+    public int RetryCount { get; set; } = 0;
+    public DateTime? DelayUntilDate { get; set; }
+
+    public void ApplyRetry(DateTime? handlerDelayUntilDate)
+    {
+        RetryCount++;
+
+        var baseTime = handlerDelayUntilDate ?? DateTime.UtcNow;
+        var backoffSeconds = Math.Pow(2, RetryCount);
+        var jitterSeconds = Random.Shared.Next(0, 3);
+
+        DelayUntilDate = baseTime.AddSeconds(backoffSeconds + jitterSeconds);
+    }
+
+    public virtual string ToJson()
+    {
+        return JsonSerializer.Serialize(this);
+    }
+}
+
+public class IntegrationMessage<T> : IntegrationMessage
+{
+    public required T Configuration { get; set; }
+
+    public override string ToJson()
+    {
+        return JsonSerializer.Serialize(this);
+    }
+
+    public static IntegrationMessage<T>? FromJson(string json)
+    {
+        return JsonSerializer.Deserialize<IntegrationMessage<T>>(json);
+    }
+}

src/Core/AdminConsole/Models/Data/EventIntegrations/IntegrationTemplateContext.cs

@@ -0,0 +1,38 @@
+#nullable enable
+
+using Bit.Core.AdminConsole.Entities;
+using Bit.Core.Entities;
+using Bit.Core.Enums;
+using Bit.Core.Models.Data;
+
+namespace Bit.Core.AdminConsole.Models.Data.EventIntegrations;
+
+public class IntegrationTemplateContext(EventMessage eventMessage)
+{
+    public EventMessage Event { get; } = eventMessage;
+
+    public string DomainName => Event.DomainName;
+    public string IpAddress => Event.IpAddress;
+    public DeviceType? DeviceType => Event.DeviceType;
+    public Guid? ActingUserId => Event.ActingUserId;
+    public Guid? OrganizationUserId => Event.OrganizationUserId;
+    public DateTime Date => Event.Date;
+    public EventType Type => Event.Type;
+    public Guid? UserId => Event.UserId;
+    public Guid? OrganizationId => Event.OrganizationId;
+    public Guid? CipherId => Event.CipherId;
+    public Guid? CollectionId => Event.CollectionId;
+    public Guid? GroupId => Event.GroupId;
+    public Guid? PolicyId => Event.PolicyId;
+
+    public User? User { get; set; }
+    public string? UserName => User?.Name;
+    public string? UserEmail => User?.Email;
+
+    public User? ActingUser { get; set; }
+    public string? ActingUserName => ActingUser?.Name;
+    public string? ActingUserEmail => ActingUser?.Email;
+
+    public Organization? Organization { get; set; }
+    public string? OrganizationName => Organization?.DisplayName();
+}

src/Core/AdminConsole/Models/Data/EventIntegrations/SlackIntegration.cs

@@ -0,0 +1,5 @@
+#nullable enable
+
+namespace Bit.Core.AdminConsole.Models.Data.EventIntegrations;
+
+public record SlackIntegration(string token);

src/Core/AdminConsole/Models/Data/EventIntegrations/SlackIntegrationConfiguration.cs

@@ -0,0 +1,5 @@
+#nullable enable
+
+namespace Bit.Core.AdminConsole.Models.Data.EventIntegrations;
+
+public record SlackIntegrationConfiguration(string channelId);

src/Core/AdminConsole/Models/Data/EventIntegrations/SlackIntegrationConfigurationDetails.cs

@@ -0,0 +1,5 @@
+#nullable enable
+
+namespace Bit.Core.AdminConsole.Models.Data.EventIntegrations;
+
+public record SlackIntegrationConfigurationDetails(string channelId, string token);

src/Core/AdminConsole/Models/Data/EventIntegrations/WebhookIntegrationConfiguration.cs

@@ -0,0 +1,5 @@
+#nullable enable
+
+namespace Bit.Core.AdminConsole.Models.Data.EventIntegrations;
+
+public record WebhookIntegrationConfiguration(string url);

src/Core/AdminConsole/Models/Data/EventIntegrations/WebhookIntegrationConfigurationDetails.cs

@@ -0,0 +1,5 @@
+#nullable enable
+
+namespace Bit.Core.AdminConsole.Models.Data.EventIntegrations;
+
+public record WebhookIntegrationConfigurationDetails(string url);