textris 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2fd3e9eb6888e74d470bde1afe44a785ecbec855
+  data.tar.gz: b32e98392db542754742c288849125af7f7b28fd
+SHA512:
+  metadata.gz: 352443cb1e2001e43ae58a11d863f80ec5b11b84956aae8f5cd654f75a0da56f313d79b683b27194a5768d8485733a5f11a016366cbf404450bb1ba6bf5b620b
+  data.tar.gz: 4b90542d764e5b78a0cd682065f5df71050cb05f0a971d21979a43627c2e631b8f55b7420efa97fe2ef07fe2416799e4112688a337755355bdfc0e7533322a4a

data/README.md

@@ -0,0 +1,118 @@
+# Textris
+
+Simple gem for implementing texter classes which allow sending SMS messages in similar way to how e-mails are implemented and sent with ActionMailer-based mailers.
+
+Unlike similar gems, **Textris** has some unique features:
+
+- phone number E164 validation and normalization with the [Phony](https://github.com/floere/phony) gem
+- multiple, per-environment configurable delivery methods
+- e-mail proxy allowing to inspect messages using [Mailinator](https://mailinator.com/) or similar service
+- support for testing using self-explanatory `Textris::Base.deliveries`
+- simple, extensible code written from the ground up instead of copying *ActionMailer*
+
+## Installation
+
+Add to `Gemfile`:
+
+    gem 'textris'
+
+And run:
+
+    bundle install
+
+## Usage
+
+Place texter classes in `app/texters` (e.g. `app/texters/user_texter.rb`):
+
+    class UserTexter < Textris::Base
+      default :from => "Our Team <+48 666-777-888>"
+
+      def welcome(user)
+        @user = user
+
+        text :to => @user.phone
+      end
+    end
+
+Place relevant view templates in `app/views/<texter_name>/<action_name>.text.*`, (e.g. `app/views/user_texter/welcome.text.erb`):
+
+    Welcome to our system, <%= @user.name %>!
+
+Invoke them from application logic:
+
+    class User < ActiveRecord::Base
+      after_create do
+        UserTexter.welcome(self).deliver
+      end
+    end
+
+## Testing
+
+Access all messages that were sent with the `:test` delivery:
+
+    Textris::Base.deliveries
+
+You may want to clear the delivery queue before each test:
+
+    before(:each) do
+      Textris::Base.deliveries.clear
+    end
+
+Keep in mind that messages targeting multiple phone numbers, like:
+
+    text :to => ['48111222333', '48222333444']
+
+will yield multiple message deliveries, each for specific phone number.
+
+## Configuration
+
+You can change default settings by placing them in any of environment files, like `development.rb` or `test.rb`, or setting them globally in `application.rb`.
+
+Choose the delivery method:
+
+    # Don't send anything, access your messages via Textris::Base.deliveries
+    config.textris_delivery_method = :test
+
+    # Send e-mails instead of SMSes in order to inspect their content
+    config.textris_delivery_method = :mail
+
+Configure the mail delivery:
+
+    # E-mail sender, here: "our-team-48666777888@test.app-name.com"
+    config.textris_mail_from_template = '%{from_name:d}-%{from_phone}@%{env:d}.%{app:d}.com'
+
+    # E-mail target, here: "app-name-test-48111222333-texts@mailinator.com"
+    config.textris_mail_to_template = '%{app:d}-%{env:d}-%{to_phone}-texts@mailinator.com'
+
+    # E-mail subject, here: "User texter: Welcome"
+    config.textris_mail_subject_template = '%{texter:dh} texter: %{action:h}'
+
+    # E-mail body, here: "Welcome to our system, Mr Jones!"
+    config.textris_mail_body_template = '%{content}'
+
+### Template interpolation
+
+You can use the following interpolations in your mail templates:
+
+- `app`: application name (like `AppName`)
+- `env`: enviroment name (like `test` or `production`)
+- `texter`: texter name (like `User`)
+- `action`: action name (like `welcome`)
+- `from_name`: name of the sender (like `Our Team`)
+- `from_phone`: phone number of the sender (like `48666777888`)
+- `to_phone`: phone number of the recipient (like `48111222333`)
+- `content`: message content (like `Welcome to our system, Mr Jones!`)
+
+You can add optional interpolation modifiers using the `%{variable:modifiers}` syntax. These are most useful for making names e-mail friendly. The following modifiers are available:
+
+- `d`: dasherize (for instance, `AppName` becomes `app-name`)
+- `h`: humanize (for instance, `user_name` becomes `User name`)
+- `p`: format phone (for instance, `48111222333` becomes `+48 111 222 333`)
+
+## Contributing
+
+1. Fork it (https://github.com/visualitypl/codegrade/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/lib/textris.rb

@@ -0,0 +1,8 @@
+require 'action_controller'
+require 'action_mailer'
+
+require 'textris/base'
+require 'textris/message'
+require 'textris/delivery'
+require 'textris/delivery/test'
+require 'textris/delivery/mail'

data/lib/textris/base.rb

@@ -0,0 +1,75 @@
+require 'render_anywhere'
+
+module Textris
+  class Base
+    include RenderAnywhere
+
+    class << self
+      def deliveries
+        ::Textris::Delivery::Test.messages
+      end
+
+      def with_defaults(options)
+        (@defaults || {}).merge(options)
+      end
+
+      protected
+
+      def default(options)
+        @defaults ||= {}
+        @defaults.merge!(options)
+      end
+
+      private
+
+      def method_missing(method_name, *args)
+        self.new(method_name, *args).call_action
+      end
+    end
+
+    class RenderingController < RenderAnywhere::RenderingController
+      def default_url_options
+        ActionMailer::Base.default_url_options || {}
+      end
+    end
+
+    def initialize(action, *args)
+      @action = action
+      @args   = args
+    end
+
+    def call_action
+      send(@action, *@args)
+    end
+
+    protected
+
+    def text(options = {})
+      set_instance_variables_for_rendering
+
+      options = self.class.with_defaults(options)
+      options.merge!(
+        :texter  => self.class,
+        :action  => @action,
+        :content => options[:body].is_a?(String) ? options[:body] : render(
+          :template => template_name, :formats => ['text']))
+
+      ::Textris::Message.new(options)
+    end
+
+    private
+
+    def template_name
+      class_name  = self.class.to_s.underscore.sub('texter/', '')
+      action_name = @action
+
+      "#{class_name}/#{action_name}"
+    end
+
+    def set_instance_variables_for_rendering
+      instance_variables.each do |var|
+        set_instance_variable(var.to_s.sub('@', ''), instance_variable_get(var))
+      end
+    end
+  end
+end

data/lib/textris/delivery.rb

@@ -0,0 +1,16 @@
+module Textris
+  module Delivery
+    module_function
+
+    def get
+      case Rails.application.config.try(:textris_delivery_method).to_s
+      when 'mail'
+        ::Textris::Delivery::Mail
+      when 'test'
+        ::Textris::Delivery::Test
+      else
+        ::Textris::Delivery::Test
+      end
+    end
+  end
+end

data/lib/textris/delivery/mail.rb

@@ -0,0 +1,95 @@
+module Textris
+  module Delivery
+    class Mail
+      class Mailer < ActionMailer::Base
+        def notify(from, to, subject, body)
+          mail :from => from, :to => to, :subject => subject, :body => body
+        end
+      end
+
+      class << self
+        def send_message_to_all(message)
+          message.to.each do |to|
+            send_message(to, message)
+          end
+        end
+
+        private
+
+        def send_message(to, message)
+          template_vars = { :to_phone => to }
+
+          from    = apply_template from_template,    message, template_vars
+          to      = apply_template to_template,      message, template_vars
+          subject = apply_template subject_template, message, template_vars
+          body    = apply_template body_template,    message, template_vars
+
+          ::Textris::Delivery::Mail::Mailer.notify(
+            from, to, subject, body).deliver
+        end
+
+        def from_template
+          Rails.application.config.try(:textris_mail_from_template) ||
+            "%{from_name:d}-%{from_phone}@%{env:d}.%{app:d}.com"
+        end
+
+        def to_template
+          Rails.application.config.try(:textris_mail_to_template) ||
+            "%{app:d}-%{env:d}-%{to_phone}-texts@mailinator.com"
+        end
+
+        def subject_template
+          Rails.application.config.try(:textris_mail_subject_template) ||
+            "%{texter:dh} texter: %{action:h}"
+        end
+
+        def body_template
+          Rails.application.config.try(:textris_mail_body_template) ||
+            "%{content}"
+        end
+
+        def apply_template(template, message, vars)
+          template.gsub(/\%\{[a-z_:]+\}/) do |match|
+            directive = match.gsub(/[%{}]/, '')
+            var       = directive.split(':').first
+            modifiers = directive.split(':')[1] || ''
+
+            content = if var == 'app'
+              Rails.application.class.parent_name
+            elsif var == 'env'
+              Rails.env
+            elsif var == 'texter' && (texter = message.texter).present?
+              texter.to_s.split('::').last.sub(/Texter$/, '')
+            elsif var == 'action' && (action = message.action).present?
+              action.to_s
+            elsif var == 'from_name' && (from = message.from_name).present?
+              from.to_s
+            elsif (value = vars[var.to_sym]).present?
+              value
+            elsif ['content', 'from_phone'].include?(var)
+              message.send(var)
+            end.to_s.strip
+
+            unless content.present?
+              content = 'unknown'
+            end
+
+            if modifiers.include?('d')
+              content = content.underscore.dasherize
+            end
+
+            if modifiers.include?('h')
+              content = content.humanize.gsub(/[-_]/, ' ')
+            end
+
+            if modifiers.include?('p')
+              content = Phony.format(content) rescue content
+            end
+
+            content
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textris/delivery/test.rb

@@ -0,0 +1,29 @@
+module Textris
+  module Delivery
+    class Test
+      class << self
+        def send_message_to_all(message)
+          message.to.each do |to|
+            send_message(to, message)
+          end
+        end
+
+        def messages
+          @messages ||= []
+        end
+
+        private
+
+        def send_message(to, message)
+          messages.push(::Textris::Message.new(
+            :content    => message.content,
+            :from_name  => message.from_name,
+            :from_phone => message.from_phone,
+            :texter     => message.texter,
+            :action     => message.action,
+            :to         => to))
+        end
+      end
+    end
+  end
+end

data/lib/textris/message.rb

@@ -0,0 +1,65 @@
+module Textris
+  class Message
+    attr_reader :content, :from_name, :from_phone, :to, :texter, :action
+
+    def initialize(options = {})
+      @to      = parse_to      options[:to]
+      @content = parse_content options[:content]
+
+      if options.has_key?(:from)
+        @from_name, @from_phone = parse_from options[:from]
+      else
+        @from_name  = options[:from_name]
+        @from_phone = options[:from_phone]
+      end
+
+      unless @content.present?
+        raise(ArgumentError, "Content must be provided")
+      end
+
+      unless @to.present?
+        raise(ArgumentError, "Recipients must be provided and E.164 compilant")
+      end
+
+      @texter = options[:texter]
+      @action = options[:action]
+    end
+
+    def deliver
+      delivery = ::Textris::Delivery.get
+      delivery.send_message_to_all(self)
+
+      self
+    end
+
+    private
+
+    def parse_from(from)
+      if from.blank?
+        nil
+      elsif (matches = from.match(/(.*)\<(.*)\>\s*$/).to_a).size == 3 &&
+          Phony.plausible?(matches[2])
+        [matches[1].strip, Phony.normalize(matches[2])]
+      elsif Phony.plausible?(from)
+        [nil, Phony.normalize(from)]
+      else
+        [from.strip, nil]
+      end
+    end
+
+    def parse_to(to)
+      to = [*to]
+      to = to.select { |phone| Phony.plausible?(phone) }
+      to = to.map    { |phone| Phony.normalize(phone) }
+
+      to
+    end
+
+    def parse_content(content)
+      content = content.gsub(/\s{1,}/, ' ')
+      content = content.strip
+
+      content
+    end
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: textris
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Karol Słuszniak
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: render_anywhere
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.10
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.10
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+description: Implement texter classes for sending SMS messages in similar way to how
+  e-mails are sent with ActionMailer-based mailers. Take advantage of e-mail proxying
+  and enhanced phone number parsing, among others.
+email: k.sluszniak@visuality.pl
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/textris.rb
+- lib/textris/base.rb
+- lib/textris/delivery.rb
+- lib/textris/delivery/mail.rb
+- lib/textris/delivery/test.rb
+- lib/textris/message.rb
+homepage: http://github.com/visualitypl/textris
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Simple SMS messaging gem for Rails based on concepts and conventions similar
+  to ActionMailer, with some extra features.
+test_files: []