contactology 0.0.1

data/lib/contactology/campaign/preview.rb

@@ -0,0 +1,11 @@
+require 'contactology/stash'
+
+module Contactology
+  class Campaign
+    class Preview < Contactology::Stash
+      property :html
+      property :text
+      property :links
+    end
+  end
+end

data/lib/contactology/campaigns.rb

@@ -0,0 +1,2 @@
+module Contactology::Campaigns
+end

data/lib/contactology/campaigns/standard.rb

@@ -0,0 +1,80 @@
+require 'contactology/campaign'
+require 'contactology/campaigns'
+
+class Contactology::Campaigns::Standard < Contactology::Campaign
+  property :content, :required => true
+  property :name, :from => :campaignName, :required => true
+  property :recipients, :required => true
+  property :sender_email, :from => :senderEmail, :required => true
+  property :sender_name, :from => :senderName, :required => true
+  property :subject, :required => true
+
+
+  def []=(property, value)
+    if property.to_s == 'recipients'
+      super 'recipients', normalize_recipients(value)
+    else
+      super
+    end
+  end
+
+  def save(options = {})
+    self.class.query('Campaign_Create_Standard', options.merge({
+      'recipients' => recipients,
+      'campaignName' => name,
+      'subject' => subject,
+      'senderEmail' => sender_email,
+      'senderName' => sender_name,
+      'content' => content,
+      'optionalParameters' => {
+        'authenticate' => authenticate,
+        'replyToEmail' => reply_to_email,
+        'replyToName' => reply_to_name,
+        'trackReplies' => track_replies,
+        'recipientName' => recipient_name,
+        'showInArchive' => show_in_archive,
+        'viewInBrowser' => view_in_browser,
+        'trackOpens' => track_opens,
+        'trackClickThruHTML' => track_click_thru_html,
+        'trackClickThruText' => track_click_thru_text,
+        'googleAnalyticsName' => google_analytics_name,
+        'clickTaleName' => click_tale_name,
+        'clickTaleCustomFields' => click_tale_custom_fields,
+        'automaticTweet' => automatic_tweet
+      },
+      :on_error => false,
+      :on_timeout => false,
+      :on_success => Proc.new { |response| self.id = response; self }
+    }))
+  end
+
+  ##
+  # Public: Sends the campaign.
+  #
+  # Returns an empty collection when successful.
+  # Returns a collection of issues when unsuccessful.
+  #
+  def send_campaign(options = {})
+    self.class.query('Campaign_Send', options.merge({
+      'campaignId' => id,
+      :on_error => Proc.new { |response| process_send_campaign_result response },
+      :on_timeout => process_send_campaign_result({'success' => false, 'issues' => [{'text' => 'Connection timeout'}]}),
+      :on_success => Proc.new { |response| process_send_campaign_result response }
+    }))
+  end
+
+
+  private
+
+
+  def normalize_recipients(input)
+    input = [input].flatten.compact.uniq
+    input = input.select { |i| i.kind_of?(Contactology::List) }.collect { |list| list.id }
+    input = {'list' => input.size == 1 ? input.first : input}
+    input
+  end
+
+  def process_send_campaign_result(data)
+    Contactology::SendResult.new(data)
+  end
+end

data/lib/contactology/campaigns/transactional.rb

@@ -0,0 +1,58 @@
+require 'contactology/campaign'
+require 'contactology/campaigns'
+
+class Contactology::Campaigns::Transactional < Contactology::Campaign
+  property :test_contact, :from => :testContact
+  property :test_replacements, :from => :testReplacements
+
+
+  def self.create(attributes, options = {})
+    new(attributes).save(options)
+  end
+
+
+  ##
+  # Public: Stores the campaign information onto Contactology.
+  #
+  # Returns a Transactional instance with the campaign ID when successful.
+  # Returns a Contactology::SendResult instance with issues on failure.
+  #
+  def save(options = {})
+    self.class.query('Campaign_Create_Transactional', options.merge({
+      'campaignName' => name,
+      'content' => content,
+      'senderEmail' => sender_email,
+      'senderName' => sender_name,
+      'subject' => subject,
+      'testContact' => test_contact,
+      'testReplacements' => test_replacements,
+      'optionalParameters' => {
+        'authenticate' => authenticate,
+        'automaticTweet' => automatic_tweet,
+        'clickTaleCustomFields' => click_tale_custom_fields,
+        'clickTaleName' => click_tale_name,
+        'googleAnalyticsName' => google_analytics_name,
+        'recipientName' => recipient_name,
+        'replyToEmail' => reply_to_email,
+        'replyToName' => reply_to_name,
+        'showInArchive' => show_in_archive,
+        'trackClickThruHTML' => track_click_thru_html,
+        'trackClickThruText' => track_click_thru_text,
+        'trackOpens' => track_opens,
+        'trackReplies' => track_replies,
+        'viewInBrowser' => view_in_browser
+      },
+      :on_error => Proc.new { |response| process_send_campaign_result response },
+      :on_timeout => process_send_campaign_result('success' => false, 'issues' => [{'text' => 'Connection error'}]),
+      :on_success => Proc.new { |response| self.id = response; self }
+    }))
+  end
+
+
+  private
+
+
+  def process_send_campaign_result(data)
+    Contactology::SendResult.new(data)
+  end
+end

data/lib/contactology/configuration.rb

@@ -0,0 +1,42 @@
+##
+# Holds configuration objects used by the library.  The Contactology module
+# holds reference to a default Configuration, which will be used when no
+# explicit configurations are given to a particular query.
+#
+class Contactology::Configuration
+  ##
+  # Public: Set the API endpoint to be used.
+  #
+  # endpoint - The String to use for the API endpoint.
+  #
+  # Returns nothing.
+  #
+  attr_writer :endpoint
+
+  ##
+  # Public: Get the API key used for queries.
+  #
+  # Returns the String of the key.
+  #
+  attr_reader :key
+  #
+  ##
+  # Public: Set the API key used for queries.
+  #
+  # key - The String to use for the API key.
+  #
+  # Returns nothing.
+  #
+  attr_writer :key
+
+  ##
+  # Public: Get the API endpoint used by the configuration.  Unless explicitly
+  # set, the endpoint will default to the official production endpoint at
+  # "https://api.emailcampaigns.net/2/REST/".
+  #
+  # Returns the String for the API endpoint.
+  #
+  def endpoint
+    @endpoint ||= 'https://api.emailcampaigns.net/2/REST/'
+  end
+end

data/lib/contactology/contact.rb

@@ -0,0 +1,193 @@
+require 'contactology/stash'
+require 'contactology/api' 
+
+module Contactology
+  ##
+  # Represents a Contact on Contactology.  Contacts always must have an email
+  # address and then may optionally carry other custom fields.
+  #
+  class Contact < Contactology::Stash
+    extend API
+
+    property :id, :from => :contactId
+    property :email, :required => true
+    property :status
+    property :source
+    property :custom_fields, :from => :customFields
+
+
+    ##
+    # Public: Create a new contact.  The only required attribute is an :email
+    # address.
+    #
+    # Examples
+    # 
+    #   Contactology::Contact.create(:email => 'joe@example.local')
+    #   # => #<Contactology::Contact:0x000... @email="joe@example.com" ...>
+    #
+    # Returns a Contactology::Contact instance when successful.
+    # Returns false when unsuccessful or a network error occurs.
+    #
+    def self.create(attributes, options = {})
+      contact = new(attributes)
+      contact.save(options) ? contact : false
+    end
+
+    ##
+    # Public: Lookup a contact's information by email address.
+    #
+    # Examples
+    #
+    #   Contactology::Contact.find('joe@example.local')
+    #   # => #<Contactology::Contact:0x000... @email="joe@example.local" ...>
+    #
+    # Returns a Contactology::Contact instance when a match is found. Otherise,
+    # returns nil.
+    #
+    def self.find(email, options = {})
+      query('Contact_Get', options.merge({
+        'email' => email,
+        'optionalParameters' => {'getAllCustomFields' => true},
+        :on_timeout => nil,
+        :on_error => nil,
+        :on_success => Proc.new { |response|
+          Contact.new(response.values.first) if response.respond_to?(:values)
+        }
+      }))
+    end
+
+
+    ##
+    # Public: Indicates whether or not the contact is active.  Active contacts
+    # may receive mailings from your campaigns.
+    #
+    # Returns true if active.
+    # Returns false if non-active.
+    #
+    def active?
+      status == 'active'
+    end
+
+    ##
+    # Public: Indicates whether or not the contact has a bounced address. This
+    # means that mail delivery has failed in a way that Contactology is no
+    # longer sending mailings to this contact.
+    #
+    # Returns true if bounced.
+    # Returns false if non-bounced.
+    #
+    def bounced?
+      status == 'bounced'
+    end
+
+    ##
+    # Public: Changes the contact's email address to the new address given.
+    #
+    # Examples
+    #
+    #   contact = Contactology::Contact.find('joe@example.local')
+    #   # => #<Contactology::Contact:0x000... @email="joe@example.local" ...>
+    #   contact.change_email('jim@example.local')
+    #   # => true
+    #   contact.email
+    #   # => 'jim@example.local'
+    #
+    # Returns true when successful.
+    # Returns false when unsuccessful or for a network failure.
+    #
+    def change_email(new_email, options = {})
+      self.class.query('Contact_Change_Email', options.merge({
+        'email' => email,
+        'newEmail' => new_email,
+        :on_timeout => false,
+        :on_error => false,
+        :on_success => Proc.new { |response| self.email = new_email; true }
+      }))
+    end
+
+    def deleted?
+      status == 'deleted'
+    end
+
+    ##
+    # Public: Removes the contact from Contactology and from your account.
+    #
+    # Examples
+    #
+    #   contact = Contactology::Contact.find('joe@example.local')
+    #   # => #<Contactology::Contact:0x000... @email="joe@example.local" ...>
+    #   contact.destroy
+    #   # => true
+    # 
+    # Returns true when successful.
+    # Returns false when unsuccessful or for a network failure.
+    #
+    def destroy(options = {})
+      self.class.query('Contact_Delete', options.merge({
+        :email => email,
+        :on_timeout => false,
+        :on_error => false,
+        :on_success => Proc.new { |r| self.status = 'deleted'; true }
+      }))
+    end
+
+    def lists(options = {})
+      self.class.query('Contact_Get_Subscriptions', options.merge({
+        'email' => email,
+        :on_timeout => [],
+        :on_error => [],
+        :on_success => Proc.new { |response|
+          response.collect { |listid| ListProxy.new(listid) }
+        }
+      }))
+    end
+
+    def save(options = {})
+      self.class.query('Contact_Add', {
+        'email' => email,
+        'customFields' => custom_fields,
+        'optionalParameters' => {'updateCustomFields' => true},
+        :on_timeout => false,
+        :on_error => false,
+        :on_success => Proc.new { |response| self.status = 'active'; self }
+      })
+    end
+
+    def save!(options = {})
+      save(options) || raise(InvalidObjectError)
+    end
+
+    ##
+    # Public: Suppresses the contact, removing them from receiving campaign
+    # mailings.
+    #
+    # Returns true when successful.
+    # Returns false when unsuccessful.
+    #
+    def suppress(options = {})
+      response = self.class.query('Contact_Suppress', options.merge({
+        :email => email,
+        :on_timeout => false,
+        :on_error => false,
+        :on_success => Proc.new { |response| response }
+      }))
+
+      if response
+        self.status = 'suppressed'
+      end
+
+      response
+    end
+
+    ##
+    # Public: Indicates whether or not the contact is suppressed.  Suppressed
+    # contacts may not receive mailings from your campaigns.
+    #
+    # Returns true if suppressed.
+    # Returns false if non-suppressed.
+    #
+    def suppressed?
+      status == 'suppressed'
+    end
+  end
+end

data/lib/contactology/errors.rb

@@ -0,0 +1,4 @@
+module Contactology
+  Error = Class.new(StandardError)
+  InvalidObjectError = Class.new(Error)
+end

data/lib/contactology/issue.rb

@@ -0,0 +1,24 @@
+module Contactology
+  class Issue
+    attr_reader :type
+    attr_reader :text
+    attr_reader :message
+    attr_reader :context
+    attr_reader :col
+    attr_reader :deduction
+
+    def initialize(details)
+      details = Hash.new unless details.kind_of?(Hash)
+      @type = details['type']
+      @text = details['text']
+      @message = details['message']
+      @context = details['context']
+      @col = details['col']
+      @deduction = details['deduction']
+    end
+
+    def to_s
+      "%s: %s, %d point deduction" % [type, text || message, deduction]
+    end
+  end
+end

data/lib/contactology/issues.rb

@@ -0,0 +1,18 @@
+require 'contactology/issue'
+
+module Contactology
+  class Issues < Array
+    attr_reader :score
+
+    def initialize(data = nil)
+      data = Hash.new unless data.kind_of?(Hash)
+      @score = data['score'] || 0
+      (data['issues'] || []).each { |i| self << i }
+    end
+
+
+    def <<(o)
+      super(Issue.new(o))
+    end
+  end
+end

data/lib/contactology/list.rb

@@ -0,0 +1,192 @@
+require 'contactology/stash'
+require 'contactology/api' 
+
+module Contactology
+  ##
+  # Represents a subscription List in Contactology. Lists are a convenient way
+  # to organize groups of Contacts in order to send large numbers of contacts
+  # a Campaign, easily.
+  #
+  class List < Contactology::Stash
+    extend API
+
+    property :id, :from => :listId
+    property :name, :required => true
+    property :description
+    property :type
+    property :opt_in, :from => :optIn
+
+
+    ##
+    # Public: Returns a collection of all active lists on your account.
+    #
+    # Returns a collection of Contactology::List instances.
+    #
+    def self.all(options = {})
+      query('List_Get_Active_Lists', options.merge({
+        :on_timeout => [],
+        :on_error => [],
+        :on_success => Proc.new { |response| response.values.collect { |list| List.new(list) }}
+      }))
+    end
+
+    ##
+    # Public: Creates a new, public list on Contactology. The new list's :name
+    # is the only required attribute.
+    #
+    # Returns a Contactology::List instance when successful.
+    # Returns false when unsuccessful or a network failure occurs.
+    #
+    def self.create(attributes, options = {})
+      raise ArgumentError, 'Expected an :name attribute' unless attributes.has_key?(:name)
+      new(attributes).save(options)
+    end
+
+    ##
+    # Public: Loads a Contactology list by ID.
+    #
+    # Returns a Contactology::List instance on success.
+    # Returns nil for an unknown ID or network error.
+    #
+    def self.find(id, options = {})
+      query('List_Get_Info', options.merge({
+        'listId' => id,
+        :on_timeout => nil,
+        :on_error => nil,
+        :on_success => Proc.new { |response| new(response) if response.kind_of?(Hash) }
+      }))
+    end
+
+
+    ##
+    # Public: Removes a list from Contactology.
+    #
+    # Returns true when successful.
+    # Returns false when unsuccessful.
+    #
+    def destroy(options = {})
+      self.class.query('List_Delete', options.merge({
+        'listId' => id,
+        :on_timeout => false,
+        :on_error => false,
+        :on_success => Proc.new { |response| response }
+      }))
+    end
+
+    ##
+    # Public: Imports contacts into a list using a prescribed contact
+    # collection format.
+    #
+    # Examples
+    #
+    #   list = Contactology::List.create :name => 'import-test'
+    #   # => #<Contactology::List:0x000... @name="import-test" ...>
+    #   list.import([{'email' => 'import@example.local', 'first_name' => 'Imp', 'last_name' => 'Orted'}, {...}])
+    #   # => true
+    #
+    # Returns true if all contacts imported successfully.
+    # Returns false if any contact import failed or a network error occurred.
+    #
+    def import(contacts, options = {})
+      self.class.query('List_Import_Contacts', options.merge({
+        'listId' => id,
+        'source' => options[:source] || 'Manual Entry',
+        'contacts' => contacts,
+        'optionalParameters' => {
+          'activateDeleted' => true,
+          'updateCustomFields' => true
+        },
+        :on_timeout => false,
+        :on_error => false,
+        :on_success => Proc.new { |response|
+          response.kind_of?(Hash) && response['success'] == contacts.size
+        }
+      }))
+    end
+
+    def internal?
+      type == 'internal'
+    end
+
+    def opt_in?
+      opt_in
+    end
+
+    def public?
+      type == 'public'
+    end
+
+    def private?
+      type == 'private'
+    end
+
+    def save(options = {})
+      self.class.query('List_Add_Public', options.merge({
+        'listId' => id,
+        'name' => name,
+        'description' => description,
+        'optionalParameters' => {
+          'optIn' => opt_in
+        },
+        :on_timeout => false,
+        :on_error => false,
+        :on_success => Proc.new { |response|
+          data = self.class.find(response)
+          self.id = data.id
+          self.description = data.description
+          self.name = data.name
+          self.type = data.type
+          self.opt_in = data.opt_in
+          self
+        }
+      }))
+    end
+
+    def save!(options = {})
+      save(options) || raise(InvalidObjectError)
+    end
+
+    ##
+    # Public: Adds an email address to the list.
+    #
+    # Examples
+    #
+    #   list = Contactology::List.find 1
+    #   # => #<Contactology::List:0x000... @id="1" ...>
+    #   list.subscribe 'new@example.local'
+    #   # => true
+    #
+    # Returns true when the address is successfully added.
+    # Returns false when the subscription fails or a network error occurs.
+    #
+    def subscribe(email, options = {})
+      self.class.query('List_Subscribe', options.merge({
+        'listId' => id,
+        'email' => email.respond_to?(:email) ? email.email : email,
+        :on_timeout => false,
+        :on_error => false,
+        :on_success => Proc.new { |response| response }
+      }))
+    end
+
+    def test?
+      type == 'test'
+    end
+
+    ##
+    # Public: Unsubscribes an email address from the Contactology::List.
+    #
+    # Returns true when the address is removed.
+    # Returns false when the removal fails or a network error occurs.
+    #
+    def unsubscribe(email, options = {})
+      self.class.query('List_Unsubscribe', options.merge({
+        'listId' => id,
+        'email' => email,
+        :on_timeout => false,
+        :on_error => false,
+        :on_success => Proc.new { |response| response }
+      }))
+    end
+  end
+end