ecircle 0.0.6 → 0.0.7

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ecircle (0.0.6)
+    ecircle (0.0.7)
       activesupport
       i18n
       rake
@@ -14,13 +14,17 @@ GEM
       multi_json (~> 1.0)
     akami (1.0.0)
       gyoku (>= 0.4.0)
+    archive-tar-minitar (0.5.2)
     builder (3.0.0)
+    columnize (0.3.4)
     diff-lcs (1.1.3)
     gyoku (0.4.4)
       builder (>= 2.1.2)
     httpi (0.9.5)
       rack
     i18n (0.6.0)
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
     multi_json (1.0.3)
     nokogiri (1.5.0)
     nori (1.0.2)
@@ -34,6 +38,16 @@ GEM
     rspec-expectations (2.6.0)
       diff-lcs (~> 1.1.2)
     rspec-mocks (2.6.0)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
     savon (0.9.7)
       akami (~> 1.0)
       builder (>= 2.1.2)
@@ -44,6 +58,7 @@ GEM
       wasabi (~> 2.0)
     wasabi (2.0.0)
       nokogiri (>= 1.4.0)
+    yard (0.7.3)
 
 PLATFORMS
   ruby
@@ -51,3 +66,5 @@ PLATFORMS
 DEPENDENCIES
   ecircle!
   rspec (= 2.6.0)
+  ruby-debug19
+  yard

data/README.md

@@ -5,7 +5,9 @@ Synopsis
 
 This gem aims to be a full-fledged solution for the ecircle API, the [synchronous one](http://webservices.ecircle-ag.com/soap/javadoc/com/ecircleag/webservices/EcMApi.html) and the [asynchronous one](http://developer.ecircle-ag.com/apiwiki/wiki/AsynchronousAPI).
 
-This is WIP and far from complete.
+The API coverage is far from complete.
+
+However, the existing API coverage can be considered stable and is used in production.
 
 Features
 -------------
@@ -15,33 +17,60 @@ So far just a couple of methods:
 * create_member
 * create_or_update_user_by_email
 * delete_member
-* logon
 * send_parametrized_single_message_to_user
 
+See the rdoc for details on arguments and return values: [TODO Add link]
+
 To do
 -------------
 
-* Rethink current structure e.g.
- * doing an explicit logon in every method is ugly at best
- * inefficient handling of session token (we could and should reuse it instead of requesting a new one every time)
+* Rethink current structure
 * Implement missing API methods
 * Specs
 * RDoc
+* Remove JobPackage from gem since this is highly specific
 
 Configuration
 -------------
 
 ```Ruby
 Ecircle.configure do |config|
-  config.user     = 'your@user.com'
-  config.realm    = 'http://your.realm.com'
-  config.password = 'your_password'
+  config.user       = 'your@user.com'
+  config.sync_realm = 'http://your.realm.com'
+  config.password   = 'your_password'
 end
 ```
 
-Usage
+The reason for the unusual configuration setting "sync_realm" is that there is also an asynchronous ecircle API with a different realm.
+
+Logon
+-------------
+
+The ecircle gem does the session handling for you, there is no need to logon explicitly.
+Session tokens will be re-used to keep the number of session related traffic to a minimum.
+
+
+Examples
 -------------
 
 ```Ruby
-Ecircle.create_or_update_user_by_email 'user@email.com'
+# Given you have called Ecircle.configure appropriatly...
+
+# 1.) Create a user
+uid = Ecircle.create_or_update_user_by_email 'your@email.com'
+puts "Ecircle user ID: #{uid}"
+
+# 2.) Add this user as a member to a group - e.g. for newsletters
+mid = Ecircle.create_member uid, 'your_group_id'
+puts "Ecircle member Id: #{mid}"
+
+# 3.) Delete member from group - e.g. when he unsubscribes
+Ecircle.delete_member mid
+
+# 4.) Send the user a transactional email:
+Ecircle.send_parametrized_single_message_to_user uid,
+                                                your_template_id_at_ecircle,
+                                                [ :name, :message ],
+                                                [ 'Tom', 'welcome!' ]
+
 ```

data/ecircle.gemspec

@@ -23,4 +23,6 @@ Gem::Specification.new do |s|
   s.add_dependency 'rake'
   s.add_dependency 'savon', '>=0.9.7'
   s.add_development_dependency 'rspec', '2.6.0'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'ruby-debug19'
 end

data/lib/ecircle.rb

@@ -16,14 +16,18 @@ end
 
 module Ecircle
   class << self
+
+    #@private
     def configuration
       @configuration ||= Configuration.new
     end
 
+    #@private
     def client
       @client ||= Client.new
     end
 
+    #@private
     def configure &block
       block.call configuration
     end

data/lib/ecircle/client.rb

@@ -1,14 +1,16 @@
 module Ecircle
   class Client
+    #@private
     attr_accessor :auth_token
 
+    #@private
     def ensuring_logon &block
       begin
         @auth_token ||= logon
       rescue Savon::SOAP::Fault => e
         # If we are here this probably means that our login credentials are wrong.
         response = e.to_hash
-        if response[:fault][:faultcode] == 'soapenv:Server.userException' && response[:fault][:detail][:fault][:code] == '502'
+        if response[:fault][:detail][:fault][:code] == '502'
           help = <<-doc
           !!!
           Got an authentication exception, chances are good that you're credentials are wrong, so better double check that.
@@ -43,6 +45,7 @@ module Ecircle
       end
     end
 
+    # @private
     def client
       @client ||= Savon::Client.new do
         wsdl.document =  Ecircle.configuration.wsdl
@@ -51,6 +54,13 @@ module Ecircle
       end
     end
 
+    # Creates a member, which basically is just an association between a user and a group.
+    #
+    # @param [Integer] user_id ecircle user_id
+    # @param [Integer] group_id ecircle group_id
+    # @param [Boolean] invite send an invite by ecircle
+    # @param [Boolean] send_message send a message by ecircle
+    # @return [String] the member id
     def create_member user_id, group_id, invite = false, send_message = false
       ensuring_logon do
         @response = client.request :createMember do
@@ -66,31 +76,59 @@ module Ecircle
       end
     end
 
-    def create_or_update_user_by_email email
+    # Create or update user by email
+    # see http://developer.ecircle-ag.com/apiwiki/wiki/SynchronousSoapAPI#section-SynchronousSoapAPI-UserObjectExample
+    # for an example of the user xml
+    # @param [Hash] user_xml, in it's most simple form a { :email => 'test@test.com' } is sufficient
+    # @return [Integer] the user id
+    def create_or_update_user_by_email attributes
+      user_xml = '<user>' + attributes.each_with_object('') do |slice, xml|
+        name, value = slice.first, slice.last;
+        xml << "<#{name}>#{value}</#{name}>"
+      end+'</user>'
+
       ensuring_logon do
         @response = client.request :createOrUpdateUserByEmail do
           soap.body = {
             :session     => auth_token, # TODO We can't use @auth_token here cause then the session_id is nil. Why?
-            :userXml     => "<user><email>#{email}</email></user>",
+            :userXml     => user_xml,
             :sendMessage => 0
           }
         end
-        @response.body[:create_or_update_user_by_email_response][:create_or_update_user_by_email_return].to_s
+        @response.body[:create_or_update_user_by_email_response][:create_or_update_user_by_email_return].to_i
       end
     end
 
+    # Delete a member.
+    #
+    # @param [Integer] member_id ecircle member id
+    # @return [Boolean]
     def delete_member member_id
       ensuring_logon do
-        @response = client.request :deleteMember do
-          soap.body = {
-            :session  => auth_token,
-            :memberId => member_id
-          }
+        # In case we pass in a non existing member id we'll get a corresponding exception, so we need to catch this here as well.
+        begin
+          @response = client.request :deleteMember do
+            soap.body = {
+              :session  => auth_token,
+              :memberId => member_id
+            }
+          end
+        rescue Savon::SOAP::Fault => e
+          if e.to_hash[:fault][:detail][:fault][:code] == '100'
+            # "100" means member ID didn't exist so just return false.
+            return false
+          else
+            # Re-raise cause something else went wrong.
+            raise
+          end
         end
-        @response.body[:delete_member_response][:delete_member_return].to_s
       end
+      true
     end
 
+    # Logon. You don't need to call this explicitly but it's useful for debugging.
+    #
+    # @return [String] the session id
     def logon
       @response = client.request :logon do
         soap.body = {
@@ -102,6 +140,13 @@ module Ecircle
       @response.body[:logon_response][:logon_return].to_s
     end
 
+    # Send a parametrized single message to user - you need an existing ecircle template ID for this.
+    #
+    # @param [Integer] user_id ecircle user_id
+    # @param [Integer] message_id the ecircle template ID
+    # @param [Array] the names of the variables you want to interpolate in the template
+    # @param [Array] the values of the variables you want to interpolate in the template
+    # @return nil
     def send_parametrized_single_message_to_user user_id, message_id, names = [], values = []
       ensuring_logon do
         @response = client.request :sendParametrizedSingleMessageToUser do

data/lib/ecircle/configuration.rb

@@ -4,8 +4,10 @@ module Ecircle
     ENDPOINT  = 'http://webservices.ecircle-ag.com/rpc'
     NAMESPACE = "http://webservices.ecircleag.com/rpcns"
 
+    # @private
     attr_accessor :user, :password, :sync_realm, :async_realm, :wsdl, :endpoint, :namespace
 
+    # @private
     def initialize
       @wsdl      = WSDL
       @endpoint  = ENDPOINT

data/lib/ecircle/helper.rb

@@ -2,6 +2,7 @@ module Ecircle
   module Helper
     extend self
 
+    # @private
     def date_format date
       tz = date.strftime('%z')
       matcher = /(.*)(00)/.match(tz) # We need to do that because ecircle won't accept +0200, just +02:00.

data/lib/ecircle/job_package.rb

@@ -2,6 +2,7 @@ module Ecircle
   module JobPackage
     TARGET_CONTENT_ENCODING = 'ISO-8859-1'
 
+    # @private
     def self.send_async_message_to_group(options)
       client = Savon::Client.new do
         wsdl.endpoint  = options[:endpoint]
@@ -17,6 +18,7 @@ module Ecircle
       end
     end
 
+    # @private
     def self.soap_body(options)
       xml = Builder::XmlMarkup.new(:indent => 2)
       xml.control 'xmlns' => "http://webservices.ecircle-ag.com/ecm", 'request-id' => options[:request_id], 'group-id' => options[:group_id] do

data/lib/ecircle/version.rb

@@ -1,3 +1,3 @@
 module Ecircle
-  VERSION = "0.0.6"
+  VERSION = "0.0.7"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecircle
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2011-11-02 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &78327690 !ruby/object:Gem::Requirement
+  requirement: &69598750 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *78327690
+  version_requirements: *69598750
 - !ruby/object:Gem::Dependency
   name: i18n
-  requirement: &78326710 !ruby/object:Gem::Requirement
+  requirement: &69598090 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *78326710
+  version_requirements: *69598090
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &78325790 !ruby/object:Gem::Requirement
+  requirement: &69597470 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *78325790
+  version_requirements: *69597470
 - !ruby/object:Gem::Dependency
   name: savon
-  requirement: &78324890 !ruby/object:Gem::Requirement
+  requirement: &69596650 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: 0.9.7
   type: :runtime
   prerelease: false
-  version_requirements: *78324890
+  version_requirements: *69596650
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &78323840 !ruby/object:Gem::Requirement
+  requirement: &69595940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -65,7 +65,29 @@ dependencies:
         version: 2.6.0
   type: :development
   prerelease: false
-  version_requirements: *78323840
+  version_requirements: *69595940
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &69595540 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *69595540
+- !ruby/object:Gem::Dependency
+  name: ruby-debug19
+  requirement: &69594720 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *69594720
 description: The ecircle gem aims to be a full-fledged client for all ecircle services.
 email:
 - timo.roessner@googlemail.com
@@ -103,7 +125,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 645926193
+      hash: -98517107
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -112,7 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 645926193
+      hash: -98517107
 requirements: []
 rubyforge_project: ecircle
 rubygems_version: 1.8.10
@@ -120,3 +142,4 @@ signing_key:
 specification_version: 3
 summary: Ecircle gem
 test_files: []
+has_rdoc: