npm package: @healthcloudai/hc-appointments-connector
Description: Healthcheck Appointments  SDK with TypeScript
Author: Healthcheck Systems Inc
Latest version: 0.0.5

# Healthcheck Appointments Connector

This connector handles authenticated appointment flows in Healthcheck: getting available slots, reading user visits, and creating appointments.
It reuses an authenticated `HCLoginClient` and resolves the active patient's `EHR` internally.

## Features

1. Get available appointment slots for the authenticated patient
2. Get user visits and encounter history
3. Create appointments from a slot payload
4. Reuse the authenticated login client for headers and base URL
5. Resolve the patient's `EHR` automatically from the login client

## Installation

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

## Import

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

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

## Methods

### Get Available Slots

Public signature: `appointmentsClient.getAvailableSlots()`

Looks up the authenticated patient's `EHR` internally from `loginClient.getUserInfo()` and returns the available slots for that EHR.

```ts
const slots = await appointmentsClient.getAvailableSlots();
```

#### Full API request

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

#### API response

Status:

```txt
200
```

```json
{
  "Data": {
    "appointmentslots": [
      {
        "AppointmentType": "Follow Up",
        "DepartmentId": null,
        "ProviderId": null,
        "PatientAppointmentTypeName": null,
        "Date": "04/08/2026",
        "AppointmentId": "slot-id-example",
        "AppointmentTypeId": null,
        "Duration": 30,
        "StartTime": "09:00",
        "EndTime": "09:30",
        "LocalProviderId": null
      }
    ],
    "availability": {
      "DATE_04_08_2026": [
        {
          "id": "slot-id-example",
          "time": "09:00 AM - 09:30 AM",
          "appointmenttypeid": "FOLLOWUP",
          "providerid": "default"
        }
      ]
    }
  },
  "ErrorMessage": null,
  "IsOK": true
}
```

### Get User Visits

Public signature: `appointmentsClient.getUserVisits()`

Looks up the authenticated patient's `EHR` internally from `loginClient.getUserInfo()` and returns visits for that patient.

```ts
const visits = await appointmentsClient.getUserVisits();
```

#### Full API request

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

#### API response

Status:

```txt
200
```

```json
{
  "Data": [
    {
      "FHIRID": "encounter-id-example",
      "AthenaID": null,
      "Status": 0,
      "Patient": null,
      "EncounterClass": null,
      "EHR": "fhir",
      "EHRType": "Example Service",
      "EHRVisitName": "Example Visit",
      "EHRAppointmentID": null,
      "EHRProviderID": null,
      "EHRProviderName": null,
      "EHRDate": null,
      "EHRStatus": "InProgress",
      "EHRStage": "virtual"
    }
  ],
  "ErrorMessage": null,
  "IsOK": true
}
```

### Create Appointment

Public signature: `appointmentsClient.createAppointment(payload)`

Sends a booking request to the resolved EHR appointment route.
`payload.slotId` is required and is used to build the booking route.
The rest of the payload is forwarded as-is inside `{ "Data": payload }`.
The method throws if `payload.slotId` is empty.

```ts
await appointmentsClient.createAppointment({
  slotId: "slot-id-example",
  providerId: "default",
  appointmentTypeId: "FOLLOWUP",
  date: "2026-04-08",
  startDateTime: "2026-04-08T09:00:00-07:00",
  endDateTime: "2026-04-08T09:30:00-07:00",
  timeZone: "America/Los_Angeles",
  durationMinutes: 30,
  rawSlot: {
    "id": "slot-id-example",
    "time": "09:00 AM - 09:30 AM",
    "appointmenttypeid": "FOLLOWUP",
    "providerid": "default"
  }
});
```

#### Full API request

```json
{
  "Data": {
    "slotId": "slot-id-example",
    "providerId": "default",
    "appointmentTypeId": "FOLLOWUP",
    "date": "2026-04-08",
    "startDateTime": "2026-04-08T09:00:00-07:00",
    "endDateTime": "2026-04-08T09:30:00-07:00",
    "timeZone": "America/Los_Angeles",
    "durationMinutes": 30,
    "rawSlot": {
      "id": "slot-id-example",
      "time": "09:00 AM - 09:30 AM",
      "appointmenttypeid": "FOLLOWUP",
      "providerid": "default"
    }
  }
}
```

#### API response

Status:

```txt
200
```

```json
{
  "Data": {
    "AppointmentType": "Follow Up",
    "PatientId": "patient-id-example",
    "AppointmentStatus": null,
    "DepartmentId": null,
    "ProviderId": null,
    "PatientAppointmentTypeName": null,
    "Date": "04/08/2026",
    "AppointmentId": "appointment-id-example",
    "AppointmentTypeId": "FOLLOWUP",
    "ChargeEntryNotRequired": false,
    "Duration": 30,
    "StartTime": "09:00 AM",
    "TelehealthDeeplink": null,
    "Expiration": null
  },
  "ErrorMessage": null,
  "IsOK": true
}
```

## How It Works

- `HCLoginClient` handles authentication and authorization headers.
- `HCAppointmentsClient` uses the authenticated login client and shared HTTP client to call appointment endpoints.
- `getAvailableSlots()`, `getUserVisits()`, and `createAppointment()` resolve the active patient's `EHR` internally from `loginClient.getUserInfo()`.
- After the first successful lookup, the resolved `EHR` value is cached on the client instance and reused for later calls.

## Notes

- `HCLoginClient` must be configured and logged in before calling appointment methods.
- Reuse the same authenticated `HCLoginClient` instance when constructing `HCAppointmentsClient`.
- `EHR` is resolved internally from `loginClient.getUserInfo()`.
- The resolved `EHR` is cached after the first successful lookup and reused for later calls on the same client instance.
- `getAvailableSlots()` and `getUserVisits()` are `GET` calls and do not require the caller to build a request body.
- `createAppointment()` throws if `payload.slotId` is empty.
- `createAppointment()` builds the booking route from `slotId` and forwards the rest of the payload inside `{ "Data": payload }`.