@healthcloudai/hc-safe-cdx 0.2.2 → 0.4.0

package/README.md

@@ -141,7 +141,7 @@ Public methods follow the documented patient workflow request shapes.
 
 ```ts
 safeCdx.getTestProfileByGTIN(gtin)
-safeCdx.getTestProfilesByAccount(includeRegisterTestDetails?)
+safeCdx.listTestProfilesByAccount(includeRegisterTestDetails?)
 safeCdx.createUploadUrl(userTestResultId, gtin, imageType?)
 safeCdx.updateCvmlStatus(imageOfCaptureId, cvmlStatus)
 safeCdx.getCvmlResults(imageOfCaptureId)
@@ -159,7 +159,7 @@ safeCdx.finalizeTest(userTestResultId)
 ## Typical Patient Workflow
 
 ```ts
-const profiles = await safeCdx.getTestProfilesByAccount();
+const profiles = await safeCdx.listTestProfilesByAccount();
 
 const profile = await safeCdx.getTestProfileByGTIN("850024942325");
 
@@ -211,23 +211,16 @@ The application is responsible for preserving workflow values returned between s
 
 ## Public Methods
 
-### `getTestProfilesByAccount(...)`
+### `listTestProfilesByAccount(...)`
 
 Lists test profiles available to the authenticated patient account. The backend resolves the tenant from the authenticated patient context.
 
 #### Signature
 
 ```ts
-safeCdx.getTestProfilesByAccount(
+safeCdx.listTestProfilesByAccount(
     includeRegisterTestDetails?: boolean
-): Promise<APIResponse<GetTestProfilesByAccountData>>
-```
-
-`GetTestProfilesByAccountData` is:
-
-```ts
-type GetTestProfilesByAccountData =
-    SafeAPIResponse<TestProfileByAccountItem[]>;
+): Promise<SafeAPIResponse<TestProfileByAccountItem[]>>
 ```
 
 #### Parameters
@@ -239,11 +232,11 @@ type GetTestProfilesByAccountData =
 #### Usage
 
 ```ts
-const profiles = await safeCdx.getTestProfilesByAccount();
+const profiles = await safeCdx.listTestProfilesByAccount();
 ```
 
 ```ts
-const profiles = await safeCdx.getTestProfilesByAccount(true);
+const profiles = await safeCdx.listTestProfilesByAccount(true);
 ```
 
 #### API request sent internally
@@ -1649,12 +1642,48 @@ const response = await safeCdx.finalizeTest(userTestResultId);
 ```
 
 
+## Distinct API Host
+
+Safe CDX calls a **different backend service** from all other connectors. The host is `api-hcs.healthcloud-services.com` (not `api-healthcheck.healthcloud-services.com`). The URL is derived from `loginClient.getEnvironment()`:
+
+| Environment | Host |
+| --- | --- |
+| `dev` | `https://dev-api-hcs.healthcloud-services.com/api/console/hcservice/safecdx` |
+| `uat` | `https://uat-api-hcs.healthcloud-services.com/api/console/hcservice/safecdx` |
+| `prod` | `https://api-hcs.healthcloud-services.com/api/console/hcservice/safecdx` |
+
+`loginClient.getBaseUrl()` is **not used** by this connector — it points to the Healthcheck API, not SafeCDX.
+
+---
+
+## Response Type by Method
+
+| Method | Returns |
+| --- | --- |
+| `getTestProfileByGTIN(gtin)` | `APIResponse<GetTestProfileByGTINData>` |
+| `listTestProfilesByAccount(...)` | `SafeAPIResponse<TestProfileByAccountItem[]>` |
+| `createUploadUrl(...)` | `APIResponse<CreateUploadUrlData>` |
+| `uploadImage(preSignedURL, image, contentType?)` | `Promise<void>` — direct S3 upload, no envelope |
+| `updateCvmlStatus(...)` | `SafeAPIResponse<UpdateCvmlStatusResponse>` |
+| `getCvmlResults(imageOfCaptureId)` | `SafeAPIResponse<GetCvmlResultsResponse>` |
+| `getPendingResults(excludeStatus?)` | `APIResponse<GetPendingResultsData>` |
+| `getLastResults(excludeStatus?)` | `APIResponse<GetLastResultsData>` |
+| `getTestHistory(excludeStatus?)` | `APIResponse<GetTestHistoryData>` |
+| `getResultDetails(userTestResultId)` | `SafeAPIResponse<GetResultDetailsResponse>` |
+| `getResultPdf(userTestResultId)` | `APIResponse<GetResultPdfData>` |
+| `getImageCaptureUrl(userTestResultId)` | `SafeAPIResponse<GetImageCaptureUrlResponse>` |
+| `resumeFlow(userTestResultId, resumed?)` | `APIResponse<ResumeFlowData>` |
+| `submitAnswers(submission)` | `APIResponse<SubmitAnswersData>` |
+| `finalizeTest(userTestResultId)` | `APIResponse<FinalizeTestData>` |
+
+`uploadImage` bypasses the `HttpClient` entirely and calls the pre-signed storage URL directly using the native `fetch` API. Auth headers are **not** sent — the pre-signed URL provides its own short-lived credential.
+
+---
+
 ## Notes
 
 - `HCSafeCDXClient` documents the authenticated patient workflow supported by the current client.
 - The connector does not perform login; it uses `HCLoginClient` for authenticated patient headers.
-- Safe CDX uses its own service URL derived from `loginClient.getEnvironment()`.
-- The connector does not use `loginClient.getBaseUrl()` for Safe CDX API routes.
 - POST payloads are wrapped internally as `{ Data: payload }`.
 - Patient tenant and identity context are supplied by the backend from the authenticated request.
 - API responses are returned in their endpoint-defined shape without being unwrapped or transformed by `HCSafeCDXClient`.

package/dist/index.cjs

@@ -20,20 +20,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  ConfigError: () => ConfigError,
-  HCSafeCDXClient: () => HCSafeCDXClient
+  APIError: () => import_hc_http2.APIError,
+  ConfigError: () => import_hc_http2.ConfigError,
+  HCSafeCDXClient: () => HCSafeCDXClient,
+  HCServiceError: () => import_hc_http2.HCServiceError,
+  NetworkError: () => import_hc_http2.NetworkError,
+  ValidationError: () => import_hc_http2.ValidationError
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
-var SafeCDXError = class _SafeCDXError extends Error {
-  constructor(message, response) {
-    super(message);
-    this.name = "SafeCDXError";
-    this.response = response;
-    Object.setPrototypeOf(this, _SafeCDXError.prototype);
-  }
-};
+var import_hc_http = require("@healthcloudai/hc-http");
 var ENV_HOST = {
   dev: "dev-api-hcs.healthcloud-services.com",
   uat: "uat-api-hcs.healthcloud-services.com",
@@ -43,7 +40,7 @@ var ROUTE_PREFIX = "api/console/hcservice/safecdx";
 function buildSafeCdxBaseUrl(environment) {
   const host = ENV_HOST[environment];
   if (!host) {
-    throw new SafeCDXError("Invalid Safe CDX environment.");
+    throw new import_hc_http.ConfigError("Invalid Safe CDX environment.");
   }
   return `https://${host}/${ROUTE_PREFIX}`;
 }
@@ -58,24 +55,12 @@ function buildUrl(baseUrl, route, query) {
   }
   return url.toString();
 }
-var HCSafeCDXClient = class {
+var HCSafeCDXClient = class extends import_hc_http.HCBaseConnector {
   constructor(httpClient, loginClient) {
-    this.http = httpClient;
-    this.loginClient = loginClient;
+    super(httpClient);
+    this.auth = loginClient;
     this.baseUrl = buildSafeCdxBaseUrl(loginClient.getEnvironment());
   }
-  setApiKey(headerName, value) {
-    const trimmedHeaderName = headerName == null ? void 0 : headerName.trim();
-    const trimmedValue = value == null ? void 0 : value.trim();
-    if (!trimmedHeaderName) {
-      throw new SafeCDXError("API key header name is required.");
-    }
-    if (!trimmedValue) {
-      throw new SafeCDXError("API key value is required.");
-    }
-    this.apiKeyHeaderName = trimmedHeaderName;
-    this.apiKeyValue = trimmedValue;
-  }
   // -------------------------------------------------------------------------
   // Test Profiles
   // -------------------------------------------------------------------------
@@ -84,27 +69,32 @@ var HCSafeCDXClient = class {
    * Resolves the SafeCDX test profile associated with a GTIN barcode.
    */
   async getTestProfileByGTIN(gtin) {
-    return this.http.get(
-      this.url(`gs1/${encodeURIComponent(gtin)}`),
-      this.getAuthHeaders()
+    const resolvedGtin = this.requireValue(gtin, "GTIN");
+    return this.execute(
+      "getTestProfileByGTIN",
+      () => this.http.get(
+        this.url(`gs1/${encodeURIComponent(resolvedGtin)}`),
+        this.getAuthHeaders()
+      )
     );
   }
   /**
-       * POST test/profiles/by-account
-  
-       *
-       * TenantId is resolved by the backend from the authenticated patient context.
-       */
-  async getTestProfilesByAccount(includeRegisterTestDetails = true) {
+   * POST test/profiles/by-account
+   *
+   * Returns test profiles configured for the authenticated patient's account.
+   * TenantId is resolved by the backend from the authenticated patient context.
+   */
+  async listTestProfilesByAccount(includeRegisterTestDetails = true) {
     const request = {
-      Data: {
-        IncludeRegisterTestDetails: includeRegisterTestDetails
-      }
+      Data: { IncludeRegisterTestDetails: includeRegisterTestDetails }
     };
-    return this.http.post(
-      this.url("test/profiles/by-account"),
-      request,
-      this.getJsonHeaders()
+    return this.executeSafe(
+      "listTestProfilesByAccount",
+      () => this.http.post(
+        this.url("test/profiles/by-account"),
+        request,
+        this.getAuthHeaders()
+      )
     );
   }
   // -------------------------------------------------------------------------
@@ -115,34 +105,42 @@ var HCSafeCDXClient = class {
    * Requests a pre-signed URL used to upload a test image.
    */
   async createUploadUrl(userTestResultId, gtin, imageType = "jpg") {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "User test result ID");
+    const resolvedGtin = this.requireValue(gtin, "GTIN");
+    const resolvedImageType = this.requireValue(imageType, "Image type");
     const request = {
       Data: {
-        Gtin: gtin,
-        UserTestResultId: userTestResultId,
-        Metadata: {
-          ImageType: imageType
-        }
+        Gtin: resolvedGtin,
+        UserTestResultId: resolvedUserTestResultId,
+        Metadata: { ImageType: resolvedImageType }
       }
     };
-    return this.http.post(
-      this.url("upload/url"),
-      request,
-      this.getJsonHeaders()
+    return this.execute(
+      "createUploadUrl",
+      () => this.http.post(
+        this.url("upload/url"),
+        request,
+        this.getAuthHeaders()
+      )
     );
   }
   /**
    * PUT preSignedURL
    * Uploads the image directly to the pre-signed storage URL.
    *
-   * This request does not call a SafeCDX API route and does not send
-   * authenticated Health Cloud headers.
+   * This request does NOT call a SafeCDX API route and does NOT send
+   * Health Cloud auth headers — it targets the storage provider directly.
+   * The pre-signed URL embeds credentials; no Authorization header is needed.
    */
   async uploadImage(preSignedURL, image, contentType = "image/jpeg") {
-    const response = await fetch(preSignedURL, {
+    const resolvedPreSignedURL = this.requireValue(preSignedURL, "Pre-signed URL");
+    const resolvedContentType = this.requireValue(contentType, "Content type");
+    if (image == null) {
+      throw new import_hc_http.ValidationError({ message: "Image is required.", code: "INVALID_INPUT" });
+    }
+    const response = await fetch(resolvedPreSignedURL, {
       method: "PUT",
-      headers: {
-        "Content-Type": contentType
-      },
+      headers: { "Content-Type": resolvedContentType },
       body: image
     });
     if (!response.ok) {
@@ -152,9 +150,12 @@ var HCSafeCDXClient = class {
       } catch {
         body = void 0;
       }
-      throw new SafeCDXError(`Image upload failed with HTTP ${response.status}.`, {
-        status: response.status,
-        body
+      throw new import_hc_http.APIError({
+        message: `uploadImage: image upload failed with HTTP ${response.status}.`,
+        code: response.status >= 500 ? "SERVER_ERROR" : "UNKNOWN_ERROR",
+        statusCode: response.status,
+        backendMessage: body,
+        details: { status: response.status, body }
       });
     }
   }
@@ -163,138 +164,188 @@ var HCSafeCDXClient = class {
   // -------------------------------------------------------------------------
   /**
    * POST cvml/status
-   * Returns the direct SafeCDX response without an outer APIResponse wrapper.
+   * Updates the CVML processing status for an image capture.
    */
   async updateCvmlStatus(imageOfCaptureId, cvmlStatus) {
+    const resolvedImageOfCaptureId = this.requireValue(imageOfCaptureId, "Image capture ID");
+    const resolvedCvmlStatus = this.requireValue(cvmlStatus, "CVML status");
     const request = {
       Data: {
-        ImageOfCaptureId: imageOfCaptureId,
-        CvmlStatus: cvmlStatus
+        ImageOfCaptureId: resolvedImageOfCaptureId,
+        CvmlStatus: resolvedCvmlStatus
       }
     };
-    return this.http.post(this.url("cvml/status"), request, this.getJsonHeaders());
+    return this.executeSafe(
+      "updateCvmlStatus",
+      () => this.http.post(this.url("cvml/status"), request, this.getAuthHeaders())
+    );
   }
   /**
    * GET cvml/results
-   * Returns the direct SafeCDX response without an outer APIResponse wrapper.
+   * Returns the CVML analysis results for an image capture.
    */
   async getCvmlResults(imageOfCaptureId) {
-    return this.http.get(this.url("cvml/results", { imageOfCaptureId }), this.getAuthHeaders());
+    const resolvedImageOfCaptureId = this.requireValue(imageOfCaptureId, "Image capture ID");
+    return this.executeSafe(
+      "getCvmlResults",
+      () => this.http.get(
+        this.url("cvml/results", { imageOfCaptureId: resolvedImageOfCaptureId }),
+        this.getAuthHeaders()
+      )
+    );
   }
   // -------------------------------------------------------------------------
   // Test Results
   // -------------------------------------------------------------------------
-  /** POST test/result/pending */
-  async getPendingResults(excludeStatus = "Invalid,Canceled") {
+  /** POST test/result/pending — returns pending test results excluding the given statuses. */
+  async listPendingResults(excludeStatus = "Invalid,Canceled") {
     const request = {
-      Data: {
-        ExcludeStatus: excludeStatus
-      }
+      Data: { ExcludeStatus: excludeStatus }
     };
-    return this.http.post(this.url("test/result/pending"), request, this.getJsonHeaders());
+    return this.executeSafe(
+      "listPendingResults",
+      () => this.http.post(this.url("test/result/pending"), request, this.getAuthHeaders())
+    );
   }
-  /** POST test/result/last */
+  /** POST test/result/last — returns the most recent test result. */
   async getLastResults(excludeStatus = "Invalid") {
     const request = {
-      Data: {
-        ExcludeStatus: excludeStatus
-      }
+      Data: { ExcludeStatus: excludeStatus }
     };
-    return this.http.post(this.url("test/result/last"), request, this.getJsonHeaders());
+    return this.executeSafe(
+      "getLastResults",
+      () => this.http.post(this.url("test/result/last"), request, this.getAuthHeaders())
+    );
   }
-  /** POST test/result/history */
-  async getTestHistory(excludeStatus = "Invalid") {
+  /** POST test/result/history — returns all test results excluding the given statuses. */
+  async listTestHistory(excludeStatus = "Invalid") {
     const request = {
-      Data: {
-        ExcludeStatus: excludeStatus
-      }
+      Data: { ExcludeStatus: excludeStatus }
     };
-    return this.http.post(this.url("test/result/history"), request, this.getJsonHeaders());
+    return this.executeSafe(
+      "listTestHistory",
+      () => this.http.post(this.url("test/result/history"), request, this.getAuthHeaders())
+    );
   }
   /**
    * POST test/result/details
-   * Returns the direct SafeCDX response without an outer APIResponse wrapper.
+   * Returns full details for a single test result.
    */
   async getResultDetails(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "User test result ID");
     const request = {
-      Data: {
-        UserTestResultId: userTestResultId
-      }
+      Data: { UserTestResultId: resolvedUserTestResultId }
     };
-    return this.http.post(this.url("test/result/details"), request, this.getJsonHeaders());
+    return this.executeSafe(
+      "getResultDetails",
+      () => this.http.post(this.url("test/result/details"), request, this.getAuthHeaders())
+    );
   }
-  /** POST test/result/pdf */
+  /** POST test/result/pdf — returns the PDF report for a test result. */
   async getResultPdf(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "User test result ID");
     const request = {
-      Data: {
-        UserTestResultId: userTestResultId
-      }
+      Data: { UserTestResultId: resolvedUserTestResultId }
     };
-    return this.http.post(this.url("test/result/pdf"), request, this.getJsonHeaders());
+    return this.executeSafe(
+      "getResultPdf",
+      () => this.http.post(this.url("test/result/pdf"), request, this.getAuthHeaders())
+    );
   }
   /**
    * POST test/result/image/capture
-   * Returns the direct SafeCDX response without an outer APIResponse wrapper.
+   * Returns a URL to capture an image for the given test result.
    */
   async getImageCaptureUrl(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "User test result ID");
     const request = {
-      Data: {
-        UserTestResultId: userTestResultId
-      }
+      Data: { UserTestResultId: resolvedUserTestResultId }
     };
-    return this.http.post(this.url("test/result/image/capture"), request, this.getJsonHeaders());
+    return this.executeSafe(
+      "getImageCaptureUrl",
+      () => this.http.post(this.url("test/result/image/capture"), request, this.getAuthHeaders())
+    );
   }
   // -------------------------------------------------------------------------
   // Resume / Answers / Finalize
   // -------------------------------------------------------------------------
   /** POST test/resume */
   async resumeFlow(userTestResultId, resumed = true) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "User test result ID");
     const request = {
-      Data: {
-        UserTestResultId: userTestResultId,
-        Resumed: resumed
-      }
+      Data: { UserTestResultId: resolvedUserTestResultId, Resumed: resumed }
     };
-    return this.http.post(this.url("test/resume"), request, this.getJsonHeaders());
+    return this.executeSafe(
+      "resumeFlow",
+      () => this.http.post(this.url("test/resume"), request, this.getAuthHeaders())
+    );
   }
   /** POST test/answers */
   async submitAnswers(submission) {
+    const resolvedId = this.requireValue(submission == null ? void 0 : submission.UserTestResultId, "User test result ID");
+    if (!(submission == null ? void 0 : submission.Result) || submission.Result.length === 0) {
+      throw new import_hc_http.ValidationError({
+        message: "At least one answer result is required.",
+        code: "INVALID_INPUT",
+        param: "Result"
+      });
+    }
     const request = {
-      Data: submission
+      Data: { ...submission, UserTestResultId: resolvedId }
     };
-    return this.http.post(this.url("test/answers"), request, this.getJsonHeaders());
+    return this.executeSafe(
+      "submitAnswers",
+      () => this.http.post(this.url("test/answers"), request, this.getAuthHeaders())
+    );
   }
   /** POST test/finalize */
   async finalizeTest(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "User test result ID");
     const request = {
-      Data: {
-        UserTestResultId: userTestResultId
-      }
+      Data: { UserTestResultId: resolvedUserTestResultId }
     };
-    return this.http.post(this.url("test/finalize"), request, this.getJsonHeaders());
+    return this.execute(
+      "finalizeTest",
+      () => this.http.post(this.url("test/finalize"), request, this.getAuthHeaders())
+    );
   }
   // -------------------------------------------------------------------------
   // Private Helpers
   // -------------------------------------------------------------------------
-  getAuthHeaders() {
-    return {
-      ...this.loginClient.getAuthHeader(),
-      ...this.getApiKeyHeader()
-    };
+  async executeSafe(operation, request) {
+    var _a;
+    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.isSafeApiResponse(response)) {
+      throw new import_hc_http.APIError({ message: `${operation}: invalid SafeCDX response structure`, code: "INVALID_RESPONSE", details: response });
+    }
+    if (!response.success) {
+      throw new import_hc_http.HCServiceError(
+        operation,
+        (_a = response.message) != null ? _a : "Backend returned success: false",
+        response
+      );
+    }
+    return response;
   }
-  getJsonHeaders() {
-    return {
-      ...this.getAuthHeaders(),
-      "Content-Type": "application/json"
-    };
+  isSafeApiResponse(value) {
+    if (!value || typeof value !== "object") return false;
+    const r = value;
+    return "success" in r && typeof r.success === "boolean" && "data" in r && "message" in r && "code" in r && typeof r.code === "number";
   }
-  getApiKeyHeader() {
-    if (!this.apiKeyHeaderName || !this.apiKeyValue) {
-      return {};
-    }
-    return {
-      [this.apiKeyHeaderName]: this.apiKeyValue
-    };
+  getAuthHeaders() {
+    return { ...this.getHeaders(), ...this.auth.getAuthHeader() };
   }
   url(route, query) {
     return buildUrl(this.baseUrl, route, query);
@@ -302,14 +353,13 @@ var HCSafeCDXClient = class {
 };
 
 // src/errors.ts
-var ConfigError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ConfigError";
-  }
-};
+var import_hc_http2 = require("@healthcloudai/hc-http");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  APIError,
   ConfigError,
-  HCSafeCDXClient
+  HCSafeCDXClient,
+  HCServiceError,
+  NetworkError,
+  ValidationError
 });