duffel_api 0.1.0 → 0.2.0

data/lib/duffel_api/services/order_change_offers_service.rb

@@ -3,6 +3,12 @@
 module DuffelAPI
   module Services
     class OrderChangeOffersService < BaseService
+      # Lists order change offers, returning a single page of results.
+      #
+      # @option [Hash] :params Parameters to include in the HTTP querystring, including
+      #   any filters
+      # @return [ListResponse]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def list(options = {})
         path = "/air/order_change_offers"
 
@@ -15,6 +21,13 @@ module DuffelAPI
         )
       end
 
+      # Returns an `Enumerator` which can automatically cycle through multiple
+      # pages of `Resources;:OrderChangeOffer`s
+      #
+      # @param options [Hash] options passed to `#list`, for example `:params` to
+      #   send an HTTP querystring with filters
+      # @return [Enumerator]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def all(options = {})
         Paginator.new(
           service: self,
@@ -22,6 +35,11 @@ module DuffelAPI
         ).enumerator
       end
 
+      # Retrieves a single order change offer by ID
+      #
+      # @param id [String]
+      # @return [Resources::OrderChangeOffer]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/air/order_change_offers/:id", "id" => id)
 

data/lib/duffel_api/services/order_change_requests_service.rb

@@ -3,6 +3,12 @@
 module DuffelAPI
   module Services
     class OrderChangeRequestsService < BaseService
+      # Creates an order change request
+      #
+      # @option [required, Hash] :params the payload for creating the order change
+      #  request
+      # @return [Resources::OrderChangeRequest]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def create(options = {})
         path = "/air/order_change_requests"
 
@@ -23,6 +29,11 @@ module DuffelAPI
         Resources::OrderChangeRequest.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Retrieves a single order change request by ID
+      #
+      # @param id [String]
+      # @return [Resources::OrderChangeRequest]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/air/order_change_requests/:id", "id" => id)
 

data/lib/duffel_api/services/order_changes_service.rb

@@ -3,6 +3,11 @@
 module DuffelAPI
   module Services
     class OrderChangesService < BaseService
+      # Creates an order chnage
+      #
+      # @option [required, Hash] :params the payload for creating the order change
+      # @return [Resources::OrderChange]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def create(options = {})
         path = "/air/order_changes"
 
@@ -22,6 +27,13 @@ module DuffelAPI
         Resources::OrderChange.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Confirms an order change by ID, passing across extra data required for
+      #   confirmation
+      #
+      # @param id [String]
+      # @option [required, Hash] :params
+      # @return [Resources::OrderChange] the payload for confirming the order change
+      # @raise [Errors::Error] when the Duffel API returns an error
       def confirm(id, options = {})
         path = substitute_url_pattern("/air/order_changes/:id/actions/confirm",
                                       "id" => id)
@@ -42,6 +54,11 @@ module DuffelAPI
         Resources::OrderChange.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Retrieves a single order change by ID
+      #
+      # @param id [String]
+      # @return [Resources::OrderChange]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/air/order_changes/:id", "id" => id)
 

data/lib/duffel_api/services/orders_service.rb

@@ -3,6 +3,11 @@
 module DuffelAPI
   module Services
     class OrdersService < BaseService
+      # Creates an order
+      #
+      # @option [required, Hash] :params the payload for creating the order
+      # @return [Resources::Order]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def create(options = {})
         path = "/air/orders"
 
@@ -22,6 +27,11 @@ module DuffelAPI
         Resources::Order.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Updates an order
+      #
+      # @option [required, Hash] :params the payload for updating the order
+      # @return [Resources::Order]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def update(id, options = {})
         path = substitute_url_pattern("/air/orders/:id", "id" => id)
 
@@ -41,6 +51,12 @@ module DuffelAPI
         Resources::Order.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Lists orders, returning a single page of results.
+      #
+      # @option [Hash] :params Parameters to include in the HTTP querystring, including
+      #   any filters
+      # @return [ListResponse]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def list(options = {})
         path = "/air/orders"
 
@@ -53,6 +69,13 @@ module DuffelAPI
         )
       end
 
+      # Returns an `Enumerator` which can automatically cycle through multiple
+      # pages of `Resources;:Order`s
+      #
+      # @param options [Hash] options passed to `#list`, for example `:params` to
+      #   send an HTTP querystring with filters
+      # @return [Enumerator]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def all(options = {})
         Paginator.new(
           service: self,
@@ -60,6 +83,11 @@ module DuffelAPI
         ).enumerator
       end
 
+      # Retrieves a single order by ID
+      #
+      # @param id [String]
+      # @return [Resources::Order]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/air/orders/:id", "id" => id)
 

data/lib/duffel_api/services/payment_intents_service.rb

@@ -3,6 +3,11 @@
 module DuffelAPI
   module Services
     class PaymentIntentsService < BaseService
+      # Creates an payment intent
+      #
+      # @option [required, Hash] :params the payload for creating the payment intent
+      # @return [Resources::PaymentIntent]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def create(options = {})
         path = "/payments/payment_intents"
 
@@ -22,6 +27,11 @@ module DuffelAPI
         Resources::PaymentIntent.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Confirms a payment intent by ID
+      #
+      # @param id [String]
+      # @return [Resources::PaymentIntent]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def confirm(id, options = {})
         path = substitute_url_pattern("/payments/payment_intents/:id/actions/confirm",
                                       "id" => id)
@@ -42,6 +52,11 @@ module DuffelAPI
         Resources::PaymentIntent.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Retrieves a single payment intent by ID
+      #
+      # @param id [String]
+      # @return [Resources::PaymentIntent]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/payments/payment_intents/:id", "id" => id)
 

data/lib/duffel_api/services/payments_service.rb

@@ -3,6 +3,11 @@
 module DuffelAPI
   module Services
     class PaymentsService < BaseService
+      # Creates an payment
+      #
+      # @option [required, Hash] :params the payload for creating the payment
+      # @return [Resources::Payment]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def create(options = {})
         path = "/air/payments"
 

data/lib/duffel_api/services/refunds_service.rb

@@ -3,6 +3,11 @@
 module DuffelAPI
   module Services
     class RefundsService < BaseService
+      # Creates a refund
+      #
+      # @option [required, Hash] :params the payload for creating the refund
+      # @return [Resources::Refund]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def create(options = {})
         path = "/payments/refunds"
 
@@ -22,6 +27,11 @@ module DuffelAPI
         Resources::Refund.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Retrieves a single refund by ID
+      #
+      # @param id [String]
+      # @return [Resources::Refund]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def get(id, options = {})
         path = substitute_url_pattern("/payments/refunds/:id", "id" => id)
 

data/lib/duffel_api/services/seat_maps_service.rb

@@ -3,6 +3,12 @@
 module DuffelAPI
   module Services
     class SeatMapsService < BaseService
+      # Lists all seat maps for an offer. This data is __not__ paginated.
+      #
+      # @option [Hash] :params Parameters to include in the HTTP querystring, including
+      #   any filters
+      # @return [ListResponse]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def list(options = {})
         path = "/air/seat_maps"
 

data/lib/duffel_api/services/webhooks_service.rb

@@ -4,19 +4,29 @@ module DuffelAPI
   module Services
     class WebhooksService < BaseService
       class PingResult
+        # Returns the raw API response this resource originated from
+        #
+        # @return [APIResponse]
         attr_reader :api_response
 
         def initialize(api_response)
           @api_response = api_response
         end
 
-        # If we return a `PingResult` rather than an error, then that means that the
-        # action was successful.
+        # Returns whether the ping was successful. This is always true, because if the
+        # ping fails, we raise an error.
+        #
+        # @return [Boolean]
         def succeeded
           true
         end
       end
 
+      # Creates an webhook
+      #
+      # @option [required, Hash] :params the payload for creating the webhook
+      # @return [Resources::Webhook]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def create(options = {})
         path = "/air/webhooks"
 
@@ -36,6 +46,12 @@ module DuffelAPI
         Resources::Webhook.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Updates a webhook by ID
+      #
+      # @param id [String]
+      # @option [required, Hash] :params the payload for updating the webhook
+      # @return [Resources::Webhook]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def update(id, options = {})
         path = substitute_url_pattern("/air/webhooks/:id", "id" => id)
 
@@ -55,6 +71,11 @@ module DuffelAPI
         Resources::Webhook.new(unenvelope_body(response.parsed_body), response)
       end
 
+      # Pings a webhook by ID
+      #
+      # @param id [String]
+      # @return [PingResult]
+      # @raise [Errors::Error] when the Duffel API returns an error
       def ping(id, options = {})
         path = substitute_url_pattern("/air/webhooks/:id/actions/ping", "id" => id)
 

data/lib/duffel_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DuffelAPI
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/duffel_api/webhook_event.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "base16"
+require "openssl"
+
+module DuffelAPI
+  module WebhookEvent
+    # An exception raised internally within the library - but not exposed - if the
+    # webhook signature provided does not match the format of a valid signature
+    class InvalidRequestSignatureError < StandardError; end
+
+    SIGNATURE_REGEXP = /\At=(.+),v1=(.+)\z/.freeze
+
+    SHA_256 = OpenSSL::Digest.new("sha256")
+
+    class << self
+      # Checks if a webhook event you received was a genuine webhook event from Duffel by
+      # checking that it was signed with your shared secret.
+      #
+      # Assuming that you've kept that secret secure and only shared it with Duffel,
+      # this can give you confidence that a webhook event was genuinely sent by Duffel.
+      #
+      # @param request_body [String] The raw body of the received request
+      # @param request_signature [String] The signature provided with the received
+      #   request, found in the `X-Duffel-Signature` request header
+      # @param webhook_secret [String] The secret of the webhook, registered with Duffel
+      # @return [Boolean] whether the webhook signature matches
+      def genuine?(request_body:, request_signature:, webhook_secret:)
+        parsed_signature = parse_signature!(request_signature)
+
+        calculated_hmac = calculate_hmac(
+          payload: request_body,
+          secret: webhook_secret,
+          timestamp: parsed_signature[:timestamp],
+        )
+
+        secure_compare(calculated_hmac, parsed_signature[:v1])
+      rescue InvalidRequestSignatureError
+        # If the signature doesn't even look like a valid one, then the webhook
+        # event can't be genuine
+        false
+      end
+
+      private
+
+      # Calculates the signature for a request body in the same way that the Duffel API
+      # does it
+      #
+      # @param secret [String]
+      # @param payload [String]
+      # @param timestamp [String]
+      # @return [String]
+      def calculate_hmac(secret:, payload:, timestamp:)
+        signed_payload = %(#{timestamp}.#{payload})
+        Base16.encode16(OpenSSL::HMAC.digest(SHA_256, secret,
+                                             signed_payload)).strip.downcase
+      end
+
+      # Parses a webhook signature and extracts the `v1` and `timestamp` values, if
+      # available.
+      #
+      # @param signature [String] A webhook event signature received in a request
+      # @return [Hash]
+      # @raise InvalidRequestSignatureError when the signature isn't valid
+      def parse_signature!(signature)
+        matches = signature.match(SIGNATURE_REGEXP)
+
+        if matches
+          {
+            v1: matches[2],
+            timestamp: matches[1],
+          }
+        else
+          raise InvalidRequestSignatureError
+        end
+      end
+
+      # Taken from `Rack::Utils`
+      # (<https://github.com/rack/rack/blob/03b4b9708f375db46ee214b219f709d08ed6eeb0/lib/rack/utils.rb#L371-L393>).
+      #
+      # Licensed under the MIT License
+      # (<https://github.com/rack/rack/blob/master/MIT-LICENSE>).
+      if defined?(OpenSSL.fixed_length_secure_compare)
+        # Checks if two strings are equal, performing a constant time string comparison
+        # resistant to timing attacks.
+        #
+        # @param a [String]
+        # @param b [String]
+        # @return [Boolean] whether the two strings are equal
+        # rubocop:disable Naming/MethodParameterName
+        def secure_compare(a, b)
+          # rubocop:enable Naming/MethodParameterName
+          return false unless a.bytesize == b.bytesize
+
+          OpenSSL.fixed_length_secure_compare(a, b)
+        end
+      else
+        # Checks if two strings are equal, performing a constant time string comparison
+        # resistant to timing attacks.
+        #
+        # @param [String] a
+        # @param [String] b
+        # @return [Boolean] whether the two strings are equal
+        # rubocop:disable Naming/MethodParameterName
+        def secure_compare(a, b)
+          # rubocop:enable Naming/MethodParameterName
+          return false unless a.bytesize == b.bytesize
+
+          l = a.unpack("C*")
+
+          r = 0
+          i = -1
+          b.each_byte { |v| r |= v ^ l[i += 1] }
+          r.zero?
+        end
+      end
+    end
+  end
+end

data/lib/duffel_api.rb

@@ -51,5 +51,6 @@ require_relative "duffel_api/client"
 require_relative "duffel_api/list_response"
 require_relative "duffel_api/request"
 require_relative "duffel_api/response"
+require_relative "duffel_api/webhook_event"
 
 module DuffelAPI; end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: duffel_api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - The Duffel team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-12-31 00:00:00.000000000 Z
+date: 2022-01-11 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base16
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.2
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -19,7 +33,7 @@ dependencies:
         version: 0.9.2
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +43,21 @@ dependencies:
         version: 0.9.2
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 description:
 email:
 - help@duffel.com
@@ -37,11 +65,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".circleci/config.yml"
-- ".github/dependabot.yml"
+- ".DS_Store"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
+- Appraisals
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -52,6 +80,7 @@ files:
 - bin/setup
 - duffel_api.gemspec
 - examples/book_and_change.rb
+- examples/book_with_extra_baggage.rb
 - examples/book_with_seat.rb
 - examples/exploring_data.rb
 - examples/hold_and_pay_later.rb
@@ -108,6 +137,7 @@ files:
 - lib/duffel_api/services/seat_maps_service.rb
 - lib/duffel_api/services/webhooks_service.rb
 - lib/duffel_api/version.rb
+- lib/duffel_api/webhook_event.rb
 homepage: https://github.com/duffelhq/duffel-api-ruby
 licenses:
 - MIT

data/.circleci/config.yml

@@ -1,82 +0,0 @@
-version: 2.1
-
-commands:
-  setup_ruby:
-    steps:
-      - run:
-          name: Install bundler gem
-          command: gem install bundler --version '~> 2.2'
-      - run:
-          name: Install Ruby dependencies
-          command: bundle check || bundle install
-
-executors:
-  ruby:
-    parameters:
-      image:
-        default: "cimg/ruby:3.0"
-        type: string
-    docker:
-      - image: << parameters.image >>
-    resource_class: small
-
-orbs:
-  ruby: circleci/ruby@1.2
- 
-jobs:
-  test:
-    parameters:
-      ruby-image:
-        type: string
-    executor:
-      name: ruby
-      image: << parameters.ruby-image >>
-    steps:
-      - checkout
-      - setup_ruby
-      - ruby/rubocop-check
-      - ruby/rspec-test
-  coverage:
-    executor: ruby
-    environment:
-      COVERAGE: true
-    steps:
-      - checkout
-      - setup_ruby
-      - run:
-          name: Run tests with Simplecov enabled
-          command: bundle exec rspec spec
-      - store_artifacts:
-          path: coverage
-  code_examples:
-    executor: ruby
-    steps:
-      - checkout
-      - setup_ruby
-      - run:
-          name: Run "search and book" example
-          command: bundle exec ruby examples/search_and_book.rb
-      - run:
-          name: Run "hold and pay later" example
-          command: bundle exec ruby examples/hold_and_pay_later.rb
-      - run:
-          name: Run "exploring data" example
-          command: bundle exec ruby examples/exploring_data.rb
-      - run:
-          name: Run "book with seat" example
-          command: bundle exec ruby examples/book_with_seat.rb
-      - run:
-          name: Run "book and change" example
-          command: bundle exec ruby examples/book_and_change.rb
-workflows:
-  version: 2
-  build_and_test:
-    jobs:
-      - test:
-          matrix:
-            parameters:
-              ruby-image: ["cimg/ruby:2.6", "cimg/ruby:2.7", "cimg/ruby:3.0", "cimg/ruby:3.1"]
-      - coverage
-      - code_examples:
-          requires:
-            - test

data/.github/dependabot.yml

@@ -1,6 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: "bundler"
-    directory: "/"
-    schedule:
-      interval: "daily"