@healthcloudai/hc-safe-cdx 0.1.3 → 0.2.0

package/README.md

@@ -9,6 +9,7 @@ The connector follows the same shared-client pattern used by other Health Cloud
 - `HCSafeCDXClient` builds Safe CDX URLs, wraps request payloads, and exposes one method per Safe CDX route.
 
 Safe CDX has its own API host. The connector uses `HCLoginClient` for authentication only; it does not use `loginClient.getBaseUrl()` for Safe CDX routes.
+Like `HCHealthRecordClient`, `HCSafeCDXClient` reads the configured environment from `HCLoginClient` and derives its own service base URL internally.
 
 Image upload is handled separately because the upload target is a pre-signed S3 URL, not a Safe CDX API route.
 
@@ -33,14 +34,10 @@ const http = new FetchClient();
 
 const loginClient = new HCLoginClient(http);
 
-// Configure and authenticate the login client first.
-// Exact login/configuration calls depend on the login connector setup used by the app.
+loginClient.configure("healthcheck", "dev");
+await loginClient.login(email, password);
 
-const safeCdx = new HCSafeCDXClient(http, loginClient, {
-  environment: "dev",
-  defaultLanguage: "en",
-  defaultImageType: "jpg",
-});
+const safeCdx = new HCSafeCDXClient(http, loginClient);
 ```
 
 The connector does not perform login. The consuming application should authenticate through the Health Cloud login connector first. Safe CDX then reuses the authenticated headers from `loginClient.getAuthHeader()`.
@@ -83,9 +80,10 @@ The client receives both the HTTP client and the login client:
 const http = new FetchClient();
 const loginClient = new HCLoginClient(http);
 
-const safeCdx = new HCSafeCDXClient(http, loginClient, {
-  environment: "dev",
-});
+loginClient.configure("healthcheck", "dev");
+await loginClient.login(email, password);
+
+const safeCdx = new HCSafeCDXClient(http, loginClient);
 ```
 
 The shared `HttpClient` is responsible for executing HTTP requests.
@@ -94,7 +92,7 @@ The `HCLoginClient` is responsible for the authenticated request headers.
 
 The Safe CDX client is responsible for:
 
-- resolving the Safe CDX environment host
+- deriving the Safe CDX base URL from the login client's configured environment
 - building Safe CDX URLs
 - adding auth headers from `HCLoginClient`
 - adding optional API key headers when configured
@@ -104,31 +102,33 @@ The Safe CDX client is responsible for:
 
 The Safe CDX client does not create its own internal `fetch` helpers for standard Safe CDX API routes.
 
-## Environment Configuration
+## Base URL Configuration
 
-The connector supports the following environments:
+Safe CDX base URL configuration follows the same constructor pattern as the Health Record connector:
 
 ```ts
-const safeCdx = new HCSafeCDXClient(http, loginClient, {
-  environment: "dev",
-});
+loginClient.configure("healthcheck", "dev");
+
+const safeCdx = new HCSafeCDXClient(http, loginClient);
 ```
 
-Available environments:
+The Safe CDX client reads the environment from:
 
 ```ts
-"dev" | "uat" | "prod"
+loginClient.getEnvironment()
 ```
 
-Safe CDX environment host mapping is handled internally by the connector:
+Safe CDX still uses its own service base URL. It does not reuse `loginClient.getBaseUrl()`.
+
+Environment mapping is handled internally by the connector:
 
 ```txt
-dev  -> dev-api-hcs.healthcloud-services.com
-uat  -> uat-api-hcs.healthcloud-services.com
-prod -> api-hcs.healthcloud-services.com
+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
 ```
 
-These hosts are separate from the login connector base URL.
+These base URLs are separate from the login connector base URL.
 
 ## Authentication
 
@@ -149,12 +149,10 @@ const http = new FetchClient();
 
 const loginClient = new HCLoginClient(http);
 
-// loginClient.configure(...)
-// await loginClient.loginPatient(...)
+loginClient.configure("healthcheck", "dev");
+await loginClient.login(email, password);
 
-const safeCdx = new HCSafeCDXClient(http, loginClient, {
-  environment: "dev",
-});
+const safeCdx = new HCSafeCDXClient(http, loginClient);
 ```
 
 Safe CDX does not manually receive a token. It does not expose `setAccessToken()`. Auth is inherited from the configured login client.
@@ -228,9 +226,7 @@ If `IsOK` is `false`, the client throws `SafeCDXError`.
 
 This validation exists because an HTTP `200` response does not always mean the backend operation succeeded. The HTTP client validates the transport layer, while the Safe CDX client validates the API response envelope.
 
-Some endpoints return a raw service result instead of the standard `ApiResponse` envelope. Those methods return the raw result directly.
-
-Raw result methods include:
+For the following methods, the client returns the received response directly without applying `ApiResponse` validation:
 
 ```ts
 updateCvmlStatus(...)
@@ -264,13 +260,10 @@ const http = new FetchClient();
 
 const loginClient = new HCLoginClient(http);
 
-// Configure and authenticate loginClient first.
+loginClient.configure("healthcheck", "dev");
+await loginClient.login(email, password);
 
-const safeCdx = new HCSafeCDXClient(http, loginClient, {
-  environment: "dev",
-  defaultLanguage: "en",
-  defaultImageType: "jpg",
-});
+const safeCdx = new HCSafeCDXClient(http, loginClient);
 ```
 
 ### 1. Get available test profiles
@@ -336,30 +329,6 @@ await safeCdx.submitAnswers({
 ```ts
 await safeCdx.finalizeTest({
   UserTestResultId: userTestResultId,
-  ctaResult: {
-    id: "2",
-    title: "Connect with a Telehealth Provider for Next Steps",
-    instructions: "Share your test results with a telehealth provider for next steps.",
-    urlText: "Connect with Telehealth",
-    url: "https://example.com/start",
-  },
-  indicationResult: {
-    id: "4",
-    title: "Indication",
-    text: "Results suggest follow-up may be needed.",
-    recommendTitle: "Recommendation",
-    recommendText: "Review the result with a healthcare provider.",
-    ctaId: "2",
-  },
-  decisionResult: {
-    calculation: "Total: analyte.responses.score",
-    results: [
-      {
-        indicationId: "4",
-        value: "4",
-      },
-    ],
-  },
 });
 ```
 
@@ -404,22 +373,201 @@ These values should be stored by the consuming app and passed to the next SDK me
 ### getTestProfileByGTIN
 
 ```ts
-const profile = await safeCdx.getTestProfileByGTIN(gtin, language);
+const profile = await safeCdx.getTestProfileByGTIN(gtin);
 ```
 
 Resolves a test profile by GTIN barcode.
 
-`language` is optional. If not provided, the client uses `defaultLanguage` from config when available.
+#### API Response example
 
-
-### getTestProfile
-
-```ts
-const profile = await safeCdx.getTestProfile(payload);
+```json
+{
+  "Data": {
+    "ID": "6a104bba6068dd9a213db810",
+    "FHIRID": null,
+    "CQLID": null,
+    "TestName": "UTI Test + Treat",
+    "CustomTestName": "UTI Test + Treat",
+    "IsDeactivated": false,
+    "IsOrderable": true,
+    "EnablePublicHealthReporting": true,
+    "IsSelfAssessmentMode": true,
+    "CaptureMethod": 0,
+    "IsMLDisabled": false,
+    "ShortName": "UTI Test + Treat",
+    "DescriptionHTML": null,
+    "OrderableName": "Winx Health",
+    "VendorName": null,
+    "ManufactureName": null,
+    "VendorTestID": "0123",
+    "Sku": "SH00131",
+    "LabTestType": null,
+    "TestClassification": "NOT_SPECIFIED",
+    "KitRegistrationRequired": false,
+    "RequiresProviderVerificationOfResults": false,
+    "DiagnosticProfile": {
+      "_id": "6780031a991814469e88237f",
+      "Created": "2025-01-09T17:10:50.8Z",
+      "Modified": "2026-05-06T12:39:08.732Z",
+      "TestInfo": {
+        "gtin": "860002060439",
+        "testInfoHeader": "Winx Health",
+        "productName": "Winx UTI Test + Treat",
+        "testCategory": "Rapid",
+        "fdaStatus": "EUA",
+        "cvmlTestName": "winx-uti",
+        "cvmlDuration": 20,
+        "isCVMLResult": true,
+        "accountIds": [
+          "winxhealth",
+          "safehealth",
+          "test-account",
+          "speedyswab",
+          "healthcheck"
+        ],
+        "cvmlRetryLimit": 2,
+        "failoverEnabled": true,
+        "cvmlPollingPolicy": "FullResult"
+      },
+      "Analyte": [
+        {
+          "_id": "1",
+          "DisplayOrder": 1,
+          "Display": "CVML",
+          "Name": "Leukocyte",
+          "Question": "What is the Leukocyte reading?",
+          "Image": "/analyte/WinxLeuk.png",
+          "Responses": [
+            {
+              "value": "Negative -",
+              "displayOrder": 1,
+              "storedValue": "Neg",
+              "cvmlValue": "Neg",
+              "score": "0"
+            },
+            {
+              "value": "Positive 70+",
+              "displayOrder": 3,
+              "storedValue": "70+",
+              "cvmlValue": "70+",
+              "score": "4"
+            }
+          ]
+        },
+        {
+          "_id": "2",
+          "DisplayOrder": 2,
+          "Display": "CVML",
+          "Name": "Nitrite",
+          "Question": "What is the Nitrite reading?",
+          "Image": "/analyte/WinxNitr.png",
+          "Responses": [
+            {
+              "value": "Negative",
+              "displayOrder": 1,
+              "storedValue": "Neg",
+              "cvmlValue": "Neg",
+              "score": "0"
+            },
+            {
+              "value": "Positive High++",
+              "displayOrder": 3,
+              "storedValue": "High++",
+              "cvmlValue": "High++",
+              "score": "2"
+            }
+          ]
+        }
+      ],
+      "Cta": [
+        {
+          "id": "1",
+          "title": "No UTI is detected",
+          "instructions": "If you're still having symptoms, we recommend talking to your doctor about additional testing.",
+          "linkType": "url",
+          "linkText": "Find a Doctor",
+          "linkValue": "https://book.zocdoc.com/?utm_source=winx&utm_medium=app&utm_campaign=testandtreat"
+        }
+      ],
+      "Indication": [
+        {
+          "id": "4",
+          "title": "Indication",
+          "text": "Results suggest you have a UTI",
+          "recommendTitle": "Recommendation",
+          "recommendText": "Drink lots of water and connect with a doctor to discuss treatment and next steps.",
+          "ctaId": "2"
+        }
+      ],
+      "Decision": [
+        {
+          "calculation": "Total: analyte.responses.score",
+          "results": [
+            {
+              "indicationId": "4",
+              "value": "4"
+            }
+          ]
+        }
+      ]
+    },
+    "ProductAssetDetail": {
+      "imageURL": "https://safe-content-cache-us-west-2-quality-speed.s3-us-west-2.amazonaws.com/LabTestOrderable/ProductAsset/Image/47197f0c75844ba3b11335f7bfe1959b-639062362985442065.png",
+      "body": "<p></p>"
+    },
+    "DisclaimerDetail": {
+      "body": "<p><span style=\"font-family: Avenir, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif; font-size: 14pt;\">At this time please refer back to your paper Instructions For Use (IFU).</span></p>",
+      "title": "Record Results",
+      "continueButtonTitle": "Continue",
+      "showDisclaimer": false
+    },
+    "ScanImageDetail": {
+      "ImageUrl": "https://safe-content-cache-us-west-2-quality-speed.s3-us-west-2.amazonaws.com/LabTestOrderable/ScanImage/Image/590172d7548e4b3eb09bfe42679fc6b1-638900206144635626.png"
+    },
+    "Instructions": [
+      {
+        "NavigationTitle": "Instructional Video",
+        "Type": "CollectionInstructionOnly",
+        "Title": "Instructional Video",
+        "ButtonTitle": "Continue",
+        "TimeInSeconds": 0,
+        "VideoUrl": "https://safe-content-cache-us-west-2-quality-speed.s3-us-west-2.amazonaws.com/LabTestOrderable/CollectionInstruction/Video/3a74d7091d65455ab675f8ddd5f9d9d5-638918232791589391.mp4",
+        "SequenceOrder": 0
+      }
+    ],
+    "BillingInfo": {
+      "Taxable": false
+    },
+    "Associations": null,
+    "TestReportAsset": null,
+    "Articles": [],
+    "TestResults": [
+      {
+        "PatientTestResult": 0,
+        "ResultTitle": "Positive",
+        "ResultDisplay": "Positive",
+        "TreatmentPlanDescription": "",
+        "IsReturnToDashboardAllowed": false,
+        "IsOrderTestAllowed": false,
+        "IsFindTestRetailerAllowed": false
+      }
+    ],
+    "GS1GTINs": null,
+    "Included": null,
+    "LOINCCodes": null,
+    "TestLOINCCodes": null,
+    "TestSNOMEDCTCodes": null,
+    "Created": "2024-12-23T18:00:48.619Z",
+    "Modified": "2026-05-13T17:07:07.048Z",
+    "CreatedByID": null,
+    "ModifiedByID": null,
+    "TenantID": null
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
 ```
 
-Returns the full test profile for a given payload.
-
 ### getTestProfilesByAccount
 
 ```ts
@@ -436,6 +584,61 @@ const profiles = await safeCdx.getTestProfilesByAccount({
 });
 ```
 
+#### API Response example
+
+```json
+{
+  "Data": {
+    "success": true,
+    "data": [
+      {
+        "gtin": "810172700093",
+        "productName": "Speedy Swab COVID-19 + Flu Self-Test",
+        "description": "",
+        "testKitImageURL": "https://safe-content-cache-us-west-2-quality-speed.s3-us-west-2.amazonaws.com/LabTestOrderable/RegisterTest/Image/4307c803740644ab8c4594f69783c1d8-638694157517533356.png",
+        "language": "en",
+        "registerTestDetail": {
+          "title": "Scan the barcode",
+          "description": "<p><span style=\"font-size: 12pt; font-family: Avenir, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif;\">Hold your phone over the barcode on the box.</span></p>",
+          "buttonTitle": "Scan Code",
+          "imageURL": "https://safe-content-cache-us-west-2-quality-speed.s3-us-west-2.amazonaws.com/LabTestOrderable/RegisterTest/Image/1ccc293f924a4c5bb2c5fc76f474c625-638769599179275771.png"
+        }
+      },
+      {
+        "gtin": "860002060439",
+        "productName": "Winx UTI Test + Treat",
+        "description": "",
+        "testKitImageURL": "https://safe-content-cache-us-west-2-quality-speed.s3-us-west-2.amazonaws.com/LabTestOrderable/RegisterTest/Image/36649cb6377c435a9e4f83af0f2fea46-639058689126409862.png",
+        "language": "en",
+        "registerTestDetail": {
+          "title": "",
+          "description": "<p></p>",
+          "buttonTitle": "Scan Barcode on the Box",
+          "imageURL": "https://safe-content-cache-us-west-2-quality-speed.s3-us-west-2.amazonaws.com/LabTestOrderable/RegisterTest/Image/ad72c9b8c3324c1cb7aa9dbf29e46d64-638905990491115782.png"
+        }
+      },
+      {
+        "gtin": "850024942325",
+        "productName": "Vaginal Health pH Test + Treat",
+        "description": "",
+        "testKitImageURL": "https://safe-content-cache-us-west-2-quality-speed.s3-us-west-2.amazonaws.com/LabTestOrderable/RegisterTest/Image/3cebedbb69cb4455af33da5ab524ec93-639058688331122684.png",
+        "language": "en",
+        "registerTestDetail": {
+          "title": "",
+          "description": "<p></p>",
+          "buttonTitle": "Scan Barcode on the Box",
+          "imageURL": "https://safe-content-cache-us-west-2-quality-speed.s3-us-west-2.amazonaws.com/LabTestOrderable/RegisterTest/Image/1475ae0004084d749ee2dfc9123af952-638905989776168388.png"
+        }
+      }
+    ],
+    "message": "Success",
+    "code": 0
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
 ### createUploadUrl
 
 ```ts
@@ -448,7 +651,24 @@ const upload = await safeCdx.createUploadUrl(
 
 Creates a pre-signed image upload URL.
 
-`imageType` is optional. If not provided, the client uses `defaultImageType` from config, or `jpg` by default.
+`imageType` is optional. If not provided, the client sends `jpg`.
+
+#### API Response example
+
+```json
+{
+  "Data": {
+    "preSignedURL": "https://sf-us-west-2-lower-neural-cdx-img-uploads-quality.s3.us-west-2.amazonaws.com/healthcheck/winx-uti/860002060439_6a104bba6068dd9a213db810-1.jpg?X-Amz-Expires=1200&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=***&X-Amz-Date=20260522T123118Z&X-Amz-SignedHeaders=host&X-Amz-Signature=***",
+    "Metadata": {
+      "UploadId": "860002060439_6a104bba6068dd9a213db810-1",
+      "Type": "Rapid Test Kit Upload",
+      "File": "860002060439_6a104bba6068dd9a213db810-1.jpg"
+    }
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
 
 ### uploadImage
 
@@ -471,7 +691,20 @@ const result = await safeCdx.updateCvmlStatus(
 
 Updates the CVML processing status for a captured image.
 
-This method returns a raw service result.
+The client returns the received response directly without applying `ApiResponse` validation.
+
+#### API Response example
+
+```json
+{
+  "success": true,
+  "data": {
+    "_id": "6a104bba6068dd9a213db810"
+  },
+  "message": "Success",
+  "code": 0
+}
+```
 
 ### getCvmlResults
 
@@ -481,7 +714,51 @@ const result = await safeCdx.getCvmlResults(imageOfCaptureId);
 
 Polls CVML analysis results for a captured image.
 
-This method returns a raw service result.
+The client returns the received response directly without applying `ApiResponse` validation.
+
+#### API Response example
+
+```json
+{
+  "success": true,
+  "data": {
+    "userID": "5d00527a-2a9c-4d68-a7f4-8f154b2ca3e6",
+    "status": "Started",
+    "cvmlStatus": "Retake",
+    "gtin": "860002060439",
+    "isCVMLResult": true,
+    "isSelfReportingPostTest": false,
+    "schemaVersion": 1,
+    "capture": {
+      "retryCount": 0,
+      "retryLimit": 0,
+      "failoverEnabled": true,
+      "lastCvmlStatus": "Retake",
+      "failoverTriggered": false
+    },
+    "questionnaireSnapshot": {
+      "isValid": []
+    },
+    "resumed": false,
+    "imageOfCaptureResult": {
+      "parsed": {
+        "outcome": "Retake",
+        "responseCode": "Err4",
+        "responseMessage": "ml_result_code_error_04_msg",
+        "responseTitle": "ml_result_code_error_04_title"
+      }
+    },
+    "failoverEnabled": true,
+    "failoverTriggered": false,
+    "resumable": false,
+    "showValidity": false,
+    "showError": true,
+    "_id": "6a104bba6068dd9a213db810"
+  },
+  "message": "Success",
+  "code": 0
+}
+```
 
 ### getPendingResults
 
@@ -491,14 +768,104 @@ const pending = await safeCdx.getPendingResults();
 
 Returns pending or incomplete test results.
 
-A custom payload may also be provided:
+When called without an argument, the SDK sends:
+
+```ts
+{
+  Data: {
+    ExcludeStatus: "Invalid,Canceled",
+  },
+}
+```
+
+The same request can be made explicitly:
 
 ```ts
 const pending = await safeCdx.getPendingResults({
-  ExcludeStatus: "Started",
+  ExcludeStatus: "Invalid,Canceled",
 });
 ```
 
+#### API Response example
+
+```json
+{
+  "Data": {
+    "success": true,
+    "data": [
+      {
+        "status": "Started",
+        "cvmlStatus": "Retake",
+        "gtin": "860002060439",
+        "testName": "Winx UTI Test + Treat",
+        "recordedDate": "2026-05-22T12:49:26.047Z",
+        "isCVMLBackground": false,
+        "isCVMLResult": true,
+        "isSelfReportingPostTest": false,
+        "isSelfReportingPreTest": false,
+        "viewed": false,
+        "schemaVersion": 1,
+        "capture": {
+          "retryCount": 0,
+          "retryLimit": 0,
+          "failoverEnabled": true,
+          "lastCvmlStatus": "Retake",
+          "failoverTriggered": false
+        },
+        "questionnaireSnapshot": {
+          "isValid": []
+        },
+        "resumed": false,
+        "failoverEnabled": true,
+        "failoverTriggered": false,
+        "resumable": true,
+        "resumeNext": "SelfReporting",
+        "showValidity": false,
+        "showError": true,
+        "_id": "6a104bba6068dd9a213db810"
+      },
+      {
+        "status": "Started",
+        "gtin": "810172700093",
+        "testName": "Speedy Swab COVID-19 + Flu Self-Test",
+        "recordedDate": "2026-05-22T10:11:10.181Z",
+        "isCVMLBackground": true,
+        "isCVMLResult": false,
+        "isSelfReportingPostTest": true,
+        "isSelfReportingPreTest": false,
+        "viewed": false,
+        "schemaVersion": 1,
+        "capture": {
+          "retryCount": 0,
+          "retryLimit": 0,
+          "failoverEnabled": true,
+          "failoverTriggered": false
+        },
+        "questionnaireSnapshot": {
+          "isValid": [
+            {
+              "display": "post-test",
+              "question": "Do you see a control line (C)?"
+            }
+          ]
+        },
+        "resumed": false,
+        "failoverEnabled": true,
+        "failoverTriggered": false,
+        "resumable": false,
+        "showValidity": false,
+        "showError": true,
+        "_id": "6a102bbe6068dd9a213db80f"
+      }
+    ],
+    "message": "Success",
+    "code": 0
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
 ### getLastResults
 
 ```ts
@@ -507,6 +874,160 @@ const last = await safeCdx.getLastResults();
 
 Returns the most recent test result for the authenticated patient.
 
+When called without an argument, the SDK sends:
+
+```ts
+{
+  Data: {
+    ExcludeStatus: "Invalid",
+  },
+}
+```
+
+#### API Response example
+
+```json
+{
+  "Data": {
+    "success": true,
+    "data": {
+      "cvmlUploadId": "6a104bba6068dd9a213db810",
+      "userID": "5d00527a-2a9c-4d68-a7f4-8f154b2ca3e6",
+      "tenantID": "healthcheck",
+      "isSelfAssessment": false,
+      "status": "Started",
+      "cvmlStatus": "Retake",
+      "gtin": "860002060439",
+      "testInfoHeader": "Winx Health",
+      "testName": "Winx UTI Test + Treat",
+      "imageOfCapture": "860002060439_6a104bba6068dd9a213db810-1.jpg",
+      "imageOfCaptureUploadAt": "2026-05-22T12:31:18.333Z",
+      "imageOfCaptureResults": [
+        {
+          "imageOfCapture": "860002060439_6a104bba6068dd9a213db810-1.jpg",
+          "uploadAt": "2026-05-22T12:31:18.333Z",
+          "cvmlStatus": "Retake",
+          "parsed": {
+            "outcome": "Retake",
+            "responseCode": "Err4",
+            "responseMessage": "ml_result_code_error_04_msg",
+            "responseTitle": "ml_result_code_error_04_title"
+          }
+        }
+      ],
+      "resultPDF": "archive/2026/05/22/12/48/7ecfd730-c4c3-4cd6-8b12-4210b9a2db28.pdf",
+      "result": [
+        {
+          "analyte": "Purchase",
+          "reportedValue": "drug store",
+          "storedValue": "drug store",
+          "score": "0"
+        }
+      ],
+      "recordedDate": "2026-05-22T12:49:26.047Z",
+      "cvmlTestName": "winx-uti",
+      "isCVMLBackground": false,
+      "isCVMLResult": true,
+      "isSelfReportingPostTest": false,
+      "isSelfReportingPreTest": false,
+      "viewed": false,
+      "finalized": false,
+      "schemaVersion": 1,
+      "capture": {
+        "retryCount": 1,
+        "retryLimit": 2,
+        "failoverEnabled": true,
+        "lastCvmlStatus": "Retake",
+        "failoverTriggered": false
+      },
+      "questionnaireSnapshot": {
+        "isValid": [],
+        "analyte": [
+          {
+            "_id": "1",
+            "displayOrder": 1,
+            "display": "CVML",
+            "name": "Leukocyte",
+            "question": "What is the Leukocyte reading?",
+            "image": "WinxLeuk.png",
+            "cvmlOrder": 1,
+            "responses": [
+              {
+                "value": "Negative -",
+                "displayOrder": 1,
+                "storedValue": "Neg",
+                "cvmlValue": "Neg",
+                "score": "0"
+              },
+              {
+                "value": "Trace 15+-",
+                "displayOrder": 2,
+                "storedValue": "15+-",
+                "cvmlValue": "15+-",
+                "score": "3"
+              },
+              {
+                "value": "Positive 70+",
+                "displayOrder": 3,
+                "storedValue": "70+",
+                "cvmlValue": "70+",
+                "score": "4"
+              }
+            ]
+          },
+          {
+            "_id": "2",
+            "displayOrder": 2,
+            "display": "CVML",
+            "name": "Nitrite",
+            "question": "What is the Nitrite reading?",
+            "image": "WinxNitr.png",
+            "cvmlOrder": 2,
+            "responses": [
+              {
+                "value": "Negative",
+                "displayOrder": 1,
+                "storedValue": "Neg",
+                "cvmlValue": "Neg",
+                "score": "0"
+              },
+              {
+                "value": "Positive Low+",
+                "displayOrder": 2,
+                "storedValue": "Low+",
+                "cvmlValue": "Low+",
+                "score": "2"
+              },
+              {
+                "value": "Positive High++",
+                "displayOrder": 3,
+                "storedValue": "High++",
+                "cvmlValue": "High++",
+                "score": "2"
+              }
+            ]
+          }
+        ]
+      },
+      "resumed": false,
+      "language": "en",
+      "labVendor": "Winx Health",
+      "labTestType": "Home Test (Rapid)",
+      "externalId": "test-user@example.com",
+      "positiveAnalytes": [],
+      "_id": "6a104bba6068dd9a213db810",
+      "modifier": "5d00527a-2a9c-4d68-a7f4-8f154b2ca3e6",
+      "created": "2026-05-22T12:27:38.731Z",
+      "modified": "2026-05-22T12:49:26.047Z"
+    },
+    "message": "Success",
+    "code": 0
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
 ### getTestHistory
 
 ```ts
@@ -515,6 +1036,57 @@ const history = await safeCdx.getTestHistory();
 
 Returns the test history for the authenticated patient.
 
+When called without an argument, the SDK sends:
+
+```ts
+{
+  Data: {
+    ExcludeStatus: "Invalid",
+  },
+}
+```
+
+#### API Response example
+
+```json
+{
+  "Data": {
+    "success": true,
+    "data": [
+      {
+        "status": "Started",
+        "cvmlStatus": "Retake",
+        "testInfoHeader": "Winx Health",
+        "testName": "Winx UTI Test + Treat",
+        "recordedDate": "2026-05-22T12:49:26.047Z",
+        "viewed": false,
+        "schemaVersion": 1,
+        "overallResult": "Unknown",
+        "positiveAnalytes": [],
+        "_id": "6a104bba6068dd9a213db810",
+        "created": "2026-05-22T12:27:38.731Z"
+      },
+      {
+        "status": "Started",
+        "testInfoHeader": "Biolabs International",
+        "testName": "Speedy Swab COVID-19 + Flu Self-Test",
+        "recordedDate": "2026-05-22T10:11:10.181Z",
+        "viewed": false,
+        "schemaVersion": 1,
+        "overallResult": "Unknown",
+        "positiveAnalytes": [],
+        "_id": "6a102bbe6068dd9a213db80f",
+        "created": "2026-05-22T10:11:10.181Z"
+      }
+    ],
+    "message": "Success",
+    "code": 0
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
 ### getResultDetails
 
 ```ts
@@ -523,7 +1095,141 @@ const details = await safeCdx.getResultDetails(userTestResultId);
 
 Returns detailed result data for a specific test attempt.
 
-This method returns a raw service result.
+The client returns the received response directly without applying `ApiResponse` validation.
+
+#### API Response example
+
+```json
+{
+  "success": true,
+  "data": {
+    "cvmlUploadId": "6a104bba6068dd9a213db810",
+    "userID": "5d00527a-2a9c-4d68-a7f4-8f154b2ca3e6",
+    "tenantID": "healthcheck",
+    "isSelfAssessment": false,
+    "status": "Started",
+    "cvmlStatus": "Retake",
+    "gtin": "860002060439",
+    "testInfoHeader": "Winx Health",
+    "testName": "Winx UTI Test + Treat",
+    "imageOfCapture": "860002060439_6a104bba6068dd9a213db810-1.jpg",
+    "imageOfCaptureUploadAt": "2026-05-22T12:31:18.333Z",
+    "imageOfCaptureResults": [
+      {
+        "imageOfCapture": "860002060439_6a104bba6068dd9a213db810-1.jpg",
+        "uploadAt": "2026-05-22T12:31:18.333Z",
+        "cvmlStatus": "Retake",
+        "parsed": {
+          "outcome": "Retake",
+          "responseCode": "Err4",
+          "responseMessage": "ml_result_code_error_04_msg",
+          "responseTitle": "ml_result_code_error_04_title"
+        }
+      }
+    ],
+    "result": [],
+    "recordedDate": "2026-05-22T12:27:38.731Z",
+    "cvmlTestName": "winx-uti",
+    "isCVMLBackground": false,
+    "isCVMLResult": true,
+    "isSelfReportingPostTest": false,
+    "isSelfReportingPreTest": false,
+    "viewed": false,
+    "finalized": false,
+    "schemaVersion": 1,
+    "capture": {
+      "retryCount": 1,
+      "retryLimit": 2,
+      "failoverEnabled": true,
+      "lastCvmlStatus": "Retake",
+      "failoverTriggered": false
+    },
+    "questionnaireSnapshot": {
+      "isValid": [],
+      "analyte": [
+        {
+          "_id": "1",
+          "displayOrder": 1,
+          "display": "CVML",
+          "name": "Leukocyte",
+          "question": "What is the Leukocyte reading?",
+          "image": "WinxLeuk.png",
+          "cvmlOrder": 1,
+          "responses": [
+            {
+              "value": "Negative -",
+              "displayOrder": 1,
+              "storedValue": "Neg",
+              "cvmlValue": "Neg",
+              "score": "0"
+            },
+            {
+              "value": "Trace 15+-",
+              "displayOrder": 2,
+              "storedValue": "15+-",
+              "cvmlValue": "15+-",
+              "score": "3"
+            },
+            {
+              "value": "Positive 70+",
+              "displayOrder": 3,
+              "storedValue": "70+",
+              "cvmlValue": "70+",
+              "score": "4"
+            }
+          ]
+        },
+        {
+          "_id": "2",
+          "displayOrder": 2,
+          "display": "CVML",
+          "name": "Nitrite",
+          "question": "What is the Nitrite reading?",
+          "image": "WinxNitr.png",
+          "cvmlOrder": 2,
+          "responses": [
+            {
+              "value": "Negative",
+              "displayOrder": 1,
+              "storedValue": "Neg",
+              "cvmlValue": "Neg",
+              "score": "0"
+            },
+            {
+              "value": "Positive Low+",
+              "displayOrder": 2,
+              "storedValue": "Low+",
+              "cvmlValue": "Low+",
+              "score": "2"
+            },
+            {
+              "value": "Positive High++",
+              "displayOrder": 3,
+              "storedValue": "High++",
+              "cvmlValue": "High++",
+              "score": "2"
+            }
+          ]
+        }
+      ]
+    },
+    "resumed": false,
+    "language": "en",
+    "labVendor": "Winx Health",
+    "labTestType": "Home Test (Rapid)",
+    "statusResultsText": "",
+    "externalId": "test-user@example.com",
+    "overallResult": "Unknown",
+    "positiveAnalytes": [],
+    "_id": "6a104bba6068dd9a213db810",
+    "modifier": "system",
+    "created": "2026-05-22T12:27:38.731Z",
+    "modified": "2026-05-22T12:33:17.308Z"
+  },
+  "message": "Success",
+  "code": 0
+}
+```
 
 ### getResultPdf
 
@@ -533,30 +1239,42 @@ const pdf = await safeCdx.getResultPdf({
 });
 ```
 
-Generates or retrieves the PDF report for a specific test result.
+Requests the PDF result for a specific test result.
 
-### getImageCaptureUrl
+#### API Response example
 
-```ts
-const imageUrl = await safeCdx.getImageCaptureUrl(userTestResultId);
+```json
+{
+  "Data": {
+    "success": true,
+    "data": "https://safe-manual-test-results-us-west-2-quality-speed.s3.us-west-2.amazonaws.com/archive/2026/05/22/12/48/7ecfd730-c4c3-4cd6-8b12-4210b9a2db28.pdf?X-Amz-Expires=900&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=***&X-Amz-Date=20260522T124843Z&X-Amz-SignedHeaders=host&X-Amz-Signature=***",
+    "message": "Success",
+    "code": 0
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
 ```
 
-Returns the image capture URL for a specific test result.
-
-This method returns a raw service result.
-
-### getAnalytics
+### getImageCaptureUrl
 
 ```ts
-const analytics = await safeCdx.getAnalytics();
+const imageUrl = await safeCdx.getImageCaptureUrl(userTestResultId);
 ```
 
-Returns analytics data for test results.
+Requests image capture data for a specific test result.
 
-A custom payload may also be provided:
+The client returns the received response directly without applying `ApiResponse` validation.
 
-```ts
-const analytics = await safeCdx.getAnalytics(payload);
+#### API Response example
+
+```json
+{
+  "success": true,
+  "data": "https://sf-us-west-2-lower-neural-cdx-img-uploads-quality.s3.us-west-2.amazonaws.com/healthcheck/winx-uti/860002060439_6a104bba6068dd9a213db810-1.jpg?X-Amz-Expires=900&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=***&X-Amz-Date=20260522T125017Z&X-Amz-SignedHeaders=host&X-Amz-Signature=***",
+  "message": "Success",
+  "code": 0
+}
 ```
 
 ### resumeFlow
@@ -573,6 +1291,28 @@ The second argument can be used to explicitly set the resumed value:
 const resumed = await safeCdx.resumeFlow(userTestResultId, true);
 ```
 
+#### API Response example
+
+```json
+{
+  "Data": {
+    "success": true,
+    "data": {
+      "cvmlStatus": "Retake",
+      "reportType": "SELF",
+      "resumed": true,
+      "failoverTriggered": false,
+      "showValidity": false,
+      "_id": "6a02f6da6068dd9a213db7cb"
+    },
+    "message": "Success",
+    "code": 0
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
 ### submitAnswers
 
 ```ts
@@ -583,20 +1323,42 @@ Submits analyte answers for a test attempt.
 
 `Result` should contain at least one answer item. The connector does not generate analyte answers automatically.
 
+#### API Response example
+
+```json
+{
+  "Data": {
+    "success": true,
+    "data": {
+      "_id": "6a104bba6068dd9a213db810"
+    },
+    "message": "Success",
+    "code": 0
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
 ### finalizeTest
 
 ```ts
-const result = await safeCdx.finalizeTest(payload);
+const result = await safeCdx.finalizeTest({
+  UserTestResultId: userTestResultId,
+});
 ```
 
-Finalizes a test attempt with CTA, indication, and decision results.
+Finalizes a test by `UserTestResultId`.
 
-The payload should include:
+The SDK sends:
 
-- `UserTestResultId`
-- `ctaResult`
-- `indicationResult`
-- `decisionResult`
+```ts
+{
+  Data: {
+    UserTestResultId: userTestResultId,
+  },
+}
+```
 
 
 ## Notes
@@ -604,7 +1366,7 @@ The payload should include:
 - The connector does not perform login.
 - The connector uses `HCLoginClient` for authenticated request headers.
 - The connector does not use `loginClient.getBaseUrl()` for Safe CDX API routes.
-- Safe CDX routes use the Safe CDX environment host from `SafeCDXConfig`.
+- Safe CDX derives its service base URL from `loginClient.getEnvironment()`.
 - Standard Safe CDX API methods use the shared `HttpClient`.
 - POST payloads are wrapped internally as `{ Data: payload }`.
 - The caller should pass only the inner payload to SDK methods.