@healthcloudai/hc-safe-cdx 0.2.0 → 0.2.1

package/README.md

@@ -1,17 +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.
-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.
+Image upload is handled separately because the upload target is a pre-signed storage URL rather than a Safe CDX API route.
 
 ## Installation
 
@@ -27,358 +20,323 @@ import { HCLoginClient } from "@healthcloudai/hc-login-connector";
 import { HCSafeCDXClient } from "@healthcloudai/hc-safe-cdx";
 ```
 
-## Basic Setup
-
-```ts
-const http = new FetchClient();
-
-const loginClient = new HCLoginClient(http);
-
-loginClient.configure("healthcheck", "dev");
-await loginClient.login(email, password);
-
-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()`.
-
-There is no `setAccessToken()` step in this version of the client.
-
-## Dependency Notes
-
-Because `HCSafeCDXClient` accepts `HCLoginClient` in the constructor, `@healthcloudai/hc-login-connector` should be included as a package dependency.
-
-Example package configuration:
-
-```json
-{
-  "dependencies": {
-    "@healthcloudai/hc-http": "^0.x.x",
-    "@healthcloudai/hc-login-connector": "^0.x.x"
-  }
-}
-```
-
-In a workspace setup, use the same dependency versioning strategy already used by the other connector packages.
+## Setup
 
-Example:
-
-```json
-{
-  "dependencies": {
-    "@healthcloudai/hc-http": "workspace:*",
-    "@healthcloudai/hc-login-connector": "workspace:*"
-  }
-}
-```
-
-## How the Client Works
-
-The client receives both the HTTP client and the login client:
+Create the shared HTTP client, authenticate the patient through `HCLoginClient`, and then create the Safe CDX client with the authenticated login instance.
 
 ```ts
-const http = new FetchClient();
-const loginClient = new HCLoginClient(http);
+const httpClient = new FetchClient();
+const loginClient = new HCLoginClient(httpClient);
 
 loginClient.configure("healthcheck", "dev");
 await loginClient.login(email, password);
 
-const safeCdx = new HCSafeCDXClient(http, loginClient);
+const safeCdx = new HCSafeCDXClient(httpClient, loginClient);
 ```
 
-The shared `HttpClient` is responsible for executing HTTP requests.
+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.
 
-The `HCLoginClient` is responsible for the authenticated request headers.
+## Client Configuration
 
-The Safe CDX client is responsible for:
+### Service URL
 
-- 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
-- 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
+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.
 
-The Safe CDX client does not create its own internal `fetch` helpers for standard Safe CDX API routes.
 
-## Base URL Configuration
+### Optional API Key
 
-Safe CDX base URL configuration follows the same constructor pattern as the Health Record connector:
+When an environment requires an API key header, configure it on the Safe CDX client:
 
 ```ts
-loginClient.configure("healthcheck", "dev");
-
-const safeCdx = new HCSafeCDXClient(http, loginClient);
-```
-
-The Safe CDX client reads the environment from:
-
-```ts
-loginClient.getEnvironment()
-```
-
-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  -> 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
+safeCdx.setApiKey("x-api-key", apiKeyValue);
 ```
 
-These base URLs are separate from the login connector base URL.
+The configured API key header is added to Safe CDX API route requests together with the patient authentication headers.
 
-## Authentication
+## Request Contract
 
-Safe CDX API calls require authenticated Health Cloud headers.
+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.
 
-The connector gets those headers from:
+For POST requests, `HCSafeCDXClient` constructs the API request envelope internally:
 
 ```ts
-loginClient.getAuthHeader()
+interface APIRequest<T> {
+    Data: T;
+}
 ```
 
-This means the login connector must be configured and authenticated before Safe CDX methods are called.
-
-Example flow:
+For example:
 
 ```ts
-const http = new FetchClient();
-
-const loginClient = new HCLoginClient(http);
-
-loginClient.configure("healthcheck", "dev");
-await loginClient.login(email, password);
-
-const safeCdx = new HCSafeCDXClient(http, loginClient);
+await safeCdx.submitAnswers({
+    UserTestResultId: userTestResultId,
+    Result: [
+        {
+            Analyte: "Purchase",
+            ReportedValue: "drug store",
+            StoredValue: "drug store",
+            Score: "0"
+        }
+    ]
+});
 ```
 
-Safe CDX does not manually receive a token. It does not expose `setAccessToken()`. Auth is inherited from the configured login client.
-
-## Optional API Key Header
+The client sends:
 
-If an API key header is required by the environment, it can be set on the Safe CDX client:
-
-```ts
-safeCdx.setApiKey("x-api-key", apiKeyValue);
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>",
+        "Result": [
+            {
+                "Analyte": "Purchase",
+                "ReportedValue": "drug store",
+                "StoredValue": "drug store",
+                "Score": "0"
+            }
+        ]
+    }
+}
 ```
 
-When configured, the API key header is added to Safe CDX API calls together with the login auth headers.
-
-## Request Payload Wrapping
+## Response Contract
 
-For POST requests, only the inner payload should be passed to SDK methods.
+Safe CDX methods return the response shape produced by their backend endpoint without unwrapping or transforming it.
 
-The SDK wraps the payload internally as:
+Most documented methods return the standard Health Cloud response envelope:
 
 ```ts
-{
-  Data: payload
+interface APIResponse<T> {
+    Data: T | null;
+    IsOK: boolean;
+    ErrorMessage: string | null;
 }
 ```
 
-Correct:
+Several Safe CDX operations return a service response inside `APIResponse.Data`, or return that service response directly:
 
 ```ts
-await safeCdx.submitAnswers({
-  UserTestResultId: userTestResultId,
-  Result: [
-    {
-      Analyte: "Purchase",
-      ReportedValue: "drug store",
-      StoredValue: "drug store",
-      Score: "0",
-    },
-  ],
-});
+interface SafeAPIResponse<T> {
+    success: boolean;
+    data: T | null;
+    message: string | null;
+    code: number;
+}
 ```
 
-Incorrect:
+The following methods return `SafeAPIResponse<T>` directly, without the outer `APIResponse<T>` wrapper:
 
 ```ts
-await safeCdx.submitAnswers({
-  Data: {
-    UserTestResultId: userTestResultId,
-    Result: [],
-  },
-});
+safeCdx.updateCvmlStatus(...)
+safeCdx.getCvmlResults(...)
+safeCdx.getResultDetails(...)
+safeCdx.getImageCaptureUrl(...)
 ```
 
-The caller should not manually add the `Data` wrapper.
+`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`.
 
-## API Response Handling
+## Parameter Design
 
-Most Safe CDX endpoints return the standard backend response envelope:
+Public methods follow the documented patient workflow request shapes. 
 
 ```ts
-{
-  Data: T;
-  IsOK: boolean;
-  ErrorMessage: string | null;
-}
+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)
 ```
 
-For these endpoints, the client validates `IsOK`.
 
-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.
-
-For the following methods, the client returns the received response directly without applying `ApiResponse` validation:
+## Typical Patient Workflow
 
 ```ts
-updateCvmlStatus(...)
-getCvmlResults(...)
-getResultDetails(...)
-getImageCaptureUrl(...)
-```
-
-## Image Upload Handling
+const profiles = await safeCdx.getTestProfilesByAccount();
 
-Image upload is different from normal Safe CDX API calls.
+const profile = await safeCdx.getTestProfileByGTIN("850024942325");
 
-The method `createUploadUrl(...)` returns a pre-signed S3 URL. That URL is then used to upload the image file directly.
+if (!profile.IsOK || !profile.Data) {
+    throw new Error(profile.ErrorMessage ?? "Unable to resolve the test profile.");
+}
 
-```ts
-await safeCdx.uploadImage(preSignedURL, imageBody, "image/jpeg");
-```
+const userTestResultId = profile.Data.ID;
+const gtin = profile.Data.DiagnosticProfile?.TestInfo.gtin;
 
-This upload does not go through the shared `HttpClient`.
+if (!userTestResultId || !gtin) {
+    throw new Error("The selected test profile does not include the required workflow identifiers.");
+}
 
-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.
+const upload = await safeCdx.createUploadUrl(userTestResultId, gtin);
 
-Authorization headers should not be sent to the pre-signed URL. The pre-signed URL already contains temporary upload authorization.
+if (!upload.IsOK || !upload.Data?.preSignedURL || !upload.Data.Metadata?.UploadId) {
+    throw new Error(upload.ErrorMessage ?? "Unable to prepare image upload.");
+}
 
-## Typical Safe CDX Flow
+const preSignedURL = upload.Data.preSignedURL;
+const imageOfCaptureId = upload.Data.Metadata.UploadId;
 
-A typical flow looks like this:
+await safeCdx.uploadImage(preSignedURL, imageBody, "image/jpeg");
+await safeCdx.updateCvmlStatus(imageOfCaptureId, "ImageProcessing");
 
-```ts
-const http = new FetchClient();
+const cvmlResults = await safeCdx.getCvmlResults(imageOfCaptureId);
 
-const loginClient = new HCLoginClient(http);
+await safeCdx.submitAnswers({
+    UserTestResultId: userTestResultId,
+    Result: [
+        {
+            Analyte: "Purchase",
+            ReportedValue: "drug store",
+            StoredValue: "drug store",
+            Score: "0"
+        }
+    ]
+});
 
-loginClient.configure("healthcheck", "dev");
-await loginClient.login(email, password);
+await safeCdx.finalizeTest(userTestResultId);
 
-const safeCdx = new HCSafeCDXClient(http, loginClient);
+const details = await safeCdx.getResultDetails(userTestResultId);
+const pdf = await safeCdx.getResultPdf(userTestResultId);
+const imageCaptureUrl = await safeCdx.getImageCaptureUrl(userTestResultId);
 ```
 
-### 1. Get available test profiles
+The application is responsible for preserving workflow values returned between steps, including `userTestResultId`, `gtin`, `preSignedURL`, and `imageOfCaptureId`.
 
-```ts
-const profiles = await safeCdx.getTestProfilesByAccount();
-```
-
-### 2. Resolve test profile by GTIN
+## Public Methods
 
-```ts
-const profile = await safeCdx.getTestProfileByGTIN("850024942325");
+### `getTestProfilesByAccount(...)`
 
-const userTestResultId = profile.Data.ID;
-const gtin = profile.Data.DiagnosticProfile.TestInfo.gtin;
-```
+Lists test profiles available to the authenticated patient account. The backend resolves the tenant from the authenticated patient context.
 
-### 3. Create upload URL
+#### Signature
 
 ```ts
-const upload = await safeCdx.createUploadUrl(userTestResultId, gtin);
-
-const preSignedURL = upload.Data.preSignedURL;
-const imageOfCaptureId = upload.Data.Metadata.UploadId;
+safeCdx.getTestProfilesByAccount(
+    includeRegisterTestDetails?: boolean
+): Promise<APIResponse<GetTestProfilesByAccountData>>
 ```
 
-### 4. Upload image
+`GetTestProfilesByAccountData` is:
 
 ```ts
-await safeCdx.uploadImage(preSignedURL, imageBody, "image/jpeg");
+type GetTestProfilesByAccountData =
+    SafeAPIResponse<TestProfileByAccountItem[]>;
 ```
 
-### 5. Update CVML status
+#### Parameters
 
-```ts
-await safeCdx.updateCvmlStatus(imageOfCaptureId, "ImageProcessing");
-```
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `includeRegisterTestDetails` | `boolean` | No | Includes registration-specific test details when `true`. Defaults to `true`. |
 
-### 6. Poll CVML results
+#### Usage
 
 ```ts
-const cvmlResults = await safeCdx.getCvmlResults(imageOfCaptureId);
+const profiles = await safeCdx.getTestProfilesByAccount();
 ```
 
-### 7. Submit answers
-
 ```ts
-await safeCdx.submitAnswers({
-  UserTestResultId: userTestResultId,
-  Result: [
-    {
-      Analyte: "Purchase",
-      ReportedValue: "drug store",
-      StoredValue: "drug store",
-      Score: "0",
-    },
-  ],
-});
+const profiles = await safeCdx.getTestProfilesByAccount(true);
 ```
 
-### 8. Finalize test
+#### API request sent internally
 
-```ts
-await safeCdx.finalizeTest({
-  UserTestResultId: userTestResultId,
-});
+```json
+{
+    "Data": {
+        "IncludeRegisterTestDetails": true
+    }
+}
 ```
 
-### 9. Retrieve result data
+#### API response example
 
-```ts
-const details = await safeCdx.getResultDetails(userTestResultId);
-
-const pdf = await safeCdx.getResultPdf({
-  UserTestResultId: userTestResultId,
-});
-
-const imageCaptureUrl = await safeCdx.getImageCaptureUrl(userTestResultId);
+```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
+}
 ```
 
-## State Management
+---
+
+### `getTestProfileByGTIN(...)`
 
-The connector does not manage the full Safe CDX flow state.
+Resolves the Safe CDX test profile associated with a GTIN barcode.
 
-The application should keep track of values returned between steps, such as:
+#### Signature
 
 ```ts
-const state = {
-  gtin: undefined,
-  userTestResultId: undefined,
-  preSignedURL: undefined,
-  imageOfCaptureId: undefined,
-};
+safeCdx.getTestProfileByGTIN(gtin: string): Promise<APIResponse<GetTestProfileByGTINData>>
 ```
 
-Important values:
+#### Parameters
 
-- `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
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `gtin` | `string` | Yes | GTIN barcode value used to resolve the test profile. |
 
-These values should be stored by the consuming app and passed to the next SDK method when needed.
-
-## Public Methods
-
-### getTestProfileByGTIN
+#### Usage
 
 ```ts
-const profile = await safeCdx.getTestProfileByGTIN(gtin);
+const profile = await safeCdx.getTestProfileByGTIN("850024942325");
 ```
 
-Resolves a test profile by GTIN barcode.
 
-#### API Response example
+#### API response example
 
 ```json
 {
@@ -568,92 +526,55 @@ Resolves a test profile by GTIN barcode.
 }
 ```
 
-### getTestProfilesByAccount
+---
 
-```ts
-const profiles = await safeCdx.getTestProfilesByAccount();
-```
+### `createUploadUrl(...)`
 
-Lists test profiles available to the authenticated account.
+Creates a pre-signed URL for uploading a test image.
 
-A custom payload may also be provided:
+#### Signature
 
 ```ts
-const profiles = await safeCdx.getTestProfilesByAccount({
-  IncludeRegisterTestDetails: true,
-});
+safeCdx.createUploadUrl(
+    userTestResultId: string,
+    gtin: string,
+    imageType?: string
+): Promise<APIResponse<CreateUploadUrlData>>
 ```
 
-#### API Response example
+#### Parameters
 
-```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
-}
-```
+| 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"`. |
 
-### createUploadUrl
+#### Usage
 
 ```ts
 const upload = await safeCdx.createUploadUrl(
-  userTestResultId,
-  gtin,
-  "jpg"
+    userTestResultId,
+    gtin,
+    "jpg"
 );
 ```
 
-Creates a pre-signed image upload URL.
+#### API request sent internally
 
-`imageType` is optional. If not provided, the client sends `jpg`.
+```json
+{
+    "Data": {
+        "Gtin": "<GTIN>",
+        "UserTestResultId": "<USER_TEST_RESULT_ID>",
+        "Metadata": {
+            "ImageType": "jpg"
+        }
+    }
+}
+```
 
-#### API Response example
+#### API response example
 
 ```json
 {
@@ -670,30 +591,92 @@ Creates a pre-signed image upload URL.
 }
 ```
 
-### uploadImage
+---
+
+### `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
 
 ```ts
-await safeCdx.uploadImage(preSignedURL, imageBody, "image/jpeg");
+safeCdx.uploadImage(
+    preSignedURL: string,
+    image: BodyInit,
+    contentType?: string
+): Promise<void>
 ```
 
-Uploads the image directly to the pre-signed URL.
+#### Parameters
 
-This method does not call a Safe CDX API route.
+| 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"`. |
 
-### updateCvmlStatus
+#### Usage
 
 ```ts
-const result = await safeCdx.updateCvmlStatus(
-  imageOfCaptureId,
-  "ImageProcessing"
+await safeCdx.uploadImage(
+    preSignedURL,
+    imageBody,
+    "image/jpeg"
 );
 ```
 
-Updates the CVML processing status for a captured image.
+A failed direct upload throws `SafeCDXError`.
+
+---
 
-The client returns the received response directly without applying `ApiResponse` validation.
+### `updateCvmlStatus(...)`
 
-#### API Response example
+Updates the CVML processing status for a captured image. This endpoint returns `SafeAPIResponse<T>` directly.
+
+#### Signature
+
+```ts
+safeCdx.updateCvmlStatus(
+    imageOfCaptureId: string,
+    cvmlStatus: string
+): Promise<UpdateCvmlStatusResponse>
+```
+
+`UpdateCvmlStatusResponse` is:
+
+```ts
+type UpdateCvmlStatusResponse =
+    SafeAPIResponse<EntityReferenceData>;
+```
+
+#### Parameters
+
+| 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"`. |
+
+#### Usage
+
+```ts
+const response = await safeCdx.updateCvmlStatus(
+    imageOfCaptureId,
+    "ImageProcessing"
+);
+```
+
+#### API request sent internally
+
+```json
+{
+    "Data": {
+        "ImageOfCaptureId": "<IMAGE_OF_CAPTURE_ID>",
+        "CvmlStatus": "ImageProcessing"
+    }
+}
+```
+
+#### API response example
 
 ```json
 {
@@ -706,17 +689,40 @@ The client returns the received response directly without applying `ApiResponse`
 }
 ```
 
-### getCvmlResults
+---
+
+### `getCvmlResults(...)`
+
+Polls CVML results for a captured image. This endpoint returns `SafeAPIResponse<T>` directly.
+
+#### Signature
+
+```ts
+safeCdx.getCvmlResults(
+    imageOfCaptureId: string
+): Promise<GetCvmlResultsResponse>
+```
+
+`GetCvmlResultsResponse` is:
 
 ```ts
-const result = await safeCdx.getCvmlResults(imageOfCaptureId);
+type GetCvmlResultsResponse =
+    SafeAPIResponse<CvmlResultsData>;
 ```
 
-Polls CVML analysis results for a captured image.
+#### Parameters
 
-The client returns the received response directly without applying `ApiResponse` validation.
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `imageOfCaptureId` | `string` | Yes | Identifier of the captured image being processed. |
 
-#### API Response example
+#### Usage
+
+```ts
+const response = await safeCdx.getCvmlResults(imageOfCaptureId);
+```
+
+#### API response example
 
 ```json
 {
@@ -760,33 +766,56 @@ The client returns the received response directly without applying `ApiResponse`
 }
 ```
 
-### getPendingResults
+---
+
+### `getPendingResults(...)`
+
+Returns pending or incomplete test results for the authenticated patient.
+
+#### Signature
 
 ```ts
-const pending = await safeCdx.getPendingResults();
+safeCdx.getPendingResults(
+    excludeStatus?: string
+): Promise<APIResponse<GetPendingResultsData>>
 ```
 
-Returns pending or incomplete test results.
-
-When called without an argument, the SDK sends:
+`GetPendingResultsData` is:
 
 ```ts
-{
-  Data: {
-    ExcludeStatus: "Invalid,Canceled",
-  },
-}
+type GetPendingResultsData =
+    SafeAPIResponse<TestResultSummary[]>;
 ```
 
-The same request can be made explicitly:
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `excludeStatus` | `string` | No | Comma-separated statuses excluded from the returned results. Defaults to `"Invalid,Canceled"`. |
+
+#### Usage
 
 ```ts
-const pending = await safeCdx.getPendingResults({
-  ExcludeStatus: "Invalid,Canceled",
-});
+const pending = await safeCdx.getPendingResults();
 ```
 
-#### API Response example
+```ts
+const pending = await safeCdx.getPendingResults(
+    "Invalid,Canceled"
+);
+```
+
+#### API request sent internally
+
+```json
+{
+    "Data": {
+        "ExcludeStatus": "Invalid,Canceled"
+    }
+}
+```
+
+#### API response example
 
 ```json
 {
@@ -866,25 +895,54 @@ const pending = await safeCdx.getPendingResults({
 }
 ```
 
-### getLastResults
+---
+
+### `getLastResults(...)`
+
+Returns the most recent test result for the authenticated patient.
+
+#### Signature
+
+```ts
+safeCdx.getLastResults(
+    excludeStatus?: string
+): Promise<APIResponse<GetLastResultsData>>
+```
+
+`GetLastResultsData` is:
 
 ```ts
-const last = await safeCdx.getLastResults();
+type GetLastResultsData =
+    SafeAPIResponse<TestResultDetails>;
 ```
 
-Returns the most recent test result for the authenticated patient.
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `excludeStatus` | `string` | No | Status excluded from the returned result. Defaults to `"Invalid"`. |
 
-When called without an argument, the SDK sends:
+#### Usage
 
 ```ts
+const lastResult = await safeCdx.getLastResults();
+```
+
+```ts
+const lastResult = await safeCdx.getLastResults("Invalid");
+```
+
+#### API request sent internally
+
+```json
 {
-  Data: {
-    ExcludeStatus: "Invalid",
-  },
+    "Data": {
+        "ExcludeStatus": "Invalid"
+    }
 }
 ```
 
-#### API Response example
+#### API response example
 
 ```json
 {
@@ -1028,25 +1086,54 @@ When called without an argument, the SDK sends:
 }
 ```
 
-### getTestHistory
+---
+
+### `getTestHistory(...)`
+
+Returns test result history for the authenticated patient.
+
+#### Signature
 
 ```ts
-const history = await safeCdx.getTestHistory();
+safeCdx.getTestHistory(
+    excludeStatus?: string
+): Promise<APIResponse<GetTestHistoryData>>
+```
+
+`GetTestHistoryData` is:
+
+```ts
+type GetTestHistoryData =
+    SafeAPIResponse<TestResultSummary[]>;
 ```
 
-Returns the test history for the authenticated patient.
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `excludeStatus` | `string` | No | Status excluded from the returned history. Defaults to `"Invalid"`. |
 
-When called without an argument, the SDK sends:
+#### Usage
 
 ```ts
+const history = await safeCdx.getTestHistory();
+```
+
+```ts
+const history = await safeCdx.getTestHistory("Invalid");
+```
+
+#### API request sent internally
+
+```json
 {
-  Data: {
-    ExcludeStatus: "Invalid",
-  },
+    "Data": {
+        "ExcludeStatus": "Invalid"
+    }
 }
 ```
 
-#### API Response example
+#### API response example
 
 ```json
 {
@@ -1087,17 +1174,50 @@ When called without an argument, the SDK sends:
 }
 ```
 
-### getResultDetails
+---
+
+### `getResultDetails(...)`
+
+Returns detailed data for a specific test attempt. This endpoint returns `SafeAPIResponse<T>` directly.
+
+#### Signature
+
+```ts
+safeCdx.getResultDetails(
+    userTestResultId: string
+): Promise<GetResultDetailsResponse>
+```
+
+`GetResultDetailsResponse` is:
+
+```ts
+type GetResultDetailsResponse =
+    SafeAPIResponse<TestResultDetails>;
+```
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `userTestResultId` | `string` | Yes | Identifier of the test attempt. |
+
+#### Usage
 
 ```ts
 const details = await safeCdx.getResultDetails(userTestResultId);
 ```
 
-Returns detailed result data for a specific test attempt.
+#### API request sent internally
 
-The client returns the received response directly without applying `ApiResponse` validation.
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>"
+    }
+}
+```
 
-#### API Response example
+#### API response example
 
 ```json
 {
@@ -1231,17 +1351,47 @@ The client returns the received response directly without applying `ApiResponse`
 }
 ```
 
-### getResultPdf
+---
+
+### `getResultPdf(...)`
+
+Requests the PDF result for a specific test attempt.
+
+#### Signature
 
 ```ts
-const pdf = await safeCdx.getResultPdf({
-  UserTestResultId: userTestResultId,
-});
+safeCdx.getResultPdf(userTestResultId: string): Promise<APIResponse<GetResultPdfData>>
 ```
 
-Requests the PDF result for a specific test result.
+`GetResultPdfData` is:
+
+```ts
+type GetResultPdfData = SafeAPIResponse<string>;
+```
 
-#### API Response example
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `userTestResultId` | `string` | Yes | Identifier of the test attempt. |
+
+#### Usage
+
+```ts
+const pdf = await safeCdx.getResultPdf(userTestResultId);
+```
+
+#### API request sent internally
+
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>"
+    }
+}
+```
+
+#### API response example
 
 ```json
 {
@@ -1256,17 +1406,50 @@ Requests the PDF result for a specific test result.
 }
 ```
 
-### getImageCaptureUrl
+---
+
+### `getImageCaptureUrl(...)`
+
+Requests image capture data for a specific test attempt. This endpoint returns `SafeAPIResponse<T>` directly.
+
+#### Signature
+
+```ts
+safeCdx.getImageCaptureUrl(
+    userTestResultId: string
+): Promise<GetImageCaptureUrlResponse>
+```
+
+`GetImageCaptureUrlResponse` is:
+
+```ts
+type GetImageCaptureUrlResponse =
+    SafeAPIResponse<string>;
+```
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `userTestResultId` | `string` | Yes | Identifier of the test attempt. |
+
+#### Usage
 
 ```ts
 const imageUrl = await safeCdx.getImageCaptureUrl(userTestResultId);
 ```
 
-Requests image capture data for a specific test result.
+#### API request sent internally
 
-The client returns the received response directly without applying `ApiResponse` validation.
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>"
+    }
+}
+```
 
-#### API Response example
+#### API response example
 
 ```json
 {
@@ -1277,21 +1460,60 @@ The client returns the received response directly without applying `ApiResponse`
 }
 ```
 
-### resumeFlow
+---
+
+### `resumeFlow(...)`
+
+Marks a test attempt as resumed or not resumed.
+
+#### Signature
 
 ```ts
-const resumed = await safeCdx.resumeFlow(userTestResultId);
+safeCdx.resumeFlow(
+    userTestResultId: string,
+    resumed?: boolean
+): Promise<APIResponse<ResumeFlowData>>
 ```
 
-Marks a test attempt as resumed.
+`ResumeFlowData` is:
+
+```ts
+type ResumeFlowData =
+    SafeAPIResponse<ResumeFlowResult>;
+```
 
-The second argument can be used to explicitly set the resumed value:
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `userTestResultId` | `string` | Yes | Identifier of the test attempt. |
+| `resumed` | `boolean` | No | Resume state sent to the API. Defaults to `true`. |
+
+#### Usage
 
 ```ts
-const resumed = await safeCdx.resumeFlow(userTestResultId, true);
+const response = await safeCdx.resumeFlow(userTestResultId);
 ```
 
-#### API Response example
+```ts
+const response = await safeCdx.resumeFlow(
+    userTestResultId,
+    true
+);
+```
+
+#### API request sent internally
+
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>",
+        "Resumed": true
+    }
+}
+```
+
+#### API response example
 
 ```json
 {
@@ -1313,17 +1535,69 @@ const resumed = await safeCdx.resumeFlow(userTestResultId, true);
 }
 ```
 
-### submitAnswers
+---
+
+### `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
+safeCdx.submitAnswers(
+    submission: SubmitAnswersRequest
+): Promise<APIResponse<SubmitAnswersData>>
+```
+
+`SubmitAnswersData` is:
+
+```ts
+type SubmitAnswersData =
+    SafeAPIResponse<EntityReferenceData>;
+```
+
+#### 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. |
+
+#### Usage
 
 ```ts
-const result = await safeCdx.submitAnswers(payload);
+const response = await safeCdx.submitAnswers({
+    UserTestResultId: userTestResultId,
+    Result: [
+        {
+            Analyte: "Purchase",
+            ReportedValue: "drug store",
+            StoredValue: "drug store",
+            Score: "0"
+        }
+    ]
+});
 ```
 
-Submits analyte answers for a test attempt.
+#### API request sent internally
 
-`Result` should contain at least one answer item. The connector does not generate analyte answers automatically.
+```json
+{
+    "Data": {
+        "UserTestResultId": "<USER_TEST_RESULT_ID>",
+        "Result": [
+            {
+                "Analyte": "Purchase",
+                "ReportedValue": "drug store",
+                "StoredValue": "drug store",
+                "Score": "0"
+            }
+        ]
+    }
+}
+```
 
-#### API Response example
+#### API response example
 
 ```json
 {
@@ -1340,36 +1614,48 @@ Submits analyte answers for a test attempt.
 }
 ```
 
-### finalizeTest
+---
+
+### `finalizeTest(...)`
+
+Finalizes the test attempt identified by `userTestResultId`.
+
+#### Signature
 
 ```ts
-const result = await safeCdx.finalizeTest({
-  UserTestResultId: userTestResultId,
-});
+safeCdx.finalizeTest(userTestResultId: string): Promise<APIResponse<FinalizeTestData>>
 ```
 
-Finalizes a test by `UserTestResultId`.
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `userTestResultId` | `string` | Yes | Identifier of the test attempt to finalize. |
 
-The SDK sends:
+#### Usage
 
 ```ts
+const response = await safeCdx.finalizeTest(userTestResultId);
+```
+
+#### API request sent internally
+
+```json
 {
-  Data: {
-    UserTestResultId: userTestResultId,
-  },
+    "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 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.
-- 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.