@healthcloudai/hc-safe-cdx 0.2.1 → 0.3.0

package/dist/index.cjs

@@ -20,20 +20,18 @@ 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,
+  errorFromHttpStatus: () => import_hc_http2.errorFromHttpStatus
 });
 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 +41,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}`;
 }
@@ -68,10 +66,10 @@ var HCSafeCDXClient = class {
     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.");
+      throw new import_hc_http.ConfigError("API key header name is required.");
     }
     if (!trimmedValue) {
-      throw new SafeCDXError("API key value is required.");
+      throw new import_hc_http.ConfigError("API key value is required.");
     }
     this.apiKeyHeaderName = trimmedHeaderName;
     this.apiKeyValue = trimmedValue;
@@ -84,27 +82,34 @@ 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
-   * Lists test profiles available to the authenticated patient account.
-   *
-   * TenantId is resolved by the backend from the authenticated patient context.
-   */
+       * POST test/profiles/by-account
+  
+       *
+       * TenantId is resolved by the backend from the authenticated patient context.
+       */
   async getTestProfilesByAccount(includeRegisterTestDetails = true) {
     const request = {
       Data: {
         IncludeRegisterTestDetails: includeRegisterTestDetails
       }
     };
-    return this.http.post(
-      this.url("test/profiles/by-account"),
-      request,
-      this.getJsonHeaders()
+    return this.execute(
+      "getTestProfilesByAccount",
+      () => this.http.post(
+        this.url("test/profiles/by-account"),
+        request,
+        this.getJsonHeaders()
+      )
     );
   }
   // -------------------------------------------------------------------------
@@ -115,19 +120,25 @@ 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 request = {
       Data: {
-        Gtin: gtin,
-        UserTestResultId: userTestResultId,
+        Gtin: resolvedGtin,
+        UserTestResultId: resolvedUserTestResultId,
         Metadata: {
-          ImageType: imageType
+          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.getJsonHeaders()
+      )
     );
   }
   /**
@@ -138,10 +149,12 @@ var HCSafeCDXClient = class {
    * authenticated Health Cloud headers.
    */
   async uploadImage(preSignedURL, image, contentType = "image/jpeg") {
-    const response = await fetch(preSignedURL, {
+    const resolvedPreSignedURL = this.requireValue(preSignedURL, "preSignedURL");
+    const resolvedContentType = this.requireValue(contentType, "contentType");
+    const response = await fetch(resolvedPreSignedURL, {
       method: "PUT",
       headers: {
-        "Content-Type": contentType
+        "Content-Type": resolvedContentType
       },
       body: image
     });
@@ -152,9 +165,15 @@ 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
+        }
       });
     }
   }
@@ -166,20 +185,32 @@ var HCSafeCDXClient = class {
    * Returns the direct SafeCDX response without an outer APIResponse wrapper.
    */
   async updateCvmlStatus(imageOfCaptureId, cvmlStatus) {
+    const resolvedImageOfCaptureId = this.requireValue(imageOfCaptureId, "imageOfCaptureId");
+    const resolvedCvmlStatus = this.requireValue(cvmlStatus, "cvmlStatus");
     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.getJsonHeaders())
+    );
   }
   /**
    * GET cvml/results
    * Returns the direct SafeCDX response without an outer APIResponse wrapper.
    */
   async getCvmlResults(imageOfCaptureId) {
-    return this.http.get(this.url("cvml/results", { imageOfCaptureId }), this.getAuthHeaders());
+    const resolvedImageOfCaptureId = this.requireValue(imageOfCaptureId, "imageOfCaptureId");
+    return this.executeSafe(
+      "getCvmlResults",
+      () => this.http.get(
+        this.url("cvml/results", { imageOfCaptureId: resolvedImageOfCaptureId }),
+        this.getAuthHeaders()
+      )
+    );
   }
   // -------------------------------------------------------------------------
   // Test Results
@@ -191,7 +222,10 @@ var HCSafeCDXClient = class {
         ExcludeStatus: excludeStatus
       }
     };
-    return this.http.post(this.url("test/result/pending"), request, this.getJsonHeaders());
+    return this.execute(
+      "getPendingResults",
+      () => this.http.post(this.url("test/result/pending"), request, this.getJsonHeaders())
+    );
   }
   /** POST test/result/last */
   async getLastResults(excludeStatus = "Invalid") {
@@ -200,7 +234,10 @@ var HCSafeCDXClient = class {
         ExcludeStatus: excludeStatus
       }
     };
-    return this.http.post(this.url("test/result/last"), request, this.getJsonHeaders());
+    return this.execute(
+      "getLastResults",
+      () => this.http.post(this.url("test/result/last"), request, this.getJsonHeaders())
+    );
   }
   /** POST test/result/history */
   async getTestHistory(excludeStatus = "Invalid") {
@@ -209,73 +246,188 @@ var HCSafeCDXClient = class {
         ExcludeStatus: excludeStatus
       }
     };
-    return this.http.post(this.url("test/result/history"), request, this.getJsonHeaders());
+    return this.execute(
+      "getTestHistory",
+      () => this.http.post(this.url("test/result/history"), request, this.getJsonHeaders())
+    );
   }
   /**
    * POST test/result/details
    * Returns the direct SafeCDX response without an outer APIResponse wrapper.
    */
   async getResultDetails(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
     const request = {
       Data: {
-        UserTestResultId: userTestResultId
+        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.getJsonHeaders())
+    );
   }
   /** POST test/result/pdf */
   async getResultPdf(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
     const request = {
       Data: {
-        UserTestResultId: userTestResultId
+        UserTestResultId: resolvedUserTestResultId
       }
     };
-    return this.http.post(this.url("test/result/pdf"), request, this.getJsonHeaders());
+    return this.execute(
+      "getResultPdf",
+      () => this.http.post(this.url("test/result/pdf"), request, this.getJsonHeaders())
+    );
   }
   /**
    * POST test/result/image/capture
    * Returns the direct SafeCDX response without an outer APIResponse wrapper.
    */
   async getImageCaptureUrl(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
     const request = {
       Data: {
-        UserTestResultId: userTestResultId
+        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.getJsonHeaders())
+    );
   }
   // -------------------------------------------------------------------------
   // Resume / Answers / Finalize
   // -------------------------------------------------------------------------
   /** POST test/resume */
   async resumeFlow(userTestResultId, resumed = true) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
     const request = {
       Data: {
-        UserTestResultId: userTestResultId,
+        UserTestResultId: resolvedUserTestResultId,
         Resumed: resumed
       }
     };
-    return this.http.post(this.url("test/resume"), request, this.getJsonHeaders());
+    return this.execute(
+      "resumeFlow",
+      () => this.http.post(this.url("test/resume"), request, this.getJsonHeaders())
+    );
   }
   /** POST test/answers */
   async submitAnswers(submission) {
     const request = {
       Data: submission
     };
-    return this.http.post(this.url("test/answers"), request, this.getJsonHeaders());
+    return this.execute(
+      "submitAnswers",
+      () => this.http.post(this.url("test/answers"), request, this.getJsonHeaders())
+    );
   }
   /** POST test/finalize */
   async finalizeTest(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
     const request = {
       Data: {
-        UserTestResultId: userTestResultId
+        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.getJsonHeaders())
+    );
   }
   // -------------------------------------------------------------------------
   // 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) {
+    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
+      });
+    }
+    return 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;
+  }
+  isSafeApiResponse(value) {
+    if (!value || typeof value !== "object") {
+      return false;
+    }
+    const response = value;
+    return "success" in response && typeof response.success === "boolean" && "data" in response && "message" in response && "code" in response && typeof response.code === "number";
+  }
+  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;
+  }
   getAuthHeaders() {
     return {
       ...this.loginClient.getAuthHeader(),
@@ -302,14 +454,14 @@ 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,
+  errorFromHttpStatus
 });

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { HCLoginClient } from '@healthcloudai/hc-login-connector';
 import { HttpClient } from '@healthcloudai/hc-http';
+export { APIError, ConfigError, HCServiceError, NetworkError, ValidationError, errorFromHttpStatus } from '@healthcloudai/hc-http';
 
 type Environment = "dev" | "uat" | "prod";
 /**
@@ -469,7 +470,7 @@ declare class HCSafeCDXClient {
     getTestProfileByGTIN(gtin: string): Promise<APIResponse<GetTestProfileByGTINData>>;
     /**
      * POST test/profiles/by-account
-     * Lists test profiles available to the authenticated patient account.
+
      *
      * TenantId is resolved by the backend from the authenticated patient context.
      */
@@ -521,14 +522,16 @@ declare class HCSafeCDXClient {
     submitAnswers(submission: SubmitAnswersRequest): Promise<APIResponse<SubmitAnswersData>>;
     /** POST test/finalize */
     finalizeTest(userTestResultId: string): Promise<APIResponse<FinalizeTestData>>;
+    protected execute<T>(operation: string, request: () => Promise<APIResponse<T>>): Promise<APIResponse<T>>;
+    protected executeSafe<T>(operation: string, request: () => Promise<SafeAPIResponse<T>>): Promise<SafeAPIResponse<T>>;
+    private executeRaw;
+    private isApiResponse;
+    private isSafeApiResponse;
+    private requireValue;
     private getAuthHeaders;
     private getJsonHeaders;
     private getApiKeyHeader;
     private url;
 }
 
-declare class ConfigError extends Error {
-    constructor(message: string);
-}
-
-export { type APIRequest, type APIResponse, type AnswerResult, type CaptureState, ConfigError, type CreateUploadUrlData, type CreateUploadUrlRequest, type CvmlImageOfCaptureResult, type CvmlParsedResult, type CvmlResultsData, type DiagnosticProfileCta, type DiagnosticProfileData, type DiagnosticProfileDecision, type DiagnosticProfileDecisionResult, type DiagnosticProfileIndication, type DiagnosticProfileTestInfo, type DisclaimerDetail, type EntityReferenceData, type Environment, type ExcludeStatusRequest, type FinalizeTestData, type FinalizeTestRequest, type GetCvmlResultsResponse, type GetImageCaptureUrlRequest, type GetImageCaptureUrlResponse, type GetLastResultsData, type GetLastResultsRequest, type GetPendingResultsData, type GetPendingResultsRequest, type GetResultDetailsRequest, type GetResultDetailsResponse, type GetResultPdfData, type GetResultPdfRequest, type GetTestHistoryData, type GetTestHistoryRequest, type GetTestProfileByGTINData, type GetTestProfilesByAccountData, type GetTestProfilesByAccountRequest, HCSafeCDXClient, type ImageOfCaptureResult, type ProductAssetDetail, type QuestionnaireAnalyte, type QuestionnaireAnalyteResponse, type QuestionnaireSnapshot, type QuestionnaireValidityItem, type RegisterTestDetail, type ReportedAnswerResult, type ResumeFlowData, type ResumeFlowRequest, type ResumeFlowResult, type SafeAPIResponse, type SubmitAnswersData, type SubmitAnswersRequest, type TestProfileAnalyte, type TestProfileAnalyteResponse, type TestProfileArticle, type TestProfileBillingInfo, type TestProfileByAccountItem, type TestProfileInstruction, type TestProfileResult, type TestProfileScanImageDetail, type TestProfileTerritory, type TestResultDetails, type TestResultSummary, type UpdateCvmlStatusRequest, type UpdateCvmlStatusResponse, type UploadMetadata, type UserTestResultIdRequest };
+export { type APIRequest, type APIResponse, type AnswerResult, type CaptureState, type CreateUploadUrlData, type CreateUploadUrlRequest, type CvmlImageOfCaptureResult, type CvmlParsedResult, type CvmlResultsData, type DiagnosticProfileCta, type DiagnosticProfileData, type DiagnosticProfileDecision, type DiagnosticProfileDecisionResult, type DiagnosticProfileIndication, type DiagnosticProfileTestInfo, type DisclaimerDetail, type EntityReferenceData, type Environment, type ExcludeStatusRequest, type FinalizeTestData, type FinalizeTestRequest, type GetCvmlResultsResponse, type GetImageCaptureUrlRequest, type GetImageCaptureUrlResponse, type GetLastResultsData, type GetLastResultsRequest, type GetPendingResultsData, type GetPendingResultsRequest, type GetResultDetailsRequest, type GetResultDetailsResponse, type GetResultPdfData, type GetResultPdfRequest, type GetTestHistoryData, type GetTestHistoryRequest, type GetTestProfileByGTINData, type GetTestProfilesByAccountData, type GetTestProfilesByAccountRequest, HCSafeCDXClient, type ImageOfCaptureResult, type ProductAssetDetail, type QuestionnaireAnalyte, type QuestionnaireAnalyteResponse, type QuestionnaireSnapshot, type QuestionnaireValidityItem, type RegisterTestDetail, type ReportedAnswerResult, type ResumeFlowData, type ResumeFlowRequest, type ResumeFlowResult, type SafeAPIResponse, type SubmitAnswersData, type SubmitAnswersRequest, type TestProfileAnalyte, type TestProfileAnalyteResponse, type TestProfileArticle, type TestProfileBillingInfo, type TestProfileByAccountItem, type TestProfileInstruction, type TestProfileResult, type TestProfileScanImageDetail, type TestProfileTerritory, type TestResultDetails, type TestResultSummary, type UpdateCvmlStatusRequest, type UpdateCvmlStatusResponse, type UploadMetadata, type UserTestResultIdRequest };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { HCLoginClient } from '@healthcloudai/hc-login-connector';
 import { HttpClient } from '@healthcloudai/hc-http';
+export { APIError, ConfigError, HCServiceError, NetworkError, ValidationError, errorFromHttpStatus } from '@healthcloudai/hc-http';
 
 type Environment = "dev" | "uat" | "prod";
 /**
@@ -469,7 +470,7 @@ declare class HCSafeCDXClient {
     getTestProfileByGTIN(gtin: string): Promise<APIResponse<GetTestProfileByGTINData>>;
     /**
      * POST test/profiles/by-account
-     * Lists test profiles available to the authenticated patient account.
+
      *
      * TenantId is resolved by the backend from the authenticated patient context.
      */
@@ -521,14 +522,16 @@ declare class HCSafeCDXClient {
     submitAnswers(submission: SubmitAnswersRequest): Promise<APIResponse<SubmitAnswersData>>;
     /** POST test/finalize */
     finalizeTest(userTestResultId: string): Promise<APIResponse<FinalizeTestData>>;
+    protected execute<T>(operation: string, request: () => Promise<APIResponse<T>>): Promise<APIResponse<T>>;
+    protected executeSafe<T>(operation: string, request: () => Promise<SafeAPIResponse<T>>): Promise<SafeAPIResponse<T>>;
+    private executeRaw;
+    private isApiResponse;
+    private isSafeApiResponse;
+    private requireValue;
     private getAuthHeaders;
     private getJsonHeaders;
     private getApiKeyHeader;
     private url;
 }
 
-declare class ConfigError extends Error {
-    constructor(message: string);
-}
-
-export { type APIRequest, type APIResponse, type AnswerResult, type CaptureState, ConfigError, type CreateUploadUrlData, type CreateUploadUrlRequest, type CvmlImageOfCaptureResult, type CvmlParsedResult, type CvmlResultsData, type DiagnosticProfileCta, type DiagnosticProfileData, type DiagnosticProfileDecision, type DiagnosticProfileDecisionResult, type DiagnosticProfileIndication, type DiagnosticProfileTestInfo, type DisclaimerDetail, type EntityReferenceData, type Environment, type ExcludeStatusRequest, type FinalizeTestData, type FinalizeTestRequest, type GetCvmlResultsResponse, type GetImageCaptureUrlRequest, type GetImageCaptureUrlResponse, type GetLastResultsData, type GetLastResultsRequest, type GetPendingResultsData, type GetPendingResultsRequest, type GetResultDetailsRequest, type GetResultDetailsResponse, type GetResultPdfData, type GetResultPdfRequest, type GetTestHistoryData, type GetTestHistoryRequest, type GetTestProfileByGTINData, type GetTestProfilesByAccountData, type GetTestProfilesByAccountRequest, HCSafeCDXClient, type ImageOfCaptureResult, type ProductAssetDetail, type QuestionnaireAnalyte, type QuestionnaireAnalyteResponse, type QuestionnaireSnapshot, type QuestionnaireValidityItem, type RegisterTestDetail, type ReportedAnswerResult, type ResumeFlowData, type ResumeFlowRequest, type ResumeFlowResult, type SafeAPIResponse, type SubmitAnswersData, type SubmitAnswersRequest, type TestProfileAnalyte, type TestProfileAnalyteResponse, type TestProfileArticle, type TestProfileBillingInfo, type TestProfileByAccountItem, type TestProfileInstruction, type TestProfileResult, type TestProfileScanImageDetail, type TestProfileTerritory, type TestResultDetails, type TestResultSummary, type UpdateCvmlStatusRequest, type UpdateCvmlStatusResponse, type UploadMetadata, type UserTestResultIdRequest };
+export { type APIRequest, type APIResponse, type AnswerResult, type CaptureState, type CreateUploadUrlData, type CreateUploadUrlRequest, type CvmlImageOfCaptureResult, type CvmlParsedResult, type CvmlResultsData, type DiagnosticProfileCta, type DiagnosticProfileData, type DiagnosticProfileDecision, type DiagnosticProfileDecisionResult, type DiagnosticProfileIndication, type DiagnosticProfileTestInfo, type DisclaimerDetail, type EntityReferenceData, type Environment, type ExcludeStatusRequest, type FinalizeTestData, type FinalizeTestRequest, type GetCvmlResultsResponse, type GetImageCaptureUrlRequest, type GetImageCaptureUrlResponse, type GetLastResultsData, type GetLastResultsRequest, type GetPendingResultsData, type GetPendingResultsRequest, type GetResultDetailsRequest, type GetResultDetailsResponse, type GetResultPdfData, type GetResultPdfRequest, type GetTestHistoryData, type GetTestHistoryRequest, type GetTestProfileByGTINData, type GetTestProfilesByAccountData, type GetTestProfilesByAccountRequest, HCSafeCDXClient, type ImageOfCaptureResult, type ProductAssetDetail, type QuestionnaireAnalyte, type QuestionnaireAnalyteResponse, type QuestionnaireSnapshot, type QuestionnaireValidityItem, type RegisterTestDetail, type ReportedAnswerResult, type ResumeFlowData, type ResumeFlowRequest, type ResumeFlowResult, type SafeAPIResponse, type SubmitAnswersData, type SubmitAnswersRequest, type TestProfileAnalyte, type TestProfileAnalyteResponse, type TestProfileArticle, type TestProfileBillingInfo, type TestProfileByAccountItem, type TestProfileInstruction, type TestProfileResult, type TestProfileScanImageDetail, type TestProfileTerritory, type TestResultDetails, type TestResultSummary, type UpdateCvmlStatusRequest, type UpdateCvmlStatusResponse, type UploadMetadata, type UserTestResultIdRequest };

package/dist/index.js

@@ -1,12 +1,10 @@
 // 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);
-  }
-};
+import {
+  APIError,
+  ConfigError,
+  HCServiceError,
+  ValidationError
+} from "@healthcloudai/hc-http";
 var ENV_HOST = {
   dev: "dev-api-hcs.healthcloud-services.com",
   uat: "uat-api-hcs.healthcloud-services.com",
@@ -16,7 +14,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 ConfigError("Invalid Safe CDX environment.");
   }
   return `https://${host}/${ROUTE_PREFIX}`;
 }
@@ -41,10 +39,10 @@ var HCSafeCDXClient = class {
     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.");
+      throw new ConfigError("API key header name is required.");
     }
     if (!trimmedValue) {
-      throw new SafeCDXError("API key value is required.");
+      throw new ConfigError("API key value is required.");
     }
     this.apiKeyHeaderName = trimmedHeaderName;
     this.apiKeyValue = trimmedValue;
@@ -57,27 +55,34 @@ 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
-   * Lists test profiles available to the authenticated patient account.
-   *
-   * TenantId is resolved by the backend from the authenticated patient context.
-   */
+       * POST test/profiles/by-account
+  
+       *
+       * TenantId is resolved by the backend from the authenticated patient context.
+       */
   async getTestProfilesByAccount(includeRegisterTestDetails = true) {
     const request = {
       Data: {
         IncludeRegisterTestDetails: includeRegisterTestDetails
       }
     };
-    return this.http.post(
-      this.url("test/profiles/by-account"),
-      request,
-      this.getJsonHeaders()
+    return this.execute(
+      "getTestProfilesByAccount",
+      () => this.http.post(
+        this.url("test/profiles/by-account"),
+        request,
+        this.getJsonHeaders()
+      )
     );
   }
   // -------------------------------------------------------------------------
@@ -88,19 +93,25 @@ 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 request = {
       Data: {
-        Gtin: gtin,
-        UserTestResultId: userTestResultId,
+        Gtin: resolvedGtin,
+        UserTestResultId: resolvedUserTestResultId,
         Metadata: {
-          ImageType: imageType
+          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.getJsonHeaders()
+      )
     );
   }
   /**
@@ -111,10 +122,12 @@ var HCSafeCDXClient = class {
    * authenticated Health Cloud headers.
    */
   async uploadImage(preSignedURL, image, contentType = "image/jpeg") {
-    const response = await fetch(preSignedURL, {
+    const resolvedPreSignedURL = this.requireValue(preSignedURL, "preSignedURL");
+    const resolvedContentType = this.requireValue(contentType, "contentType");
+    const response = await fetch(resolvedPreSignedURL, {
       method: "PUT",
       headers: {
-        "Content-Type": contentType
+        "Content-Type": resolvedContentType
       },
       body: image
     });
@@ -125,9 +138,15 @@ var HCSafeCDXClient = class {
       } catch {
         body = void 0;
       }
-      throw new SafeCDXError(`Image upload failed with HTTP ${response.status}.`, {
-        status: response.status,
-        body
+      throw new 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
+        }
       });
     }
   }
@@ -139,20 +158,32 @@ var HCSafeCDXClient = class {
    * Returns the direct SafeCDX response without an outer APIResponse wrapper.
    */
   async updateCvmlStatus(imageOfCaptureId, cvmlStatus) {
+    const resolvedImageOfCaptureId = this.requireValue(imageOfCaptureId, "imageOfCaptureId");
+    const resolvedCvmlStatus = this.requireValue(cvmlStatus, "cvmlStatus");
     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.getJsonHeaders())
+    );
   }
   /**
    * GET cvml/results
    * Returns the direct SafeCDX response without an outer APIResponse wrapper.
    */
   async getCvmlResults(imageOfCaptureId) {
-    return this.http.get(this.url("cvml/results", { imageOfCaptureId }), this.getAuthHeaders());
+    const resolvedImageOfCaptureId = this.requireValue(imageOfCaptureId, "imageOfCaptureId");
+    return this.executeSafe(
+      "getCvmlResults",
+      () => this.http.get(
+        this.url("cvml/results", { imageOfCaptureId: resolvedImageOfCaptureId }),
+        this.getAuthHeaders()
+      )
+    );
   }
   // -------------------------------------------------------------------------
   // Test Results
@@ -164,7 +195,10 @@ var HCSafeCDXClient = class {
         ExcludeStatus: excludeStatus
       }
     };
-    return this.http.post(this.url("test/result/pending"), request, this.getJsonHeaders());
+    return this.execute(
+      "getPendingResults",
+      () => this.http.post(this.url("test/result/pending"), request, this.getJsonHeaders())
+    );
   }
   /** POST test/result/last */
   async getLastResults(excludeStatus = "Invalid") {
@@ -173,7 +207,10 @@ var HCSafeCDXClient = class {
         ExcludeStatus: excludeStatus
       }
     };
-    return this.http.post(this.url("test/result/last"), request, this.getJsonHeaders());
+    return this.execute(
+      "getLastResults",
+      () => this.http.post(this.url("test/result/last"), request, this.getJsonHeaders())
+    );
   }
   /** POST test/result/history */
   async getTestHistory(excludeStatus = "Invalid") {
@@ -182,73 +219,188 @@ var HCSafeCDXClient = class {
         ExcludeStatus: excludeStatus
       }
     };
-    return this.http.post(this.url("test/result/history"), request, this.getJsonHeaders());
+    return this.execute(
+      "getTestHistory",
+      () => this.http.post(this.url("test/result/history"), request, this.getJsonHeaders())
+    );
   }
   /**
    * POST test/result/details
    * Returns the direct SafeCDX response without an outer APIResponse wrapper.
    */
   async getResultDetails(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
     const request = {
       Data: {
-        UserTestResultId: userTestResultId
+        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.getJsonHeaders())
+    );
   }
   /** POST test/result/pdf */
   async getResultPdf(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
     const request = {
       Data: {
-        UserTestResultId: userTestResultId
+        UserTestResultId: resolvedUserTestResultId
       }
     };
-    return this.http.post(this.url("test/result/pdf"), request, this.getJsonHeaders());
+    return this.execute(
+      "getResultPdf",
+      () => this.http.post(this.url("test/result/pdf"), request, this.getJsonHeaders())
+    );
   }
   /**
    * POST test/result/image/capture
    * Returns the direct SafeCDX response without an outer APIResponse wrapper.
    */
   async getImageCaptureUrl(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
     const request = {
       Data: {
-        UserTestResultId: userTestResultId
+        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.getJsonHeaders())
+    );
   }
   // -------------------------------------------------------------------------
   // Resume / Answers / Finalize
   // -------------------------------------------------------------------------
   /** POST test/resume */
   async resumeFlow(userTestResultId, resumed = true) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
     const request = {
       Data: {
-        UserTestResultId: userTestResultId,
+        UserTestResultId: resolvedUserTestResultId,
         Resumed: resumed
       }
     };
-    return this.http.post(this.url("test/resume"), request, this.getJsonHeaders());
+    return this.execute(
+      "resumeFlow",
+      () => this.http.post(this.url("test/resume"), request, this.getJsonHeaders())
+    );
   }
   /** POST test/answers */
   async submitAnswers(submission) {
     const request = {
       Data: submission
     };
-    return this.http.post(this.url("test/answers"), request, this.getJsonHeaders());
+    return this.execute(
+      "submitAnswers",
+      () => this.http.post(this.url("test/answers"), request, this.getJsonHeaders())
+    );
   }
   /** POST test/finalize */
   async finalizeTest(userTestResultId) {
+    const resolvedUserTestResultId = this.requireValue(userTestResultId, "userTestResultId");
     const request = {
       Data: {
-        UserTestResultId: userTestResultId
+        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.getJsonHeaders())
+    );
   }
   // -------------------------------------------------------------------------
   // Private Helpers
   // -------------------------------------------------------------------------
+  async execute(operation, request) {
+    const response = await this.executeRaw(operation, request);
+    if (!this.isApiResponse(response)) {
+      throw new APIError({
+        message: `${operation}: invalid API response structure`,
+        code: "INVALID_RESPONSE",
+        details: response
+      });
+    }
+    if (!response.IsOK) {
+      throw new 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 APIError({
+        message: `${operation}: invalid SafeCDX response structure`,
+        code: "INVALID_RESPONSE",
+        details: response
+      });
+    }
+    if (!response.success) {
+      throw new 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) {
+    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
+      });
+    }
+    return 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;
+  }
+  isSafeApiResponse(value) {
+    if (!value || typeof value !== "object") {
+      return false;
+    }
+    const response = value;
+    return "success" in response && typeof response.success === "boolean" && "data" in response && "message" in response && "code" in response && typeof response.code === "number";
+  }
+  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;
+  }
   getAuthHeaders() {
     return {
       ...this.loginClient.getAuthHeader(),
@@ -275,13 +427,20 @@ var HCSafeCDXClient = class {
 };
 
 // src/errors.ts
-var ConfigError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ConfigError";
-  }
-};
+import {
+  APIError as APIError2,
+  ConfigError as ConfigError2,
+  HCServiceError as HCServiceError2,
+  NetworkError,
+  ValidationError as ValidationError2,
+  errorFromHttpStatus
+} from "@healthcloudai/hc-http";
 export {
-  ConfigError,
-  HCSafeCDXClient
+  APIError2 as APIError,
+  ConfigError2 as ConfigError,
+  HCSafeCDXClient,
+  HCServiceError2 as HCServiceError,
+  NetworkError,
+  ValidationError2 as ValidationError,
+  errorFromHttpStatus
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@healthcloudai/hc-safe-cdx",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Healthcheck Safe CDX connector.",
   "author": "Healthcheck Systems Inc",
   "license": "MIT",
@@ -33,8 +33,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@healthcloudai/hc-http": "^0.0.6",
-    "@healthcloudai/hc-login-connector": "^0.1.0"
+    "@healthcloudai/hc-http": "^0.1.0",
+    "@healthcloudai/hc-login-connector": "^0.2.0"
   },
   "peerDependencies": {
     "react-native": ">=0.70.0"