API v3.1 additions, changes base URLs, adds tests, bumps version… (#37)

* Update to use API v3.1 and add new features * Make region required and change base URL for EU region * Bump version to 2.0.0 * Convert autofill address lines to camelCase Co-authored-by: Ciaran Lawlor <[email protected]>
onfido · Apr 14, 2021 · 55490e0 · 55490e0
1 parent 06210c9
commit 55490e0
Show file tree

Hide file tree

Showing 23 changed files with 173 additions and 147 deletions.
diff --git a/.nvmrc b/.nvmrc
@@ -1 +1 @@
-12
+15
diff --git a/.tool-versions b/.tool-versions
@@ -1 +1 @@
-nodejs 12.13.0
+nodejs 15.7.0
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,52 +1,53 @@
 # Changelog
 
+## v2.0.0, 9 April 2021
+
+- Updated to use API v3.1
+- Region is now a required argument when constructing an `Onfido` instance. The region previously defaulted to `Region.EU`
+- Add support for downloading a check
+
+## v1.6.0, 8 March 2021
+
+- Add `privacy_notices_read_consent_given` to the type for creating a chec
+
 ## v1.5.4, 12 January 2021
 
 - Updated dependencies.
 
-
 ## v1.5.3, 3 December 2020
 
 - Library should work now with `esModuleInterop: false`
 
-
 ## v1.5.2, 3 September 2020
 
 - Fix type declaration location for TypeScript users
 
-
 ## v1.5.1, 20 August 2020
 
 - Ensure consistent version in User-Agent
 
-
 ## v1.5.0, 14 August 2020
 
 - Add User Agent header
 
-
 ## v1.4.0, 15 July 2020
 
 - Add support for [Autofill endpoint](https://documentation.onfido.com/#autofill-beta)
 
-
 ## v1.3.0, 30 June 2020
 
 - Add support for `cross_device_url` when generating an SDK token
 
-
 ## v1.2.0, 23 June 2020
 
 - Allow specifying the filepath and content type explicitly for file upload
 - Add support for the Canada region (api.ca.onfido.com)
 - Add missing `document_ids` field to `CheckRequest` type
 
-
 ## v1.1.0, 2 April 2020
 
 - Improved typing of check and report objects.
 
-
 ## v1.0.0, 23 January 2020
 
 - The initial release of this library, which uses v3 of the Onfido API
diff --git a/README.md b/README.md
@@ -6,6 +6,8 @@ Documentation can be found at <https://documentation.onfido.com>
 
 This library is only for use on the backend, as it uses Onfido API tokens which must be kept secret. If you do need to collect applicant data in the frontend of your application, we recommend that you use one of [the Onfido SDKs](https://developers.onfido.com/sdks/).
 
+This version uses Onfido API v3.1. Refer to our [API versioning guide](https://developers.onfido.com/guide/api-versioning-policy#client-libraries) for details of which client library versions use which versions of the API.
+
 ## Installation
 
 For npm:
@@ -34,13 +36,13 @@ For TypeScript users, types are available as well:
 import { Onfido, Region, Applicant, OnfidoApiError } from "@onfido/api";
 ```
 
-Configure with your API token, and region if necessary:
+Configure with your API token and region:
 
 ```js
 const onfido = new Onfido({
-  apiToken: process.env.ONFIDO_API_TOKEN
-  // Defaults to Region.EU (api.onfido.com), supports Region.US and Region.CA
-  // region: Region.US
+  apiToken: process.env.ONFIDO_API_TOKEN,
+  // Supports Region.EU, Region.US and Region.CA
+  region: Region.EU
 });
 ```
 

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@onfido/api",
-  "version": "1.6.0",
+  "version": "2.0.0",
   "description": "Node.js library for the Onfido API",
   "keywords": [
     "onfido",

diff --git a/src/Onfido.ts b/src/Onfido.ts
@@ -19,17 +19,11 @@ export enum Region {
 
 export type OnfidoOptions = {
   apiToken: string;
-  region?: Region;
+  region: Region;
   timeout?: number;
   unknownApiUrl?: string;
 };
 
-const apiUrls = {
-  [Region.EU]: "https://api.onfido.com/v3/",
-  [Region.US]: "https://api.us.onfido.com/v3/",
-  [Region.CA]: "https://api.ca.onfido.com/v3/"
-};
-
 export class Onfido {
   public readonly axiosInstance: AxiosInstance;
   // Core resources
@@ -47,19 +41,23 @@ export class Onfido {
 
   constructor({
     apiToken,
-    region = Region.EU,
+    region,
     timeout = 30_000,
     unknownApiUrl
   }: OnfidoOptions) {
     if (!apiToken) {
       throw new Error("No apiToken provided");
     }
-
-    const regionUrl = apiUrls[region];
-    if (!regionUrl) {
-      throw new Error("Unknown region " + region);
+    if (!region || !Object.values(Region).includes(region)) {
+      throw new Error(
+        `Unknown or missing region '${region}'. ` +
+          "We previously defaulted to region 'EU', so if you previously didn’t " +
+          "set a region or used api.onfido.com, please set your region to 'EU'"
+      );
     }
 
+    const regionUrl = `https://api.${region.toLowerCase()}.onfido.com/v3.1/`;
+
     this.axiosInstance = axios.create({
       baseURL: unknownApiUrl || regionUrl,
       headers: {

diff --git a/src/formatting.ts b/src/formatting.ts
@@ -15,11 +15,13 @@ type ContentsAndOptions = {
 
 export type FileLike = Readable | ContentsAndOptions;
 
-const snakeCase = (s: string): string =>
-  s.replace(/[A-Z]/g, char => `_${char.toLowerCase()}`);
+const snakeCase = (camelCaseString: string): string =>
+  camelCaseString.replace(/[A-Z]/g, char => `_${char.toLowerCase()}`);
 
-const camelCase = (s: string): string =>
-  s.replace(/_[a-z]/g, underscoreChar => underscoreChar[1].toUpperCase());
+const camelCase = (snakeCaseString: string): string =>
+  snakeCaseString
+    .replace(/_[0-9]/g, underscoreDigit => underscoreDigit[1])
+    .replace(/_[a-z]/g, underscoreChar => underscoreChar[1].toUpperCase());
 
 const deepMapObjectKeys = (value: unknown, f: (key: string) => string): any => {
   if (!(value instanceof Object)) {

diff --git a/src/resources/Checks.ts b/src/resources/Checks.ts
@@ -1,4 +1,5 @@
 import { AxiosInstance } from "axios";
+import { OnfidoDownload } from "../OnfidoDownload";
 import { Method, Resource } from "../Resource";
 
 export type CheckRequest = {
@@ -11,6 +12,7 @@ export type CheckRequest = {
   suppressFormEmails?: boolean;
   redirectUri?: string | null;
   privacyNoticesReadConsentGiven?: boolean;
+  webhookIds?: string[] | null;
 };
 
 export type Check = {
@@ -26,6 +28,8 @@ export type Check = {
   formUri: string | null;
   redirectUri: string | null;
   resultsUri: string;
+  privacyNoticesReadConsentGiven: boolean;
+  webhookIds: string[] | null;
 };
 
 export class Checks extends Resource<CheckRequest> {
@@ -53,4 +57,8 @@ export class Checks extends Resource<CheckRequest> {
   public async resume(id: string): Promise<void> {
     await this.request({ method: Method.POST, path: `${id}/resume` });
   }
+
+  public async download(id: string): Promise<OnfidoDownload> {
+    return super.download(`${id}/download`);
+  }
 }
diff --git a/test/Onfido.test.ts b/test/Onfido.test.ts
@@ -1,43 +1,49 @@
 import { Onfido, Region } from "onfido-node";
 
 it("sets the authorization header from the given token", () => {
-  const onfido = new Onfido({ apiToken: "api_token" });
+  const onfido = new Onfido({ apiToken: "api_token", region: Region.EU });
   expect(onfido.axiosInstance.defaults.headers.Authorization).toBe(
     "Token token=api_token"
   );
 });
 
 it("contains a user agent header", () => {
-  const onfido = new Onfido({ apiToken: "api_token" });
+  const onfido = new Onfido({ apiToken: "api_token", region: Region.EU });
   expect(onfido.axiosInstance.defaults.headers["User-Agent"]).toMatch(
     /^onfido-node\/\d+\.\d+\.\d+$/
   );
 });
 
-it("defaults to the EU region", () => {
-  const onfido = new Onfido({ apiToken: "token" });
+it("allows setting the EU region", () => {
+  const onfido = new Onfido({ apiToken: "token", region: Region.EU });
   expect(onfido.axiosInstance.defaults.baseURL).toBe(
-    "https://api.onfido.com/v3/"
+    "https://api.eu.onfido.com/v3.1/"
   );
 });
 
 it("allows setting the US region", () => {
   const onfido = new Onfido({ apiToken: "token", region: Region.US });
   expect(onfido.axiosInstance.defaults.baseURL).toBe(
-    "https://api.us.onfido.com/v3/"
+    "https://api.us.onfido.com/v3.1/"
   );
 });
 
 it("allows setting the CA region", () => {
   const onfido = new Onfido({ apiToken: "token", region: Region.CA });
   expect(onfido.axiosInstance.defaults.baseURL).toBe(
-    "https://api.ca.onfido.com/v3/"
+    "https://api.ca.onfido.com/v3.1/"
+  );
+});
+
+it("throws an error for no region", () => {
+  expect(() => new Onfido({ apiToken: "token" } as any)).toThrow(
+    "Unknown or missing region 'undefined'"
   );
 });
 
 it("throws an error for unknown regions", () => {
   expect(() => new Onfido({ apiToken: "token", region: "abc" as any })).toThrow(
-    "Unknown region abc"
+    "Unknown or missing region 'abc'"
   );
 });
 
@@ -47,6 +53,11 @@ it("throws an error if no api token is provided", () => {
 });
 
 it("allows changing the default timeout", () => {
-  const onfido = new Onfido({ apiToken: "token", timeout: 123 });
+  const onfido = new Onfido({
+    apiToken: "token",
+    region: Region.EU,
+    timeout: 123
+  });
+
   expect(onfido.axiosInstance.defaults.timeout).toBe(123);
 });
diff --git a/test/Resource.test.ts b/test/Resource.test.ts
@@ -1,15 +1,10 @@
-import axios from "axios";
-import nock from "nock";
 import { OnfidoApiError, OnfidoDownload } from "onfido-node";
 import { Resource } from "../src/Resource";
-
-const axiosInstance = axios.create({
-  baseURL: "https://api.onfido.com/v3/"
-});
+import { createNock, onfido } from "./testHelpers";
 
 class TestResource extends Resource<{}> {
   public constructor() {
-    super("test", axiosInstance);
+    super("test", onfido.axiosInstance);
   }
 
   public async upload(body: {}): Promise<any> {
@@ -37,7 +32,7 @@ describe("error handling", () => {
   it("returns an OnfidoApiError when a response is recieved", async () => {
     expect.assertions(2);
 
-    nock("https://api.onfido.com/v3")
+    createNock()
       .post("/test/")
       .reply(404, "Not Found");
 
@@ -52,7 +47,7 @@ describe("error handling", () => {
   it("reads json error messages when streaming the response", async () => {
     expect.assertions(2);
 
-    nock("https://api.onfido.com/v3")
+    createNock()
       .get("/test/123/download")
       .reply(400, errorJson);
 

diff --git a/test/formatting.test.ts b/test/formatting.test.ts
@@ -20,9 +20,9 @@ describe("convertObjectToCamelCase", () => {
     expect(
       convertObjectToCamelCase({
         key_name: { nested_key: 2 },
-        a: [{ nested_in_array: 1 }]
+        a: [{ nested_in_array_1: 1 }]
       })
-    ).toEqual({ keyName: { nestedKey: 2 }, a: [{ nestedInArray: 1 }] });
+    ).toEqual({ keyName: { nestedKey: 2 }, a: [{ nestedInArray1: 1 }] });
   });
 });
 

diff --git a/test/resources/Addresses.test.ts b/test/resources/Addresses.test.ts
@@ -1,7 +1,5 @@
-import nock from "nock";
-import { Address, Onfido } from "onfido-node";
-
-const onfido = new Onfido({ apiToken: "api_token" });
+import { Address } from "onfido-node";
+import { createNock, onfido } from "../testHelpers";
 
 const exampleAddress: Address = {
   postcode: "S2 2DF",
@@ -34,7 +32,7 @@ const exampleAddressJson = {
 };
 
 it("allows picking addresses", async () => {
-  nock("https://api.onfido.com/v3")
+  createNock()
     .get("/addresses/pick")
     .query({ postcode: "S2 2DF" })
     .reply(200, { addresses: [exampleAddressJson, exampleAddressJson] });