Preferred Pharmacy Connector

This connector handles authenticated preferred pharmacy retrieval, pharmacy search, and preferred pharmacy updates.

HCPreferredPharmacyClient reuses an authenticated HCLoginClient instance for:

• authenticated request headers
• tenant context
• environment configuration
• resolved base API URL

Features

1. Retrieve the authenticated patient's preferred pharmacy
2. Search pharmacies using a search phrase
3. Update the authenticated patient's preferred pharmacy
4. Reuse the authenticated HCLoginClient authorization state and API configuration
5. Optionally attach API key headers to Preferred Pharmacy requests

Installation

npm install @healthcloudai/hc-preferred-pharmacy-connector \
@healthcloudai/hc-login-connector \
@healthcloudai/hc-http

Import

import { HCPreferredPharmacyClient } from "@healthcloudai/hc-preferred-pharmacy-connector";
import { HCLoginClient } from "@healthcloudai/hc-login-connector";
import { FetchClient } from "@healthcloudai/hc-http";

Usage

Configuration

const httpClient = new FetchClient();

const authClient = new HCLoginClient(
  httpClient
);

authClient.configure(
  "demo-tenant",
  "dev"
);

await authClient.login(
  "[email protected]",
  "ExamplePassword123!"
);

const preferredPharmacyClient =
  new HCPreferredPharmacyClient(
    httpClient,
    authClient
  );

API Key

Use setApiKey(...) to attach an API key header to requests sent by HCPreferredPharmacyClient.

const apiKey =
  process.env.HEALTHCLOUD_API_KEY;

if (!apiKey) {
  throw new Error(
    "HEALTHCLOUD_API_KEY is required."
  );
}

preferredPharmacyClient.setApiKey(
  "x-api-key",
  apiKey
);

Parameters

| Parameter | Type | Description | |---|---|---| | headerName | string | API key header name | | value | string | API key value |

Note

• Header name should typically be x-api-key.

Methods

Get Preferred Pharmacy

Method Signature

preferredPharmacyClient.listPreferredPharmacies(): Promise<
  APIResponse<PreferredPharmacy[]>
>

Behavior

Returns the authenticated patient's preferred pharmacy records.

Returns

APIResponse<PreferredPharmacy[]>

Usage

const response =
  await preferredPharmacyClient.listPreferredPharmacies();

if (!response.IsOK) {
  console.error(
    response.ErrorMessage
  );

  return;
}

console.log(response.Data);

API Response

{
  "Data": [
    {
      "Name": "Walgreens Pharmacy",
      "FullAddress": "3201 W 6th St, Los Angeles, CA 90020, USA",
      "ClinicalProviderId": "clinical-provider-id-example",
      "NCPDPID": "ncpdpid-example"
    }
  ],
  "ErrorMessage": null,
  "IsOK": true
}

Notes

• The backend currently returns a list of preferred pharmacy records.
• The connector preserves the raw backend response contract.

Search Preferred Pharmacies

Method Signature

preferredPharmacyClient.searchPreferredPharmacies(
  searchPhrase: string
): Promise<
  APIResponse<GooglePlacesSearchResponse>
>

Behavior

Searches pharmacies using a search phrase.

The search phrase may contain:

• pharmacy names
• partial pharmacy names
• cities
• addresses
• general location text

Parameters

| Parameter | Type | Description | |---|---|---| | searchPhrase | string | Search phrase used for pharmacy lookup |

Returns

APIResponse<GooglePlacesSearchResponse>

Usage

const response =
  await preferredPharmacyClient.searchPreferredPharmacies(
    "los"
  );

if (!response.IsOK) {
  console.error(
    response.ErrorMessage
  );

  return;
}

console.log(response.Data);

API Request

{
  "Data": {
    "SearchPhrase": "los"
  }
}

API Response

{
  "Data": {
    "Results": [
      {
        "PlaceId": "place-id-example",
        "Name": "Walgreens Pharmacy",
        "FormattedAddress": "3201 W 6th St, Los Angeles, CA 90020, USA",
        "Geometry": {
          "Location": {
            "Lat": 34.063,
            "Lng": -118.301
          }
        },
        "Types": [
          "pharmacy",
          "health"
        ],
        "BusinessStatus": "OPERATIONAL",
        "Rating": 4.2,
        "UserRatingsTotal": 120,
        "OpeningHours": {
          "OpenNow": true
        }
      }
    ],
    "Status": "OK",
    "ErrorMessage": null
  },
  "ErrorMessage": null,
  "IsOK": true
}

Note

• The API may return multiple pharmacy results.

Update Preferred Pharmacy

Method Signature

preferredPharmacyClient.updatePreferredPharmacy(
  pharmacy: PreferredPharmacy
): Promise<APIResponse<boolean>>

Behavior

Updates the authenticated patient's preferred pharmacy.

Parameters

| Parameter | Type | Description | |---|---|---| | pharmacy | PreferredPharmacy | Preferred pharmacy information |

Returns

APIResponse<boolean>

Usage

const response =
  await preferredPharmacyClient.updatePreferredPharmacy({
    Name: "Walgreens Pharmacy",
    FullAddress:
      "3201 W 6th St, Los Angeles, CA 90020, USA",
    ClinicalProviderId:
      "clinical-provider-id-example",
    NCPDPID:
      "ncpdpid-example"
  });

if (!response.IsOK) {
  console.error(
    response.ErrorMessage
  );

  return;
}

console.log(response.Data);

API Request

{
  "Data": {
    "Name": "Walgreens Pharmacy",
    "FullAddress": "3201 W 6th St, Los Angeles, CA 90020, USA",
    "ClinicalProviderId": "clinical-provider-id-example",
    "NCPDPID": "ncpdpid-example"
  }
}

API Response

{
  "Data": true,
  "ErrorMessage": null,
  "IsOK": true
}

How It Works

HCLoginClient handles:

• tenant configuration
• environment configuration
• authentication
• token management
• authenticated request headers
• base URL resolution

HCPreferredPharmacyClient reuses the authenticated login context for Preferred Pharmacy API requests.

If configured through setApiKey(...), the connector also attaches the configured API key header to Preferred Pharmacy requests.

Notes

• HCLoginClient must be configured and authenticated before calling Preferred Pharmacy methods.
• Reuse the same authenticated HCLoginClient instance when constructing HCPreferredPharmacyClient.
• Public SDK methods do not require consumers to manually provide:
  • Data wrappers
  • authorization headers
  • tenant identifiers
  • resolved service URLs
• The connector returns raw backend APIResponse<T> responses without response transformation or unwrapping.
• Backend-defined failure responses remain part of the returned API contract.

Prerequisites

HCLoginClient must be configured and the patient must be logged in before calling any method on this connector.

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

const httpClient = new FetchClient();
const loginClient = new HCLoginClient(httpClient);

loginClient.configure("healthcheck", "dev");
await loginClient.login("[email protected]", "ExamplePassword123!");

See the hc-login-connector documentation for the full authentication flow.

Error Handling

All methods throw errors that extend APIError from @healthcloudai/hc-http.

Backend business failures (IsOK: false) are thrown as HCServiceError.

import { HCServiceError, APIError } from "@healthcloudai/hc-http";

try {
  const result = await client.someMethod();
} catch (err) {
  if (err instanceof HCServiceError) {
    console.error("Backend error:", err.backendMessage);
  } else if (err instanceof APIError) {
    console.error("SDK error:", err.message, err.code);
  }
}