teams_connector 0.1.0 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1637a8989e80ccddbd794e906543c29845f701ae2aa2241728cfc27c42eb4005
-  data.tar.gz: 4396ee9a4a861078e29a84b7e4f372505ad397d71ab4b93082476c40d9e984d5
+  metadata.gz: 46a69bacfa1eb6a6b46616d436ff4b8c7890db602ce30c7f082e004e53e161c3
+  data.tar.gz: e98ac0f36a4fc64a1ec41f100ce6b062dc4b1ff4579a2094e2b6d49530b2b5f3
 SHA512:
-  metadata.gz: 074b2bb7966fd01e514c8c089335e67ab8cdb643a64cef413d744307f441b6acd4523beba610caf5345383a6043b8ab80166d20f66e7bdec6762d21b8c1a8c3c
-  data.tar.gz: 010c32f3c62b14102603b3196124a671630d38c9d18d9a661dfb10324f9b1ebf47190d9e8098fa925ba013d29705fe9f80b2d25178a0a13149308c1d2b46d26b
+  metadata.gz: f5183b39ff855da474a6417861020f44b2933a4e93fbc497207eab427802e88a33d41511ca30c90390741baf85f39a72b30804ddf78a302f1247e49bfb3edd69
+  data.tar.gz: b68b7311f4ba4f7fd2b37c99bdc960fef80d0c7528fdad6a06002820df60131c0f4b5ae1eb2f5f08a9d57e54c5a7673ee96add2d9aca7219c76301ccc5d27f14

data/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,70 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ main ]
+  schedule:
+    - cron: '20 21 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'ruby' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Learn more about CodeQL language support at https://git.io/codeql-language-support
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v1
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 https://git.io/JvXDl
+
+    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+    #    and modify them (or add more) to build your code if your project
+    #    uses a compiled language
+
+    #- run: |
+    #   make bootstrap
+    #   make release
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

data/.github/workflows/ruby.yml

@@ -0,0 +1,35 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.6', '2.7', '3.0']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@473e4d8fe5dd94ee328fdfca9f8c9c7afc9dae5e
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake

data/CHANGES.md

@@ -1,5 +1,33 @@
 # Teams Connector Changelog
 
+0.1.4
+---
+- Add rudimentary testing method
+
+0.1.3
+---
+- Allow sending a notification to multiple channels at the same time
+
+0.1.2
+---
+- Use `TeamsConnector::Configuration#load_from_rails_credentials` to load encrypted channel URLs in your Rails environment
+
+0.1.1
+---
+- Adaptive Card Notification
+  - Send a more complex Adaptive Card instead of the basic Message Card
+- Builder
+  - Introduce Builder for [Adaptive Cards](https://docs.microsoft.com/en-us/outlook/actionable-messages/adaptive-card) generation
+  - Directly create messages with TeamsConnector::Notification::AdaptiveCard and the adaptive_card default template
+  - Output as JSON for creation of custom templates
+  - Supports
+    - Text
+    - Container
+    - Facts
+- Notification 
+  - Change constructor from numbered to named parameters
+  - Pretty print JSON to STDOUT with #pretty_print
+
 0.1.0
 ---
 - Initial commit of the Teams Connector gem

data/README.md

@@ -1,5 +1,8 @@
 # Teams Connector
 
+[![Gem Version](https://badge.fury.io/rb/teams_connector.svg)](https://badge.fury.io/rb/teams_connector)
+![RSpec](https://github.com/qurasoft/teams_connector/actions/workflows/ruby.yml/badge.svg)
+
 Welcome to Teams Connector. This gem allows you to easily send messages from your ruby project to Microsoft Teams channels.
 It integrates in your rails project, when you are using bundler or even in plain ruby projects.
 
@@ -22,16 +25,18 @@ Or install it yourself as:
     $ gem install teams_connector
 
 ## Usage
-After setting up the Incoming Webhook Connector four your Microsoft Teams channel, it is as simple as configuring the channel and creating a new `TeamsConnector::Notification`.
+After setting up the Incoming Webhook Connector for your Microsoft Teams channel, it is as simple as configuring the channel and creating a new `TeamsConnector::Notification`.
+
+The `channels` parameter can either be a single channel identifier or an array of multiple channel identifiers, that each will receive the notification. 
 
 ```ruby
-# Configuration
+# TeamsConnector initializer
 TeamsConnector.configure do |config|
   config.channel :channel_id, "https://<YOUR COMPLETE WEBHOOK URL GOES HERE>"
 end
 
 # Send a test card to your channel
-TeamsConnector::Notification.new(:test_card, :channel_id).deliver_later
+TeamsConnector::Notification.new(template: :test_card, channels: :channel_id).deliver_later
 
 # Send a card with a list of facts
 content = {
@@ -43,19 +48,88 @@ content = {
 }
 TeamsConnector::Notification::Message.new(:facts_card, "This is a summary", content).deliver_later
 ```
-This gem provides some basic templates in its default template path. You can also define your own templates in your own path. The default templates will be still available so you can mix and match.
 
-### Default templates
+### Secure Channel Configuration
+Since the Incoming Webhook Connector does not allow any authentication at the endpoint it is crucial that you keep your channel urls secret.
+At best nobody finds the url but it can also lead to spam or even faking of critical messages.
+
+In Rails provides the credentials functionality for [environmental security](https://edgeguides.rubyonrails.org/security.html#environmental-security). This mechanism can be used by TeamsConnector to load channels from an encrypted file. This also allows easy separation of production and development channel URLs.
+All channels are defined under the top-level entry `teams_connector` and will be identified by their key.
+```yaml
+# $ bin/rails credentials:edit
+teams_connector:
+  default: "<INSERT DEFAULT URL HERE>"
+  sales: "<INSERT URL FOR THE :sales CHANNEL HERE>"
+```
+
+After configuration of the credentials you can load the channels in your initializer.
+Since `#load_from_rails_configuration` is a wrapper around `#channel` both methods can be used together.
+
+```ruby
+# TeamsConnector initializer
+TeamsConnector.configure do |config|
+  config.load_from_rails_credentials
+  # After loading the :default channel is available and can be set as the default 
+  config.default = :default
+  config.channel :another_channel, "<URL>"
+end
+```
+
+### Templates
+This gem provides some basic templates in its default template path. You can also define your own templates in your own path.
+The default templates will be still available so you can mix and match.
+
+#### Default templates
 
 Template name | Description
 -----|-------
-:test_card | A simple text message without any configurable content for testing
+:adaptive_card | A card with the body of an adaptive card for more complex scenarios
 :facts_card | A card with title, subtitle and a list of facts
+:test_card | A simple text message without any configurable content for testing
+
+#### Custom Templates
+
+Custom templates are stored in the directory specified by the configuration option `template_dir`. As an array of strings, describing the path relative to the project root. When using Rails or Bundler their root is used, otherwise it is the current working directory.
+
+Templates are json files with the extension `.json.erb`. The file is parsed and populated by the ruby ERB module.
+
+#### Builder
+
+You can use TeamsConnector::Builder to create Adaptive Cards directly in ruby. YOu can output the result of the builder as JSON for future use with `TeamsController::Notification::AdaptiveCard#pretty_print`.
+
+```ruby
+builder = TeamsConnector::Builder.container do |content|
+  content << TeamsConnector::Builder.text("This is an introductory text for the following facts")
+  content << TeamsConnector::Builder.facts { |facts|
+    facts["Usage"] = "Testing the adaptive card builder"
+    facts["Quokka fact"] = "They are funny little creatures"
+  }
+end
+
+TeamsConnector::Notification::AdaptiveCard.new(content: builder).deliver_later
+```
+
+## Testing
+
+To test TeamsConnector integration in your application you can use the `:testing` method.
+Instead of performing real HTTP requests, an array in `TeamsConnector.testing.requests` is filled in chronological order.
+
+The request elements have the following structure:
+```ruby
+{
+  channel: :default,
+  template: :facts_card,
+  content: "rendered content",
+  time: Time.now
+}
+```
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+You can define the channels you use for testing in the file `bin/channels.yml` or directly in the `bin/console` script.
+
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing

data/bin/.gitignore

@@ -0,0 +1 @@
+channels.yml

data/bin/console

@@ -11,7 +11,22 @@ require "teams_connector"
 # Pry.start
 
 TeamsConnector.configure do |config|
-  config.channel :default, "<INSERT YOUR WEBHOOK URL HERE>"
+  if File.exist?("channels.yml")
+    # NOTE(Keune): The channels available in the console can be set in the file channels.yml. It contains a simple
+    # mapping of channel identifiers to webhook URLs. The channel identifier is loaded as a symbol.
+    #
+    # Example: default: "<INSERT YOUR WEBHOOK URL HERE>"
+    puts "Load channels specified by file"
+
+    require "yaml"
+    channels = YAML.load_file "channels.yml"
+    channels.each do |k, v|
+      config.channel k.to_sym, v
+    end
+  else
+    # NOTE(Keune): Specify the channels you want to have available in the console
+    config.channel :default, "<INSERT YOUR WEBHOOK URL HERE>"
+  end
   config.default = :default
   config.always_use_default = true
   config.method = :direct

data/lib/teams_connector/builder.rb

@@ -0,0 +1,60 @@
+module TeamsConnector
+  class Builder
+    attr_accessor :type, :content
+
+    def initialize
+      yield self
+    end
+
+    def self.text(text)
+      TeamsConnector::Builder.new { |entry| entry.text text }
+    end
+
+    def text(text)
+      @type = :text
+      @content = text
+    end
+
+    def self.container
+      TeamsConnector::Builder.new { |entry| entry.container { |items| yield items } }
+    end
+
+    def container
+      @type = :container
+      @content = []
+      yield @content
+    end
+
+    def self.facts
+      TeamsConnector::Builder.new { |entry| entry.facts { |facts| yield facts } }
+    end
+
+    def facts
+      @type = :facts
+      @content = {}
+      yield @content
+    end
+
+    def result
+      case @type
+      when :container
+        {
+          type: "Container",
+          items: @content.map { |element| element.result }
+        }
+      when :facts
+        {
+          type: "FactSet",
+          facts: @content.map { |fact| { title: fact[0], value: fact[1] } }
+        }
+      when :text
+        {
+          type: "TextBlock",
+          text: @content
+        }
+      else
+        raise TypeError, "The type #{@type} is not supported by the TeamsConnector::Builder"
+      end
+    end
+  end
+end

data/lib/teams_connector/configuration.rb

@@ -19,7 +19,7 @@ module TeamsConnector
     end
 
     def method=(method)
-      raise ArgumentError, "Method '#{method.to_s}' is not supported" unless [:direct, :sidekiq].include? method
+      raise ArgumentError, "Method '#{method.to_s}' is not supported" unless [:direct, :sidekiq, :testing].include? method
       raise ArgumentError, "Sidekiq is not available" if method == :sidekiq && !defined? Sidekiq
       @method = method
     end
@@ -27,5 +27,16 @@ module TeamsConnector
     def channel(name, url)
       @channels[name] = url;
     end
+
+    def load_from_rails_credentials
+      unless defined? Rails
+        raise RuntimeError, "This method is only available in Ruby on Rails."
+      end
+
+      webhook_urls = Rails.application.credentials.teams_connector!
+      webhook_urls.each do |entry|
+        channel(entry[0], entry[1])
+      end
+    end
   end
 end

data/lib/teams_connector/notification/adaptive_card.rb

@@ -0,0 +1,16 @@
+module TeamsConnector
+  class Notification::AdaptiveCard < Notification
+    attr_accessor :content
+
+    def initialize(template: :adaptive_card, content: {}, channel: TeamsConnector.configuration.default)
+      super(template: template, channel: channel)
+      if content.instance_of? TeamsConnector::Builder
+        @content = {
+          card: [content.result]
+        }
+      else
+        @content = content
+      end
+    end
+  end
+end

data/lib/teams_connector/notification/message.rb

@@ -3,7 +3,7 @@ module TeamsConnector
     attr_accessor :summary, :content
 
     def initialize(template, summary, content = {}, channel = TeamsConnector.configuration.default)
-      super(template, channel)
+      super(template: template, channels: channel)
       @summary = summary
       @content = content
     end

data/lib/teams_connector/notification.rb

@@ -1,14 +1,15 @@
 require 'erb'
+require 'json'
 require 'net/http'
 require 'teams_connector/post_worker' if defined? Sidekiq
 
 module TeamsConnector
   class Notification
-    attr_accessor :template, :channel
+    attr_accessor :template, :channels
 
-    def initialize(template, channel)
+    def initialize(template: nil, channels: TeamsConnector.configuration.default)
       @template = template
-      @channel = channel
+      @channels = channels.instance_of?(Array) ? channels : [channels]
     end
 
     def deliver_later
@@ -17,20 +18,34 @@ module TeamsConnector
       renderer = ERB.new(File.read(template_path))
       renderer.location = [template_path.to_s, 0]
 
-      url = TeamsConnector.configuration.channels[@channel]
-      url = TeamsConnector.configuration.channels[TeamsConnector.configuration.default] if TeamsConnector.configuration.always_use_default
-      raise ArgumentError, "The Teams channel '#{@channel}' is not available in the configuration." if url.nil?
-
       content = renderer.result(binding)
 
-      if TeamsConnector.configuration.method == :sidekiq
-        TeamsConnector::PostWorker.perform_async(url, content)
-      else
-        response = Net::HTTP.post(URI(url), content, { "Content-Type": "application/json" })
-        response.value
+      channels = TeamsConnector.configuration.always_use_default ? [TeamsConnector.configuration.default] : @channels
+      channels.each do |channel|
+        url = TeamsConnector.configuration.channels[channel]
+        raise ArgumentError, "The Teams channel '#{channel}' is not available in the configuration." if url.nil?
+
+        if TeamsConnector.configuration.method == :sidekiq
+          TeamsConnector::PostWorker.perform_async(url, content)
+        elsif TeamsConnector.configuration.method == :testing
+          TeamsConnector.testing.perform_request channel, @template, content
+        else
+          response = Net::HTTP.post(URI(url), content, { "Content-Type": "application/json" })
+          response.value
+        end
       end
     end
 
+    def pretty_print
+      template_path = find_template
+
+      renderer = ERB.new(File.read(template_path))
+      renderer.location = [template_path.to_s, 0]
+      content = renderer.result(binding)
+
+      puts JSON.pretty_generate(JSON.parse(content))
+    end
+
     private
 
     def find_template

data/lib/teams_connector/testing.rb

@@ -0,0 +1,13 @@
+module TeamsConnector
+  class Testing
+    attr_reader :requests
+
+    def initialize
+      @requests = []
+    end
+
+    def perform_request(channel, template, content)
+      @requests.push({channel: channel, content: content, template: template, time: Time.now})
+    end
+  end
+end

data/lib/teams_connector/version.rb

@@ -1,3 +1,3 @@
 module TeamsConnector
-  VERSION = "0.1.0"
+  VERSION = "0.1.4"
 end

data/lib/teams_connector.rb

@@ -2,10 +2,12 @@ require 'teams_connector/configuration'
 require 'teams_connector/version'
 require 'teams_connector/notification'
 require 'teams_connector/notification/message'
+require 'teams_connector/notification/adaptive_card'
+require 'teams_connector/builder'
 
 module TeamsConnector
   class << self
-    attr_accessor :configuration
+    attr_accessor :configuration, :testing
   end
 
   def self.configuration
@@ -20,6 +22,16 @@ module TeamsConnector
     yield configuration
   end
 
+  def self.testing
+    require 'teams_connector/testing'
+    @testing ||= Testing.new
+  end
+
+  def self.reset_testing
+    require 'teams_connector/testing'
+    @testing = Testing.new
+  end
+
   def self.project_root
     if defined?(Rails)
       return Rails.root

data/teams_connector.gemspec

@@ -33,9 +33,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.17"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "bundler", ">= 1.17"
+  spec.add_development_dependency "rake", ">= 10.0"
+  spec.add_development_dependency "rspec", ">= 3.0"
   spec.add_development_dependency "webmock"
   spec.add_development_dependency "sidekiq"
   spec.add_development_dependency "simplecov"

data/templates/teams_connector/adaptive_card.json.erb

@@ -0,0 +1,18 @@
+{
+  "type": "message",
+  "attachments": [
+    {
+      "contentType": "application/vnd.microsoft.card.adaptive",
+      "contentUrl": null,
+      "padding": "None",
+      "content": {
+        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+        "type": "AdaptiveCard",
+        "version": "1.2",
+        "body": [
+          <%= @content[:card].map {|k| k.to_json}.join(", ") %>
+        ]
+      }
+    }
+  ]
+}

metadata

@@ -1,55 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: teams_connector
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.4
 platform: ruby
 authors:
 - Lucas Keune
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-11-11 00:00:00.000000000 Z
+date: 2021-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.17'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.17'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
@@ -101,6 +101,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/codeql-analysis.yml"
+- ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
@@ -109,15 +111,20 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/.gitignore
 - bin/console
 - bin/setup
 - lib/teams_connector.rb
+- lib/teams_connector/builder.rb
 - lib/teams_connector/configuration.rb
 - lib/teams_connector/notification.rb
+- lib/teams_connector/notification/adaptive_card.rb
 - lib/teams_connector/notification/message.rb
 - lib/teams_connector/post_worker.rb
+- lib/teams_connector/testing.rb
 - lib/teams_connector/version.rb
 - teams_connector.gemspec
+- templates/teams_connector/adaptive_card.json.erb
 - templates/teams_connector/facts_card.json.erb
 - templates/teams_connector/test_card.json.erb
 homepage: https://github.com/Qurasoft/teams_connector