npm package: @highnoteplatform/document-upload
Description: A document upload component that enables easy uploads of required documents for an application.
Author: packages@highnote.com
Latest version: 1.1.5

# @highnoteplatform/document-upload

> **Note:** This library is in a pre-release phase. Prior to the release of
> version `1.0.0`, breaking changes may be introduced.

Document Upload SDK simplifies our Subscriber’s integration.

It minimizes impact for Subscriber to changes in Highnote’s manual reviews.

It expands the secured document upload capability.

## Requirements

1. A Highnote Account

2. A server-side integration using an API Key

3. Document Upload Session ID

4. A HTML selector for injecting a DOM Element

## Installation

With npm:

```sh
npm i @highnoteplatform/document-upload
```

With yarn:

```sh
yarn add @highnoteplatform/document-upload
```

With pnpm:

```sh
pnpm add @highnoteplatform/document-upload
```

This package ships with TypeScript definitions installed.

via CDN

<!-- markdownlint-disable MD013 -->

You can install the Document Upload SDK for use on your page directly from a CDN such as JSDelivr. This is helpful when exploring the SDK or for use in tools such as CodeSandbox.

It is recommended you select a specific version of the library to use. You can replace @latest with your chosen version, for example, @1.0.0.

```html
<script src="https://cdn.jsdelivr.net/npm/@highnoteplatform/document-upload@latest/lib/in
```

## Usage

### Step 1: Get your documentUploadSessionId

Get your documentUploadSessionId

<!-- markdownlint-enable MD013 -->

<!-- markdownlint-disable MD036 -->

**GraphQL query**

```graphql
query getApplication($id: ID!) {
  node(id: $id) {
    ... on AccountHolderCardProductApplication {
      id
      accountHolderSnapshot {
        ... on USPersonAccountHolderSnapshot {
          currentVerification {
            requiredDocuments {
              ... on AccountHolderApplicationRequiredDocument {
                documentUploadSession {
                  ... on USAccountHolderApplicationDocumentUploadSession {
                    id
                  }
                }
              }
            }
          }
        }
        ... on USBusinessAccountHolderSnapshot {
          primaryAuthorizedPerson {
            currentVerification {
              requiredDocuments {
                ... on AccountHolderApplicationRequiredDocument {
                  documentUploadSession {
                    ... on USAccountHolderApplicationDocumentUploadSession {
                      id
                    }
                  }
                }
              }
            }
          }
          businessProfile {
            currentVerification {
              requiredDocuments {
                ... on AccountHolderApplicationRequiredDocument {
                  documentUploadSession {
                    ... on USAccountHolderApplicationDocumentUploadSession {
                      id
                    }
                  }
                }
              }
            }
            ultimateBeneficialOwners {
              currentVerification {
                requiredDocuments {
                  ... on AccountHolderApplicationRequiredDocument {
                    documentUploadSession {
                      ... on USAccountHolderApplicationDocumentUploadSession {
                        id
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

**Input variables**

```json
{
  "id": "APPLICATION_ID"
}
```

**Response**

```json
{
  "data": {
    "node": {
      "id": "ap_22bflm1504f70a9d624437aee126cccbee3c80",
      "accountHolderSnapshot": {
        "primaryAuthorizedPerson": {
          "currentVerification": {
            "requiredDocuments": [
              {
                "documentUploadSession": {
                  "id": "du_22aspapae536c062aa644a7b147e34997016a81"
                }
              }
            ]
          }
        },
        "businessProfile": {
          "currentVerification": {
            "requiredDocuments": [
              {
                "documentUploadSession": {
                  "id": "du_22ahbapcadfaa2085314a8f8fdde89a2b101c98"
                }
              }
            ]
          },
          "ultimateBeneficialOwners": []
        }
      }
    }
  },
  "extensions": {
    "requestId": "331f81c8-f28b-9975-9abe-d85eaab69a1a",
    "rateLimit": {
      "limit": 30030,
      "remaining": 30016,
      "cost": 14
    }
  }
}
```

### Step 2: Generate a client token

On your server, generate a client token using the GraphQL API.

<!-- markdownlint-disable MD013 -->

> See the [generateDocumentUploadClientToken](https://highnote.com/docs/reference/mutation/generateDocumentUploadClientToken) docs.

<!-- markdownlint-enable MD013 -->

<!-- markdownlint-disable MD036 -->

**GraphQL query**

```graphql
mutation GenerateDocumentUploadClientToken(
  $input: GenerateDocumentUploadClientTokenInput!
) {
  generateDocumentUploadClientToken(input: $input) {
    ... on ClientToken {
      value
      expirationDate
      usage
    }
  }
}
```

**Input variables**

```json
{
  "input": {
    "documentUploadSessionId": "DOCUMENT_UPLOAD_SESSION_ID_FROM_ABOVE",
    "permissions": ["MANAGE_DOCUMENT_UPLOAD_SESSION"]
  }
}
```

**Response**

```json
{
  "data": {
    "generatePaymentCardClientToken": {
      "value": "TOKEN",
      "expirationDate": "2022-02-07T20:04:50.633Z",
      "usage": "UNTIL_EXPIRATION"
    }
  },
  "extensions": {
    "requestId": "example-request-id"
  }
}
```

### Step 3: Prepare your HTML

<!-- markdownlint-disable MD013 -->

You must provide the Document Uploader with an element to which the new HTMLDivElement can be appended.

document-upload-component

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document-Upload</title>
  </head>
  <body>
    <div class="side-rail">
      <form id="documentUploadConfig">
        <label for="clientToken">Client Token</label>
        <input
          type="text"
          name="clientToken"
          id="clientToken"
          placeholder="Client Token"
        />
        <div class="margin-top">
          <label for="documentUploadSessionId"
            >Document Upload Session ID</label
          >
          <input
            type="text"
            name="documentUploadSessionId"
            id="documentUploadSessionId"
            placeholder="Document Upload Session ID"
          />
        </div>
        <button type="submit">Initialize Document Upload</button>
      </form>
    </div>
    <div id="document-upload-component">
      <!-- An new DOM element will be appended here -->
    </div>
    <script src="index.ts" type="module"></script>
  </body>
</html>
```

<!-- markdownlint-disable MD013 -->

The library will append a HTMLDivElement into this element to render the appropriate widget. You can style the content inside of each iframe by passing any combination of allowed styles.

You can initialize the Document Upload by calling initializeDocumentUploadSdk. This will return a Promise that, will contain a reference to the HTMLDivElement instance.

## Error Handling

| Error                                                                                                                                                                                                                 | Description                                                                                               |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| **_InvalidCredentialError_** <br /> This error occurs when the provided Client Token is invalid or expired.The payload will contain the requestId which can be used for support and debugging.                        | name: "InvalidCredential" <br /> context: object <br /> requestId: string                                 |
| **_DocumentUploadRequestError_** <br /> This error represents errors encountered when communicating with the Highnote GraphQL API.The payload will contain the requestId which can be used for support and debugging. | name: "DocumentUploadRequestError" <br /> message: string <br /> context: object <br /> requestId: string |
| **_DocumentUploadConfigError_** <br /> This error is raised when an invalid configuration is provided at runtime.                                                                                                     | name: "DocumentUploadConfigError" <br /> message: string                                                  |

### Examples

```typescript
import { initializeDocumentUploadSDK } from "@highnoteplatform/document-upload";

const handleError = (error: Error) => {
  switch (error.name) {
    case "InvalidCredential":
      // Handle invalid/expired credential
      // Unmount fields, fetch new client token, re-initialize
      console.error(error.context.requestId); // "some-request-id"
      break;

    case "DoumentUploadRequestError":
      console.error(error.context.requestId); // some-request-id
      break;

    case "DocumentUploadConfigError":
      console.error(error.message); // "Invalid Session ID"
      break;

    default:
      console.error(error);
  }
};

const handleOnLoad = (component: Element) => {
  console.log(`[Integrator log]: ${component.id} value appended to selector!`);
};

const handleOnSuccess = (onSuccess: boolean) => {
  if (onSuccess) {
    console.log(`[Integrator log]: All documents uploaded and session closed.`);
  }
};

await initializeDocumentUploadSdk({
  clientToken: "client-token",
  documentUploadSessionId: "document-upload-session-id",
  environment: "test",
  documentUploadComponent: { selector: "#document-upload-component" },
  onLoad: handleOnLoad,
  onSuccess: handleOnSuccess,
  onError: handleError,
});
```