npm package: @healthcloudai/hc-settings-connector
Description: Healthcheck Settings SDK with TypeScript
Author: Healthcheck Systems Inc
Latest version: 0.0.6

# 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.

---

## Features
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

---

## Installation

```sh
npm install @healthcloudai/hc-settings-connector \
@healthcloudai/hc-login-connector \
@healthcloudai/hc-http
```

---

## Import

```ts
import { HCSettingsClient } from "@healthcloudai/hc-settings-connector";
import { HCLoginClient } from "@healthcloudai/hc-login-connector";
import { FetchClient } from "@healthcloudai/hc-http";
```

---

## Usage

### Configuration

```ts
const httpClient = new FetchClient();
const authClient = new HCLoginClient(httpClient);

authClient.configure("demo-tenant", "dev");
await authClient.login("john.doe@example.com", "ExamplePassword123!");

const settingsClient = new HCSettingsClient(
  httpClient,
  authClient
);
```

---

## Methods

### Get User Info

Public signature: `settingsClient.getUserInfo()`

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 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

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: "member-id-example",
  FirstName: "John",
  LastName: "Doe",
  Sex: "",
  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 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("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)`

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_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 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("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)`

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_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 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_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 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("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)`

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(
  "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 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 stored user image file reference using a file name returned from `getUserImageCannedUrl(...)`.

```ts
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 authenticated user.

```ts
await settingsClient.deactivateUser();
```

#### Full API request

```json
{
  "Data": {}
}
```

#### API response

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.

---

## 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()`, `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.