infusionsoft 1.0.2 → 1.0.3

data/README.md

@@ -1,14 +1,19 @@
 # The Infusionsoft Ruby Gem
 A Ruby wrapper for the Infusionsoft API
 
+**This is a complete rewrite and has been implemented as a RubyGem**
+All previous versions will need to update their calls to follow the new schema
+
 ## <a name="installation">Installation</a>
     gem install infusionsoft
 
 ## <a name="documentation">Documentation</a>
-documentation link here
+[http://rubydoc.info/gems/infusionsoft/1.0.2/frames](http://rubydoc.info/gems/infusionsoft/1.0.2/frames)
 
 ## <a name="setup">Setup & Configuration</a>
-For Rails, create an initilizer in `config\initilizers` called infusionsoft.rb and the following
+For Rails 2.3 add `config.gem 'infusionsoft'` or for Rails 3 add it to Bundler
+
+Then create an initilizer in `config\initilizers` called infusionsoft.rb and the following
 
     Infusionsoft.configure do |config|
       config.api_url = 'YOUR_INFUSIONSOFT_URL' # example infused.infusionsoft.com

data/lib/infusionsoft.rb

@@ -1,7 +1,6 @@
 require 'infusionsoft/api'
 require 'infusionsoft/client'
 require 'infusionsoft/configuration'
-#require 'api_infusionsoft/error'
 
 module Infusionsoft
   extend Configuration

data/lib/infusionsoft/client.rb

@@ -12,7 +12,8 @@ module Infusionsoft
     require 'infusionsoft/client/data'
     require 'infusionsoft/client/affiliate'
     require 'infusionsoft/client/file'
-    require 'infusionsoft/client/ticket'
+    require 'infusionsoft/client/ticket' # Deprecated by Infusionsoft
+    require 'infusionsoft/client/search'
 
     include Infusionsoft::Client::Contact
     include Infusionsoft::Client::Email
@@ -20,6 +21,7 @@ module Infusionsoft
     include Infusionsoft::Client::Data
     include Infusionsoft::Client::Affiliate
     include Infusionsoft::Client::File
-    include Infusionsoft::Client::Ticket
+    include Infusionsoft::Client::Ticket # Deprecated by Infusionsoft
+    include Infusionsoft::Client::Search
   end
 end

data/lib/infusionsoft/client/affiliate.rb

@@ -1,51 +1,61 @@
 module Infusionsoft
   class Client
-    ########################
-    ### Affiliate Service ##
-    ########################
+    # The Affiliate service is used to pull commission data and activities for affiliates.
+    # With this service, you have access to Clawbacks, Commissions, Payouts, Running Totals,
+    # and the Activity Summary. The methods in the Affiliate service mirror the reports
+    # produced inside Infusionsoft.
+    #
+    # @note To manage affiliate information (ie Name, Phone, etc.) you will need to use the Data service.
     module Affiliate
-      # return all claw backs in a date range
+      # Used when you need to retrieve all clawed back commissions for a particular affiliate.
       #
-      # @affiliate_id [Integer]
-      # @start_date [Date]
-      # @end_date [Date]
+      # @param [Integer] affiliate_id
+      # @params [Date] start_date
+      # @end_date [Date] end_date
+      # @return [Array] all claw backs for the given affiliate that have occurred within the date
+      #   range specified
       def affiliate_clawbacks(affiliate_id, start_date, end_date)
-        response = get('APIAffiliateService', 'affClawbacks', affiliate_id, start_date, end_date)
+        response = get('APIAffiliateService.affClawbacks', affiliate_id, start_date, end_date)
       end
 
-      # return all commissions in a date range
+      # Used to retrieve all commissions for a specific affiliate within a date range.
       #
-      # @affiliate_id [Integer]
-      # @start_date [Date]
-      # @end_date [Date]
+      # @param [Integer] affiliate_id
+      # @param [Date] start_date
+      # @param [Date] end_date
+      # @return [Array] all sales commissions for the given affiliate earned within the date range
+      #   specified
       def affiliate_commissions(affiliate_id, start_date, end_date)
-        response = get('APIAffiliateService', 'affCommissions', affiliate_id, start_date, end_date)
+        response = get('APIAffiliateService.affCommissions', affiliate_id, start_date, end_date)
       end
 
-      # return all payouts in a date range
+      # Used to retrieve all payments for a specific affiliate within a date range.
       #
-      # @affiliate_id [Integer]
-      # @start_date [Date]
-      # @end_date [Date]
+      # @param [Integer] affiliate_id
+      # @param [Date] start_date
+      # @param [Date] end_date
+      # @return [Array] a list of rows, each row is a single payout
       def affiliate_payouts(affiliate_id, start_date, end_date)
-        response = get('APIAffiliateService', 'affPayouts', affiliate_id, start_date, end_date)
+        response = get('APIAffiliateService.affPayouts', affiliate_id, start_date, end_date)
       end
 
-      # returns a list with each row representing a single affiliates totals represented by a map with key
-      # one of the names above, and value being the total for the variable
+      # This method is used to retrieve all commissions for a specific affiliate within a date range.
       #
-      # @affiliate_list [Array]
+      # @param [Array] affiliate_list
+      # @return [Array] all sales commissions for the given affiliate earned within the date range
+      #   specified
       def affiliate_running_totals(affiliate_list)
-        response = get('APIAffiliateService', 'affRunningTotals', affiliate_list)
+        response = get('APIAffiliateService.affRunningTotals', affiliate_list)
       end
 
-      # return how much the specified affiliates are owed
+      # Used to retrieve a summary of statistics for a list of affiliates.
       #
-      # @affiliate_list [Array]
-      # @start_date [Date]
-      # @end_date [Date]
+      # @param [Array] affiliate_list
+      # @param [Date] start_date
+      # @param [Date] end_date
+      # @return [Array<Hash>] a summary of the affiliates information for a specified date range
       def affiliate_summary(affiliate_list, start_date, end_date)
-        response = get('APIAffiliateService', 'affSummary', affiliate_list, start_date, end_date)
+        response = get('APIAffiliateService.affSummary', affiliate_list, start_date, end_date)
       end
     end
   end

data/lib/infusionsoft/client/contact.rb

@@ -1,143 +1,187 @@
 module Infusionsoft
   class Client
-    ########################  
-    ### Contact Service  ###
-    ########################
+    # Contact service is used to manage contacts. You can add, update and find contacts in
+    # addition to managing follow up sequences, tags and action sets.
     module Contact
-      # Finds all contacts with the supplied email address in any of the three contact record email addresses
+      # Creates a new contact record from the data passed in the associative array.
       #
-      # @email [String]
-      # @selected_fields [Array]
-      def contact_find_by_email(email, selected_fields)
-        response = get('ContactService.findByEmail', email, selected_fields)
-      end
-
-      # Adds a contact to the database, then opts in the email address
-      #
-      # @data = [Hash]
-      # @example data = {:EmailAddress1 => 'test@test.com', :FirstName => 'first_name', :LastName => 'last_name'}
-      # @returns [Integer] This is the id of the newly added contact
+      # @param [Hash] data contains the mappable contact fields and it's data
+      # @return [Integer] the id of the newly added contact
+      # @example
+      #   { :Email => 'test@test.com', :FirstName => 'first_name', :LastName => 'last_name' }
       def contact_add(data)
         contact_id = get('ContactService.add', data)
-        if data.has_key?("Email"); api_email_optin(data["Email"], "requested information"); end
+        if data.has_key?("Email"); email_optin(data["Email"], "requested information"); end
         return contact_id
       end
 
-      # Creates a new recurring order for a contact.
+      # Adds or updates a contact record based on matching data
       #
-      # @contact_id [Integer]
-      # @allow_duplicate [Boolean]
-      # @cprogram_id [Integer]
-      # @merchante_account_id [Integer]
-      # @credit_card_id [Integer]
-      # @affiliate_id [Integer]
-      def contact_add_recurring_order(contact_id, allow_duplicate, cprogram_id, merchant_account_id, credit_card_id, affiliate_id,
-                            days_till_charge)
-        response = get('ContactService','addRecurringOrder', contact_id, allow_duplicate, cprogram_id, 
-                            merchant_account_id, credit_card_id, affiliate_id, days_till_charge)
+      # @param [Array<Hash>] data the contact data you want added
+      # @param [String] check_type available options are 'Email', 'EmailAndName',
+      #   'EmailAndNameAndCompany'
+      # @return [Integer] id of the contact added or updated
+      def contact_add_with_dup_check(data, check_type)
+        response = get('ContactService.addWithDupCheck', data, check_type)
       end
 
-      # Adds a contact to a group
+      # Updates a contact in the database.
       #
-      # @contact_id [Integer]
-      # @group_id [Integer]
-      def contact_add_to_group(contact_id, group_id)
-        response = get('ContactService', 'addToGroup', contact_id, group_id)
-      end
-
-      def contact_link_contact(remoteApp, remoteId, localId)
-        response = get('ContactService', 'linkContact', remoteApp, remoteId, localId)
+      # @param [Integer] contact_id
+      # @param [Hash] data contains the mappable contact fields and it's data
+      # @return [Integer] the id of the contact updated
+      # @example
+      #   { :FirstName => 'first_name', :StreetAddress1 => '123 N Street' }
+      def contact_update(contact_id, data)
+        bool = get('ContactService.update', contact_id, data)
+        if data.has_key?("Email"); email_optin(data["Email"], "requested information"); end
+        return bool
       end
 
       # Loads a contact from the database
       #
-      # @id [Integer]
-      # @selected_fields [Array]
+      # @param [Integer] id
+      # @param [Array] selected_fields the list of fields you want back
+      # @return [Array] the fields returned back with it's data
+      # @example this is what you would get back
+      #   { "FirstName" => "John", "LastName" => "Doe" }
       def contact_load(id, selected_fields)
-        response = get('ContactService', 'load', id, selected_fields)
+        response = get('ContactService.load', id, selected_fields)
       end
 
-      def contact_locate_contact_link(locate_map_id)
-        response = get('ContactService', 'locateContactLink', locate_map_id)
+      # Finds all contacts with the supplied email address in any of the three contact record email
+      # addresses.
+      #
+      # @param [String] email
+      # @param [Array] selected_fields the list of fields you want with it's data
+      # @return [Array<Hash>] the list of contacts with it's fields and data
+      def contact_find_by_email(email, selected_fields)
+        response = get('ContactService.findByEmail', email, selected_fields)
       end
 
-      def contact_mark_link_updated(locate_map_id)
-        response = get('ContactService', 'markLinkUpdated', locate_map_id)
+      # Adds a contact to a follow-up sequence (campaigns were the original name of follow-up sequences).
+      #
+      # @param [Integer] contact_id
+      # @param [Integer] campaign_id
+      # @return [Boolean] returns true/false if the contact was added to the follow-up sequence
+      #   successfully
+      def contact_add_to_campaign(contact_id, campaign_id)
+        response = get('ContactService.addToCampaign', contact_id, campaign_id)
       end
 
-      # Adds a contact to a campaign.
+      # Returns the Id number of the next follow-up sequence step for the given contact.
       #
-      # @contact_id [Integer]
-      # @campaign_id [Integer]
-      def contact_add_to_campaign(contact_id, campaign_id)
-        response = get('ContactService','addToCampaign', contact_id, campaign_id)
+      # @param [Integer] contact_id
+      # @param [Integer] campaign_id
+      # @return [Integer] id number of the next unfishished step in the given follow up sequence
+      #   for the given contact
+      def contact_get_next_campaign_step(contact_id, campaign_id)
+        response = get('ContactService.getNextCampaignStep', contact_id, campaign_id)
       end
 
-      # Pauses a campaign for a given contact.
+      # Pauses a follow-up sequence for the given contact record
       #
-      # @contact_id [Integer]
-      # @campaign_id [Integer]
+      # @param [Integer] contact_id
+      # @param [Integer] campaign_id
+      # @return [Boolean] returns true/false if the sequence was paused
       def contact_pause_campaign(contact_id, campaign_id)
-        response = get('ContactService', 'pauseCampaign', contact_id, campaign_id)
+        response = get('ContactService.pauseCampaign', contact_id, campaign_id)
       end
 
-      # Removes a contact from a given campaign.
+      # Removes a follow-up sequence from a contact record
       #
-      # @contact_id [Integer]
-      # @campaign_id [Integer]
+      # @param [Integer] contact_id
+      # @param [Integer] campaign_id
+      # @return [Boolean] returns true/false if removed
       def contact_remove_from_campaign(contact_id, campaign_id)
-        response = get('ContactService', 'removeFromCampaign', contact_id, campaign_id)
+        response = get('ContactService.removeFromCampaign', contact_id, campaign_id)
       end
 
-      # returns the next step in a campaign
+      # Resumes a follow-up sequence that has been stopped/paused for a given contact.
       #
-      # @contact_id [Integer]
-      # @campaign_id [Integer]
-      def contact_get_next_campaign_step(contact_id, campaign_id)
-        response = get('ContactService', 'getNextCampaignStep', contact_id, campaign_id)
+      # @param [Integer] contact_id
+      # @param [Ingeger] campaign_id
+      # @return [Boolean] returns true/false if sequence was resumed
+      def contact_resume_campaign(contact_id, campaign_id)
+        response = get('ConactService.resumeCampaignForContact', contact_id, campaign_id)
       end
 
-      # Reschedules a campaign step for a list of contacts
+      # Immediately performs the given follow-up sequence step_id for the given contacts.
       #
-      # @list_of_contacts [Array]
-      # @campaign_id [Integer]
-      def contact_reschedule_campaign_step(list_of_contacts, campaign_id)
-        response = get('ContactService', 'reschedulteCampaignStep', list_of_contacts, campaign_id)
+      # @param [Array<Integer>] list_of_contacts
+      # @param [Integer] ) step_id
+      # @return [Boolean] returns true/false if the step was rescheduled
+      def contact_reschedule_campaign_step(list_of_contacts, step_id)
+        response = get('ContactService.reschedulteCampaignStep', list_of_contacts, step_id)
       end
 
-      # Removes a contact from a given group.
+      # Removes a tag from a contact (groups were the original name of tags).
       #
-      # @contact_id [Integer]
-      # @group_id [Integer]
+      # @param [Integer] contact_id
+      # @param [Integer] group_id
+      # @return [Boolean] returns true/false if tag was removed successfully
       def contact_remove_from_group(contact_id, group_id)
-        response = get('ContactService', 'removeFromGroup', contact_id, group_id)
+        response = get('ContactService.removeFromGroup', contact_id, group_id)
+      end
+
+      # Adds a tag to a contact
+      #
+      # @param [Integer] contact_id
+      # @param [Integer] group_id
+      # @return [Boolean] returns true/false if the tag was added successfully
+      def contact_add_to_group(contact_id, group_id)
+        response = get('ContactService.addToGroup', contact_id, group_id)
       end
 
-      # Executes an action sequence for a given contact
+      # Runs an action set on a given contact record
+      #
+      # @param [Integer] contact_id
+      # @param [Integer] action_set_id
+      # @return [Array<Hash>] A list of details on each action run
+      # @example here is a list of what you get back
+      #   [{ 'Action' => 'Create Task', 'Message' => 'task1 (Task) sent successfully', 'isError' =>
+      #   nil }]
       def contact_run_action_set(contact_id, action_set_id)
-        response = get('ContactService', 'runActionSequence', contact_id, action_set_id)
+        response = get('ContactService.runActionSequence', contact_id, action_set_id)
+      end
+
+      def contact_link_contact(remoteApp, remoteId, localId)
+        response = get('ContactService.linkContact', remoteApp, remoteId, localId)
+      end
+
+
+      def contact_locate_contact_link(locate_map_id)
+        response = get('ContactService.locateContactLink', locate_map_id)
+      end
+
+      def contact_mark_link_updated(locate_map_id)
+        response = get('ContactService.markLinkUpdated', locate_map_id)
       end
 
-      # Executes an action sequence for a given contact, passing in
-      # runtime params for running affiliate signup actions, etc
+      # Creates a new recurring order for a contact.
       #
-      # @contact_id [Integer]
-      # @action_set_id [Integer]
-      # @params [Hash]
-      def contact_run_action_set_with_params(contact_id, action_set_id, params)
-        response = get('ContactService', 'runActionSequence', contact_id, action_set_id, params)
+      # @param [Integer] contact_id
+      # @param [Boolean] allow_duplicate
+      # @param [Integer] cprogram_id
+      # @param [Integer] merchant_account_id
+      # @param [Integer] credit_card_id
+      # @param [Integer] affiliate_id
+      def contact_add_recurring_order(contact_id, allow_duplicate, cprogram_id, merchant_account_id,
+                                      credit_card_id, affiliate_id, days_till_charge)
+        response = get('ContactService.addRecurringOrder', contact_id, allow_duplicate, cprogram_id,
+                            merchant_account_id, credit_card_id, affiliate_id, days_till_charge)
       end
 
-      # Updates a contact in the database.
+      # Executes an action sequence for a given contact, passing in runtime params
+      # for running affiliate signup actions, etc
       #
-      # @contact_id [Integer]
-      # @data [Hash]
-      # @example {:FirstName => 'first_name', :StreetAddress1 => '123 N Street'}
-      def contact_update(contact_id, data)
-        bool = get('ContactService', 'update', contact_id, data)
-        if data.has_key?("Email"); api_email_optin(data["Email"], "requested information"); end
-        return bool
+      # @param [Integer] contact_id
+      # @param [Integer] action_set_id
+      # @param [Hash] data
+      def contact_run_action_set_with_params(contact_id, action_set_id, data)
+        response = get('ContactService.runActionSequence', contact_id, action_set_id, data)
       end
+
     end
   end
 end

data/lib/infusionsoft/client/data.rb

@@ -1,89 +1,131 @@
 module Infusionsoft
   class Client
-    ########################
-    ###   Data Service   ###
-    ########################
+    # The Data service is used to manipulate most data in Infusionsoft. It permits you to
+    # work on any available tables and has a wide range of uses.
     module Data
-      # Adds a record to the database. If you attempt to set fields that are marked read-only
-      # by the Data Spec, this operation will simply ignore those fields - not throw an error
+      # Adds a record with the data provided.
       #
-      # @table [String]
-      # @values [Hash]
-      def data_add(table, values)
-        response = get('DataService.add', table, values)
+      # @param [String] table the name of the Infusiosoft database table
+      # @param [Hash] data the fields and it's data
+      # @return [Integer] returns the id of the record added
+      def data_add(table, data)
+        response = get('DataService.add', table, data)
+      end
+
+      # This method will load a record from the database given the primary key.
+      #
+      # @param [String] table
+      # @param [Integer] id
+      # @param [Array] selected_fields
+      # @return [Hash] the field names and their data
+      # @example
+      #   { "FirstName" => "John", "LastName" => "Doe" }
+      def data_load(table, id, selected_fields)
+        response = get('DataService.load', table, id, selected_fields)
+      end
+
+      # Updates the specified record (indicated by ID) with the data provided.
+      #
+      # @param [String] table
+      # @param [Integer] id
+      # @param [Hash] data this is the fields and values you would like to update
+      # @return [Integer] id of the record updated
+      # @example
+      #   { :FirstName => 'John', :Email => 'test@test.com' }
+      def data_update(table, id, data)
+        response = get('DataService.update', table, id, data)
+      end
+
+      # Deletes the record (specified by id) in the given table from the database.
+      #
+      # @param [String] table
+      # @param [Integer] id
+      # @return [Boolean] returns true/false if the record was successfully deleted
+      def data_delete(table, id)
+        response = get('DataService.delete', table, id)
       end
 
       # This will locate all records in a given table that match the criteria for a given field.
       #
-      # @table [String]
-      # @limit [Integer]
-      # @page [Integer]
-      # @field_name [String]
-      # @field_value [String]
-      # @selected_fields [Array]
+      # @param [String] table
+      # @param [Integer] limit how many records you would like to return (max is 1000)
+      # @param [Integer] page the page of results (each page is max 1000 records)
+      # @param [String] field_name
+      # @param [String, Integer, Date] field_value
+      # @param [Array] selected_fields
+      # @return [Array<Hash>] returns the array of records with a hash of the fields and values
       def data_find_by_field(table, limit, page, field_name, field_value, selected_fields)
         response = get('DataService.findByField', table, limit, page, field_name,
                        field_value, selected_fields)
       end
 
-      # This method will load a record from the database given the primary key
+      # Queries records in a given table to find matches on certain fields.
       #
-      # @table [String]
-      # @id [Integer]
-      # @selected_fields [Array]
-      def data_load(table, id, selected_fields)
-        response = get('DataService.load', table, id, selected_fields)
-      end
-
-      # Queries records in a given table to find matches on certain fields
-      #
-      # @table [String]
-      # @limit [Integer]
-      # @page [Integer]
-      # @data [Hash] The data you would like to query on. { :FirstName => 'first_name' }
-      # @selected_fields [Array]
+      # @param [String] table
+      # @param [Integer] limit
+      # @param [Integer] page
+      # @param [Hash] data  the data you would like to query on. { :FirstName => 'first_name' }
+      # @param [Array] selected_fields the fields and values you want back
+      # @return [Array<Hash>] the fields and associated values
       def data_query(table, limit, page, data, selected_fields)
         response = get('DataService.query', table, limit, page, data, selected_fields)
       end
 
-      # Updates a given record to the database
+      # Adds a custom field to Infusionsoft
       #
-      # @table [String]
-      # @id [Integer]
-      # @values [Hash] This is the fields and values you would like to update
-      # @example { :FirstName => 'first_name', :EmailAddress1 => 'test@test.com' }
-      def data_update(table, id, values)
-        response = get('DataService.update', table, id, values)
+      # @param [String] field_type options include Person, Company, Affiliate, Task/Appt/Note,
+      #   Order, Subscription, or Opportunity
+      # @param [String] name
+      # @param [String] data_type the type of field Text, Dropdown, TextArea
+      # @param [Integer] header_id see notes here
+      #   http://help.infusionsoft.com/developers/services-methods/data/addCustomField
+      def data_add_custom_field(field_type, name, data_type, header_id)
+        response = get('DataService.addCustomField', field_type, name, data_type, header_id)
       end
 
-      # Adds a custom field to Infusionsoft
+      # Authenticate an Infusionsoft username and password(md5 hash). If the credentials match
+      # it will return back a User ID, if the credentials do not match it will send back an
+      # error message
       #
-      # @context [String]
-      # @label [String]
-      # @data_type [String]
-      # @group_id [Integer]
-      def data_add_custom_field(context, label, data_type, group_id)
-        response = get('DataService.addCustomField', context, label, data_type, group_id)
+      # @param [String] username
+      # @param [String] password
+      # @return [Integer] id of the authenticated user
+      def data_authenticate_user(username, password)
+        response = get('DataService.authenticateUser', username, password)
       end
 
-      # Updates a custom field
+      # This method will return back the data currently configured in a user configured
+      # application setting.
       #
-      # @field_id [Integer]
-      # @field_value
-      def data_update_custom_field(field_id, field_value)
-        response = get('DataService.updateCustomField', field_id, field_value)
+      # @param [String] module
+      # @param [String] setting
+      # @return [String] current values in given application setting
+      # @note to find the module and option names, view the HTML field name within the Infusionsoft
+      #   settings. You will see something such as name="Contact_WebModule0optiontypes" . The portion
+      #   before the underscore is the module name. "Contact" in this example. The portion after the
+      #   0 is the setting name, "optiontypes" in this example.
+      def data_get_app_setting(module_name, setting)
+        response = get('DataService.getAppSetting', module_name, setting)
       end
 
-      # Authenticates a user account in Infusionsoft
+      # Returns a temporary API key if given a valid Vendor key and user credentials.
       #
-      # @username [String]
-      # @password [String]
-      def data_authenticate_user(username, password)
-        response = get('DataService.authenticateUser', username, password)
+      # @param [String] vendor_key
+      # @param [String] username
+      # @param [String] password_hash an md5 hash of users password
+      # @return [String] temporary API key
+      def data_get_temporary_key(vendor_key, username, password_hash)
+        response = get('DataService.getTemporaryKey', username, password_hash)
       end
 
-      def data_echo(text)
-        response = get('DataService.echo', text)
+      # Updates a custom field. Every field can have it’s display name and group id changed,
+      # but only certain data types will allow you to change values(dropdown, listbox, radio, etc).
+      #
+      # @param [Integer] field_id
+      # @param [Hash] field_values
+      # @return [Boolean] returns true/false if it was updated
+      def data_update_custom_field(field_id, field_values)
+        response = get('DataService.updateCustomField', field_id, field_values)
       end
     end
   end