bookingsync-api 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 92433c7543f03518887efc316656768355772c6e
-  data.tar.gz: caf9b90d93ebd5b323f12d7f2a3e81d124353c0b
+  metadata.gz: 15c752a5fbf7e0b1d4990d6b34afc96614ba55ea
+  data.tar.gz: 56a26b6f8d5ddec6b917f0201a0c9455f90df413
 SHA512:
-  metadata.gz: 06dff22dabc99c0e7de5197340db2b0cf6270ec62c18518262f6faa31a597a9a48374baebf4811b9bc1d0af880ec0b0cdd7335b2b5587c95a002c23248f23473
-  data.tar.gz: 640a730f3ee59300645065c3023e3ba4f249e684f35a729acd764f10a348b80f260c134a845853b006ffff3e3dc105e1e781e6fbd4d96022cb9b60c714a34c9d
+  metadata.gz: 410fa026ba1cc55e7a9a01ef2a35747b143e4528f3e2d5ebf1a1990a334e3e3182f5d50240e090ccfd823504619c9ebb1e8ff11eaf68264c421781cf68a89c58
+  data.tar.gz: 16fbf28c39dccbacfb1f4199bf1770fc288ef40178520f688456a34d8a35113d453be8d37e66cf0bfddb307f60ebd3a8f525a9380e7b4282323e7cae72bcedae

data/.travis.yml

@@ -1,5 +1,5 @@
 language: ruby
 rvm:
-  - 2.1.1
+  - 2.1.2
   - 2.0.0
   - 1.9.3

data/README.md

@@ -45,6 +45,26 @@ Fetch all resources (with multiple requests under the hood) and return one big a
 
     api.bookings(auto_paginate: true) => [BookingSync::API::Resource, BookingSync::API::Resource, ...]
 
+### Logging
+
+Sometimes it's useful to see what data bookingsync-api gem sends and what it
+receives from the API. By default, gem doesn't log anything.
+There are two ways to enable logging:
+
+1. Set `BOOKINGSYNC_API_DEBUG` environment variable to `true`, when running
+  gem or your app server in development. This will print all logs to `STDOUT`.
+
+2. Pass your own logger to API client, it can be for example `Rails.logger`.
+
+        api = BookingSync::API.new("OAUTH_TOKEN", logger: Rails.logger)
+
+#### Log levels
+
+`INFO` - Logged are only request method and the URL.
+`DEBUG` - Logged are request and response headers and bodies.
+
+When using `BOOKINGSYNC_API_DEBUG` variable, log level is DEBUG.
+
 ## Gem documentation
 
 See [gem documentation](http://rdoc.info/github/BookingSync/bookingsync-api/master/frames) for more info.
@@ -70,6 +90,16 @@ you need to run spec with below environment variables.
 
 If you want to change a cassette, you need to delete it first.
 
+### Environment variables
+
+There are a few environment variables which comes handy while developing and
+debugging bookingsync-api gem.
+
+* `BOOKINGSYNC_URL` - The url of the website, should be. Default https://www.bookingsync.com
+* `BOOKINGSYNC_VERIFY_SSL` - Verify SSL. Default to true.
+* `BOOKINGSYNC_API_DEBUG` - If true, gem will log all request/responses to STDOUT. Default to false.
+* `ACCESS_TOKEN` - OAuth token.
+
 ## Contributing
 
 1. Fork it ( http://github.com/BookingSync/bookingsync-api/fork )

data/lib/bookingsync/api.rb

@@ -1,5 +1,4 @@
 require "faraday"
-
 require "bookingsync/api/version"
 require "bookingsync/api/client"
 
@@ -8,9 +7,10 @@ module BookingSync
     # Return new API Client
     #
     # @param token [String] OAuth token
+    # @param options [Hash] Options for the API Client
     # @return [BookingSync::API::Client] New BookingSync API client
-    def self.new(token)
-      Client.new(token)
+    def self.new(token, options = {})
+      Client.new(token, options)
     end
   end
 end

data/lib/bookingsync/api/client.rb

@@ -1,4 +1,5 @@
 require "bookingsync/api/middleware/authentication"
+require "bookingsync/api/middleware/logger"
 require "bookingsync/api/client/amenities"
 require "bookingsync/api/client/billing_addresses"
 require "bookingsync/api/client/bookings"
@@ -22,6 +23,7 @@ require "bookingsync/api/relation"
 require "bookingsync/api/response"
 require "bookingsync/api/resource"
 require "bookingsync/api/serializer"
+require "logger"
 
 module BookingSync::API
   class Client
@@ -46,16 +48,19 @@ module BookingSync::API
 
     MEDIA_TYPE = "application/vnd.api+json"
 
-    attr_reader :token
+    attr_reader :token, :logger
 
     # Initialize new Client
     #
     # @param token [String] OAuth token
     # @param options [Hash]
     # @option options [String] base_url: Base URL to BookingSync site
+    # @option options [Logger] logger: Logger where headers and body of every
+    #   request and response will be logged.
     # @return [BookingSync::API::Client] New BookingSync API client
     def initialize(token, options = {})
       @token = token
+      @logger = options[:logger] || default_logger
       @base_url = options[:base_url]
       @serializer = Serializer.new
       @conn = Faraday.new(faraday_options)
@@ -212,6 +217,7 @@ module BookingSync::API
     def middleware
       Faraday::RackBuilder.new do |builder|
         builder.use :authentication, token
+        builder.use :logger, logger
         builder.adapter Faraday.default_adapter
       end
     end
@@ -262,9 +268,23 @@ module BookingSync::API
       when 204; nil # destroy/cancel
       when 200..299; response
       when 401; raise Unauthorized.new
+      when 404; raise NotFound.new
       when 422; raise UnprocessableEntity.new
-      else nil
+      else raise UnsupportedResponse.new(response)
       end
     end
+
+    def debug?
+      ENV["BOOKINGSYNC_API_DEBUG"] == "true"
+    end
+
+    # Return default logger. By default we don't log anywhere.
+    # If we are in debug mode, we log everything to STDOUT.
+    #
+    # @return [Logger] Logger where faraday middleware will log requests and
+    #   responses.
+    def default_logger
+      Logger.new(debug? ? STDOUT : nil)
+    end
   end
 end

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

@@ -32,10 +32,12 @@ module BookingSync::API
 
       # Create a booking
       #
-      # @param options [Hash] Booking attributes
-      # @return [BookingSync::API::Resource] Newly create booking
-      def create_booking(options = {})
-        post(:bookings, bookings: [options]).pop
+      # @param rental [BookingSync::API::Resource|Integer] Rental or ID of
+      #   the rental for which booking will be created.
+      # @param options [Hash] Booking attributes.
+      # @return [BookingSync::API::Resource] Newly create booking.
+      def create_booking(rental, options = {})
+        post("rentals/#{rental}/bookings", bookings: [options]).pop
       end
 
       # Edit a booking
@@ -53,9 +55,9 @@ module BookingSync::API
 
       # Cancel a booking
       #
-      # @param booking [BookingSync::API::Resource|Integer] Booking or ID of the booking
-      #   to be canceled
-      # @return [Array] An empty Array on success, exception is raised otherwise
+      # @param booking [BookingSync::API::Resource|Integer] Booking or ID of
+      #   the booking to be canceled.
+      # @return [NilClass] Returns nil on success.
       def cancel_booking(booking, options = {})
         delete "bookings/#{booking}"
       end

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

@@ -13,10 +13,12 @@ module BookingSync::API
 
       # Create a new inquiry
       #
-      # @param options [Hash] Inquiry attributes
-      # @return [BookingSync::API::Resource] Newly create inquiry
-      def create_inquiry(options = {})
-        post(:inquiries, inquiries: [options]).pop
+      # @param rental [BookingSync::API::Resource] Rental or ID of the rental
+      #   for which an inquiry will be created.
+      # @param options [Hash] Inquiry attributes.
+      # @return [BookingSync::API::Resource] Newly create inquiry.
+      def create_inquiry(rental, options = {})
+        post("rentals/#{rental}/inquiries", inquiries: [options]).pop
       end
     end
   end

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

@@ -42,10 +42,10 @@ module BookingSync::API
 
       # Cancel a payment
       #
-      # @param payment [BookingSync::API::Resource|Integer] payment or ID of the payment
-      # to be canceled
-      # @return [Array] An empty Array on success, exception is raised otherwise
-      def cancel_payment(payment, options = {})
+      # @param payment [BookingSync::API::Resource|Integer] Payment or ID of
+      #   the payment to be canceled.
+      # @return [NilClass] Returns nil on success.
+      def cancel_payment(payment)
         delete "payments/#{payment}"
       end
     end

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

@@ -20,20 +20,21 @@ module BookingSync::API
 
       # Create a new period
       #
-      # @param season_id [Integer] ID of the season
-      # @param options [Hash] period attributes
-      # @return [BookingSync::API::Resource] Newly created period
-      def create_period(season_id, options = {})
-        post(:periods, season_id: season_id, periods: [options]).pop
+      # @param season [BookingSync::API::Resource|Integer] Season or ID of
+      #   the season for which period will be created.
+      # @param options [Hash] Period's attributes.
+      # @return [BookingSync::API::Resource] Newly created period.
+      def create_period(season, options = {})
+        post("seasons/#{season}/periods", periods: [options]).pop
       end
 
       # Edit a period
       #
-      # @param period [BookingSync::API::Resource|Integer] period or ID of the period
-      # to be updated
-      # @param options [Hash] period attributes to be updated
+      # @param period [BookingSync::API::Resource|Integer] Period or ID of
+      #   the period to be updated.
+      # @param options [Hash] period attributes to be updated.
       # @return [BookingSync::API::Resource] Updated period on success,
-      # exception is raised otherwise
+      #   exception is raised otherwise.
       # @example
       #   period = @api.periods.first
       #   @api.edit_period(period, { end_at: "2014-04-28" })
@@ -43,10 +44,10 @@ module BookingSync::API
 
       # Delete a period
       #
-      # @param period [BookingSync::API::Resource|Integer] period or ID of the period
-      # to be deleted
-      # @return [Array] An empty Array on success, exception is raised otherwise
-      def delete_period(period, options = {})
+      # @param period [BookingSync::API::Resource|Integer] Period or ID
+      #   of the period to be deleted.
+      # @return [NilClass] Returns nil on success.
+      def delete_period(period)
         delete "periods/#{period}"
       end
     end

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

@@ -1,3 +1,5 @@
+require "base64"
+
 module BookingSync::API
   class Client
     module Photos
@@ -17,6 +19,57 @@ module BookingSync::API
       def photos(options = {}, &block)
         paginate :photos, options, &block
       end
+
+      # Create a photo
+      #
+      # @param rental [BookingSync::API::Resource|Integer] Rental object or ID
+      #   for which the photo will be created. Image can be provided in three
+      #   was, as a file path, encode string or as an URL.
+      # @param options [Hash] Photo's attributes.
+      # @option options [String] photo_path: Path to the image to be uploaded.
+      # @option options [String] photo: Photo encoded with Base64
+      # @option options [String] remote_photo_url: URL to a remote image which
+      #   will be fetched and then saved
+      # @return [BookingSync::API::Resource] Newly created photo.
+      # @example Create a photo.
+      #   @api.create_photo(10, photo_path: 'rentals/big_one.jpg')
+      # @see http://docs.api.bookingsync.com/reference/endpoints/photos/#create-a-new-photo
+      def create_photo(rental, options = {})
+        if photo_path = options.delete(:photo_path)
+          options[:photo] ||= encode(photo_path)
+        end
+        post("rentals/#{rental}/photos", photos: [options]).pop
+      end
+
+      # Edit a photo
+      #
+      # @param photo [BookingSync::API::Resource|Integer] Photo or ID of the
+      #   photo to be updated.
+      # @param options [Hash] Photo's attributes.
+      # @return [BookingSync::API::Resource] Updated photo
+      # @see http://docs.api.bookingsync.com/reference/endpoints/photos/#update-a-photo
+      def edit_photo(photo, options = {})
+        if photo_path = options.delete(:photo_path)
+          options[:photo] ||= encode(photo_path)
+        end
+        put("photos/#{photo}", photos: [options]).pop
+      end
+
+      # Delete a photo
+      #
+      # @param photo [BookingSync::API::Resource|Integer] Photo or ID of the
+      #   photo to be deleted.
+      # @return [NilClass] Returns nil on success.
+      # @see http://docs.api.bookingsync.com/reference/endpoints/photos/#destroy-a-photo
+      def delete_photo(photo)
+        delete "photos/#{photo}"
+      end
+
+      private
+
+      def encode(file_path)
+        Base64.encode64(File.read(file_path))
+      end
     end
   end
 end

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

@@ -40,12 +40,12 @@ module BookingSync::API
         put("rates_tables/#{rates_table}", rates_tables: [options]).pop
       end
 
-      # delete a rates_table
+      # Delete a rates_table
       #
-      # @param rates_table [BookingSync::API::Resource|Integer] rates table or
-      # ID of the rates table to be deleteed
-      # @return [Array] An empty Array on success, exception is raised otherwise
-      def delete_rates_table(rates_table, options = {})
+      # @param rates_table [BookingSync::API::Resource|Integer] Rates table or
+      #   ID of the rates table to be deleteed.
+      # @return [NilClass] Returns nil on success
+      def delete_rates_table(rates_table)
         delete "rates_tables/#{rates_table}"
       end
     end

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

@@ -1,9 +1,10 @@
 module BookingSync::API
   class Client
     module RentalAgreements
-      # List rental agreements
+      # List rental agreements.
       #
-      # Returns rental agreements for the rentals of the account user is authenticated with.
+      # Returns rental agreements for the rentals of the account
+      #   user is authenticated with.
       # @param options [Hash] A customizable set of options.
       # @option options [Array] fields: List of fields to be fetched.
       # @return [Array<BookingSync::API::Resource>] Array of rental agreements.
@@ -18,30 +19,32 @@ module BookingSync::API
         paginate :rental_agreements, options, &block
       end
 
-      # Create a new rental agreement for a booking
+      # Create a new rental agreement for a booking.
       #
-      # @param booking_id [Integer] ID of the booking
-      # @param options [Hash] rental agreement attributes
-      # @return [BookingSync::API::Response] Newly created rental agreement
-      def create_rental_agreement_for_booking(booking_id, options = {})
-        post(:rental_agreements, booking_id: booking_id,
-             rental_agreements: [options]).pop
+      # @param booking [BookingSync::API::Resource|Integer] Booking or ID of
+      #   the booking for which rental agreement will be created.
+      # @param options [Hash] Rental agreement's attributes.
+      # @return [BookingSync::API::Resource] Newly created rental agreement.
+      def create_rental_agreement_for_booking(booking, options = {})
+        post("bookings/#{booking}/rental_agreements",
+          rental_agreements: [options]).pop
       end
 
-      # Create a new rental agreement for a rental
+      # Create a new rental agreement for a rental.
       #
-      # @param rental_id [Integer] ID of the rental
-      # @param options [Hash] rental agreement attributes
-      # @return [BookingSync::API::Response] Newly created rental agreement
-      def create_rental_agreement_for_rental(rental_id, options = {})
-        post(:rental_agreements, rental_id: rental_id,
-             rental_agreements: [options]).pop
+      # @param rental [BookingSync::API::Resource|Integer] Rental or ID of
+      #   the rental for which rental agreement will be created.
+      # @param options [Hash] Rental agreement's attributes.
+      # @return [BookingSync::API::Resource] Newly created rental agreement
+      def create_rental_agreement_for_rental(rental, options = {})
+        post("rentals/#{rental}/rental_agreements",
+          rental_agreements: [options]).pop
       end
 
-      # Create a new rental agreement for an account
+      # Create a new rental agreement for an account.
       #
-      # @param options [Hash] rental agreement attributes
-      # @return [BookingSync::API::Response] Newly created rental agreement
+      # @param options [Hash] Rental agreement's attributes.
+      # @return [BookingSync::API::Resource] Newly created rental agreement.
       def create_rental_agreement(options = {})
         post(:rental_agreements, rental_agreements: [options]).pop
       end

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

@@ -39,18 +39,19 @@ module BookingSync::API
         put("rentals/#{rental}", rentals: [options]).pop
       end
 
-      # Cancel a rental
+      # Delete a rental
       #
-      # @param rental [BookingSync::API::Resource|Integer] rental or ID of the rental
-      # to be canceled
-      # @return [Array] An empty Array on success, exception is raised otherwise
-      def cancel_rental(rental, options = {})
+      # @param rental [BookingSync::API::Resource|Integer] Rental or ID
+      #   of the rental to be deleted.
+      # @return [NilClass] Returns nil on success.
+      def delete_rental(rental)
         delete "rentals/#{rental}"
       end
 
       # Get a single rental
       #
-      # @param rental [BookingSync::API::Resource|Integer] Rental or ID of the rental
+      # @param rental [BookingSync::API::Resource|Integer] Rental or ID
+      #   of the rental.
       # @return [BookingSync::API::Resource]
       def rental(rental)
         get("rentals/#{rental}").pop

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

@@ -20,11 +20,12 @@ module BookingSync::API
 
       # Create a new review
       #
-      # @param booking_id [Integer] ID of the booking
-      # @param options [Hash] review attributes
-      # @return [BookingSync::API::Resource] Newly created review
-      def create_review(booking_id, options = {})
-        post(:reviews, booking_id: booking_id, reviews: [options]).pop
+      # @param booking [BookingSync::API::Resource|Integer] Booking or ID of
+      #   the booking for which a review will be created.
+      # @param options [Hash] Review's attributes.
+      # @return [BookingSync::API::Resource] Newly created review.
+      def create_review(booking, options = {})
+        post("bookings/#{booking}/reviews", reviews: [options]).pop
       end
     end
   end