nuntius 0.1.1 → 1.0.27

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 736ed78b3a455b90aad20c47ba9bf6c3946cb7d45dc064c33d689a622ac40f18
+  data.tar.gz: c2f9abeeffe69fe5f28df8af6b0ff1c72c3c73d743b9156f0a12ed6daca3d1a9
+SHA512:
+  metadata.gz: a6fe800fc712a05dc2a35166a28a6d3c0d41f248365ca1cdb3f529f1430e77ca11553342cc0681490b1aaad952de6f87b89412f8329501e79765c556efa3428f
+  data.tar.gz: 4e79093e36ffeb8967aa5568a064b41828c33dcd3da32bf87ff0a5ed3504f5c3dc2794560c237254e63ed042a521442d3c51e57ca54690f209057e5bc29b73a5

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2018 Tom de Grunt
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,93 +1,229 @@
-# Nuntius:
+# Nuntius
 
-> A messenger, reporter, courier, bearer of news or tidings
+Nuntius offers messaging and notifications for ActiveRecord models in Ruby on Rails applications.
 
-Nuntius is a simple scheme to send and receive messages in a cryptographicaly secure and compatible way.
+## Setup
+
+Add Nuntius to your Gemfile and run bundle install to install it.
+
+Create an initializer (config/initializers/messaging.rb) and configure as desired:
+
+```ruby
+Nuntius.setup do
+  # Have Nuntius log to the Rails.logger
+  config.logger = Rails.logger
+
+  # Allow custom events (default = false)
+  # Enable this option to allow use of Nuntius with a Hash
+  config.allow_custom_events = true
+
+  # Configure the transport you want to use
+
+  # Enable e-mail
+  config.transport :mail
+  # Enable push notifications
+  config.transport :push
+  # Enable SMS
+  config.transport :sms
+  # Enable voice
+  config.transport :voice
+  # Enable Slack
+  config.transport :slack
+
+  # Configure providers for each of the transports you enabled above.
+  # Advised is to either do this using credentials, environment variables, or somewhere in a model (securely stored away).
+  config.provider :slack, transport: :slack, settings: lambda { |_message|
+    Rails.application.credentials[:slack]
+  }
+end
+```
+
+Mount the Rails engine in your routes.rb to enable Nuntius' maintenance pages:
+
+```ruby
+Rails.application.routes.draw do
+  # your own routes ...
+  mount Nuntius::Engine, at: '/messaging', as: 'nuntius' # change the path and aliases at your own discretion
+end
+```
+
+To enable you to send messages with Nuntius you need to make one or more ActiveRecord models nuntiable:
+
+```ruby
+class Car < ApplicationRecord
+  nuntiable
+end
+```
+
+Additionally you need to define an extension of the Nuntius::BaseMessenger for the same model with a matching name (in app/messengers):
+
+```ruby
+class CarMessenger < Nuntius::BaseMessenger
+  def your_event(car, params)
+    # your optional logic here
+  end
+end
+```
+
+If you are using the state_machines-activemodel gem you can pass use_state_machine: true to the
+nuntiable call, this will automatically define empty methods for these events on the model's
+messenger class if they are not defined already.
+
+Additionally the use_state_machine option will add an after_commit hook to the state machine
+to automatically trigger the event for the state transition.
 
 ## Usage
 
-### Encript a Message
+### With templates
+
+Usually you would call Nuntius programatically with code by using Templates. In this case you would use for example:
 
 ```ruby
-  require 'nuntius'
-
-  sender = Nuntius::Key.new( File.read('private_key_path') )
-  messenger = Nuntius::Mesenger.new({
-    :key => sender
-  })
-
-  receiver = Nuntius::Key.new( File.read('public_key_path') )
-
-  envelope = messenger.wrap({
-    :message => "Message Content",
-    :to => receiver
-  })
-
-  envelope.data
-    # => The encripted message
-  envelope.key
-    # => The encripted message key
-  envelope.signature
-    # => The encripted message signature
+ Nuntius.event(:your_event, car)
 ```
 
-### Decript a message
+When custom events are enabled you can also do the following:
 
 ```ruby
-  require 'nuntius'
+ Nuntius.event('shipped', { shipped: { to: 'test@example.com', ref: 'Test-123'} }, attachments: [ { url: 'http://example.com' } ])
+```
 
-  receiver = Nuntius::Key.new( File.read('private_key_path') )
-  messenger = Nuntius::Mesenger.new({
-    :key => receiver
-  })
+For the above cases you need to define templates, this is done with the maintenace pages under
+/messaging/admin/templates (/messaging is whatever you have defined in your routes file).
 
-  sender = Nuntius::Key.new( File.read('public_key_path') )
+When Nuntius#message is called a message will be sent for every matching template. To allow you to
+send different messages under different circumstances you can specify a template_scope on the messenger
+class that uses the template's metadata in combination with the nuntiable object to determine whether
+or not the template should be used.
 
-  envelope = Nuntius::Envelope.new({
-    :data => 'The encripted message'
-    :key => 'The encripted message key'
-    :signature => 'The encripted message signature'
-  })
+### Timebased events
 
-  message = messenger.unwrap({
-    :envelope => envelope,
-    :from => sender
-  })
+If you want to send messages based on time intervals you can add such events to your messenger with the
+timebased_scope class method like so:
 
-  message
-    # => The verified and decripted raw message
+```ruby
+class CarMessenger < Nuntius::BaseMessenger
+  # time_range is a range, for a before scope the time_range the interval is added to the current
+  # time, the end of the range is 1 hour from the start.
+  timebased_scope :before_tuneup do |time_range, metadata|
+    cars = Car.where(tuneup_at: time_range)
+    cars = cars.where(color: metadata['color']) if metadata['color'].present?
+    cars
+  end
+
+  # For an after scope the time_range the interval is taken from the current time, the end of the
+  # range is 1 hour from its start.
+  timebased_scope :after_tuneup do |time_range, metadata|
+    cars = Car.where(tuneup_at: time_range)
+    cars = cars.where(color: metadata['color']) if metadata['color'].present?
+    cars
+  end
+end
 ```
 
-## Encription Scheme
+This method also requires you to configure a template using the maintenance pages. When you choose
+a timebased scope as an event you will be prompted to enter an interval, you can enter anything in the
+following formats:
 
-Under the hood Nuntius is just a wrapper around OpenSSL and by default uses [RSA]( http://en.wikipedia.org/wiki/RSA_%28algorithm%29 ), [AES](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard) in [CBC mode](http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation#Cipher-block_chaining_.28CBC.29) and [SHA512](http://en.wikipedia.org/wiki/SHA512) to encript/decript and sign/verify the messages and [URL Safe Base64](http://en.wikipedia.org/wiki/Base64#RFC_4648) to encode/decode the results.
+- N minute(s)
+- N hour(s)
+- N day(s)
+- N week(s)
+- N month(s)
 
-The whole scheme can be sumarized in 4 steps:
+To send timebased messages you need to execute Nuntius::TimestampBasedMessagesRunner.call, you could do this
+in a cronjob every 5 minutes with "bundle exec rails runner Nuntius::TimestampBasedMessagesRunner.call"
 
- * The message is encripted using AES-256-CBC with a randomly generated key.
- * The key is then encrypted using the receiver's public RSA key.
- * The encripted message's digest is calculated using SHA512 and then signed using the sender's private RSA key.
- * Finally the encripted message, the encripted key and the signed digest are encoded using the RFC4648 URL Safe Base 64 encoding
+### Direct
 
-In other terms, encrypting a message with nuntius is the same as doing
+Another more direct way of using Nuntius is by just instantiating a message:
 
 ```ruby
-  require 'openssl'
+ Nuntius::Message.new(to: 'tom@boxture.com', subject: 'Test', text: 'Test text', nuntiable: channel).deliver_as(:mail)
+```
 
-  sender = OpenSSL::PKey::RSA.new( File.read('sender_private_key') )
-  receiver = OpenSSL::PKey::RSA.new( File.read('receiver_public_key') )
+or
 
-  cipher = OpenSSL::Cipher.new("AES-256-CBC").encrypt
-  
-  key = receiver.public_encrypt( cipher.random_key )
+```ruby
+user = User.find(1)
+user.messages.new(to: 'test@example.com', subject: 'Test', text: 'Test text').deliver_as(:mail)
+```
 
-  data = cipher.update("message") + cipher.final
+Here we still need a nuntiable object, in case provider settings can differ from object to object.
 
-  signature = receiver.private_encrypt( OpenSSL::Digest::SHA512.new(data).digest )
+You can also define custom events, which take a scope and an event name:
 
-  result = {
-    :data => [data].pack("m0").tr("+/","-_").gsub("=","")
-    :key => [key].pack("m0").tr("+/","-_").gsub("=","")
-    :signature => [signature].pack("m0").tr("+/","-_").gsub("=","")
-  }
+```ruby
+Nuntius.event('packed', packing: {smurrefluts: 'hatseflats'})
+```
+
+The main key of the hash passed will also be the liquid variable.
+
+### Inbound
+
+Inbound messages are also possible, currently mail/IMAP and Twilio inbound SMS are supported.
+
+## Transports
+
+### Mail
+
+#### AWS SES
+
+In case you use AWS SES, you can use the SNS Feedback Notifications to automatically mark messages as read, or deal with complaints and bounces. Create a AWS SNS topic, with a HTTPS subscription with the following URL (pattern):
+
+Use the following URL: https://<host>/messaging/feedback/awssns
+
+The actual URL may be different depending on your routing setup.
+
+The subscription will automatically be confirmed.
+
+Next in AWS SES, configure the SNS topic to receive feedback notifications for Bounce, Complaint and Delivery and include original headers.
+
+### SMS
+
+### Push
+
+### Voice
+
+#### Twilio
+
+Information on voice TWIML is here: https://www.twilio.com/docs/voice/twiml/gather
+You can try voices here: https://www.twilio.com/console/voice/twiml/text-to-speech
+
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+    <Say language="nl-NL">
+        Hallo, dit is een bericht van Boxture!
+        <break strength="x-weak" time="100ms"/>
+        <p>We geven je zo je wachtwoord-herstel-code, dus pak een pen en schrijf mee.</p>
+    </Say>
+    <Gather input="dtmf" numDigits="1" action="{%raw%}{{url}}{%endraw%}/code">
+       <Say language="nl-NL">Druk een toets om verder te gaan.</Say>
+    </Gather>
+    <Redirect>{%raw%}{{url}}{%endraw%}/code</Redirect>
+</Response>
+
+---
+path: /code
+---
+<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+  <Gather input="dtmf" numDigits="1">
+     <Say language="nl-NL">
+      <s>Je code is:</s>
+      <break strength="x-weak" time="100ms"/>
+      <prosody rate="x-slow"><say-as interpret-as="character">1 n a x d 8 b</say-as></prosody>
+      <break strength="x-weak" time="1s"/>
+      Druk een toets om te herhalen, of hang op.
+     </Say>
+  </Gather>
+  <Redirect>{%raw%}{{url}}{%endraw%}/code</Redirect>
+</Response>
+```
+
+## Testing
+
+```
+bundle exec sidekiq -C test/dummy/config/sidekiq.yml -r test/dummy
 ```

data/Rakefile

@@ -1 +1,62 @@
-require "bundler/gem_tasks"
+# frozen_string_literal: true
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Nuntius'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+  t.warning = false
+end
+
+task default: :test
+
+# Adds the Auxilium semver task
+spec = Gem::Specification.find_by_name 'auxilium'
+load "#{spec.gem_dir}/lib/tasks/semver.rake"
+
+namespace :nuntius do
+  namespace :webpacker do
+    desc 'Install deps with yarn'
+    task :yarn_install do
+      Dir.chdir(File.join(__dir__, '../..')) do
+        system 'yarn install --no-progress --production'
+      end
+    end
+
+    desc 'Compile JavaScript packs using webpack for production with digests'
+    task compile: %i[yarn_install environment] do
+      Webpacker.with_node_env('production') do
+        if Nuntius.webpacker.commands.compile
+          # Successful compilation!
+        else
+          # Failed compilation
+          exit!
+        end
+      end
+    end
+  end
+end

data/app/controllers/nuntius/admin/campaigns_controller.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_dependency 'nuntius/application_admin_controller'
+
+module Nuntius
+  module Admin
+    class CampaignsController < ApplicationAdminController
+      before_action :set_objects, except: [:index]
+
+      def index
+        @campaigns = Nuntius::Campaign.visible.order(created_at: :desc)
+      end
+
+      def new
+        render :edit
+      end
+
+      def create
+        @campaign.save
+        respond_with :admin, @campaign, action: :edit
+      end
+
+      def show
+        redirect_to :edit_admin_campaign, status: :see_other
+      end
+
+      def edit; end
+
+      def update
+        saved = @campaign.update(campaign_params)
+
+        if saved && params[:commit] == 'send'
+          @campaign.publish! if @campaign.can_publish?
+          redirect_to :edit_admin_campaign, status: :see_other
+        else
+          respond_with :admin, @campaign
+        end
+      end
+
+      private
+
+      def set_objects
+        @campaign = params[:id] ? Nuntius::Campaign.visible.find(params[:id]) : Nuntius::Campaign.new(campaign_params)
+        @lists = Nuntius::List.visible
+        @layouts = Nuntius::Layout.visible
+        @messages = Nuntius::Message.where(campaign: @campaign)
+      end
+
+      def campaign_params
+        return unless params[:campaign]
+
+        params.require(:campaign).permit(:name, :transport, :layout_id, :list_id, :from, :subject, :text, :html)
+      end
+    end
+  end
+end

data/app/controllers/nuntius/admin/layouts/attachments_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Nuntius
+  module Admin
+    module Layouts
+      class AttachmentsController < ApplicationController
+        before_action :set_objects
+
+        def index; end
+
+        def create
+          params[:attachments].each do |file|
+            @layout.attachments.attach(file)
+          end
+        end
+
+        def destroy
+          attachment = @layout.attachments.find_by(id: params[:id])
+          attachment&.purge
+
+          render :create
+        end
+
+        private
+
+        def set_objects
+          @layout = Nuntius::Layout.visible.find(params[:layout_id]) if params[:layout_id]
+        end
+      end
+    end
+  end
+end

data/app/controllers/nuntius/admin/layouts_controller.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_dependency 'nuntius/application_admin_controller'
+
+module Nuntius
+  module Admin
+    class LayoutsController < ApplicationAdminController
+      def index
+        @layouts = Nuntius::Layout.visible.order(:name)
+      end
+
+      def new
+        @layout = Nuntius::Layout.new
+        render :edit
+      end
+
+      def create
+        @layout = Nuntius::Layout.new(layout_params)
+        @layout.save
+        respond_with :admin, @layout
+      end
+
+      def edit
+        @layout = Nuntius::Layout.visible.find(params[:id])
+      end
+
+      def show
+        redirect_to :edit_admin_layout, status: :see_other
+      end
+
+      def update
+        @layout = Nuntius::Layout.visible.find(params[:id])
+        @layout.update(layout_params)
+        respond_with :admin, @layout
+      end
+
+      def destroy
+        @layout = Nuntius::Layout.visible.find(params[:id])
+        @layout.destroy
+        respond_with @layout
+      end
+
+      private
+
+      def layout_params
+        params.require(:layout).permit(:name, :data, :metadata_yaml)
+      end
+    end
+  end
+end

data/app/controllers/nuntius/admin/lists/subscribers_controller.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_dependency 'nuntius/application_admin_controller'
+
+module Nuntius
+  module Admin
+    module Lists
+      class SubscribersController < ApplicationAdminController
+        before_action :set_objects
+
+        def index
+          @subscribers = @list.subscribers.all
+        end
+
+        def new
+          @subscriber = @list.subscribers.new
+          render :edit
+        end
+
+        def create
+          @subscriber = @list.subscribers.new(subscriber_params)
+          @subscriber.save
+          # FIXME: This should redirect to list
+          respond_with :admin, :list, @subscriber, collection_location: -> { nuntius.admin_list_url(@list) }, location: -> { nuntius.admin_list_url(@list) }, status: :see_other
+        end
+
+        def edit
+          @subscriber = @list.subscribers.find(params[:id])
+        end
+
+        def update
+          @subscriber = @list.subscribers.find(params[:id])
+          @subscriber.update(subscriber_params)
+          # FIXME: This should redirect to list
+          respond_with :admin, :list, @subscriber, collection_location: -> { nuntius.admin_list_url(@list) }, location: -> { nuntius.admin_list_url(@list) }, status: :see_other
+        end
+
+        private
+
+        def subscriber_params
+          params.require(:subscriber).permit(:first_name, :last_name, :email, :phone_number, tags: [])
+        end
+
+        def set_objects
+          @list = List.find(params[:list_id])
+        end
+      end
+    end
+  end
+end

data/app/controllers/nuntius/admin/lists_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_dependency 'nuntius/application_admin_controller'
+
+module Nuntius
+  module Admin
+    class ListsController < ApplicationAdminController
+
+      def index
+        @lists = Nuntius::List.visible.order(:name)
+      end
+
+      def new
+        @list = Nuntius::List.new
+        render :edit
+      end
+
+      def create
+        @list = Nuntius::List.create(list_params)
+        respond_with :admin, @list
+      end
+
+      def show
+        redirect_to :edit_admin_list, status: :see_other
+      end
+
+      def edit
+        @list = Nuntius::List.visible.find(params[:id])
+      end
+
+      def update
+        @list = Nuntius::List.visible.find(params[:id])
+        @list.update(list_params)
+        respond_with :admin, @list
+      end
+
+      private
+
+      def set_objects; end
+
+      def list_params
+        params.require(:list).permit(:name)
+      end
+    end
+  end
+end

data/app/controllers/nuntius/admin/locales_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_dependency 'nuntius/application_admin_controller'
+
+module Nuntius
+  module Admin
+    class LocalesController < ApplicationAdminController
+      def index
+        @locales = Nuntius::Locale.visible.order(:key)
+      end
+
+      def new
+        @locale = Nuntius::Locale.new
+        render :edit
+      end
+
+      def create
+        @locale = Nuntius::Locale.new(locale_params)
+        @locale.save
+        respond_with :admin, @locale
+      end
+
+      def show
+        redirect_to :edit_admin_locales, status: :see_other
+      end
+
+      def edit
+        @locale = Nuntius::Locale.visible.find(params[:id])
+      end
+
+      def update
+        @locale = Nuntius::Locale.visible.find(params[:id])
+        @locale.update(locale_params)
+        respond_with :admin, @locale
+      end
+
+      private
+
+      def set_objects; end
+
+      def locale_params
+        params.require(:locale).permit(:key, :data, :metadata_yaml, :data_yaml)
+      end
+    end
+  end
+end