@healthcloudai/hc-settings-connector 0.0.13 → 0.1.0

package/README.md

@@ -1,21 +1,20 @@
+````md
 # Healthcheck Settings Connector
 
-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.
+This connector gives authenticated patients access to account information and document flows used in your application. It includes dashboard information, profile image management, identification document processing, insurance information, and account deactivation.
+
+`HCSettingsClient` reuses the configured and authenticated `HCLoginClient` for the API base URL and authorization context.
 
 ---
 
 ## Features
-1. Retrieve the authenticated patient dashboard
-2. Generate canned upload URLs for selfie, ID, and insurance images
-3. Submit uploaded identification and insurance file keys for capture
-4. Submit patient insurance coverage details
-5. Retrieve patient insurances
-6. Submit driving license data
-7. Update the stored user image file reference
-8. Deactivate the authenticated user
-9. Built on the shared Healthcheck HttpClient and authentication layer
+
+1. Retrieve dashboard information for the authenticated patient.
+2. Request upload information for patient profile and document images.
+3. Submit uploaded identification and insurance images for capture.
+4. Submit and retrieve insurance information.
+5. Update the patient profile image.
+6. Deactivate the authenticated patient account.
 
 ---
 
@@ -23,16 +22,16 @@ It is built on top of the shared Healthcheck HTTP and Login connectors.
 
 ```sh
 npm install @healthcloudai/hc-settings-connector \
-@healthcloudai/hc-login-connector \
-@healthcloudai/hc-http
-```
+  @healthcloudai/hc-login-connector \
+  @healthcloudai/hc-http
+````
 
 ---
 
 ## Import
 
 ```ts
-import { HCSettingsClient } from "@healthcloudai/hc-settings-connector";
+import { HCSupportClient } from "@healthcloudai/hc-settings-connector";
 import { HCLoginClient } from "@healthcloudai/hc-login-connector";
 import { FetchClient } from "@healthcloudai/hc-http";
 ```
@@ -45,72 +44,72 @@ import { FetchClient } from "@healthcloudai/hc-http";
 
 ```ts
 const httpClient = new FetchClient();
-const authClient = new HCLoginClient(httpClient);
 
-authClient.configure("demo-tenant", "dev");
-await authClient.login("john.doe@example.com", "ExamplePassword123!");
+const loginClient = new HCLoginClient(httpClient);
+
+loginClient.configure("demo-tenant", "dev");
+
+await loginClient.login(
+  "john.doe@example.com",
+  "ExamplePassword123!"
+);
 
 const settingsClient = new HCSettingsClient(
   httpClient,
-  authClient
+  loginClient
 );
 ```
 
----
+`HCLoginClient` must be configured and authenticated before calling Settings methods.
 
+---
 
 ## API Key
 
-Use `setApiKey(...)` to attach an API key header to requests from `HCSettingsClient`.
+Use `setApiKey(...)` when the configured environment requires an API key for Settings requests.
 
 ```ts
 const apiKey = process.env.HEALTHCLOUD_API_KEY;
 
 if (!apiKey) {
-  throw new Error("HEALTHCLOUD_API_KEY is required.");
+  throw new Error(
+    "HEALTHCLOUD_API_KEY is required."
+  );
 }
 
-settingsClient.setApiKey("x-api-key", apiKey);
+settingsClient.setApiKey(
+  "x-api-key",
+  apiKey
+);
 ```
 
-- Header name should be `x-api-key`.
-
-## Methods
-
-The Settings connector methods are grouped by the main usage flow:
-
-1. Dashboard
-2. Profile image upload and update
-3. ID document upload, capture, and submit
-4. Insurance upload, capture, submit, and retrieval
-5. Account actions
+The API key header name should be `x-api-key`.
 
 ---
 
-## Dashboard methods
+## Methods
 
-### Get Dashboard
+# Dashboard
 
-Public signature: `settingsClient.getDashboard()`
+## Get Dashboard
 
-Returns the authenticated patient dashboard.
+Public signature:
 
 ```ts
-const dashboard = await settingsClient.getDashboard();
+settingsClient.getDashboard()
 ```
 
-#### Full API request
+Returns dashboard information associated with the authenticated patient.
 
-This method performs an authenticated request internally and does not send a request body.
-
-#### API response
-
-Status:
+```ts
+const dashboard =
+  await settingsClient.getDashboard();
 
-```txt
-200
+console.log(dashboard);
 ```
 
+### API response
+
 ```json
 {
   "Data": {
@@ -158,41 +157,32 @@ Status:
 
 ---
 
-## Upload and capture flow
+# User Image
 
-Image-related methods follow an upload-first flow. Profile image uses `updateUserImage(...)` after upload, while driver license and insurance use capture methods after upload.
+User image methods allow the patient to upload and update the profile image associated with their account.
 
-1. Request upload information by calling the matching canned URL method.
-2. Upload the file bytes to the returned upload URL outside this package.
-3. Include any signed headers required by the upload URL, such as `x-amz-acl: public-read` when provided.
-4. Submit the returned file name or file key through the matching capture or update method.
+## Get User Image Canned URL
 
-The connector does not upload file bytes. It requests upload information and then submits the uploaded file reference after the upload is complete.
+Public signature:
 
----
-
-## Profile image methods
-
-Profile image methods follow this flow:
-
-1. Call `getUserImageCannedUrl(extension)` to request upload information.
-2. Upload the image file to the returned `ImageURL` outside this package.
-3. Include any signed headers required by the upload URL, such as `x-amz-acl: public-read` when provided.
-4. Call `updateUserImage(fileName)` using the returned `FileName`.
-
-### Get User Image Canned URL
-
-Public signature: `settingsClient.getUserImageCannedUrl(extension)`
-
-Generates upload information for a user profile image.
+```ts
+settingsClient.getUserImageCannedUrl(
+  extension
+)
+```
 
-Use the returned `ImageURL` to upload the image file outside this package. After upload, pass the returned `FileName` to `updateUserImage(...)`.
+Returns upload information for a patient profile image.
 
 ```ts
-const selfieUpload = await settingsClient.getUserImageCannedUrl("jpeg");
+const upload =
+  await settingsClient.getUserImageCannedUrl(
+    "jpeg"
+  );
+
+console.log(upload);
 ```
 
-#### Full API request
+### API request
 
 ```json
 {
@@ -202,13 +192,7 @@ const selfieUpload = await settingsClient.getUserImageCannedUrl("jpeg");
 }
 ```
 
-#### API response
-
-Status:
-
-```txt
-200
-```
+### API response
 
 ```json
 {
@@ -222,23 +206,28 @@ Status:
 }
 ```
 
----
-
-### Update User Image URL
+## Update User Image
 
-Public signature: `settingsClient.updateUserImage(fileName)`
+Public signature:
 
-Updates the stored user image reference using the `FileName` returned by `getUserImageCannedUrl(...)`.
+```ts
+settingsClient.updateUserImage(
+  fileName
+)
+```
 
-Call this method after uploading the image file to the returned `ImageURL`.
+Updates the patient profile image using the uploaded image reference.
 
 ```ts
-const updated = await settingsClient.updateUserImage(
-  "selfie_example.jpeg"
-);
+const updated =
+  await settingsClient.updateUserImage(
+    "selfie_example.jpeg"
+  );
+
+console.log(updated);
 ```
 
-#### Full API request
+### API request
 
 ```json
 {
@@ -248,35 +237,44 @@ const updated = await settingsClient.updateUserImage(
 }
 ```
 
-#### API response
-
-Status:
-
-```txt
-200
-```
+### API response
 
 ```json
-true
+{
+  "Data": true,
+  "IsOK": true,
+  "ErrorMessage": null
+}
 ```
 
 ---
 
-## ID document methods
+# Identification
 
-### Get Driving License Canned URL
+Identification methods allow the patient to upload and process identification document images.
 
-Public signature: `settingsClient.getDrivingLicenseCannedUrl(extension)`
+## Get Driving License Canned URL
 
-Generates upload information for an ID document image.
+Public signature:
 
-Use the returned upload information to upload the image file outside this package. If the upload URL requires signed headers, include them in the upload request.
+```ts
+settingsClient.getDrivingLicenseCannedUrl(
+  extension
+)
+```
+
+Returns upload information for an identification document image.
 
 ```ts
-const idUpload = await settingsClient.getDrivingLicenseCannedUrl("jpeg");
+const upload =
+  await settingsClient.getDrivingLicenseCannedUrl(
+    "jpeg"
+  );
+
+console.log(upload);
 ```
 
-#### Full API request
+### API request
 
 ```json
 {
@@ -286,13 +284,7 @@ const idUpload = await settingsClient.getDrivingLicenseCannedUrl("jpeg");
 }
 ```
 
-#### API response
-
-Status:
-
-```txt
-200
-```
+### API response
 
 ```json
 {
@@ -306,23 +298,28 @@ Status:
 }
 ```
 
----
+## Capture Driving License
 
-### Capture Driving License
+Public signature:
 
-Public signature: `settingsClient.captureDrivingLicense(fileKey)`
-
-Submits the uploaded ID document file key after the image has been uploaded.
+```ts
+settingsClient.captureDrivingLicense(
+  fileKey
+)
+```
 
-This method should be called after uploading the file using the upload information returned by `getDrivingLicenseCannedUrl(...)`.
+Processes the uploaded identification image and returns captured information.
 
 ```ts
-const capturedLicense = await settingsClient.captureDrivingLicense(
-  "idcard_example.jpeg"
-);
+const captured =
+  await settingsClient.captureDrivingLicense(
+    "idcard_example.jpeg"
+  );
+
+console.log(captured);
 ```
 
-#### Full API request
+### API request
 
 ```json
 {
@@ -333,13 +330,7 @@ const capturedLicense = await settingsClient.captureDrivingLicense(
 }
 ```
 
-#### API response
-
-Status:
-
-```txt
-200
-```
+### API response
 
 ```json
 {
@@ -364,21 +355,28 @@ Status:
 }
 ```
 
----
+## Submit Driving License
 
-### Submit Driving License
+Public signature:
 
-Public signature: `settingsClient.submitDrivingLicense(payload)`
+```ts
+settingsClient.submitDrivingLicense(
+  image
+)
+```
 
-Submits patient driving license data.
+Submits the uploaded identification image reference.
 
 ```ts
-const response = await settingsClient.submitDrivingLicense({
-  Image: "idcard_example.jpeg"
-});
+const response =
+  await settingsClient.submitDrivingLicense(
+    "idcard_example.jpeg"
+  );
+
+console.log(response);
 ```
 
-#### Full API request
+### API request
 
 ```json
 {
@@ -388,13 +386,7 @@ const response = await settingsClient.submitDrivingLicense({
 }
 ```
 
-#### API response
-
-Status:
-
-```txt
-200
-```
+### API response
 
 ```json
 {
@@ -405,21 +397,33 @@ Status:
 ```
 
 ---
-## Insurance methods
 
-### Get Insurance Canned URL
+# Insurance
 
-Public signature: `settingsClient.getInsuranceCannedUrl(extension)`
+Insurance methods allow the patient to upload insurance images, process insurance information, and retrieve insurance records.
 
-Generates upload information for an insurance card image.
+## Get Insurance Canned URL
 
-Use the returned upload information to upload the image file outside this package. If the upload URL requires signed headers, include them in the upload request.
+Public signature:
 
 ```ts
-const insuranceUpload = await settingsClient.getInsuranceCannedUrl("jpeg");
+settingsClient.getInsuranceCannedUrl(
+  extension
+)
 ```
 
-#### Full API request
+Returns upload information for an insurance image.
+
+```ts
+const upload =
+  await settingsClient.getInsuranceCannedUrl(
+    "jpeg"
+  );
+
+console.log(upload);
+```
+
+### API request
 
 ```json
 {
@@ -429,13 +433,7 @@ const insuranceUpload = await settingsClient.getInsuranceCannedUrl("jpeg");
 }
 ```
 
-#### API response
-
-Status:
-
-```txt
-200
-```
+### API response
 
 ```json
 {
@@ -449,23 +447,28 @@ Status:
 }
 ```
 
----
-
-### Capture Insurance
+## Capture Insurance
 
-Public signature: `settingsClient.captureInsurance(fileKey)`
+Public signature:
 
-Submits the uploaded insurance file key after the image has been uploaded.
+```ts
+settingsClient.captureInsurance(
+  fileKey
+)
+```
 
-This method should be called after uploading the file using the upload information returned by `getInsuranceCannedUrl(...)`.
+Processes the uploaded insurance image and returns captured information.
 
 ```ts
-const capturedInsurance = await settingsClient.captureInsurance(
-  "insurancecard_example.jpeg"
-);
+const captured =
+  await settingsClient.captureInsurance(
+    "insurancecard_example.jpeg"
+  );
+
+console.log(captured);
 ```
 
-#### Full API request
+### API request
 
 ```json
 {
@@ -476,13 +479,7 @@ const capturedInsurance = await settingsClient.captureInsurance(
 }
 ```
 
-#### API response
-
-Status:
-
-```txt
-200
-```
+### API response
 
 ```json
 {
@@ -506,26 +503,33 @@ Status:
 }
 ```
 
----
+## Submit Insurance
 
-### Submit Insurance
+Public signature:
 
-Public signature: `settingsClient.submitInsurance(payload)`
+```ts
+settingsClient.submitInsurance(
+  coverage
+)
+```
 
-Submits patient insurance coverage details.
+Submits insurance coverage information for the authenticated patient.
 
 ```ts
-await settingsClient.submitInsurance({
-  InsurancePackageId: "693245",
-  MemberId: "member-id-example",
-  FirstName: "John",
-  LastName: "Doe",
-  Sex: "",
-  Image: "insurancecard_example.jpeg"
-});
+const response =
+  await settingsClient.submitInsurance({
+    InsurancePackageId: "693245",
+    MemberId: "member-id-example",
+    FirstName: "John",
+    LastName: "Doe",
+    Sex: "",
+    Image: "insurancecard_example.jpeg"
+  });
+
+console.log(response);
 ```
 
-#### Full API request
+### API request
 
 ```json
 {
@@ -540,13 +544,7 @@ await settingsClient.submitInsurance({
 }
 ```
 
-#### API response
-
-Status:
-
-```txt
-200
-```
+### API response
 
 ```json
 {
@@ -564,30 +562,25 @@ Status:
 }
 ```
 
----
+## Get Insurances
 
-### Get Insurances
-
-Public signature: `settingsClient.getInsurances()`
-
-Returns patient insurances.
+Public signature:
 
 ```ts
-const insurances = await settingsClient.getInsurances();
+settingsClient.getInsurances()
 ```
 
-#### Full API request
-
-This method performs an authenticated request internally and does not send a request body.
-
-#### API response
+Returns insurance records associated with the authenticated patient.
 
-Status:
+```ts
+const insurances =
+  await settingsClient.getInsurances();
 
-```txt
-200
+console.log(insurances);
 ```
 
+### API response
+
 ```json
 {
   "Data": [
@@ -612,33 +605,53 @@ Status:
 
 ---
 
-## Account methods
+# User Photo Capture
+
+User photo capture methods process uploaded patient profile images.
+
+## Capture User Photo
 
-### Deactivate User
+Public signature:
 
-Public signature: `settingsClient.deactivateUser()`
+```ts
+settingsClient.captureUserPhoto(
+  fileKey
+)
+```
 
-Deactivates the current authenticated user.
+Processes the uploaded patient profile image and stores it as the patient user image.
 
 ```ts
-await settingsClient.deactivateUser();
+const response =
+  await settingsClient.captureUserPhoto(
+    "selfie_example.jpeg"
+  );
+
+console.log(response);
 ```
 
-#### Full API request
+### API request
 
 ```json
 {
-  "Data": {}
+  "Data": {
+    "Type": "userphoto",
+    "FileID": "selfie_example.jpeg"
+  }
 }
 ```
 
-#### API response
-
-The client returns the backend response from the authenticated request.
+### API response
 
 ```json
 {
-  "Data": true,
+  "Data": {
+    "CapturedData": {
+      "ImageKey": "patient-image-example.jpeg"
+    },
+    "IsCaptured": true,
+    "InsurancePackages": null
+  },
   "ErrorMessage": null,
   "IsOK": true
 }
@@ -646,24 +659,55 @@ The client returns the backend response from the authenticated request.
 
 ---
 
+# Account
+
+## Deactivate User
+
+Public signature:
+
+```ts
+settingsClient.deactivateUser()
+```
+
+Deactivates the authenticated patient account.
+
+```ts
+const response =
+  await settingsClient.deactivateUser();
+
+console.log(response);
+```
+
+### API response
+
+```json
+{
+  "Data": true,
+  "IsOK": true,
+  "ErrorMessage": null
+}
+```
+
+---
+
 ## How It Works
 
-- `HCLoginClient` handles tenant configuration, authentication, and authenticated headers.
-- `HCSettingsClient` uses the authenticated login client for the base API URL and authenticated request headers.
-- If configured through `setApiKey(...)`, `HCSettingsClient` also includes its configured API key header with Settings connector requests.
-- Profile image methods use `getUserImageCannedUrl(...)` to request upload information and `updateUserImage(...)` to store the uploaded image reference.
-- Upload URL methods return generated upload information. The caller is responsible for uploading the actual file bytes outside this package.
-- Driver license and insurance capture methods submit the uploaded file key after the file has already been uploaded.
+* `HCSettingsClient` uses the configured `HCLoginClient` for the API base URL and authorization context.
+* Public methods only accept the values required from the application.
+* The connector internally creates the backend `APIRequest<T>` request envelope.
+* Image upload methods return upload information only. File uploads are performed outside the connector.
+* Capture methods internally attach the required capture type before sending the request.
 
 ---
 
 ## Notes
 
-- `HCLoginClient` must be configured and logged in before calling Settings connector methods.
-- Canned URL methods return the backend response containing upload information in `Data`.
-- Profile image upload uses `getUserImageCannedUrl(...)` followed by `updateUserImage(...)`.
-- After requesting upload information, the file must be uploaded outside this package before capture methods can succeed.
-- When uploading to the returned storage URL, include any signed headers required by that URL, such as `x-amz-acl: public-read` when provided.
-- `captureDrivingLicense()` sends the ID document file key using `Type: "identification"` and `FileID` inside the request body.
-- `captureInsurance()` sends `Type: "healthinsurance"` and `FileID` inside the request body.
-- `submitDrivingLicense()` submits the driving license data payload.
+* Configure and authenticate `HCLoginClient` before calling Settings methods.
+* Do not pass authorization headers or base URLs manually.
+* Upload image files outside the connector using the returned upload URL.
+* `captureDrivingLicense(...)` internally sends `Type: "identification"`.
+* `captureInsurance(...)` internally sends `Type: "healthinsurance"`.
+* `captureUserPhoto(...)` internally sends `Type: "userphoto"`.
+
+```
+```