emarsys 0.1.0

data/.gitignore

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

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in emarsys.gemspec
+
+group :test do
+  gem 'rspec', '~> 2.13.0'
+  gem 'webmock', '~> 1.9.0'
+end
+
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Daniel Schoppmann
+
+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,171 @@
+# emarsys-rb
+
+Simple Ruby wrapper for the Emarsys API.
+
+## Installation
+
+    gem install emarsys
+
+## Emarsys API Hint
+
+This wrapper tries to implement all available methods of the Emarsys API in a
+Ruby-like fashion. However, the Emarsys API lacks a decent amount of methods that
+you expect an API to provide.
+Thus, if methods are missing or a certain implementation
+style was choosen it is most likely due to the inconsistency of the API itself.
+Feel free to get in touch or submit a pull request if you encounter any problems.
+
+Must-known facts about the Emarsys API:
+
+* Emarsys uses internal IDs as field identifiers. E.g. 'email' is mapped to the value 3.
+This gem tries to work around this by letting you specify a field mapping constant.
+* certain methods require the specification of a key-field, e.g. the email (internally refered to as '3' again).
+* Return values differ from method to method due to the way the Emarsys API is implemented.
+Thus, a Hash as a return value or an Array of Hashes was choosen as the global return object. Basically it is a parsed JSON response.
+* Please refer to the Emarsys API documentation for detailed information on parameters, return values or error codes.
+
+## Configuration and Setup
+### Authentication
+
+Authenticate with the api credentials provided by your Emarsys account manager.
+
+    Emarsys.configure do |c|
+      c.api_username = 'my_username'
+      c.api_password = 'my_password'
+      # OPTIONAL, defaults to https://suite5.emarsys.net/api/v2
+      c.api_endpoint = 'https://www.emarsys.net/api/v2'
+    end
+
+### Field Mapping
+
+As said before, Emarsys loves IDs. For using an APi, they are evil. This Gem provides
+an easy way to adjust the individual field settings. Internally a Ruby Mapping Constant is used,
+which that can be overwritten. It will be picked up automatically. E.g.:
+
+    # Complete overwrite
+    Emarsys::FieldMapping::ATTRIBUTES = [
+      {:id => 0, :identifier => 'interests', :name => 'Interests'},
+      {:id => 1, :identifier => 'firstname', :name => 'First Name'},
+      {:id => 2, :identifier => 'lastname',  :name => 'Last Name'},
+    ]
+
+    # Add to the Mapping-Constant
+    Emarsys::FieldMapping::ATTRIBUTES << {:id => 100, :identifier => 'user_id', :name => "User-ID"}
+
+All Emarsys predefined system fields are prefixed with an underscore, e.g. '_firstname' or '_revenue' in order to not
+clash with individual mappings.
+
+
+## Interacting with the API
+
+You can interact with the API on the provided data objects:
+
+#### Condition
+
+    # Get all conditions
+    Emarsys::Condition.collection
+
+#### Contact
+
+    # Create a contact with custom key_field (one example with mapped identifier, one without)
+    Emarsys::Contact.create('user_id', 10, {firstname: "Jane", lastname: "Doe", email: "jane.doe@example.com"})
+    Emarsys::Contact.create(4980, 10, {1 => "Jane", 2 => "Doe", 3 => "jane.doe@example.com"})
+
+    # Update a contact with key_field (one example with mapped identifier, one without)
+    Emarsys::Contact.update('email', "jane.doe@example.com", {firstname: "John", lastname: "Doe"})
+    Emarsys::Contact.update(3, "jane.doe@example.com", {1 => "John", 2 => "Doe"})
+
+#### ContactList
+
+    # Get all contact_lists
+    Emarsys::ContactList.collection
+
+    # Create a contact list
+    Emarsys::ContactList.create
+
+#### Emails
+
+    # Get all email campaigns, optional filter
+    Emarsys::Email.collection
+    Emarsys::Email.collection(status: 3)
+
+    # Get a single email resource
+    Emarsys::Email.resource(1)
+
+    # Create a new email campaign
+    Emarsys::Email.create({})
+
+    Emarsys::Email.launch({})
+
+#### Event
+
+    Emarsys::Event.collection
+
+    # Trigger a custom event
+    Emarsys::Event.trigger(65, 3, ["test@example.com"])
+
+    # Trigger a custom event which actually sends a mail
+    # (Emarsys way to send transactional mails with placeholders)
+    Emarsys::Event.trigger(2, 3, 'test@example.com', {:global => {:my_placeholder => "some content"}})
+
+#### Export
+
+    Emarsys::Export.resource(1)
+
+#### Field
+
+    Emarsys::Field.collection
+    Emarsys::Field.choice(1)
+
+#### Folder
+
+    # Get all forms, optional filter parameters
+    Emarsys::Folder.collection
+    Emarsys::Folder.collection(:folder => 3)
+
+#### Form
+
+    # Get all forms
+    Emarsys::Form.collection
+
+#### Language
+
+    # Get all languages
+    Emarsys::Language.collection
+
+#### Segment
+
+    # Get all segments
+    Emarsys::Segment.collection
+
+#### Source
+
+    # Get all sources
+    Emarsys::Source.collection
+
+    # Create a new source
+    Emarsys::Source.create("New Source")
+
+    # Destroy a source
+    Emarsys::Source.destroy(123)
+
+
+Please refer to the code for detailed instructions of each method.
+
+## Ruby Versions
+
+This gem was developed and tested with versions 1.9.3 and 2.0.0
+
+
+## Contributing
+
+1. Fork it
+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 new Pull Request
+
+
+## Copyright
+
+Copyright (c) 2013 Daniel Schoppmann. See LICENSE.txt for details.

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec

data/emarsys.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'emarsys/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "emarsys"
+  spec.version       = Emarsys::VERSION
+  spec.authors       = ["Daniel Schoppmann"]
+  spec.email         = ["daniel.schoppmann@absolventa.de"]
+  spec.description   = %q{A Ruby library for interacting with the Emarsys API.}
+  spec.summary       = %q{Easy to use ruby library for Emarsys Marketing Suite.}
+  spec.homepage      = "http://www.absolventa.de"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rest-client"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/lib/emarsys.rb

@@ -0,0 +1,60 @@
+require "base64"
+require 'json'
+require 'rest_client'
+require 'uri'
+
+require 'emarsys/client'
+require 'emarsys/data_object'
+require 'emarsys/error'
+require 'emarsys/extensions'
+require 'emarsys/field_mapping'
+require 'emarsys/params_converter'
+require 'emarsys/request'
+require 'emarsys/response'
+
+require 'emarsys/data_objects/condition'
+require 'emarsys/data_objects/contact_list'
+require 'emarsys/data_objects/contact'
+require 'emarsys/data_objects/email'
+require 'emarsys/data_objects/email_category'
+require 'emarsys/data_objects/email_launch_status'
+require 'emarsys/data_objects/email_status_code'
+require 'emarsys/data_objects/event'
+require 'emarsys/data_objects/export'
+require 'emarsys/data_objects/field'
+require 'emarsys/data_objects/file'
+require 'emarsys/data_objects/folder'
+require 'emarsys/data_objects/form'
+require 'emarsys/data_objects/language'
+require 'emarsys/data_objects/segment'
+require 'emarsys/data_objects/source'
+
+require "emarsys/version"
+
+# Ruby toolkit for the Emarsys API
+module Emarsys
+  class << self
+
+    # @!attribute api_endpoint
+    #   @return [String] Base URL for emarsys URLs. default: https://suite5.emarsys.net/api/v2
+    # @!attribute api_password
+    #   @return [String] API Username given by Emarsys
+    # @!attribute api_username
+    #   @return [String] API Username given by Emarsys
+
+    attr_accessor :api_endpoint, :api_username, :api_password
+
+    # Base URL for the Emarsys API
+    #
+    # @return [String] domain which should be used to query the API
+    def api_endpoint
+      @api_endpoint ||= 'https://suite5.emarsys.net/api/v2'
+    end
+
+    # Set configuration options using a block
+    def configure
+      yield self
+    end
+
+  end
+end

data/lib/emarsys/client.rb

@@ -0,0 +1,40 @@
+module Emarsys
+  class Client
+
+    def username
+      raise ArgumentError, "Emarsys.api_username is not set" if Emarsys.api_username.nil?
+      Emarsys.api_username
+    end
+
+    def password
+      raise ArgumentError, "Emarsys.api_password is not set" if Emarsys.api_password.nil?
+      Emarsys.api_password
+    end
+
+    def x_wsse_string
+      string = 'UsernameToken '
+      string += 'Username = "' + username + '", '
+      string += 'PasswordDigest = "' + header_password_digest + '", '
+      string += 'Nonce = "' + header_nonce + '", '
+      string += 'Created = "' + header_created + '"'
+      string
+    end
+
+    def header_password_digest
+      Base64.encode64(calculated_digest).gsub("\n", "")
+    end
+
+    def header_nonce
+      Digest::MD5.hexdigest(Time.new.to_i.to_s)
+    end
+
+    def header_created
+      Time.new.strftime("%Y-%m-%d %H:%M:%S")
+    end
+
+    def calculated_digest
+      Digest::SHA1.hexdigest(header_nonce + header_created + password)
+    end
+
+  end
+end

data/lib/emarsys/data_object.rb

@@ -0,0 +1,78 @@
+#require 'hashie'
+
+module Emarsys
+  class DataObject
+    class << self
+
+      # Make a HTTP GET request
+      #
+      # @param method_name [String] The path, relative to Emarsys.api_endpoint
+      # @param params [Hash] custom params hash
+      # @return [Hash]
+      def get(method_name, params)
+        if params.empty?
+          self.new.request 'get', method_name, params
+        else
+          self.new.request 'get', [method_name, parameterize_params(params)].join("/"), {}
+        end
+      end
+
+      # Make a HTTP POST request
+      #
+      # @param method_name [String] The path, relative to Emarsys.api_endpoint
+      # @param params [Hash] custom params hash
+      # @return [Hash]
+      def post(method_name, params)
+        self.new.request 'post', method_name, params
+      end
+
+      # Make a HTTP PUT request
+      #
+      # @param method_name [String] The path, relative to Emarsys.api_endpoint
+      # @param params [Hash] custom params hash
+      # @return [Hash]
+      def put(method_name, params)
+        self.new.request 'put', method_name, params
+      end
+
+      # Make a HTTP DELETE request
+      #
+      # @param method_name [String] The path, relative to Emarsys.api_endpoint
+      # @param params [Hash] custom params hash
+      # @return [Hash]
+      def delete(method_name, params)
+        self.new.request 'delete', method_name, params
+      end
+
+      # Custom Parameterizer for Emarsys
+      #
+      # @param params [Hash] custom params hash
+      # @return [String] key => value is returned as key=value
+      def parameterize_params(params)
+        params.inject(""){|string, (k, v)| string << "#{k}=#{v}"; string << "&"; string}[0..-2]
+      end
+    end
+
+    # Make a HTTP request
+    #
+    # @param http_verb [String] Http method
+    # @param method_name [String] The path, relative to Emarsys.api_endpoint
+    # @param params [Hash] custom params hash
+    # @return [Hash]
+    def request(http_verb, method_name, params)
+      response = Emarsys::Request.new(http_verb, method_name, params).send_request
+      #hashiefy(response)
+    end
+
+    # TODO: Not finally evaluated. Is Hashie necessary? Maybe use "real Data Objects instead"?
+    # def hashiefy(response)
+    #   if response.is_a?(Array)
+    #     response.map!{|elem| Hashie::Mash.new(elem) }
+    #   elsif
+    #     Hashie::Mash.new(response)
+    #   else
+    #     response
+    #   end
+    # end
+  end
+end