@healthcloudai/hc-settings-connector 0.1.0 → 0.2.1

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

@@ -26,42 +26,28 @@ __export(index_exports, {
   HCSettingsClient: () => HCSettingsClient,
   NetworkError: () => import_hc_http2.NetworkError,
   UserStatus: () => UserStatus,
-  ValidationError: () => import_hc_http2.ValidationError,
-  errorFromHttpStatus: () => import_hc_http2.errorFromHttpStatus
+  ValidationError: () => import_hc_http2.ValidationError
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
 var import_hc_http = require("@healthcloudai/hc-http");
-var HCSettingsClient = class {
+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 import_hc_http.ConfigError(
-        "API key header name is required."
-      );
-    }
-    if (!trimmedValue) {
-      throw new import_hc_http.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.execute(
       "getDashboard",
-      () => this.httpClient.get(
-        `${this.getBaseUrl()}/api/patient/dashboard`,
+      () => this.http.get(
+        `${this.auth.getBaseUrl()}/api/patient/dashboard`,
         this.getAuthHeaders()
       )
     );
@@ -69,152 +55,143 @@ var HCSettingsClient = class {
   // ===========================================================================
   // 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", "extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
     return this.execute(
       "getUserImageCannedUrl",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/image/cannedurl`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/image/cannedurl`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "fileName");
     const requestPayload = {
-      Data: {
-        FileName: resolvedFileName
-      }
+      Data: { FileName: resolvedFileName }
     };
     return this.execute(
       "updateUserImage",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/image/url`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/image/url`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
     return this.execute(
       "getDrivingLicenseCannedUrl",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/id/cannedurl`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/id/cannedurl`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "fileKey");
     const requestPayload = {
-      Data: {
-        Type: "identification",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "identification", FileID: resolvedFileKey }
     };
     return this.execute(
       "captureDrivingLicense",
-      () => this.httpClient.post(
-        `${this.getBaseUrl()}/api/patient/capture`,
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "image");
     const requestPayload = {
-      Data: {
-        Image: resolvedImage
-      }
+      Data: { Image: resolvedImage }
     };
     return this.execute(
       "submitDrivingLicense",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/ehr/patient/drivinglicense`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/ehr/patient/drivinglicense`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
     return this.execute(
       "getInsuranceCannedUrl",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/insurance/cannedurl`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/insurance/cannedurl`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "fileKey");
     const requestPayload = {
-      Data: {
-        Type: "healthinsurance",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "healthinsurance", FileID: resolvedFileKey }
     };
     return this.execute(
       "captureInsurance",
-      () => this.httpClient.post(
-        `${this.getBaseUrl()}/api/patient/capture`,
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
         requestPayload,
-        this.getJsonHeaders()
+        this.getAuthHeaders()
       )
     );
   }
+  /**
+   * Creates or updates the patient's insurance coverage record.
+   */
   async submitInsurance(coverage) {
     if (!coverage) {
       throw new import_hc_http.ValidationError({
         message: "Insurance coverage data is required.",
-        code: "INVALID_INPUT"
+        code: "INVALID_INPUT",
+        param: "coverage"
       });
     }
     const requestPayload = {
@@ -222,18 +199,21 @@ var HCSettingsClient = class {
     };
     return this.execute(
       "submitInsurance",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/coverage`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/coverage`,
         requestPayload,
-        this.getJsonHeaders()
+        this.getAuthHeaders()
       )
     );
   }
-  async getInsurances() {
+  /**
+   * Returns all insurance records for the authenticated patient.
+   */
+  async listInsurances() {
     return this.execute(
-      "getInsurances",
-      () => this.httpClient.get(
-        `${this.getBaseUrl()}/api/ehr/patient/insurances`,
+      "listInsurances",
+      () => this.http.get(
+        `${this.auth.getBaseUrl()}/api/ehr/patient/insurances`,
         this.getAuthHeaders()
       )
     );
@@ -241,128 +221,46 @@ var HCSettingsClient = class {
   // ===========================================================================
   // 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", "fileKey");
     const requestPayload = {
-      Data: {
-        Type: "userphoto",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "userphoto", FileID: resolvedFileKey }
     };
     return this.execute(
       "captureUserPhoto",
-      () => this.httpClient.post(
-        `${this.getBaseUrl()}/api/patient/capture`,
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
         requestPayload,
-        this.getJsonHeaders()
+        this.getAuthHeaders()
       )
     );
   }
   // ===========================================================================
   // Account
   // ===========================================================================
-  async deactivateUser() {
+  /**
+   * Soft-deactivates the current patient account.
+   * The patient record is not permanently deleted.
+   */
+  async deactivateCurrentPatient() {
     return this.execute(
-      "deactivateUser",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/deactivate`,
+      "deactivateCurrentPatient",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/deactivate`,
         void 0,
-        this.getJsonHeaders()
+        this.getAuthHeaders()
       )
     );
   }
   // ===========================================================================
-  // Helpers
+  // Private
   // ===========================================================================
-  async execute(operation, request) {
-    let response;
-    try {
-      response = await request();
-    } catch (err) {
-      if (err instanceof import_hc_http.APIError) {
-        throw err;
-      }
-      if (err instanceof Error) {
-        throw new import_hc_http.APIError({
-          message: `${operation}: ${err.message}`,
-          code: "UNKNOWN_ERROR",
-          details: err
-        });
-      }
-      throw new import_hc_http.APIError({
-        message: `${operation}: unexpected runtime failure`,
-        code: "UNKNOWN_ERROR",
-        details: err
-      });
-    }
-    if (response == null) {
-      throw new import_hc_http.APIError({
-        message: `${operation}: empty response received`,
-        code: "EMPTY_RESPONSE",
-        details: response
-      });
-    }
-    if (!this.isApiResponse(response)) {
-      throw new import_hc_http.APIError({
-        message: `${operation}: invalid API response structure`,
-        code: "INVALID_RESPONSE",
-        details: response
-      });
-    }
-    if (!response.IsOK) {
-      throw this.mapBackendError(operation, response);
-    }
-    return response;
-  }
-  mapBackendError(operation, response) {
-    return new import_hc_http.HCServiceError(
-      operation,
-      response.ErrorMessage,
-      response
-    );
-  }
-  isApiResponse(value) {
-    if (!value || typeof value !== "object") {
-      return false;
-    }
-    const response = value;
-    return "IsOK" in response && typeof response.IsOK === "boolean" && "Data" in response && "ErrorMessage" in response;
-  }
-  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 import_hc_http.ValidationError({
-        message: `${parameterName} is required.`,
-        code: "INVALID_INPUT"
-      });
-    }
-    return trimmedValue;
+    return { ...this.getHeaders(), ...this.auth.getAuthHeader() };
   }
 };
 
@@ -384,6 +282,5 @@ var UserStatus = /* @__PURE__ */ ((UserStatus2) => {
   HCSettingsClient,
   NetworkError,
   UserStatus,
-  ValidationError,
-  errorFromHttpStatus
+  ValidationError
 });

package/dist/index.d.cts

@@ -1,15 +1,7 @@
 import { HCLoginClient } from '@healthcloudai/hc-login-connector';
-import { HttpClient, APIError } from '@healthcloudai/hc-http';
-export { APIError, ConfigError, HCServiceError, NetworkError, ValidationError, errorFromHttpStatus } 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;
@@ -121,33 +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>>;
-    protected execute<T>(operation: string, request: () => Promise<APIResponse<T>>): Promise<APIResponse<T>>;
-    protected mapBackendError(operation: string, response: APIResponse<unknown>): APIError;
-    private isApiResponse;
-    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;
 }
 
-export { type APIRequest, type APIResponse, type CaptureResult, type CaptureType, type CoverageData, type Encounter, HCSettingsClient, 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,15 +1,7 @@
 import { HCLoginClient } from '@healthcloudai/hc-login-connector';
-import { HttpClient, APIError } from '@healthcloudai/hc-http';
-export { APIError, ConfigError, HCServiceError, NetworkError, ValidationError, errorFromHttpStatus } 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;
@@ -121,33 +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>>;
-    protected execute<T>(operation: string, request: () => Promise<APIResponse<T>>): Promise<APIResponse<T>>;
-    protected mapBackendError(operation: string, response: APIResponse<unknown>): APIError;
-    private isApiResponse;
-    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;
 }
 
-export { type APIRequest, type APIResponse, type CaptureResult, type CaptureType, type CoverageData, type Encounter, HCSettingsClient, 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,39 +1,21 @@
 // src/client.ts
-import {
-  APIError,
-  ConfigError,
-  HCServiceError,
-  ValidationError
-} from "@healthcloudai/hc-http";
-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.execute(
       "getDashboard",
-      () => this.httpClient.get(
-        `${this.getBaseUrl()}/api/patient/dashboard`,
+      () => this.http.get(
+        `${this.auth.getBaseUrl()}/api/patient/dashboard`,
         this.getAuthHeaders()
       )
     );
@@ -41,152 +23,143 @@ var HCSettingsClient = class {
   // ===========================================================================
   // 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", "extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
     return this.execute(
       "getUserImageCannedUrl",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/image/cannedurl`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/image/cannedurl`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "fileName");
     const requestPayload = {
-      Data: {
-        FileName: resolvedFileName
-      }
+      Data: { FileName: resolvedFileName }
     };
     return this.execute(
       "updateUserImage",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/image/url`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/image/url`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
     return this.execute(
       "getDrivingLicenseCannedUrl",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/id/cannedurl`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/id/cannedurl`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "fileKey");
     const requestPayload = {
-      Data: {
-        Type: "identification",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "identification", FileID: resolvedFileKey }
     };
     return this.execute(
       "captureDrivingLicense",
-      () => this.httpClient.post(
-        `${this.getBaseUrl()}/api/patient/capture`,
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "image");
     const requestPayload = {
-      Data: {
-        Image: resolvedImage
-      }
+      Data: { Image: resolvedImage }
     };
     return this.execute(
       "submitDrivingLicense",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/ehr/patient/drivinglicense`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/ehr/patient/drivinglicense`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "extension");
     const requestPayload = {
-      Data: {
-        Extension: resolvedExtension
-      }
+      Data: { Extension: resolvedExtension }
     };
     return this.execute(
       "getInsuranceCannedUrl",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/insurance/cannedurl`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/insurance/cannedurl`,
         requestPayload,
-        this.getJsonHeaders()
+        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", "fileKey");
     const requestPayload = {
-      Data: {
-        Type: "healthinsurance",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "healthinsurance", FileID: resolvedFileKey }
     };
     return this.execute(
       "captureInsurance",
-      () => this.httpClient.post(
-        `${this.getBaseUrl()}/api/patient/capture`,
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
         requestPayload,
-        this.getJsonHeaders()
+        this.getAuthHeaders()
       )
     );
   }
+  /**
+   * Creates or updates the patient's insurance coverage record.
+   */
   async submitInsurance(coverage) {
     if (!coverage) {
       throw new ValidationError({
         message: "Insurance coverage data is required.",
-        code: "INVALID_INPUT"
+        code: "INVALID_INPUT",
+        param: "coverage"
       });
     }
     const requestPayload = {
@@ -194,18 +167,21 @@ var HCSettingsClient = class {
     };
     return this.execute(
       "submitInsurance",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/coverage`,
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/coverage`,
         requestPayload,
-        this.getJsonHeaders()
+        this.getAuthHeaders()
       )
     );
   }
-  async getInsurances() {
+  /**
+   * Returns all insurance records for the authenticated patient.
+   */
+  async listInsurances() {
     return this.execute(
-      "getInsurances",
-      () => this.httpClient.get(
-        `${this.getBaseUrl()}/api/ehr/patient/insurances`,
+      "listInsurances",
+      () => this.http.get(
+        `${this.auth.getBaseUrl()}/api/ehr/patient/insurances`,
         this.getAuthHeaders()
       )
     );
@@ -213,139 +189,56 @@ var HCSettingsClient = class {
   // ===========================================================================
   // 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", "fileKey");
     const requestPayload = {
-      Data: {
-        Type: "userphoto",
-        FileID: resolvedFileKey
-      }
+      Data: { Type: "userphoto", FileID: resolvedFileKey }
     };
     return this.execute(
       "captureUserPhoto",
-      () => this.httpClient.post(
-        `${this.getBaseUrl()}/api/patient/capture`,
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/patient/capture`,
         requestPayload,
-        this.getJsonHeaders()
+        this.getAuthHeaders()
       )
     );
   }
   // ===========================================================================
   // Account
   // ===========================================================================
-  async deactivateUser() {
+  /**
+   * Soft-deactivates the current patient account.
+   * The patient record is not permanently deleted.
+   */
+  async deactivateCurrentPatient() {
     return this.execute(
-      "deactivateUser",
-      () => this.httpClient.put(
-        `${this.getBaseUrl()}/api/patient/deactivate`,
+      "deactivateCurrentPatient",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/deactivate`,
         void 0,
-        this.getJsonHeaders()
+        this.getAuthHeaders()
       )
     );
   }
   // ===========================================================================
-  // Helpers
+  // Private
   // ===========================================================================
-  async execute(operation, request) {
-    let response;
-    try {
-      response = await request();
-    } catch (err) {
-      if (err instanceof APIError) {
-        throw err;
-      }
-      if (err instanceof Error) {
-        throw new APIError({
-          message: `${operation}: ${err.message}`,
-          code: "UNKNOWN_ERROR",
-          details: err
-        });
-      }
-      throw new APIError({
-        message: `${operation}: unexpected runtime failure`,
-        code: "UNKNOWN_ERROR",
-        details: err
-      });
-    }
-    if (response == null) {
-      throw new APIError({
-        message: `${operation}: empty response received`,
-        code: "EMPTY_RESPONSE",
-        details: response
-      });
-    }
-    if (!this.isApiResponse(response)) {
-      throw new APIError({
-        message: `${operation}: invalid API response structure`,
-        code: "INVALID_RESPONSE",
-        details: response
-      });
-    }
-    if (!response.IsOK) {
-      throw this.mapBackendError(operation, response);
-    }
-    return response;
-  }
-  mapBackendError(operation, response) {
-    return new HCServiceError(
-      operation,
-      response.ErrorMessage,
-      response
-    );
-  }
-  isApiResponse(value) {
-    if (!value || typeof value !== "object") {
-      return false;
-    }
-    const response = value;
-    return "IsOK" in response && typeof response.IsOK === "boolean" && "Data" in response && "ErrorMessage" in response;
-  }
-  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 ValidationError({
-        message: `${parameterName} is required.`,
-        code: "INVALID_INPUT"
-      });
-    }
-    return trimmedValue;
+    return { ...this.getHeaders(), ...this.auth.getAuthHeader() };
   }
 };
 
 // src/errors.ts
 import {
-  APIError as APIError2,
-  ConfigError as ConfigError2,
-  HCServiceError as HCServiceError2,
+  APIError,
+  ConfigError,
+  HCServiceError,
   NetworkError,
-  ValidationError as ValidationError2,
-  errorFromHttpStatus
+  ValidationError as ValidationError2
 } from "@healthcloudai/hc-http";
 
 // src/types.ts
@@ -356,12 +249,11 @@ var UserStatus = /* @__PURE__ */ ((UserStatus2) => {
   return UserStatus2;
 })(UserStatus || {});
 export {
-  APIError2 as APIError,
-  ConfigError2 as ConfigError,
-  HCServiceError2 as HCServiceError,
+  APIError,
+  ConfigError,
+  HCServiceError,
   HCSettingsClient,
   NetworkError,
   UserStatus,
-  ValidationError2 as ValidationError,
-  errorFromHttpStatus
+  ValidationError2 as ValidationError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@healthcloudai/hc-settings-connector",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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.2.0",
-    "@healthcloudai/hc-http": "^0.1.0"
+    "@healthcloudai/hc-login-connector": "^0.3.1",
+    "@healthcloudai/hc-http": "^0.2.1"
   },
   "peerDependencies": {
     "react-native": ">=0.70.0"