capsulecrmii 0.0.5

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        = "capsulecrmii"
+  s.version     = CapsuleCRM::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Ahmed Adam", "dsimard"]
+  s.email       = ["ahmed.msgs@gmail.com", "dsimard@azanka.ca"]
+  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.
+
+
+# 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.rb

@@ -0,0 +1,45 @@
+require 'active_support/core_ext/module/attribute_accessors'
+require 'active_support/core_ext/hash'
+require 'active_support'
+require 'active_model'
+require 'httparty'
+require 'uri'
+module CapsuleCRM
+
+  mattr_accessor :account_name
+  mattr_accessor :api_token
+
+  # nodoc
+  def self.base_uri(account_name)
+    "https://#{account_name}.capsulecrm.com"
+  end
+
+
+  # nodoc
+  def self.initialize!
+    raise ArgumentError, "CapsuleCRM.account_name not defined" if account_name.nil?
+    raise ArgumentError, "CapsuleCRM.api_token not defined" if api_token.nil?
+    CapsuleCRM::Base.base_uri base_uri(account_name)
+    CapsuleCRM::Base.basic_auth api_token, 'x'
+  end
+
+
+end
+
+require 'capsulecrm/record_not_found'
+require 'capsulecrm/base'
+require 'capsulecrm/history'
+require 'capsulecrm/party'
+require 'capsulecrm/person'
+require 'capsulecrm/organisation'
+require 'capsulecrm/collection'
+require 'capsulecrm/child_collection'
+require 'capsulecrm/child'
+require 'capsulecrm/custom_field'
+require 'capsulecrm/contact'
+require 'capsulecrm/email'
+require 'capsulecrm/phone'
+require 'capsulecrm/address'
+require 'capsulecrm/tag'
+require 'capsulecrm/history_item'
+require 'capsulecrm/website'

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