@healthcloudai/hc-settings-connector 0.0.14 → 0.2.0

package/README.md

@@ -1,4 +1,3 @@
-````md
 # Healthcheck Settings Connector
 
 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.
@@ -31,7 +30,7 @@ npm install @healthcloudai/hc-settings-connector \
 ## Import
 
 ```ts
-import { HCSupportClient } from "@healthcloudai/hc-settings-connector";
+import { HCSettingsClient } from "@healthcloudai/hc-settings-connector";
 import { HCLoginClient } from "@healthcloudai/hc-login-connector";
 import { FetchClient } from "@healthcloudai/hc-http";
 ```
@@ -114,40 +113,59 @@ console.log(dashboard);
 {
   "Data": {
     "Record": {
-      "Status": 0,
+      "Status": 1,
       "Sex": "Male",
       "GenderIdentity": "Male",
       "HasInsurance": true,
       "HasIDCard": true,
       "HasSelfie": true,
-      "Flags": {
-        "IsVerified": "true",
-        "NeedsInsurance": "false"
-      }
+      "Flags": null,
+      "FirstName": "John",
+      "LastName": "Smith",
+      "MiddleName": null,
+      "BirthDate": "1990-01-01T00:00:00",
+      "Email": "john.smith@example.com",
+      "Phone": "+15555550123",
+      "Gender": "Male",
+      "Race": "White",
+      "Ethnicity": "",
+      "CRMID": null,
+      "AppleUserId": null,
+      "Address": {
+        "StreetAndNumber": "1 Main St",
+        "Extension": null,
+        "City": "Springfield",
+        "State": "IL",
+        "PostalCode": "62701",
+        "Country": "US"
+      },
+      "Attributes": {
+        "AthenaPatientID": "patient-id-example",
+        "AthenaGuarantorFirstName": "John",
+        "AthenaGuarantorLastName": "Smith",
+        "AthenaCountryCode": "USA",
+        "AthenaDepartmentId": "1",
+        "AthenaEmailExists": "True",
+        "AthenaTestPatient": "False",
+        "PatientImageURL": "https://storage.example.com/selfie_example.jpg",
+        "CompositeID": "tenant-id/john.smith@example.com",
+        "Insurance": "EXAMPLE INSURANCE"
+      },
+      "CompositeID": "tenant-id/john.smith@example.com",
+      "FHIRID": "fhir-id-example",
+      "AthenaID": "patient-id-example",
+      "Created": "0001-01-01T00:00:00",
+      "Modified": "0001-01-01T00:00:00",
+      "CreatedByID": null,
+      "ModifiedByID": null,
+      "IsDeactivated": false,
+      "TenantID": "test-tenant",
+      "ID": "record-uuid-example"
     },
-    "Encounters": [
-      {
-        "FHIRID": "test-fhir-id-001",
-        "AthenaID": "test-athena-id-001",
-        "Status": 0,
-        "Patient": null,
-        "EncounterClass": "ambulatory",
-        "EHR": "athena",
-        "EHRType": "Athena Health",
-        "EHRVisitName": "Office Visit",
-        "EHRAppointmentID": "test-appointment-id-001",
-        "EHRProviderID": "test-provider-id-001",
-        "EHRProviderName": "Test Provider",
-        "EHRDate": "04/22/2026",
-        "EHRStatus": "Finished",
-        "EHRStage": "completed"
-      }
-    ],
+    "Encounters": null,
     "EHR": "athena",
     "PendingActions": [
-      "ADD_INSURANCE",
-      "ADD_ID",
-      "IMPORT_VITALS"
+      "TAKE_TEST"
     ]
   },
   "IsOK": true,
@@ -567,14 +585,14 @@ console.log(response);
 Public signature:
 
 ```ts
-settingsClient.getInsurances()
+settingsClient.listInsurances()
 ```
 
 Returns insurance records associated with the authenticated patient.
 
 ```ts
 const insurances =
-  await settingsClient.getInsurances();
+  await settingsClient.listInsurances();
 
 console.log(insurances);
 ```
@@ -711,3 +729,56 @@ console.log(response);
 
 ```
 ```
+
+
+---
+
+## Prerequisites
+
+`HCLoginClient` must be configured and the patient must be logged in before calling any method on this connector.
+
+```ts
+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("patient@example.com", "ExamplePassword123!");
+```
+
+See the [hc-login-connector](../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`.
+
+```ts
+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);
+  }
+}
+```
+
+
+---
+
+## getDashboard vs getPatientHeader
+
+`HCSettingsClient.getDashboard()` calls `/api/patient/dashboard` and returns a full patient dashboard including record, encounters, EHR type, and pending actions.
+
+`HCLoginClient.getPatientHeader()` calls `/api/patient/header` and returns a lighter patient header used after login to quickly check patient state.
+
+These are different endpoints returning different data shapes. Neither is a duplicate of the other.

package/dist/index.cjs

@@ -20,277 +20,253 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  AuthError: () => AuthError,
-  ConfigError: () => ConfigError,
+  APIError: () => import_hc_http2.APIError,
+  ConfigError: () => import_hc_http2.ConfigError,
+  HCServiceError: () => import_hc_http2.HCServiceError,
   HCSettingsClient: () => HCSettingsClient,
-  HttpError: () => HttpError,
-  UserStatus: () => UserStatus
+  NetworkError: () => import_hc_http2.NetworkError,
+  UserStatus: () => UserStatus,
+  ValidationError: () => import_hc_http2.ValidationError
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/errors.ts
-var ConfigError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ConfigError";
-  }
-};
-var AuthError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "AuthError";
-  }
-};
-var HttpError = class extends Error {
-  constructor(status, message) {
-    super(message);
-    this.name = "HttpError";
-    this.status = status;
-  }
-};
-
 // src/client.ts
-var HCSettingsClient = class {
+var import_hc_http = require("@healthcloudai/hc-http");
+var HCSettingsClient = class extends import_hc_http.HCBaseConnector {
   constructor(httpClient, loginClient) {
-    this.httpClient = httpClient;
-    this.loginClient = loginClient;
-  }
-  setApiKey(headerName, value) {
-    const trimmedHeaderName = headerName == null ? void 0 : headerName.trim();
-    const trimmedValue = value == null ? void 0 : value.trim();
-    if (!trimmedHeaderName) {
-      throw new ConfigError(
-        "API key header name is required."
-      );
-    }
-    if (!trimmedValue) {
-      throw new ConfigError(
-        "API key value is required."
-      );
-    }
-    this.apiKeyHeaderName = trimmedHeaderName;
-    this.apiKeyValue = trimmedValue;
+    super(httpClient);
+    this.auth = loginClient;
   }
   // ===========================================================================
   // Dashboard
   // ===========================================================================
+  /**
+   * Returns the patient dashboard including record, encounters, and pending actions.
+   */
   async getDashboard() {
-    return this.httpClient.get(
-      `${this.getBaseUrl()}/patient/dashboard`,
-      this.getAuthHeaders()
+    return this.execute(
+      "getDashboard",
+      () => this.http.get(
+        `${this.auth.getBaseUrl()}/api/patient/dashboard`,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
   // User image
   // ===========================================================================
+  /**
+   * Returns a canned (pre-signed) URL for uploading the patient profile image.
+   * Extension must be a valid file extension such as "jpg" or "png".
+   */
   async getUserImageCannedUrl(extension) {
-    const resolvedExtension = this.requireValue(
-      extension,
-      "extension"
-    );
+    const resolvedExtension = this.requireValue(extension, "Extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/image/cannedurl`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "getUserImageCannedUrl",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/image/cannedurl`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
+  /**
+   * Updates the patient's profile image by confirming the uploaded file name.
+   */
   async updateUserImage(fileName) {
-    const resolvedFileName = this.requireValue(
-      fileName,
-      "fileName"
-    );
+    const resolvedFileName = this.requireValue(fileName, "File name");
     const requestPayload = {
-      Data: {
-        FileName: resolvedFileName
-      }
+      Data: { FileName: resolvedFileName }
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/image/url`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "updateUserImage",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/image/url`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
   // Identification
   // ===========================================================================
+  /**
+   * Returns a canned URL for uploading the patient's driving licence image.
+   */
   async getDrivingLicenseCannedUrl(extension) {
-    const resolvedExtension = this.requireValue(
-      extension,
-      "extension"
-    );
+    const resolvedExtension = this.requireValue(extension, "Extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/id/cannedurl`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "getDrivingLicenseCannedUrl",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/id/cannedurl`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
+  /**
+   * Submits a driving licence file for OCR capture.
+   * fileKey is the storage key of the uploaded image.
+   */
   async captureDrivingLicense(fileKey) {
-    const resolvedFileKey = this.requireValue(
-      fileKey,
-      "fileKey"
-    );
+    const resolvedFileKey = this.requireValue(fileKey, "File key");
     const requestPayload = {
-      Data: {
-        Type: "identification",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "identification", FileID: resolvedFileKey }
     };
-    return this.httpClient.post(
-      `${this.getBaseUrl()}/patient/capture`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "captureDrivingLicense",
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
+  /**
+   * Submits a base64-encoded driving licence image to the EHR.
+   */
   async submitDrivingLicense(image) {
-    const resolvedImage = this.requireValue(
-      image,
-      "image"
-    );
+    const resolvedImage = this.requireValue(image, "Image");
     const requestPayload = {
-      Data: {
-        Image: resolvedImage
-      }
+      Data: { Image: resolvedImage }
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/ehr/patient/drivinglicense`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "submitDrivingLicense",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/ehr/patient/drivinglicense`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
   // Insurance
   // ===========================================================================
+  /**
+   * Returns a canned URL for uploading the insurance card image.
+   */
   async getInsuranceCannedUrl(extension) {
-    const resolvedExtension = this.requireValue(
-      extension,
-      "extension"
-    );
+    const resolvedExtension = this.requireValue(extension, "Extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/insurance/cannedurl`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "getInsuranceCannedUrl",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/insurance/cannedurl`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
+  /**
+   * Submits an insurance card image for OCR capture.
+   * fileKey is the storage key of the uploaded image.
+   */
   async captureInsurance(fileKey) {
-    const resolvedFileKey = this.requireValue(
-      fileKey,
-      "fileKey"
-    );
+    const resolvedFileKey = this.requireValue(fileKey, "File key");
     const requestPayload = {
-      Data: {
-        Type: "healthinsurance",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "healthinsurance", FileID: resolvedFileKey }
     };
-    return this.httpClient.post(
-      `${this.getBaseUrl()}/patient/capture`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "captureInsurance",
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
+  /**
+   * Creates or updates the patient's insurance coverage record.
+   */
   async submitInsurance(coverage) {
     if (!coverage) {
-      throw new ConfigError(
-        "Insurance coverage data is required."
-      );
+      throw new import_hc_http.ValidationError({
+        message: "Insurance coverage data is required.",
+        code: "INVALID_INPUT",
+        param: "coverage"
+      });
     }
     const requestPayload = {
       Data: coverage
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/coverage`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "submitInsurance",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/coverage`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
-  async getInsurances() {
-    return this.httpClient.get(
-      `${this.getBaseUrl()}/ehr/patient/insurances`,
-      this.getAuthHeaders()
+  /**
+   * Returns all insurance records for the authenticated patient.
+   */
+  async listInsurances() {
+    return this.execute(
+      "listInsurances",
+      () => this.http.get(
+        `${this.auth.getBaseUrl()}/api/ehr/patient/insurances`,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
   // User photo capture
   // ===========================================================================
+  /**
+   * Submits a user photo (selfie) for capture.
+   * fileKey is the storage key of the uploaded image.
+   */
   async captureUserPhoto(fileKey) {
-    const resolvedFileKey = this.requireValue(
-      fileKey,
-      "fileKey"
-    );
+    const resolvedFileKey = this.requireValue(fileKey, "File key");
     const requestPayload = {
-      Data: {
-        Type: "userphoto",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "userphoto", FileID: resolvedFileKey }
     };
-    return this.httpClient.post(
-      `${this.getBaseUrl()}/patient/capture`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "captureUserPhoto",
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
   // Account
   // ===========================================================================
-  async deactivateUser() {
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/deactivate`,
-      void 0,
-      this.getJsonHeaders()
+  /**
+   * Soft-deactivates the current patient account.
+   * The patient record is not permanently deleted.
+   */
+  async deactivateCurrentPatient() {
+    return this.execute(
+      "deactivateCurrentPatient",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/deactivate`,
+        void 0,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
-  // Helpers
+  // Private
   // ===========================================================================
-  getBaseUrl() {
-    return this.loginClient.getBaseUrl();
-  }
   getAuthHeaders() {
-    return {
-      ...this.loginClient.getAuthHeader(),
-      ...this.getApiKeyHeader()
-    };
-  }
-  getJsonHeaders() {
-    return {
-      ...this.getAuthHeaders(),
-      "Content-Type": "application/json"
-    };
-  }
-  getApiKeyHeader() {
-    if (!this.apiKeyHeaderName || !this.apiKeyValue) {
-      return {};
-    }
-    return {
-      [this.apiKeyHeaderName]: this.apiKeyValue
-    };
-  }
-  requireValue(value, parameterName) {
-    const trimmedValue = value == null ? void 0 : value.trim();
-    if (!trimmedValue) {
-      throw new ConfigError(
-        `${parameterName} is required.`
-      );
-    }
-    return trimmedValue;
+    return { ...this.getHeaders(), ...this.auth.getAuthHeader() };
   }
 };
 
+// src/errors.ts
+var import_hc_http2 = require("@healthcloudai/hc-http");
+
 // src/types.ts
 var UserStatus = /* @__PURE__ */ ((UserStatus2) => {
   UserStatus2[UserStatus2["INACTIVE"] = 0] = "INACTIVE";
@@ -300,9 +276,11 @@ var UserStatus = /* @__PURE__ */ ((UserStatus2) => {
 })(UserStatus || {});
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  AuthError,
+  APIError,
   ConfigError,
+  HCServiceError,
   HCSettingsClient,
-  HttpError,
-  UserStatus
+  NetworkError,
+  UserStatus,
+  ValidationError
 });

package/dist/index.d.cts

@@ -1,14 +1,7 @@
 import { HCLoginClient } from '@healthcloudai/hc-login-connector';
-import { HttpClient } from '@healthcloudai/hc-http';
+import { HCBaseConnector, HttpClient, APIResponse } from '@healthcloudai/hc-http';
+export { APIError, APIResponse, ConfigError, HCServiceError, NetworkError, ValidationError } from '@healthcloudai/hc-http';
 
-interface APIRequest<T> {
-    Data: T;
-}
-interface APIResponse<T> {
-    Data: T | null;
-    IsOK: boolean;
-    ErrorMessage: string | null;
-}
 interface UserImage {
     ImageURL: string | null;
     FileName: string | null;
@@ -120,41 +113,63 @@ interface InsuranceRecord {
     Image?: string | null;
 }
 
-declare class HCSettingsClient {
-    private readonly httpClient;
-    private readonly loginClient;
-    private apiKeyHeaderName?;
-    private apiKeyValue?;
+declare class HCSettingsClient extends HCBaseConnector {
+    private readonly auth;
     constructor(httpClient: HttpClient, loginClient: HCLoginClient);
-    setApiKey(headerName: string, value: string): void;
+    /**
+     * Returns the patient dashboard including record, encounters, and pending actions.
+     */
     getDashboard(): Promise<APIResponse<PatientDashboard>>;
+    /**
+     * Returns a canned (pre-signed) URL for uploading the patient profile image.
+     * Extension must be a valid file extension such as "jpg" or "png".
+     */
     getUserImageCannedUrl(extension: string): Promise<APIResponse<UserImage>>;
+    /**
+     * Updates the patient's profile image by confirming the uploaded file name.
+     */
     updateUserImage(fileName: string): Promise<APIResponse<boolean>>;
+    /**
+     * Returns a canned URL for uploading the patient's driving licence image.
+     */
     getDrivingLicenseCannedUrl(extension: string): Promise<APIResponse<UserImage>>;
+    /**
+     * Submits a driving licence file for OCR capture.
+     * fileKey is the storage key of the uploaded image.
+     */
     captureDrivingLicense(fileKey: string): Promise<APIResponse<CaptureResult<IdentificationCaptureData>>>;
+    /**
+     * Submits a base64-encoded driving licence image to the EHR.
+     */
     submitDrivingLicense(image: string): Promise<APIResponse<string>>;
+    /**
+     * Returns a canned URL for uploading the insurance card image.
+     */
     getInsuranceCannedUrl(extension: string): Promise<APIResponse<UserImage>>;
+    /**
+     * Submits an insurance card image for OCR capture.
+     * fileKey is the storage key of the uploaded image.
+     */
     captureInsurance(fileKey: string): Promise<APIResponse<CaptureResult<InsuranceCaptureData>>>;
+    /**
+     * Creates or updates the patient's insurance coverage record.
+     */
     submitInsurance(coverage: CoverageData): Promise<APIResponse<InsuranceRecord>>;
-    getInsurances(): Promise<APIResponse<InsuranceRecord[]>>;
+    /**
+     * Returns all insurance records for the authenticated patient.
+     */
+    listInsurances(): Promise<APIResponse<InsuranceRecord[]>>;
+    /**
+     * Submits a user photo (selfie) for capture.
+     * fileKey is the storage key of the uploaded image.
+     */
     captureUserPhoto(fileKey: string): Promise<APIResponse<CaptureResult<UserPhotoCaptureData>>>;
-    deactivateUser(): Promise<APIResponse<boolean>>;
-    private getBaseUrl;
+    /**
+     * Soft-deactivates the current patient account.
+     * The patient record is not permanently deleted.
+     */
+    deactivateCurrentPatient(): Promise<APIResponse<boolean>>;
     private getAuthHeaders;
-    private getJsonHeaders;
-    private getApiKeyHeader;
-    private requireValue;
-}
-
-declare class ConfigError extends Error {
-    constructor(message: string);
-}
-declare class AuthError extends Error {
-    constructor(message: string);
-}
-declare class HttpError extends Error {
-    status: number;
-    constructor(status: number, message: string);
 }
 
-export { type APIRequest, type APIResponse, AuthError, type CaptureResult, type CaptureType, ConfigError, type CoverageData, type Encounter, HCSettingsClient, HttpError, type IdentificationCaptureData, type InsuranceCaptureData, type InsuranceRecord, type PatientDashboard, type PatientRecord, type UserImage, type UserPhotoCaptureData, UserStatus };
+export { type CaptureResult, type CaptureType, type CoverageData, type Encounter, HCSettingsClient, type IdentificationCaptureData, type InsuranceCaptureData, type InsuranceRecord, type PatientDashboard, type PatientRecord, type UserImage, type UserPhotoCaptureData, UserStatus };

package/dist/index.d.ts

@@ -1,14 +1,7 @@
 import { HCLoginClient } from '@healthcloudai/hc-login-connector';
-import { HttpClient } from '@healthcloudai/hc-http';
+import { HCBaseConnector, HttpClient, APIResponse } from '@healthcloudai/hc-http';
+export { APIError, APIResponse, ConfigError, HCServiceError, NetworkError, ValidationError } from '@healthcloudai/hc-http';
 
-interface APIRequest<T> {
-    Data: T;
-}
-interface APIResponse<T> {
-    Data: T | null;
-    IsOK: boolean;
-    ErrorMessage: string | null;
-}
 interface UserImage {
     ImageURL: string | null;
     FileName: string | null;
@@ -120,41 +113,63 @@ interface InsuranceRecord {
     Image?: string | null;
 }
 
-declare class HCSettingsClient {
-    private readonly httpClient;
-    private readonly loginClient;
-    private apiKeyHeaderName?;
-    private apiKeyValue?;
+declare class HCSettingsClient extends HCBaseConnector {
+    private readonly auth;
     constructor(httpClient: HttpClient, loginClient: HCLoginClient);
-    setApiKey(headerName: string, value: string): void;
+    /**
+     * Returns the patient dashboard including record, encounters, and pending actions.
+     */
     getDashboard(): Promise<APIResponse<PatientDashboard>>;
+    /**
+     * Returns a canned (pre-signed) URL for uploading the patient profile image.
+     * Extension must be a valid file extension such as "jpg" or "png".
+     */
     getUserImageCannedUrl(extension: string): Promise<APIResponse<UserImage>>;
+    /**
+     * Updates the patient's profile image by confirming the uploaded file name.
+     */
     updateUserImage(fileName: string): Promise<APIResponse<boolean>>;
+    /**
+     * Returns a canned URL for uploading the patient's driving licence image.
+     */
     getDrivingLicenseCannedUrl(extension: string): Promise<APIResponse<UserImage>>;
+    /**
+     * Submits a driving licence file for OCR capture.
+     * fileKey is the storage key of the uploaded image.
+     */
     captureDrivingLicense(fileKey: string): Promise<APIResponse<CaptureResult<IdentificationCaptureData>>>;
+    /**
+     * Submits a base64-encoded driving licence image to the EHR.
+     */
     submitDrivingLicense(image: string): Promise<APIResponse<string>>;
+    /**
+     * Returns a canned URL for uploading the insurance card image.
+     */
     getInsuranceCannedUrl(extension: string): Promise<APIResponse<UserImage>>;
+    /**
+     * Submits an insurance card image for OCR capture.
+     * fileKey is the storage key of the uploaded image.
+     */
     captureInsurance(fileKey: string): Promise<APIResponse<CaptureResult<InsuranceCaptureData>>>;
+    /**
+     * Creates or updates the patient's insurance coverage record.
+     */
     submitInsurance(coverage: CoverageData): Promise<APIResponse<InsuranceRecord>>;
-    getInsurances(): Promise<APIResponse<InsuranceRecord[]>>;
+    /**
+     * Returns all insurance records for the authenticated patient.
+     */
+    listInsurances(): Promise<APIResponse<InsuranceRecord[]>>;
+    /**
+     * Submits a user photo (selfie) for capture.
+     * fileKey is the storage key of the uploaded image.
+     */
     captureUserPhoto(fileKey: string): Promise<APIResponse<CaptureResult<UserPhotoCaptureData>>>;
-    deactivateUser(): Promise<APIResponse<boolean>>;
-    private getBaseUrl;
+    /**
+     * Soft-deactivates the current patient account.
+     * The patient record is not permanently deleted.
+     */
+    deactivateCurrentPatient(): Promise<APIResponse<boolean>>;
     private getAuthHeaders;
-    private getJsonHeaders;
-    private getApiKeyHeader;
-    private requireValue;
-}
-
-declare class ConfigError extends Error {
-    constructor(message: string);
-}
-declare class AuthError extends Error {
-    constructor(message: string);
-}
-declare class HttpError extends Error {
-    status: number;
-    constructor(status: number, message: string);
 }
 
-export { type APIRequest, type APIResponse, AuthError, type CaptureResult, type CaptureType, ConfigError, type CoverageData, type Encounter, HCSettingsClient, HttpError, type IdentificationCaptureData, type InsuranceCaptureData, type InsuranceRecord, type PatientDashboard, type PatientRecord, type UserImage, type UserPhotoCaptureData, UserStatus };
+export { type CaptureResult, type CaptureType, type CoverageData, type Encounter, HCSettingsClient, type IdentificationCaptureData, type InsuranceCaptureData, type InsuranceRecord, type PatientDashboard, type PatientRecord, type UserImage, type UserPhotoCaptureData, UserStatus };

package/dist/index.js

@@ -1,266 +1,246 @@
-// src/errors.ts
-var ConfigError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ConfigError";
-  }
-};
-var AuthError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "AuthError";
-  }
-};
-var HttpError = class extends Error {
-  constructor(status, message) {
-    super(message);
-    this.name = "HttpError";
-    this.status = status;
-  }
-};
-
 // src/client.ts
-var HCSettingsClient = class {
+import { HCBaseConnector, ValidationError } from "@healthcloudai/hc-http";
+var HCSettingsClient = class extends HCBaseConnector {
   constructor(httpClient, loginClient) {
-    this.httpClient = httpClient;
-    this.loginClient = loginClient;
-  }
-  setApiKey(headerName, value) {
-    const trimmedHeaderName = headerName == null ? void 0 : headerName.trim();
-    const trimmedValue = value == null ? void 0 : value.trim();
-    if (!trimmedHeaderName) {
-      throw new ConfigError(
-        "API key header name is required."
-      );
-    }
-    if (!trimmedValue) {
-      throw new ConfigError(
-        "API key value is required."
-      );
-    }
-    this.apiKeyHeaderName = trimmedHeaderName;
-    this.apiKeyValue = trimmedValue;
+    super(httpClient);
+    this.auth = loginClient;
   }
   // ===========================================================================
   // Dashboard
   // ===========================================================================
+  /**
+   * Returns the patient dashboard including record, encounters, and pending actions.
+   */
   async getDashboard() {
-    return this.httpClient.get(
-      `${this.getBaseUrl()}/patient/dashboard`,
-      this.getAuthHeaders()
+    return this.execute(
+      "getDashboard",
+      () => this.http.get(
+        `${this.auth.getBaseUrl()}/api/patient/dashboard`,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
   // User image
   // ===========================================================================
+  /**
+   * Returns a canned (pre-signed) URL for uploading the patient profile image.
+   * Extension must be a valid file extension such as "jpg" or "png".
+   */
   async getUserImageCannedUrl(extension) {
-    const resolvedExtension = this.requireValue(
-      extension,
-      "extension"
-    );
+    const resolvedExtension = this.requireValue(extension, "Extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/image/cannedurl`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "getUserImageCannedUrl",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/image/cannedurl`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
+  /**
+   * Updates the patient's profile image by confirming the uploaded file name.
+   */
   async updateUserImage(fileName) {
-    const resolvedFileName = this.requireValue(
-      fileName,
-      "fileName"
-    );
+    const resolvedFileName = this.requireValue(fileName, "File name");
     const requestPayload = {
-      Data: {
-        FileName: resolvedFileName
-      }
+      Data: { FileName: resolvedFileName }
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/image/url`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "updateUserImage",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/image/url`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
   // Identification
   // ===========================================================================
+  /**
+   * Returns a canned URL for uploading the patient's driving licence image.
+   */
   async getDrivingLicenseCannedUrl(extension) {
-    const resolvedExtension = this.requireValue(
-      extension,
-      "extension"
-    );
+    const resolvedExtension = this.requireValue(extension, "Extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/id/cannedurl`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "getDrivingLicenseCannedUrl",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/id/cannedurl`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
+  /**
+   * Submits a driving licence file for OCR capture.
+   * fileKey is the storage key of the uploaded image.
+   */
   async captureDrivingLicense(fileKey) {
-    const resolvedFileKey = this.requireValue(
-      fileKey,
-      "fileKey"
-    );
+    const resolvedFileKey = this.requireValue(fileKey, "File key");
     const requestPayload = {
-      Data: {
-        Type: "identification",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "identification", FileID: resolvedFileKey }
     };
-    return this.httpClient.post(
-      `${this.getBaseUrl()}/patient/capture`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "captureDrivingLicense",
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
+  /**
+   * Submits a base64-encoded driving licence image to the EHR.
+   */
   async submitDrivingLicense(image) {
-    const resolvedImage = this.requireValue(
-      image,
-      "image"
-    );
+    const resolvedImage = this.requireValue(image, "Image");
     const requestPayload = {
-      Data: {
-        Image: resolvedImage
-      }
+      Data: { Image: resolvedImage }
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/ehr/patient/drivinglicense`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "submitDrivingLicense",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/ehr/patient/drivinglicense`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
   // Insurance
   // ===========================================================================
+  /**
+   * Returns a canned URL for uploading the insurance card image.
+   */
   async getInsuranceCannedUrl(extension) {
-    const resolvedExtension = this.requireValue(
-      extension,
-      "extension"
-    );
+    const resolvedExtension = this.requireValue(extension, "Extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/insurance/cannedurl`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "getInsuranceCannedUrl",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/insurance/cannedurl`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
+  /**
+   * Submits an insurance card image for OCR capture.
+   * fileKey is the storage key of the uploaded image.
+   */
   async captureInsurance(fileKey) {
-    const resolvedFileKey = this.requireValue(
-      fileKey,
-      "fileKey"
-    );
+    const resolvedFileKey = this.requireValue(fileKey, "File key");
     const requestPayload = {
-      Data: {
-        Type: "healthinsurance",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "healthinsurance", FileID: resolvedFileKey }
     };
-    return this.httpClient.post(
-      `${this.getBaseUrl()}/patient/capture`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "captureInsurance",
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
+  /**
+   * Creates or updates the patient's insurance coverage record.
+   */
   async submitInsurance(coverage) {
     if (!coverage) {
-      throw new ConfigError(
-        "Insurance coverage data is required."
-      );
+      throw new ValidationError({
+        message: "Insurance coverage data is required.",
+        code: "INVALID_INPUT",
+        param: "coverage"
+      });
     }
     const requestPayload = {
       Data: coverage
     };
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/coverage`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "submitInsurance",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/coverage`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
-  async getInsurances() {
-    return this.httpClient.get(
-      `${this.getBaseUrl()}/ehr/patient/insurances`,
-      this.getAuthHeaders()
+  /**
+   * Returns all insurance records for the authenticated patient.
+   */
+  async listInsurances() {
+    return this.execute(
+      "listInsurances",
+      () => this.http.get(
+        `${this.auth.getBaseUrl()}/api/ehr/patient/insurances`,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
   // User photo capture
   // ===========================================================================
+  /**
+   * Submits a user photo (selfie) for capture.
+   * fileKey is the storage key of the uploaded image.
+   */
   async captureUserPhoto(fileKey) {
-    const resolvedFileKey = this.requireValue(
-      fileKey,
-      "fileKey"
-    );
+    const resolvedFileKey = this.requireValue(fileKey, "File key");
     const requestPayload = {
-      Data: {
-        Type: "userphoto",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "userphoto", FileID: resolvedFileKey }
     };
-    return this.httpClient.post(
-      `${this.getBaseUrl()}/patient/capture`,
-      requestPayload,
-      this.getJsonHeaders()
+    return this.execute(
+      "captureUserPhoto",
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
+        requestPayload,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
   // Account
   // ===========================================================================
-  async deactivateUser() {
-    return this.httpClient.put(
-      `${this.getBaseUrl()}/patient/deactivate`,
-      void 0,
-      this.getJsonHeaders()
+  /**
+   * Soft-deactivates the current patient account.
+   * The patient record is not permanently deleted.
+   */
+  async deactivateCurrentPatient() {
+    return this.execute(
+      "deactivateCurrentPatient",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/deactivate`,
+        void 0,
+        this.getAuthHeaders()
+      )
     );
   }
   // ===========================================================================
-  // Helpers
+  // Private
   // ===========================================================================
-  getBaseUrl() {
-    return this.loginClient.getBaseUrl();
-  }
   getAuthHeaders() {
-    return {
-      ...this.loginClient.getAuthHeader(),
-      ...this.getApiKeyHeader()
-    };
-  }
-  getJsonHeaders() {
-    return {
-      ...this.getAuthHeaders(),
-      "Content-Type": "application/json"
-    };
-  }
-  getApiKeyHeader() {
-    if (!this.apiKeyHeaderName || !this.apiKeyValue) {
-      return {};
-    }
-    return {
-      [this.apiKeyHeaderName]: this.apiKeyValue
-    };
-  }
-  requireValue(value, parameterName) {
-    const trimmedValue = value == null ? void 0 : value.trim();
-    if (!trimmedValue) {
-      throw new ConfigError(
-        `${parameterName} is required.`
-      );
-    }
-    return trimmedValue;
+    return { ...this.getHeaders(), ...this.auth.getAuthHeader() };
   }
 };
 
+// src/errors.ts
+import {
+  APIError,
+  ConfigError,
+  HCServiceError,
+  NetworkError,
+  ValidationError as ValidationError2
+} from "@healthcloudai/hc-http";
+
 // src/types.ts
 var UserStatus = /* @__PURE__ */ ((UserStatus2) => {
   UserStatus2[UserStatus2["INACTIVE"] = 0] = "INACTIVE";
@@ -269,9 +249,11 @@ var UserStatus = /* @__PURE__ */ ((UserStatus2) => {
   return UserStatus2;
 })(UserStatus || {});
 export {
-  AuthError,
+  APIError,
   ConfigError,
+  HCServiceError,
   HCSettingsClient,
-  HttpError,
-  UserStatus
+  NetworkError,
+  UserStatus,
+  ValidationError2 as ValidationError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@healthcloudai/hc-settings-connector",
-  "version": "0.0.14",
+  "version": "0.2.0",
   "description": "Healthcheck Settings SDK with TypeScript",
   "author": "Healthcheck Systems Inc",
   "license": "MIT",
@@ -36,8 +36,8 @@
   },
   "dependencies": {
     "axios": "^1.13.4",
-    "@healthcloudai/hc-login-connector": "^0.1.0",
-    "@healthcloudai/hc-http": "^0.0.6"
+    "@healthcloudai/hc-login-connector": "^0.3.0",
+    "@healthcloudai/hc-http": "^0.2.0"
   },
   "peerDependencies": {
     "react-native": ">=0.70.0"