ecircle 0.0.8 → 0.0.9

data/.yardopts

@@ -0,0 +1,6 @@
+--no-private
+--hide-void-return
+
+--markup-provider=redcarpet
+--markup=markdown
+

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ecircle (0.0.8)
+    ecircle (0.0.9)
       activesupport
       i18n
       rake

data/README.md

@@ -36,6 +36,7 @@ Since the asynchronous API is neither documented by ecircle nor intuitive at all
 To do
 -------------
 
+* Fix TODOs in source code
 * Implement missing API methods:
  * createOrUpdateGroup
  * deleteUser
@@ -43,16 +44,26 @@ To do
  * lookupGroups
 * Write specs
 
+
+Installation
+-------------
+
+Either as a gem:
+
+    gem install ecircle
+
+or via Bundler by adding it to your Gemfile.
+
+
 Configuration
 -------------
 
-```Ruby
-Ecircle.configure do |config|
-  config.user       = 'your@user.com'
-  config.sync_realm = 'http://your.realm.com'
-  config.password   = 'your_password'
-end
-```
+    Ecircle.configure do |config|
+      config.user       = 'your@user.com'
+      config.sync_realm = 'http://your.realm.com'
+      config.password   = 'your_password'
+    end
+
 
 The reason for the unusual configuration setting "sync_realm" is that there is also an asynchronous ecircle API with a different realm.
 
@@ -62,63 +73,81 @@ 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.
 
+Response
+-------------
+
+The ecircle gem will always return a wrapped response. Except for when it doesn't because I didn't find the time which is
+for create_or_update_user_by_email and logon (see examples below or the API doc).
+
+The wrapped response object is just a neat abstraction to hide Ecircle's horrible, horrible error handling from you and provides several methods for doing so.
+
+The most usefull (and self-explanatory) would be:
+
+* success?
+* error_message
+* fault_code
+* ecircle_id IF the API returns an ID an success, e.g. for create_member and create_or_update_user_by_email
+* convenience methods which depend on your (failed request), e.g.:
+  * member_does_not_exist? (relevant for create_member requests)
+  * TODO Explain all convenience methods.
+
+For details see [here](http://rubydoc.info/github/troessner/ecircle/master/Ecircle/WrappedResponse)
 
 Examples
 -------------
 
 ### Synchronous API
 
-```Ruby
-# Given you have called Ecircle.configure appropriatly...
+    # 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}"
 
-# 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
+    response = Ecircle.create_member uid, 'your_group_id'
+    puts "Ecircle member Id: #{response.ecircle_id}"
 
-# 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
 
-# 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!' ]
 
-# 4.) Send the user a transactional email:
-Ecircle.send_parametrized_single_message_to_user uid,
-                                                your_template_id_at_ecircle,
-                                                [ :name, :message ],
-                                                [ 'Tom', 'welcome!' ]
+    # 5.) Delete the group
+    Ecircle.delete_group your_group_id
 
-# 5.) Delete the group
-Ecircle.delete_group your_group_id
+    # 6.) Log out
+    Ecircle.logout
 
-# 6.) Log out
-Ecircle.logout
 
-```
 ### Asynchronous API
 
-```Ruby
-Ecircle.configure do |config|
-  config.user        = 'your@user.com'
-  config.async_realm = 'http://your.async.realm.com' # IMPORTANT - different realm.
-  config.password    = 'your_password'
-end
-
-@options = {
-  :endpoint                     => 'http://your.domain/eC-MessageService',
-  :request_id                   => '1234',
-  :group_id                     => '5678',
-  :send_out_date                => 70.minutes.from_now, # Must be at least one hour in the future!
-  :send_date_for_report         => 140.minutes.from_now,  # Must be at least one hour in the future *after* dispatching!
-  :report_email                 => 'your@report.de',
-  :report_email_name            => 'Your name',
-  :subject                      => 'Newsletter',
-  :text                         => 'Newsletter text content',
-  :html                         => 'Newsletter html content'
-}
-
-Ecircle::JobPackage.send_async_message_to_group @options
-```
+Note the async_realm in the configure block, this another realm as for the sync API.
+
+    Ecircle.configure do |config|
+      config.user        = 'your@user.com'
+      config.async_realm = 'http://your.async.realm.com' # IMPORTANT - different realm.
+      config.password    = 'your_password'
+    end
+
+    @options = {
+      :endpoint                     => 'http://your.domain/eC-MessageService',
+      :request_id                   => '1234',
+      :group_id                     => '5678',
+      :send_out_date                => 70.minutes.from_now, # Must be at least one hour in the future!
+      :send_date_for_report         => 140.minutes.from_now,  # Must be at least one hour in the future *after* dispatching!
+      :report_email                 => 'your@report.de',
+      :report_email_name            => 'Your name',
+      :subject                      => 'Newsletter',
+      :text                         => 'Newsletter text content',
+      :html                         => 'Newsletter html content'
+    }
+
+    Ecircle::JobPackage.send_async_message_to_group @options
 
 Documentation
 -------------

data/lib/ecircle/api.rb

@@ -59,7 +59,7 @@ module Ecircle
     #
     # @param [Integer] user_id ecircle user_id
     # @param [Integer] group_id ecircle group_id
-    # @param [Boolean] invite send an invite by ecircle
+    # @param [Boolean] invite send an additional invite mail
     # @param [Boolean] send_message send a message by ecircle
     # @return [WrappedResponse]
     def create_member user_id, group_id, invite = false, send_message = false
@@ -75,23 +75,41 @@ module Ecircle
             }
           end
         rescue Savon::SOAP::Fault => e
-          wrapped_response = WrappedResponse.new(e)
-          if wrapped_response.no_such_user? || wrapped_response.no_such_group_when_a_user_was_given
-            return wrapped_response
-          else
-            raise # Re-raise cause something else went wrong.
-          end
+          return WrappedResponse.new(e)
         end
         WrappedResponse.new(:success => true, :ecircle_id => @response.body[:create_member_response][:create_member_return].to_s)
       end
     end
 
+    # Create or update group
+    # see http://developer.ecircle-ag.com/apiwiki/wiki/SynchronousSoapAPI#section-SynchronousSoapAPI-GroupObjectExample
+    # for an example of the group xml
+    # @param [Hash] group_xml, in it's most simple form a { :name => 'your name', :description => 'desc', ':email => 'test@test.com' } is sufficient
+    # @return [WrappedResponse]
+    # Important note: `email` must be unique across all groups AND must be a subdomain of the system you registered at ecircle.
+    def create_or_update_group group_attributes
+      ensuring_logon do
+        begin
+          client.request :createOrUpdateGroup do
+            soap.body = {
+              :session   => auth_token,
+              'wsdl:groupXml'  => Helper.build_group_xml(group_attributes)
+            }
+          end
+        rescue Savon::SOAP::Fault => e
+          return WrappedResponse.new(e)
+        end
+      WrappedResponse.new(:success => true)
+      end
+    end
+
     # 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
     # TODO Error handling is missing.
+    # TODO Return a wrapped response.
     def create_or_update_user_by_email user_attributes
       ensuring_logon do
         @response = client.request :createOrUpdateUserByEmail do
@@ -119,12 +137,7 @@ module Ecircle
             }
           end
         rescue Savon::SOAP::Fault => e
-          wrapped_response = WrappedResponse.new(e)
-          if wrapped_response.group_does_not_exist?
-            return wrapped_response
-          else
-            raise # Re-raise cause something else went wrong.
-          end
+          return WrappedResponse.new(e)
         end
       end
       WrappedResponse.new(:success => true)
@@ -144,12 +157,7 @@ module Ecircle
             }
           end
         rescue Savon::SOAP::Fault => e
-          wrapped_response = WrappedResponse.new(e)
-          if wrapped_response.member_does_not_exist?
-            return wrapped_response
-          else
-            raise # Re-raise cause something else went wrong.
-          end
+          return WrappedResponse.new(e)
         end
       end
       WrappedResponse.new(:success => true)
@@ -178,6 +186,7 @@ module Ecircle
           :session  => auth_token,
         }
       end
+      WrappedResponse.new(:success => true)
     end
 
     # Send a parametrized single message to user - you need an existing ecircle template ID for this.
@@ -190,7 +199,7 @@ module Ecircle
     def send_parametrized_single_message_to_user user_id, message_id, names = [], values = []
       ensuring_logon do
         begin
-          @response = client.request :sendParametrizedSingleMessageToUser do
+          client.request :sendParametrizedSingleMessageToUser do
             soap.body = {
               :session           => auth_token,
               :singleMessageId   => message_id,

data/lib/ecircle/helper.rb

@@ -15,5 +15,18 @@ module Ecircle
         xml << "<#{name}>#{value}</#{name}>"
       end+'</user>'
     end
+
+    def build_group_xml attrs
+      # Important note: Actually I have no idea what ecircle wants here. This works for me. Just go with the flow.
+      xml = Builder::XmlMarkup.new
+      xml.tag! 'group', :xmlns => 'http://webservices.ecircle-ag.com/ecm', 'group-id' => 'new', 'preferred-channel' => 'email' do
+        xml.name attrs[:name]
+        xml.description attrs[:description]
+        xml.tag! 'email-channel' do
+          xml.email attrs[:email]
+        end
+      end
+      xml.target!.gsub('"', "'").gsub('\\', '')
+    end
   end
 end

data/lib/ecircle/version.rb

@@ -1,3 +1,3 @@
 module Ecircle
-  VERSION = '0.0.8'
+  VERSION = '0.0.9'
 end

data/lib/ecircle/wrapped_response.rb

@@ -43,6 +43,10 @@ module Ecircle
       @fault_code == 502 && @error_message = 'Permission Problem'
     end
 
+    def message_id_does_not_exist?
+      @error_message =~ /MessageInfo '(\d+)' not found/
+    end
+
     def success?
       @success
     end

data/spec/{client_spec.rb → job_package_spec.rb}

@@ -9,6 +9,7 @@ describe Ecircle::JobPackage do
       :send_out_date                => date,
       :send_date_for_report         => date,
       :report_email                 => 'report@dealvertise.de',
+      :report_email_name            => 'Your name',
       :location_name                => 'Berlin',
       :subject                      => 'Berlin newsletter',
       :text                         => 'Newsletter text content',
@@ -28,14 +29,14 @@ describe Ecircle::JobPackage do
     <send-report-address>
       <email-address>
         <email>#{@options[:report_email]}</email>
-        <name>Send report for newsletter for location #{@options[:location_name]} sent out on #{@options[:send_out_date]}</name>
+        <name>Your name</name>
       </email-address>
     </send-report-address>
     <status-report report-id="new" delete="false" user-tracking-details="false" link-tracking-details="false" bouncing-details="false">
       <report-address>
         <email-address>
           <email>#{@options[:report_email]}</email>
-          <name>Status report for newsletter for location #{@options[:location_name]} sent out on #{@options[:send_out_date]}</name>
+          <name>Your name</name>
         </email-address>
       </report-address>
       <send-date>
@@ -51,13 +52,13 @@ describe Ecircle::JobPackage do
   <success-report-address>
     <email-address>
       <email>#{@options[:report_email]}</email>
-      <name>Success report for newsletter for location #{@options[:location_name]} sent out on #{@options[:send_out_date]}</name>
+      <name>Your name</name>
     </email-address>
   </success-report-address>
   <failure-report-address>
     <email-address>
       <email>#{@options[:report_email]}</email>
-      <name>Failure report for newsletter for location #{@options[:location_name]} sent out on #{@options[:send_out_date]}</name>
+      <name>Your name</name>
     </email-address>
   </failure-report-address>
 </control>

metadata

@@ -1,108 +1,104 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: ecircle
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.0.9
   prerelease: 
-  version: 0.0.8
 platform: ruby
-authors: 
-- "Timo R\xC3\xB6\xC3\x9Fner"
+authors:
+- Timo Rößner
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-11-09 00:00:00 +01:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-11-17 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &84616970 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
+  version_requirements: *84616970
+- !ruby/object:Gem::Dependency
   name: i18n
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &84616320 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
+  version_requirements: *84616320
+- !ruby/object:Gem::Dependency
   name: rake
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &84615600 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
+  version_requirements: *84615600
+- !ruby/object:Gem::Dependency
   name: savon
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &84614520 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 0.9.7
   type: :runtime
   prerelease: false
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
+  version_requirements: *84614520
+- !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &84611650 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - "="
-      - !ruby/object:Gem::Version 
+    requirements:
+    - - =
+      - !ruby/object:Gem::Version
         version: 2.6.0
   type: :development
   prerelease: false
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
+  version_requirements: *84611650
+- !ruby/object:Gem::Dependency
   name: yard
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  requirement: &84610850 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
   prerelease: false
-  version_requirements: *id006
-- !ruby/object:Gem::Dependency 
+  version_requirements: *84610850
+- !ruby/object:Gem::Dependency
   name: ruby-debug19
-  requirement: &id007 !ruby/object:Gem::Requirement 
+  requirement: &84609900 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
   prerelease: false
-  version_requirements: *id007
+  version_requirements: *84609900
 description: The ecircle gem aims to be a full-fledged client for all ecircle services.
-email: 
+email:
 - timo.roessner@googlemail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - .rvmrc
 - .travis.yml
+- .yardopts
 - Gemfile
 - Gemfile.lock
 - README.md
@@ -115,41 +111,37 @@ files:
 - lib/ecircle/job_package.rb
 - lib/ecircle/version.rb
 - lib/ecircle/wrapped_response.rb
-- spec/client_spec.rb
+- spec/job_package_spec.rb
 - spec/spec_helper.rb
-has_rdoc: true
-homepage: ""
+homepage: ''
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: -743074899
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: 133028911
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: -743074899
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
+      hash: 133028911
 requirements: []
-
 rubyforge_project: ecircle
-rubygems_version: 1.6.2
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Ecircle gem
 test_files: []
-
+has_rdoc: