@healthcloudai/hc-settings-connector 0.0.5 → 0.0.6

package/README.md

@@ -1,24 +1,22 @@
 # Healthcheck Settings Connector
 
-This library provides a client for accessing **user settings and profile-related data**
-from the Healthcheck API.  
+This library provides a client for authenticated user settings, profile image,
+identification, insurance, and dashboard-related flows in Healthcheck.
 It is built on top of the shared Healthcheck HTTP and Login connectors.
+
 ---
 
 ## Features
-1. Retrieve patient dashboard data
-2. Generate a pre-signed URL for user selfie upload
-3. Capture user selfie from uploaded file key
-4. Generate a pre-signed URL for driving license / ID upload
-5. Capture driving license / ID data from uploaded file key
-6. Submit driving license / ID data
-7. Generate a pre-signed URL for insurance upload
-8. Capture insurance data from uploaded file key
-9. Submit user insurance
-10. Retrieve patient insurances
-11. Update user profile image URL
-12. Self deactivate user
-13. Built on shared Healthcheck HttpClient and authentication layer
+1. Retrieve the authenticated patient profile
+2. Retrieve the authenticated patient dashboard
+3. Generate canned upload URLs for selfie, ID, and insurance images
+4. Capture selfie, identification, and insurance documents from uploaded file keys
+5. Update or submit driving license data through the resolved EHR route
+6. Submit patient insurance coverage details
+7. Retrieve patient insurances through the resolved EHR route
+8. Update the stored user image file reference
+9. Deactivate the authenticated user
+10. Built on the shared Healthcheck HttpClient and authentication layer
 
 ---
 
@@ -50,8 +48,8 @@ import { FetchClient } from "@healthcloudai/hc-http";
 const httpClient = new FetchClient();
 const authClient = new HCLoginClient(httpClient);
 
-authClient.configure("tenant-id", "dev");
-await authClient.login("john.doe@test.com", "password");
+authClient.configure("demo-tenant", "dev");
+await authClient.login("john.doe@example.com", "ExamplePassword123!");
 
 const settingsClient = new HCSettingsClient(
   httpClient,
@@ -67,24 +65,120 @@ const settingsClient = new HCSettingsClient(
 
 Public signature: `settingsClient.getUserInfo()`
 
-Returns the current patient profile data.
+Returns the current authenticated patient profile.
 
 ```ts
 const userInfo = await settingsClient.getUserInfo();
 ```
 
+#### Full API request
+
+This method performs an authenticated request internally and does not send a request body.
+
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+{
+  "Data": {
+    "Record": {
+      "ID": "record-id-example",
+      "TenantID": "demo-tenant",
+      "FirstName": "John",
+      "LastName": "Doe",
+      "Email": "john.doe@example.com",
+      "Phone": null,
+      "BirthDate": "0001-01-01T00:00:00",
+      "HasInsurance": false,
+      "HasIDCard": false,
+      "HasSelfie": true,
+      "Address": {
+        "StreetAndNumber": null,
+        "Extension": null,
+        "City": null,
+        "State": null,
+        "PostalCode": null,
+        "Country": null
+      },
+      "Attributes": {
+        "FHIRPatientID": "patient-id-example",
+        "CompositeID": "composite-id-example",
+        "PatientImageURL": "https://storage.example.com/selfie_example.jpeg"
+      },
+      "CompositeID": "composite-id-example",
+      "FHIRID": "fhir-id-example"
+    },
+    "Encounters": null,
+    "EHR": "fhir",
+    "PendingActions": [
+      "ADD_ID",
+      "IMPORT_VITALS"
+    ]
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
 ---
 
 ### Get Dashboard
 
 Public signature: `settingsClient.getDashboard()`
 
-Returns the current patient dashboard response.
+Returns the current authenticated patient dashboard response.
 
 ```ts
 const dashboard = await settingsClient.getDashboard();
 ```
 
+#### Full API request
+
+This method performs an authenticated request internally and does not send a request body.
+
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+{
+  "Data": {
+    "Record": {
+      "ID": "record-id-example",
+      "TenantID": "demo-tenant",
+      "FirstName": "John",
+      "LastName": "Doe",
+      "Email": "john.doe@example.com",
+      "HasInsurance": false,
+      "HasIDCard": false,
+      "HasSelfie": true,
+      "Attributes": {
+        "FHIRPatientID": "patient-id-example",
+        "CompositeID": "composite-id-example",
+        "PatientImageURL": "https://storage.example.com/selfie_example.jpeg"
+      }
+    },
+    "Encounters": [],
+    "EHR": "fhir",
+    "PendingActions": [
+      "ADD_ID",
+      "IMPORT_VITALS"
+    ]
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
 ---
 
 ### Submit Insurance
@@ -92,162 +186,546 @@ const dashboard = await settingsClient.getDashboard();
 Public signature: `settingsClient.submitInsurance(payload)`
 
 Submits patient insurance coverage details.
+The client forwards the provided payload into the backend `Data` wrapper.
 
 ```ts
 await settingsClient.submitInsurance({
   InsurancePackageId: "693245",
-  MemberId: "096304628",
+  MemberId: "member-id-example",
   FirstName: "John",
-  LastName: "Smith",
+  LastName: "Doe",
   Sex: "",
-  Image: "1765886686136.png"
+  Image: "insurancecard_example.jpeg"
 });
 ```
 
+#### Full API request
+
+```json
+{
+  "Data": {
+    "InsurancePackageId": "693245",
+    "MemberId": "member-id-example",
+    "FirstName": "John",
+    "LastName": "Doe",
+    "Sex": "",
+    "Image": "insurancecard_example.jpeg"
+  }
+}
+```
+
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+{
+  "Data": {
+    "InsuranceId": "insurance-id-example",
+    "InsurancePackageId": 693245,
+    "InsurancePolicyHolder": "John Doe",
+    "InsuranceType": "Insurance",
+    "IssueDate": "01/01/2030",
+    "MemberId": "member-id-example",
+    "Image": "insurancecard_example.jpeg"
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
+---
+
 ### Get User Image Canned URL
 
 Public signature: `settingsClient.getUserImageCannedUrl(extension)`
 
-Generates a pre-signed upload URL for a user selfie file.
+Generates a canned upload URL for a user selfie file.
+The connector returns the raw backend response object for the generated file.
+The package does not upload the file bytes for you.
+When you upload to the returned S3 URL, you must preserve any signed headers that the URL expects.
+In live verification, uploads succeeded only when the S3 request included `x-amz-acl: public-read`.
 
 ```ts
-const selfieUpload = await settingsClient.getUserImageCannedUrl("jpg");
+const selfieUpload = await settingsClient.getUserImageCannedUrl("jpeg");
 ```
 
+#### Full API request
+
+```json
+{
+  "Data": {
+    "Extension": "jpeg"
+  }
+}
+```
+
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+{
+  "ImageURL": "https://storage.example.com/selfie_example.jpeg?signature=example",
+  "FileName": "selfie_example.jpeg",
+  "Extension": "jpeg"
+}
+```
+
+---
+
 ### Capture User Photo
 
 Public signature: `settingsClient.captureUserPhoto(fileKey)`
 
-Captures a user selfie through `POST /patient/capture`.
-The client internally sends `Type: "userphoto"` and `FileID: fileKey`.
+Convenience wrapper around the patient capture endpoint.
+The client sends `Type: "userphoto"` and the uploaded file key inside the backend `Data` wrapper.
+This method expects the file to have already been uploaded to the canned URL returned by `getUserImageCannedUrl(...)`.
+If the canned URL requires signed S3 headers, the upload must include them before capture can succeed.
 
 ```ts
 const capturedSelfie = await settingsClient.captureUserPhoto(
-  "selfie_639064123637965380.jpg"
+  "selfie_example.jpeg"
 );
 ```
 
+#### Full API request
+
+```json
+{
+  "Data": {
+    "Type": "userphoto",
+    "FileID": "selfie_example.jpeg"
+  }
+}
+```
+
+#### API response
+
+Direct success response for a selfie image was not verified in the latest live run.
+The same upload prerequisite applies here as for the ID and insurance flows: the file must exist at the canned URL upload target, and any signed S3 headers such as `x-amz-acl: public-read` must be preserved during upload.
+
+---
+
 ### Get Driving License Canned URL
 
 Public signature: `settingsClient.getDrivingLicenseCannedUrl(extension)`
 
-Generates a pre-signed upload URL for a driving license / ID file.
+Generates a canned upload URL for a driving license or identification file.
+The package does not upload the file bytes for you.
+When you upload to the returned S3 URL, you must preserve any signed headers that the URL expects.
+In live verification, uploads succeeded only when the S3 request included `x-amz-acl: public-read`.
 
 ```ts
-const idUpload = await settingsClient.getDrivingLicenseCannedUrl("jpg");
+const idUpload = await settingsClient.getDrivingLicenseCannedUrl("jpeg");
+```
+
+#### Full API request
+
+```json
+{
+  "Data": {
+    "Extension": "jpeg"
+  }
+}
 ```
 
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+{
+  "ImageURL": "https://storage.example.com/idcard_example.jpeg?signature=example",
+  "FileName": "idcard_example.jpeg",
+  "Extension": "jpeg"
+}
+```
+
+---
+
 ### Capture Driving License
 
 Public signature: `settingsClient.captureDrivingLicense(fileKey)`
 
-Captures and extracts patient identification data through `POST /patient/capture`.
-The client internally sends `Type: "identification"` and `FileID: fileKey`.
+Convenience wrapper around the patient capture endpoint.
+The client sends `Type: "identification"` and the uploaded file key inside the backend `Data` wrapper.
+This method expects the file to have already been uploaded to the canned URL returned by `getDrivingLicenseCannedUrl(...)`.
 
 ```ts
 const capturedLicense = await settingsClient.captureDrivingLicense(
-  "idcard_639064123637965380.jpg"
+  "idcard_example.jpeg"
 );
 ```
 
+#### Full API request
+
+```json
+{
+  "Data": {
+    "Type": "identification",
+    "FileID": "idcard_example.jpeg"
+  }
+}
+```
+
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+{
+  "Data": {
+    "CapturedData": {
+      "FirstName": "John",
+      "LastName": "Doe",
+      "StreetAddress": "123 Main St",
+      "City": "Springfield",
+      "ZipCode": "90210",
+      "State": "California",
+      "IssuedDate": "01/01/2024",
+      "ExpiresDate": "01/01/2028",
+      "Dob": "01/01/1990",
+      "IDNumber": null
+    },
+    "IsCaptured": true,
+    "InsurancePackages": null
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
+---
+
 ### Update Driving License
 
 Public signature: `settingsClient.updateDrivingLicense(payload)`
 
-Updates patient driving license data through the wrapper-backed EHR route.
-The client resolves the current patient's `EHR` internally from `authClient.getUserInfo()`
-and sends the payload inside the backend `Data` wrapper.
-`Image` should be the uploaded file key / path, not a raw file.
+Updates patient driving license data through the EHR-backed route.
+The client resolves the current `EHR` internally from `authClient.getUserInfo()` and sends the payload inside the backend `Data` wrapper.
 
 ```ts
 const response = await settingsClient.updateDrivingLicense({
-  Image: "idcard_639064123637965380.jpg"
+  Image: "idcard_example.jpeg"
 });
 ```
 
+#### Full API request
+
+```json
+{
+  "Data": {
+    "Image": "idcard_example.jpeg"
+  }
+}
+```
+
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+{
+  "Data": "true",
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
+`Data` was observed as the string `"true"` in the live test environment after a successful upload and capture flow.
+
 `submitDrivingLicense(payload)` is still available as a backward-compatible alias.
 
+---
+
+### Submit Driving License
+
+Public signature: `settingsClient.submitDrivingLicense(payload)`
+
+Backward-compatible alias for `updateDrivingLicense(payload)`.
+It sends the same request payload and currently calls the same implementation internally.
+
+```ts
+const response = await settingsClient.submitDrivingLicense({
+  Image: "idcard_example.jpeg"
+});
+```
+
+#### Full API request
+
+```json
+{
+  "Data": {
+    "Image": "idcard_example.jpeg"
+  }
+}
+```
+
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+{
+  "Data": "true",
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
+---
+
 ### Get Insurance Canned URL
 
 Public signature: `settingsClient.getInsuranceCannedUrl(extension)`
 
-Generates a pre-signed upload URL for an insurance file.
+Generates a canned upload URL for an insurance file.
+The package does not upload the file bytes for you.
+When you upload to the returned S3 URL, you must preserve any signed headers that the URL expects.
+In live verification, uploads succeeded only when the S3 request included `x-amz-acl: public-read`.
 
 ```ts
-const insuranceUpload = await settingsClient.getInsuranceCannedUrl("jpg");
+const insuranceUpload = await settingsClient.getInsuranceCannedUrl("jpeg");
+```
+
+#### Full API request
+
+```json
+{
+  "Data": {
+    "Extension": "jpeg"
+  }
+}
+```
+
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+{
+  "ImageURL": "https://storage.example.com/insurancecard_example.jpeg?signature=example",
+  "FileName": "insurancecard_example.jpeg",
+  "Extension": "jpeg"
+}
 ```
 
+---
+
 ### Capture Insurance
 
 Public signature: `settingsClient.captureInsurance(fileKey)`
 
-Captures and extracts insurance data through `POST /patient/capture`.
-The client internally sends `Type: "healthinsurance"` and `FileID: fileKey`.
+Convenience wrapper around the patient capture endpoint.
+The client sends `Type: "healthinsurance"` and the uploaded file key inside the backend `Data` wrapper.
+This method expects the file to have already been uploaded to the canned URL returned by `getInsuranceCannedUrl(...)`.
 
 ```ts
 const capturedInsurance = await settingsClient.captureInsurance(
-  "insurance_639064123637965380.jpg"
+  "insurancecard_example.jpeg"
 );
 ```
 
+#### Full API request
+
+```json
+{
+  "Data": {
+    "Type": "healthinsurance",
+    "FileID": "insurancecard_example.jpeg"
+  }
+}
+```
+
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+{
+  "Data": {
+    "CapturedData": {
+      "FirstName": "John",
+      "LastName": "Doe",
+      "MemberId": "member-id-example",
+      "GroupNumber": "group-number-example",
+      "EffectiveDate": "",
+      "RxBIN": "",
+      "RxPCN": "",
+      "RxGRP": "",
+      "Carrier": "Carrier Example"
+    },
+    "IsCaptured": true,
+    "InsurancePackages": null
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
+---
+
 ### Get Insurances
 
 Public signature: `settingsClient.getInsurances()`
 
-Returns patient insurances through the wrapper-backed EHR route.
-The client resolves the current patient's `EHR` internally from `authClient.getUserInfo()`.
+Returns patient insurances through the EHR-backed route.
+The client resolves the current `EHR` internally from `authClient.getUserInfo()`.
 
 ```ts
 const insurances = await settingsClient.getInsurances();
 ```
 
+#### Full API request
+
+This method performs an authenticated request internally and does not send a request body.
+
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+{
+  "Data": [
+    {
+      "InsuranceId": "insurance-id-example",
+      "InsurancePackageId": 693245,
+      "InsurancePolicyHolderFirstName": "John",
+      "InsurancePolicyHolderLastName": "Doe",
+      "InsurancePolicyHolder": "John Doe",
+      "RelationshipToInsured": "Self",
+      "EligibilityStatus": "Active",
+      "InsurancePlanName": " - ",
+      "InsuranceType": "FHIR",
+      "MemberId": "member-id-example",
+      "Image": "insurancecard_example.jpeg"
+    }
+  ],
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
+---
+
 ### Update User Image URL
 
 Public signature: `settingsClient.updateUserImage(fileName)`
 
-Updates the user profile image URL using a file name.
+Updates the stored user image file reference using a file name returned from `getUserImageCannedUrl(...)`.
 
 ```ts
-await settingsClient.updateUserImage("selfie_639064123637965380.jpg");
+const updated = await settingsClient.updateUserImage(
+  "selfie_example.jpeg"
+);
 ```
 
+#### Full API request
+
+```json
+{
+  "Data": {
+    "FileName": "selfie_example.jpeg"
+  }
+}
+```
+
+#### API response
+
+Status:
+
+```txt
+200
+```
+
+```json
+true
+```
+
+---
+
 ### Deactivate User
 
 Public signature: `settingsClient.deactivateUser()`
 
-Deactivates the current user.
+Deactivates the current authenticated user.
 
 ```ts
 await settingsClient.deactivateUser();
 ```
 
----
+#### Full API request
 
-## How It Works
+```json
+{
+  "Data": {}
+}
+```
 
-- **HCLoginClient**
-  - Handles authentication
-  - Resolves base API URL
-  - Provides authorization headers
-  - Resolves the current user's `EHR` for EHR-backed settings methods
+#### API response
 
-- **HttpClient**
-  - Performs all HTTP requests
+This method was not directly verified in the live environment because it would deactivate the authenticated test user.
+The client returns the raw backend response from the authenticated `PUT` request.
 
-- **HCSettingsClient**
-  - Exposes user settings and profile-related endpoints
+---
+
+## How It Works
+
+- `HCLoginClient` handles tenant configuration, authentication, and authenticated headers.
+- `HCSettingsClient` uses the authenticated login client to call patient settings and profile-related endpoints.
+- Canned URL methods return a backend-generated upload URL and file name, but the caller is responsible for uploading the file bytes and preserving any signed S3 headers required by that URL.
+- Capture, insurance, and EHR-backed settings methods all use the authenticated patient context from the shared login client.
+- `getInsurances()`, `updateDrivingLicense()`, and `submitDrivingLicense()` resolve the active patient's `EHR` internally before building the final route.
 
 ---
 
 ## Notes
 
-- `HCLoginClient` must be configured and logged in before calling settings methods
-- `getUserImageCannedUrl()` uses `PUT /patient/image/cannedurl`
-- `getDrivingLicenseCannedUrl()` uses `PUT /patient/id/cannedurl`
-- `getInsuranceCannedUrl()` uses `PUT /patient/insurance/cannedurl`
-- `captureUserPhoto()` sends `Type: "userphoto"` and `FileID` to `/patient/capture`
-- `captureDrivingLicense()` sends `Type: "identification"` and `FileID` to `/patient/capture`
-- `captureInsurance()` sends `Type: "healthinsurance"` and `FileID` to `/patient/capture`
-- `updateDrivingLicense()` and `submitDrivingLicense()` send `{ Data: { Image: fileKey } }`
-- `getInsurances()`, `updateDrivingLicense()` and `submitDrivingLicense()` internally resolve the current patient's `EHR`
-
+- `HCLoginClient` must be configured and logged in before calling settings methods.
+- `getUserImageCannedUrl()`, `getDrivingLicenseCannedUrl()`, and `getInsuranceCannedUrl()` return the backend canned URL response and do not upload the file contents.
+- After requesting a canned URL, the file must be uploaded outside this package before capture methods can succeed.
+- Live verification showed that the S3 upload must preserve signed headers from the canned URL; when `x-amz-acl` was signed, uploads succeeded with `x-amz-acl: public-read`.
+- `captureUserPhoto()` sends `Type: "userphoto"` and `FileID` to the patient capture endpoint.
+- `captureDrivingLicense()` sends `Type: "identification"` and `FileID` to the patient capture endpoint.
+- `captureInsurance()` sends `Type: "healthinsurance"` and `FileID` to the patient capture endpoint.
+- `updateDrivingLicense()` and `submitDrivingLicense()` send `{ "Data": { "Image": "..." } }` to the resolved EHR patient route.
+- `submitDrivingLicense()` is a backward-compatible alias of `updateDrivingLicense()`.
+- `getInsurances()`, `updateDrivingLicense()`, and `submitDrivingLicense()` internally resolve the current patient's `EHR`.
+- Live verification showed the canned URL methods returning `ImageURL`, `FileName`, and `Extension` keys from the backend response.

package/dist/index.d.cts

@@ -3,9 +3,12 @@ import { HttpClient } from '@healthcloudai/hc-http';
 
 type Environment = "dev" | "uat" | "prod";
 interface UserImage {
-    imageUrl: string;
-    fileName: string;
-    extension: string;
+    ImageURL: string;
+    FileName: string;
+    Extension: string;
+    imageUrl?: string;
+    fileName?: string;
+    extension?: string;
 }
 interface UserInfo {
     ID?: string;
@@ -79,7 +82,7 @@ declare class HCSettingsClient {
     getInsurances(): Promise<any>;
     updateDrivingLicense(payload: DrivingLicenseData): Promise<DrivingLicenseResponse>;
     submitDrivingLicense(payload: DrivingLicenseData): Promise<DrivingLicenseResponse>;
-    updateUserImage(fileName: string): Promise<UserImage>;
+    updateUserImage(fileName: string): Promise<any>;
     deactivateUser(): Promise<any>;
     private buildEhrPatientUrl;
     private getResolvedEhr;

package/dist/index.d.ts

@@ -3,9 +3,12 @@ import { HttpClient } from '@healthcloudai/hc-http';
 
 type Environment = "dev" | "uat" | "prod";
 interface UserImage {
-    imageUrl: string;
-    fileName: string;
-    extension: string;
+    ImageURL: string;
+    FileName: string;
+    Extension: string;
+    imageUrl?: string;
+    fileName?: string;
+    extension?: string;
 }
 interface UserInfo {
     ID?: string;
@@ -79,7 +82,7 @@ declare class HCSettingsClient {
     getInsurances(): Promise<any>;
     updateDrivingLicense(payload: DrivingLicenseData): Promise<DrivingLicenseResponse>;
     submitDrivingLicense(payload: DrivingLicenseData): Promise<DrivingLicenseResponse>;
-    updateUserImage(fileName: string): Promise<UserImage>;
+    updateUserImage(fileName: string): Promise<any>;
     deactivateUser(): Promise<any>;
     private buildEhrPatientUrl;
     private getResolvedEhr;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@healthcloudai/hc-settings-connector",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Healthcheck Settings SDK with TypeScript",
   "author": "Healthcheck Systems Inc",
   "license": "MIT",