duffel_api 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb4caaadd883236526bb2e8bdbc78b4f96f2264ae3a09f0c6b2d645eb0e63b4f
-  data.tar.gz: 81a190fbc71c4b5033647393634e0759fdc18513809c1f81fa80dc2ca2453a44
+  metadata.gz: 3f34f8f28b32ebbcce50624f302a8c571322804417841653645dd6ea659f8a22
+  data.tar.gz: fab5945c12ed6054f01330dc2bd62cb814cd90f486b7dc36ed4caa0c8197617c
 SHA512:
-  metadata.gz: 70950a1db91a40ba7fbc1fe2b0b232f8553ab16c497225641ca13d4244374efc9c8b5d80174477e2ab8c3dedd085ea99abc71bdc2159c3af4083ebeab9ac35f6
-  data.tar.gz: 4686727e0c4e1d005713b44e684f91fa931f73d214a778fad5b2cb83724d5592b4d4aace1810f95d9c544d92d37a62eb903af9a4d2765d18ad9ad14a1a5d2fac
+  metadata.gz: 89708a5b441623dfecaee21f06bfba8da70e93b251d2587895a1b7ea3a9df1375251ae5a85de0a4550bf96ef46249a3c8d341f85c187d268cdf4fc6c6029c2da
+  data.tar.gz: c0e3165cf5a164dab4d2da40e9171fc2c680800be4a2f43c96e18556c75c9890555bec6cd3455c90de3c8141347bd32fc13d50eb78e33336ce8954a38387633e

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+.DS_Store

data/Appraisals

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# vim: syntax=ruby
+
+appraise "faraday-1" do
+  gem "faraday", "1.8.0"
+end
+
+appraise "faraday-2" do
+  gem "faraday", "2.0.1"
+end

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.2.0] - 2022-01-11
+
+- Add `WebhookEvent.genuine?` for checking whether a webhook event was genuinely sent by Duffel
+- Add support for `faraday` `v2.x`
+- Add YARD in-code documentation, [published to RubyDoc.info](https://rubydoc.info/github/duffelhq/duffel-api-ruby/main)
+
 ## [0.1.0] - 2021-12-31
 
 - Initial release

data/Gemfile

@@ -6,14 +6,15 @@ source "https://rubygems.org"
 gemspec
 
 group :development, :test do
-  gem "gc_ruboconfig", "~> 2.29.0"
+  gem "gc_ruboconfig", "~> 2.30.0"
   gem "pry", "~> 0.14.1"
   gem "rake", "~> 13.0"
   gem "rspec", "~> 3.10.0"
   gem "rspec-its", "~> 1.3.0"
-  gem "rspec_junit_formatter", "~> 0.4.1"
+  gem "rspec_junit_formatter", "~> 0.5.0"
   gem "rubocop", "~> 1.24.0"
   gem "rubocop-rake", "~> 0.6.0"
   gem "simplecov", "~> 0.21.2"
   gem "webmock", "~> 3.14.0"
+  gem "yard", "~> 0.9.27"
 end

data/README.md

@@ -1,5 +1,7 @@
 # Duffel API Ruby client library
 
+[![RubyDoc.info documentation](http://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/duffelhq/duffel-api-ruby)
+
 A Ruby client library for the [Duffel API](https://duffel.com/docs/api).
 
 ## Contents
@@ -18,7 +20,7 @@ A Ruby client library for the [Duffel API](https://duffel.com/docs/api).
 In most cases, you'll want to add `duffel_api` to your project as a dependency by listing it in your `Gemfile`, and then running `bundle`:
 
 ```ruby
-gem "duffel_api", "~> 0.1.0"
+gem "duffel_api", "~> 0.2.0"
 ```
 
 You can install `duffel_api` outside of the context of a project by running `gem install duffel_api` - for example if you want to play with the client library in `irb`.
@@ -209,4 +211,35 @@ If an error has been raised, you can call `#api_response` on the exception, whic
 
 From the `APIResponse`, you can call `#headers`, `#status_code`, `#raw_body`, `#parsed_body`, `#meta` or `#request_id` to get key information from the response.
 
+### Verifying webhooks
+
+You can set up [webhooks](https://duffel.com/docs/guides/receiving-webhooks) with Duffel to receive notifications about events that happen in your Duffel account - for example, when an airline has a schedule change affecting one of your orders.
+
+These webhook events are signed with a shared secret. This allows you to be sure that any webhook events are genuinely sent from Duffel when you receive them.
+
+When you create a webhook, you'll set a secret. With that secret in mind, you can verify that a webhook is genuine like this:
+
+```ruby
+# In Rails, you'd get this with `request.raw_post`.
+request_body = '{"created_at":"2022-01-08T18:44:56.129339Z","data":{"changes":{},"object":{}},"id":"eve_0000AFEsrBKZAcKgGtZCnQ","live_mode":false,"object":"order","type":"order.updated"}'
+# In Rails, you'd get this with `request.headers['X-Duffel-Signature']`.
+request_signature = "t=1641667496,v1=691f25ffb1f206c0fda5bb7b1a9d60fafe42c5f42819d44a06a7cfe09486f102"
+
+# Note that this code doesn't require your access token - `DuffelAPI::WebhookEvent`
+# doesn't expect you to have a `Client` initialised
+if DuffelAPI::WebhookEvent.genuine?(
+  request_body: request_body,
+  request_signature: request_signature,
+  webhook_secret: "a_secret"
+)
+  puts "This is a real webhook from Duffel 🌟"
+else
+  puts "This is a fake webhook! ☠️"
+end
+```
+
+## Learn more
+
+You can find complete documentation on this library's classes and methods in the in-code
+documentation on [RubyDoc.info](https://rubydoc.info/github/duffelhq/duffel-api-ruby).
 

data/duffel_api.gemspec

@@ -20,17 +20,19 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:test|spec|features|gemfiles|.circleci|.github)/})
+    end
   end
 
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "faraday", [">= 0.9.2", "< 2"]
+  spec.add_dependency "base16", "~> 0.0.2"
+  spec.add_dependency "faraday", ">= 0.9.2", "< 3"
 
-  # Uncomment to register a new dependency of your gem
-  # spec.add_dependency "example-gem", "~> 1.0"
+  spec.add_development_dependency "appraisal", "~> 2.4"
 
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html

data/examples/book_with_extra_baggage.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "duffel_api"
+
+client = DuffelAPI::Client.new(
+  access_token: ENV["DUFFEL_ACCESS_TOKEN"],
+)
+
+# 365 days from now
+departure_date = (Time.now + (60 * 60 * 24 * 365)).strftime("%Y-%m-%d")
+
+offer_request = client.offer_requests.create(params: {
+  cabin_class: "economy",
+  passengers: [{
+    age: 28,
+  }],
+  slices: [{
+    # We use a non-sensical route to make sure we get speedy, reliable Duffel Airways
+    # results.
+    origin: "LGA",
+    destination: "JFK",
+    departure_date: departure_date,
+  }],
+  # This attribute is sent as a query parameter rather than in the body like the others.
+  # Worry not! The library handles this complexity for you.
+  return_offers: false,
+})
+
+puts "Created offer request: #{offer_request.id}"
+
+offers = client.offers.all(params: { offer_request_id: offer_request.id })
+
+puts "Got #{offers.count} offers"
+
+selected_offer = offers.first
+
+puts "Selected offer #{selected_offer.id} to book"
+
+# Send the query param return_available_services to request ancillaries (e.g. baggage)
+priced_offer = client.offers.get(selected_offer.id,
+                                 params: { return_available_services: true })
+
+puts "The final price for offer #{priced_offer.id} is #{priced_offer.total_amount} " \
+     "#{priced_offer.total_currency}"
+
+available_baggage = priced_offer.available_services.
+  find { |service| service["type"] == "baggage" }
+
+puts "Adding #{available_baggage['metadata']['maximum_weight_kg']}kg extra baggage for " \
+     "#{available_baggage['total_amount']} " \
+     "#{available_baggage['total_currency']}"
+
+total_amount = priced_offer.total_amount.to_f +
+  available_baggage["total_amount"].to_f
+
+order = client.orders.create(params: {
+  selected_offers: [priced_offer.id],
+  services: [{
+    id: available_baggage["id"],
+    quantity: 1,
+  }],
+  payments: [
+    {
+      type: "balance",
+      amount: total_amount,
+      currency: priced_offer.total_currency,
+    },
+  ],
+  passengers: [
+    {
+      id: priced_offer.passengers.first["id"],
+      title: "mr",
+      gender: "m",
+      given_name: "Tim",
+      family_name: "Rogers",
+      born_on: "1993-04-01",
+      phone_number: "+441290211999",
+      email: "tim@duffel.com",
+    },
+  ],
+})
+
+puts "Created order #{order.id} with booking reference #{order.booking_reference}"

data/examples/book_with_seat.rb

@@ -36,8 +36,7 @@ selected_offer = offers.first
 
 puts "Selected offer #{selected_offer.id} to book"
 
-priced_offer = client.offers.get(selected_offer.id,
-                                 params: { return_available_services: true })
+priced_offer = client.offers.get(selected_offer.id)
 
 puts "The final price for offer #{priced_offer.id} is #{priced_offer.total_amount} " \
      "#{priced_offer.total_currency}"

data/lib/duffel_api/api_response.rb

@@ -1,17 +1,47 @@
 # frozen_string_literal: true
 
 module DuffelAPI
-  # wraps a faraday response object with some accessors
+  # An HTTP response returned from the API
   class APIResponse
     extend Forwardable
 
+    # Builds an `APIResponse` from a `Response`, the library's internal representation
+    # of an HTTP response
+    #
+    # @param response [Response]
+    # @return [APIResponse]
     def initialize(response)
       @response = response
     end
 
-    def_delegator :@response, :headers
-    def_delegator :@response, :raw_body, :body
-    def_delegator :@response, :status_code
-    def_delegator :@response, :request_id
+    # Returns the HTTP response headers
+    #
+    # @return [Hash]
+    def headers
+      @response.headers
+    end
+
+    # Returns the raw body of the HTTP response
+    #
+    # @return [String]
+    def body
+      @response.raw_body
+    end
+
+    # Returns the HTTP status code of the HTTP response
+    #
+    # @return [Integer]
+    def status_code
+      @response.status_code
+    end
+
+    # Returns the request ID from the Duffel API, included in the response headers.
+    # This could be `nil` if the response didn't make it to the Duffel API itself and,
+    # for example, only reached a load balancer.
+    #
+    # @return [String, nil]
+    def request_id
+      @response.request_id
+    end
   end
 end

data/lib/duffel_api/api_service.rb

@@ -4,8 +4,17 @@ require "faraday"
 require "uri"
 
 module DuffelAPI
+  # An internal class used within the library that is able to make requests to
+  # the Duffel API and handle errors
   class APIService
-    def initialize(base_url, access_token, options = {})
+    # Sets up an API service based on a base URL, access token and set of default
+    # headers
+    #
+    # @param base_url [String] A test or live mode access token
+    # @param access_token [String] The URL of the Duffel API
+    # @param default_headers [Hash] The headers to include by default in HTTP requests
+    # @return [APIService]
+    def initialize(base_url, access_token, default_headers:)
       @base_url = base_url
       root_url, @path_prefix = unpack_url(base_url)
 
@@ -15,16 +24,21 @@ module DuffelAPI
         faraday.adapter(:net_http)
       end
 
-      @headers = options[:default_headers] || {}
-      @headers["Authorization"] = "Bearer #{access_token}"
+      @headers = default_headers.merge("Authorization" => "Bearer #{access_token}")
     end
 
+    # Makes a request to the API, including any defauot headers
+    #
+    # @param method [Symbol] the HTTP method to make the request with
+    # @param path [String] the path to make the request to
+    # @param options [Hash] options to be passed with `Request#new`
+    # @return [Request]
     def make_request(method, path, options = {})
       raise ArgumentError, "options must be a hash" unless options.is_a?(Hash)
 
       options[:headers] ||= {}
       options[:headers] = @headers.merge(options[:headers])
-      Request.new(@connection, method, @path_prefix + path, options).request
+      Request.new(@connection, method, @path_prefix + path, **options).call
     end
 
     private

data/lib/duffel_api/client.rb

@@ -1,73 +1,96 @@
 # frozen_string_literal: true
 
 module DuffelAPI
+  # A client for accessing the Duffel API, configured with a provided access token and
+  # base URL, which provides access to API services
   class Client
     API_VERSION = "beta"
 
+    # Sets up the client with your access token
+    #
+    # @param access_token [String] A test or live mode access token
+    # @param base_url [String] The URL of the Duffel API
+    # @return [Client]
     def initialize(access_token:, base_url: "https://api.duffel.com")
-      @api_service = APIService.new(base_url, access_token, default_options)
+      @api_service = APIService.new(base_url, access_token, **default_options)
     end
 
+    # @return [Services::AircraftService]
     def aircraft
       @aircraft ||= Services::AircraftService.new(@api_service)
     end
 
+    # @return [Services::AirlinesService]
     def airlines
       @airlines ||= Services::AirlinesService.new(@api_service)
     end
 
+    # @return [Services::AirportsService]
     def airports
       @airports ||= Services::AirportsService.new(@api_service)
     end
 
+    # @return [Services::OfferPassengersService]
     def offer_passengers
       @offer_passengers ||= Services::OfferPassengersService.new(@api_service)
     end
 
+    # @return [Services::OfferRequestsService]
     def offer_requests
       @offer_requests ||= Services::OfferRequestsService.new(@api_service)
     end
 
+    # @return [Services::OffersService]
     def offers
       @offers ||= Services::OffersService.new(@api_service)
     end
 
+    # @return [Services::OrderCancellationsService]
     def order_cancellations
       @order_cancellations ||= Services::OrderCancellationsService.new(@api_service)
     end
 
+    # @return [Services::OrderChangeOffersService]
     def order_change_offers
       @order_change_offers ||= Services::OrderChangeOffersService.new(@api_service)
     end
 
+    # @return [Services::OrderChangeRequestsService]
     def order_change_requests
       @order_change_requests ||= Services::OrderChangeRequestsService.new(@api_service)
     end
 
+    # @return [Services::OrderChangesService]
     def order_changes
       @order_changes ||= Services::OrderChangesService.new(@api_service)
     end
 
+    # @return [Services::OrdersService]
     def orders
       @orders ||= Services::OrdersService.new(@api_service)
     end
 
+    # @return [Services::PaymentIntentsService]
     def payment_intents
       @payment_intents ||= Services::PaymentIntentsService.new(@api_service)
     end
 
+    # @return [Services::PaymentsService]
     def payments
       @payments ||= Services::PaymentsService.new(@api_service)
     end
 
+    # @return [Services::RefundsService]
     def refunds
       @refunds ||= Services::RefundsService.new(@api_service)
     end
 
+    # @return [Services::SeatMapsService]
     def seat_maps
       @seat_maps ||= Services::SeatMapsService.new(@api_service)
     end
 
+    # @return [Services::WebhooksService]
     def webhooks
       @webhooks ||= Services::WebhooksService.new(@api_service)
     end

data/lib/duffel_api/errors/error.rb

@@ -5,6 +5,14 @@ module DuffelAPI
     class Error < StandardError
       attr_reader :error
 
+      # Builds an error, which provides access to the raw response. In general,
+      # subclasses of this error (e.g. `APIError`) will be raised, apart from
+      # for unrecognised errors returned by the Duffel API or errors that don't
+      # look like standardised Duffel API errors.
+      #
+      # @param error [Hash] the parsed error data from the API
+      # @param response [APIResponse, nil]
+      # @return [Error]
       def initialize(error, response = nil)
         raise ArgumentError, "Duffel errors expect a hash" unless error.is_a?(Hash)
 
@@ -14,38 +22,73 @@ module DuffelAPI
         super(error)
       end
 
+      # Returns a URL where documentation about the error can be found. This can be
+      # `nil` for errors that don't look like standardised Duffel errors (e.g. errors
+      # returned by the load balancer rather than the API itself).
+      #
+      # @return [String, nil]
       def documentation_url
         @error["documentation_url"]
       end
 
+      # Returns the title associated with the error. This can be `nil` for errors that
+      # don't look like standardised Duffel errors (e.g. errors returned by the load
+      # balancer rather than the API itself).
+      #
+      # @return [String, nil]
       def title
         @error["title"]
       end
 
+      # Return the message associated with the error
+      #
+      # @return [String]
       def message
         @error["message"]
       end
 
+      # Returns a string representation of the error, taken from its `#message`
+      #
+      # @return [String]
       def to_s
         @error["message"]
       end
 
+      # Returns the type of the error. See the Duffel API reference for possible values.
+      # This can be `nil` for errors that don't look like standardised Duffel errors
+      # (e.g. errors returned by the load balancer rather than the API itself).
+      #
+      # @return [String, nil]
       def type
         @error["type"]
       end
 
+      # Returns the code of the error. See the Duffel API reference for possible values.
+      # This can be `nil` for errors that don't look like standardised Duffel errors
+      # (e.g. errors returned by the load balancer rather than the API itself).
+      #
+      # @return [String, nil]
       def code
         @error["code"]
       end
 
+      # Returns the request ID of the request that generated the error.
+      #
+      # @return [String]
       def request_id
-        @error["request_id"]
+        api_response.request_id
       end
 
+      # Return s the source of the error.
+      #
+      # @return [Hash, nil]
       def source
         @error["source"]
       end
 
+      # Returns the raw API response where this error originated from
+      #
+      # @return [APIResponse]
       def api_response
         APIResponse.new(@response)
       end

data/lib/duffel_api/list_response.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module DuffelAPI
+  # A page of results returned by a "list" action in the API, provides access to the
+  # records on the page, and metadata about the page itself.
   class ListResponse
+    # Returns the records contained within the page
+    #
+    # @return [Array<Resources::BaseResource>] an array of records - for example, for the
+    #   list action for offers, this would be a list of `Resources::Offer`s
     attr_reader :records
 
     def initialize(options = {})
@@ -12,14 +18,25 @@ module DuffelAPI
       @records = @unenveloped_body.map { |item| @resource_class.new(item, @response) }
     end
 
+    # Returns the raw API response received for this listing request
+    #
+    # @return [APIResponse]
     def api_response
       @api_response ||= APIResponse.new(@response)
     end
 
+    # Returns the cursor representing the previous page of paginated results, if there is
+    # a previous page
+    #
+    # @return [String, nil]
     def before
       @response.parsed_body["meta"]["before"]
     end
 
+    # Returns the cursor representing the next page of paginated results, if there is
+    # a next page
+    #
+    # @return [String, nil]
     def after
       @response.parsed_body["meta"]["after"]
     end

data/lib/duffel_api/middlewares/raise_duffel_errors.rb

@@ -4,11 +4,14 @@ require "faraday"
 
 module DuffelAPI
   module Middlewares
-    class RaiseDuffelErrors < Faraday::Response::Middleware
+    class RaiseDuffelErrors < Faraday::Middleware
       UNEXPECTED_ERROR_STATUSES = (501..599).freeze
       EXPECTED_ERROR_STATUSES = (400..500).freeze
 
       # rubocop:disable Metrics/AbcSize
+      # Handles a completed (Faraday) request and raises an error, if appropriate
+      #
+      # @param [Faraday::Env] env
       def on_complete(env)
         if !json?(env) || UNEXPECTED_ERROR_STATUSES.include?(env.status)
           response = Response.new(env.response)
@@ -31,6 +34,11 @@ module DuffelAPI
 
       private
 
+      # Picks the correct error class to use for an error returned by the Duffel API
+      # based on its type
+      #
+      # @param type [Atom] the type returned by the API
+      # @return [Errors::Error]
       def error_class_for_type(type)
         {
           airline_error: DuffelAPI::Errors::AirlineError,
@@ -43,16 +51,24 @@ module DuffelAPI
         }.fetch(type.to_sym) || DuffelAPI::Errors::Error
       end
 
+      # Generates error data - specifically a message - based on the `Faraday::Env` for
+      # non-standard Duffel errors
+      #
+      # @param env [Faraday::Env]
+      # @return [Hash]
       def generate_error_data(env)
         {
           "message" => "Something went wrong with this request\n" \
                        "Code: #{env.status}\n" \
                        "Headers: #{env.response_headers}\n" \
                        "Body: #{env.body}",
-          "code" => env.status,
         }
       end
 
+      # Works out if the response is a JSON response based on the `Faraday::Env`
+      #
+      # @param env [Faraday::Env]
+      # @return [Boolean]
       def json?(env)
         content_type = env.response_headers["Content-Type"] ||
           env.response_headers["content-type"] || ""

data/lib/duffel_api/paginator.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
 module DuffelAPI
+  # An internal class used within the library to paginated automatically thruogh results
+  # from list actions that can be spread over multiple pages
   class Paginator
-    def initialize(options = {})
-      @service = options.fetch(:service)
-      @options = options.fetch(:options)
+    # @param service [Services::BaseService] a service which implements `#list`
+    # @param options [Hash] the options originally passed to `#all`
+    def initialize(service:, options:)
+      @service = service
+      @options = options
     end
 
+    # Returns an enumerator that is able to automatically cycle through paginated data
+    # returned by the API
+    #
+    # @return [Enumerator]
     def enumerator
       response = @service.list(@options)