@healthcloudai/hc-safe-cdx 0.1.4 → 0.2.1

package/README.md

@@ -1,16 +1,10 @@
 # Healthcheck Safe CDX Connector
 
-Safe CDX connector provides a thin TypeScript wrapper around Safe CDX API routes.
+Safe CDX supports the diagnostic test workflow performed by an authenticated patient. It provides the SDK methods used to retrieve available test profiles, resolve a selected test by GTIN, prepare and upload test images, process test results, and complete the test flow.
 
-The connector follows the same shared-client pattern used by other Health Cloud connector modules:
+`HCSafeCDXClient` uses the authenticated patient context provided by `HCLoginClient`. The client derives its own Safe CDX service URL from the configured environment, sends authenticated requests to Safe CDX routes, and wraps request payloads internally where the API expects the standard `Data` envelope.
 
-- `HttpClient` handles HTTP transport.
-- `HCLoginClient` provides the authenticated request headers.
-- `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.
-
-Image upload is handled separately because the upload target is a pre-signed S3 URL, not a Safe CDX API route.
+Image upload is handled separately because the upload target is a pre-signed storage URL rather than a Safe CDX API route.
 
 ## Installation
 
@@ -26,588 +20,1642 @@ import { HCLoginClient } from "@healthcloudai/hc-login-connector";
 import { HCSafeCDXClient } from "@healthcloudai/hc-safe-cdx";
 ```
 
-## Basic Setup
+## Setup
 
-```ts
-const http = new FetchClient();
+Create the shared HTTP client, authenticate the patient through `HCLoginClient`, and then create the Safe CDX client with the authenticated login instance.
 
-const loginClient = new HCLoginClient(http);
+```ts
+const httpClient = new FetchClient();
+const loginClient = new HCLoginClient(httpClient);
 
-// 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(httpClient, 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()`.
+The Safe CDX connector does not perform login and does not require a separate `setAccessToken(...)` step. Authenticated headers are read from the existing `HCLoginClient` instance.
 
-There is no `setAccessToken()` step in this version of the client.
+## Client Configuration
 
-## Dependency Notes
+### Service URL
 
-Because `HCSafeCDXClient` accepts `HCLoginClient` in the constructor, `@healthcloudai/hc-login-connector` should be included as a package dependency.
+Safe CDX uses its own service base URL and does not reuse `loginClient.getBaseUrl()`. The client reads the configured environment through `loginClient.getEnvironment()` and resolves the Safe CDX host internally.
 
-Example package configuration:
 
-```json
-{
-  "dependencies": {
-    "@healthcloudai/hc-http": "^0.x.x",
-    "@healthcloudai/hc-login-connector": "^0.x.x"
-  }
+### Optional API Key
+
+When an environment requires an API key header, configure it on the Safe CDX client:
+
+```ts
+safeCdx.setApiKey("x-api-key", apiKeyValue);
+```
+
+The configured API key header is added to Safe CDX API route requests together with the patient authentication headers.
+
+## Request Contract
+
+SDK methods receive only the values needed by the consuming application. The consumer does not manually provide the backend `Data` wrapper, tenant context, patient identity values, or authentication headers.
+
+For POST requests, `HCSafeCDXClient` constructs the API request envelope internally:
+
+```ts
+interface APIRequest<T> {
+    Data: T;
 }
 ```
 
-In a workspace setup, use the same dependency versioning strategy already used by the other connector packages.
+For example:
 
-Example:
+```ts
+await safeCdx.submitAnswers({
+    UserTestResultId: userTestResultId,
+    Result: [
+        {
+            Analyte: "Purchase",
+            ReportedValue: "drug store",
+            StoredValue: "drug store",
+            Score: "0"
+        }
+    ]
+});
+```
+
+The client sends:
 
 ```json
 {
-  "dependencies": {
-    "@healthcloudai/hc-http": "workspace:*",
-    "@healthcloudai/hc-login-connector": "workspace:*"
-  }
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>",
+        "Result": [
+            {
+                "Analyte": "Purchase",
+                "ReportedValue": "drug store",
+                "StoredValue": "drug store",
+                "Score": "0"
+            }
+        ]
+    }
 }
 ```
 
-## How the Client Works
+## Response Contract
 
-The client receives both the HTTP client and the login client:
+Safe CDX methods return the response shape produced by their backend endpoint without unwrapping or transforming it.
 
-```ts
-const http = new FetchClient();
-const loginClient = new HCLoginClient(http);
+Most documented methods return the standard Health Cloud response envelope:
 
-const safeCdx = new HCSafeCDXClient(http, loginClient, {
-  environment: "dev",
-});
+```ts
+interface APIResponse<T> {
+    Data: T | null;
+    IsOK: boolean;
+    ErrorMessage: string | null;
+}
 ```
 
-The shared `HttpClient` is responsible for executing HTTP requests.
+Several Safe CDX operations return a service response inside `APIResponse.Data`, or return that service response directly:
 
-The `HCLoginClient` is responsible for the authenticated request headers.
+```ts
+interface SafeAPIResponse<T> {
+    success: boolean;
+    data: T | null;
+    message: string | null;
+    code: number;
+}
+```
 
-The Safe CDX client is responsible for:
+The following methods return `SafeAPIResponse<T>` directly, without the outer `APIResponse<T>` wrapper:
 
-- resolving the Safe CDX environment host
-- building Safe CDX URLs
-- adding auth headers from `HCLoginClient`
-- adding optional API key headers when configured
-- wrapping POST request payloads into `{ Data: payload }`
-- validating `ApiResponse` results where the backend returns `{ IsOK, Data, ErrorMessage }`
-- exposing one SDK method per Safe CDX route
+```ts
+safeCdx.updateCvmlStatus(...)
+safeCdx.getCvmlResults(...)
+safeCdx.getResultDetails(...)
+safeCdx.getImageCaptureUrl(...)
+```
 
-The Safe CDX client does not create its own internal `fetch` helpers for standard Safe CDX API routes.
+`HCSafeCDXClient` does not replace an API-defined response with a different return value. Local errors may still be thrown before or outside a Safe CDX API response, such as invalid API key configuration or a failed direct image upload. Transport-level handling for unsuccessful HTTP responses is determined by the supplied `HttpClient`.
 
-## Environment Configuration
+## Parameter Design
 
-The connector supports the following environments:
+Public methods follow the documented patient workflow request shapes. 
 
 ```ts
-const safeCdx = new HCSafeCDXClient(http, loginClient, {
-  environment: "dev",
-});
+safeCdx.getTestProfileByGTIN(gtin)
+safeCdx.getTestProfilesByAccount(includeRegisterTestDetails?)
+safeCdx.createUploadUrl(userTestResultId, gtin, imageType?)
+safeCdx.updateCvmlStatus(imageOfCaptureId, cvmlStatus)
+safeCdx.getCvmlResults(imageOfCaptureId)
+safeCdx.getPendingResults(excludeStatus?)
+safeCdx.getLastResults(excludeStatus?)
+safeCdx.getTestHistory(excludeStatus?)
+safeCdx.getResultDetails(userTestResultId)
+safeCdx.getResultPdf(userTestResultId)
+safeCdx.getImageCaptureUrl(userTestResultId)
+safeCdx.resumeFlow(userTestResultId, resumed?)
+safeCdx.finalizeTest(userTestResultId)
 ```
 
-Available environments:
+
+## Typical Patient Workflow
 
 ```ts
-"dev" | "uat" | "prod"
-```
+const profiles = await safeCdx.getTestProfilesByAccount();
+
+const profile = await safeCdx.getTestProfileByGTIN("850024942325");
+
+if (!profile.IsOK || !profile.Data) {
+    throw new Error(profile.ErrorMessage ?? "Unable to resolve the test profile.");
+}
+
+const userTestResultId = profile.Data.ID;
+const gtin = profile.Data.DiagnosticProfile?.TestInfo.gtin;
+
+if (!userTestResultId || !gtin) {
+    throw new Error("The selected test profile does not include the required workflow identifiers.");
+}
 
-Safe CDX environment host mapping is handled internally by the connector:
+const upload = await safeCdx.createUploadUrl(userTestResultId, gtin);
+
+if (!upload.IsOK || !upload.Data?.preSignedURL || !upload.Data.Metadata?.UploadId) {
+    throw new Error(upload.ErrorMessage ?? "Unable to prepare image upload.");
+}
+
+const preSignedURL = upload.Data.preSignedURL;
+const imageOfCaptureId = upload.Data.Metadata.UploadId;
 
-```txt
-dev  -> dev-api-hcs.healthcloud-services.com
-uat  -> uat-api-hcs.healthcloud-services.com
-prod -> api-hcs.healthcloud-services.com
+await safeCdx.uploadImage(preSignedURL, imageBody, "image/jpeg");
+await safeCdx.updateCvmlStatus(imageOfCaptureId, "ImageProcessing");
+
+const cvmlResults = await safeCdx.getCvmlResults(imageOfCaptureId);
+
+await safeCdx.submitAnswers({
+    UserTestResultId: userTestResultId,
+    Result: [
+        {
+            Analyte: "Purchase",
+            ReportedValue: "drug store",
+            StoredValue: "drug store",
+            Score: "0"
+        }
+    ]
+});
+
+await safeCdx.finalizeTest(userTestResultId);
+
+const details = await safeCdx.getResultDetails(userTestResultId);
+const pdf = await safeCdx.getResultPdf(userTestResultId);
+const imageCaptureUrl = await safeCdx.getImageCaptureUrl(userTestResultId);
 ```
 
-These hosts are separate from the login connector base URL.
+The application is responsible for preserving workflow values returned between steps, including `userTestResultId`, `gtin`, `preSignedURL`, and `imageOfCaptureId`.
 
-## Authentication
+## Public Methods
+
+### `getTestProfilesByAccount(...)`
 
-Safe CDX API calls require authenticated Health Cloud headers.
+Lists test profiles available to the authenticated patient account. The backend resolves the tenant from the authenticated patient context.
 
-The connector gets those headers from:
+#### Signature
 
 ```ts
-loginClient.getAuthHeader()
+safeCdx.getTestProfilesByAccount(
+    includeRegisterTestDetails?: boolean
+): Promise<APIResponse<GetTestProfilesByAccountData>>
 ```
 
-This means the login connector must be configured and authenticated before Safe CDX methods are called.
+`GetTestProfilesByAccountData` is:
+
+```ts
+type GetTestProfilesByAccountData =
+    SafeAPIResponse<TestProfileByAccountItem[]>;
+```
 
-Example flow:
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `includeRegisterTestDetails` | `boolean` | No | Includes registration-specific test details when `true`. Defaults to `true`. |
+
+#### Usage
 
 ```ts
-const http = new FetchClient();
+const profiles = await safeCdx.getTestProfilesByAccount();
+```
 
-const loginClient = new HCLoginClient(http);
+```ts
+const profiles = await safeCdx.getTestProfilesByAccount(true);
+```
 
-// loginClient.configure(...)
-// await loginClient.loginPatient(...)
+#### API request sent internally
 
-const safeCdx = new HCSafeCDXClient(http, loginClient, {
-  environment: "dev",
-});
+```json
+{
+    "Data": {
+        "IncludeRegisterTestDetails": true
+    }
+}
+```
+
+#### 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
+}
 ```
 
-Safe CDX does not manually receive a token. It does not expose `setAccessToken()`. Auth is inherited from the configured login client.
+---
+
+### `getTestProfileByGTIN(...)`
 
-## Optional API Key Header
+Resolves the Safe CDX test profile associated with a GTIN barcode.
 
-If an API key header is required by the environment, it can be set on the Safe CDX client:
+#### Signature
 
 ```ts
-safeCdx.setApiKey("x-api-key", apiKeyValue);
+safeCdx.getTestProfileByGTIN(gtin: string): Promise<APIResponse<GetTestProfileByGTINData>>
 ```
 
-When configured, the API key header is added to Safe CDX API calls together with the login auth headers.
+#### Parameters
 
-## Request Payload Wrapping
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `gtin` | `string` | Yes | GTIN barcode value used to resolve the test profile. |
 
-For POST requests, only the inner payload should be passed to SDK methods.
-
-The SDK wraps the payload internally as:
+#### Usage
 
 ```ts
+const profile = await safeCdx.getTestProfileByGTIN("850024942325");
+```
+
+
+#### API response example
+
+```json
 {
-  Data: payload
+  "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
 }
 ```
 
-Correct:
+---
+
+### `createUploadUrl(...)`
+
+Creates a pre-signed URL for uploading a test image.
+
+#### Signature
 
 ```ts
-await safeCdx.submitAnswers({
-  UserTestResultId: userTestResultId,
-  Result: [
-    {
-      Analyte: "Purchase",
-      ReportedValue: "drug store",
-      StoredValue: "drug store",
-      Score: "0",
-    },
-  ],
-});
+safeCdx.createUploadUrl(
+    userTestResultId: string,
+    gtin: string,
+    imageType?: string
+): Promise<APIResponse<CreateUploadUrlData>>
 ```
 
-Incorrect:
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `userTestResultId` | `string` | Yes | Test result identifier reused through the workflow. |
+| `gtin` | `string` | Yes | GTIN associated with the selected test. |
+| `imageType` | `string` | No | Image type used in upload metadata. Defaults to `"jpg"`. |
+
+#### Usage
 
 ```ts
-await safeCdx.submitAnswers({
-  Data: {
-    UserTestResultId: userTestResultId,
-    Result: [],
-  },
-});
+const upload = await safeCdx.createUploadUrl(
+    userTestResultId,
+    gtin,
+    "jpg"
+);
 ```
 
-The caller should not manually add the `Data` wrapper.
+#### API request sent internally
 
-## API Response Handling
+```json
+{
+    "Data": {
+        "Gtin": "<GTIN>",
+        "UserTestResultId": "<USER_TEST_RESULT_ID>",
+        "Metadata": {
+            "ImageType": "jpg"
+        }
+    }
+}
+```
 
-Most Safe CDX endpoints return the standard backend response envelope:
+#### API response example
 
-```ts
+```json
 {
-  Data: T;
-  IsOK: boolean;
-  ErrorMessage: string | null;
+  "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
 }
 ```
 
-For these endpoints, the client validates `IsOK`.
+---
+
+### `uploadImage(...)`
+
+Uploads an image directly to the pre-signed URL returned by `createUploadUrl(...)`. This method does not call a Safe CDX API route and does not send Health Cloud authentication headers.
+
+#### Signature
 
-If `IsOK` is `false`, the client throws `SafeCDXError`.
+```ts
+safeCdx.uploadImage(
+    preSignedURL: string,
+    image: BodyInit,
+    contentType?: string
+): Promise<void>
+```
 
-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.
+#### Parameters
 
-Some endpoints return a raw service result instead of the standard `ApiResponse` envelope. Those methods return the raw result directly.
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `preSignedURL` | `string` | Yes | Temporary storage upload URL returned by `createUploadUrl(...)`. |
+| `image` | `BodyInit` | Yes | Raw image body, such as a `File`, `Blob` or compatible upload body. |
+| `contentType` | `string` | No | MIME type of the uploaded file. Defaults to `"image/jpeg"`. |
 
-Raw result methods include:
+#### Usage
 
 ```ts
-updateCvmlStatus(...)
-getCvmlResults(...)
-getResultDetails(...)
-getImageCaptureUrl(...)
+await safeCdx.uploadImage(
+    preSignedURL,
+    imageBody,
+    "image/jpeg"
+);
 ```
 
-## Image Upload Handling
+A failed direct upload throws `SafeCDXError`.
 
-Image upload is different from normal Safe CDX API calls.
+---
 
-The method `createUploadUrl(...)` returns a pre-signed S3 URL. That URL is then used to upload the image file directly.
+### `updateCvmlStatus(...)`
+
+Updates the CVML processing status for a captured image. This endpoint returns `SafeAPIResponse<T>` directly.
+
+#### Signature
 
 ```ts
-await safeCdx.uploadImage(preSignedURL, imageBody, "image/jpeg");
+safeCdx.updateCvmlStatus(
+    imageOfCaptureId: string,
+    cvmlStatus: string
+): Promise<UpdateCvmlStatusResponse>
 ```
 
-This upload does not go through the shared `HttpClient`.
+`UpdateCvmlStatusResponse` is:
 
-The reason is that the shared `FetchClient.put()` is JSON-oriented and sends request bodies with `JSON.stringify(...)`. Image upload needs to send a raw `BodyInit`, such as a `Blob`, `File`, `ArrayBuffer`, or stream-compatible body.
+```ts
+type UpdateCvmlStatusResponse =
+    SafeAPIResponse<EntityReferenceData>;
+```
 
-Authorization headers should not be sent to the pre-signed URL. The pre-signed URL already contains temporary upload authorization.
+#### Parameters
 
-## Typical Safe CDX Flow
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `imageOfCaptureId` | `string` | Yes | Identifier returned in the image upload metadata. |
+| `cvmlStatus` | `string` | Yes | CVML processing status to apply, such as `"ImageProcessing"`. |
 
-A typical flow looks like this:
+#### Usage
 
 ```ts
-const http = new FetchClient();
+const response = await safeCdx.updateCvmlStatus(
+    imageOfCaptureId,
+    "ImageProcessing"
+);
+```
 
-const loginClient = new HCLoginClient(http);
+#### API request sent internally
 
-// Configure and authenticate loginClient first.
+```json
+{
+    "Data": {
+        "ImageOfCaptureId": "<IMAGE_OF_CAPTURE_ID>",
+        "CvmlStatus": "ImageProcessing"
+    }
+}
+```
 
-const safeCdx = new HCSafeCDXClient(http, loginClient, {
-  environment: "dev",
-  defaultLanguage: "en",
-  defaultImageType: "jpg",
-});
+#### API response example
+
+```json
+{
+  "success": true,
+  "data": {
+    "_id": "6a104bba6068dd9a213db810"
+  },
+  "message": "Success",
+  "code": 0
+}
 ```
 
-### 1. Get available test profiles
+---
+
+### `getCvmlResults(...)`
+
+Polls CVML results for a captured image. This endpoint returns `SafeAPIResponse<T>` directly.
+
+#### Signature
 
 ```ts
-const profiles = await safeCdx.getTestProfilesByAccount();
+safeCdx.getCvmlResults(
+    imageOfCaptureId: string
+): Promise<GetCvmlResultsResponse>
 ```
 
-### 2. Resolve test profile by GTIN
+`GetCvmlResultsResponse` is:
 
 ```ts
-const profile = await safeCdx.getTestProfileByGTIN("850024942325");
-
-const userTestResultId = profile.Data.ID;
-const gtin = profile.Data.DiagnosticProfile.TestInfo.gtin;
+type GetCvmlResultsResponse =
+    SafeAPIResponse<CvmlResultsData>;
 ```
 
-### 3. Create upload URL
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `imageOfCaptureId` | `string` | Yes | Identifier of the captured image being processed. |
+
+#### Usage
 
 ```ts
-const upload = await safeCdx.createUploadUrl(userTestResultId, gtin);
+const response = await safeCdx.getCvmlResults(imageOfCaptureId);
+```
 
-const preSignedURL = upload.Data.preSignedURL;
-const imageOfCaptureId = upload.Data.Metadata.UploadId;
+#### 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
+}
 ```
 
-### 4. Upload image
+---
+
+### `getPendingResults(...)`
+
+Returns pending or incomplete test results for the authenticated patient.
+
+#### Signature
 
 ```ts
-await safeCdx.uploadImage(preSignedURL, imageBody, "image/jpeg");
+safeCdx.getPendingResults(
+    excludeStatus?: string
+): Promise<APIResponse<GetPendingResultsData>>
 ```
 
-### 5. Update CVML status
+`GetPendingResultsData` is:
 
 ```ts
-await safeCdx.updateCvmlStatus(imageOfCaptureId, "ImageProcessing");
+type GetPendingResultsData =
+    SafeAPIResponse<TestResultSummary[]>;
 ```
 
-### 6. Poll CVML results
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `excludeStatus` | `string` | No | Comma-separated statuses excluded from the returned results. Defaults to `"Invalid,Canceled"`. |
+
+#### Usage
 
 ```ts
-const cvmlResults = await safeCdx.getCvmlResults(imageOfCaptureId);
+const pending = await safeCdx.getPendingResults();
 ```
 
-### 7. Submit answers
-
 ```ts
-await safeCdx.submitAnswers({
-  UserTestResultId: userTestResultId,
-  Result: [
-    {
-      Analyte: "Purchase",
-      ReportedValue: "drug store",
-      StoredValue: "drug store",
-      Score: "0",
-    },
-  ],
-});
+const pending = await safeCdx.getPendingResults(
+    "Invalid,Canceled"
+);
 ```
 
-### 8. Finalize test
+#### API request sent internally
 
-```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: [
+```json
+{
+    "Data": {
+        "ExcludeStatus": "Invalid,Canceled"
+    }
+}
+```
+
+#### API response example
+
+```json
+{
+  "Data": {
+    "success": true,
+    "data": [
       {
-        indicationId: "4",
-        value: "4",
+        "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
+}
 ```
 
-### 9. Retrieve result data
+---
+
+### `getLastResults(...)`
+
+Returns the most recent test result for the authenticated patient.
+
+#### Signature
 
 ```ts
-const details = await safeCdx.getResultDetails(userTestResultId);
+safeCdx.getLastResults(
+    excludeStatus?: string
+): Promise<APIResponse<GetLastResultsData>>
+```
 
-const pdf = await safeCdx.getResultPdf({
-  UserTestResultId: userTestResultId,
-});
+`GetLastResultsData` is:
 
-const imageCaptureUrl = await safeCdx.getImageCaptureUrl(userTestResultId);
+```ts
+type GetLastResultsData =
+    SafeAPIResponse<TestResultDetails>;
 ```
 
-## State Management
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `excludeStatus` | `string` | No | Status excluded from the returned result. Defaults to `"Invalid"`. |
 
-The connector does not manage the full Safe CDX flow state.
+#### Usage
 
-The application should keep track of values returned between steps, such as:
+```ts
+const lastResult = await safeCdx.getLastResults();
+```
 
 ```ts
-const state = {
-  gtin: undefined,
-  userTestResultId: undefined,
-  preSignedURL: undefined,
-  imageOfCaptureId: undefined,
-};
+const lastResult = await safeCdx.getLastResults("Invalid");
 ```
 
-Important values:
+#### API request sent internally
 
-- `gtin`: product or test kit identifier
-- `userTestResultId`: test result record ID used across the flow
-- `preSignedURL`: temporary URL used for image upload
-- `imageOfCaptureId`: upload identifier returned after creating the upload URL
+```json
+{
+    "Data": {
+        "ExcludeStatus": "Invalid"
+    }
+}
+```
 
-These values should be stored by the consuming app and passed to the next SDK method when needed.
+#### API response example
 
-## Public Methods
+```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(...)`
 
-### getTestProfileByGTIN
+Returns test result history for the authenticated patient.
+
+#### Signature
 
 ```ts
-const profile = await safeCdx.getTestProfileByGTIN(gtin, language);
+safeCdx.getTestHistory(
+    excludeStatus?: string
+): Promise<APIResponse<GetTestHistoryData>>
 ```
 
-Resolves a test profile by GTIN barcode.
+`GetTestHistoryData` is:
+
+```ts
+type GetTestHistoryData =
+    SafeAPIResponse<TestResultSummary[]>;
+```
 
-`language` is optional. If not provided, the client uses `defaultLanguage` from config when available.
+#### Parameters
 
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `excludeStatus` | `string` | No | Status excluded from the returned history. Defaults to `"Invalid"`. |
 
-### getTestProfile
+#### Usage
 
 ```ts
-const profile = await safeCdx.getTestProfile(payload);
+const history = await safeCdx.getTestHistory();
 ```
 
-Returns the full test profile for a given payload.
+```ts
+const history = await safeCdx.getTestHistory("Invalid");
+```
 
-### getTestProfilesByAccount
+#### API request sent internally
 
-```ts
-const profiles = await safeCdx.getTestProfilesByAccount();
+```json
+{
+    "Data": {
+        "ExcludeStatus": "Invalid"
+    }
+}
 ```
 
-Lists test profiles available to the authenticated account.
+#### API response example
 
-A custom payload may also be provided:
+```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(...)`
+
+Returns detailed data for a specific test attempt. This endpoint returns `SafeAPIResponse<T>` directly.
+
+#### Signature
 
 ```ts
-const profiles = await safeCdx.getTestProfilesByAccount({
-  IncludeRegisterTestDetails: true,
-});
+safeCdx.getResultDetails(
+    userTestResultId: string
+): Promise<GetResultDetailsResponse>
 ```
 
-### createUploadUrl
+`GetResultDetailsResponse` is:
 
 ```ts
-const upload = await safeCdx.createUploadUrl(
-  userTestResultId,
-  gtin,
-  "jpg"
-);
+type GetResultDetailsResponse =
+    SafeAPIResponse<TestResultDetails>;
 ```
 
-Creates a pre-signed image upload URL.
+#### Parameters
 
-`imageType` is optional. If not provided, the client uses `defaultImageType` from config, or `jpg` by default.
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `userTestResultId` | `string` | Yes | Identifier of the test attempt. |
 
-### uploadImage
+#### Usage
 
 ```ts
-await safeCdx.uploadImage(preSignedURL, imageBody, "image/jpeg");
+const details = await safeCdx.getResultDetails(userTestResultId);
 ```
 
-Uploads the image directly to the pre-signed URL.
+#### API request sent internally
 
-This method does not call a Safe CDX API route.
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>"
+    }
+}
+```
 
-### updateCvmlStatus
+#### API response example
 
-```ts
-const result = await safeCdx.updateCvmlStatus(
-  imageOfCaptureId,
-  "ImageProcessing"
-);
+```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
+}
 ```
 
-Updates the CVML processing status for a captured image.
+---
+
+### `getResultPdf(...)`
 
-This method returns a raw service result.
+Requests the PDF result for a specific test attempt.
 
-### getCvmlResults
+#### Signature
 
 ```ts
-const result = await safeCdx.getCvmlResults(imageOfCaptureId);
+safeCdx.getResultPdf(userTestResultId: string): Promise<APIResponse<GetResultPdfData>>
 ```
 
-Polls CVML analysis results for a captured image.
+`GetResultPdfData` is:
 
-This method returns a raw service result.
+```ts
+type GetResultPdfData = SafeAPIResponse<string>;
+```
+
+#### Parameters
 
-### getPendingResults
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `userTestResultId` | `string` | Yes | Identifier of the test attempt. |
+
+#### Usage
 
 ```ts
-const pending = await safeCdx.getPendingResults();
+const pdf = await safeCdx.getResultPdf(userTestResultId);
 ```
 
-Returns pending or incomplete test results.
+#### API request sent internally
+
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>"
+    }
+}
+```
+
+#### API response example
+
+```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
+}
+```
 
-A custom payload may also be provided:
+---
+
+### `getImageCaptureUrl(...)`
+
+Requests image capture data for a specific test attempt. This endpoint returns `SafeAPIResponse<T>` directly.
+
+#### Signature
 
 ```ts
-const pending = await safeCdx.getPendingResults({
-  ExcludeStatus: "Started",
-});
+safeCdx.getImageCaptureUrl(
+    userTestResultId: string
+): Promise<GetImageCaptureUrlResponse>
 ```
 
-### getLastResults
+`GetImageCaptureUrlResponse` is:
 
 ```ts
-const last = await safeCdx.getLastResults();
+type GetImageCaptureUrlResponse =
+    SafeAPIResponse<string>;
 ```
 
-Returns the most recent test result for the authenticated patient.
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `userTestResultId` | `string` | Yes | Identifier of the test attempt. |
 
-### getTestHistory
+#### Usage
 
 ```ts
-const history = await safeCdx.getTestHistory();
+const imageUrl = await safeCdx.getImageCaptureUrl(userTestResultId);
 ```
 
-Returns the test history for the authenticated patient.
+#### API request sent internally
+
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>"
+    }
+}
+```
 
-### getResultDetails
+#### API response example
 
-```ts
-const details = await safeCdx.getResultDetails(userTestResultId);
+```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
+}
 ```
 
-Returns detailed result data for a specific test attempt.
+---
+
+### `resumeFlow(...)`
 
-This method returns a raw service result.
+Marks a test attempt as resumed or not resumed.
 
-### getResultPdf
+#### Signature
 
 ```ts
-const pdf = await safeCdx.getResultPdf({
-  UserTestResultId: userTestResultId,
-});
+safeCdx.resumeFlow(
+    userTestResultId: string,
+    resumed?: boolean
+): Promise<APIResponse<ResumeFlowData>>
 ```
 
-Generates or retrieves the PDF report for a specific test result.
-
-### getImageCaptureUrl
+`ResumeFlowData` is:
 
 ```ts
-const imageUrl = await safeCdx.getImageCaptureUrl(userTestResultId);
+type ResumeFlowData =
+    SafeAPIResponse<ResumeFlowResult>;
 ```
 
-Returns the image capture URL for a specific test result.
+#### Parameters
 
-This method returns a raw service result.
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `userTestResultId` | `string` | Yes | Identifier of the test attempt. |
+| `resumed` | `boolean` | No | Resume state sent to the API. Defaults to `true`. |
 
-### getAnalytics
+#### Usage
 
 ```ts
-const analytics = await safeCdx.getAnalytics();
+const response = await safeCdx.resumeFlow(userTestResultId);
 ```
 
-Returns analytics data for test results.
+```ts
+const response = await safeCdx.resumeFlow(
+    userTestResultId,
+    true
+);
+```
+
+#### API request sent internally
+
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>",
+        "Resumed": true
+    }
+}
+```
 
-A custom payload may also be provided:
+#### 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(...)`
+
+Submits analyte answers for a test attempt. This method accepts a structured object because the request contains a collection of answer entries.
+
+#### Signature
 
 ```ts
-const analytics = await safeCdx.getAnalytics(payload);
+safeCdx.submitAnswers(
+    submission: SubmitAnswersRequest
+): Promise<APIResponse<SubmitAnswersData>>
 ```
 
-### resumeFlow
+`SubmitAnswersData` is:
 
 ```ts
-const resumed = await safeCdx.resumeFlow(userTestResultId);
+type SubmitAnswersData =
+    SafeAPIResponse<EntityReferenceData>;
 ```
 
-Marks a test attempt as resumed.
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `submission.UserTestResultId` | `string` | Yes | Identifier of the test attempt. |
+| `submission.Result` | `AnswerResult[]` | Yes | Answer entries submitted for the test attempt. |
 
-The second argument can be used to explicitly set the resumed value:
+#### Usage
 
 ```ts
-const resumed = await safeCdx.resumeFlow(userTestResultId, true);
+const response = await safeCdx.submitAnswers({
+    UserTestResultId: userTestResultId,
+    Result: [
+        {
+            Analyte: "Purchase",
+            ReportedValue: "drug store",
+            StoredValue: "drug store",
+            Score: "0"
+        }
+    ]
+});
 ```
 
-### submitAnswers
+#### API request sent internally
 
-```ts
-const result = await safeCdx.submitAnswers(payload);
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>",
+        "Result": [
+            {
+                "Analyte": "Purchase",
+                "ReportedValue": "drug store",
+                "StoredValue": "drug store",
+                "Score": "0"
+            }
+        ]
+    }
+}
+```
+
+#### API response example
+
+```json
+{
+  "Data": {
+    "success": true,
+    "data": {
+      "_id": "6a104bba6068dd9a213db810"
+    },
+    "message": "Success",
+    "code": 0
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
 ```
 
-Submits analyte answers for a test attempt.
+---
+
+### `finalizeTest(...)`
 
-`Result` should contain at least one answer item. The connector does not generate analyte answers automatically.
+Finalizes the test attempt identified by `userTestResultId`.
 
-### finalizeTest
+#### Signature
 
 ```ts
-const result = await safeCdx.finalizeTest(payload);
+safeCdx.finalizeTest(userTestResultId: string): Promise<APIResponse<FinalizeTestData>>
 ```
 
-Finalizes a test attempt with CTA, indication, and decision results.
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `userTestResultId` | `string` | Yes | Identifier of the test attempt to finalize. |
 
-The payload should include:
+#### Usage
+
+```ts
+const response = await safeCdx.finalizeTest(userTestResultId);
+```
 
-- `UserTestResultId`
-- `ctaResult`
-- `indicationResult`
-- `decisionResult`
+#### API request sent internally
+
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>"
+    }
+}
+```
 
 
 ## Notes
 
-- The connector does not perform login.
-- The connector uses `HCLoginClient` for authenticated request headers.
+- `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.
-- Safe CDX routes use the Safe CDX environment host from `SafeCDXConfig`.
-- 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.
-- Image upload uses the pre-signed URL directly and sends the raw file body.
-- Authorization headers should not be sent to the pre-signed upload URL.
-- Pre-signed URLs are time-bound and should not be logged in production.
+- 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`.
+- Direct image upload uses the pre-signed URL and sends the raw file body without Health Cloud authorization headers.