@regulaforensics/idv-capture-web 3.1.230-rc → 3.1.232-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 +113 -135
  2. package/dist/index.d.ts +27 -1
  3. package/dist/main.iife.js +32 -32
  4. package/dist/main.js +8 -5
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,32 +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
8
  - [Setup](#setup)
9
9
  - [Events](#events)
10
- - [Setters](#setters)
11
- - [Getters](#getters)
10
+ - [Configuration](#configuration)
12
11
  - [Methods](#methods)
12
+ - [Examples](#examples)
13
13
 
14
14
  ---
15
15
 
16
16
  ## Overview
17
17
 
18
- The available component is:
18
+ The available component is `<idv-flow>`.
19
19
 
20
- - `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.
21
21
 
22
- 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
23
23
 
24
- ## Before you start
25
-
26
- Please note that:
27
-
28
- - The components work **only** under the HTTPS protocol on the website.
29
- - 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.
30
26
 
31
27
  ## Compatibility
32
28
 
@@ -38,32 +34,27 @@ Please note that:
38
34
 
39
35
  ## Install via NPM
40
36
 
41
- On the command line, navigate to the root directory of your project:
37
+ If you are starting a new project, initialize it:
42
38
 
43
39
  ```
44
40
  cd /path/to/project
45
- ```
46
-
47
- Run the following command:
48
-
49
- ```
50
41
  npm init
51
42
  ```
52
43
 
53
- Answer the questions in the command line questionnaire.
54
-
55
- Install idv-capture-web:
44
+ Install the main package:
56
45
 
57
46
  ```
58
47
  npm i @regulaforensics/idv-capture-web
48
+ ```
59
49
 
60
- #optionally
50
+ Optionally, install additional modules:
61
51
 
52
+ ```
62
53
  npm i @regulaforensics/idv-face
63
54
  npm i @regulaforensics/idv-document
64
55
  ```
65
56
 
66
- 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.
67
58
 
68
59
  Import `@regulaforensics/idv-capture-web` into your `index.js`:
69
60
 
@@ -71,11 +62,7 @@ Import `@regulaforensics/idv-capture-web` into your `index.js`:
71
62
  import './node_modules/@regulaforensics/idv-capture-web/dist/main.js';
72
63
  ```
73
64
 
74
- In `index.html` connect `index.js` and add the name of the component you want to use. Available components:
75
-
76
- `<idv-flow></idv-flow>`
77
-
78
- For example:
65
+ In `index.html`, add the component and load `index.js`:
79
66
 
80
67
  ```html
81
68
  <!DOCTYPE html>
@@ -91,169 +78,160 @@ For example:
91
78
  </html>
92
79
  ```
93
80
 
94
- ## 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>.
95
82
 
96
- Connect the script in your `.html` file. CDN link: `unpkg.com/:package@:version/:file`
83
+ ## Install via CDN
97
84
 
98
- 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`:
99
86
 
100
87
  ```html
101
88
  <script src="https://unpkg.com/@regulaforensics/idv-capture-web@latest/dist/main.iife.js"></script>
102
89
 
103
90
  <script src="https://unpkg.com/@regulaforensics/idv-face@latest/dist/main.iife.js"></script>
104
91
  <script src="https://unpkg.com/@regulaforensics/idv-document@latest/dist/main.iife.js"></script>
105
-
106
92
  ```
107
93
 
108
- Add the component tag to your HTML, as shown in the example above.
109
-
110
94
  ## Setup
111
95
 
112
- Use `IdvIntegrationService` to setup idv flow.
96
+ The setup process involves four steps: **Initialize → Configure → Prepare → Start**.
113
97
 
114
- General example of the integration step by step
98
+ ### Initialize
115
99
 
116
100
  ```javascript
117
- /** import necessary service */
118
101
  import { IdvIntegrationService } from '@regulaforensics/idv-capture-web';
119
- /** and packages 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 can also use Promises */
137
- (async function () {
138
- /** set modules */
139
- const initResult = await service.initialize({
140
- modulesConfig: { docreader: { devLicense: 'yourBase64license' } },
141
- includedModules: [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
- baseUrl: '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
- **Alternative configure options:**
121
+ ### Configure
122
+
123
+ Use credentials, API key, or token URL.
183
124
 
184
- Using **apiKey**:
125
+ **With username/password**
185
126
 
186
127
  ```javascript
187
128
  const configureResult = await service.configure({
188
- baseUrl: 'https://your.host.com',
189
- apiKey: 'your apiKey',
190
- ttl: 86400,
129
+ baseUrl: 'https://your.host.com',
130
+ userName: '',
131
+ password: '',
191
132
  });
192
133
  ```
193
134
 
194
- Using **url**:
135
+ **With API key**
195
136
 
196
137
  ```javascript
197
138
  const configureResult = await service.configure({
198
- url: 'your url with token',
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.
199
142
  });
200
143
  ```
201
144
 
202
- ## Events
145
+ **With token URL**
203
146
 
204
- You can subscribe to the component events.
147
+ ```javascript
148
+ const configureResult = await service.configure({
149
+ url: 'your-token-url',
150
+ });
151
+ ```
205
152
 
206
- For example:
153
+ ### Prepare Workflow
207
154
 
208
155
  ```javascript
209
- /** your listener */
210
- const idvEventListener = (event) => {
211
- console.log(event);
212
- };
156
+ const prepareResult = await service.prepareWorkflow({
157
+ workflowId: 'your_workflow_id',
158
+ });
213
159
 
214
- const service = new IdvIntegrationService();
215
- service.eventListener = idvEventListener;
160
+ // Error handling
161
+ if (prepareResult.error) {
162
+ console.error(prepareResult.error);
163
+ }
216
164
  ```
217
165
 
218
- ## Setters
219
-
220
- `nonce` - set CSP nonce id to the style tag
166
+ ### Start Workflow
221
167
 
222
168
  ```javascript
223
- const service = new IdvIntegrationService();
224
- service.nonce = nonceId;
225
- ```
169
+ const metadata = { anyMetadata: 'Any Metadata' };
170
+ const locale = 'en-us';
171
+
172
+ const startWorkflowResult = await service.startWorkflow({
173
+ locale,
174
+ metadata,
175
+ });
226
176
 
227
- `sessionRestoreMode` - set restore mode to the **idv-capture-web** . restores the session from the current step (for example, if the page was accidentally reloaded)
177
+ // Error handling
178
+ if (startWorkflowResult.error) {
179
+ console.error(startWorkflowResult.error);
180
+ }
228
181
 
229
- ```javascript
230
- const service = new IdvIntegrationService();
231
- service.sessionRestoreMode = true;
182
+ console.log('WORKFLOW FINISHED:', startWorkflowResult);
232
183
  ```
233
184
 
234
- ## Getters
185
+ ## Events
186
+
187
+ You can subscribe to service events such as status updates, errors, and workflow progress by assigning a listener:
235
188
 
236
- `version` - returns the version of the component
237
189
  ```javascript
238
- const service = new IdvIntegrationService();
239
- 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
+ };
240
196
  ```
241
197
 
242
- ## Methods
198
+ ## Configuration
199
+
200
+ ### Setters
243
201
 
244
- 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.|
206
+
207
+ ```javascript
208
+ const service = new IdvIntegrationService();
209
+ service.nonce = 'nonceId';
210
+ service.sessionRestoreMode = true;
211
+ ```
245
212
 
246
- `async initialize(config: InitConfig): Promise<{ error?: BaseInitializationError }>` - initialize the idv-web-capture worker.
213
+ ### Getters
247
214
 
215
+ | Getter | Description |
216
+ | -------------------- | --------------------------------------- |
217
+ | `version` | Returns the version of the component. |
248
218
 
249
- `async configure(
250
- config: CredentialConnectionConfig | TokenConnectionConfig | ApiKeyConnectionConfig,
251
- ): Promise<ConfigureCompletion | TokenConfigureCompletion>` - configures the service. accepts input parameters for connecting to the platform
219
+ ```javascript
220
+ const service = new IdvIntegrationService();
221
+ console.log(service.version);
222
+ ```
252
223
 
253
- `async getWorkFlows(params?: WorkflowListRequest): Promise<WorkflowListCompletion>` - returns list of available workflows
224
+ ## Methods
254
225
 
255
- `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. |
256
234
 
257
- `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
258
236
 
259
- `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>.
package/dist/index.d.ts CHANGED
@@ -28,7 +28,7 @@ declare class BaseDeinitializationError extends BaseError {
28
28
  });
29
29
  }
30
30
 
31
- declare class BaseError {
31
+ export declare class BaseError {
32
32
  errorCode: number | string;
33
33
  errorCodeKey: string;
34
34
  message?: string;
@@ -68,6 +68,11 @@ declare class BaseInitializationError extends BaseError {
68
68
  });
69
69
  }
70
70
 
71
+ export declare abstract class BaseModule<TModuleProps = unknown, TModulesConfig = unknown> extends HTMLElement {
72
+ abstract props: IdvModuleProps<TModuleProps, TModulesConfig> | null;
73
+ abstract setProps(config: IdvModuleProps<TModuleProps, TModulesConfig>): void;
74
+ }
75
+
71
76
  declare class BasePrepareWorkflowError extends BaseError {
72
77
  private static readonly MODULE;
73
78
  private static readonly ERROR_ENUM_NAME;
@@ -167,6 +172,23 @@ export declare type IdvMessageEvent = {
167
172
  message?: IdvServiceMessages;
168
173
  };
169
174
 
175
+ export declare type IdvModuleProps<TModuleProps, TModulesConfig> = {
176
+ isProcessing?: (isProcessing: boolean) => void;
177
+ moduleProps: TModuleProps;
178
+ modulesConfig?: TModulesConfig;
179
+ perform: (data: any) => void;
180
+ idvEventListener: (module: string, data: any) => void;
181
+ };
182
+
183
+ export declare interface IdvModuleStaticMethods {
184
+ displayName: string;
185
+ isReady(): boolean;
186
+ getSupportedTemplates(): string[];
187
+ initialize(modulesConfig: Record<string, unknown>): void;
188
+ deinitialize(): void;
189
+ getIdentifier(): string;
190
+ }
191
+
170
192
  export declare enum IdvServiceMessages {
171
193
  DID_START_SESSION = "DID_START_SESSION",
172
194
  DID_END_SESSION = "DID_END_SESSION",
@@ -205,6 +227,8 @@ export declare enum InitializeError {
205
227
  INITIALIZATION_IN_PROGRESS = 2
206
228
  }
207
229
 
230
+ export declare type ModuleClass<TModuleProps = unknown, TModulesConfig = unknown> = IdvModuleStaticMethods & (new (...args: any[]) => BaseModule<TModuleProps, TModulesConfig>);
231
+
208
232
  export declare type PrepareWorkflowCompletion = {
209
233
  workflow?: Workflow;
210
234
  error?: BasePrepareWorkflowError;
@@ -218,6 +242,8 @@ export declare enum PrepareWorkflowError {
218
242
  SCENARIO_IN_PROGRESS = 4
219
243
  }
220
244
 
245
+ export declare function registerModule<TModuleProps = unknown, TModulesConfig = unknown>(name: string, ModuleClass: ModuleClass<TModuleProps, TModulesConfig>): void;
246
+
221
247
  export declare enum SessionError {
222
248
  HTTP_ISSUE = 0,
223
249
  PROVIDER_ERROR = 1,