bronto 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in bronto.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Martin Gordon
+
+MIT License
+
+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,82 @@
+# Bronto
+
+This is a handy library that wraps the Bronto SOAP API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'bronto'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bronto
+
+## Usage
+
+Let's setup some contacts, add them to a list, and then send them a message.
+
+1. Require the library and specify the API Key on the Base class:
+
+    ```
+    require 'bronto'
+    Bronto::Base.api_key = "..."
+    ```
+
+2. Create two contacts:
+
+    ```
+    contact_1 = Bronto::Contact.new(email: "test_1@example.com")
+    contact_2 = Bronto::Contact.new(email: "test_2@example.com")
+
+    puts contact_1.id
+    # => nil
+
+    puts contact_2.id
+    # => nil
+
+    # You can save multiple objects with one API call using the class `save` method.
+    Bronto::Contact.save(contact_1, contact_2)
+
+    # Both contacts should now have ids.
+    puts contact_1.id
+    # => "32da24c..."
+
+    puts contact_2.id
+    # => "98cd453..."
+    ```
+
+3. Create a list and the contacts:
+
+    ```
+    list = Bronto::List.new(name: "A Test List", label: "This is a test list.")
+    list.save
+
+    list.add_to_list(contact_1, contact_2)
+    ```
+
+4. Create a new message and add content:
+
+    message = Bronto::Message.new(name: "Test Message")
+    message.add_content("html", "HTML Subject", "HTML Content")
+    message.add_content("text", "Text Subject", "Text Content")
+    message.save
+
+5. Create a new delivery with a message and recipients and send it ASAP:
+
+    delivery = Bronto::Delivery.new(start: Time.now, type: "normal", from_name: "Test", from_email: "test@example.com")
+    delivery.message_id = message.id
+    delivery.add_recipient(list)
+    delivery.save
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,12 @@
+#!/usr/bin/env rake
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "./lib/bronto"
+
+Rake::TestTask.new(:test) do |test|
+  test.ruby_opts = ["-rubygems"] if defined? Gem
+  test.libs << "lib" << "test"
+  test.pattern = "test/**/*_test.rb"
+end

data/bronto.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/bronto/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Martin Gordon"]
+  gem.email         = ["martingordon@gmail.com"]
+  gem.description   = %q{A Ruby wrapper for the Bronto SOAP API}
+  gem.summary       = %q{A Ruby wrapper for the Bronto SOAP API}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "bronto"
+  gem.require_paths = ["lib"]
+  gem.version       = Bronto::VERSION
+
+  gem.add_dependency "savon"
+
+  gem.add_development_dependency "debugger"
+  gem.add_development_dependency "turn"
+  gem.add_development_dependency "shoulda"
+end

data/lib/bronto.rb

@@ -0,0 +1,36 @@
+require "savon"
+
+require "bronto/base"
+require "bronto/contact"
+require "bronto/delivery"
+require "bronto/field"
+require "bronto/filter"
+require "bronto/list"
+require "bronto/message"
+require "bronto/version"
+
+require "core_ext/array"
+require "core_ext/object"
+require "core_ext/string"
+
+module Bronto
+  class Errors
+    attr_accessor :messages
+
+    def initialize
+      self.messages = {}
+    end
+
+    def add(code, message)
+      messages[code] = message
+    end
+
+    def clear; messages.clear; end
+    def length; messages.length; end
+    def count; messages.count; end
+
+    def to_a(include_codes = true)
+      messages.map { |k,v| include_codes ? "#{v} (#{k})" : v }
+    end
+  end
+end

data/lib/bronto/base.rb

@@ -0,0 +1,198 @@
+module Bronto
+  class Base
+    attr_accessor :id, :errors
+
+    # Getter/Setter for global API Key.
+    def self.api_key=(api_key)
+      @@api_key = api_key
+    end
+
+    def self.api_key
+      @@api_key
+    end
+
+    # Simple helper method to convert class name to downcased pluralized version (e.g., Field -> fields).
+    def self.plural_class_name
+      self.to_s.split("::").last.downcase.pluralize
+    end
+
+    # The primary method used to interface with the SOAP API.
+    # This method automatically adds the required session header and returns the actual response section of the SOAP response body.
+    #
+    # If a symbol is passed in, it is converted to "method_plural_class_name" (e.g., :read => read_lists). A string
+    # method is used as-is.
+    # Pass in a block and assign a hash to soap.body with a structure appropriate to the method call.
+    def self.request(method, refresh_header = false, &_block)
+      _soap_header = self.soap_header(refresh_header)
+
+      method = "#{method}_#{plural_class_name}" if method.is_a? Symbol
+
+      resp = api.request(:v4, method.to_sym) do
+        soap.header = _soap_header
+        evaluate(&_block) if _block # See Savon::Client#evaluate; necessary to preserve scope.
+      end
+
+      resp.body["#{method}_response".to_sym]
+    end
+
+    # Sets up the Savon SOAP client object (if necessary) and returns it.
+    def self.api
+      return @api unless @api.nil?
+
+      @api = Savon::Client.new do
+        wsdl.endpoint = "https://api.bronto.com/v4"
+        wsdl.namespace = "http://api.bronto.com/v4"
+      end
+    end
+
+    # Helper method to retrieve the session ID and return a SOAP header.
+    # Will return a header with the same initial session ID unless the `refresh` argument is `true`.
+    def self.soap_header(refresh = false)
+      return @soap_header if !refresh and @soap_header.present?
+
+      resp = api.request(:v4, :login) do
+        soap.body = { api_token: self.api_key }
+      end
+
+      @soap_header = { "v4:sessionHeader" => { session_id: resp.body[:login_response][:return] } }
+    end
+
+    # Saves a collection of Bronto::Base objects.
+    # Objects without IDs are considered new and are `create`d; objects with IDs are considered existing and are `update`d.
+    def self.save(*objs)
+      objs = objs.flatten
+      update(objs.select { |o| o.id.present? })
+      create(objs.select { |o| o.id.blank? })
+      objs
+    end
+
+    # Finds objects matching the `filter` (a Bronto::Filter instance).
+    def self.find(filter = Bronto::Filter.new, page_number = 1)
+      resp = request(:read) do
+        soap.body = { filter: filter.to_hash, page_number: page_number }
+      end
+
+      Array.wrap(resp[:return]).map { |hash| new(hash) }
+    end
+
+    # Tells the remote server to create the passed in collection of Bronto::Base objects.
+    # The object should implement `to_hash` to return a hash in the format expected by the SOAP API.
+    #
+    # Returns the same collection of objects that was passed in. Objects whose creation succeeded will be assigned the
+    # ID returned from Bronto.
+    def self.create(*objs)
+      objs = objs.flatten
+
+      resp = request(:add) do
+        soap.body = {
+          plural_class_name => objs.map(&:to_hash)
+        }
+      end
+
+      objs.each { |o| o.errors.clear }
+
+      Array.wrap(resp[:return][:results]).each_with_index do |result, i|
+        if result[:is_new] and !result[:is_error]
+          objs[i].id = result[:id]
+        elsif result[:is_error]
+          objs[i].errors.add(result[:error_code], result[:error_string])
+        end
+      end
+
+      objs
+    end
+
+    # Updates a collection of Bronto::Base objects. The objects should exist on the remote server.
+    # The object should implement `to_hash` to return a hash in the format expected by the SOAP API.
+    def self.update(*objs)
+      objs = objs.flatten
+
+      resp = request(:update) do
+        soap.body = {
+          plural_class_name => objs.map(&:to_hash)
+        }
+      end
+
+      objs.each { |o| o.errors.clear }
+      objs
+    end
+
+    # Destroys a collection of Bronto::Base objects on the remote server.
+    #
+    # Returns the same collection of objects that was passed in. Objects whose destruction succeeded will
+    # have a nil ID.
+    def self.destroy(*objs)
+      objs = objs.flatten
+
+      resp = request(:delete) do
+        soap.body = {
+          plural_class_name => objs.map { |o| { id: o.id }}
+        }
+      end
+
+      Array.wrap(resp[:return][:results]).each_with_index do |result, i|
+        if result[:is_error]
+          objs[i].errors.add(result[:error_code], result[:error_string])
+        else
+          objs[i].id = nil
+        end
+      end
+
+      objs
+    end
+
+    # Accepts a hash whose keys should be setters on the object.
+    def initialize(options = {})
+      self.errors = Errors.new
+      options.each { |k,v| send("#{k}=", v) if respond_to?("#{k}=") }
+    end
+
+    # `to_hash` should be overridden to provide a hash whose structure matches the structure expected by the API.
+    def to_hash
+      {}
+    end
+
+    # Convenience instance method that calls the class `request` method.
+    def request(method, &block)
+      self.class.request(method, &block)
+    end
+
+    def reload
+      return if self.id.blank?
+
+      # The block below is evaluated in a weird scope so we need to capture self as _self for use inside the block.
+      _self = self
+
+      resp = request(:read) do
+        soap.body = { filter: { id: _self.id } }
+      end
+
+      resp[:return].each do |k, v|
+        self.send("#{k}=", v) if self.respond_to? "#{k}="
+      end
+
+      nil
+    end
+
+    # Saves the object. If the object has an ID, it is updated. Otherwise, it is created.
+    def save
+      id.blank? ? create : update
+    end
+
+    # Creates the object. See `Bronto::Base.create` for more info.
+    def create
+      res = self.class.create(self)
+      res.first
+    end
+
+    # Updates the object. See `Bronto::Base.update` for more info.
+    def update
+      self.class.update(self).first
+    end
+
+    # Destroys the object. See `Bronto::Base.destroy` for more info.
+    def destroy
+      self.class.destroy(self).first
+    end
+  end
+end

data/lib/bronto/contact.rb

@@ -0,0 +1,62 @@
+module Bronto
+  class Contact < Base
+    attr_accessor :email, :fields, :lists
+
+    # Finds contacts based on the `filter` (Bronto::Filter object).
+    # * `page_number` is the page of contacts to request. Bronto doesn't specify how many contacts are returned per page,
+    #    only that you should keep increasing the number until no more contacts are returned.
+    # * `fields` can be an array of field IDs or an array of Field objects.
+    # * `include_lists` determines whether to include the list IDs each contact belongs to.
+    def self.find(filter = Bronto::Filter.new, page_number = 1, fields = nil, include_lists = false)
+      body = { filter: filter.to_hash, page_number: page_number }
+
+      body[:fields] = Array.wrap(fields).map { |f| f.is_a?(Bronto::Field) ? f.id : f } if Array(fields).length > 0
+      body[:include_lists] = include_lists
+
+      resp = request(:read) do
+        soap.body = body
+      end
+
+      Array.wrap(resp[:return]).map { |hash| new(hash) }
+    end
+
+    def initialize(options = {})
+      self.fields = {}
+      fields = options.delete(:fields)
+      Array.wrap(fields).each { |field| set_field(field[:field_id], field[:content]) }
+
+      super(options)
+    end
+
+    def to_hash
+      if id.present?
+        { id: id, email: email, fields: fields.values.map(&:to_hash) }
+      else
+        { email: email, fields: fields.values.map(&:to_hash) }
+      end
+    end
+
+    def set_field(field, value)
+      id = field.is_a?(Bronto::Field) ? field.id : field
+      self.fields[id] = Field.new(id, value)
+    end
+
+    def get_field(field)
+      id = field.is_a?(Bronto::Field) ? field.id : field
+      self.fields[id].try(:content)
+    end
+
+    class Field
+      attr_accessor :field_id, :content
+
+      def initialize(id, content)
+        self.field_id = id
+        self.content = content
+      end
+
+      def to_hash
+        { field_id: field_id, content: content }
+      end
+    end
+  end
+end