outbox 0.0.1 → 0.1.0

data/.gitignore

@@ -2,6 +2,7 @@
 *.rbc
 .bundle
 .config
+.ruby-version
 .yardoc
 Gemfile.lock
 InstalledFiles

data/README.md

@@ -1,7 +1,10 @@
 Outbox
 ======
 
-Outbox is a Rails Engine and generic interface for sending notifications using a variety of delivery methods, with built-in support for the most popular SaaS solutions.
+[![Gem Version](https://badge.fury.io/rb/outbox.png)](http://badge.fury.io/rb/outbox)
+
+Outbox is a factory for creating notifications in a variety of protocols, including: email, SMS, and push notifications. Each protocol is built as a generic interface where the actual delivery method or service can be configured independently of the message itself.
+
 
 Installation
 ------------
@@ -24,10 +27,88 @@ Or install it yourself as:
 $ gem install outbox
 ```
 
+Support
+-------
+
+This gem is still in early development with plans to support email, SMS, and push notificaitons. As protocols and services are added, this support table will be updated:
+
+### Email
+
+| Service                                   | Alias   | Client     |
+|-------------------------------------------|---------|------------|
+| [Mail gem](https://github.com/mikel/mail) | `:mail` | MailClient |
+
+### SMS
+
+TODO…
+
+### Push
+
+TODO…
+
 Usage
 -----
 
-TODO: Write usage instructions here
+Outbox is inspired by [Mail's](https://github.com/mikel/mail) syntax for creating emails.
+
+### Making a Message
+
+An Outbox message is actually a factory for creating many different types of messages with the same **topic**. For example: a **topic** could be an event reminder in a calendar application. You want to send out essentially the same content (the reminder) as an email, SMS, and/or push notifications depending on user preferences:
+
+``` ruby
+message = Outbox::Message.new do
+  email do
+    from 'noreply@myapp.com'
+    subject 'You have an upcoming event!'
+  end
+
+  sms do
+    from '+15557654321'
+  end
+
+  ios_push do
+    badget '+1'
+    sound 'default'
+  end
+
+  body "Don't forget, you have an upcoming event on 8/15/2013."
+end
+
+# This will deliver the message to User's given contact points.
+message.deliver email: 'user@gmail.com', sms: '+15551234567', ios_push: 'FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660'
+```
+
+### Making an email
+
+Making just an email is done just how you would using the [Mail gem](https://github.com/mikel/mail), so look there for in-depth examples. Here's a simple one to get you started:
+
+``` ruby
+email = Outbox::Messages::Email.new do
+  to 'user@gmail.com'
+  from 'noreply@myapp.com'
+  subject 'You have an upcoming event!'
+
+  text_part do
+    body "Don't forget, you have an upcoming event on 8/15/2013."
+  end
+
+  html_part do
+    body "<h1>Event Reminder</h1>..."
+  end
+end
+
+# Configure the client. If you use the MailClient, you can specify
+# the actual delivery method:
+email.client :mail, delivery_method: :smtp, smtp_settings: {}
+
+# And deliver using the specified client
+email.deliver
+```
+
+Configuration
+-------------
+
+TODO...
 
 Contributing
 ------------

data/lib/outbox.rb

@@ -1,4 +1,21 @@
-require 'outbox/version'
-
 module Outbox
+  require 'outbox/errors'
+  require 'outbox/version'
+
+  autoload 'Accessor', 'outbox/accessor'
+  autoload 'Message', 'outbox/message'
+  autoload 'MessageClients', 'outbox/message_clients'
+  autoload 'MessageFields', 'outbox/message_fields'
+  autoload 'MessageTypes', 'outbox/message_types'
+
+  module Clients
+    autoload 'Base', 'outbox/clients/base'
+    autoload 'MailClient', 'outbox/clients/mail_client'
+    autoload 'TestClient', 'outbox/clients/test_client'
+  end
+
+  module Messages
+    autoload 'Base', 'outbox/messages/base'
+    autoload 'Email', 'outbox/messages/email'
+  end
 end

data/lib/outbox/accessor.rb

@@ -0,0 +1,71 @@
+module Outbox
+  # Accessor is a simple object for wrapping access to either a hash's keys
+  # or an object's properties. You can arbitrarily get/set either. Note that
+  # with hashes, the keys are symbolized and a new hash is created - so if you
+  # set properties you'll need to get the resulting hash from the #object
+  # method.
+  #
+  # Example:
+  #
+  #   hash = { :a => 1, 'b' => 2 }
+  #   hash_accessor = Outbox::Accessor.new(hash)
+  #   hash_accessor[:a] #=> 1
+  #   hash_accessor[:b] #=> 2
+  #   hash_accessor[:c] #=> nil
+  #   hash_accessor[:c] = 3
+  #   hash_accessor.object[:c] #=> 3
+  #   hash_accessor.object #=> { a: 1, b: 2, c: 3 }
+  #
+  #   object = OpenStruct.new
+  #   object.a = 1
+  #   object.b = 2
+  #   object_accessor = Outbox::Accessor.new(object)
+  #   object_accessor[:a] #=> 1
+  #   object_accessor[:b] #=> 2
+  #   object_accessor[:c] #=> nil
+  #   object_accessor[:c] = 3
+  #   object_accessor.object.c #=> 3
+  class Accessor
+    attr_reader :object
+
+    def initialize(object)
+      if object.instance_of? Hash
+        @object = convert_keys(object)
+      else
+        @object = object
+      end
+    end
+
+    def []=(key, value)
+      setter = "#{key}="
+      if @object.respond_to?(setter)
+        @object.public_send(setter, value)
+      elsif @object.respond_to? :[]=
+        @object[convert_key(key)] = value
+      end
+    end
+
+    def [](key)
+      key = convert_key(key)
+      if @object.respond_to?(key)
+        @object.public_send(key)
+      elsif @object.respond_to? :[]
+        @object[key]
+      end
+    end
+
+    protected
+
+    def convert_keys(hash)
+      result = {}
+      hash.each_key do |key|
+        result[convert_key(key)] = hash[key]
+      end
+      result
+    end
+
+    def convert_key(key)
+      key.to_sym rescue key
+    end
+  end
+end

data/lib/outbox/clients/base.rb

@@ -0,0 +1,39 @@
+module Outbox
+  module Clients
+    class Base
+      attr_reader :settings
+
+      # Sets default settings for the client.
+      #
+      #   MailClient.defaults delivery_method: :sendmail
+      #   client = MailClient.new
+      #   client.settings[:delivery_method] #=> :sendmail
+      def self.defaults(defaults = nil)
+        @defaults ||= {}
+
+        if defaults.nil?
+          @defaults
+        else
+          @defaults.merge!(defaults)
+        end
+      end
+
+      # Creates a new client instance. Settings can be configured per
+      # instance by passing in a hash.
+      #
+      #    client = MailClient.new delivery_method: :sendmail
+      #    client.settings[:delivery_method] #=> :sendmail
+      def initialize(settings = nil)
+        @settings = self.class.defaults.dup
+        @settings.merge! settings if settings
+      end
+
+      # Delivers the given message.
+      #
+      # Subclasses must provide an implementation of this method.
+      def deliver(message)
+        raise NotImplementedError, 'Subclasses must implement a deliver method'
+      end
+    end
+  end
+end

data/lib/outbox/clients/mail_client.rb

@@ -0,0 +1,40 @@
+module Outbox
+  module Clients
+    class MailClient < Base
+      defaults delivery_method: :smtp
+
+      # Returns the configured delivery method.
+      def delivery_method
+        settings[:delivery_method]
+      end
+
+      # Returns the configured delivery method settings. This will also check
+      # the Rails-style #{delivery_method}_settings key as well.
+      #
+      #   client = Outbox::Clients::MailClient.new delivery_method: :sendmail, delivery_method_settings: {
+      #     location: '/usr/bin/sendmail'
+      #   }
+      #   client.delivery_method_settings #=> { location: '/usr/bin/sendmail' }
+      #
+      #   client = Outbox::Clients::MailClient.new delivery_method: :sendmail, sendmail_settings: {
+      #     location: '/usr/bin/sendmail'
+      #   }
+      #   client.delivery_method_settings #=> { location: '/usr/bin/sendmail' }
+      def delivery_method_settings
+        settings[:delivery_method_settings] || settings[:"#{delivery_method}_settings"]
+      end
+
+      def deliver(email)
+        message = create_message_from_email(email)
+        message.delivery_method(delivery_method, delivery_method_settings)
+        message.deliver
+      end
+
+      private
+
+      def create_message_from_email(email)
+        email.message_object.dup
+      end
+    end
+  end
+end

data/lib/outbox/clients/test_client.rb

@@ -0,0 +1,20 @@
+module Outbox
+  module Clients
+    # The TestClient is a bare bones client that does nothing. It is useful
+    # when you are testing.
+    #
+    # It also provides a template of the minimum methods required to make
+    # a custom client.
+    class TestClient < Base
+      # Provides a store of all the message sent with the TestClient so you
+      # can check them.
+      def self.deliveries
+        @@deliveries ||= []
+      end
+
+      def deliver(message)
+        self.class.deliveries << message
+      end
+    end
+  end
+end

data/lib/outbox/errors.rb

@@ -0,0 +1,5 @@
+module Outbox
+  # Raised when a message is missing data for a required field.
+  class MissingRequiredFieldError < StandardError
+  end
+end

data/lib/outbox/message.rb

@@ -0,0 +1,47 @@
+module Outbox
+  class Message
+    include MessageTypes
+
+    register_message_type :email, Outbox::Messages::Email
+
+    # Make a new message. Every message can be created using a hash,
+    # block, or direct assignment.
+    #
+    #   message = Message.new do
+    #     email do
+    #       subject 'Subject'
+    #     end
+    #   end
+    #   message = Message.new email: { subject: 'Subject' }
+    #   message = Message.new
+    #   message.email = Email.new subject: 'Subject'
+    def initialize(message_type_values = nil, &block)
+      if block_given?
+        instance_eval(&block)
+      else
+        assign_message_type_values(message_type_values) unless message_type_values.nil?
+      end
+    end
+
+    # Delivers all of the messages to the given 'audience'. An 'audience' object
+    # can be a hash or an object that responds to the current message types. Only
+    # the message types specified in the 'audience' object will be sent to.
+    #
+    #   message.deliver email: 'hello@example.com', sms: '+15555555555'
+    #   audience = OpenStruct.new
+    #   audience.email = 'hello@example.com'
+    #   audience.sms = '+15555555555'
+    #   message.deliver(audience)
+    def deliver(audience)
+      audience = Outbox::Accessor.new(audience)
+
+      self.class.message_types.each_key do |message_type|
+        message = self.public_send(message_type)
+        next if message.nil?
+
+        recipient = audience[message_type]
+        message.deliver(recipient) if recipient
+      end
+    end
+  end
+end

data/lib/outbox/message_clients.rb

@@ -0,0 +1,70 @@
+module Outbox
+  module MessageClients
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Returns the default client for the message type.
+      #
+      #   Email.default_client #=> #<Outbox::Clients::Mail>
+      #
+      # Also allows you to set the default client using an alias, with optoins.
+      #
+      #   Email.default_client :test, option: 'foo'
+      #   Email.default_client #=> #<Outbox::Clients::TestClient>
+      def default_client(client = nil, options = nil)
+        if client.nil?
+          @default_client
+        else
+          @default_client = get_client(client, options)
+        end
+      end
+
+      # Registers a client class with an alias.
+      #
+      #   Email.register_client_alias :mandrill, MandrillClient
+      #   Email.default_client :mandrill, mandrill_option: 'foo'
+      def register_client_alias(name, client)
+        registered_client_aliases[name.to_sym] = client
+      end
+
+      # Returns a hash of client aliases, where the key is the alias and
+      # the value is client class.
+      def registered_client_aliases
+        @registered_client_aliases ||= { test: Outbox::Clients::TestClient }
+      end
+
+      protected
+
+      def get_client(client, options = nil)
+        case client
+        when Symbol, String
+          client = registered_client_aliases[client.to_sym]
+        end
+
+        if client.instance_of?(Class)
+          client.new(options)
+        else
+          client
+        end
+      end
+    end
+
+    # Returns the message's client.
+    #
+    #   message.client #=> #<Outbox::Clients::Mail>
+    #
+    # Also allows you set the instance's client using an alias, with options.
+    #
+    #   message.client :test, option: 'foo'
+    #   message.client #=> #<Outbox::Clients::TestClient>
+    def client(client = nil, options = nil)
+      if client.nil?
+        @client
+      else
+        @client = self.class.send(:get_client, client, options)
+      end
+    end
+  end
+end

data/lib/outbox/message_fields.rb

@@ -0,0 +1,209 @@
+module Outbox
+  module MessageFields
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Sets default values for defined fields.
+      #
+      #   Email.defaults from: 'bob@example.com'
+      #   message = Email.new
+      #   message.from #=> 'bob@example.com'
+      def defaults(defaults = nil)
+        @defaults ||= {}
+
+        if defaults.nil?
+          @defaults
+        else
+          @defaults.merge!(defaults)
+        end
+      end
+
+      # Returns the defined fields for this message type.
+      #
+      #   class SomeMessageType < Outbox::Messages::Base
+      #     field :to
+      #     field :from
+      #   end
+      #
+      #   SomeMessageType.fields #=> [:to, :from]
+      #
+      # Also allows you to define multiple fields at once.
+      #
+      #   class SomeMessageType < Outbox::Messages::Base
+      #     fields :to, :from, required: true
+      #   end
+      #
+      #   message = SomeMessageType.new do
+      #     to 'Bob'
+      #     from 'John'
+      #   end
+      #   message.to #=> 'Bob'
+      #   message.from #=> 'John'
+      #   message.from = nil
+      #   message.validate_fields #=> raises Outbox::MissingRequiredFieldError
+      def fields(*names)
+        if names.empty?
+          @fields ||= []
+        else
+          options = names.last.is_a?(Hash) ? names.pop : {}
+          names.flatten.each do |name|
+            field(name, options)
+          end
+        end
+      end
+
+      # Defines a 'field' which is a point of data for this type of data.
+      # Optionally you can set it to be required, or wether or not you want
+      # accessors defined for you. If you define your own accessors, make
+      # sure the reader also accepts a value that can be set, so it'll work
+      # with the block definition.
+      #
+      #   class SomeMessageType < Outbox::Messages::base
+      #     field :to, required: true
+      #     field :body, accessor: false
+      #
+      #     def body(value = nil)
+      #       value ? self.body = value : @body
+      #     end
+      #
+      #     def body=(value)
+      #       @body = parse_body(value)
+      #     end
+      #   end
+      #
+      #   message = SomeMessageType.new do
+      #     to 'Bob'
+      #   end
+      #   message.to #=> 'Bob'
+      #   message.to = 'John'
+      #   message.to #=> 'John'
+      #   message.to = nil
+      #   message.validate_fields #=> raises Outbox::MissingRequiredFieldError
+      def field(name, options = {})
+        name = name.to_sym
+        options = Outbox::Accessor.new(options)
+
+        fields.push(name)
+        required_fields.push(name) if options[:required]
+
+        unless options[:accessor] == false
+          define_field_reader(name) unless options[:reader] == false
+          define_field_writer(name) unless options[:writer] == false
+        end
+      end
+
+      # Returns an array of the required fields for a message type.
+      #
+      #   class SomeMessageType < Outbox::Messages::Base
+      #     field :to, required: true
+      #     fields :from, :subject
+      #   end
+      #   SomeMessageType.required_fields #=> [:to]
+      #
+      # Also can be used an alias for defining fields that are required.
+      #
+      #   class SomeMessageType < Outbox::Messages::Base
+      #     required_fields :to, :from
+      #   end
+      #   SomeMessageType.required_fields #=> [:to, :from]
+      def required_fields(*names)
+        if names.empty?
+          @required_fields ||= []
+        else
+          options = names.last.is_a?(Hash) ? names.pop : {}
+          options[:required] = true
+          names << options
+          fields(*names)
+        end
+      end
+      alias :required_field :required_fields
+
+      protected
+
+      def define_field_reader(name)
+        define_method(name) do |value = nil|
+          if value.nil?
+            @fields[name]
+          else
+            @fields[name] = value
+          end
+        end
+      end
+
+      def define_field_writer(name)
+        define_method("#{name}=") do |value|
+          @fields[name] = value
+        end
+      end
+    end
+
+    # Read an arbitrary field.
+    #
+    # Example:
+    #
+    #  message['foo'] = '1234'
+    #  message['foo'] #=> '1234'
+    def [](name)
+      @fields[name.to_sym]
+    end
+
+    # Add an arbitray field.
+    #
+    # Example:
+    #
+    #  message['foo'] = '1234'
+    #  message['foo'] #=> '1234'
+    def []=(name, value)
+      @fields[name.to_sym] = value
+    end
+
+    # Returns a hash of the defined fields.
+    #
+    #   class SomeMessageType < Outbox::Messages::Base
+    #     fields :to, :from
+    #   end
+    #   message = SomeMessageType.new to: 'Bob'
+    #   message.from 'John'
+    #   message.fields #=> { to: 'Bob', from: 'John' }
+    #
+    # Also allows you to set fields if you pass in a hash.
+    #
+    #   message.fields to: 'Bob', from: 'Sally'
+    #   message.fields #=> { to: 'Bob', from: 'Sally' }
+    def fields(new_fields = nil)
+      if new_fields.nil?
+        fields = {}
+        self.class.fields.each do |field|
+          fields[field] = self.public_send(field)
+        end
+        fields
+      else
+        self.fields = new_fields
+      end
+    end
+
+    # Assigns the values of the given hash.
+    #
+    #   message.to = 'Bob'
+    #   message.fields = { from: 'Sally' }
+    #   message.fields #=> { to: 'Bob', from: 'Sally' }
+    def fields=(new_fields)
+      new_fields.each do |field, value|
+        self.public_send(field, value) if self.respond_to?(field)
+      end
+    end
+
+    # Checks the current values of the fields and raises errors for any
+    # validation issues.
+    def validate_fields
+      self.class.required_fields.each do |field|
+        value = self.public_send(field)
+        if value.nil? || value.respond_to?(:empty?) && value.empty?
+          raise Outbox::MissingRequiredFieldError.new("Missing required field: #{field}")
+        end
+      end
+    end
+  end
+end