@onfido/api 2.9.0 → 3.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 Onfido
+Copyright (c) 2024 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

package/README.md

@@ -2,98 +2,121 @@
 
 The official Node.js library for integrating with the Onfido API.
 
-Documentation can be found at <https://documentation.onfido.com>
+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 the Onfido SDKs: [iOS](https://github.com/onfido/onfido-ios-sdk), [Android](https://github.com/onfido/onfido-android-sdk), [Web](https://github.com/onfido/onfido-sdk-ui), and [React Native](https://github.com/onfido/react-native-sdk). 
+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 the Onfido SDKs: [iOS](https://github.com/onfido/onfido-ios-sdk), [Android](https://github.com/onfido/onfido-android-sdk), [Web](https://github.com/onfido/onfido-sdk-ui), and [React Native](https://github.com/onfido/react-native-sdk).
 
 This version uses Onfido API v3.6. 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
+## Installation & Usage
 
-For npm:
+### Installation
+
+#### Npm
 
 ```sh
 npm install @onfido/api
 ```
 
-For Yarn:
+#### Yarn
 
 ```sh
 yarn add @onfido/api
 ```
 
-## Getting started
+## Getting Started
 
 Require the package:
 
 ```js
-const { Onfido, Region } = require("@onfido/api");
+const {
+  DefaultApi,
+  Configuration,
+  WebhookEventVerifier
+} = require("@onfido/api");
+const { isAxiosError } = require("axios");
 ```
 
 For TypeScript users, types are available as well:
 
 ```ts
-import { Onfido, Region, Applicant, OnfidoApiError } from "@onfido/api";
+import {
+  DefaultApi,
+  Configuration,
+  Region,
+  WebhookEventVerifier
+} from "@onfido/api";
+import { isAxiosError } from "axios";
 ```
 
 Configure with your API token and region:
 
 ```js
-const onfido = new Onfido({
-  apiToken: process.env.ONFIDO_API_TOKEN,
-  // Supports Region.EU, Region.US and Region.CA
-  region: Region.EU
-});
+const onfido = new DefaultApi(
+  new Configuration({
+    apiToken: process.env.ONFIDO_API_TOKEN,
+    region: Region.EU, // Supports Region.EU, Region.US and Region.CA
+    baseOptions: { timeout: 60_000 } // Additional Axios options (timeout, etc.)
+  })
+);
 ```
 
-Using with `async`/`await` (in an `async function`):
+NB: by default, timeout is set to 30 seconds.
 
-```js
-try {
-  const applicant = await onfido.applicant.create({
-    firstName: "Jane",
-    lastName: "Doe", 
-    location: {
-      ipAddress: "127.0.0.1",
-      countryOfResidence: "GBR"
-    }
-  });
+### Making a call to the API
 
-  const check = await onfido.check.create({
-    applicantId: applicant.id,
-    reportNames: ["identity_enhanced"]
-  });
+Using `async`/`await` (in an `async function`):
 
-  return check;
-} catch (error) {
-  if (error instanceof OnfidoApiError) {
-    // An error response was received from the Onfido API, extra info is available.
-    console.log(error.message);
-    console.log(error.type);
-    console.log(error.isClientError());
-  } else {
-    // No response was received for some reason e.g. a network error.
-    console.log(error.message);
+```js
+(async () => {
+  try {
+    const applicant = await onfido.createApplicant({
+      first_name: "Jane",
+      last_name: "Doe",
+      location: {
+        ip_address: "127.0.0.1",
+        country_of_residence: "GBR"
+      }
+    });
+
+    // ...
+  } catch (error) {
+    if (isAxiosError(error)) {
+      console.log(`status code: ${error.response?.status}`);
+      const error_details = error.response?.data.error;
+      // An error response was received from the Onfido API, extra info is available.
+      if (error_details) {
+        console.log(error_details.message);
+        console.log(error_details.type);
+      } else {
+        // No response was received for some reason e.g. a network error.
+        console.log(error.message);
+      }
+    } else {
+      console.log(error.message);
+    }
   }
-}
+})();
 ```
 
-Using with promises:
+Please find more information regarding Axios errors in library [documentation](https://axios-http.com/docs/handling_errors).
+
+Using promises:
 
 ```js
-onfido.applicant
-  .create({
-    firstName: "Jane",
-    lastName: "Doe",
+onfido
+  .createApplicant({
+    first_name: "Jane",
+    last_name: "Doe",
     location: {
-      ipAddress: "127.0.0.1",
-      countryOfResidence: "GBR"
+      ip_address: "127.0.0.1",
+      country_of_residence: "GBR"
     }
   })
   .then(applicant =>
-    onfido.check.create({
-      applicantId: applicant.id,
-      reportNames: ["identity_enhanced"]
+    onfido.createCheck({
+      applicant_id: applicant.data.id,
+      report_names: ["identity_enhanced"]
     })
   )
   .then(check =>
@@ -104,111 +127,94 @@ onfido.applicant
   });
 ```
 
-## Response format
-
-Most responses will be normal JavaScript objects. Property names will be in camelCase rather than snake_case, including property names in nested objects.
-
-```js
-const applicant = await onfido.applicant.create({
-  firstName: "Jane",
-  lastName: "Doe",
-  address: {
-    flatNumber: "12",
-    postcode: "S2 2DF",
-    country: "GBR",
-  },
-  location: {
-    ipAddress: "127.0.0.1",
-    countryOfResidence: "GBR",
-  }
-});
-
-console.log(applicant);
-{
-  id: "<APPLICANT_ID>",
-  createdAt: "2020-01-22T10:44:01Z",
-  firstName: "Jane",
-  lastName: "Doe",
-  email: null,
-  dob: null,
-  deleteAt: null,
-  href: "/v3/applicants/<APPLICANT_ID>",
-  address: {
-    flatNumber: "12",
-    buildingNumber: null,
-    buildingName: null,
-    street: null,
-    subStreet: null,
-    town: null,
-    state: null,
-    postcode: "S2 2DF",
-    country: "GBR",
-    line1: null,
-    line2: null,
-    line3: null
-  },
-  idNumbers: [],
-  phoneNumber: null,
-  location: {
-    ipAddress: "127.0.0.1",
-    countryOfResidence: "GBR"
-  }
-}
-```
+### File download
 
-File downloads, for example `onfido.document.download(documentId)`, will return instances of `OnfidoDownload`.
+File downloads, for example `onfido.downloadDocument(documentId, {responseType: 'arraybuffer'})`, will return an instance of a specific object for this endpoint.
 
 These objects will have a content type, e.g. `image/png`.
 
 ```js
-download.contentType;
+download.headers["content-type"];
 ```
 
-Call `asStream()` to get a `Readable` stream of the download. You can read more about [`Readable` streams](https://nodejs.org/api/stream.html#stream_readable_streams).
+Call `slice()` to get a `Blob` of the download:
 
 ```js
-const readableStream = download.asStream();
+const blob = download.data.slice();
 ```
 
-## File upload
+### File upload
 
-For some common types of streams, like instances of `fs.ReadStream`, you can provide the stream directly in the `file` property:
+For some common types of streams, like instances of `fs.ReadStream`, you can provide the stream directly:
 
 ```js
-onfido.document.upload({
-  applicantId: "<APPLICANT_ID>",
-  file: fs.createReadStream("path/to/passport.png"),
-  type: "passport"
-});
+onfido.uploadDocument(
+  "passport",
+  "<APPLICANT_ID>",
+  fs.createReadStream("path/to/passport.png")
+);
 ```
 
-Alternatively, you may need to provide some extra information, for example when uploading a Base64 encoded image:
+### Webhook event verification
+
+Webhook events payload needs to be verified before it can be accessed. Library allows to easily decode the payload and verify its signature before returning it as an object for user convenience:
 
 ```js
-const buffer = Buffer.from(base64Data, "base64");
-const bufferStream = new PassThrough();
-bufferStream.end(buffer);
-
-onfido.document.upload({
-  applicantId: "<APPLICANT_ID>",
-  file: {
-    contents: bufferStream,
-    filepath: "image.png",
-    contentType: "image/png"
-  },
-  type: "passport"
-});
+(async () => {
+  try {
+    const token = process.env.ONFIDO_WEBHOOK_SECRET_TOKEN;
+    const verifier = new WebhookEventVerifier(token);
+    const signature = "a0...760e";
+
+    const event = verifier.readPayload(`{"payload":{"r...3"}}`, signature);
+  } catch (e) {
+    if (e instanceof OnfidoInvalidSignatureError) {
+      // Invalid webhook signature
+    }
+  }
+})();
 ```
 
-## More documentation
+### Recommendations
 
-More documentation and code examples can be found at <https://documentation.onfido.com>
+#### Do not use square bracket syntax
 
-## Support
+Except for accessing Task object's outputs, retain from using the square bracket syntax (i.e. `[]`) to access not defined properties to avoid breaking changes when these fields will appear.
+
+## Contributing
+
+This library is automatically generated using [OpenAPI Generator](https://openapi-generator.tech) (version: 7.6.0); therefore all the contributions, except tests files, should target [Onfido OpenAPI specification repository](https://github.com/onfido/onfido-openapi-spec/tree/master) instead of this repository.
+
+For contributions to the tests instead, please follow the steps below:
 
-Should you encounter any technical issues during integration, please contact Onfido’s Customer Support team
-via [email](mailto:support@onfido.com), including the word ISSUE: at the start of the subject line.
+1. [Fork](https://github.com/onfido/onfido-node/fork) repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Make your changes
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request
 
-Alternatively, you can search the support documentation available via the customer experience
-portal, [public.support.onfido.com](http://public.support.onfido.com).
+## Versioning policy
+
+[Semantic Versioning](https://semver.org) policy is used for library versioning, following guidelines and limitations below:
+
+- MAJOR versions (x.0.0) might:
+  - target a new API version
+  - include non-backward compatible change
+- MINOR versions (0.x.0) might:
+  - add a new functionality, non-mandatory parameter or property
+  - deprecate an old functionality
+  - include non-backward compatible change to a functionality which is:
+    - labelled as alpha or beta
+    - completely broken and not usable
+- PATCH version (0.0.x) might:
+  - fix a bug
+  - include backward compatible changes only
+
+## More documentation
+
+More documentation and code examples can be found at <https://documentation.onfido.com>.
+
+## Support
 
+Should you encounter any technical issues during integration, please contact Onfido's Customer Support team via the [Customer Experience Portal](https://public.support.onfido.com/) which also includes support documentation.