onfido 0.12.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 8db5e90cf91e9eebbeed0ecb56e8e2940c430fa8ea742a5eef3959bafa3cec16
-  data.tar.gz: 995f57f45b8c0109499b8167edf6ecc6b9212c5c0391676338ef3f23e5539361
+SHA1:
+  metadata.gz: 8749aa43cbc394686f1ff769f0b0ada44c541a9c
+  data.tar.gz: f6e314d3f734e8eb315f97daa6765c0904bec8db
 SHA512:
-  metadata.gz: 3f506b59b42c1b5639a402d369f99aee0bc9f59a9036c2257c0209c431e7a487b0b6e961a17b966c8ea0f928241c148233a0424b36b8fed4b04d91793722f961
-  data.tar.gz: 72f1c306e8b8dc23e3d669f8968af77f319a7c46539aa8d2f4407b18bdbb2baafabb292bafd61211f249067deb8a56ad3d0d44ff3c78d78f05fcd6069dd43022
+  metadata.gz: f2db07995e16031cb9b04da83497400f082fb1fdac289761b46481ab83d283efbdf7bc12ac61508fa50583f081c53311c4dce8aa7cf90efda97d5c6bc4244435
+  data.tar.gz: 3e41ed2d4988192d230b67382e78b19209684a059aec2af1ca875234b3bf7787f17dbcdbd6004ca1ad0df12b051061d9413afffc85a6739c519d9eccfc89c1a9

data/.rubocop.yml

@@ -2,9 +2,6 @@
 
 AllCops:
   DisplayCopNames: true
-  Include:
-    - Rakefile
-    - lib/tasks/*.rake
   Exclude:
     - vendor/**/*
     - .*/**
@@ -54,3 +51,7 @@ Layout/DotPosition:
 # Allow class and message or instance raises
 Style/RaiseArgs:
   Enabled: false
+
+Lint/AmbiguousBlockAssociation:
+  Exclude:
+    - "spec/**/*"

data/.travis.yml

@@ -1,18 +1,19 @@
 language: ruby
-
-matrix:
-  allow_failures:
-    - rvm: jruby
-    - rvm: rbx-2
+cache: bundler 
 
 rvm:
   - 2.2
   - 2.3
   - 2.4
   - 2.5
-  - jruby
-  - rbx-2
+  - 2.6
+  - 2.7
 
 script:
   - bundle exec rubocop
   - bundle exec rspec spec
+
+# safelist
+branches:
+  only:
+  - master

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+## v1.1.0, 6 Aug 2020
+
+- Add User-Agent header
+- Add support for CA region
+
+## v1.0.0, 13 Jan 2020
+
+- Support Onfido API version 3
+- Drop support for Onfido API version 2
+- To upgrade from 0.15.0 see the v2 to v3 migration [guide](https://developers.onfido.com/guide/v2-to-v3-migration-guide)
+
+## v0.15.0, 4 Feb 2019
+
+- Add Check#find_by_url method (@ctrlaltdylan)
+
+## v0.14.0, 28 Jan 2019
+
+- Add support for applicant deletion and restore endpoints
+
+## v0.13.0, 5 Nov 2018
+
+- Add support for region-specific environments (@stephencookdev)
+
 ## v0.12.0, 29 May 2018
 
 - Add support for the Live Video resource (#55) (@Intrepidd)

data/LICENSE

@@ -1,6 +1,7 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Hassle
+Original work Copyright (c) 2015 Hassle
+Modified work Copyright 2019 Onfido
 
 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

@@ -3,75 +3,93 @@
 A thin wrapper for Onfido's API.
 
 [![Gem Version](https://badge.fury.io/rb/onfido.svg)](http://badge.fury.io/rb/onfido)
-[![Build Status](https://travis-ci.org/hvssle/onfido.svg?branch=master)](https://travis-ci.org/hvssle/onfido)
+[![Build Status](https://travis-ci.org/onfido/onfido-ruby.svg?branch=master)](https://travis-ci.org/onfido/onfido-ruby)
 
-This gem supports both `v1` and `v2` of the Onfido API. Refer to Onfido's [API documentation](https://onfido.com/documentation#introduction) for details of the expected requests and responses for both.
+This gem supports only `v3` of Onfido's API from version `1.0.0` onwards. The latest version that supports `v2` of Onfido's API is `0.15.0`. `v1` of Onfido's API is deprecated.
+
+The gem is compatible with Ruby 2.2.0 and onwards. Earlier versions of Ruby have [reached end-of-life](https://www.ruby-lang.org/en/news/2017/04/01/support-of-ruby-2-1-has-ended/), are no longer supported and no longer receive security fixes.
+
+Refer to Onfido's [API documentation](https://documentation.onfido.com) for details of the expected requests and responses.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'onfido', '~> 0.12.0'
+gem 'onfido', '~> 1.1.0'
 ```
 
-The gem is compatible with Ruby 2.2.0 and onwards. Earlier versions of Ruby have [reached end-of-life](https://www.ruby-lang.org/en/news/2017/04/01/support-of-ruby-2-1-has-ended/), are no longer supported and no longer receive security fixes.
-
 ## Configuration
 
 There are 5 configuration options:
 
 ```ruby
 Onfido.configure do |config|
-  config.api_key = 'MY_API_KEY'
-  config.api_version = 'v2'
+  config.api_key = '<YOUR_API_KEY>'
   config.logger = Logger.new(STDOUT)
   config.open_timeout = 30
   config.read_timeout = 80
+  config.region = nil
 end
 ```
 
+### Regions
+
+The gem will use the default region if no region is specified.
+
+To specify the US region do:
+`config.region = :us`
+
+To specify the CA region do:
+`config.region = :ca`
+
+See https://documentation.onfido.com/#regions for supported regions.
+
 ## Usage
 
 You can make API calls by using an instance of the `API` class:
 
 ```ruby
-api = Onfido::API.new
+onfido = Onfido::API.new
 ```
 
-Alternatively, you can set an API key here instead of in the initializer:
+You can also set an API key as follows, instead of in the initializer configuration:
 
 ```ruby
-api = Onfido::API.new(api_key: 'API_KEY')
+onfido = Onfido::API.new(api_key: '<YOUR_API_KEY>')
 ```
 
 ### Resources
 
 All resources share the same interface when making API calls. Use `.create` to create a resource, `.find` to find one, and `.all` to fetch all resources.
 
-**Note:** *All param keys should be a symbol e.g. `{ type: 'express', reports: [{ name: 'identity' }] }`*
+**Note:** *All param keys should be symbols e.g. `{ report_names: ['document'] }`*
 
 #### Applicants
 
 Applicants are the object upon which Onfido checks are performed.
 
 ```ruby
-api.applicant.create(params)                  # => Creates an applicant
-api.applicant.update('applicant_id', params)  # => Updates an applicant
-api.applicant.destroy('applicant_id')         # => Destroy an applicant
-api.applicant.find('applicant_id')            # => Finds a single applicant
-api.applicant.all                             # => Returns all applicants
+onfido.applicant.create(params)                  # => Creates an applicant
+onfido.applicant.update('<APPLICANT_ID>', params)  # => Updates an applicant
+onfido.applicant.destroy('<APPLICANT_ID>')         # => Schedule an applicant for deletion
+onfido.applicant.restore('<APPLICANT_ID>')         # => Restore an applicant scheduled for deletion
+onfido.applicant.find('<APPLICANT_ID>')            # => Finds a single applicant
+onfido.applicant.all                             # => Returns all applicants
 ```
 
+**Note:** Calling `onfido.applicant.destroy` adds the applicant and all associated documents, photos, videos, checks, and reports to the deletion queue. They will be deleted 20 days after the request is made. An applicant that is scheduled for deletion can be restored but applicants that have been permanently deleted cannot.
+See https://documentation.onfido.com/#delete-applicant for more information.
+
 #### Documents
 
-Documents provide supporting evidence for Onfido checks.
+Some report types require identity documents (passport, driving licence etc.) in order to be processed.
 
 ```ruby
-api.document.create('applicant_id', file: 'http://example.com', type: 'passport') # => Creates a document
-api.document.find('applicant_id', 'document_id') # => Finds a document
-api.document.download('applicant_id', 'document_id') # => Downloads a document as a binary data
-api.document.all('applicant_id') # => Returns all applicant's documents
+onfido.document.create(applicant_id: '<APPLICANT_ID>', file: <FILE>, type: 'passport') # => Creates a document
+onfido.document.find('<DOCUMENT_ID>')      # => Finds a document
+onfido.document.download('<DOCUMENT_ID>')  # => Downloads a document as a binary data
+onfido.document.all('<APPLICANT_ID>')      # => Returns all documents belonging to an applicant
 ```
 
 **Note:** The file parameter must be a `File`-like object which responds to `#read` and `#path`.
@@ -79,15 +97,17 @@ Previous versions of this gem supported providing a URL to a file accessible ove
 to a file in the local filesystem. You should instead load the file yourself and then pass it in
 to `#create`.
 
+See https://documentation.onfido.com/#document-types for example document types.
+
 #### Live Photos
 
-Live Photos, like documents, can provide supporting evidence for Onfido checks.
+Live photos are images of the applicant’s face, typically taken at the same time as documents are provided. These photos are used to perform Facial Similarity Photo reports on the applicant.
 
 ```ruby
-api.live_photo.create('applicant_id', file: 'http://example.com')
-api.live_photo.find(applicant_id, live_photo_id) # => Finds a live photo
-api.live_photo.download(applicant_id, live_photo_id) # => Downloads a live photo as binary data
-api.live_photo.all(applicant_id) # => Returns all applicant's live photos
+onfido.live_photo.create(applicant_id: '<APPLICANT_ID>', file: <FILE>) # => Creates a live photo
+onfido.live_photo.find('<LIVE_PHOTO_ID>')      # => Finds a live photo
+onfido.live_photo.download('<LIVE_PHOTO_ID>')  # => Downloads a live photo as binary data
+onfido.live_photo.all('<APPLICANT_ID>')        # => Returns all live photos belonging to an applicant
 ```
 
 **Note:** The file parameter must be a `File`-like object which responds to `#read` and `#path`.
@@ -97,48 +117,37 @@ to `#create`.
 
 #### Checks
 
-Checks are requests for Onfido to check an applicant, by commissioning one or
-more "reports" on them.
+Checks are performed on an applicant. Depending on the type of check you wish to perform, different information will be required when you create an applicant. A check consists of one or more reports.
 
 ```ruby
-api.check.create('applicant_id', type: 'express', reports: [{ name: 'identity' }])
-api.check.find('applicant_id', 'check_id')
-api.check.resume('check_id')
-api.check.all('applicant_id')
+onfido.check.create(applicant_id: '<APPLICANT_ID>', report_names: ['document', 'facial_similarity_photo']) # => Creates a check
+onfido.check.find('<CHECK_ID>')    # => Finds a check
+onfido.check.resume('<CHECK_ID>')  # => Resumes a paused check
+onfido.check.all('<APPLICANT_ID>') # => Returns all an applicant's checks
 ```
 
 #### Reports
 
-Reports provide details of the results of some part of a "check". They are
+Reports provide details of the results of some part of a check. They are
 created when a check is created, so the Onfido API only provides support for
 finding and listing them. For paused reports specifically, additional support for resuming and
  cancelling reports is also available.
 
 ```ruby
-api.report.find('check_id', 'report_id')
-api.report.all('check_id')
-api.report.resume('check_id', 'report_id')
-api.report.cancel('check_id', 'report_id')
-```
-
-#### Report Type Groups
-
-Report type groups provide a convenient way to group and organize different types of reports.
- The Onfido API only provides support for finding and listing them.
-
-```ruby
-api.report_type_group.find('report_type_group_id')
-api.report_type_group.all()
+onfido.report.find('<REPORT_ID>')    # => Finds a report
+onfido.report.all('<CHECK_ID>')      # => Returns all the reports in a check
+onfido.report.resume('<REPORT_ID>')  # => Resumes a paused report
+onfido.report.cancel('<REPORT_ID>')  # => Cancels a paused report
 ```
 
 #### Address Lookups
 
 Onfido provides an address lookup service, to help ensure well-formatted
-addresses are provided when creating "applicants". To search for addresses
+addresses are provided when creating applicants. To search for addresses
 by postcode, use:
 
 ```ruby
-api.address.all('SE1 4NG')
+onfido.address.all('SE1 4NG') # => Returns all addresses in a given postcode
 ```
 
 #### Webhook Endpoints
@@ -147,9 +156,9 @@ Onfido allows you to set up and view your webhook endpoints via the API, as well
 as through the dashboard.
 
 ```ruby
-api.webhook.create(params)          # => Creates a webhook endpoint
-api.webhook.find('webhook_id')      # => Finds a single webhook endpoint
-api.webhook.all                     # => Returns all webhook endpoints
+onfido.webhook.create(url: "https://webhook.url", events: ['report.completed, check.completed']) # => Registers a webhook endpoint
+onfido.webhook.find('<WEBHOOK_ID>')  # => Finds a single webhook endpoint
+onfido.webhook.all                 # => Returns all webhook endpoints
 ```
 
 #### SDK Tokens
@@ -158,26 +167,21 @@ Onfido allows you to generate JSON Web Tokens via the API in order to authentica
 with Onfido's [JavaScript SDK](https://github.com/onfido/onfido-sdk-ui).
 
 ```ruby
-api.sdk_token.create(applicant_id: 'applicant_id', referrer: 'referrer')
+onfido.sdk_token.create(applicant_id: 'applicant_id', referrer: 'referrer') # => Creates a JWT
 ```
 
-### Pagination
-
-All resources that support an `all` method also support pagination. By default,
-the first 20 records are fetched.
-
 ### Error Handling
 
-There are three classes of errors raised by the library, all of which subclass `Onfido::OnfidoError`:
+There are 3 classes of errors raised by the library, all of which subclass `Onfido::OnfidoError`:
 - `Onfido::ServerError` is raised whenever Onfido returns a `5xx` response
 - `Onfido::RequestError` is raised whenever Onfido returns any other kind of error
 - `Onfido::ConnectionError` is raised whenever a network error occurs (e.g., a timeout)
 
-All three error classes provide the `response_code`, `response_body`, `json_body`, `type` and `fields` of the error (although for `Onfido::ServerError` and `Onfido::ConnectionError` the last three are likely to be `nil`).
+All 3 error classes provide the `response_code`, `response_body`, `json_body`, `type` and `fields` of the error (although for `Onfido::ServerError` and `Onfido::ConnectionError` the last 3 are likely to be `nil`).
 
 ```ruby
 def create_applicant
-  api.applicant.create(params)
+  onfido.applicant.create(params)
 rescue Onfido::RequestError => e
   e.type          # => 'validation_error'
   e.fields        # => { "email": { "messages": ["invalid format"] } }
@@ -187,13 +191,13 @@ end
 
 ## Webhooks
 
-Each webhook endpoint has a secret token, generated automatically and [exposed](https://onfido.com/documentation#register-webhook) in the API. When sending a request, Onfido includes a signature computed using the request body and this token in the `X-Signature` header.
+Each webhook endpoint has a secret token, generated automatically and [exposed](https://onfido.com/documentation#register-webhook) in the API. When sending a request, Onfido includes a signature computed using the request body and this token in the `X-SHA2-Signature` header.
 
-This provided signature [should](https://onfido.com/documentation#webhook-security) be compared to one you generate yourself with the token to check that a webhook is a genuine request from Onfido.
+You should compare this provided signature to one you generate yourself with the token to verify that a webhook is a genuine request from Onfido.
 
 ```ruby
 if Onfido::Webhook.valid?(request.raw_post,
-                          request.headers["X-Signature"],
+                          request.headers["X-SHA2-Signature"],
                           ENV['ONFIDO_WEBHOOK_TOKEN'])
   process_webhook
 else
@@ -201,15 +205,11 @@ else
 end
 ```
 
-## Roadmap
-
-- Improve test coverage with more scenarios
-- Add custom errors based on the response code
-- Improve pagination handling (use information passed in link header)
+Read more at https://onfido.com/documentation#webhook-security
 
 ## Contributing
 
-1. Fork it ( https://github.com/hvssle/onfido/fork )
+1. Fork it ( https://github.com/onfido/onfido-ruby/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/onfido.rb

@@ -16,10 +16,10 @@ require 'onfido/resources/address'
 require 'onfido/resources/applicant'
 require 'onfido/resources/check'
 require 'onfido/resources/document'
+require 'onfido/resources/extraction'
 require 'onfido/resources/live_photo'
 require 'onfido/resources/live_video'
 require 'onfido/resources/report'
-require 'onfido/resources/report_type_group'
 require 'onfido/resources/sdk_token'
 require 'onfido/resources/webhook'
 

data/lib/onfido/api.rb

@@ -28,10 +28,6 @@ module Onfido
       Onfido::Report.new(@api_key)
     end
 
-    def report_type_group
-      Onfido::ReportTypeGroup.new(@api_key)
-    end
-
     def sdk_token
       Onfido::SdkToken.new(@api_key)
     end
@@ -43,5 +39,9 @@ module Onfido
     def address
       Onfido::Address.new(@api_key)
     end
+
+    def extraction
+      Onfido::Extraction.new(@api_key)
+    end
   end
 end

data/lib/onfido/configuration.rb

@@ -1,6 +1,11 @@
 module Onfido
   module Configuration
-    attr_accessor :api_key, :open_timeout, :read_timeout, :api_version
+    REGION_HOSTS = {
+      us: "api.us.onfido.com",
+      ca: "api.ca.onfido.com"
+    }.freeze
+
+    attr_accessor :api_key, :region, :open_timeout, :read_timeout
 
     def self.extended(base)
       base.reset
@@ -12,9 +17,9 @@ module Onfido
 
     def reset
       self.api_key = nil
+      self.region = nil
       self.open_timeout = 30
       self.read_timeout = 80
-      self.api_version = 'v2'
       RestClient.log = nil
     end
 
@@ -30,22 +35,13 @@ module Onfido
       RestClient.log ||= NullLogger.new
     end
 
-    def region
-      return unless api_key
-
-      first_bit = api_key.split("_")[0]
-
-      return if %w(live test).include?(first_bit)
-
-      first_bit
-    end
-
     def endpoint
-      if region
-        "https://api.#{region}.onfido.com/#{api_version}/"
-      else
-        "https://api.onfido.com/#{api_version}/"
+      region_host = region ? REGION_HOSTS[region.downcase.to_sym] : "api.onfido.com"
+      unless region_host
+        raise "The region \"#{region.downcase}\" is not currently supported"
       end
+
+      "https://#{region_host}/v3/"
     end
   end
 end