Release 3231/add mention functionality (#4)

* [lib/msteams_hermes/msteams/entities/*.rb]: Add classes to support mentions

* [adaptive_card.rb]: Add support for entities
which encapsulate the mention type
https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format?tabs=adaptive-md%2Cdesktop%2Cconnector-html#mention-support-within-adaptive-cards

* [lib/msteams_hermes/components/base.rb]: Remove superfluous 'require'

* [mention.rb]: Remove accessors
They aren't used as of now

* [lib/msteams_hermes/msteams/entities/mention.rb]: Add guard exceptions

* mention_spec.rb]: Add rspec test for mention class

* [lib/msteams_hermes/components/adaptive_card.rb]: Formatting change

* [adaptive_card_spec.rb]: Incorporate entities key that comes with supporting mentions

* [message_spec.rb]: Adapt test to accomodate 'msteams' and 'entities' key
Necessary to support mentions

* [lib/msteams_hermes/msteams/entities/base.rb]: Address rubocop issue

* [entities/mention.rb]: Address rubocop issue

* [lib/msteams_hermes/msteams/entities/mention.rb]: Address rubocop issue

* [entities/mention.rb]: Maybe this change for 2.7 rubocopping?

* Update lib/msteams_hermes/msteams/entities/mention.rb

Co-authored-by: Rafael Rocha <[email protected]>

* Update lib/msteams_hermes/msteams/entities/mention.rb

Co-authored-by: Rafael Rocha <[email protected]>

* [mention_spec.rb]: Add rspec test of 'to_hash'

* Update lib/msteams_hermes/components/adaptive_card.rb

Co-authored-by: Jason Franklin <[email protected]>

* Update lib/msteams_hermes/components/adaptive_card.rb

Co-authored-by: Jason Franklin <[email protected]>

* Update lib/msteams_hermes/msteams/entities/mention.rb

Co-authored-by: Jason Franklin <[email protected]>

* Revert "Update lib/msteams_hermes/msteams/entities/mention.rb"
This reverts commit 168e105.
The parameters of the mention class should not be optional

* [adaptive_card_spec.rb]: Adapt tests to comply with ea70fb

* [spec/msteams_hermes/entities/mention_spec.rb]: Rubocopping

Co-authored-by: Rafael Rocha <[email protected]>
Co-authored-by: Jason Franklin <[email protected]>

lib/msteams_hermes/components/adaptive_card.rb

@@ -12,22 +12,26 @@ module Components
     # https://adaptivecards.io/explorer/AdaptiveCard.html
     ##
     class AdaptiveCard < Base
-      attr_reader :body, :actions
+      attr_reader :body, :actions, :entities
 
-      def initialize(body:, actions: nil)
+      def initialize(body:, actions: nil, entities: [])
         @body = body
         raise "AdaptiveCard `body` must be an Array" unless @body.is_a? Array
 
         @actions = actions
         raise "AdaptiveCard `actions` must be an Array" unless @actions.nil? || @actions.is_a?(Array)
+
+        @entities = entities
+        raise "AdaptiveCard `entities` must be an Array" unless @entities.nil? || @entities.is_a?(Array)
       end
 
       def to_hash
         {
           type: "AdaptiveCard",
           version: "1.5",
           body: body.map(&:to_hash),
-          actions: actions&.map(&:to_hash)
+          actions: actions&.map(&:to_hash),
+          msteams: { entities: entities.map(&:to_hash) }
         }
       end
     end

lib/msteams_hermes/components/base.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "msteams_hermes/components/base"
-
 module MsTeamsHermes
   ##
   # Module containing Microsoft's components representations

lib/msteams_hermes/msteams/entities/base.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MsTeamsHermes
+  module MsTeams
+    module Entities
+      # Super class for entities to enforce overridding the `to_hash` method
+      class Base
+        def to_hash
+          raise "Should be implemented on the subclass"
+        end
+      end
+    end
+  end
+end

lib/msteams_hermes/msteams/entities/mention.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "msteams_hermes/msteams/entities/base"
+
+module MsTeamsHermes
+  module MsTeams
+    module Entities
+      ##
+      # A class representing Microsoft's Msteams.Mention object
+      # https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format?tabs=adaptive-md%2Cdesktop%2Cconnector-html#user-mention-in-incoming-webhook-with-adaptive-cards
+      ##
+      class Mention < Base
+        attr_reader :mention_reference, :mention_string, :user_id
+
+        def initialize(text:, name:, id:)
+          raise "`text` must be a string" unless text.is_a? String
+          raise "`text` must contain <at>...</at>" unless text.include?("<at>") && text.include?("</at>")
+          raise "`id` must be a string" unless text.is_a? String
+
+          @mention_reference = text # String surrounded by <at>string</at> that marks the mention section in a text
+          @mention_string = name # allows for overriding the mention_reference
+          @user_id = id
+        end
+
+        def to_hash
+          {
+            type: "mention",
+            text: mention_reference,
+            mentioned: {
+              id: user_id,
+              name: mention_string
+            }
+          }
+        end
+      end
+    end
+  end
+end

spec/msteams_hermes/components/adaptive_card_spec.rb

@@ -44,7 +44,8 @@
             title: nil,
             tooltip: nil
           }
-        ]
+        ],
+        msteams: { entities: [] }
       }
 
       expect(component.to_hash).to eq hash

spec/msteams_hermes/entities/mention_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "msteams_hermes/msteams/entities/mention"
+
+RSpec.describe MsTeamsHermes::MsTeams::Entities::Mention do
+  describe "#initialize" do
+    it "throws an error if text parameter does not contain <at> and </at>" do
+      expect do
+        MsTeamsHermes::MsTeams::Entities::Mention.new(text: "foo", name: "something", id: "123")
+      end.to raise_error("`text` must contain <at>...</at>")
+    end
+  end
+
+  describe "#to_hash" do
+    subject(:mention) do
+      MsTeamsHermes::MsTeams::Entities::Mention.new(text: mention_segment_in_text,
+                                                    name: mention_string,
+                                                    id: user_id)
+    end
+
+    let(:mention_segment_in_text) { "<at>original text reference</at>" }
+    let(:user_id) { "[email protected]" }
+    let(:mention_string) { "Text to show up as mention" }
+
+    it "renders the hash object" do
+      expected_hash = {
+        type: "mention",
+        text: mention_segment_in_text,
+        mentioned: {
+          id: user_id,
+          name: mention_string
+        }
+      }
+
+      expect(mention.to_hash).to eq(expected_hash)
+    end
+  end
+end

spec/msteams_hermes/message_spec.rb

@@ -50,7 +50,10 @@
                   facts: [fact]
                 }
               ],
-              actions: nil
+              actions: nil,
+              msteams: {
+                entities: []
+              }
             }
           }
         ]