microsoft_teams_incoming_webhook_ruby 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0c571083b61043cc97cf99f320f91c54fa2bc23724553d3eb4cc862573fcbd7
-  data.tar.gz: c54e9204da1e10d72a5ca2c8542d3aa612544af37c2f6c1bc3d3c03f1d7ac7de
+  metadata.gz: 39b4271906654ad2de7ff8ec2498b3aff1fd06254d2907cf2c7057ce56953b2c
+  data.tar.gz: f0aafd0aa31ef6f89e9d757754006bd02a96eab0771cfe79469df497b8fb4558
 SHA512:
-  metadata.gz: 5d837c4e2ecc294a05666d620be29de5df21a96a6ff6ad444e0f6df7ba5619a138f1ed4aec96cdc962cf98d099d82f3d92fa7b5e7bed4befa7c1efb8831af860
-  data.tar.gz: 5f396da0271d571114229429a8c05f9adeb68b52c9b7238b2e467f2ee9b0880a179b877019397cd67ea94888e717b76c5dc8f89730ea094ee78e6852cfbbd10f
+  metadata.gz: 9378f2e20942e2b655e11f3d7f0fb185f20f21086e2ddb4a593824bdd308dbfb4286107965f1b10fc9e6507ab81bfd632be8d9d2a0541e141610f0798b377d6e
+  data.tar.gz: 6560b0e12bcd0787255fc63351cecc2e71700caa4d30665426f1b853415c7a05a7736e8b56fb96d47c4667311084c289c596b141c622ce38e7bfeacd87451be4

data/.github/workflows/publish_to_rubygems.yml

@@ -1,7 +1,6 @@
 name: Publish to Rubygems
 
 on:
-  workflow_dispatch:
   release:
     types: [created]
 

data/.gitignore

@@ -7,4 +7,6 @@
 /spec/reports/
 /tmp/
 .rspec_status
-Gemfile.lock
+/Gemfile.lock
+*.gem
+*.log

data/README.md

@@ -41,12 +41,17 @@ The first step before using this gem is to configure the connector inside your T
 
 For this purpose, please check the official documentation from Microsoft. It's listed below some useful links:
 
-- https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook#create-incoming-webhook-1
+- https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook
+- https://techcommunity.microsoft.com/t5/microsoft-365-pnp-blog/how-to-configure-and-use-incoming-webhooks-in-microsoft-teams/ba-p/2051118
 - https://www.youtube.com/watch?v=amvh4rzTCS0
 
-### 'Hello World' message sending, for testing
+After the configuration, keep your generated Incoming Webhook URL in a secret and secure way.
 
-Once you have Incoming Webhook configured in Teams channels, you can send a sample `Hello World` message (for testing) with such code like this:
+You will use it (the URL) in next sections of README.
+
+### Hello World message sending
+
+Once you have configured Incoming Webhook inside your Teams channels, you can send a very simple `Hello World` message:
 
 ```ruby
 require 'microsoft_teams_incoming_webhook_ruby'
@@ -59,83 +64,324 @@ end
 message.send
 ```
 
-Note that there are 2 keys that is the minimum required to define a valid message:
+Note that there are 2 keys that is the minimum required to define a valid message for Teams:
  - `url`: The URL of Incoming Webhook connector, generated via Microsoft Teams
  - `text`: The text of your message
 
-There are many other possible keys to be sent to Microsoft Incoming Webhook API. But pay attention to always send at least this 2 keys.
+There are many other possible keys to be sent to Microsoft Incoming Webhook API.
+But pay attention to always send **at least** the 2 keys.
+
+### Gem public interface
+
+The `MicrosoftTeamsIncomingWebhookRuby::Message` class has 3 main methods:
+
+- `new`: Initialization of object. You need to pass a block as parameter, containing the message structure. This structure will be converted automatically to JSON and be sent to Microsoft Incoming Webhook API.
+- `builder`: Message builder object, that allows add/redefine/remove fields arbitrarily.
+- `send`: Invocation of Incoming Webhook API, using HTTPS.
+
+### Message structure
+
+The Microsoft Incoming Webhook API allows us to send a variety of fields, that will result in diferents cards displayed in Teams channels.
+
+Because of this, the gem will not enforce any schema in message structure. The only required parameters are `url` and `text`. Any other options will be accepted, considering that Microsoft Incoming Webhook API accepts it.
 
 ### Configuration of message structure lately of initialization
 
-### Error handling
+The message structure and its fields can be defined in two moments:
+
+- Initialization of `MicrosoftTeamsIncomingWebhookRuby::Message` object
+- After object initialization, but before `send` method call
+
+🚨 You can add/replace/remove any fields arbitrarily, but keeping at least the minimum required fields (`url` and `text`). Otherwise, an error will be generated when invoke `send` method.
+
+Below there are some examples of this manipulation:
+
+- Initialization of attributes in `MicrosoftTeamsIncomingWebhookRuby::Message` object
 
-You can build the message with any supported [card fields](https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#card-fields).
-This example is taken directly from [Microsoft Docs](https://docs.microsoft.com/en-us/outlook/actionable-messages/send-via-connectors)
 ```ruby
-require "ms_teams"
+require 'microsoft_teams_incoming_webhook_ruby'
 
-message = MsTeams::Message.new do |m|
-    m.url = "https://outlook.office.com/...."
-    m.themeColor = "0072C6"
-    m.title = "Visit the Outlook Dev Portal"
-    m.text = "Click **Learn More** to learn more about Actionable Messages!"
-    m.potentialAction = [
-        {
-            "@type": "ActionCard",
-            "name": "Send Feedback",
-            "inputs": [{
-                "@type": "TextInput",
-                "id": "feedback",
-                "isMultiline": true,
-                "title": "Let us know what you think about Actionable Messages"
-            }],
-            "actions": [{
-                "@type": "HttpPOST",
-                "name": "Send Feedback",
-                "isPrimary": true,
-                "target": "http://..."
-            }]
-        },
-        {
-            "@type": "OpenUri",
-            "name": "Learn More",
-            "targets": [
-                { "os": "default", "uri": "https://docs.microsoft.com/outlook/actionable-messages" }
-            ]
-        }
-    ]
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url                        = 'YOUR INCOMING WEBHOOK URL HERE'
+  m.text                       = 'Hello World!'
+
+  m.my_arbitrary_field         = 'My value'
+  m.my_another_arbitrary_field = { my: 'value' }
 end
 
-# You can edit any field after the message has been built by modifying the `builder` object
-message.builder.text = "Something new"
+message.send
+```
+
+- Adding of attribute after object initialization, but before `send` method call
+
+```ruby
+require 'microsoft_teams_incoming_webhook_ruby'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url  = 'YOUR INCOMING WEBHOOK URL HERE'
+  m.text = 'Hello World!'
+end
+
+message.builder.my_arbitrary_field         = 'My value'
+message.builder.my_another_arbitrary_field = { my: 'value' }
 
 message.send
 ```
 
-Error Handling:
+- Removing of attributes after object initialization, but before `send` method call
 
-A non-2xx response code will raise a `MsTeams::Message::FailedRequest` error
+```ruby
+require 'microsoft_teams_incoming_webhook_ruby'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url                     = 'YOUR INCOMING WEBHOOK URL HERE'
+  m.text                    = 'Hello World!'
+
+  m.my_custom_field         = 'My custom value'
+end
+
+message.builder.delete_field :my_custom_field
+
+message.send
+```
+
+- Redefing of attributes after object initialization, but before `send` method call
+
+```ruby
+require 'microsoft_teams_incoming_webhook_ruby'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url                     = 'YOUR INCOMING WEBHOOK URL HERE'
+  m.text                    = 'Hello World!'
+
+  m.my_custom_field         = 'My custom value'
+end
+
+message.builder.my_custom_field = 'Updated value'
+
+message.send
+```
+
+In case of keys that starts with **@**, is necessary to use brackets notation:
+
+```ruby
+require 'microsoft_teams_incoming_webhook_ruby'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url          = 'YOUR INCOMING WEBHOOK URL HERE'
+  m.text         = 'Hello World!'
+  m['@my_field'] = 'Lorem ipsum'
+end
+
+message.builder['@my_another_new_field'] = 'Ipsum valorium'
+
+message.send
+```
+
+### Error handling
+
+If the builder object turn itself invalid before invocation of `send` method, the gem will raise a `MicrosoftTeamsIncomingWebhookRuby::Message::Error::InvalidMessage` exception:
 
 ```ruby
-# ...
+require 'microsoft_teams_incoming_webhook_ruby'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url          = 'YOUR INCOMING WEBHOOK URL HERE'
+  m.text         = 'Hello World!'
+end
+
+message.delete_field :url
+
 begin
-    message.send
-rescue MsTeams::Message::FailedRequest => e
-    # Do stuff
+  message.send
+rescue MicrosoftTeamsIncomingWebhookRuby::Message::Error::InvalidMessage
+  puts 'Your message structure is invalid!'
 end
 ```
 
+```ruby
+require 'microsoft_teams_incoming_webhook_ruby'
+
+begin
+  message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+    m.my_only_one_field = 'Lorem ipsum'
+  end
+rescue MicrosoftTeamsIncomingWebhookRuby::Message::Error::InvalidMessage
+  puts 'Your message structure is invalid'
+end
+```
 
-Building an invalid message object will immediately raise an error
+If a non-successful response code be returned by API (1xx, 4xx or 5xx), the gem will raise a `MicrosoftTeamsIncomingWebhookRuby::Message::Error::FailedRequest` exception:
 
 ```ruby
-message = MsTeams::Message.new do |m|
-    # no url set
-    m.text = "Hello World"
+require 'microsoft_teams_incoming_webhook_ruby'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url          = 'YOUR INCOMING WEBHOOK URL HERE'
+  m.text         = 'My message'
+end
+
+begin
+  message.send
+rescue MicrosoftTeamsIncomingWebhookRuby::Message::Error::FailedRequest
+  puts 'Microsoft API is down, broken, or your network failed!'
+end
+```
+
+## Examples
+
+You can build and send messages with any supported card fields provided by Microsoft:
+
+- https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using
+- https://adaptivecards.io/samples
+- https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference
+- https://amdesigner.azurewebsites.net
+- https://messagecardplayground.azurewebsites.net
+- https://docs.microsoft.com/en-us/outlook/actionable-messages/adaptive-card
+- https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/what-are-webhooks-and-connectors
+
+We will provide below some ready-to-go examples to be used, based on API described in links above.
+
+### Minimal
+
+```ruby
+require 'microsoft_teams_incoming_webhook_ruby'
+
+webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url  = webhook_url
+  m.text = 'Minimal message!'
+end
+
+message.send
+```
+
+### Theme color
+
+```ruby
+require 'microsoft_teams_incoming_webhook_ruby'
+
+webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url        = webhook_url
+  m.text       = 'Message with theme color!'
+  m.themeColor = 'FF0000'
+end
+
+message.send
+```
+
+### Title
+
+```ruby
+require 'microsoft_teams_incoming_webhook_ruby'
+
+webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url   = webhook_url
+  m.text  = 'Message with title!'
+  m.title = 'FF0000'
+end
+
+message.send
+```
+
+### Summary
+
+```ruby
+require 'microsoft_teams_incoming_webhook_ruby'
+
+webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url     = webhook_url
+  m.text    = 'Message with summary!'
+  m.summary = 'My summary'
+end
+
+message.send
+```
+
+### Potential action
+
+```ruby
+require 'microsoft_teams_incoming_webhook_ruby'
+
+webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url   = webhook_url
+  m.text  = 'Message with potential action!'
+  m.potentialAction = [
+    {
+      '@type': 'ActionCard',
+      'name': 'Answer',
+      'inputs': [
+        {
+          '@type': 'TextInput',
+          'id': 'title',
+          'isMultiline': true,
+          'title': 'Your text here'
+        }
+      ],
+      'actions': [
+        {
+          '@type': 'HttpPOST',
+          'name': 'Send my answer',
+          'isPrimary': true,
+          'target': 'https://example.com/example'
+        }
+      ]
+    },
+    {
+      '@type': 'HttpPOST',
+      'name': 'Make another action',
+      'target': 'https://example.com/example2'
+    },
+    {
+      '@type': 'OpenUri',
+      'name': 'Open a URL',
+      'targets': [
+        {
+          'os': 'default',
+          'uri': 'https://github.com/pedrofurtado/microsoft_teams_incoming_webhook_ruby'
+        }
+      ]
+    }
+  ]
 end
 
-> ArgumentError (`url` cannot be nil. Must be set during initialization)
+message.send
+```
+
+### Sections
 
+```ruby
+require 'microsoft_teams_incoming_webhook_ruby'
+
+webhook_url = 'YOUR INCOMING WEBHOOK URL HERE'
+
+message = MicrosoftTeamsIncomingWebhookRuby::Message.new do |m|
+  m.url   = webhook_url
+  m.text  = 'Message with sections!'
+  m.sections = [
+    {
+      'text': 'Lorem ipsum vastium',
+      'activityTitle': 'John Smith',
+      'activitySubtitle': '01/01/1990, 11:45AM',
+      'activityImage': 'https://connectorsdemo.azurewebsites.net/images/MSC12_Oscar_002.jpg',
+      'facts': [
+        { 'name': 'Repository:', 'value': 'my-repo' },
+        { 'name': 'Issue #:',    'value': '123456789' }
+      ]
+    }
+  ]
+end
+
+message.send
 ```
 
 ## Execute tests/specs
@@ -153,13 +399,9 @@ docker build -t microsoft_teams_incoming_webhook_ruby_specs .
 docker run -v $(pwd):/app/ -it microsoft_teams_incoming_webhook_ruby_specs
 ```
 
-## Demo
-
-...
-
-## Another similar gems for reference
+## Similar gems for reference
 
-There are similar open source libraries that shares the same purpose of this gem, such as:
+There are similar and great open source libraries that shares the same purpose of this gem, such as:
 
 - https://github.com/toririn/teams_incoming_clients
 - https://github.com/shirts/microsoft-teams-ruby

data/lib/microsoft_teams_incoming_webhook_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MicrosoftTeamsIncomingWebhookRuby
-  VERSION = '0.1.0'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsoft_teams_incoming_webhook_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Pedro Furtado