dotmailer 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,51 @@
+dotMailer
+=========
+
+[dotMailer](http://www.dotmailer.co.uk/) provide both a REST and SOAP API for interacting with their system. The REST API supports both XML and JSON payloads.
+
+This gem provides a Ruby wrapper allowing you to access the REST API, and uses JSON payloads.
+
+For a full description of the API, see https://api.dotmailer.com
+
+Installation
+------------
+
+To install as a standalone gem:
+
+    gem install dotmailer
+
+To install as part of a project managed by bundler, add to your Gemfile:
+
+    gem 'dotmailer'
+
+Usage
+-----
+
+Use the `Dotmailer::Client` class to access the dotMailer REST API.
+
+You must initialize the Client with an API user and password (see [here](http://www.dotmailer.co.uk/api/more_about_api/getting_started_with_the_api.aspx) for instructions on obtaining these):
+
+    client = Dotmailer::Client.new('your-api-username', 'your-api-password')
+
+Data Fields
+-----------
+
+### List
+
+`Dotmailer::Client#get_data_fields` will return an Array of `Dotmailer::DataField` objects representing the data fields for the global address book:
+
+    client.get_data_fields
+    => [
+         Dotmailer::DataField name: "FIELD1", type: "String", visibility: "Public", default: "",
+         Dotmailer::DataField name: "FIELD2", type: "Numeric", visibility: "Private", default: 0
+       ]
+
+### Create
+
+`Dotmailer::Client#create_data_field` will attempt to create a new data field. On success it returns true, on failure it raises an exception:
+
+    client.create_data_field 'FIELD3', :type => 'String'
+    => true
+
+    client.create_data_field 'FIELD3', :type => 'String'
+    => Dotmailer::DuplicateDataField

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/dotmailer.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "dotmailer/version"
+
+Gem::Specification.new do |s|
+  s.name        = "dotmailer"
+  s.version     = Dotmailer::VERSION
+  s.authors     = ["Econsultancy"]
+  s.email       = ["tech@econsultancy.com"]
+  s.homepage    = "https://github.com/econsultancy/dotmailer"
+  s.summary     = %q{A Ruby wrapper around the dotMailer REST API: https://apiconnector.com/v2/help/wadl}
+
+  s.rubyforge_project = "dotmailer"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency 'rest-client'
+
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'webmock'
+end

data/lib/dotmailer.rb

@@ -0,0 +1,3 @@
+require 'dotmailer/exceptions'
+require 'dotmailer/data_field'
+require 'dotmailer/client'

data/lib/dotmailer/client.rb

@@ -0,0 +1,78 @@
+require 'cgi'
+require 'json'
+require 'csv'
+require 'restclient'
+
+module Dotmailer
+  class Client
+    def initialize(api_user, api_pass)
+      self.api_user = api_user
+      self.api_pass = api_pass
+    end
+
+    def get_data_fields
+      fields = get 'data-fields'
+
+      fields.map { |attributes| DataField.new(attributes) }
+    end
+
+    def create_data_field(name, options = {})
+      options[:type]       ||= 'String'
+      options[:visibility] ||= 'Public'
+
+      post_json(
+        'data-fields',
+        'name'         => name,
+        'type'         => options[:type],
+        'visibility'   => options[:visibility],
+        'defaultValue' => options[:default]
+      )
+
+      true
+    rescue RestClient::BadRequest
+      raise DuplicateDataField
+    end
+
+    def import_contacts(headers, contacts)
+      csv = CSV.generate do |csv|
+        csv << headers
+
+        contacts.each do |contact|
+          csv << headers.map { |header| contact[header] }
+        end
+      end
+
+      post 'contacts/import', csv, :content_type => :csv
+    end
+
+    def import_status(import_id)
+      response = get "contacts/import/#{import_id}"
+
+      response['status']
+    end
+
+    private
+    attr_accessor :api_user, :api_pass
+
+    def get(path)
+      JSON.parse RestClient.get url(path), :accept => :json
+    end
+
+    def post_json(path, params)
+      post path, params.to_json, :content_type => :json
+    end
+
+    def post(path, data, options = {})
+      JSON.parse RestClient.post url(path), data, options.merge(:accept => :json)
+    end
+
+    def url(path)
+      URI::Generic.build(
+        :scheme   => 'https',
+        :userinfo => "#{CGI.escape(api_user)}:#{api_pass}",
+        :host     => 'api.dotmailer.com',
+        :path     => "/v2/#{path}"
+      ).to_s
+    end
+  end
+end

data/lib/dotmailer/data_field.rb

@@ -0,0 +1,38 @@
+module Dotmailer
+  class DataField
+    def initialize(attributes)
+      self.attributes = attributes
+    end
+
+    def name
+      attributes['name']
+    end
+
+    def type
+      attributes['type']
+    end
+
+    def visibility
+      attributes['visibility']
+    end
+
+    def default
+      attributes['defaultValue']
+    end
+
+    def to_json(options = {})
+      attributes.to_json
+    end
+
+    def to_s
+      %{#{self.class.name} name: "#{name}", type: "#{type}", visibility: "#{visibility}", default: "#{default}"}
+    end
+
+    def ==(other)
+      attributes == other.attributes
+    end
+
+    protected
+    attr_accessor :attributes
+  end
+end

data/lib/dotmailer/exceptions.rb

@@ -0,0 +1,4 @@
+module Dotmailer
+  class DuplicateDataField < Exception
+  end
+end

data/lib/dotmailer/version.rb

@@ -0,0 +1,3 @@
+module Dotmailer
+  VERSION = "0.0.1"
+end

data/spec/dotmailer/client_spec.rb

@@ -0,0 +1,159 @@
+require 'spec_helper'
+
+describe Dotmailer::Client do
+  let(:api_user) { 'john_doe' }
+  let(:api_pass) { 's3cr3t' }
+  let(:api_base_url) { "https://#{api_user}:#{api_pass}@api.dotmailer.com" }
+
+  subject { Dotmailer::Client.new(api_user, api_pass) }
+
+  context 'data fields' do
+    let(:data_fields_endpoint) do
+      "#{api_base_url}/v2/data-fields"
+    end
+
+    describe '#get_data_fields' do
+      let(:data_fields) do
+        [
+          Dotmailer::DataField.new(
+            'name'         => 'FIRSTNAME',
+            'type'         => 'String',
+            'visibility'   => 'Public',
+            'defaultValue' => 'John'
+          ),
+          Dotmailer::DataField.new(
+            'name'         => 'CODE',
+            'type'         => 'String',
+            'visibility'   => 'Private',
+            'defaultValue' => nil
+          )
+        ]
+      end
+
+      before(:each) do
+        stub_request(:get, data_fields_endpoint).to_return(:body => data_fields.to_json)
+      end
+
+      it 'should get the fields from the data fields endpoint' do
+        subject.get_data_fields
+
+        WebMock.should have_requested(:get, data_fields_endpoint).with(
+          :headers => { 'Accept' => 'application/json' }
+        )
+      end
+
+      it 'should return the data fields from the data fields endpoint' do
+        subject.get_data_fields.should == data_fields
+      end
+    end
+
+    describe '#create_data_field' do
+      let(:name) { 'FIRSTNAME' }
+
+      let(:data_field_json) do
+        {
+          'name'         => name,
+          'type'         => 'String',
+          'visibility'   => 'Public',
+          'defaultValue' => nil
+        }.to_json
+      end
+
+      before(:each) do
+        stub_request(:post, data_fields_endpoint).to_return(:body => data_field_json)
+      end
+
+      it 'should post the field to the data fields endpoint' do
+        subject.create_data_field name
+
+        WebMock.should have_requested(:post, data_fields_endpoint).with(
+          :body    => data_field_json,
+          :headers => {
+            'Accept'       => 'application/json',
+            'Content-Type' => 'application/json'
+          }
+        )
+      end
+
+      context 'when the field doesnt exist' do
+        it 'should return true' do
+          subject.create_data_field(name).should == true
+        end
+      end
+
+      context 'when the field already exists' do
+        before(:each) do
+          stub_request(:post, data_fields_endpoint).to_return(:status => 400)
+        end
+
+        it 'should raise an error' do
+          expect { subject.create_data_field(name) }.to raise_error(Dotmailer::DuplicateDataField)
+        end
+      end
+    end
+  end
+
+  context 'contacts' do
+    describe '#import_contacts' do
+      let(:contact_import_endpoint) do
+        "#{api_base_url}/v2/contacts/import"
+      end
+
+      let(:headers) { ['Email'] }
+
+      let(:contacts) do
+        [
+          { 'Email' => 'john.doe@example.com' }
+        ]
+      end
+
+      let(:contacts_csv) { "Email\njohn.doe@example.com\n" }
+
+      let(:response) { { 'id' => '123', 'status' => 'Finished' } }
+
+      before(:each) do
+        stub_request(:post, contact_import_endpoint).to_return(:body => response.to_json)
+      end
+
+      it 'should post the contacts in CSV format to the contact import endpoint' do
+        subject.import_contacts ['Email'], contacts
+
+        WebMock.should have_requested(:post, contact_import_endpoint).with(
+          :body    => contacts_csv,
+          :headers => {
+            'Accept'       => 'application/json',
+            'Content-Type' => 'text/csv'
+          }
+        )
+      end
+    end
+
+    describe '#import_status' do
+      let(:import_id) { 123 }
+
+      let(:import_status_endpoint) do
+        "#{api_base_url}/v2/contacts/import/#{import_id}"
+      end
+
+      let(:status) { 'Finished' }
+
+      let(:response) { { 'id' => import_id, 'status' => status } }
+
+      before(:each) do
+        stub_request(:get, import_status_endpoint).to_return(:body => response.to_json )
+      end
+
+      it 'should get the import status from the import status endpoint' do
+        subject.import_status import_id
+
+        WebMock.should have_requested(:get, import_status_endpoint).with(
+          :headers => { 'Accept' => 'application/json' }
+        )
+      end
+
+      it 'should return the status from the import status endpoint' do
+        subject.import_status(import_id).should == status
+      end
+    end
+  end
+end

data/spec/dotmailer/data_field_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+describe Dotmailer::DataField do
+  let(:name)       { 'FIRSTNAME' }
+  let(:type)       { 'String' }
+  let(:visibility) { 'Public' }
+  let(:default)    { 'John' }
+
+  let(:attributes) do
+    {
+      'name'         => name,
+      'type'         => type,
+      'visibility'   => visibility,
+      'defaultValue' => default
+    }
+  end
+
+  subject { Dotmailer::DataField.new(attributes) }
+
+  its(:name)       { should == name }
+  its(:type)       { should == type }
+  its(:visibility) { should == visibility }
+  its(:default)    { should == default }
+
+  its(:to_s) { should == 'Dotmailer::DataField name: "FIRSTNAME", type: "String", visibility: "Public", default: "John"' }
+
+  its(:to_json) { should == attributes.to_json }
+
+  describe '#==' do
+    specify { subject.should == Dotmailer::DataField.new(attributes) }
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+require 'webmock/rspec'
+
+require 'dotmailer'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: dotmailer
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Econsultancy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- tech@econsultancy.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- dotmailer.gemspec
+- lib/dotmailer.rb
+- lib/dotmailer/client.rb
+- lib/dotmailer/data_field.rb
+- lib/dotmailer/exceptions.rb
+- lib/dotmailer/version.rb
+- spec/dotmailer/client_spec.rb
+- spec/dotmailer/data_field_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/econsultancy/dotmailer
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: dotmailer
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: ! 'A Ruby wrapper around the dotMailer REST API: https://apiconnector.com/v2/help/wadl'
+test_files: []