bookingsync-api 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 482e5a2b0789e895be5b708da4e0695d9f0a260f
-  data.tar.gz: 9243586b0e24bbab147f20ecbce0b6da009de350
+  metadata.gz: 43eb6b12130e0e8f634f516be82b68aa771aee94
+  data.tar.gz: cb1438eb9863b01ba062f7d695e7f724bb8b5ec1
 SHA512:
-  metadata.gz: 366e4825396ef6b9cfcb2596c4ac9fdab053c8b8ce0a82ecfc7c16817724b3995df63eddc5e6e386ce077188b2286f3828fbd5a23875f5f5c82035376a1f4312
-  data.tar.gz: ae0492b2ab4c56881ba3c225357cd72fd24d981ca94f2e6d602f1236d8914a1e4c0a65e61cfba93efe9312565ac7ebf0eb15d6be2059a4d28e4e3c4e4e72f939
+  metadata.gz: b0236f9a753191bb68adc74a0074acd258901ad0f37fd1e5ea78ffa2ce658fe1056482480e1b53abd1cb7dbd0aa6014ed586c45ee4c67114afaae3af1a4411c3
+  data.tar.gz: 65eaa193e9b8f89a24a0192486554313f16462494327602966b32efc649eba4e720acb06126d70c175b13e9cf0146a1ba9b82c2455f23885dd4ac3b50b286136

data/README.md

@@ -27,7 +27,31 @@ Gem assumes that you already have OAuth token for an account.
     rentals = api.rentals # => [Sawyer::Resource, Sawyer::Resource]
     rentals.first.name # => "Small apartment"
 
-See our [documentation](http://rubydoc.info/github/BookingSync/bookingsync-api) for more info.
+### Pagination
+
+All endpoints returning a collection of resources can be paginated. There are three ways to do it.
+
+Specify `:per_page` and `:page` params. It's useful when implementing pagination on your site.
+
+    api.bookings(per_page: 10, page: 1) => [Sawyer::Resource, Sawyer::Resource, ...]
+
+Use pagination with a block.
+
+    api.bookings(per_page: 10) do |batch|
+      # display 10 bookings, will make one HTTP request for each batch
+    end
+
+Fetch all resources (with multiple requests under the hood) and return one big array.
+
+    api.bookings(auto_paginate: true) => [Sawyer::Resource, Sawyer::Resource, ...]
+
+## Gem documentation
+
+See [gem documentation](http://rdoc.info/github/BookingSync/bookingsync-api/master/frames) for more info.
+
+## API documentation
+
+See [API documentation](http://docs.api.bookingsync.com).
 
 ## Running specs
 

data/lib/bookingsync/api.rb

@@ -1,6 +1,7 @@
 require "faraday"
 require "sawyer"
 
+require "bookingsync/ext/resource"
 require "bookingsync/api/version"
 require "bookingsync/api/client"
 

data/lib/bookingsync/api/client.rb

@@ -1,11 +1,13 @@
 require "bookingsync/api/middleware/authentication"
 require "bookingsync/api/client/bookings"
+require "bookingsync/api/client/inquiries"
 require "bookingsync/api/client/rentals"
 require "bookingsync/api/error"
 
 module BookingSync::API
   class Client
     include BookingSync::API::Client::Bookings
+    include BookingSync::API::Client::Inquiries
     include BookingSync::API::Client::Rentals
 
     MEDIA_TYPE = "application/vnd.api+json"
@@ -23,9 +25,37 @@ module BookingSync::API
     # Make a HTTP GET request
     #
     # @param path [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Query params for the request
     # @return [Array<Sawyer::Resource>] Array of resources.
     def get(path, options = {})
-      request :get, path, options
+      request :get, path, query: options
+    end
+
+    # Make a HTTP POST request
+    #
+    # @param path [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Body params for the request
+    # @return [Array<Sawyer::Resource>]
+    def post(path, options = {})
+      request :post, path, options
+    end
+
+    # Make a HTTP PUT request
+    #
+    # @param path [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Body params for the request
+    # @return [Array<Sawyer::Resource>]
+    def put(path, options = {})
+      request :put, path, options
+    end
+
+    # Make a HTTP DELETE request
+    #
+    # @param path [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Body params for the request
+    # @return [Array<Sawyer::Resource>]
+    def delete(path, options = {})
+      request :delete, path, options
     end
 
     # Return API endpoint
@@ -41,28 +71,68 @@ module BookingSync::API
     #
     # @param method [Symbol] HTTP verb to use.
     # @param path [String] The path, relative to {#api_endpoint}.
-    # @param query [Hash] A customizable set of query options.
+    # @param data [Hash] Data to be send in the request's body
+    #   it can include query: key with requests params for GET requests
+    # @param options [Hash] A customizable set of request options.
     # @return [Array<Sawyer::Resource>] Array of resources.
-    def request(method, path, query = {})
-      [:fields, :status].each do |key|
-        query[key] = Array(query[key]).join(",") if query.has_key?(key)
+    def request(method, path, data, options = {})
+      if data.is_a?(Hash)
+        options[:query] = data.delete(:query) || {}
+        options[:query].keys.each do |key|
+          if options[:query][key].is_a?(Array)
+            options[:query][key] = options[:query][key].join(",")
+          end
+        end
       end
 
-      response = agent.call(method, path, nil, {query: query})
+      @last_response = response = agent.call(method, path, data.to_json, options)
       case response.status
-      # fetch objects from outer hash
-      # {rentals => [{rental}, {rental}]}
-      # will return [{rental}, {rental}]
-      when 200..299; response.data.to_hash.values.flatten
+      when 204; [] # update/destroy response
+      when 200..299; json_api_to_array(response.data)
       when 401; raise Unauthorized.new
+      when 422; raise UnprocessableEntity.new
       end
     end
 
+    def paginate(path, options = {}, &block)
+      auto_paginate = options.delete(:auto_paginate)
+
+      data = request(:get, path, query: options)
+
+      if (block_given? or auto_paginate) && @last_response.rels[:next]
+        first_request = true
+        loop do
+          if block_given?
+            yield(json_api_to_array(@last_response.data))
+          elsif auto_paginate
+            data.concat(json_api_to_array(@last_response.data)) unless first_request
+            first_request = false
+          end
+          break unless @last_response.rels[:next]
+          @last_response = @last_response.rels[:next].get
+        end
+      end
+
+      data
+    end
+
     private
 
+    # Return collection of resources
+    #
+    # In jsonapi spec every response has format
+    # {resources => [{resource}, {resource}]. This method returns the inner Array
+    # @param data [Sawyer::Resource]  Sawyer resource from response.data
+    # @return [<Sawyer::Resource>] An Array of resources
+    # FIXME: This could have better name
+    def json_api_to_array(data)
+      data.to_hash.values.flatten
+    end
+
     def agent
       @agent ||= Sawyer::Agent.new(api_endpoint, sawyer_options) do |http|
         http.headers[:accept] = MEDIA_TYPE
+        http.headers[:content_type] = MEDIA_TYPE
       end
     end
 

data/lib/bookingsync/api/client/bookings.rb

@@ -15,11 +15,51 @@ module BookingSync::API
       #   are shown, otherwise they are hidden.
       # @option options [Array] status: Array of booking states.
       #   If specyfied bookings with given states are shown.
+      #   Possible statuses: `:booked`, `:unavailable` and `:tentative`
       # @return [Array<Sawyer::Resource>] Array of bookings.
       # @example
       #   @api.bookings(months: 12, states: [:booked, :unavailable], include_canceled: true)
-      def bookings(options = {})
-        get :bookings, options
+      #
+      # @example Pagination
+      #   @api.bookings(per_page: 10) do |batch|
+      #     # do something with ten bookings
+      #   end
+      # @see http://docs.api.bookingsync.com/reference/endpoints/bookings/#list-bookings
+      # @see http://docs.api.bookingsync.com/reference/endpoints/bookings/#search-bookings
+      def bookings(options = {}, &block)
+        paginate :bookings, options, &block
+      end
+
+
+      # Create a booking
+      #
+      # @param options [Hash] Booking attributes
+      # @return <Sawyer::Resource> Newly create booking
+      def create_booking(options = {})
+        post(:bookings, bookings: [options]).pop
+      end
+
+      # Edit a booking
+      #
+      # @param booking [Sawyer::Resource|Integer] Booking or ID of the booking
+      #   to be updated
+      # @param options [Hash] Booking attributes to be updated
+      # FIXME: should be changed resource
+      # @return [Array] An empty Array on success, exception is raised otherwise
+      # @example
+      #   booking = @api.bookings.first
+      #   @api.edit_booking(booking, {adults: 1}) => []
+      def edit_booking(booking, options = {})
+        put "bookings/#{booking}", bookings: [options]
+      end
+
+      # Cancel a booking
+      #
+      # @param booking [Sawyer::Resource|Integer] Booking or ID of the booking
+      #   to be canceled
+      # @return [Array] An empty Array on success, exception is raised otherwise
+      def cancel_booking(booking, options = {})
+        delete "bookings/#{booking}"
       end
     end
   end

data/lib/bookingsync/api/client/inquiries.rb

@@ -0,0 +1,23 @@
+module BookingSync::API
+  class Client
+    module Inquiries
+      # List inquiries
+      #
+      # Return list of inquiries for current account.
+      # @param options [Hash] A customizable set of query options.
+      # @return [Array<Sawyer::Resource>] Array of inquiries.
+      # @see http://docs.api.bookingsync.com/reference/endpoints/inquiries/#list-inquiries
+      def inquiries(options = {}, &block)
+        paginate :inquiries, options, &block
+      end
+
+      # Create a new inquiry
+      #
+      # @param options [Hash] Inquiry attributes
+      # @return <Sawyer::Resource> Newly create inquiry
+      def create_inquiry(options = {})
+        post(:inquiries, inquiries: [options]).pop
+      end
+    end
+  end
+end

data/lib/bookingsync/api/client/rentals.rb

@@ -13,8 +13,9 @@ module BookingSync::API
       #   rentals.first.name # => "Small apartment"
       # @example Get the list of rentals only with name and description for smaller response
       #   @api.rentals(fields: [:name, :description])
-      def rentals(options = {})
-        get :rentals, options
+      # @see http://docs.api.bookingsync.com/reference/endpoints/rentals/#list-rentals
+      def rentals(options = {}, &block)
+        paginate :rentals, options, &block
       end
     end
   end

data/lib/bookingsync/api/error.rb

@@ -2,4 +2,5 @@ module BookingSync::API
   # Class for rescuing all BS API errors
   class Error < StandardError; end
   class Unauthorized < Error; end
+  class UnprocessableEntity < Error; end
 end

data/lib/bookingsync/api/version.rb

@@ -1,5 +1,5 @@
 module BookingSync
   module API
-    VERSION = "0.0.4"
+    VERSION = "0.0.5"
   end
 end

data/lib/bookingsync/ext/resource.rb

@@ -0,0 +1,9 @@
+module Sawyer
+  class Resource
+    # With below alias it's possible to pass ID or Sawyer::Resource
+    # to edit/destroy methods
+    def to_s
+      id
+    end
+  end
+end

data/spec/bookingsync/api/client/bookings_spec.rb

@@ -8,5 +8,83 @@ describe BookingSync::API::Client::Bookings do
       expect(client.bookings).not_to be_nil
       assert_requested :get, bs_url("bookings")
     end
+
+    describe "pagination" do
+      context "with per_page setting" do
+        it "returns limited number of bookings" do
+          bookings = client.bookings(per_page: 2)
+          expect(bookings.size).to eql(2)
+        end
+      end
+
+      context "with a block" do
+        it "yields block with batch of bookings" do
+          sizes = [2, 2, 1]
+          index = 0
+          client.bookings(per_page: 2) do |bookings|
+            expect(bookings.size).to eql(sizes[index])
+            index += 1
+          end
+        end
+      end
+
+      context "with auto_paginate: true" do
+        it "returns all bookings joined from many requests" do
+          bookings = client.bookings(per_page: 2, auto_paginate: true)
+          expect(bookings.size).to eql(5)
+        end
+      end
+    end
+  end
+
+  describe ".create_booking", :vcr do
+    let(:attributes) {
+      {start_at: '2014-01-03', end_at: '2014-01-04', rental_id: 20,
+        booked: true}
+    }
+
+    it "creates a booking" do
+      client.create_booking(attributes)
+      assert_requested :post, bs_url("bookings"),
+        body: {bookings: [attributes]}.to_json
+    end
+
+    it "returns newly created booking" do
+      VCR.use_cassette('BookingSync_API_Client_Bookings/_create_booking/creates_a_booking') do
+        booking = client.create_booking(attributes)
+        expect(booking.account_id).to eql(1)
+        expect(booking.rental_id).to eql(20)
+      end
+    end
+  end
+
+  describe ".edit_booking", :vcr do
+    it "updates given booking by ID" do
+      client.edit_booking(50, {adults: 1})
+      assert_requested :put, bs_url("bookings/50"),
+        body: {bookings: [{adults: 1}]}.to_json
+    end
+
+    it "returns an empty array" do
+      VCR.use_cassette('BookingSync_API_Client_Bookings/_edit_booking/updates_given_booking_by_ID') do
+        expect(client.edit_booking(50, {adults: 1})).to eql([])
+      end
+    end
+
+    it "updates given booking by Resource object" do
+      VCR.use_cassette('BookingSync_API_Client_Bookings/_edit_booking/updates_given_booking_by_ID') do
+        resource = double(to_s: "50")
+        client.edit_booking(resource, {adults: 1})
+        assert_requested :put, bs_url("bookings/50"),
+          body: {bookings: [{adults: 1}]}.to_json
+      end
+    end
+  end
+
+  describe ".cancel_booking", :vcr do
+    it "cancels given booking" do
+      client.cancel_booking(50)
+      assert_requested :delete, bs_url("bookings/50")
+    end
   end
 end

data/spec/bookingsync/api/client/inquiries_spec.rb

@@ -0,0 +1,37 @@
+require "spec_helper"
+
+describe BookingSync::API::Client::Inquiries do
+  let(:client) { BookingSync::API::Client.new(test_access_token) }
+
+  describe ".inquiries", :vcr do
+    it "returns inquiries" do
+      expect(client.inquiries).not_to be_nil
+      assert_requested :get, bs_url("inquiries")
+    end
+  end
+
+  describe ".create_inquiry", :vcr do
+    let(:attributes) { {
+      rental_id: 7,
+      start_at:  Time.now,
+      end_at:    Time.now + 86400, # one day
+      firstname: "John",
+      lastname:  "Smith",
+      email:     "john@example.com"
+    } }
+
+    it "creates a new inquiry" do
+      client.create_inquiry(attributes)
+      assert_requested :post, bs_url("inquiries"),
+        body: {inquiries: [attributes]}.to_json
+    end
+
+    it "returns newly created inquiry" do
+      VCR.use_cassette('BookingSync_API_Client_Inquiries/_create_inquiry/creates_a_new_inquiry') do
+        inquiry = client.create_inquiry(attributes)
+        expect(inquiry.rental_id).to eql(7)
+        expect(inquiry.firstname).to eql("John")
+      end
+    end
+  end
+end

data/spec/bookingsync/api/client_spec.rb

@@ -17,6 +17,48 @@ describe BookingSync::API::Client do
       client.get("resource")
       assert_requested :get, bs_url("resource")
     end
+
+    it "adds query options to the URL" do
+      stub_get("resource?abc=123")
+      client.get("resource", abc: 123)
+      assert_requested :get, bs_url("resource?abc=123")
+    end
+  end
+
+  describe "#post" do
+    before { VCR.turn_off! }
+    it "makes a HTTP POST request with body" do
+      stub_post("resource")
+      client.post("resource", {key: :value})
+      assert_requested :post, bs_url("resource"), body: '{"key":"value"}'
+    end
+
+    context "on 422 response" do
+      it "raises UnprocessableEntity exception" do
+        stub_post("resource", status: 422)
+        expect {
+          client.post("resource", {key: :value})
+        }.to raise_error(BookingSync::API::UnprocessableEntity)
+      end
+    end
+  end
+
+  describe "#put" do
+    before { VCR.turn_off! }
+    it "makes a HTTP PUT request with body" do
+      stub_put("resource")
+      client.put("resource", {key: :value})
+      assert_requested :put, bs_url("resource"), body: '{"key":"value"}'
+    end
+  end
+
+  describe "#delete" do
+    before { VCR.turn_off! }
+    it "makes a HTTP DELETE request" do
+      stub_delete("resource")
+      client.delete("resource")
+      assert_requested :delete, bs_url("resource")
+    end
   end
 
   describe "#request" do
@@ -29,13 +71,20 @@ describe BookingSync::API::Client do
         headers: {"Authorization" => "Bearer fake-access-token"}
     end
 
-    it "requests proper content type for JSON API" do
+    it "requests proper accept header for JSON API" do
       stub_get("resource")
       client.get("resource")
       assert_requested :get, bs_url("resource"),
         headers: {"Accept" => "application/vnd.api+json"}
     end
 
+    it "requests sends data with JSON API content type" do
+      stub_post("resource")
+      client.post("resource")
+      assert_requested :post, bs_url("resource"),
+        headers: {"Content-Type" => "application/vnd.api+json"}
+    end
+
     it "returns Array of resources" do
       stub_get("resource", body: {resources: [{name: "Megan"}]}.to_json)
       resources = client.get("resource")
@@ -43,7 +92,7 @@ describe BookingSync::API::Client do
       expect(resources.first.name).to eq("Megan")
     end
 
-    context "client returns 401" do
+    context "API returns 401" do
       it "raises Unauthorized exception" do
         stub_get("resource", status: 401)
         expect {
@@ -52,19 +101,32 @@ describe BookingSync::API::Client do
       end
     end
 
-    context "status code is outside 200..299 range" do
+    context "API returns status code outside 200..299 range" do
       it "returns nil" do
         stub_get("resource", status: 404)
         expect(client.get("resource")).to be_nil
       end
     end
 
+    context "API returns 204 No Content" do
+      it "returns an empty array" do
+        stub_get("resource", status: 204)
+        expect(client.get("resource")).to eql([])
+      end
+    end
+
     context "user wants to fetch only specific fields" do
       it "constructs url for filtered fields" do
         stub_get("resource?fields=name,description")
         client.get("resource", fields: [:name, :description])
         assert_requested :get, bs_url("resource?fields=name,description")
       end
+
+      it "should support single field" do
+        stub_get("resource?fields=name")
+        client.get("resource", fields: :name)
+        assert_requested :get, bs_url("resource?fields=name")
+      end
     end
 
     context "user passes additional query options" do