duffel_api 0.0.1.pre.dev → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e564fc3ef58a41bd22d8cd9f16e5f81adc6c84f795fd48b969e2b5abbc947df9
-  data.tar.gz: 12bee5c0d8e169e26f0e253e47194e299afd743ab9601cf3c89744f46407f53d
+  metadata.gz: bb4caaadd883236526bb2e8bdbc78b4f96f2264ae3a09f0c6b2d645eb0e63b4f
+  data.tar.gz: 81a190fbc71c4b5033647393634e0759fdc18513809c1f81fa80dc2ca2453a44
 SHA512:
-  metadata.gz: 58813b477f7a9877471d4a2f77ad19d9c1bbd3a1e665394bf87903d5402341f644cb55dd177424abb51400d6ba1218698527d72f1ac9cbe8d5e7da4993b71b18
-  data.tar.gz: 995b3113fea6d0a25de8fa545d34eae59f8818c12462a6719a23a278064db72deae3c39948f57aa1bf832989d0e322e86deacfd1d3bd76a0b5f80a916bffa0d9
+  metadata.gz: 70950a1db91a40ba7fbc1fe2b0b232f8553ab16c497225641ca13d4244374efc9c8b5d80174477e2ab8c3dedd085ea99abc71bdc2159c3af4083ebeab9ac35f6
+  data.tar.gz: 4686727e0c4e1d005713b44e684f91fa931f73d214a778fad5b2cb83724d5592b4d4aace1810f95d9c544d92d37a62eb903af9a4d2765d18ad9ad14a1a5d2fac

data/.circleci/config.yml

@@ -0,0 +1,82 @@
+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

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

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rubocop.yml

@@ -1,13 +1,13 @@
+require: rubocop-rake
+
+inherit_gem:
+  gc_ruboconfig: rubocop.yml
 AllCops:
   TargetRubyVersion: 2.6
+  NewCops: enable
 
-Style/StringLiterals:
-  Enabled: true
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  Enabled: true
-  EnforcedStyle: double_quotes
+RSpec/ExampleLength:
+  Enabled: false
 
-Layout/LineLength:
-  Max: 120
+RSpec/MultipleExpectations:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,3 @@
-## [Unreleased]
-
-## [0.0.1-dev] - 2021-12-07
+## [0.1.0] - 2021-12-31
 
 - Initial release

data/CODE_OF_CONDUCT.md

@@ -39,7 +39,7 @@ This Code of Conduct applies within all community spaces, and also applies when
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at sasha@duffel.com. All complaints will be reviewed and investigated promptly and fairly.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at tim@duffel.com. All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the reporter of any incident.
 

data/Gemfile

@@ -2,10 +2,18 @@
 
 source "https://rubygems.org"
 
+# Specify your gem's dependencies in duffel_api.gemspec
 gemspec
 
 group :development, :test do
+  gem "gc_ruboconfig", "~> 2.29.0"
+  gem "pry", "~> 0.14.1"
   gem "rake", "~> 13.0"
-  gem "rspec", "~> 3.0"
-  gem "rubocop", "~> 1.21"
+  gem "rspec", "~> 3.10.0"
+  gem "rspec-its", "~> 1.3.0"
+  gem "rspec_junit_formatter", "~> 0.4.1"
+  gem "rubocop", "~> 1.24.0"
+  gem "rubocop-rake", "~> 0.6.0"
+  gem "simplecov", "~> 0.21.2"
+  gem "webmock", "~> 3.14.0"
 end

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021 Duffel
+Copyright (c) 2021 Duffel Technology Ltd
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,55 +1,212 @@
-# DuffelAPI
+# Duffel API Ruby client library
 
-A Ruby client library for the [Duffel API](https://duffel.com/docs/api)
-(currently in `beta`).
+A Ruby client library for the [Duffel API](https://duffel.com/docs/api).
+
+## Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+
+## Requirements
+
+* Ruby 2.6 or later
+* A Duffel API access token (get started [here](https://duffel.com/docs/guides/quick-start) ✨)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+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'
+gem "duffel_api", "~> 0.1.0"
 ```
 
-And then execute:
+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`.
+
+## Usage
 
-    $ bundle install
+You can see a complete end-to-end example of searching and booking using the client library in [`example/search_and_book.rb`](https://github.com/duffelhq/duffel-api-ruby/blob/main/examples/search_and_book.rb).
 
-Or install it yourself as:
+### Initialising the client
 
-    $ gem install duffel_api
+All of the library's functionality is accessed from a `DuffelAPI::Client` instance.
 
-## Usage
+To initialise a `DuffelAPI::Client`, all you'll need is your API access token:
+
+```ruby
+require "duffel_api"
+
+client = DuffelAPI::Client.new(access_token: "duffel_test_000000000")
+```
+
+### Resources in the Duffel API
+
+In this readme, we'll use the term "resources" to refer to the different Duffel concepts that you can *act on* in the API - for example airports, offers, orders and payment intents.
+
+We'll refer to instances of each of these resources - an airport, an offer, a payment intent - as "records".
+
+In the [Duffel API reference](https://duffel.com/docs/api/), the resources are listed in the sidebar. For each resource, you'll find:
+
+* a schema, which describes the data attributes we expose for each record from this resource
+* a list of actions you can perform related to that resource (e.g. for [Orders](https://duffel.com/docs/api/orders), you can "Get a single order", "Update a single order", "List orders" and "Create an order")
+
+The Ruby client library is structured around these resources. Each resource has its own "service" which you use to perform actions. These services are accessible from your `Client` instance:
+
+```ruby
+client.orders
+client.offers
+client.payment_intents
+```
+
+__To see what actions are available for each resource, check out the definitions for the service classes [here](https://github.com/duffelhq/duffel-api-ruby/tree/main/lib/duffel_api/services).__
+
+### Creating a record
+
+Most resources allow you to create a record. In fact, the most important flows in the Duffel API start with creating a record. You'll do this with the `#create` method exposed on a service.
+
+For example, you'll search for flights by creating an offer request:
+
+```ruby
+offer_request = client.offer_requests.create(params: {
+  cabin_class: "economy",
+  passengers: [{
+    age: 28
+  }],
+  slices: [{
+    origin: "LHR",
+    destination: "NYC",
+    departure_date: "2022-12-31"
+  }],
+  # 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 "You've created an offer request, #{offer_request.id}."
+```
+
+The `#create` method returns the created record.
+
+### Listing records
+
+Many resources in the Duffel API (e.g. airports, orders and offers) allow you to list their records.
+
+For example, you can get a list of all the airports that Duffel knows about - that is, a list of airport records.
+
+For performance reasons, we [paginate](https://duffel.com/docs/api/overview/pagination) records in the API when listing. You can only see up to 200 at a time. You'll need to page through, like moving through pages of a book.
+
+This is quite fiddly, so the client library does it for you in the `#all` method exposed by relevant services. All you have to do is something like this:
+
+```ruby
+client.offer_requests.all.each do |offer_request|
+  puts "Loaded offer request #{order_request.id}"
+end
+```
+
+Sometimes, you'll want to specify filters or sort orders when listing,like this:
+
+```ruby
+# The filters you can use for a given resource are documented in the API Reference
+client.offers.
+  all(params: { offer_request_id: "ofr_123", sort: "total_amount" }).
+  each do |order|
+    puts "Loaded order #{order.id}"
+  end
+```
+
+A call to `#all` returns a Ruby [`Enumerator`](https://ruby-doc.org/core-2.6/Enumerator.html), which behaves a lot like an array - you can get the number of records with `#length`, loop through it with `#each`, etc.
+
+If you prefer, you can also page through records manually using a service's `#list` method (e.g. `client.orders.list`) which returns a `DuffelAPI::ListResponse`. 
+
+The records in the page are returned by `#records` (`client.orders.list.records`) and the cursor for the next page (if there is one) can be found with `#after` (`client.orders.list.after`)
+
+#### An exception: seat maps
+
+Watch out! There is one kind of list in the Duffel API which isn't paginated: seat maps.
+
+When you call `client.seat_maps.list(params: { offer_id: "off_123" })`, all of the seat maps will be returned at once in a single `ListResponse`.
+
+### Fetching single records
+
+Many resources in the Duffel API allow you fetch a single record (e.g. *an* airport, *a* payment intent) if you know its ID.
+
+You do that using the `#get` method on a resource like this:
+
+```ruby
+order = client.orders.get("ord_123")
+puts "Your booking reference is #{order.booking_reference}."
+```
+
+The `#get` method returns the record.
+
+### Updating a record
+
+Some records in the Duffel API allow you to update them after they've been created, if you know their ID.
+
+That works like this using the `#update` method on a resource:
+
+```ruby
+client.webhooks.update("sev_0000AEdmUJKCvFK45qMFBg", params: {
+  active: false
+})
+```
+
+The `#update` method returns the updated record.
+
+### Performing an action on a record
+
+Some resources allow you to perform special actions on their records - for example confirming an order cancellation or pinging a webhook.
+
+The methods you'll use to do this aren't named consistently, because each resource has different actions. For example, you'll call `#confirm` to confirm an order cancellation but `#ping` to ping a webhook.
+
+It'll look a bit like this:
+
+```ruby
+client.order_cancellations.confirm("ore_0000AEUvjGoJlav2j6FDlZ")
+```
+
+Sometimes, you'll need to pass extra data when performing the action. That works like this:
+
+```ruby
+client.order_changes.confirm("oce_0000AEdlOBVlABkDhgsUqW", params: {
+  payment: {
+    type: "balance",
+    currency: "GBP",
+    amount: "125.00",
+  }
+})
+```
+
+In general, these action methods return the record you've acted on.
+
+#### An exception: pinging a webhook
+
+Watch out! There is one action in the API which doesn't return the record you've acted on.
+
+When you ping a webhook with `client.webhooks.ping("sev_0000AEdmUJKCvFK45qMFBg")`, it'll return a `DuffelAPI::Services::WebhooksService::PingResult` if successful, or otherwise it'll raise an error.
+
+### Handling errors
+
+When the Duffel API returns an error, the library will raise an exception.
+
+We have an exception class for each of the possible `type`s of error which the API can return, documented [here](https://duffel.com/docs/api/overview/errors) in the API reference. For example, if the API returns an error with `type` `invalid_state_error`, the library will raise a `DuffelAPI::Errors::InvalidStateError` exception.
 
-TODO: Write usage instructions here
+You can find all of those error classes [here](https://github.com/duffelhq/duffel-api-ruby/tree/main/lib/duffel_api/errors).
 
-## Development
+You can rescue all of these errors and get important information with them using instances methods: `#message`, `#title`, `#code`, `#request_id`, etc.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake spec` to run the tests. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment.
+If the client library is unable to connect to Duffel, an appropriate exception will be raised, for example:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To
-release a new version, update the version number in `version.rb`, and then run
-`bundle exec rake release`, which will create a git tag for the version, push
-git commits and the created tag, and push the `.gem` file to
-[rubygems.org](https://rubygems.org).
+* `Faraday::TimeoutError` in case of a timeout
+* `Faraday::ConnectionFailed` in case of a connection issue (e.g. problems with DNS resolution)
+* `DuffelAPI::Errors::Error` for `5XX` errors returned from by Duffel's infrastructure, but not by the API itself (e.g. a load balancer)
 
-## Contributing
+### Accessing the raw API response
 
-Bug reports and pull requests are welcome on GitHub at
-https://github.com/duffelhq/duffel-api-ruby. This project is intended to be a safe,
-welcoming space for collaboration, and contributors are expected to adhere to
-the [code of
-conduct](https://github.com/sgerrand/duffel_api/blob/main/CODE_OF_CONDUCT.md).
+Sometimes, you might want to get lower-level details about the response you received from the Duffel API - for example the raw body or headers.
 
-## License
+If an error has been raised, you can call `#api_response` on the exception, which returns a `DuffelAPI::APIResponse`. If you're looking at a `ListResponse` or any resource, you can call `#api_response` on that.
 
-The gem is available as open source under the terms of the [MIT
-License](https://opensource.org/licenses/MIT).
+From the `APIResponse`, you can call `#headers`, `#status_code`, `#raw_body`, `#parsed_body`, `#meta` or `#request_id` to get key information from the response.
 
-## Code of Conduct
 
-Everyone interacting in the Ruby Duffel API project's codebases, issue trackers,
-chat rooms and mailing lists is expected to follow the [code of
-conduct](https://github.com/duffelhq/duffel-api-ruby/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
+require "rubocop/rake_task"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
-
-require "rubocop/rake_task"
-
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]

data/bin/console

@@ -4,5 +4,12 @@
 require "bundler/setup"
 require "duffel_api"
 
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
 require "irb"
 IRB.start(__FILE__)

data/bin/setup

@@ -4,3 +4,5 @@ IFS=$'\n\t'
 set -vx
 
 bundle install
+
+# Do any other automated setup that you need to do here

data/duffel_api.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/duffel_api/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "duffel_api"
+  spec.version       = DuffelAPI::VERSION
+  spec.authors       = ["The Duffel team"]
+  spec.email         = ["help@duffel.com"]
+
+  spec.summary       = "A Ruby client for interacting with the Duffel API"
+  spec.homepage      = "https://github.com/duffelhq/duffel-api-ruby"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "https://github.com/duffelhq/duffel-api-ruby/blob/main/CHANGELOG.md"
+
+  # 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)/}) }
+  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"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+  spec.metadata = {
+    "rubygems_mfa_required" => "true",
+  }
+end

data/examples/book_and_change.rb

@@ -0,0 +1,106 @@
+# 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: "LHR",
+    destination: "STN",
+    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"
+
+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}"
+
+order = client.orders.create(params: {
+  selected_offers: [priced_offer.id],
+  payments: [
+    {
+      type: "balance",
+      amount: priced_offer.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}"
+
+order_change_request = client.order_change_requests.create(params: {
+  order_id: order.id,
+  slices: {
+    add: [{
+      cabin_class: "economy",
+      departure_date: "2022-12-25",
+      origin: "LHR",
+      destination: "STN",
+    }],
+    remove: [{
+      slice_id: order.slices.first["id"],
+    }],
+  },
+})
+
+order_change_offers = client.order_change_offers.
+  all(params: { order_change_request_id: order_change_request.id })
+
+puts "Got #{order_change_offers.count} options for changing the order; picking first " \
+     "option"
+
+order_change = client.order_changes.create(params: {
+  selected_order_change_offer: order_change_offers.first.id,
+  order_id: order.id,
+})
+
+puts "Created order change #{order_change.id}, confirming..."
+
+client.order_changes.confirm(order_change.id, params: {
+  payment: {
+    type: "balance",
+    amount: order_change.change_total_amount,
+    currency: order_change.change_total_currency,
+  },
+})
+
+puts "Processed change to order #{order.id} costing " \
+     "#{order_change.change_total_amount} #{order_change.change_total_currency}"