gnumarcelo-campaigning 0.10.0 → 0.11.0

data/lib/campaigning/{types/list.rb → list.rb}

@@ -1,19 +1,16 @@
 # Campaign is defined in soap/default.rb which is automatically generated.
 # In this file we add additional methods to the Campaign class.
-require File.expand_path(File.dirname(__FILE__)) + '/../helpers/helpers'
-
+require File.expand_path(File.dirname(__FILE__)) + '/module_mixin'
 
 module Campaigning
-  
   class List
-    include Helpers   
+    include ModuleMixin   
     attr_accessor :listID
     attr_accessor :name
 
     def initialize(listID = nil, name = nil)
       @listID = listID
       @name = name
-      @soap = Campaigning::SOAPDriver.instance.get_driver
     end
 
     #Creates a brand new subscriber list
@@ -32,19 +29,19 @@ module Campaigning
     #*Success*: Upon a successful call, this method will return a Campaigning::List object representing the newly created list.
     #
     #*Error*: An Exception containing the cause of the error will be raised.
-    def self.create(params)
-      response = Campaigning::SOAPDriver.instance.get_driver.createList(
-        :apiKey => CAMPAIGN_MONITOR_API_KEY,
-        :clientID => params[:clientID],
-        :title => params[:title],
-        :unsubscribePage => params.fetch(:unsubscribePage, ""),
-        :confirmOptIn => params[:confirmOptIn],
-        :confirmationSuccessPage => params.fetch(:confirmationSuccessPage, "")
+    def self.create!(params)
+      response = @@soap.createList(
+      :apiKey => CAMPAIGN_MONITOR_API_KEY,
+      :clientID => params[:clientID],
+      :title => params[:title],
+      :unsubscribePage => params.fetch(:unsubscribePage, ""),
+      :confirmOptIn => params[:confirmOptIn],
+      :confirmationSuccessPage => params.fetch(:confirmationSuccessPage, "")
       )      
       new_list_id = handle_response response.list_CreateResult
       List.new(new_list_id, params[:title])
     end
-    
+
     #Creates a new custom field for a list
     #
     #Available _params_ argument are:
@@ -59,17 +56,17 @@ module Campaigning
     #containing a successful message.
     #
     #*Error*: An Exception containing the cause of the error will be raised.
-    def create_custom_field(params)      
-      response = @soap.createListCustomField(
-        :apiKey => CAMPAIGN_MONITOR_API_KEY,
-        :listID => @listID,
-        :fieldName => params[:fieldName],
-        :dataType => params[:dataType],
-        :options => params.fetch(:options, "") 
+    def create_custom_field!(params)      
+      response = @@soap.createListCustomField(
+      :apiKey => CAMPAIGN_MONITOR_API_KEY,
+      :listID => @listID,
+      :fieldName => params[:fieldName],
+      :dataType => params[:dataType],
+      :options => params.fetch(:options, "") 
       )
       handle_response response.list_CreateCustomFieldResult
     end
-    
+
     #Deletes a list
     #
     #*Return*:
@@ -78,8 +75,8 @@ module Campaigning
     #containing a successful message.
     #
     #*Error*: An Exception containing the cause of the error will be raised.
-    def delete
-      List.delete(@listID)
+    def delete!
+      List.delete!(@listID)
       self.listID, self.name  = nil, nil
     end
 
@@ -91,11 +88,11 @@ module Campaigning
     #containing a successful message.
     #
     #*Error*: An Exception containing the cause of the error will be raised.
-    def self.delete(list_id)
-      response = Campaigning::SOAPDriver.instance.get_driver.deleteList(:apiKey => CAMPAIGN_MONITOR_API_KEY, :listID => list_id)
+    def self.delete!(list_id)
+      response = @@soap.deleteList(:apiKey => CAMPAIGN_MONITOR_API_KEY, :listID => list_id)
       handle_response response.list_DeleteResult
     end
-    
+
     #Deletes a custom field from a list
     #
     #*Return*:
@@ -104,11 +101,11 @@ module Campaigning
     #containing a successful message.
     #
     #*Error*: An Exception containing the cause of the error will be raised.
-    def delete_custom_field(key)
-      response = @soap.deleteListCustomField(:apiKey => CAMPAIGN_MONITOR_API_KEY, :listID => @listID, :key => '['+key+']')
+    def delete_custom_field!(key)
+      response = @@soap.deleteListCustomField(:apiKey => CAMPAIGN_MONITOR_API_KEY, :listID => @listID, :key => '['+key+']')
       handle_response response.list_DeleteCustomFieldResult
     end
-    
+
     #Gets all the Custom Fields available for a list
     #
     #*Return*:
@@ -118,10 +115,10 @@ module Campaigning
     #
     #*Error*: An Exception containing the cause of the error will be raised.
     def custom_fields
-      response = @soap.getListCustomFields(:apiKey => CAMPAIGN_MONITOR_API_KEY, :listID => @listID)
+      response = @@soap.getListCustomFields(:apiKey => CAMPAIGN_MONITOR_API_KEY, :listID => @listID)
       handle_response response.list_GetCustomFieldsResult
     end
-    
+
     #Gets a list's configuration detail
     #
     #*Return*:
@@ -131,10 +128,10 @@ module Campaigning
     #
     #*Error*: An Exception containing the cause of the error will be raised.
     def details
-      response = @soap.getListDetail(:apiKey => CAMPAIGN_MONITOR_API_KEY, :listID => @listID)
+      response = @@soap.getListDetail(:apiKey => CAMPAIGN_MONITOR_API_KEY, :listID => @listID)
       handle_response response.list_GetDetailResult
     end
-  
+
     #Gets a list of all active subscribers for a list.
     #
     #*Return*:
@@ -145,7 +142,7 @@ module Campaigning
     def get_all_active_subscribers
       find_active_subscribers(DateTime.new(y=1911,m=1,d=01, h=01,min=00,s=00))
     end
-  
+
     #Gets a list of all active subscribers for a list that have been joined since the specified date.
     #The +joined_at+ param has to be a DateTime object, like:
     #
@@ -157,10 +154,10 @@ module Campaigning
     #
     #*Error*: An Exception containing the cause of the error will be raised.
     def find_active_subscribers(joined_at)
-      response = @soap.getSubscribers(
-       :apiKey => CAMPAIGN_MONITOR_API_KEY,
-       :listID => @listID,
-       :date =>joined_at.strftime('%Y-%m-%d %H:%M:%S')
+      response = @@soap.getSubscribers(
+      :apiKey => CAMPAIGN_MONITOR_API_KEY,
+      :listID => @listID,
+      :date =>joined_at.strftime('%Y-%m-%d %H:%M:%S')
       )
       handle_response response.subscribers_GetActiveResult
     end
@@ -177,14 +174,14 @@ module Campaigning
     #
     #*Error*: An Exception containing the cause of the error will be raised.    
     def find_unsubscribed(unjoined_at)
-      response = @soap.getUnsubscribed(
-       :apiKey => CAMPAIGN_MONITOR_API_KEY,
-       :listID => @listID,
-       :date => unjoined_at.strftime('%Y-%m-%d %H:%M:%S') # TODO: Move that to a helper method
+      response = @@soap.getUnsubscribed(
+      :apiKey => CAMPAIGN_MONITOR_API_KEY,
+      :listID => @listID,
+      :date => unjoined_at.strftime('%Y-%m-%d %H:%M:%S') # TODO: Move that to a helper method
       )
       handle_response response.subscribers_GetUnsubscribedResult
     end
-    
+
     #This method returns all of a particular subscribers details, including email address, name, active/inactive
     #status and all custom field data. If a subscriber with that email address does not exist in that list, a +nil+ value is returned.
     #
@@ -194,14 +191,14 @@ module Campaigning
     #
     #*Error*: An Exception containing the cause of the error will be raised.    
     def find_single_subscriber(email_address) # TODO: Create a mehod to handle with custom fields returned like (names from "State Name" to "state_name")
-      response = @soap.getSingleSubscriber(
-       :apiKey => CAMPAIGN_MONITOR_API_KEY,
-       :listID => @listID,
-       :emailAddress => email_address
+      response = @@soap.getSingleSubscriber(
+      :apiKey => CAMPAIGN_MONITOR_API_KEY,
+      :listID => @listID,
+      :emailAddress => email_address
       )
       handle_response response.subscribers_GetSingleSubscriberResult
     end
-        
+
     #Update a subscriber list’s details
     #
     #Available _params_ argument are:
@@ -219,23 +216,23 @@ module Campaigning
     #containing a successful message.
     #
     #*Error*: An Exception containing the cause of the error will be raised.
-    def update(params)
-      response = @soap.updateList(
-        :apiKey => CAMPAIGN_MONITOR_API_KEY,
-        :listID => @listID,
-        :title => params[:title],
-        :unsubscribePage => params.fetch(:unsubscribePage, ""),
-        :confirmOptIn => params[:confirmOptIn],
-        :confirmationSuccessPage => params.fetch(:confirmationSuccessPage, "") 
+    def update!(params)
+      response = @@soap.updateList(
+      :apiKey => CAMPAIGN_MONITOR_API_KEY,
+      :listID => @listID,
+      :title => params[:title],
+      :unsubscribePage => params.fetch(:unsubscribePage, ""),
+      :confirmOptIn => params[:confirmOptIn],
+      :confirmationSuccessPage => params.fetch(:confirmationSuccessPage, "") 
       )
       handle_response response.list_UpdateResult
     end
-    
+
     protected
 
-      def custom_field_options(custom_fields) #:nodoc:
-        custom_fields.join("||").to_s
-      end
+    def custom_field_options(custom_fields) #:nodoc:
+      custom_fields.join("||").to_s
+    end
 
   end
 end

data/lib/campaigning/{helpers/helpers.rb → module_mixin.rb}

@@ -1,17 +1,21 @@
+require File.expand_path(File.dirname(__FILE__)) + '/soap/generated/defaultDriver.rb'
 module Campaigning
-  module Helpers #:nodoc:
+  module ModuleMixin #:nodoc:
+    #DefaultEndpointUrl = "http://api.createsend.com/api/api.asmx"
+    @@soap = Campaigning::ApiSoap.new
+
     def self.included(base)
       base.extend(ClassMethods) # Make all ClassMethods methods avaiable to the object including this module.
       private :handle_response
     end
-     
+
     def handle_response(response)
       self.class.handle_response(response)
     end
-    
+
     # All methods above will became Object methods
     module ClassMethods #:nodoc:
-      
+
       #Method responsable to handle all response from the API server and raising an exception when
       #the API returns an error code (different from 0 (zero) ).
       def handle_response(response)
@@ -20,7 +24,7 @@ module Campaigning
         end
         response
       end
-      
+
     end
 
   end

data/lib/campaigning/subscriber.rb

@@ -0,0 +1,145 @@
+# Subscriber is defined in default.rb which is automatically generated.
+# In this file we add additional methods to the Subscriber class.
+require File.expand_path(File.dirname(__FILE__)) + '/module_mixin'
+
+module Campaigning
+  class Subscriber
+    include ModuleMixin   
+    attr_accessor :emailAddress
+    attr_accessor :name
+    attr_accessor :date
+    attr_accessor :state
+    attr_accessor :customFields
+
+    def initialize(emailAddress = nil, name = nil, date = nil, state = nil, customFields = nil)
+      @emailAddress = emailAddress
+      @name = name
+      @date = date
+      @state = state
+      @customFields = customFields
+    end
+
+
+    #Adds a subscriber to a subscriber list, including adding custom field data for the subscriber. If the subscriber
+    #(email address) already exists, the name value is updated with whatever is passed in.
+    #
+    #If the list has been set as double opt-in, they will be sent the verification email, otherwise they will be sent the
+    #confirmation email you have set up for the list being subscribed to.
+    #
+    #<b>Please note</b>: If the subscriber is in an inactive state or has previously been unsubscribed, they will *not* be re-added
+    #to the active list. Therefore, this method should be used with caution and only where suitable.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
+    #containing a successful message.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def add!(list_id, custom_fields={})
+      params = {
+        :apiKey => CAMPAIGN_MONITOR_API_KEY,
+        :listID => list_id,
+        :email => @emailAddress,
+        :name => @name
+      }
+      if custom_fields.empty?
+        response = @@soap.addSubscriber(params)
+        handle_response response.subscriber_AddResult
+      else
+        params.merge!({:customFields => custom_fields_array(custom_fields)})
+        response = @@soap.addSubscriberWithCustomFields(params)
+        handle_response response.subscriber_AddWithCustomFieldsResult
+      end  
+    end
+
+
+    #Adds a subscriber to a subscriber list, including adding custom field data for the subscriber. If the subscriber (email address) already exists,
+    #the name value is updated with whatever is passed in.
+    #
+    #If the list has been set as double opt-in, they will be sent the verification email, otherwise they will be sent the
+    #confirmation email you have set up for the list being subscribed to.
+    #
+    #<b>Please note</b>: If the subscriber is in an inactive state or has previously been unsubscribed, they will be re-added to
+    #the active list. Therefore, this method should be used with caution and only where suitable.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
+    #containing a successful message.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def add_and_resubscribe!(list_id, custom_fields={})
+      params = {
+        :apiKey => CAMPAIGN_MONITOR_API_KEY,
+        :listID => list_id,
+        :email => @emailAddress,
+        :name => @name
+      }
+      if custom_fields.empty?
+        response = @@soap.addAndResubscribe(params)
+        handle_response response.subscriber_AddAndResubscribeResult
+      else
+        params.merge!({:customFields => custom_fields_array(custom_fields)})
+        response = @@soap.addAndResubscribeWithCustomFields(params)
+        handle_response response.subscriber_AddAndResubscribeWithCustomFieldsResult
+      end  
+    end
+
+
+    #Changes the status of an Active Subscriber to an Unsubscribed Subscriber who will no longer receive
+    #campaigns sent to that Subscriber List.
+    #
+    #If the list is set to add unsubscribing subscribers to the suppression list, then the subscriber’s email address will
+    #also be added to the suppression list.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
+    #containing a successful message.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def unsubscribe(list_id)
+      Subscriber.unsubscribe!(@emailAddress, list_id)
+    end
+
+
+    #Changes the status of an Active Subscriber to an Unsubscribed Subscriber who will no longer receive
+    #campaigns sent to that Subscriber List (Same that the instance method with the same name).
+    def self.unsubscribe!(email, list_id)
+      response = @@soap.unsubscribe(
+      :apiKey => CAMPAIGN_MONITOR_API_KEY,
+      :listID => list_id,
+      :email => email
+      )
+      handle_response response.subscriber_UnsubscribeResult
+    end
+
+    #Returns True or False as to the existence of the given email address in the list supplied.
+    def is_subscribed?(list_id)
+      Subscriber.is_subscribed?(@emailAddress, list_id)
+    end
+
+    #Returns True or False as to the existence of the given email address in the list supplied.
+    def self.is_subscribed?(email, list_id)
+      response = @@soap.getIsSubscribed(
+      :apiKey => CAMPAIGN_MONITOR_API_KEY,
+      :listID => list_id,
+      :email => email
+      )
+      response = handle_response response.subscribers_GetIsSubscribedResult
+      response == 'True' ? true : false
+    end
+
+
+    protected
+
+    def custom_fields_array(custom_fields) #:nodoc:
+      arr = []
+      custom_fields.each do |key, value|
+        arr << { :key => key, :value => value }
+      end
+      arr
+    end
+
+  end
+end