@healthcloudai/hc-safe-cdx 0.3.0 → 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

@@ -25,8 +25,7 @@ __export(index_exports, {
   HCSafeCDXClient: () => HCSafeCDXClient,
   HCServiceError: () => import_hc_http2.HCServiceError,
   NetworkError: () => import_hc_http2.NetworkError,
-  ValidationError: () => import_hc_http2.ValidationError,
-  errorFromHttpStatus: () => import_hc_http2.errorFromHttpStatus
+  ValidationError: () => import_hc_http2.ValidationError
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -56,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 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;
-  }
   // -------------------------------------------------------------------------
   // Test Profiles
   // -------------------------------------------------------------------------
@@ -82,7 +69,7 @@ var HCSafeCDXClient = class {
    * Resolves the SafeCDX test profile associated with a GTIN barcode.
    */
   async getTestProfileByGTIN(gtin) {
-    const resolvedGtin = this.requireValue(gtin, "gtin");
+    const resolvedGtin = this.requireValue(gtin, "GTIN");
     return this.execute(
       "getTestProfileByGTIN",
       () => this.http.get(
@@ -92,23 +79,21 @@ var HCSafeCDXClient = class {
     );
   }
   /**
-       * 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.execute(
-      "getTestProfilesByAccount",
+    return this.executeSafe(
+      "listTestProfilesByAccount",
       () => this.http.post(
         this.url("test/profiles/by-account"),
         request,
-        this.getJsonHeaders()
+        this.getAuthHeaders()
       )
     );
   }
@@ -120,16 +105,14 @@ 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, "userTestResultId");
-    const resolvedGtin = this.requireValue(gtin, "gtin");
-    const resolvedImageType = this.requireValue(imageType, "imageType");
+    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: resolvedGtin,
         UserTestResultId: resolvedUserTestResultId,
-        Metadata: {
-          ImageType: resolvedImageType
-        }
+        Metadata: { ImageType: resolvedImageType }
       }
     };
     return this.execute(
@@ -137,7 +120,7 @@ var HCSafeCDXClient = class {
       () => this.http.post(
         this.url("upload/url"),
         request,
-        this.getJsonHeaders()
+        this.getAuthHeaders()
       )
     );
   }
@@ -145,17 +128,19 @@ var HCSafeCDXClient = class {
    * 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 resolvedPreSignedURL = this.requireValue(preSignedURL, "preSignedURL");
-    const resolvedContentType = this.requireValue(contentType, "contentType");
+    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": resolvedContentType
-      },
+      headers: { "Content-Type": resolvedContentType },
       body: image
     });
     if (!response.ok) {
@@ -170,10 +155,7 @@ var HCSafeCDXClient = class {
         code: response.status >= 500 ? "SERVER_ERROR" : "UNKNOWN_ERROR",
         statusCode: response.status,
         backendMessage: body,
-        details: {
-          status: response.status,
-          body
-        }
+        details: { status: response.status, body }
       });
     }
   }
@@ -182,11 +164,11 @@ 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, "imageOfCaptureId");
-    const resolvedCvmlStatus = this.requireValue(cvmlStatus, "cvmlStatus");
+    const resolvedImageOfCaptureId = this.requireValue(imageOfCaptureId, "Image capture ID");
+    const resolvedCvmlStatus = this.requireValue(cvmlStatus, "CVML status");
     const request = {
       Data: {
         ImageOfCaptureId: resolvedImageOfCaptureId,
@@ -195,15 +177,15 @@ var HCSafeCDXClient = class {
     };
     return this.executeSafe(
       "updateCvmlStatus",
-      () => this.http.post(this.url("cvml/status"), request, this.getJsonHeaders())
+      () => 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) {
-    const resolvedImageOfCaptureId = this.requireValue(imageOfCaptureId, "imageOfCaptureId");
+    const resolvedImageOfCaptureId = this.requireValue(imageOfCaptureId, "Image capture ID");
     return this.executeSafe(
       "getCvmlResults",
       () => this.http.get(
@@ -215,85 +197,73 @@ var HCSafeCDXClient = class {
   // -------------------------------------------------------------------------
   // 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.execute(
-      "getPendingResults",
-      () => 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.execute(
+    return this.executeSafe(
       "getLastResults",
-      () => this.http.post(this.url("test/result/last"), request, this.getJsonHeaders())
+      () => 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.execute(
-      "getTestHistory",
-      () => 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, "userTestResultId");
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "User test result ID");
     const request = {
-      Data: {
-        UserTestResultId: resolvedUserTestResultId
-      }
+      Data: { UserTestResultId: resolvedUserTestResultId }
     };
     return this.executeSafe(
       "getResultDetails",
-      () => this.http.post(this.url("test/result/details"), request, this.getJsonHeaders())
+      () => 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, "userTestResultId");
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "User test result ID");
     const request = {
-      Data: {
-        UserTestResultId: resolvedUserTestResultId
-      }
+      Data: { UserTestResultId: resolvedUserTestResultId }
     };
-    return this.execute(
+    return this.executeSafe(
       "getResultPdf",
-      () => this.http.post(this.url("test/result/pdf"), request, this.getJsonHeaders())
+      () => 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, "userTestResultId");
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "User test result ID");
     const request = {
-      Data: {
-        UserTestResultId: resolvedUserTestResultId
-      }
+      Data: { UserTestResultId: resolvedUserTestResultId }
     };
     return this.executeSafe(
       "getImageCaptureUrl",
-      () => this.http.post(this.url("test/result/image/capture"), request, this.getJsonHeaders())
+      () => this.http.post(this.url("test/result/image/capture"), request, this.getAuthHeaders())
     );
   }
   // -------------------------------------------------------------------------
@@ -301,152 +271,81 @@ var HCSafeCDXClient = class {
   // -------------------------------------------------------------------------
   /** POST test/resume */
   async resumeFlow(userTestResultId, resumed = true) {
-    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "User test result ID");
     const request = {
-      Data: {
-        UserTestResultId: resolvedUserTestResultId,
-        Resumed: resumed
-      }
+      Data: { UserTestResultId: resolvedUserTestResultId, Resumed: resumed }
     };
-    return this.execute(
+    return this.executeSafe(
       "resumeFlow",
-      () => this.http.post(this.url("test/resume"), request, this.getJsonHeaders())
+      () => 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.execute(
+    return this.executeSafe(
       "submitAnswers",
-      () => this.http.post(this.url("test/answers"), request, this.getJsonHeaders())
+      () => this.http.post(this.url("test/answers"), request, this.getAuthHeaders())
     );
   }
   /** POST test/finalize */
   async finalizeTest(userTestResultId) {
-    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "User test result ID");
     const request = {
-      Data: {
-        UserTestResultId: resolvedUserTestResultId
-      }
+      Data: { UserTestResultId: resolvedUserTestResultId }
     };
     return this.execute(
       "finalizeTest",
-      () => this.http.post(this.url("test/finalize"), request, this.getJsonHeaders())
+      () => this.http.post(this.url("test/finalize"), request, this.getAuthHeaders())
     );
   }
   // -------------------------------------------------------------------------
   // Private Helpers
   // -------------------------------------------------------------------------
-  async execute(operation, request) {
-    const response = await this.executeRaw(operation, request);
-    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 new import_hc_http.HCServiceError(operation, response.ErrorMessage, response);
-    }
-    return response;
-  }
   async executeSafe(operation, request) {
-    var _a, _b;
-    const response = await this.executeRaw(operation, request);
-    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.APIError({
-        message: (_a = response.message) != null ? _a : `${operation}: backend returned success: false`,
-        code: "BACKEND_FAILURE",
-        statusCode: 200,
-        backendMessage: (_b = response.message) != null ? _b : void 0,
-        details: response
-      });
-    }
-    return response;
-  }
-  async executeRaw(operation, request) {
+    var _a;
     let response;
     try {
       response = await request();
     } catch (err) {
-      if (err instanceof import_hc_http.APIError) {
-        throw 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}: ${err.message}`, code: "UNKNOWN_ERROR", details: err });
       }
-      throw new import_hc_http.APIError({
-        message: `${operation}: unexpected runtime failure`,
-        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
-      });
+      throw new import_hc_http.APIError({ message: `${operation}: empty response received`, code: "EMPTY_RESPONSE", details: response });
     }
-    return response;
-  }
-  isApiResponse(value) {
-    if (!value || typeof value !== "object") {
-      return false;
+    if (!this.isSafeApiResponse(response)) {
+      throw new import_hc_http.APIError({ message: `${operation}: invalid SafeCDX response structure`, code: "INVALID_RESPONSE", details: response });
     }
-    const response = value;
-    return "IsOK" in response && typeof response.IsOK === "boolean" && "Data" in response && "ErrorMessage" in response;
-  }
-  isSafeApiResponse(value) {
-    if (!value || typeof value !== "object") {
-      return false;
+    if (!response.success) {
+      throw new import_hc_http.HCServiceError(
+        operation,
+        (_a = response.message) != null ? _a : "Backend returned success: false",
+        response
+      );
     }
-    const response = value;
-    return "success" in response && typeof response.success === "boolean" && "data" in response && "message" in response && "code" in response && typeof response.code === "number";
+    return response;
   }
-  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;
+  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";
   }
   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
-    };
+    return { ...this.getHeaders(), ...this.auth.getAuthHeader() };
   }
   url(route, query) {
     return buildUrl(this.baseUrl, route, query);
@@ -462,6 +361,5 @@ var import_hc_http2 = require("@healthcloudai/hc-http");
   HCSafeCDXClient,
   HCServiceError,
   NetworkError,
-  ValidationError,
-  errorFromHttpStatus
+  ValidationError
 });