capsulecrm-b 0.0.6

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,10 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in capsulecrm.gemspec
+gemspec
+
+group :development do
+  gem 'webmock'
+  gem 'vcr'
+end
+  

data/README.rdoc

@@ -0,0 +1,33 @@
+= CapsuleCRM
+
+This is a ruby wrapper for the CapsuleCRM API.  It is alpha software and should be considered a work in progress.  It currently supports People & Organisations.  There is support for CustomFields & Contacts but they are read-only.
+
+== Installation
+
+  [sudo] gem install capsulecrm
+
+  gem 'capsulecrm' # rails
+  require 'capsulecrm' # non-rails
+
+== Getting started
+
+You will need to supply the gem with your CapsuleCRM API token and account name. The account name is the first part of your CapsuleCRM url:
+
+  CapsuleCRM.account_name = "test-account" # http://test-account.capsulecrm.com
+  CapsuleCRM.api_token = 'MY_API_TOKEN'
+  CapsuleCRM.initialize!
+
+If you're using rails, you can put that in config/initializers/capsulecrm.rb
+
+
+== Usage
+
+Please see examples.rb for usage examples
+
+== Feedback
+
+Bug reports, feature requests and patches are welcome.  Please create an issue on the github issue tracker.
+
+== License
+
+MIT License. Copyright 2011 Ahmed Adam

data/Rakefile

@@ -0,0 +1,9 @@
+require 'bundler'
+require 'rake/testtask'
+Bundler::GemHelper.install_tasks
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+end

data/capsulecrm.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "capsulecrm/version"
+
+Gem::Specification.new do |s|
+  s.name        = "capsulecrm-b"
+  s.version     = CapsuleCRM::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Ahmed Adam", "dsimard", "FWMatt"]
+  s.email       = ["ahmed.msgs@gmail.com", "dsimard@azanka.ca", "matt@futureworkshops.com"]
+  s.homepage    = "https://github.com/dsimard/capsulecrm"
+  s.summary     = %q{CapsuleCRM API Gem}
+  s.description = %q{CapsuleCRM API Gem}
+
+  s.add_dependency 'httparty', '~> 0.7'
+  s.add_dependency 'activemodel', '~> 3.0'
+  s.add_dependency 'activesupport', '~> 3.0'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/examples.rb

@@ -0,0 +1,82 @@
+# NOTE: CapsuleCRM::Person and CapsuleCRM::Organisation have virtually identically methods.
+require 'capsulecrm'
+
+# find by id
+person = CapsuleCRM::Person.find 123
+
+# or if you don't know what you are searching for Party
+something = CapsuleCRM::Party.find 123
+something.is?(:person)
+something.is?(:organisation)
+
+# find by email
+person = CapsuleCRM::Person.find_by_email 'foo@example.com'
+
+# find all
+person = CapsuleCRM::Person.find :all, :offset => 10, :limit => 5
+
+# find by search term (searches name, telephone number and searchable custom fields)
+person = CapsuleCRM::Person.search 'fred', :offset => 10, :limit => 5
+
+# CapsuleCRM::Person attributes
+person.id
+person.title
+person.first_name
+person.last_name
+person.job_title
+person.about
+
+# Add a note to the history
+person.add_history "This is a note"
+
+# update a person object
+person.first_name = "Homer"
+person.last_name = "Simpson"
+person.save # returns true/false
+
+# create a person object
+person = CapsuleCRM::Person.new
+person.first_name = "Marge"
+person.last_name = "Simpson"
+person.save # returns true/false
+
+
+# get the person's organisation
+person.organisation # CapsuleCRM::Organisation
+
+# CapsuleCRM::Organisation attributes:
+organisation.about
+organisation.name
+
+
+# Contacts: CapsuleCRM::Phone (read-only)
+person.phone_numbers # CapsuleCRM::Collection
+person.phone_numbers.first.number # 01234 56789
+person.phone_numbers.first.type   # work
+
+# Contacts: CapsuleCRM::Website (read-only)
+party.websites # CapsuleCRM::Collection
+party.websites.first.url # http://google.com
+party.websites.first.web_address # http://google.com
+
+# Contacts: CapsuleCRM::Email (read-only)
+person.emails # CapsuleCRM::Collection
+person.emails.first.address # 'foo@example.com'
+person.emails.first.type    # 'home'
+
+# Contacts: CapsuleCRM::Address (read-only)
+person.addresses # CapsuleCRM::Collection
+person.addresses.first.street   # 10 Somestreet
+person.addresses.first.city     # Manchester
+person.addresses.first.state    # Greater Manchester
+person.addresses.first.zip      # ME10 7TR
+person.addresses.first.country  # United Kingdom
+
+# CapsuleCRM::CustomFields (read-only)
+person.custom_fields # CapsuleCRM::Collection
+person.custom_fields.first.label # 'Favourite colour'
+person.custom_fields.first.value # 'Blue'
+
+# CapsuleCRM::Tag (read-only)
+person.tags # CapsuleCRM::Collection
+person.tag_names # ["array", "of all", "tags", "as strings"]

data/lib/capsulecrm/address.rb

@@ -0,0 +1,23 @@
+class CapsuleCRM::Address < CapsuleCRM::Contact
+
+  attr_accessor :street
+  attr_accessor :city
+  attr_accessor :state
+  attr_accessor :zip
+  attr_accessor :country
+
+
+  # nodoc
+  def self.xml_map
+    map = {
+      'street' => 'street',
+      'city' => 'city',
+      'state' => 'state',
+      'zip' => 'zip',
+      'country' => 'country'
+    }
+    super.merge map
+  end
+
+
+end

data/lib/capsulecrm/base.rb

@@ -0,0 +1,176 @@
+module CapsuleCRM
+  class Base
+    include HTTParty
+    include ActiveModel::Dirty
+
+
+    # This is needed for PUT and POST requests because the capsule API returns html
+    # if the request is unsuccessful.  HTTParty's default xlm parser crashes if fed
+    # html so this parser is used for PUT/POST
+    class Parser::Simple < HTTParty::Parser
+      def parse; body; end
+    end
+
+
+    # -- Attributes --
+    attr_accessor :id
+    attr_accessor :raw_data
+    @@last_response = nil
+
+
+    # -- HttpParty --
+    format      :xml
+    headers     'User-Agent' => 'CapsuleCRM ruby gem'
+
+
+    # nodoc
+    def initialize(attributes={})
+      attributes.each do |name, value|
+        send("#{name}=", value)
+      end
+      changed_attributes.clear
+    end
+
+
+    # nodoc
+    def ==(other)
+      return false if other.nil?
+      id == other.id
+    end
+
+
+    # nodoc
+    def id
+      return nil if @id.nil?
+      @id.to_i
+    end
+
+
+    # nodoc
+    def errors
+      @errors ||= []
+    end
+
+
+    # nodoc
+    def new_record?
+      id.nil?
+    end
+
+
+    # -- Class Methods --
+
+    
+    # nodoc
+    def self.find(what, options={})
+      return find_all(options) if what == :all
+      find_one(what)
+    end
+
+
+    # for debugging
+    def self.last_response
+      @@last_response
+    end
+
+
+    private
+
+
+    # uses xml_map() to convert the xml hash from response.data into an attributes hash
+    def self.attributes_from_xml_hash(hash)
+      attributes = {:raw_data => hash}
+      xml_map.each { |k,v| attributes[v] = hash[k] }
+      attributes
+    end
+
+
+    # uses xml_map() to convert :attributes into an xml string
+    def self.attributes_to_xml(attributes, root=nil)
+      xml = {}
+      map = xml_map.invert
+      attributes.each do |k,v|
+        key = map[k.to_s]
+        xml[key] = v
+      end
+      xml.to_xml :root => root
+    end
+
+
+    # nodoc
+    def self.find_one(id)
+      path = get_path + '/' + id.to_s
+      @@last_response = get(path)
+      raise_404(id) if last_response.code == 404
+      init_one(last_response)
+    end
+
+
+    # nodoc
+    def self.find_all(options={}, path=nil)
+      path ||= get_path
+      params = query_params(options)
+      @@last_response = get(path, :query => params)
+      init_many(last_response)
+    end
+
+
+    # over-ride in sub-classes
+    def self.get_path
+    end
+
+
+    # capsule API uses :start.  :offset is prob more familiar to ruby/active_record users
+    def self.query_params(options)
+      params = options.dup
+      params[:start] = params.delete(:offset) if params.has_key?(:offset)
+      params
+    end
+
+
+    # nodoc
+    def self.raise_404(id)
+      err = "Could not find #{name} with id #{id}"
+      raise CapsuleCRM::RecordNotFound, err
+    end
+
+
+    # creates a new object, and returns the ID
+    # returns false if something went wrong (use last_response() to debug)
+    def self.create(attributes, options={})
+      return false if attributes.empty?
+      xml = attributes_to_xml(attributes, options.delete(:root))
+      @@last_response = post options[:path], xml_request_options(xml)
+      return false unless last_response.code == 201
+      last_response.headers['location'].split('/').last
+    end
+
+
+    # updates an object with the given id, returns true on success, false
+    # on failure.
+    def self.update(id, attributes, options={})
+      return true if attributes.empty?
+      xml = attributes_to_xml(attributes, options.delete(:root))
+      @@last_response = put options[:path], xml_request_options(xml)
+      last_response.code == 200
+    end
+
+
+    # nodoc
+    def self.xml_map
+      {'id' => 'id'}
+    end
+
+
+    # needed for PUT and POST operations
+    def self.xml_request_options(xml)
+      options = {
+        :body => xml,
+        :headers => {'Content-Type' => 'text/xml'},
+        :parser => Parser::Simple
+      }
+    end
+
+
+  end
+end

data/lib/capsulecrm/child.rb

@@ -0,0 +1,24 @@
+class CapsuleCRM::Child < CapsuleCRM::Base
+  attr_accessor :parent
+
+
+  # nodoc
+  def initialize(parent, attributes={})
+    @parent = parent
+    super(attributes)
+  end
+
+
+  # nodoc
+  def self.init_many(parent, data)
+    CapsuleCRM::ChildCollection.new(parent, self, data)
+  end
+
+
+  # nodoc
+  def self.init_one(parent, data)
+    new(parent, attributes_from_xml_map(data))
+  end
+
+
+end

data/lib/capsulecrm/child_collection.rb

@@ -0,0 +1,14 @@
+class CapsuleCRM::ChildCollection < CapsuleCRM::Collection
+
+
+  # nodoc
+  def initialize(parent, klass, data)
+    return if data.nil?
+    [data].flatten.each do |attributes|
+      attributes = klass.attributes_from_xml_hash(attributes)
+      self.push klass.new(parent, attributes)
+    end
+  end
+
+
+end

data/lib/capsulecrm/collection.rb

@@ -0,0 +1,14 @@
+class CapsuleCRM::Collection < Array
+
+
+  # nodoc
+  def initialize(klass, data)
+    return if data.nil?
+    [data].flatten.each do |attributes|
+      attributes = klass.attributes_from_xml_hash(attributes)
+      self.push klass.new(attributes)
+    end
+  end
+
+
+end

data/lib/capsulecrm/contact.rb

@@ -0,0 +1,27 @@
+class CapsuleCRM::Contact < CapsuleCRM::Child
+
+  attr_accessor :type
+  define_attribute_methods [:type]
+
+  # nodoc
+  def attributes
+    attrs = {}
+    arr = [:type]
+    arr.each do |key|
+      attrs[key] = self.send(key)
+    end
+    attrs
+  end
+  
+  # nodoc
+  def type=(value)
+    type_will_change! unless value == type
+    @type = value
+  end
+  
+  # nodoc
+  def self.xml_map
+    map = {'type' => 'type'}
+    super.merge map
+  end
+end

data/lib/capsulecrm/custom_field.rb

@@ -0,0 +1,41 @@
+class CapsuleCRM::CustomField < CapsuleCRM::Child
+
+  attr_accessor :boolean
+  attr_accessor :date
+  attr_accessor :label
+  attr_accessor :text
+
+
+  # nodoc
+  def boolean=(value)
+    return @boolean = true if value.to_s == 'true'
+    @boolean = false
+  end
+
+
+  # nodoc
+  def date=(value)
+    value = Time.parse(value) if value.is_a?(String)
+    @date = value
+  end
+
+
+  # nodoc
+  def value
+    date || text || boolean
+  end
+
+
+  # nodoc
+  def self.xml_map
+    map = {
+      'label' => 'label',
+      'text' => 'text',
+      'date' => 'date',
+      'boolean' => 'boolean'
+    }
+    super.merge map
+  end
+
+
+end

data/lib/capsulecrm/email.rb

@@ -0,0 +1,64 @@
+class CapsuleCRM::Email < CapsuleCRM::Contact
+
+  attr_accessor :address
+  define_attribute_methods [:address]
+
+
+  # nodoc
+  def attributes
+    attrs = {}
+    arr = [:address, :type]
+    arr.each do |key|
+      attrs[key] = self.send(key)
+    end
+    attrs
+  end
+  
+  # nodoc
+  def address=(value)
+    address_will_change! unless value == address
+    @address = value
+  end
+  
+  # nodoc
+  def dirty_attributes
+    Hash[attributes.select { |k,v| changed.include? k.to_s }]
+  end
+  
+  def parent_type
+    return "person" if self.parent.class == CapsuleCRM::Person
+    return "organisation" if self.parent.class == CapsuleCRM::Organisation
+    raise "Unknown Parent Type"
+  end
+  
+  # nodoc
+  def save
+    path = ["", "api", parent_type, self.parent.id].join("/")
+    options = {:root => 'person', :path => path}
+    attrs = new_record?? attributes : {:id => id}.merge(dirty_attributes)
+    success = self.class.update id, attrs, options
+    changed_attributes.clear if success
+    success   
+  end
+  
+  # uses xml_map() to convert :attributes into an xml string
+  def self.attributes_to_xml(attributes, root=nil)
+    xml = {"contacts" => {"email" => {}}}
+    map = xml_map.invert
+    attributes.each do |k,v|
+      key = map[k.to_s]
+      xml["contacts"]["email"][key] = v
+    end
+    xml.to_xml :root => root
+  end
+  
+  # nodoc
+  def self.xml_map
+    map = {
+      'emailAddress' => 'address'
+    }
+    super.merge map
+  end
+
+
+end

data/lib/capsulecrm/history.rb

@@ -0,0 +1,32 @@
+module CapsuleCRM::History
+  # Reload history
+  def history!
+    @history = nil
+    history
+  end 
+
+  # Load history if not loaded
+  def history
+    return @history if @history
+
+    path = self.class.get_path
+    path = [path, id, 'history'].join '/'
+    last_response = self.class.get(path)
+    data = last_response['history'].try(:[], 'historyItem')
+    @history = CapsuleCRM::HistoryItem.init_many(self, data)
+  end
+
+  
+  def add_history(note)
+    if note
+      path = [self.class.get_path, self.id, 'history'].join '/'
+      self.class.create(Hash[{:note => note}], {:root => 'historyItem', :path => path})
+      
+      # TODO : Should be optimized so it doesn't reload history each time
+      @history = nil
+    end
+  end
+  
+  alias :add_note :add_history
+end
+

data/lib/capsulecrm/history_item.rb

@@ -0,0 +1,20 @@
+class CapsuleCRM::HistoryItem < CapsuleCRM::Child
+  attr_reader :id
+  attr_accessor :type
+  attr_accessor :entry_date
+  attr_accessor :creator
+  attr_accessor :subject
+  attr_accessor :note
+    
+  def self.xml_map
+    map = {
+      "id" => 'id',
+      "type" => 'type',
+      "entryDate" => 'entry_date',
+      "creator" => 'creator',
+      "subject" => 'subject',
+      "note" => 'note'
+    }
+    super.merge map
+  end
+end

data/lib/capsulecrm/opportunity.rb

@@ -0,0 +1,60 @@
+class CapsuleCRM::Opportunity < CapsuleCRM::Base
+
+  attr_accessor :name
+  attr_accessor :party_id
+  attr_accessor :currency
+  attr_accessor :value
+  attr_accessor :duration_basis
+  attr_accessor :duration
+  attr_accessor :expected_close_date
+  attr_accessor :actual_close_date
+  attr_accessor :milestone
+  attr_accessor :updated_on
+  attr_accessor :created_on  
+
+  # nodoc
+  def self.xml_map
+    map = {
+      'name' => 'name',
+      'partyId' => 'party_id',
+      'currency' => 'currency',
+      'value' => 'value',
+      'durationBasis' => 'duration_basis',
+      'expectedCloseDate' => 'expected_close_date',
+      'actualCloseDate' => 'actual_close_date',
+      'milestone' => 'milestone',
+      'updatedOn' => 'updated_on',
+      'createdOn' => 'created_on',
+    }
+    super.merge map
+  end
+
+  def all
+    return @opportunities if @opportunities
+    path = self.class.get_path
+    last_response = self.class.get(path)
+    @opportunities = CapsuleCRM::Opportunity.init_many(last_response)
+  end
+  
+  # nodoc
+  def self.get_path
+    '/api/opportunity'
+  end
+
+
+  # nodoc
+  def self.init_many(response)
+    data = response['opportunities']['opportunity']
+    CapsuleCRM::Collection.new(self, data)
+  end
+
+
+  # nodoc
+  def self.init_one(response)
+    data = response['opportunity']
+    new(attributes_from_xml_hash(data))
+  end
+
+
+
+end