@regulaforensics/idv-capture-web 0.1.216-nightly → 0.1.248-nightly

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +126 -127
  2. package/dist/index.d.ts +443 -58
  3. package/dist/main.iife.js +109 -65
  4. package/dist/main.js +8249 -21071
  5. package/package.json +4 -2
package/README.md CHANGED
@@ -1,28 +1,28 @@
1
- # Idv Web Component
1
+ # Welcome to IDV Platform Web Components documentation!
2
2
 
3
3
  - [Overview](#overview)
4
- - [Before you start](#before-you-start)
4
+ - [Before You Start](#before-you-start)
5
5
  - [Compatibility](#compatibility)
6
6
  - [Install via NPM](#install-via-npm)
7
7
  - [Install via CDN](#install-via-cdn)
8
+ - [Setup](#setup)
8
9
  - [Events](#events)
10
+ - [Configuration](#configuration)
11
+ - [Methods](#methods)
12
+ - [Examples](#examples)
9
13
 
10
14
  ---
11
15
 
12
16
  ## Overview
13
17
 
14
- The available component is:
18
+ The available component is `<idv-flow>`.
15
19
 
16
- - `idv-flow`
20
+ The component is based on WebAssembly (compiled from our core C++ code and wrapped with JavaScript). The same code is used across all SDK packages, ensuring consistency between platforms.
17
21
 
18
- The web components are based on WebAssembly (.wasm module), which is our core C++ code compiled for use in browsers and wrapped with a JS layer. It is exactly the same code as built for all the other platform SDK packages.
22
+ ## Before You Start
19
23
 
20
- ## Before you start
21
-
22
- Please note that:
23
-
24
- - The components work **only** under the HTTPS protocol on the website.
25
- - The components library does register the components on the web page itself, so make sure to import the library to your web site before adding the components to the web page code.
24
+ - Components **require HTTPS** — they will not work over plain HTTP.
25
+ - The library automatically registers web components. Import it before adding the components to your HTML.
26
26
 
27
27
  ## Compatibility
28
28
 
@@ -34,46 +34,35 @@ Please note that:
34
34
 
35
35
  ## Install via NPM
36
36
 
37
- On the command line, navigate to the root directory of your project:
37
+ If you are starting a new project, initialize it:
38
38
 
39
39
  ```
40
40
  cd /path/to/project
41
- ```
42
-
43
- Run the following command:
44
-
45
- ```
46
41
  npm init
47
42
  ```
48
43
 
49
- Answer the questions in the command line questionnaire.
50
-
51
- Install idv-capture-web:
44
+ Install the main package:
52
45
 
53
46
  ```
54
47
  npm i @regulaforensics/idv-capture-web
55
- npm i @regulaforensics/idv-gui
48
+ ```
56
49
 
57
- #optionally
50
+ Optionally, install additional modules:
58
51
 
52
+ ```
59
53
  npm i @regulaforensics/idv-face
60
54
  npm i @regulaforensics/idv-document
61
55
  ```
62
56
 
63
- Create `index.html` and `index.js` files in the root directory of the project.
57
+ Create `index.html` and `index.js` files in the root directory of the project.
64
58
 
65
59
  Import `@regulaforensics/idv-capture-web` into your `index.js`:
66
60
 
67
61
  ```javascript
68
62
  import './node_modules/@regulaforensics/idv-capture-web/dist/main.js';
69
- import './node_modules/@regulaforensics/idv-gui/dist/main.js';
70
63
  ```
71
64
 
72
- In `index.html` connect `index.js` and add the name of the component you want to use. Available components:
73
-
74
- `<idv-flow></idv-flow>`
75
-
76
- For example:
65
+ In `index.html`, add the component and load `index.js`:
77
66
 
78
67
  ```html
79
68
  <!DOCTYPE html>
@@ -89,150 +78,160 @@ For example:
89
78
  </html>
90
79
  ```
91
80
 
92
- ## Install via CDN
81
+ Here is an <a href="https://github.com/regulaforensics/idv-capture-web-samples/blob/main/webpack/index.js" target="_blank">example of index.js file</a>.
93
82
 
94
- Connect the script in your `.html` file. CDN link: `unpkg.com/:package@:version/:file`
83
+ ## Install via CDN
95
84
 
96
- For example:
85
+ Use a CDN if you don’t have a build process (for example, a plain HTML/JS project). Add the following `script` tags to your `.html` file. The CDN link format is `unpkg.com/:package@:version/:file`:
97
86
 
98
87
  ```html
99
88
  <script src="https://unpkg.com/@regulaforensics/idv-capture-web@latest/dist/main.iife.js"></script>
100
- <script src="https://unpkg.com/@regulaforensics/idv-gui@latest/dist/main.iife.js"></script>
101
89
 
102
90
  <script src="https://unpkg.com/@regulaforensics/idv-face@latest/dist/main.iife.js"></script>
103
91
  <script src="https://unpkg.com/@regulaforensics/idv-document@latest/dist/main.iife.js"></script>
104
-
105
92
  ```
106
93
 
107
- Add the name of the component to the html, as in the example above.
108
-
109
94
  ## Setup
110
95
 
111
- Use `IdvIntegrationService` to setup idv flow.
96
+ The setup process involves four steps: **Initialize → Configure → Prepare → Start**.
112
97
 
113
- General example of the integration step by step
98
+ ### Initialize
114
99
 
115
100
  ```javascript
116
- /** import necessary service & packages */
117
101
  import { IdvIntegrationService } from '@regulaforensics/idv-capture-web';
118
- import { GuiIdv } from "@regulaforensics/idv-gui";
119
- /** depends of your workflow */
120
- import { FaceIdv } from "@regulaforensics/idv-face";
121
- import { DocumentIdv } from "@regulaforensics/idv-document";
102
+ import { FaceIdv } from '@regulaforensics/idv-face';
103
+ import { DocumentIdv } from '@regulaforensics/idv-document';
122
104
 
123
-
124
- /** create service */
125
105
  const service = new IdvIntegrationService();
126
106
 
127
- /** create events listener, which set to the service */
128
- const idvEventListener = (event) => {
129
- console.log(event);
130
- };
107
+ // Event listener
108
+ service.eventListener = (event) => console.log(event);
131
109
 
132
- /** set up service settings */
133
- service.sessionRestoreMode = true;
134
- service.eventListener = idvEventListener;
135
-
136
- /** for convenience, we will use an asynchronous function. You also can use Promises */
137
- (async function () {
138
- /** set modules */
139
- const initResult = await service.initialize({
140
- modulesConfig: { docreader: { devLicense: 'yourBase64license' } },
141
- includedModules: [GuiIdv, FaceIdv, DocumentIdv],
142
- });
143
- /** if something goes wrong, the command error will contain an error field. */
144
- if (initResult.error) {
145
- console.log(initResult.error);
146
- return;
147
- }
148
-
149
- const configureResult = await service.configure({
150
- host: 'https://your.host.com',
151
- userName: '',
152
- password: '',
153
- });
154
-
155
- if (configureResult.error) {
156
- console.log(configureResult.error);
157
- return;
158
- }
159
-
160
- const prepareResult = await service.prepareWorkflow({
161
- workflowId: 'your_workflow_id',
162
- });
163
-
164
- if (prepareResult.error) {
165
- console.log(prepareResult.error);
166
- return;
167
- }
168
-
169
- const metadata = { anyMetadata: 'Any Metadata' };
170
- const locale = 'en-us'; // 'en-us' for example. Should be the language of your workflow
171
- const startWorkflowResult = await service?.startWorkflow({ locale: locale, metadata: metadata });
172
-
173
- if (startWorkflowResult.error) {
174
- console.log(startWorkflowResult.error);
175
- return;
176
- }
177
-
178
- console.log('WORKFLOW FINISHED :', startWorkflowResult);
179
- })();
110
+ // Initialize modules
111
+ const initResult = await service.initialize({
112
+ modulesConfig: { docreader: { devLicense: 'yourBase64license' } }, // For development use only. Do not use it in production.
113
+ includedModules: [FaceIdv, DocumentIdv],
114
+ });
115
+
116
+ if (initResult.error) {
117
+ console.error(initResult.error);
118
+ }
180
119
  ```
181
120
 
182
- ## Events
121
+ ### Configure
122
+
123
+ Use credentials, API key, or token URL.
183
124
 
184
- You can subscribe to the component events.
125
+ **With username/password**
126
+
127
+ ```javascript
128
+ const configureResult = await service.configure({
129
+ baseUrl: 'https://your.host.com',
130
+ userName: '',
131
+ password: '',
132
+ });
133
+ ```
185
134
 
186
- For example:
135
+ **With API key**
187
136
 
188
137
  ```javascript
189
- /** your listener */
190
- const idvEventListener = (event) => {
191
- console.log(event);
192
- };
138
+ const configureResult = await service.configure({
139
+ baseUrl: 'https://your.host.com',
140
+ apiKey: 'yourApiKey',
141
+ ttl: 86400, // Optional. Default is 86400 seconds (24h). You can set a custom TTL in seconds.
142
+ });
143
+ ```
144
+
145
+ **With token URL**
193
146
 
194
- const service = new IdvIntegrationService();
195
- service.eventListener = idvEventListener;
147
+ ```javascript
148
+ const configureResult = await service.configure({
149
+ url: 'your-token-url',
150
+ });
196
151
  ```
197
- ## Setters
198
152
 
199
- `nonce` - set CSP nonce id to the style tag
153
+ ### Prepare Workflow
200
154
 
201
155
  ```javascript
202
- const service = new IdvIntegrationService();
203
- service.nonce = nonceId;
156
+ const prepareResult = await service.prepareWorkflow({
157
+ workflowId: 'your_workflow_id',
158
+ });
159
+
160
+ // Error handling
161
+ if (prepareResult.error) {
162
+ console.error(prepareResult.error);
163
+ }
204
164
  ```
205
165
 
206
- `sessionRestoreMode` - set restore mode to the **idv-capture-web** . restores the session from the current step (for example, if the page was accidentally reloaded)
166
+ ### Start Workflow
207
167
 
208
168
  ```javascript
209
- const service = new IdvIntegrationService();
210
- service.sessionRestoreMode = true;
169
+ const metadata = { anyMetadata: 'Any Metadata' };
170
+ const locale = 'en-us';
171
+
172
+ const startWorkflowResult = await service.startWorkflow({
173
+ locale,
174
+ metadata,
175
+ });
176
+
177
+ // Error handling
178
+ if (startWorkflowResult.error) {
179
+ console.error(startWorkflowResult.error);
180
+ }
181
+
182
+ console.log('WORKFLOW FINISHED:', startWorkflowResult);
211
183
  ```
212
184
 
213
- ## Getters
185
+ ## Events
186
+
187
+ You can subscribe to service events such as status updates, errors, and workflow progress by assigning a listener:
214
188
 
215
- `version` - returns the version of the component
216
189
  ```javascript
217
- const service = new IdvIntegrationService();
218
- console.log(service.version);
190
+ const service = new IdvIntegrationService();
191
+
192
+ // Define your listener
193
+ service.eventListener = (event) => {
194
+ console.log('Event received:', event);
195
+ };
219
196
  ```
220
197
 
221
- ## Methods
198
+ ## Configuration
199
+
200
+ ### Setters
222
201
 
223
- Check types in the `index.d.ts`
202
+ | Setter | Description |
203
+ | -------------------- | --------------------------------------- |
204
+ | `nonce` | Sets a CSP nonce for `<style>` tags. |
205
+ | `sessionRestoreMode` | Restores a session if the page reloads. `false` by default.|
224
206
 
225
- `async initialize(config: InitConfig): Promise<{ error?: BaseInitializationError }>` - initialize the idv-web-capture worker.
207
+ ```javascript
208
+ const service = new IdvIntegrationService();
209
+ service.nonce = 'nonceId';
210
+ service.sessionRestoreMode = true;
211
+ ```
226
212
 
213
+ ### Getters
227
214
 
228
- `async configure(
229
- config: ConnectionConfig | UrlConnectionConfig | ConnectionByApiKeyConfig,
230
- ): Promise<ConfigureCompletion | UrlConfigureCompletion>` - configures the service. accepts input parameters for connecting to the platform
215
+ | Getter | Description |
216
+ | -------------------- | --------------------------------------- |
217
+ | `version` | Returns the version of the component. |
231
218
 
232
- `async getWorkFlows(params?: WorkflowListRequest): Promise<WorkflowListCompletion>` - returns list of available workflows
219
+ ```javascript
220
+ const service = new IdvIntegrationService();
221
+ console.log(service.version);
222
+ ```
223
+
224
+ ## Methods
233
225
 
234
- `async prepareWorkflow({ workflowId }: { workflowId: string }): Promise<PrepareWorkflowCompletion>` - prepared service with workflowId. In this method, the component checks the compatibility of modules and steps in the workflow.
226
+ | Method | Description | Type | Notes |
227
+ | --------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
228
+ | `initialize(config: InitConfig)` | Initializes the service. Returns error if initialization fails. | `async initialize(config: InitConfig): Promise<{ error?: BaseInitializationError }>` | Call this first before any other method. |
229
+ | `configure(config)` | Configures the service with credentials, API key, or token. | `async configure(config: CredentialConnectionConfig \| TokenConnectionConfig \| ApiKeyConnectionConfig): Promise<ConfigureCompletion \| TokenConfigureCompletion>` | Required before preparing a workflow.
230
+ | `getWorkFlows(params?)` | Returns a list of available workflows. | `async getWorkFlows(params?: WorkflowListRequest): Promise<WorkflowListCompletion>` | Useful for dynamically displaying workflows to users. |
231
+ | `prepareWorkflow({ workflowId })` | Prepares the service for the given workflow. Checks module and step compatibility. | `async prepareWorkflow({ workflowId }: { workflowId: string }): Promise<PrepareWorkflowCompletion>` | Must be called after configure. Validates workflow and modules. |
232
+ | `startWorkflow(config?)` | Starts the workflow. Show the web component before running and remove it after completion. | `async startWorkflow(config?: StartWorkflowConfig): Promise<WorkflowCompletion>` | Display the component before calling. Pass locale/metadata if needed. |
233
+ | `deinitialize()` | Deinitializes the service. Run `initialize` again to restart. Recommended after completing work. | `async deinitialize(): Promise<DeinitializeCompletion>` | Clean up resources after finishing a workflow. Use `initialize` to start again. |
235
234
 
236
- `async startWorkflow(config?: StartWorkflowConfig): Promise<WorkflowCompletion>` - this method starts workflow. We recommend showing the web component immediately before executing this method and deleting the web component after the promise of this method resolves.
235
+ ## Examples
237
236
 
238
- `async deinitialize(): Promise<DeinitializeCompletion>` - deinitialize the service. After this command you should run `initialize` method if you want to continue working with the service. We recommend executing this command when you have completed the necessary work on the page.
237
+ You can find examples of using the components on the <a href="https://github.com/regulaforensics/idv-capture-web-samples/" target="_blank">Samples page</a>.