pipejump 0.2.0

data/lib/pipejump/base/session.rb

@@ -0,0 +1,172 @@
+module Pipejump
+  
+  # The Pipejump::Session instance represents an active Session with the Pipejump API
+  # 
+  # Any access to the Pipejump API requires authentication, which means you need to initialize a 
+  # Pipejump::Session instance before calling any other methods
+  # 
+  # == Authentication
+  # 
+  # To authenticate, simply call Pipejump::Session.new with a argument hash with the following keys:
+  # 
+  # * _email_ - your Pipejump user account email
+  # * _password_ - your Pipejump user account password
+  # * _endpoint_ - (optional) Default is http://api.pipejump.com, however you can override it (for example for development)
+  # 
+  # You can perform later actions either on a instance returned by the canstructor or within a supplied block
+  # 
+  # 
+  #     @session = Pipejump::Session.new(:email => EMAIL, :password => PASSWORD)
+  #     @session.account
+  # 
+  # 
+  # or 
+  # 
+  # 
+  #     Pipejump::Session.new(:email => EMAIL, :password => PASSWORD) do |session|
+  #       session.account
+  #     end
+  #
+  # As of version 0.1.1 you can use the token which is fetched when authenticating using the email and password. So once you get the token, you can use it for future initialization of the Session and not send the username and password, which is a more secure.
+  # 
+  #   @session = Pipejump::Session.new(:token => 'your_token')
+  # 
+  # Also, as of version 0.1.1 connection is performed over SSL.
+  # 
+  # 
+  # 
+  # 
+  # == Account
+  # 
+  # To access the Account instance, call the account method
+  # 
+  # 
+  #      @session.account # => #<Pipejump::Account name: "myaccount", id: "1", currency_name: "$">
+  # 
+  # 
+  # == Deals
+  # 
+  # You can access your deals by calling 
+  # 
+  # 
+  #      @session.deals
+  # 
+  # 
+  # With Deals you get access to Notes, Reminders and Deal Contacts.
+  # 
+  # For more information, consult the Deals page.
+  # 
+  # == Clients
+  # 
+  # You can access your clients by calling 
+  # 
+  # 
+  #      @session.clients
+  # 
+  # 
+  # For more information, consult the Clients page.
+  # 
+  # == Contacts
+  # 
+  # You can access your contacts by calling 
+  # 
+  # 
+  #      @session.contacts
+  # 
+  # 
+  # For more information, consult the Contacts page.
+  # 
+  # == Sources
+  # 
+  # You can access your sources by calling 
+  # 
+  # 
+  #      @session.sources
+  # 
+  # 
+  # For more information, consult the Sources page.
+  # 
+  class Session
+    
+    attr_accessor :token
+    
+    def initialize(params, &block) 
+      if endpoint = params.delete("endpoint") or endpoint = params.delete(:endpoint)
+        connection(endpoint)
+      end
+      # If user supplies token, do not connect for authentication
+      if token = params.delete('token') or token = params.delete(:token)
+        self.token = token
+      else
+        authenticate(params)
+      end
+      yield(self) if block_given?
+    end
+    
+    def authenticate(params) #:nodoc:
+      response = connection.post('/authentication', params.collect { |pair| pair.join('=') }.join('&'))
+      data = JSON.parse(response.body)
+      self.token = data['authentication']['token']
+      raise AuthenticationFailed if response.code == '401'
+    end
+    
+    def connection(endpoint = nil) #:nodoc:
+      @connection ||= Connection.new(self, endpoint)
+    end
+        
+    def get(url) #:nodoc:
+      response = connection.get(url)
+      data = (response.code.to_i == 200 and url.match('.json')) ? JSON.parse(response.body) : ''
+      [response.code.to_i, data]
+    end
+
+    def post(url, data) #:nodoc:
+      response = connection.post(url, data)
+      data = url.match('.json') ? JSON.parse(response.body) : response.body
+      [response.code.to_i, data]
+    end
+
+    def put(url, data) #:nodoc:
+      response = connection.put(url, data)
+      data = url.match('.json') ? JSON.parse(response.body) : response.body
+      [response.code.to_i, data]
+    end
+    
+    def delete(url) #:nodoc:
+      response = connection.delete(url)
+      [response.code.to_i, response.body]
+    end
+    
+    def inspect
+      "#<#{self.class} token: \"#{token}\">"
+    end
+    
+    # Returns a Pipejump::Account instance of the current account
+    def account
+      code, response = get('/account.json')
+      Account.new(response['account'])
+    end
+    
+    # Returns a Pipejump::Collection instance of Clients
+    def clients
+      Collection.new(self, Client)
+    end
+
+    # Returns a Pipejump::Collection instance of Sources
+    def sources
+      Collection.new(self, Source)
+    end
+
+    # Returns a Pipejump::Collection instance of Contacts
+    def contacts
+      Collection.new(self, Contact)
+    end
+
+    # Returns a Pipejump::Collection instance of Deals
+    def deals
+      Collection.new(self, Deal)
+    end
+
+    
+  end
+end

data/lib/pipejump/resources/account.rb

@@ -0,0 +1,20 @@
+module Pipejump
+  
+  # The Account resource is represented by an instance of Pipejump::Account, which holds information about your account, such as:
+  # 
+  # * id
+  # * name
+  # * currency
+  # 
+  # *Note*: To access any resources, you need a valid [[Session]] instance, referred to as @session in the following examples.
+  # 
+  # == Access
+  # 
+  # To access an instance of Pipejump::Account, call 
+  # 
+  #   @session.account
+  # 
+  class Account < Resource 
+  end
+  
+end

data/lib/pipejump/resources/client.rb

@@ -0,0 +1,162 @@
+module Pipejump
+  
+
+  # The Client resource is represented by an instance of Pipejump::Client.
+  # 
+  # *Note*: To access any resources, you need a valid Session instance, referred to as @session in the following examples.
+  # 
+  # == Access
+  # 
+  # === Collection
+  # 
+  # To fetch a collection of Pipejump::Client instances, call
+  # 
+  # 
+  #      @session.clients 
+  #      # => #<Pipejump::Collection resource: Pipejump::Client>
+  # 
+  # 
+  # This returns a Pipejump::Collection instance. To retrieve an array of Pipejump::Client instances, call the _all_ method on the collection:
+  # 
+  # 
+  #      @session.clients.all 
+  #      # => [#<Pipejump::Client name: "My Client", id: "1">, #<Pipejump::Client name: "Another Client", id: "2">]
+  # 
+  # 
+  # Instead of _all_, you can also call a variety of Array methods in the collection which will be delegated to the array returned by _all_, such as:
+  # 
+  # * first
+  # * last
+  # * each
+  # * size
+  # * collect
+  # * reject
+  # 
+  # *Examples*:
+  # 
+  #      @session.clients.first 
+  #      # => #<Pipejump::Client name: "My Client", id: "1">
+  #      @session.clients.last 
+  #      # => #<Pipejump::Client name: "Another Client", id: "2">
+  #      @session.clients.size
+  #      # => 2
+  #      @session.clients.each { |client| puts client.name } 
+  #      # Prints out "My Client" and "Another Client"
+  #      @session.clients.collect { |client| client.name } 
+  #      # => ["My Client",  "Another Client"]
+  #      @session.clients.reject { |client| client.name == 'My Client' } 
+  #      # => ["My Client",  "Another Client"]
+  # 
+  # 
+  # === Resource
+  # 
+  # To fetch a single resource, call the _find_ method with the resource id as an argument:
+  # 
+  # 
+  #      @session.clients.find(1) 
+  #      # => #<Pipejump::Client name: "My Client", id: "1">
+  # 
+  # 
+  # == Creation
+  # 
+  # *Note*: Clients require the following fields in the hash of attributes:
+  # 
+  # * _name_: a valid name
+  # 
+  # To create a new client, call the _create_ method on the Client Pipejump::Collection with a hash of attributes as an argument:
+  # 
+  # 
+  #      @session.clients.create(:name => 'Third Client') 
+  #      # => #<Pipejump::Client name: "Third Client", id: "3">
+  # 
+  # 
+  # If the resource was created properly, it will be returned with a id assigned to it. You can check it by calling the created? method
+  # 
+  # 
+  #      client = @session.clients.create(:name => 'Third Client') 
+  #      # => #<Pipejump::Client name: "Third Client", id: "3">
+  #      client.created? 
+  #      # => true
+  #      client = @session.clients.create(:name => '') 
+  #      # => #<Pipejump::Client name: "">
+  #      client.created? 
+  #      # => false
+  # 
+  # 
+  # You can access validation/creation errors by calling the _errors_ method on the instance returned by _create_:
+  # 
+  # 
+  #      client = @session.clients.create(:name => '') 
+  #      # => #<Pipejump::Client name: "">
+  #      client.created? 
+  #      # => false
+  #      client.errors 
+  #      # => {"client"=>[{"error"=>{"code"=>"E0001", "field"=>"name", "description"=>"can't be blank"}}]}
+  # 
+  # 
+  # == Update
+  # 
+  # To update a resource, change the attributes and call the _save_ method.
+  # 
+  # === Changing attributes
+  # 
+  # Each attribute has an accessor which you can use to change the values:
+  # 
+  # 
+  #      client = @session.clients.create(:name => 'Third Client') 
+  #      # => #<Pipejump::Client name: "Third Client", id: "3">
+  #      client.name 
+  #      # => 'Third Client'
+  #      client.name = 'Super Client' 
+  #      # => 'Super Client'
+  #      client.name 
+  #      # => 'Super Client'
+  # 
+  # 
+  # === Saving
+  # 
+  # Once you've changed the attributes, call the _save_ method on the resource instance:
+  # 
+  # 
+  #      client = @session.clients.create(:name => 'Third Client') 
+  #      # => #<Pipejump::Client name: "Third Client", id: "3">
+  #      client.name 
+  #      # => 'Third Client'
+  #      client.save
+  #      # => true
+  # 
+  # 
+  # _save_ returns _true_ if save was successful and _false_ if it failed. In the latter scenario, you can access the errors via the _errors_ method:
+  # 
+  # 
+  #      client = @session.clients.create(:name => 'Third Client') 
+  #      # => #<Pipejump::Client name: "Third Client", id: "3">
+  #      client.name = 'Super Client'
+  #      # => 'Super Client'
+  #      client.save 
+  #      # => true
+  #      client.name = '' 
+  #      # => ''
+  #      client.save 
+  #      # => false
+  #      client.errors 
+  #      # => {"client"=>[{"error"=>{"code"=>"E0001", "field"=>"name", "description"=>"can't be blank"}}]}
+  # 
+  # 
+  # == Removal
+  # 
+  # To remove a resource, call the _destroy_ method on the instance:
+  # 
+  # 
+  #      client = @session.clients.find(1) 
+  #      #  => #<Pipejump::Client name: "My Client", id: "1">
+  #      client.destroy 
+  #      # => true
+  # 
+  class Client < Resource 
+    has_many :contacts do
+      disable :create
+    end
+  end
+  
+end

data/lib/pipejump/resources/contact.rb

@@ -0,0 +1,225 @@
+module Pipejump
+  
+  # A Contact is represented by an instance of Pipejump::Contact.
+  # 
+  # *Note*: To access any contacts, you need a valid Session instance, referred to as @session in the following examples.
+  # 
+  # == Access
+  # 
+  # === Collection
+  # 
+  # To fetch a collection of Pipejump::Contact instances, call
+  # 
+  # 
+  #      @session.contacts 
+  #      # => #<Pipejump::Collection recontact: Pipejump::Contact>
+  # 
+  # 
+  # This returns a Pipejump::Collection instance. To retrieve an array of Pipejump::Contact instances, call the _all_ method on the collection:
+  # 
+  # 
+  #      @session.contacts.all 
+  #      # => [#<Pipejump::Contact name: "Tom", id: "1", mobile: "123", phone: "456", email: "tom@email.com">, #<Pipejump::Contact name: "Mike", id: "2", mobile: "321", phone: "654", email: "mike@email.com">]
+  # 
+  # 
+  # Instead of _all_, you can also call a variety of Array methods in the collection which will be delegated to the array returned by _all_, such as:
+  # 
+  # * first
+  # * last
+  # * each
+  # * size
+  # * collect
+  # * reject
+  # 
+  # *Examples*:
+  # 
+  #      @session.contacts.first 
+  #      # => #<Pipejump::Contact name: "Tom", id: "1", mobile: "123", phone: "456", email: "tom@email.com">
+  #      @session.contacts.last 
+  #      # => #<Pipejump::Contact name: "Mike", id: "2", mobile: "321", phone: "654", email: "mike@email.com">
+  #      @session.contacts.size
+  #      # => 2
+  #      @session.contacts.each { |contact| puts contact.name } 
+  #      # Prints out "Tom" and "Mike"
+  #      @session.contacts.collect { |contact| contact.name } 
+  #      # => ["Tom",  "Mike"]
+  #      @session.contacts.reject { |contact| contact.name == 'Tom' } 
+  #      # => ["Mike"]
+  # 
+  # 
+  # === Resource
+  # 
+  # To fetch a single contact, call the _find_ method with the contact id as an argument:
+  # 
+  # 
+  #      @session.contacts.find(1) 
+  #      # => #<Pipejump::Contact name: "Tom", id: "1", mobile: "123", phone: "456", email: "tom@email.com">
+  # 
+  # 
+  # == Creation
+  # 
+  # *Note*: Contacts require the following fields in the hash of attributes:
+  # 
+  # * _name_: a valid name
+  # * _client_id_: a valid a Client| id 
+  # 
+  # To create a new contact, call the _create_ method on the Contact Pipejump::Collection with a hash of attributes as an argument. 
+  # 
+  # 
+  #      @session.contacts.create(:name => 'Jerry', :client_id => 1) 
+  #      # => #<Pipejump::Contact name: "Jerry", id: "3", mobile: "", client_id: "1", phone: "", email: "">
+  # 
+  # 
+  # If the contact was created properly, it will be returned with a id assigned to it. You can check it by calling the created? method
+  # 
+  # 
+  #      contact = @session.contacts.create(:name => 'Jerry', :client_id => 1) 
+  #      # => #<Pipejump::Contact name: "Jerry", id: "3", mobile: "", client_id: "1", phone: "", email: "">
+  #      contact.created? 
+  #      # => true
+  #      contact = @session.contacts.create(:name => '') 
+  #      # => #<Pipejump::Contact name: "">
+  #      contact.created? 
+  #      # => false
+  # 
+  # 
+  # You can access validation/creation errors by calling the _errors_ method on the instance returned by _create_:
+  # 
+  # 
+  #      contact = @session.contacts.create(:name => '') 
+  #      # => #<Pipejump::Contact name: "">
+  #      contact.created? 
+  #      # => false
+  #      contact.errors 
+  #      # => "contact"=>[{"error"=>{"code"=>"E0001", "field"=>"name", "description"=>"Well... we need a name."}}, {"error"=>{"code"=>"E0001", "field"=>"client", "description"=>"can't be blank"}}]}
+  # 
+  # 
+  # == Update
+  # 
+  # To update a contact, change the attributes and call the _save_ method.
+  # 
+  # === Changing attributes
+  # 
+  # Each attribute has an accessor which you can use to change the values:
+  # 
+  # 
+  #      contact = @session.contacts.create(:name => 'Jerry', :client_id => 1) 
+  #      # => #<Pipejump::Contact name: "Jerry", id: "3", mobile: "", client_id: "1", phone: "", email: "">
+  #      contact.name 
+  #      # => 'Jerry'
+  #      contact.name = 'Wally' 
+  #      # => 'Wally'
+  #      contact.name 
+  #      # => 'Wally'
+  # 
+  # 
+  # === Saving
+  # 
+  # Once you've changed the attributes, call the _save_ method on the contact instance:
+  # 
+  # 
+  #      contact = @session.contacts.create(:name => 'Jerry', :client_id => 1) 
+  #      # => #<Pipejump::Contact name: "Jerry", id: "3", mobile: "", client_id: "1", phone: "", email: "">
+  #      contact.name = 'Wally' 
+  #      # => 'Wally'
+  #      contact.save
+  #      # => true
+  # 
+  # 
+  # _save_ returns _true_ if save was successful and _false_ if it failed. In the latter scenario, you can access the errors via the _errors_ method:
+  # 
+  # 
+  #      contact = @session.contacts.create(:name => 'Jerry', :client_id => 1) 
+  #      # => #<Pipejump::Contact name: "Jerry", id: "3", mobile: "", client_id: "1", phone: "", email: "">
+  #      contact.name = 'Wally'
+  #      # => 'Wally'
+  #      contact.save 
+  #      # => true
+  #      contact.name = '' 
+  #      # => ''
+  #      contact.save 
+  #      # => false
+  #      contact.errors 
+  #      # => "contact"=>[{"error"=>{"code"=>"E0001", "field"=>"name", "description"=>"Well... we need a name."}}, {"error"=>{"code"=>"E0001", "field"=>"client", "description"=>"can't be blank"}}]}
+  # 
+  # 
+  # == Removal
+  # 
+  # To remove a contact, call the _destroy_ method on the instance:
+  # 
+  # 
+  #      contact = @session.contacts.find(1) 
+  #      #  => #<Pipejump::Contact name: "Tom", id: "1", mobile: "123", phone: "456", email: "tom@email.com">
+  #      contact.destroy 
+  #      # => true
+  # 
+  #
+  # = Contacts within a Deal
+  # 
+  # A Contact is represented by an instance of Pipejump::Contact. Deal Contacts, however, can only be accessed from a specific deal.
+  #
+  # *Note*: To access any Deal Contacts, you need a valid Deal| instance, referred to as @deal in the following examples. Deal Contacts belong to a deal, so you can only access them via @deal, not the session.
+  # 
+  # == Access
+  # 
+  # === Collection
+  # 
+  # To fetch a collection of Pipejump::Contact instances belonging to a specific Deal, call
+  # 
+  # 
+  #      @deal.contacts 
+  #      # => #<Pipejump::Collection resource: Pipejump::Contact, owner: #<Pipejump::Deal name: "My Deal", scope: "0", hot: "false", stage_name: "incoming", id: "1", deal_tags: "">>
+  # 
+  # 
+  # This returns a Pipejump::Collection instance. To retrieve an array of Pipejump::Contact instances belonging to a specific Deal, call the _all_ method on the collection:
+  # 
+  # 
+  #      @deal.contacts.all 
+  #      # => [#<Pipejump::Contact name: "Tom", id: "1", mobile: "123", phone: "456", email: "tom@email.com">, 
+  #      #     #<Pipejump::Contact name: "Mike", id: "2", mobile: "321", phone: "654", email: "mike@email.com">]
+  # 
+  # 
+  # Instead of _all_, you can also call a variety of Array methods in the collection which will be delegated to the array returned by _all_, such as:
+  # 
+  # * first
+  # * last
+  # * each
+  # * size
+  # * collect
+  # * reject
+  # 
+  # *Examples*:
+  # 
+  #      @deal.contacts.first 
+  #      # => #<Pipejump::Contact name: "Tom", id: "1", mobile: "123", phone: "456", email: "tom@email.com">
+  #      @deal.contacts.last 
+  #      # => #<Pipejump::Contact name: "Mike", id: "2", mobile: "321", phone: "654", email: "mike@email.com">
+  #      @deal.contacts.size
+  #      # => 2
+  #      @deal.contacts.each { |contact| puts contact.name } 
+  #      # Prints out "Tom" and "Mike"
+  #      @deal.contacts.collect { |contact| contact.name } 
+  #      # => ["Tom",  "Mike"]
+  #      @deal.contacts.reject { |contact| contact.name == 'Tom' } 
+  #      # => ["Mike"]
+  # 
+  # 
+  # == Updating
+  # 
+  # To update the Contacts that are assigned to a Deal|, call the _update_ method on the Contacts collection:
+  # 
+  # 
+  #      @deal.contacts.collect(&:id)
+  #      # => ['1', '2', '3']
+  #      @deal.contacts.update('1,2')
+  #      # => true
+  #      @deal.contacts.collect(&:id)
+  #      # => ['1', '2']
+  # 
+  # 
+  # *Note*: The Contacts must have the same Client as the Deal or update will return _false_
+  class Contact < Resource
+    belongs_to :client
+  end
+  
+end