@soyio/soyio-widget 1.0.7 → 1.0.9

package/README.md

@@ -26,22 +26,88 @@ yarn add @soyio/soyio-widget
 
 ## Usage
 
-Integrate the widget into your frontend framework using the script below. Ensure to replace placeholders (e.g., <flow>, <company id>) with actual values relevant to your implementation.
+Integrate the widget into your frontend framework using the script below. Ensure to replace placeholders (e.g., \<flow>, \<company id>) with actual values relevant to your implementation.
+
+### 1. Validation attempt
 
 ```html
 <script>
-  import SoyioWidget from '@soyio/soyio-widget';
+  import { SoyioWidget } from "@soyio/soyio-widget";
 
   // Widget configuration
   const widgetConfig = {
-    flow: "<flow>",
+    flow: "register",
     configProps: {
       companyId: "<company id>",
       userReference: "<user identifier of company>",
       userEmail: "<user email>",
       flowTemplateId: "<flow template id>",
+      forceError: "<error type>",
+      customColor: "<custom color>"
+    },
+    onEvent: (data) => console.log(data),
+    isSandbox: true,
+  };
+
+  // Create widget when needed. In this example, widget is created when page is loaded.
+  document.addEventListener("DOMContentLoaded", function () {
+    new SoyioWidget(widgetConfig);
+  });
+</script>
+```
+
+Optional props:
+
+- `userReference`
+- `userEmail`
+- `forceError`
+- `customColor`.
+
+### 2. Auth attempt
+
+```html
+<script>
+  import { SoyioWidget } from "@soyio/soyio-widget";
+
+  // Widget configuration
+  const widgetConfig = {
+    flow: "authenticate",
+    configProps: {
+      companyId: "<company id>",
+      userReference: "<user identifier of company>",
       identityId: "<identity id>",
       forceError: "<error type>",
+      customColor: "<custom color>",
+    },
+    onEvent: (data) => console.log(data),
+    isSandbox: true,
+  };
+
+  // Create widget when needed. In this example, widget is created when page is loaded.
+  document.addEventListener("DOMContentLoaded", function () {
+    new SoyioWidget(widgetConfig);
+  });
+</script>
+```
+
+Optional props:
+
+- `userReference`
+- `forceError`
+- `customColor`.
+
+### 3. Signature attempt (_coming soon..._)
+
+```html
+<script>
+  import { SoyioWidget } from "@soyio/soyio-widget";
+
+  // Widget configuration
+  const widgetConfig = {
+    flow: "signature",
+    configProps: {
+      signatureAttemptId: "<signature attempt id>",
+      forceError: "<error type>",
       customColor: "<custom color>"
     },
     onEvent: (data) => console.log(data),
@@ -55,35 +121,46 @@ Integrate the widget into your frontend framework using the script below. Ensure
 </script>
 ```
 
-#### Attribute Descriptions
+Optional props:
+
+- `forceError`
+- `customColor`.
+
+### Attribute Descriptions
 
-- **`flow`**: A string that can only take the values `'register'` or `'authenticate'`. Specifies the workflow of the widget.
 - **`companyId`**: The unique identifier for the company, must start with `'com_'`.
-- **`userReference`**: (Optional) A reference identifier provided by the company for the user engaging with the widget. This identifier is used in events (`onEvent` and `webhooks`) to inform the company which user the events are associated with.
-- **`userEmail`**: The user's email address. This field is optional when the flow is `'register'`, where if not provided, Soyio will prompt the user to enter their email. However, for the `'authenticate'` flow, this field should not be provided.
-- **`flowTemplateId`**: Required only in the `'register'` flow, this identifier specifies the order and quantity of documents requested from the user. It must start with `'vt_'`.
-- **`identityId`**: Necessary only in the `'authenticate'` flow, this identifier must start with `'id_'` and signifies the user's identity.
-- **`forceError`**: (Optional) Triggers specific errors for testing or debugging. Used to simulate failure scenarios.
+- **`userReference`**: A reference identifier provided by the company for the user engaging with the widget. This identifier is used in events (`onEvent` and `webhooks`) to inform the company which user the events are associated with.
+- **`userEmail`**: The user's email address. If not provided, Soyio will prompt the user to enter their email.
+- **`flowTemplateId`**: Identifier of template. Specifies the order and quantity of documents requested from the user. It must start with `'vt_'`.
+- **`signatureAttemptId`**: Identifier of signature attempt obtained when creating the `SignatureAttempt`. It must start with `'sa_'`.
+- **`identityId`**: This identifier must start with `'id_'` and signifies the user's identity.
+- **`isSandbox`**: Indicates if the widget should operate in sandbox mode, defaulting to `false`.
+- **`forceError`**: Triggers specific errors for testing or debugging. Used to simulate failure scenarios. Only works in `sandbox` mode.
 - **`onEvent`**: A callback function triggered upon event occurrences, used for capturing and logging event-related data.
-- **`customColor`**: (Optional) A hex code string that specifies the base color of the interface during either the authentication or registration flow.
-- **`isSandbox`**: (Optional) Indicates if the widget should operate in sandbox mode, defaulting to `false`.
+- **`customColor`**: A hex code string that specifies the base color of the interface during either the authentication or registration flow.
 
-#### Events
+### Events
 
 The `onEvent` callback is designed to handle various events that occur during widget interaction. Specifically, it receives detailed information upon the successful completion of user flows. Here are the events it handles:
 
-- **`IDENTITY_REGISTERED`**: This event is dispatched when a user successfully completes the registration flow. The event object contains:
+- **`IDENTITY_REGISTERED`**: This event is dispatched when a user successfully completes the validation attempt. The event object contains:
 
   - `eventName`: The name of the event, in this case, `'IDENTITY_REGISTERED'`.
   - `identityId`: The unique identifier for the newly registered identity.
   - `userReference`: The reference identifier for the user, facilitating the association of the event with the user within the company's context.
 
-- **`IDENTITY_AUTHENTICATED`**: This event occurs when a user successfully completes the authentication flow. The event object includes:
+- **`IDENTITY_AUTHENTICATED`**: This event occurs when a user successfully completes an authentication attempt. The event object includes:
 
   - `eventName`: The name of the event, in this case, `'IDENTITY_AUTHENTICATED'`.
   - `identityId`: The unique identifier for the authenticated identity.
   - `userReference`: The reference identifier for the user, facilitating the association of the event with the user within the company's context.
 
+- **`IDENTITY_SIGNATURE`**: This event occurs when a user successfully completes a signature attempt. The event object includes:
+
+  - `eventName`: The name of the event, in this case, `'IDENTITY_SIGNATURE'`.
+  - `identityId`: The unique identifier for the authenticated identity.
+  - `userReference`: The reference identifier for the user, facilitating the association of the event with the user within the company's context.
+
 - **`DENIED_CAMERA_PERMISSION`**: Event triggered when user denies camera permissions. It closes the widget.
 
 - **`WIDGET_CLOSED`**: This event occurs when the user closes the `Soyio` pop up. The event object is as follows:
@@ -93,13 +170,22 @@ The `onEvent` callback is designed to handle various events that occur during wi
 - **`WIDGET_OPENED`**: This event occurs when the user closes the `Soyio` pop up. The event object is as follows:
   - `{ eventName: 'WIDGET_CLOSED' }`.
 
-#### Error types
+#### Force error types
 
 The `forceError` parameter can simulate the following error conditions:
 
-
 - `'facial_validation_error'`: Simulates a failure in the facial video liveness test, indicating the system could not verify the user's live presence.
 - `'document_validation_error'`: Indicates an issue with validating the photos of the documents provided by the user.
 - `'unknown_error'`: Generates a generic error, representing an unspecified problem.
 - `'expiration_error'`: Occurs when there is an issue with the identity provider that prevents the validation of one or both documents provided by the user, due to unspecified problems in the validation process.
 - `'camera_permission_error'`: Happens when the user does not grant the necessary permissions to access the camera, preventing the completion of the validation flow.
+
+#### Typescript
+
+The `SoyioTypes` module from the `@soyio/soyio-widget` package provides TypeScript type definitions that you can use to integrate the SoyioWidget more seamlessly into your TypeScript projects.
+
+To use the `SoyioTypes` in your project, import it directly from the `@soyio/soyio-widget` package:
+
+```javascript
+import type { SoyioTypes } from "@soyio/soyio-widget";
+```

package/dist/index.d.ts

@@ -1,3 +1,13 @@
+declare type AttemptConfig = ValidationAttemptConfig | AuthAttemptConfig | SignatureAttemptConfig;
+
+declare type AuthAttemptConfig = {
+    flow: 'authenticate';
+    configProps: AuthAttemptProps;
+    onEvent: (data: EventData) => void;
+    isSandbox?: boolean;
+    developmentUrl?: string;
+};
+
 declare type AuthAttemptProps = {
     companyId: string;
     identityId: string;
@@ -6,57 +16,69 @@ declare type AuthAttemptProps = {
     customColor?: string;
 };
 
-declare type ConfigProps = AuthAttemptProps | ValidationAttemptProps;
-
 declare type EventData = {
-    eventName: 'IDENTITY_REGISTERED' | 'IDENTITY_AUTHENTICATED' | 'DENIED_CAMERA_PERMISSION';
+    eventName: 'IDENTITY_REGISTERED' | 'IDENTITY_AUTHENTICATED' | 'IDENTITY_SIGNATURE' | 'DENIED_CAMERA_PERMISSION' | 'REJECTED_SIGNATURE';
     identityId: string;
     userReference?: string;
 };
 
-declare type Flow = 'authenticate' | 'register';
+declare type Flow = 'authenticate' | 'register' | 'signature';
 
 declare type ForceErrors = 'facial_validation_error' | 'document_validation_error' | 'unknown_error' | 'expiration_error' | 'camera_permission_error';
 
+declare type SignatureAttemptConfig = {
+    flow: 'signature';
+    configProps: SignatureAttemptProps;
+    onEvent: (data: EventData) => void;
+    isSandbox?: boolean;
+    developmentUrl?: string;
+};
+
+declare type SignatureAttemptProps = {
+    signatureAttemptId: string;
+    forceError?: ForceErrors;
+    customColor?: string;
+};
+
 declare namespace SoyioTypes {
     export {
         ForceErrors,
         Flow,
         AuthAttemptProps,
         ValidationAttemptProps,
-        ConfigProps,
+        SignatureAttemptProps,
         EventData,
-        WidgetConfig
+        ValidationAttemptConfig,
+        AuthAttemptConfig,
+        SignatureAttemptConfig,
+        AttemptConfig
     }
 }
 export { SoyioTypes }
 
-declare type ValidationAttemptProps = {
-    companyId: string;
-    flowTemplateId: string;
-    userReference?: string;
-    userEmail?: string;
-    forceError?: ForceErrors;
-    customColor?: string;
-};
-
-declare class Widget {
+declare class SoyioWidget {
     #private;
-    private flow;
-    private configProps;
     private onEvent;
-    private isSandbox;
-    constructor(options: SoyioTypes.WidgetConfig);
-    validateProps(): void;
+    constructor(options: SoyioTypes.AttemptConfig);
 }
-export default Widget;
+export { SoyioWidget }
+export default SoyioWidget;
 
-declare type WidgetConfig = {
-    flow: Flow;
-    configProps: ConfigProps;
+declare type ValidationAttemptConfig = {
+    flow: 'register';
+    configProps: ValidationAttemptProps;
     onEvent: (data: EventData) => void;
     isSandbox?: boolean;
     developmentUrl?: string;
 };
 
+declare type ValidationAttemptProps = {
+    companyId: string;
+    flowTemplateId: string;
+    userReference?: string;
+    userEmail?: string;
+    forceError?: ForceErrors;
+    customColor?: string;
+};
+
 export { }