basecrm 0.1.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 40387841cc49a997c9ab264764fc79a56190881b
-  data.tar.gz: e94fe87215b3f1302a80e87efbf6dee442989d8c
+  metadata.gz: 8112801481b6cff60fccc01b1218206447b30b35
+  data.tar.gz: b30ccfcdbfe04ea0a5b518c83e77d3d9c4631827
 SHA512:
-  metadata.gz: 0eea26c5f63be7a738f7c12992c57695afb6031c34b9d4f4a7c8c309d6165cc15c26dfd7ab342543af18b083d7ba45a4a524b55b98d9292315a1133c841faa6d
-  data.tar.gz: a0226695b2900d2d6ebc99e1a13d4e20f4189ed54be031571afd3c0e1a3c029f5f560b3de7a8b0c985448421b75c56e4a78df4d46c323b72e3982c61b88e38ef
+  metadata.gz: 492f991f87a6d464938ba7f1ab986571283103afa40a3fc6ee6e9a4d0475c7783a172193d09df6e9ad7f87c6c428a95103a08947d333247422749c5974a4305f
+  data.tar.gz: aaba445b34861708afebec9697d8eab35160f55b2ffe2f0ac34086ca682858e4c7ee1cb685cc8a9b46fe37a5ae0c397753c55d5dd85a93d07aa7fef0b921da7a

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Marcin Bunsch
+Copyright (c) 2015 BaseCRM developers
 
 MIT License
 
@@ -19,4 +19,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,18 +1,18 @@
-# Base CRM API client
+# basecrm-ruby
 
-[![Build Status](https://travis-ci.org/basecrm/basecrm.png?branch=master)](https://travis-ci.org/basecrm/basecrm)
-
-New and shiny client for the Base CRM API
+BaseCRM Official API V2 library client for ruby
 
 ## Installation
 
-The gem available via Rubygems. To install it, use the following command:
+Make sure you have [rubygems](https://rubygems.org) installed.
+
+The gem is available via Rubygems. To install, use the following command:
 
 ```ruby
 sudo gem install basecrm
 ```
 
-If you use Bundler, put this in your Gemfile:
+If you use Bundler, put the line below in your Gemfile:
 
 ```ruby
 gem 'basecrm'
@@ -21,25 +21,281 @@ gem 'basecrm'
 To get the latest version, put this in your Gemfile:
 
 ```ruby
-gem 'basecrm', :git => 'git://github.com/basecrm/basecrm.git'
+gem 'basecrm', :git => 'git://github.com/basecrm/basecrm-ruby.git'
 ```
 
 ## Usage
 
-Before using this gem you must require it by calling:
+```ruby
+require "basecrm"
+
+# Then we instantiate a client (as shown below)
+```
+
+### Build a client
+__Using this api without authentication gives an error__
 
 ```ruby
-require 'basecrm'
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 ```
 
-## Usage
+### Client Options
+
+The following options are available while instantiating a client:
+
+ * __access_token__: Personal access token
+ * __base_url__: Base url for the api
+ * __user_agent__: Default user-agent for all requests
+ * __timeout__: Request timeout
+ * __verbose__: Verbose/debug mode
+ * __logger__: Logger used in verbose mode
+
+### Architecture
+
+The library follows few architectural principles you should understand before digging deeper.
+1. Interactions with resources are done via service objects.
+2. Service objects are exposed as methods on client instances.
+3. Service objects expose resource-oriented actions.
+4. Actions return Plain Old Ruby Objects.
+
+For example, to interact with deals API you will use `DealsService`, which you can get if you call:
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
+client.deals # => BaseCRM::DealsService
+```
+
+When you want to fetch **all** resources you will use `#all` method which returns paginated resource (which implements Enumerable):
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
+client.deals.all.map { |deal| deal.name } # => Array<String>
+```
+
+To retrieve list of resources and use filtering you will call `#where` method:
+
+```ruby
+client = BaseCRM::Client.new(accss_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
+client.deals.where(organization_id: google.id, hot: true) # => Array<BaseCRM::Deal>
+```
+
+To find a resource by it's unique identifier use `#find` method:
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
+client.deals.find(id) # => BaseCRM::Deal
+```
+
+When you'd like to create a resource, or update it's attributes you want to use either `#create` or `#update` methods. Both of them can take either Hash or a model class e.g. Deal instance. For example if you want to create a new deal you will call:
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
+coffeeshop = client.contacts.where(name: "Coffee Shop")
+
+deal = client.deals.create(name: "Website redesign", contact_id: coffeeshop.id)
+deal.value = 1000
+deal.currency = "USD"
+
+client.deals.update(deal) # => BaseCRM::Deal
+```
+
+To destroy a resource use `#destroy` method:
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOU_PERSONAL_ACCESS_TOKEN>")
+client.deals.destroy(id) # => true
+```
+
+There other non-CRUD operations supported as well. Please contact corresponding service files for in-depth documentation.
+
+### Full example
+
+Create a new organization and after that change it's attributes (website).
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
+lead = client.leads.create(organization_name: "Design service company")
+
+lead.website = "http://www.designservices.com"
+client.leads.update(lead)
+```
+
+## Resources and actions
+
+Documentation for every action can be found in corresponding service files under `lib/basecrm/services` directory.
+
+### Account
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.accounts # => BaseCRM::AccountsService
+```
+
+Actions:
+* Retrieve account details - `client.accounts.self`
+
+### AssociatedContact
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.associated_contacts # => BaseCRM::AssociatedContactsService
+```
+
+Actions:
+* Retrieve deal's associated contacts - `client.associated_contacts.all`
+* Create an associated contact - `client.associated_contacts.create`
+* Remove an associated contact - `client.associated_contacts.destroy`
+
+### Contact
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.contacts # => BaseCRM::ContactsService
+```
+
+Actions:
+* Retrieve all contacts - `client.contacts.all`
+* Create a contact - `client.contacts.create`
+* Retrieve a single contact - `client.contacts.find`
+* Update a contact - `client.contacts.update`
+* Delete a contact - `client.contacts.destroy`
+
+### Deal
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.deals # => BaseCRM::DealsService
+```
+
+Actions:
+* Retrieve all deals - `client.deals.all`
+* Create a deal - `client.deals.create`
+* Retrieve a single deal - `client.deals.find`
+* Update a deal - `client.deals.update`
+* Delete a deal - `client.deals.destroy`
+
+### Lead
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.leads # => BaseCRM::LeadsService
+```
+
+Actions:
+* Retrieve all leads - `client.leads.all`
+* Create a lead - `client.leads.create`
+* Retrieve a single lead - `client.leads.find`
+* Update a lead - `client.leads.update`
+* Delete a lead - `client.leads.destroy`
+
+### LossReason
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.loss_reasons # => BaseCRM::LossReasonsService
+```
+
+Actions:
+* Retrieve all reasons - `client.loss_reasons.all`
+* Create a loss reason - `client.loss_reasons.create`
+* Retrieve a single reason - `client.loss_reasons.find`
+* Update a loss reason - `client.loss_reasons.update`
+* Delete a reason - `client.loss_reasons.destroy`
+
+### Note
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.notes # => BaseCRM::NotesService
+```
+
+Actions:
+* Retrieve all notes - `client.notes.all`
+* Create a note - `client.notes.create`
+* Retrieve a single note - `client.notes.find`
+* Update a note - `client.notes.update`
+* Delete a note - `client.notes.destroy`
+
+### Pipeline
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.pipelines # => BaseCRM::PipelinesService
+```
+
+Actions:
+* Retrieve all pipelines - `client.pipelines.all`
+
+### Source
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.sources # => BaseCRM::SourcesService
+```
+
+Actions:
+* Retrieve all sources - `client.sources.all`
+* Create a source - `client.sources.create`
+* Retrieve a single source - `client.sources.find`
+* Update a source - `client.sources.update`
+* Delete a source - `client.sources.destroy`
+
+### Stage
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.stages # => BaseCRM::StagesService
+```
+
+Actions:
+* Retrieve all stages - `client.stages.all`
+
+### Tag
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.tags # => BaseCRM::TagsService
+```
+
+Actions:
+* Retrieve all tags - `client.tags.all`
+* Create a tag - `client.tags.create`
+* Retrieve a single tag - `client.tags.find`
+* Update a tag - `client.tags.update`
+* Delete a tag - `client.tags.destroy`
+
+### Task
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.tasks # => BaseCRM::TasksService
+```
+
+Actions:
+* Retrieve all tasks - `client.tasks.all`
+* Create a task - `client.tasks.create`
+* Retrieve a single task - `client.tasks.find`
+* Update a task - `client.tasks.update`
+* Delete a task - `client.tasks.destroy`
+
+### User
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client.users # => BaseCRM::UsersService
+```
+
+Actions:
+* Retrieve all users - `client.users.all`
+* Retrieve a single user - `client.users.find`
+* Retrieve an authenticating user - `client.users.self`
+
 
-TODO: Write usage instructions here
+## License
+MIT
 
-## Contributing
+## Bug Reports
+Report [here](https://github.com/basecrm/basecrm-ruby/issues).
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+## Contact
+BaseCRM developers (developers@getbase.com)

data/lib/basecrm.rb

@@ -1,2 +1,186 @@
-require "base_crm"
+require 'json'
+require 'faraday'
 
+require 'basecrm/version'
+require 'basecrm/errors'
+require 'basecrm/envelope'
+require 'basecrm/configuration'
+require 'basecrm/http_client'
+
+require 'basecrm/model'
+require 'basecrm/models/account'
+require 'basecrm/models/address'
+require 'basecrm/models/associated_contact'
+require 'basecrm/models/contact'
+require 'basecrm/models/deal'
+require 'basecrm/models/lead'
+require 'basecrm/models/loss_reason'
+require 'basecrm/models/note'
+require 'basecrm/models/pipeline'
+require 'basecrm/models/source'
+require 'basecrm/models/stage'
+require 'basecrm/models/tag'
+require 'basecrm/models/task'
+require 'basecrm/models/user'
+
+require 'basecrm/paginated_resource'
+require 'basecrm/services/accounts_service'
+require 'basecrm/services/associated_contacts_service'
+require 'basecrm/services/contacts_service'
+require 'basecrm/services/deals_service'
+require 'basecrm/services/leads_service'
+require 'basecrm/services/loss_reasons_service'
+require 'basecrm/services/notes_service'
+require 'basecrm/services/pipelines_service'
+require 'basecrm/services/sources_service'
+require 'basecrm/services/stages_service'
+require 'basecrm/services/tags_service'
+require 'basecrm/services/tasks_service'
+require 'basecrm/services/users_service'
+
+module BaseCRM
+  class Client
+    attr_reader :config
+    attr_reader :http_client
+
+    # Instantiate a new BaseCRM API V2 client
+    #
+    # @param options [Hash] Client options
+    # @option options [String] :access_token Personal access token
+    # @option options [String] :base_url (https://api.getbase.com) Base url for the api
+    # @option options [String] :use_agent (BaseCRM/v2 Ruby/{Version}) Client user agent
+    # @option options [Integer] :timeout (30) Request timeout
+    # @option options [Boolean] :verbose (false) Verbose/debug mode
+    # @option options [Logger] :logger (STDOUT) Logged used in verbose mode
+    #
+    # @raise [ConfigurationError] if no access token provided
+    # @raise [ConfigurationError] if provided access token is invalid - contains disallowed characters
+    # @raise [ConfigurationError] if provided access token is invalid - has invalid length
+    # @raise [ConfigurationError] if provided base url is invalid
+    #
+    # @return [Client] New client
+    def initialize(options={})
+      @config = Configuration.new(options)
+      @config.validate!
+
+      @http_client = HttpClient.new(@config)
+    end
+
+    # Access all Accounts related actions. 
+    # @see AccountsService 
+    # @see Account
+    # 
+    # @return [AccountsService] Service object for  resources.
+    def accounts
+      @accounts ||= AccountsService.new(@http_client)
+    end
+
+    # Access all AssociatedContacts related actions. 
+    # @see AssociatedContactsService 
+    # @see AssociatedContact
+    # 
+    # @return [AssociatedContactsService] Service object for  resources.
+    def associated_contacts
+      @associated_contacts ||= AssociatedContactsService.new(@http_client)
+    end
+
+    # Access all Contacts related actions. 
+    # @see ContactsService 
+    # @see Contact
+    # 
+    # @return [ContactsService] Service object for  resources.
+    def contacts
+      @contacts ||= ContactsService.new(@http_client)
+    end
+
+    # Access all Deals related actions. 
+    # @see DealsService 
+    # @see Deal
+    # 
+    # @return [DealsService] Service object for  resources.
+    def deals
+      @deals ||= DealsService.new(@http_client)
+    end
+
+    # Access all Leads related actions. 
+    # @see LeadsService 
+    # @see Lead
+    # 
+    # @return [LeadsService] Service object for  resources.
+    def leads
+      @leads ||= LeadsService.new(@http_client)
+    end
+
+    # Access all LossReasons related actions. 
+    # @see LossReasonsService 
+    # @see LossReason
+    # 
+    # @return [LossReasonsService] Service object for  resources.
+    def loss_reasons
+      @loss_reasons ||= LossReasonsService.new(@http_client)
+    end
+
+    # Access all Notes related actions. 
+    # @see NotesService 
+    # @see Note
+    # 
+    # @return [NotesService] Service object for  resources.
+    def notes
+      @notes ||= NotesService.new(@http_client)
+    end
+
+    # Access all Pipelines related actions. 
+    # @see PipelinesService 
+    # @see Pipeline
+    # 
+    # @return [PipelinesService] Service object for  resources.
+    def pipelines
+      @pipelines ||= PipelinesService.new(@http_client)
+    end
+
+    # Access all Sources related actions. 
+    # @see SourcesService 
+    # @see Source
+    # 
+    # @return [SourcesService] Service object for  resources.
+    def sources
+      @sources ||= SourcesService.new(@http_client)
+    end
+
+    # Access all Stages related actions. 
+    # @see StagesService 
+    # @see Stage
+    # 
+    # @return [StagesService] Service object for  resources.
+    def stages
+      @stages ||= StagesService.new(@http_client)
+    end
+
+    # Access all Tags related actions. 
+    # @see TagsService 
+    # @see Tag
+    # 
+    # @return [TagsService] Service object for  resources.
+    def tags
+      @tags ||= TagsService.new(@http_client)
+    end
+
+    # Access all Tasks related actions. 
+    # @see TasksService 
+    # @see Task
+    # 
+    # @return [TasksService] Service object for  resources.
+    def tasks
+      @tasks ||= TasksService.new(@http_client)
+    end
+
+    # Access all Users related actions. 
+    # @see UsersService 
+    # @see User
+    # 
+    # @return [UsersService] Service object for  resources.
+    def users
+      @users ||= UsersService.new(@http_client)
+    end
+  end
+end