@eka-care/abha-stg 0.1.94 → 0.1.95

package/README.md

@@ -1,13 +1,20 @@
+---
+title: Get Started
+description: "Complete implementation guide for the ABHA[Ayushman Bharat Digital Mission] SDK"
+---
+
 # ABHA SDK Implementation
 
 This guide provides everything you need to integrate the ABHA SDK into your application.
 
 ## Overview
 
-The ABHA SDK allows you to integrate Create ABHA, Login with ABHA flows into your healthcare applications. It provides:
+The ABHA SDK allows you to integrate Create ABHA, Login with ABHA, ABHA Consent Management, ABHA Profile KYC flows into your healthcare applications. It provides:
 
-- **Create ABHA**: Create a new ABHA using Mobile or Aadhaar
-- **Login with ABHA**: Login with ABHA address[PHR Address], ABHA number, Adhaar number or Mobile number linked to your ABHA into your healthcare application.
+- **Create ABHA**: Create a new ABHA using Mobile or Aadhaar.
+- **Login with ABHA**: Login to your exisiting ABHA using PHR Address, ABHA number, Aadhaar number or Mobile number.
+- **ABHA Consent Management**: Manage Consent requests raised by healthcare providers to share medical records securely.
+- **ABHA Profile KYC**: Get your ABHA address KYC verified.
 
 ## Installation
 
@@ -46,7 +53,6 @@ Add the following HTML and script tags to your webpage:
     <!-- Include ABHA SDK JS -->
     <script
       type="module"
-      async
       src="https://unpkg.com/@eka-care/abha/dist/sdk/abha/js/abha.js"
     ></script>
 
@@ -54,31 +60,44 @@ Add the following HTML and script tags to your webpage:
       function mountABHASDK() {
         window.initAbhaApp({
           containerId: "sdk_container",
-        
-         // Pass access token and oid
+          clientId: "ext",
+          theme:{
+              // if you want to customise sdk theme/colors
+             // pass the colors of your organisation design system
+          }
+         // data object 
           data: {
-            accessToken: "<your_access_token>", // Pass the access token you have
-            oid: "<your_oid_if_available>", // Pass if you have the OID
-            orgIcon: "<url_of_your_org_icon>", // Pass the url to your organisation icon which starts with for ex: https://cdn.eka.care/vagus/cl56w6zg3001f0scsaqrh16is.jpg
-            linkToOrgIcon: "<url_of_image_to_link_abha_to_your_org>", // Pass the url of an image which depicts linking abha to your organisation for ex https://cdn.eka.care/vagus/cm6agrs5000090tfwfz984x5b.webp
-          },
+            // pass the required data as per the flow
+           },
 
           // Success callback
-          onSuccess: async (params) => {
-            console.log("ABHA flow completed successfully:", params);
-            // Example: Store ABHA data in your app
-            dispatch({
-              type: "set-only-healthid-data",
-              healthIdData: formatter(params.response.data),
-            });
+          onSuccess: (params) => {
+            console.log("ABHA Registration flow completed successfully:", params);
+          },
+
+          //KYC Successs callback
+          onKYCSuccess: (params) => {
+            console.log("ABHA KYC Verified successfully:", params);
+          },
+
+          //Consent Successs callback
+          onConsentSuccess: (params) => {
+            console.log("ABHA Consent flow completed successfully:", params);
           },
 
           // Error callback
           onError: (params) => {
-            console.error("ABHA flow failed:", params);
-            if (window.EkaAbha) {
-              window.EkaAbha.onAbhaFailure(JSON.stringify(params));
-            }
+            console.error("ABHA SDK failed:", params);
+          },
+          
+          // Abha Close callback
+          onAbhaClose: () => {
+            console.log("ABHA SDK closed");
+          },
+
+          // Skip ABHA callback
+          onSkipAbha: (params) => {
+            console.log("ABHA flow SKIPPED:", params);
           },
         });
       }
@@ -97,35 +116,22 @@ Initializes and renders the ABHA SDK in your specified container.
 | Name          | Type                                    | Required    | Description                                                                                                                                    |
 | ------------- | --------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | `containerId` | `string`                                | ✅           | The HTML element ID where the SDK will mount.                                                                                                  |
-| `data` | `{ accessToken: string; oid?: string; orgIcon?: string; linkToOrgIcon?: string }` | ⚙️ Optional | Configuration data for initializing the ABHA flow. <br/>- accessToken: Pass the access token you have. <br/>- oid: Pass if available. <br/>- orgIcon: URL of your organisation's icon to display inside the SDK url should start with https://. <br/>- linkToOrgIcon: URL of the image representing “Link ABHA to your organisation” url should start with https://. |
-| `onSuccess`   | `(params: AbhaSuccessParams) => void`   | ✅           | Triggered when the user successfully creates or logs in to ABHA.                                                                               |
-| `onError`     | `(params: AbhaErrorParams) => void`     | ✅           | Triggered when an error occurs during the ABHA flow.                                                                                           |
-
-**Example:**
-
-```javascript
-window.initAbhaApp({
-  containerId: "sdk_container",
-  data: {
-    accessToken: "your_access_token_here",
-    oid: "optional_oid_here",
-    orgIcon: "url_of_your_org_icon",
-    linkToOrgIcon: "url_of_image_to_link_abha_to_your_org",
-  },
-  onSuccess: (params) => {
-    console.log("ABHA created successfully!", params);
-  },
-  onError: (error) => {
-    console.error("ABHA flow failed:", error);
-  },
-});
-```
+| `clientId` | `string`                                | ✅           | Provide clientId as `ext`.                                                                                                  |
+| `theme` | `string`                                |  ⚙️ Optional           | Provide theme object with your org design system colors.                                                                                                  |
+| `data` | `{`<br/>`accessToken: string;`<br/>`hipId: string;`<br/>`oid?: string;`<br/>`identifier?: string;`<br/>`identifier_type?: string;`<br/>`consent_id?: string;`<br/>`flow?: string;`<br/>`linkToOrgIcon?: string;`<br/>`orgIconUrl?: string;`<br/>`skipABHAEnable?: boolean;`<br/>`}` | ⚙️ Optional | Configuration data for initializing the ABHA flow. <br/><br/>- <strong>accessToken:</strong> Pass the access token you have generated from [Connect Login ](https://developer.eka.care/api-reference/authorization/client-login) API without the word `Bearer`. <br/>- <strong>hipId:</strong> Pass the HFR ID you have. <br/>- <strong>oid:</strong> Pass oid of patient if available / needed in the flow. <br/>- <strong>identifier:</strong> Pass the login identifier value i.e. mobile number / aadhaar number / phr address / abha number.<br/>- <strong>identifier_type:</strong> Pass the type of identifier which you passed in `identifier` key i.e. "mobile" / "aadhaar_number" / "phr_address" / "abha_number" /. If not known pass undefined.  <br/>- <strong>consent_id:</strong> Pass the consent_id of the consent request raised. <br/>- <strong>flow:</strong> Pass the type of flow for which you want to use SDK for i.e. `abha-kyc` for KYC flow  / `consent` for Consent flow. <br/>- <strong>linkToOrgIcon:</strong> Public CDN URL of the icon representing “Link ABHA to your organisation” url should start with https://. [Example](https://cdn.eka.care/vagus/cm6agrs5000090tfwfz984x5b.webp)<br/>- <strong>orgIconUrl:</strong> Public URL of your organization's logo. It is displayed in specific journey headers url should start with https://. [Example](https://cdn.eka.care/vagus/cm4ml1lwu00000tfs1okl7hs9.webp)<br/>- <strong>skipABHAEnable:</strong> Pass the boolean as true if you want Skip ABHA button to be enabled on login screen. <br/><br/> `keys with ? are optional and needs to be passed as per flow requirement.` |
+| `onSuccess`   | `(params: TOnAbhaSuccessParams) => void`   | ✅           | Triggered when the user successfully creates or logs in to ABHA.                                                                               |
+| `onKYCSuccess`   | `(params: TOnAbhaKycSuccessParams) => void`   | ⚙️ Optional | Triggered when the user KYC verified successfully.
+| `onConsentSuccess`   | `(params: TOnAbhaConsentSuccessParams) => void`   | ⚙️ Optional | Triggered when the consent flow completes successfully.
+| `onError`     | `(params: TOnAbhaFailureParams) => void`     | ✅           | Triggered when an error occurs during the ABHA flow.       
+| `onAbhaClose`     | `() => void`     | ✅           | Triggered when SDK closes.   
+| `onSkipAbha`   | `(params: TOnSkipABHA) => void`   | ⚙️ Optional | Triggered if the ABHA flow is skipped.                                                                                       |
+ 
 
 ## Callback Parameters
 
 ### onSuccess Callback
 
-The onAbhaSuccess callback is triggered when the ABHA flow completes successfully.
+The onSuccess callback is triggered when the ABHA flow completes successfully.
 It returns verified user details and tokens, which can be used to log in or continue the user’s session.
 
 **Callback Signature:**
@@ -137,11 +143,11 @@ onSuccess: (params: TOnAbhaSuccessParams) => void;
 **Type Definitions**
 
 ```typescript
-export type TOnAbhaSuccessParams = {
+type TOnAbhaSuccessParams = {
   response: TAuthVerifyV2Response;
 };
 
-export type TAuthVerifyV2Response = {
+type TAuthVerifyV2Response = {
   skip_state: number;
   method: AUTH_METHOD;
   data?: {
@@ -157,6 +163,38 @@ export type TAuthVerifyV2Response = {
     message: string;
   };
 };
+
+enum AUTH_METHOD {
+  EMAIL = 1,
+  MOBILE = 2,
+  ABHA = 7,
+}
+
+type TProfileRecord = {
+  fln: string;
+  fn: string;
+  mn?: string;
+  ln?: string;
+  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
+  dob?: string;
+  mobile?: string;
+  email?: string;
+  uuid?: string;
+  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
+  pic?: string;
+  as?: string;
+  "dob-valid"?: boolean;
+  "is-d"?: boolean;
+  "is-d-s"?: boolean;
+  "is-p"?: boolean;
+  oid: string;
+  at: string;
+  type?: 1 | 2 | 3 | 4 | 5 | 6;
+  "health-ids"?: Array<string>;
+  abha_number?: string;
+  kyc_verified?: boolean;
+};
+
 ```
 
 **Parameters**
@@ -177,13 +215,91 @@ const onSuccess = (params) => {
 
   alert(`Welcome ${userName}! Your ABHA Number: ${abhaNumber}`);
 
-  // Optionally pass data to native bridge
+  // Optionally pass data to native bridge if available
   if (window.EkaAbha) {
     window.EkaAbha.onAbhaSuccess(JSON.stringify(params));
   }
 };
 ```
 
+### onKYCSuccess Callback
+
+The onKYCSuccess callback is triggered when the ABHA KYC flow completes successfully. 
+It returns a confirmation message indicating that the KYC has been verified.
+
+**Callback Signature:**
+
+```typescript
+onKYCSuccess: (params: TOnAbhaKycSuccessParams) => void;
+```
+
+**Type Definitions**
+
+```typescript
+type TOnAbhaKycSuccess = string;
+```
+
+**Parameters**
+|         | Type                    | Description                                                                                                |
+| ---------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `TOnAbhaKycSuccess` | `string` | A confirmation message from SDK post KYC verification |
+
+
+
+**Example:**
+
+```javascript
+const onKYCSuccess = (params) => {
+  console.log("KYC verification Success:", params);
+
+  alert("KYC was verified successfully!");
+
+  // Optionally pass data to native bridge if available
+  if (window.EkaAbha) {
+    window.EkaAbha.onAbhaKYCSuccess(params);
+  }
+};
+```
+
+### onConsentSuccess Callback
+
+The onConsentSuccess callback is triggered when the ABHA Consent flow completes successfully. 
+It returns a confirmation message indicating that the Consent flow ended successfully.
+
+**Callback Signature:**
+
+```typescript
+onConsentSuccess: (params: TOnAbhaConsentSuccessParams) => void;
+```
+
+**Type Definitions**
+
+```typescript
+type TOnAbhaConsentSuccessParams = string;
+```
+
+**Parameters**
+|         | Type                    | Description                                                                                                |
+| ---------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `TOnAbhaConsentSuccessParams` | `string` | A confirmation message from SDK post Consent flow completion |
+
+
+
+**Example:**
+
+```javascript
+const onConsentSuccess = (params) => {
+  console.log("Consent Flow completed:", params);
+
+  alert("Consent flow completed successfully!");
+
+  // Optionally pass data to native bridge if available
+  if (window.EkaAbha) {
+    window.EkaAbha.onAbhaConsentSuccess(params);
+  }
+};
+```
+
 ### onError Callback
 The onError callback is triggered whenever an ABHA flow fails or is interrupted.
 It provides details about the failure through structured parameters, allowing you to handle or forward the error appropriately (for example, to native apps or monitoring tools).
@@ -202,7 +318,7 @@ type TOnAbhaFailureParams = {
   response?: TAuthVerifyV2Response;
 };
 
-export type TAuthVerifyV2Response = {
+type TAuthVerifyV2Response = {
   skip_state: number;
   method: AUTH_METHOD;
   data?: {
@@ -218,6 +334,38 @@ export type TAuthVerifyV2Response = {
     message: string;
   };
 };
+
+enum AUTH_METHOD {
+  EMAIL = 1,
+  MOBILE = 2,
+  ABHA = 7,
+}
+
+type TProfileRecord = {
+  fln: string;
+  fn: string;
+  mn?: string;
+  ln?: string;
+  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
+  dob?: string;
+  mobile?: string;
+  email?: string;
+  uuid?: string;
+  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
+  pic?: string;
+  as?: string;
+  "dob-valid"?: boolean;
+  "is-d"?: boolean;
+  "is-d-s"?: boolean;
+  "is-p"?: boolean;
+  oid: string;
+  at: string;
+  type?: 1 | 2 | 3 | 4 | 5 | 6;
+  "health-ids"?: Array<string>;
+  abha_number?: string;
+  kyc_verified?: boolean;
+};
+
 ```
 
 **Parameters**
@@ -248,111 +396,161 @@ const onError = (params) => {
 };
 ```
 
-**Suggest Handling**
--Always log the full error response (params) for debugging.
--Display friendly error messages for known error.code values.
--If params.response is present, inspect response.error.message for more detail.
--If integrating with native apps, forward the serialized error object:
+### onAbhaClose Callback
+
+The onAbhaClose callback is triggered when the ABHA SDK flow gets closed. 
+
+**Callback Signature:**
+
+```typescript
+onAbhaClose: () => void;
+```
+
+**Example:**
+
 ```javascript
-window.EkaAbha.onAbhaFailure(JSON.stringify(params));
+const onAbhaClose = () => {
+  console.log("ABHA SDK Closed");
+};
 ```
 
-### Container Styling
-Ensure your container has sufficient space:
-```html
-<div
-  id="sdk_container"
-  style="width: 100%; height: 600px; border: 1px solid #ddd;"
-></div>
+### onSkipAbha Callback
+
+The onSkipAbha callback is triggered when the ABHA SDK flow is skipped. The callback is functional when skipABHAEnable is set to true in the data parameter while initializing the SDK.
+
+**Callback Signature:**
+
+```typescript
+onSkipAbha: (params: TOnSkipABHA) => void;
 ```
 
-## Complete Implementation Example
+**Example:**
 
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>ABHA SDK Complete Example</title>
-    <link
-      rel="stylesheet"
-      href="https://unpkg.com/@eka-care/abha/dist/sdk/abha/css/abha.css"
-    />
-  </head>
-  <body>
-    <h1>ABHA SDK Demo</h1>
+```javascript
+const onSkipAbha = (params) => {
+  console.log("ABHA SDK Skipped:", params);
+};
+```
+**Type Definitions**
 
-    <button onclick="mountABHASDK()">Launch ABHA SDK</button>
+```typescript
+ type IdentifierType = "mobile" | "aadhaar_number" | "abha_number" | "phr_address";
 
-    <div
-      id="sdk_container"
-      style="width: 100%; height: 600px; border: 1px solid #ccc;"
-    ></div>
+ type TOnSkipABHA = {
+  identifier?: string;
+  identifier_type?: IdentifierType[]; // No default value here
+};
+```
 
-    <script
-      type="module"
-      async
-      src="https://unpkg.com/@eka-care/abha/dist/sdk/abha/js/abha.js"
-    ></script>
+**Parameters**
+| Key        | Type                     | Description                                                      |
+| ---------- | ------------------------ | ---------------------------------------------------------------- |
+| `identifier`    | `string?`                | It will be login identifier value filled by user.               |
+| `identifier_type` | `IdentifierType[]?` | It will be type of login identifier. |
 
-    <script>
-      function mountABHASDK() {
-        window.initAbhaApp({
-          containerId: "sdk_container",
-          data: {
-            accessToken: "<your_access_token>", 
-            oid: "<your_oid_if_available>", 
-            orgIcon: "<url_of_your_org_icon>",
-            linkToOrgIcon: "<url_of_image_to_link_abha_to_your_org>",
-          },
-          onSuccess: (params) => {
-            console.log("ABHA flow completed successfully:", params);
-          },
-          onError: (params) => {
-            console.error("ABHA flow failed:", params);
-          },
-        });
-      }
-    </script>
-  </body>
-</html>
+
+**Suggest Handling**
+-Always log the full error response (params) for debugging.
+-Display friendly error messages for known error.code values.
+-If params.response is present, inspect response.error.message for more detail.
+-If integrating with native apps, forward the serialized error object:
+```javascript
+window.EkaAbha.onAbhaFailure(JSON.stringify(params));
 ```
 
-## Type Definitions
+## Customizing the Theme
+The ABHA SDK supports full color-token overriding. You can pass a theme object during initialization to match your application's branding.
+
+### Default Theme Colors
+If no theme is provided, the SDK uses the following default values:
 
 ```typescript
-interface InitAbhaAppParams {
-  containerId: string;
-  data?: {
-    accessToken: string;
-    oid?: string;
-    orgIcon?: string;              
-    linkToOrgIcon?: string;        
-  };
-  onSuccess: (params: AbhaSuccessParams) => void;
-  onError: (params: AbhaErrorParams) => void;
-}
+const defaultAbhaColors = {
+  semantic: {
+    error: '#BD0F0F',
+    warning: '#FCB069',
+    success: '#27B961',
+  },
+  primary: {
+    brand: '#6B5CE0', // Main buttons, radios, and active states
+  },
+  surface: {
+    base: '#FFFFFF',      // Background of pages
+    subtle: '#F2F4F7',    // Card backgrounds
+    muted: '#E4E7EC',     // Dividers and borders
+    strong: '#BEC5D0',
+    success: '#D5F6E2',   // Success background alerts
+    neutral: '#0000000D',
+    danger: '#DD3F3F',
+    abhaCard: '#232477',  // Specific background for the ABHA ID card
+  },
+  content: {
+    primary: '#111B31',   // Heading and main text
+    secondary: '#4B596D', // Subtext
+    muted: '#9EA8B8',     // Disabled or placeholder text
+    success: '#1B7E43',   // Success text
+  },
+  qrCodeColors: {
+      fgColor: '#000000', // Color of the QR code dots
+      bgColor: '#FFFFFF'  // Background of the QR code
+  }
+};
+```
+### Overriding the theme
+To customize the look, add the `theme` key to your `initAbhaApp` configuration:
 
-interface AbhaSuccessParams {
-  response: {
-    data: {
-      abha_number?: string;
-      abha_address?: string;
-      name?: string;
-      gender?: string;
-      yearOfBirth?: string;
-      mobile?: string;
-    };
-  };
-  message: string;
-  status: "SUCCESS";
-}
+```typescript
+window.initAbhaApp({
+  containerId: "sdk_container",
+  clientId: "ext",
+  theme: {
+    primary: {
+      brand: '<your_primary_color', // Change main brand color to bright blue
+    },
+    semantic: {
+      error: '<your_semantic_error_color>',
+      warning: '<your_semantic_warning_color>',
+      success: '<your_semantic_success_color>',
+    },
+    surface: {
+      base: '<your_base_color>',      // Background of pages
+      subtle: '<your_subtle_color>',    // Card backgrounds
+      muted: '<your_muted_color>',     // Dividers and borders
+      strong: '<your_strong_color>',
+      success: '<your_success_color>',   // Success background alerts
+      neutral: '<your_neutral_color>',
+      danger: '<your_danger_color>',
+      abhaCard: '<your_abhaCard_color>',  // Specific background for the ABHA ID card
+    },
+    content: {
+      primary: '<your_content_primary_color>',   // Heading and main text
+      secondary: '<your_content_secondary_color>', // Subtext
+      muted: '<your_content_muted_color>',     // Disabled or placeholder text
+      success: '<your_content_success_color>',   // Success text
+    },
+    qrCodeColors: {
+      fgColor: '<your_qrcode_dot_color>', // Color of the QR code dots
+      bgColor: '<your_qrcode_bg_color>'  // Background of the QR code
+    }
+  },
+  data: {
+    orgIconUrl: "https://your-domain.com/logo.png",
+    // ... rest of your data
+  },
+  onSuccess: (params) => { /* ... */ },
+  onError: (params) => { /* ... */ }
+  ...
+});
+```
 
-interface AbhaErrorParams {
-  status: "FAILED";
-  message: string;
-  error_code?: string;
-  details?: any;
-}
+
+## Container Styling
+Ensure your container has sufficient space:
+```html
+<div
+  id="sdk_container"
+  style="width: 100%; height: 600px; border: 1px solid #ddd;"
+></div>
 ```
 
 ## Troubleshooting
@@ -368,18 +566,27 @@ interface AbhaErrorParams {
 - Verify the SDK JS and CSS are correctly loaded.
 - Check browser console for errors.
 
-#### 2. Callback Not Triggered
+#### 2. APIs Not Being Called
+
+**Problem**: API requests are not triggered after the SDK is mounted.
+
+**Solution**:
+- Ensure that the accessToken is passed correctly (do not include the Bearer prefix) and that the token has not expired.
+- To prevent CORS-related issues, ensure that your domain is whitelisted.
+
+#### 3. Callback Not Triggered
 
-**Problem**: onSuccess or onError isn’t firing.
+**Problem**: onSuccess, onError, onKYCSuccess, onConsentSuccess, onAbhaClose isn’t firing.
 
 **Solution**:
-- Make sure both callbacks are passed as valid functions.
+- Make sure callbacks are passed as valid functions.
 - Avoid race conditions (e.g., calling before SDK fully loads).
 
-#### 3. Styling Issues
+#### 4. Styling Issues
 
 **Problem**: SDK content appears misaligned or clipped.
 
 **Solution**:
 - Give your container a fixed height (e.g., 600px).
-- Ensure no parent element uses overflow: hidden.
+- Ensure no parent element uses overflow: hidden.
+