action_smser 1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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

@@ -0,0 +1,191 @@
+# ActionSmser
+
+Simple way to use SMS (Short Message Service) in the same way as ActionMailer (ActionSmser == ActionMailer).
+Includes also delivery reports and easy way to add custom gateways. See examples below.
+
+[<img src="https://secure.travis-ci.org/holli/action_smser.png" />](http://travis-ci.org/holli/action_smser)
+
+# Install
+
+
+## Common
+
+```
+Gemfile ->
+
+gem 'action_smser'
+
+# To use delivery reports
+bundle exec rake railties:install:migrations FROM=ActionSmser
+rake db:migrate
+```
+
+## SMS sending basic
+
+**Initializing**
+
+```
+in /config/initializers/active_smser.rb
+
+if Rails.env.development? || Rails.env.production?
+
+  ActionSmser.delivery_options[:delivery_method] = :simple_http
+  ActionSmser.delivery_options[:simple_http] = {
+      :server => 'server_to_use', :username => 'username', :password => 'password',
+      :use_ssl => true
+  }
+
+  # ActionSmser.delivery_options[:save_delivery_reports] = true
+end
+
+```
+
+**Mailer classes**
+
+```
+in /app/mailers/test_sms.rb
+
+class TestSms < ActionSmser::Base
+  def hello_user(to, from, user)
+    str = "Hello #{user}."
+    sms(:to => to, :from => from, :body => str)
+  end
+end
+```
+
+**Sending sms**
+
+```
+E.g. from console or controller
+
+sms = TestSms.hello_user('358407573855', '358407573855', "Olli")
+sms.deliver
+```
+
+## Delivery methods
+
+Optional delivery methods can be used by creating classes under "ActionSmser::DeliveryMethods" and referring
+them as downcase infos. See example of :simple_http at
+https://github.com/holli/action_smser/blob/master/lib/action_smser/delivery_methods/simple_http.rb
+
+## Delivery reports
+
+Gem handles collecting and analysing of delivery reports. This enables you to make sure that your gateway works.
+
+Delivery reports and a summary can be seen at http://localhost.inv:3000/action_smser/delivery_reports/ .
+Summary includes info about the amount of sent sms, delivery times, types of sms, etc.
+
+Parsers and access infos can be implemented by creating a class with admin_access and process_delivery_report methods.
+See example below.
+
+```
+in /config/initializers/active_smser.rb
+
+ActionSmser.delivery_options[:save_delivery_reports] = true
+
+
+class ActionSmserConfigExample
+  # This returns true if we can show delivery reports page, return true if always permissed
+  def self.admin_access(controller)
+    if controller.session[:admin_logged].blank?
+      return controller.session[:admin_logged]
+    else
+      return true
+    end
+  end
+
+  # This has to return array of hashes. In hash msg_id is the key and other params are updated to db
+  def self.process_delivery_report(params)
+    processable_array = []
+    if params["DeliveryReport"] && params["DeliveryReport"]["message"]
+      reports = params["DeliveryReport"]["message"]
+      reports = [reports] unless reports.is_a?(Array)
+
+      reports.each do |report|
+        processable_array << {'msg_id' => report['id'], 'status' => report['status']}
+      end
+    end
+
+    return processable_array
+  end
+end
+
+
+# This is simple proc that is used in a before filter, if it returns true it allows access to
+# http://localhost.inv:3000/action_smser/delivery_reports/ with infos about delivery reports
+ActionSmser.delivery_options[:admin_access] = ActionSmserConfigExample
+
+# This gives ActionSmser way to parse infos from pushed to gateway
+# Params is all params gotten in the request
+test_gateway = lambda
+
+# Parser is used with urls like
+# /action_smser/delivery_reports/gateway_commit/test_gateway
+# where 'test_gateway' is the part that is used for locating right parser.
+ActionSmser.delivery_options[:gateway_commit] = {'test_gateway' => test_gateway}
+
+
+```
+
+## Other options
+
+Observers can be used by implementing "delivery_observer" in your sms class
+
+```
+class TestSms < ActionSmser::Base
+  def hello_user(to, from, user)
+    str = "Hello #{user}."
+    sms(:to => to, :from => from, :body => str)
+  end
+
+  def after_delivery(response_from_delivery_method)
+    puts "Done with delivery"
+  end
+end
+```
+
+## Testing
+
+Default delivery method is "test_array". It saves delivered sms to ActionSmser::DeliveryMethods::TestArray.deliveries to help test your own software.
+Its normal array, see sms by 'ActionSmser::DeliveryMethods::TestArray.deliveries' and
+clear it between tests by 'ActionSmser::DeliveryMethods::TestArray.deliveries.clear'
+
+
+```
+E.g. in functional tests
+
+test "should send right msg" do
+  ActionSmser::DeliveryMethods::TestArray.deliveries.clear
+  get :send_invite, :user_id => 1
+
+  assert_equal 1, ActionSmser::DeliveryMethods::TestArray.deliveries.size
+  assert_equal "UserSms.sent_invite", ActionSmser::DeliveryMethods::TestArray.deliveries.first.sms_type
+end
+
+```
+
+# Requirements
+
+Gem has been tested with ruby 1.8.7, 1.9.2 and Rails 3.1.
+
+[<img src="https://secure.travis-ci.org/holli/action_smser.png" />](http://travis-ci.org/holli/action_smser)
+
+http://travis-ci.org/#!/holli/action_smser
+
+# Support
+
+Submit suggestions or feature requests as a GitHub Issue or Pull Request. Remember to update tests. Tests are quite extensive.
+
+
+### Similar gems
+
+There are many gems to use custom gateways but none of them had a possibility to create classes like smser. Also these don't have
+delivery reporting.
+
+- https://github.com/dwilkie/action_sms
+- https://github.com/forrestgrant/textr
+
+# Licence
+
+This project rocks and uses MIT-LICENSE. (http://www.opensource.org/licenses/mit-license.php)
+

data/Rakefile

@@ -0,0 +1,39 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ActionSmser'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/assets/javascripts/action_smser/delivery_reports.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/app/assets/stylesheets/action_smser/application.css

@@ -0,0 +1,7 @@
+/*
+ * This is a manifest file that'll automatically include all the stylesheets available in this directory
+ * and any sub-directories. You're free to add application-wide styles to this file and they'll appear at
+ * the top of the compiled file, but it's generally better to create a new file per style scope.
+ *= require_self
+ *= require_tree . 
+*/

data/app/assets/stylesheets/action_smser/delivery_reports.css

@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/

data/app/assets/stylesheets/scaffold.css

@@ -0,0 +1,56 @@
+body { background-color: #fff; color: #333; }
+
+body, p, ol, ul, td {
+  font-family: verdana, arial, helvetica, sans-serif;
+  font-size:   13px;
+  line-height: 18px;
+}
+
+pre {
+  background-color: #eee;
+  padding: 10px;
+  font-size: 11px;
+}
+
+a { color: #000; }
+a:visited { color: #666; }
+a:hover { color: #fff; background-color:#000; }
+
+div.field, div.actions {
+  margin-bottom: 10px;
+}
+
+#notice {
+  color: green;
+}
+
+.field_with_errors {
+  padding: 2px;
+  background-color: red;
+  display: table;
+}
+
+#error_explanation {
+  width: 450px;
+  border: 2px solid red;
+  padding: 7px;
+  padding-bottom: 0;
+  margin-bottom: 20px;
+  background-color: #f0f0f0;
+}
+
+#error_explanation h2 {
+  text-align: left;
+  font-weight: bold;
+  padding: 5px 5px 5px 15px;
+  font-size: 12px;
+  margin: -7px;
+  margin-bottom: 0px;
+  background-color: #c00;
+  color: #fff;
+}
+
+#error_explanation ul li {
+  font-size: 12px;
+  list-style: square;
+}

data/app/controllers/action_smser/application_controller.rb

@@ -0,0 +1,4 @@
+module ActionSmser
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/action_smser/delivery_reports_controller.rb

@@ -0,0 +1,63 @@
+module ActionSmser
+  class DeliveryReportsController < ApplicationController
+
+    def gateway_commit
+
+      updated_count = 0
+
+      
+      if !ActionSmser.delivery_options[:gateway_commit].blank? &&
+          !ActionSmser.delivery_options[:gateway_commit][params['gateway']].blank?
+
+        ActionSmser::Logger.info("Gateway_commit found parser for gateway: #{params['gateway']}")
+
+        dr_array = ActionSmser.delivery_options[:gateway_commit][params['gateway']].send(:process_delivery_report, params)
+
+        if !dr_array.blank?
+          dr_array.each do |dr_update|
+            msg_id = dr_update["msg_id"]
+            dr = ActionSmser::DeliveryReport.where(:msg_id => msg_id).first
+
+            if dr
+              dr_update.each_pair do |key, value|
+                dr.send("#{key}=", value) if dr.attribute_names.include?(key.to_s)
+              end
+
+
+              if dr.save
+                updated_count += 1
+                ActionSmser::Logger.info("Gateway_commit updated item with id: #{msg_id}, params: #{dr_update.inspect}")
+              else
+                ActionSmser::Logger.info("Gateway_commit problem updating item with id: #{msg_id}, params: #{dr_update.inspect}")
+              end
+            else
+              ActionSmser::Logger.info("Gateway_commit not found item with id: #{msg_id}, params: #{dr_update.inspect}")
+            end
+          end
+        end
+      end
+
+      if updated_count > 0
+        render :text => "Updated info for #{updated_count} items"
+      else
+        render :text => "Not saved"
+      end
+    end
+
+    before_filter :admin_access_only, :except => :gateway_commit
+
+    def index
+
+    end
+
+    def admin_access_only
+      if !ActionSmser.delivery_options[:admin_access].blank? && ActionSmser.delivery_options[:admin_access].send(:admin_access, self)
+        return true
+      else
+        render :text => "Forbidden, only for admins", :status => 403
+        return false
+      end
+    end
+
+  end
+end

data/app/models/action_smser/delivery_report.rb

@@ -0,0 +1,30 @@
+module ActionSmser
+  class DeliveryReport < ActiveRecord::Base
+
+    def self.build_from_sms(sms, to, msg_id)
+      @delivery_report = self.new
+
+      [:from, :body, :sms_type].each do |var|
+        @delivery_report.send("#{var}=", sms.send(var))
+      end
+      @delivery_report.to = to
+      @delivery_report.msg_id = msg_id
+      @delivery_report.status = "LOCAL_SENT"
+      @delivery_report
+    end
+
+    def self.create_from_sms(sms, to, sms_id)
+      @delivery_report = self.build_from_sms(sms, to, sms_id)
+      @delivery_report.save
+      @delivery_report
+    end
+
+    def status=(stat, skip_log = false)
+      self[:status] = stat
+      self.status_updated_at = Time.now
+      self.log = "" if self.log.nil?
+      self.log += "#{Time.now.to_s(:db)}: #{stat}\n" if !skip_log
+    end
+
+  end
+end

data/app/views/action_smser/delivery_reports/index.html.erb

@@ -0,0 +1,143 @@
+
+<%
+params['time_span'] ||= 'Last Month'
+
+time_span = case params['time_span'].to_s.downcase
+  when 'previous week'
+    2.weeks.ago..1.week.ago
+  when 'last month'
+    1.month.ago..2.minutes.ago
+  else
+    1.week.ago..2.minutes.ago
+  end
+%>
+
+
+<h1>Delivery Reports Summary for <%= params['time_span'] %></h1>
+
+
+Show summary:
+<%= link_to 'Last week', delivery_reports_path(:time_span => 'Last Week') %>,
+<%= link_to 'Week before that', delivery_reports_path(:time_span => 'Previous Week') %> or
+<%= link_to 'Last month', delivery_reports_path(:time_span => 'Last Month') %>.
+
+<h2>Delivered Within (hour:min:sec)</h2>
+
+<%
+  ar = ActionSmser::DeliveryReport.where(:created_at => time_span)
+  ar_delivered = ar.where(:status => 'delivered')
+  total = ar.count
+  total_delivered = ar_delivered.count
+%>
+
+<% if ActiveRecord::Base.connection.adapter_name.downcase.to_s.include?("mysql") %>
+
+  <table>
+    <tr>
+      <th>DeliveryTime</th>
+      <th>Sms</th>
+      <th>% of sent sms</th>
+      <th>% of delivered sms</th>
+    </tr>
+
+    <% ["00:00:30", "00:01:00", "00:02:00", "00:10:00", "00:30:00", "00:90:00", "24:00:00", "48:00:00"].each do |time| %>
+      <% dev_count = ar_delivered.where('TIMEDIFF(status_updated_at, created_at) < ?', time).count %>
+      <tr>
+        <td><%= time %></td>
+        <td><%= dev_count %></td>
+        <td><%= number_to_percentage(100.0 * dev_count / total, :precision => 2) %></td>
+        <td><%= number_to_percentage(100.0 * dev_count / total_delivered, :precision => 2) %></td>
+      </tr>
+    <% end %>
+
+  </table>
+
+<% else %>
+  Delivery report uses timediff sql and has only been tested with MySql. Disabled with other adapters for now.
+<% end %>
+
+<h2>DeliveryReport Statuses</h2>
+<ul>
+<%
+   quest = ActionSmser::DeliveryReport.where(:created_at => time_span)
+   total = quest.count
+   grouped_by_status = quest.group(:status).count.each do |key, val| %>
+
+    <li>
+      <strong><%= key %></strong>:
+      &nbsp;&nbsp;
+      <%= val %> sms
+      &nbsp;&nbsp;
+      (<strong><%= number_to_percentage(100.0 * val / total, :precision => 2) %></strong>)
+    </li>
+<% end %>
+</ul>
+
+<h2>By Sms Type</h2>
+<table>
+  <tr>
+    <th>SmsType</th>
+    <th>Count</th>
+    <th>% of total</th>
+    <th>Delivered count</th>
+    <th>Delivery %</th>
+  </tr>
+
+<%
+   quest = ActionSmser::DeliveryReport.where(:created_at => time_span)
+   total = quest.count
+   grouped_by_status = quest.group(:sms_type).count.each do |key, val| %>
+   <tr>
+     <td><strong><%= key %></strong></td>
+     <td><%= val %></td>
+     <td><strong><%= number_to_percentage(100 * val / total, :precision => 2) %></strong></td>
+     <td><%= sms_count = ActionSmser::DeliveryReport.where(:created_at => time_span).where(:sms_type => key).where(:status => 'delivered').count %></td>
+     <td><strong><%= number_to_percentage(100 * sms_count / val, :precision => 2) %></strong></td>
+   </tr>
+<% end %>
+</table>
+
+
+<hr>
+
+<% items_within_page = 20 %>
+<h1 id="delivery_reports_list"><%= items_within_page %> delivery_reports ordered by created_at</h1>
+
+<%
+offset = params[:offset].to_i
+offset = 0 if offset < -0
+%>
+
+<p>
+  <strong>List offset: <%= offset %>.</strong>
+  Add
+  <%= link_to("- #{items_within_page}",  delivery_reports_path(:offset => offset-items_within_page, :anchor => 'delivery_reports_list')) unless offset == 0 %>
+  <%= link_to "+ #{items_within_page}",  delivery_reports_path(:offset => offset+items_within_page, :anchor => 'delivery_reports_list') %>
+  to offset
+</p>
+
+<table style="margin-top: 20px;">
+  <tr>
+    <th>Created_at</th>
+    <th>Msg id</th>
+    <th>Status</th>
+    <th>Status updated at</th>
+    <th>Recipient</th>
+    <th>Sender</th>
+    <th>Text body</th>
+  </tr>
+
+<% ActionSmser::DeliveryReport.order('created_at DESC').offset(offset).first(items_within_page).each do |delivery_report| %>
+  <tr>
+    <td style="white-space: nowrap;"><%= delivery_report.created_at %></td>
+    <td><%= delivery_report.msg_id %></td>
+    <td><%= delivery_report.status %></td>
+    <td style="white-space: nowrap;"><%= delivery_report.status_updated_at %></td>
+    <td><%= delivery_report.to %></td>
+    <td><%= delivery_report.from %></td>
+    <td><%= delivery_report.body %></td>
+  </tr>
+<% end %>
+</table>
+
+