npm package: @healthcloudai/hc-healthservice-connector
Description: Healthcheck Healthservice SDK with TypeScript
Author: Healthcheck Systems Inc
Latest version: 0.0.4

# Healthcheck Healthservice Connector

This connector retrieves health services, loads questionnaire definitions, and submits questionnaire answers for an authenticated patient.
It uses the shared Healthcheck HTTP client together with an authenticated `HCLoginClient`.

---

## Features

1. List available health services
2. Load questionnaire definitions for a selected health service
3. Submit questionnaire answers
4. Reuse the authenticated login client and shared HttpClient

---

## Installation

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

---

## Import

```ts
import { HCHealthserviceClient } from "@healthcloudai/hc-healthservice-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 healthserviceClient = new HCHealthserviceClient(
  httpClient,
  authClient
);
```

Reuse the same authenticated `HCLoginClient` instance when creating `HCHealthserviceClient` so both connectors share the same auth state.

---

## Methods

### Get Health Services

Public signature: `healthserviceClient.getHealthservices()`

Returns the health services available to the authenticated patient.

```ts
const services = await healthserviceClient.getHealthservices();
```

#### Full API request

This method performs an authenticated request internally and does not send a request body.

#### API response

Status:

```txt
200
```

```json
{
  "Data": [
    {
      "ID": "health-service-id-example",
      "Name": "Oral Herpes (Cold Sores)",
      "ScreeningSNOMEDCode": null,
      "Description": "Example health service description.",
      "ImageURL": "data:image/png;base64,image-data-example",
      "IntroImageURL": null,
      "Category": "Urgent Care",
      "CQLID": null,
      "CQL": null,
      "Documents": [
        "example-document.pdf"
      ],
      "Reasons": [
        {
          "ID": "reason-id-example",
          "Name": "Oral Herpes (Cold Sores)"
        }
      ],
      "Outcomes": [],
      "AlternativeKBSummary": "Example knowledge-base summary text.",
      "ScreeningGenerationAdditionalInstructions": null,
      "CQLGenerationAdditionalInstructions": null,
      "AgentID": null,
      "AdditionalAgentInstructions": null,
      "SelectedAccountIDs": [
        "account-id-example-1",
        "account-id-example-2"
      ],
      "TenantID": null
    }
  ],
  "ErrorMessage": null,
  "IsOK": true
}
```

---

### Get Questionnaire for Health Service

Public signature: `healthserviceClient.getQuestionnaire(healthServiceId)`

Retrieves the questionnaire definition for a specific health service.
Treat the returned questionnaire as the source of truth for rendering questions and preparing the answer payload for submission.

```ts
const questionnaire = await healthserviceClient.getQuestionnaire(
  "health-service-id-example"
);
```

#### Full API request

This method performs an authenticated request internally and does not send a request body.
The client places `healthServiceId` in the request path.

#### API response

Status:

```txt
200
```

```json
{
  "Data": {
    "ID": "health-service-id-example",
    "HealthServiceID": "health-service-id-example",
    "AgentID": null,
    "Title": "Oral Herpes (Cold Sores)",
    "Note": null,
    "HPI": null,
    "Questions": [
      {
        "Question": "Are you currently diagnosed with Oral Herpes?",
        "ID": "Q1",
        "Type": "Boolean",
        "Default": "",
        "Description": null,
        "Next": "Q2",
        "Outcome": null,
        "PossibleAnswers": [],
        "ActualAnswers": null,
        "ImageURLs": null
      },
      {
        "Question": "Have you experienced painful blisters or sores around your mouth?",
        "ID": "Q2",
        "Type": "SingleSelect",
        "Default": "",
        "Description": null,
        "Next": "",
        "Outcome": null,
        "PossibleAnswers": [
          {
            "Text": "Yes",
            "Next": "Q2a",
            "Outcome": null
          },
          {
            "Text": "No",
            "Next": "Q2b",
            "Outcome": null
          }
        ],
        "ActualAnswers": null,
        "ImageURLs": null
      }
    ],
    "Outcome": [
      {
        "Message": "Based on the information you provided, we suggest you schedule a Telehealth appointment with a provider.",
        "Action": "patient/book-appointment",
        "Value": 0,
        "IsDefault": false,
        "ID": null,
        "EncounterID": null
      }
    ],
    "Reasons": [
      {
        "ID": "reason-id-example",
        "Name": "Oral Herpes (Cold Sores)"
      }
    ]
  },
  "ErrorMessage": "",
  "IsOK": true
}
```

---

### Submit Questionnaire

Public signature: `healthserviceClient.submitQuestionnaire(payload)`

Submits questionnaire answers for the selected health service.
Build the payload from the questionnaire structure returned by `getQuestionnaire()`.
The client forwards that payload inside `{ "Data": payload }`.

```ts
await healthserviceClient.submitQuestionnaire({
  Title: "Oral Herpes (Cold Sores)",
  HealthServiceID: "health-service-id-example",
  Questions: [
    {
      Question: "What is your age?",
      ActualAnswers: [
        {
          FHIRID: "",
          Text: "51",
          Outcome: ""
        }
      ]
    },
    {
      Question: "Have you experienced painful blisters or sores around your mouth?",
      ActualAnswers: [
        {
          FHIRID: "",
          Text: "No",
          Outcome: null
        }
      ]
    }
  ],
  Reasons: [
    {
      ID: "reason-id-example",
      Name: "Oral Herpes (Cold Sores)"
    }
  ],
  HPI: ""
});
```

#### Full API request

```json
{
  "Data": {
    "Title": "Oral Herpes (Cold Sores)",
    "HealthServiceID": "health-service-id-example",
    "Questions": [
      {
        "Question": "What is your age?",
        "ActualAnswers": [
          {
            "FHIRID": "",
            "Text": "51",
            "Outcome": ""
          }
        ]
      },
      {
        "Question": "Have you experienced painful blisters or sores around your mouth?",
        "ActualAnswers": [
          {
            "FHIRID": "",
            "Text": "No",
            "Outcome": null
          }
        ]
      }
    ],
    "Reasons": [
      {
        "ID": "reason-id-example",
        "Name": "Oral Herpes (Cold Sores)"
      }
    ],
    "HPI": ""
  }
}
```

#### API response

Status:

```txt
200
```

```json
{
  "Data": {
    "Message": "",
    "Action": null,
    "Value": 0,
    "IsDefault": false,
    "ID": "record-id-example",
    "EncounterID": "encounter-id-example"
  },
  "ErrorMessage": null,
  "IsOK": true
}
```

---

## How It Works

- `HCLoginClient` handles tenant configuration, login, and authenticated headers.
- `HCHealthserviceClient` uses the authenticated login client and shared HTTP client to call health service endpoints.
- Typical usage is: fetch health services, fetch the questionnaire for the selected service, render the questionnaire from the returned definition, then submit answers in the expected backend shape.
- `submitQuestionnaire()` wraps the caller payload inside the backend `Data` envelope before sending it.
- `getHealthservices()` and `getQuestionnaire()` perform authenticated `GET` requests without a request body.

---

## Notes

- `HCLoginClient` must be configured and logged in before calling health service methods.
- Reuse the same authenticated `HCLoginClient` instance when constructing `HCHealthserviceClient`.
- `getQuestionnaire()` returns the questionnaire structure that should drive UI rendering.
- `submitQuestionnaire()` expects a payload compatible with the questionnaire structure returned by `getQuestionnaire()`.
- `getHealthservices()` and `getQuestionnaire()` do not require the caller to build a request body.

---