bcx 0.0.1 → 0.0.2

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -3,4 +3,4 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in bcx.gemspec
 gemspec
 
-gem 'rapidash', path: '/Users/paul/Sites/rapidash'
+gem 'rapidash', github: 'paulspringett/rapidash', branch: 'error-handling'

data/README.md

@@ -1,29 +1,78 @@
-# Bcx
+## Bcx
 
-TODO: Write a gem description
+> NB. This is still alpha software and may not work as expected. It's also missing a lot of the Basecamp endpoints. Please feel free to contribute!
 
-## Installation
+Fully-fledged Ruby API wrapper for Basecamp Next
 
-Add this line to your application's Gemfile:
+```
+      ___________________ ____  ___
+      \______   \_   ___ \\   \/  /
+       |    |  _/    \  \/ \     /
+       |    |   \     \____/     \
+       |______  /\______  /___/\  \
+              \/        \/      \_/
+```
 
-    gem 'bcx'
+### Installation
 
-And then execute:
+```shell
+$ gem install bcx
+```
 
-    $ bundle
+Or if you are using Bundler
 
-Or install it yourself as:
+```ruby
+gem 'bcx'
+```
 
-    $ gem install bcx
+### Usage
 
-## Usage
+You can connect to the Basecamp API using the Bcx client. The client provides authentication over HTTP or OAuth.
 
-TODO: Write usage instructions here
+#### HTTP Basic Auth
 
-## Contributing
+```ruby
+client = Bcx::Client.new(:http, login: 'username', password: 'secret')
+```
+
+#### OAuth
+
+```ruby
+client = Bcx::Client.new(:oauth, client_id: '1234567890', client_secret: '831994c4170', access_token: 'b02ff9345c3')
+```
+
+You can get a `client_id` and `client_secret` from https://integrate.37signals.com/
+
+### Resources
+
+See the [full resource documentation](#todo) for all available API endpoints.
+
+#### Bang operators
+
+It's important to understand the use of bang methods when using Bcx. Each resource can be called with or without a `!`.
+
+**Without the bang** you can chain and build endpoint calls:
+
+```ruby
+client.projects(123).todolists
+# => #<Bcx::Resources::Todolist ...>
+
+client.projects(123).todolists.url
+# => "projects/123/todolists"
+```
+
+**With the bang** you can hit the API endpoint over the network and fetch data:
+
+```ruby
+client.projects(123).todolists!
+# => [#<Hashie::Mash id=456 ...>, #<Hashie::Mash id=789 ...>]
+```
+
+### Contributing
 
 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
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Write your tests and check everything passes
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request (into the development branch)

data/Rakefile

@@ -1,2 +1,6 @@
 #!/usr/bin/env rake
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task default: [:spec]

data/bcx.gemspec

@@ -16,4 +16,9 @@ Gem::Specification.new do |gem|
   gem.version       = Bcx::VERSION
 
   gem.add_runtime_dependency 'rapidash', '~> 0.2.0'
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'simplecov'
+  gem.add_development_dependency 'vcr'
 end

data/lib/bcx.rb

@@ -3,13 +3,15 @@ require 'bcx/version'
 
 module Bcx
   autoload :Configuration, 'bcx/configuration'
-  autoload :Client, 'bcx/client'
 
   module Resources
-    autoload :Project, 'bcx/resources/project'
+    autoload :Todo, 'bcx/resources/todo'
     autoload :Todolist, 'bcx/resources/todolist'
+    autoload :Project, 'bcx/resources/project'
   end
 
+  autoload :Client, 'bcx/client'
+
   class << self
     attr_accessor :configuration
   end
@@ -19,3 +21,6 @@ module Bcx
     yield(configuration)
   end
 end
+
+require 'bcx/response_error'
+Rapidash.response_exception_class = Bcx::ResponseError

data/lib/bcx/client.rb

@@ -1,15 +1,22 @@
 module Bcx
   class Client < Rapidash::Client
-    @account = Bcx.configuration.account
-    @api_version = Bcx.configuration.api_version
-
-    site "https://basecamp.com/#{@account}/api/#{@api_version}/"
     extension :json
 
+    raise_errors
+
     resource :projects, class_name: 'Bcx::Resources::Project'
+    resource :todolists, class_name: 'Bcx::Resources::Todolist'
 
     def initialize(auth_method, options = {})
+      @account = Bcx.configuration.account
+      @api_version = Bcx.configuration.api_version
+
+      self.class.site("https://basecamp.com/#{@account}/api/#{@api_version}/")
       self.class.method(auth_method)
+
+      options[:uid] ||= options[:client_id]
+      options[:secret] ||= options[:client_secret]
+
       super(options)
     end
 

data/lib/bcx/configuration.rb

@@ -1,4 +1,13 @@
 module Bcx
+
+  # Bcx::Configuration
+  # Provides a configuration block for setting up the Bcx client
+  # Example:
+  #
+  #   Bcx.configure do |config|
+  #     config.account = '1234567890'
+  #   end
+  #
   class Configuration
     attr_accessor :account, :api_version
 

data/lib/bcx/resources/person.rb

@@ -0,0 +1,13 @@
+module Bcx
+  module Resources
+
+    # Get todolists with assigned todos for a person
+    # GET /people/1/assigned_todos.json
+    #
+    #   client.people(1).assigned_todos
+    #
+    class Person < Rapidash::Base
+
+    end
+  end
+end

data/lib/bcx/resources/project.rb

@@ -1,9 +1,47 @@
 module Bcx
   module Resources
+
+    # Bcx::Resources::Project
+    # Provides access to projects resoource and other nested resources
+    #
+    # Fetch all projects
+    # GET /projects.json
+    #
+    #   client.projects!
+    #
+    # Fetch archived projects
+    # GET /projects/archived.json
+    #
+    #   clients.projects.archived!
+    #
+    # Fetch single project with ID of 123
+    # GET /projects/123.json
+    #
+    #   client.projects!(123)
+    #
+    # Create a project
+    # POST /projects.json
+    #
+    #   client.projects.create!(name: 'Acme project', description: 'This is a new project')
+    #
+    # Update an existing project
+    # PUT /projects/123.json
+    #
+    #   client.projects(123).update!(description: 'A new description')
+    #
+    # Delete a project
+    # DELETE /projects/123.json
+    #
+    #   client.projects(123).delete!
+    #
     class Project < Rapidash::Base
-      root :project
+      resource :todolists
+      resource :todos
 
-      resource :todolists, class_name: 'Bcx::Resources::Todolist'
+      def archived!
+        @url += '/archived'
+        call!
+      end
     end
   end
 end

data/lib/bcx/resources/todo.rb

@@ -0,0 +1,37 @@
+module Bcx
+  module Resources
+
+    # Bcx::Resources::Todo
+    # Provides access to todolist resoource both at the client level and per-project
+    #
+    # Get todos for a todolist
+    # GET /todolists/1.json
+    #
+    #   todolist = client.todolists!(1)
+    #   todolist.todos.remaining
+    #   todolist.todos.completed
+    #
+    # Get a specific todo
+    # GET /projects/1/todos/2.json
+    #
+    #   client.projects(1).todos!(2)
+    #
+    # Create a todo
+    # POST /projects/1/todolists/2/todos.json
+    #
+    #   client.projects(1).todolists(2).todos.create!(content: 'Update copy text')
+    #
+    # Update a todo
+    # PUT /projects/1/todos/2.json
+    #
+    #   client.projects(1).todos(2).update!(completed: true)
+    #
+    # Delete a todo
+    # DELETE /projects/1/todos/2.json
+    #
+    #   client.projects(1).todos(2).delete!
+    #
+    class Todo < Rapidash::Base
+    end
+  end
+end

data/lib/bcx/resources/todolist.rb

@@ -1,7 +1,46 @@
 module Bcx
   module Resources
+
+    # Bcx::Resources::Todolist
+    # Provides access to todolist resoource both at the client level and per-project
+    #
+    # Get all todolists for a project
+    # GET /projects/123/todolists.json
+    #
+    #   client.projects(123).todolists!
+    #
+    # Get all completed todolists for a project
+    # GET /projects/1/todolists/completed.json
+    #
+    #   client.projects(123).todolists.completed!
+    #
+    # Get todolists for all projects
+    # GET /todolists.json
+    #
+    #   client.todolists!
+    #
+    # Get completed todolists for all projects
+    # GET /todolists/completed.json
+    #
+    #   client.todolists.completed!
+    #
+    # Get specific todolist including the todos
+    # GET /projects/123/todolists/456.json
+    #
+    #   client.projects(123).todolists!(456)
+    #
+    # Create a new todolist
+    # POST /projects/1/todolists.json
+    #
+    #   client.projects(123).todolists.create!(name: 'My todolist', description: 'This is a todolist')
+    #
     class Todolist < Rapidash::Base
-      root :todolist
+      resource :todos, class_name: 'Bcx::Resources::Todo'
+
+      def completed!
+        @url += '/completed'
+        call!
+      end
     end
   end
 end

data/lib/bcx/response_error.rb

@@ -0,0 +1,17 @@
+module Bcx
+  class ResponseError < Rapidash::ResponseError
+
+    def errors
+      return body if body.kind_of?(String)
+
+      messages = []
+
+      body.each_pair do |attribute, msgs|
+        msgs.each { |msg| messages.push "#{attribute} #{msg}" }
+      end
+
+      messages.join(', ')
+    end
+
+  end
+end

data/lib/bcx/version.rb

@@ -1,3 +1,3 @@
 module Bcx
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/bcx/client_spec.rb

@@ -0,0 +1,40 @@
+require 'spec_helper'
+
+describe Bcx::Client do
+
+  let(:client) { Bcx::Client.new(:http, login: 'bcx-test-user', password: 'secret') }
+
+  describe "http auth" do
+    it "should assign login" do
+      expect(client.login).to eq 'bcx-test-user'
+    end
+
+    it "should assign password" do
+      expect(client.password).to eq 'secret'
+    end
+
+    it "should build a Faraday connection" do
+      expect(client.connection).not_to be_nil
+    end
+  end
+
+  # TODO: test handling to reponse errors, with error codes
+  # it "should fail for invalid attributes" do
+  #   expect { client.projects.create!(name: '') }.to raise_error { |error|
+  #     expect(error).to be_a Bcx::ResponseError
+  #     expect(error.status).to eq 422
+  #   }
+  # end
+
+  # Rescue a response error example
+  # begin
+  #   project = client.projects.create!(name: 'foo')
+  # rescue Bcx::ResponseError => response
+  #   puts response.status
+  #   => 422
+  #   puts response.body
+  #   => "Name cannot be blank"
+  # end
+
+
+end

data/spec/bcx/project_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+
+describe Bcx::Resources::Project, :vcr do
+  let(:client) { Bcx::Client.new(:http, login: 'bcx-test-user', password: 'secret') }
+
+  describe "GET /projects" do
+    let(:projects) { client.projects! }
+
+    it "should be an array" do
+      expect(projects).to be_an Array
+    end
+
+    it "first project should have the correct id" do
+      expect(projects.first.id).to eq 2937644
+    end
+  end
+
+  describe "GET /projects/archived" do
+    let(:projects) { client.projects.archived! }
+
+    it "should be an array" do
+      expect(projects).to be_an Array
+    end
+
+    it "should be empty" do
+      expect(projects).to be_empty
+    end
+  end
+
+  describe "GET /projects/2937644" do
+    let(:project) { client.projects!(2937644) }
+
+    it "should return a hash" do
+      expect(project).to be_a Hashie::Mash
+    end
+
+    it "should have the correct id" do
+      expect(project.id).to eq 2937644
+    end
+  end
+
+  describe "POST /projects" do
+    it "should create a new project" do
+      project = client.projects.create!(name: 'New project', description: 'A new project created over the API')
+      expect(project.created_at).not_to be_blank
+    end
+  end
+
+  describe "PUT /projects/2937644" do
+    it "should update an existing project" do
+      project = client.projects(2937644).update!(description: 'New description')
+      expect(project.description).to eq 'New description'
+    end
+  end
+
+  describe "DELETE /projects/2937644" do
+    it "should delete a project" do
+      client.projects(2937644).delete!
+      expect { client.projects!(2937644) }.to raise_error { |error|
+        expect(error).to be_a Bcx::ResponseError
+        expect(error.status).to eq 404
+      }
+    end
+  end
+end