@healthcloudai/hc-safe-cdx 0.0.1 → 0.1.2

package/README.md

@@ -1,3 +1,622 @@
-# Healthcheck Safe CDX
+# Healthcheck Safe CDX Connector
 
-Healthcheck Safe CDX connector placeholder.
+Safe CDX connector provides a thin TypeScript wrapper around Safe CDX API routes.
+
+The connector follows the same shared-client pattern used by other Health Cloud connector modules:
+
+- `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.
+
+## Installation
+
+```sh
+npm install @healthcloudai/hc-safe-cdx @healthcloudai/hc-http @healthcloudai/hc-login-connector
+```
+
+## Import
+
+```ts
+import { FetchClient } from "@healthcloudai/hc-http";
+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);
+
+// Configure and authenticate the login client first.
+// Exact login/configuration calls depend on the login connector setup used by the app.
+
+const safeCdx = new HCSafeCDXClient(http, loginClient, {
+  environment: "dev",
+  defaultLanguage: "en",
+  defaultImageType: "jpg",
+});
+```
+
+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.
+
+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:
+
+```ts
+const http = new FetchClient();
+const loginClient = new HCLoginClient(http);
+
+const safeCdx = new HCSafeCDXClient(http, loginClient, {
+  environment: "dev",
+});
+```
+
+The shared `HttpClient` is responsible for executing HTTP requests.
+
+The `HCLoginClient` is responsible for the authenticated request headers.
+
+The Safe CDX client is responsible for:
+
+- 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
+
+The Safe CDX client does not create its own internal `fetch` helpers for standard Safe CDX API routes.
+
+## Environment Configuration
+
+The connector supports the following environments:
+
+```ts
+const safeCdx = new HCSafeCDXClient(http, loginClient, {
+  environment: "dev",
+});
+```
+
+Available environments:
+
+```ts
+"dev" | "uat" | "prod"
+```
+
+Safe CDX environment host mapping is handled internally by the connector:
+
+```txt
+dev  -> dev-api-hcs.healthcloud-services.com
+uat  -> uat-api-hcs.healthcloud-services.com
+prod -> api-hcs.healthcloud-services.com
+```
+
+These hosts are separate from the login connector base URL.
+
+## Authentication
+
+Safe CDX API calls require authenticated Health Cloud headers.
+
+The connector gets those headers from:
+
+```ts
+loginClient.getAuthHeader()
+```
+
+This means the login connector must be configured and authenticated before Safe CDX methods are called.
+
+Example flow:
+
+```ts
+const http = new FetchClient();
+
+const loginClient = new HCLoginClient(http);
+
+// loginClient.configure(...)
+// await loginClient.loginPatient(...)
+
+const safeCdx = new HCSafeCDXClient(http, loginClient, {
+  environment: "dev",
+});
+```
+
+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
+
+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);
+```
+
+When configured, the API key header is added to Safe CDX API calls together with the login auth headers.
+
+## Request Payload Wrapping
+
+For POST requests, only the inner payload should be passed to SDK methods.
+
+The SDK wraps the payload internally as:
+
+```ts
+{
+  Data: payload
+}
+```
+
+Correct:
+
+```ts
+await safeCdx.submitAnswers({
+  UserTestResultId: userTestResultId,
+  Result: [
+    {
+      Analyte: "Purchase",
+      ReportedValue: "drug store",
+      StoredValue: "drug store",
+      Score: "0",
+    },
+  ],
+});
+```
+
+Incorrect:
+
+```ts
+await safeCdx.submitAnswers({
+  Data: {
+    UserTestResultId: userTestResultId,
+    Result: [],
+  },
+});
+```
+
+The caller should not manually add the `Data` wrapper.
+
+## API Response Handling
+
+Most Safe CDX endpoints return the standard backend response envelope:
+
+```ts
+{
+  Data: T;
+  IsOK: boolean;
+  ErrorMessage: string | null;
+}
+```
+
+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.
+
+Some endpoints return a raw service result instead of the standard `ApiResponse` envelope. Those methods return the raw result directly.
+
+Raw result methods include:
+
+```ts
+updateCvmlStatus(...)
+getCvmlResults(...)
+getResultDetails(...)
+getImageCaptureUrl(...)
+```
+
+## Image Upload Handling
+
+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.
+
+```ts
+await safeCdx.uploadImage(preSignedURL, imageBody, "image/jpeg");
+```
+
+This upload does not go through the shared `HttpClient`.
+
+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.
+
+Authorization headers should not be sent to the pre-signed URL. The pre-signed URL already contains temporary upload authorization.
+
+## Typical Safe CDX Flow
+
+A typical flow looks like this:
+
+```ts
+const http = new FetchClient();
+
+const loginClient = new HCLoginClient(http);
+
+// Configure and authenticate loginClient first.
+
+const safeCdx = new HCSafeCDXClient(http, loginClient, {
+  environment: "dev",
+  defaultLanguage: "en",
+  defaultImageType: "jpg",
+});
+```
+
+### 1. Get available test profiles
+
+```ts
+const profiles = await safeCdx.getTestProfilesByAccount();
+```
+
+### 2. Resolve test profile by GTIN
+
+```ts
+const profile = await safeCdx.getTestProfileByGTIN("850024942325");
+
+const userTestResultId = profile.Data.ID;
+const gtin = profile.Data.DiagnosticProfile.TestInfo.gtin;
+```
+
+### 3. Create upload URL
+
+```ts
+const upload = await safeCdx.createUploadUrl(userTestResultId, gtin);
+
+const preSignedURL = upload.Data.preSignedURL;
+const imageOfCaptureId = upload.Data.Metadata.UploadId;
+```
+
+### 4. Upload image
+
+```ts
+await safeCdx.uploadImage(preSignedURL, imageBody, "image/jpeg");
+```
+
+### 5. Update CVML status
+
+```ts
+await safeCdx.updateCvmlStatus(imageOfCaptureId, "ImageProcessing");
+```
+
+### 6. Poll CVML results
+
+```ts
+const cvmlResults = await safeCdx.getCvmlResults(imageOfCaptureId);
+```
+
+### 7. Submit answers
+
+```ts
+await safeCdx.submitAnswers({
+  UserTestResultId: userTestResultId,
+  Result: [
+    {
+      Analyte: "Purchase",
+      ReportedValue: "drug store",
+      StoredValue: "drug store",
+      Score: "0",
+    },
+  ],
+});
+```
+
+### 8. Finalize test
+
+```ts
+await safeCdx.finalizeTest({
+  UserTestResultId: userTestResultId,
+  ctaResult: {
+    id: "2",
+    title: "Connect with a Telehealth Provider for Next Steps",
+    instructions: "Share your test results with a telehealth provider for next steps.",
+    urlText: "Connect with Telehealth",
+    url: "https://example.com/start",
+  },
+  indicationResult: {
+    id: "4",
+    title: "Indication",
+    text: "Results suggest follow-up may be needed.",
+    recommendTitle: "Recommendation",
+    recommendText: "Review the result with a healthcare provider.",
+    ctaId: "2",
+  },
+  decisionResult: {
+    calculation: "Total: analyte.responses.score",
+    results: [
+      {
+        indicationId: "4",
+        value: "4",
+      },
+    ],
+  },
+});
+```
+
+### 9. Retrieve result data
+
+```ts
+const details = await safeCdx.getResultDetails(userTestResultId);
+
+const pdf = await safeCdx.getResultPdf({
+  UserTestResultId: userTestResultId,
+});
+
+const imageCaptureUrl = await safeCdx.getImageCaptureUrl(userTestResultId);
+```
+
+## State Management
+
+The connector does not manage the full Safe CDX flow state.
+
+The application should keep track of values returned between steps, such as:
+
+```ts
+const state = {
+  gtin: undefined,
+  userTestResultId: undefined,
+  preSignedURL: undefined,
+  imageOfCaptureId: undefined,
+};
+```
+
+Important values:
+
+- `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
+
+These values should be stored by the consuming app and passed to the next SDK method when needed.
+
+## Public Methods
+
+### getTestProfileByGTIN
+
+```ts
+const profile = await safeCdx.getTestProfileByGTIN(gtin, language);
+```
+
+Resolves a test profile by GTIN barcode.
+
+`language` is optional. If not provided, the client uses `defaultLanguage` from config when available.
+
+### scan2Ddm
+
+```ts
+const scan = await safeCdx.scan2Ddm(payload);
+```
+
+Scans a 2D data matrix barcode and resolves the related test data.
+
+This method requires a real 2D DataMatrix payload. A plain GTIN should not be used as the DataMatrix payload.
+
+### getTestProfile
+
+```ts
+const profile = await safeCdx.getTestProfile(payload);
+```
+
+Returns the full test profile for a given payload.
+
+### getTestProfilesByAccount
+
+```ts
+const profiles = await safeCdx.getTestProfilesByAccount();
+```
+
+Lists test profiles available to the authenticated account.
+
+A custom payload may also be provided:
+
+```ts
+const profiles = await safeCdx.getTestProfilesByAccount({
+  IncludeRegisterTestDetails: true,
+});
+```
+
+### createUploadUrl
+
+```ts
+const upload = await safeCdx.createUploadUrl(
+  userTestResultId,
+  gtin,
+  "jpg"
+);
+```
+
+Creates a pre-signed image upload URL.
+
+`imageType` is optional. If not provided, the client uses `defaultImageType` from config, or `jpg` by default.
+
+### uploadImage
+
+```ts
+await safeCdx.uploadImage(preSignedURL, imageBody, "image/jpeg");
+```
+
+Uploads the image directly to the pre-signed URL.
+
+This method does not call a Safe CDX API route.
+
+### updateCvmlStatus
+
+```ts
+const result = await safeCdx.updateCvmlStatus(
+  imageOfCaptureId,
+  "ImageProcessing"
+);
+```
+
+Updates the CVML processing status for a captured image.
+
+This method returns a raw service result.
+
+### getCvmlResults
+
+```ts
+const result = await safeCdx.getCvmlResults(imageOfCaptureId);
+```
+
+Polls CVML analysis results for a captured image.
+
+This method returns a raw service result.
+
+### getPendingResults
+
+```ts
+const pending = await safeCdx.getPendingResults();
+```
+
+Returns pending or incomplete test results.
+
+A custom payload may also be provided:
+
+```ts
+const pending = await safeCdx.getPendingResults({
+  ExcludeStatus: "Started",
+});
+```
+
+### getLastResults
+
+```ts
+const last = await safeCdx.getLastResults();
+```
+
+Returns the most recent test result for the authenticated patient.
+
+### getTestHistory
+
+```ts
+const history = await safeCdx.getTestHistory();
+```
+
+Returns the test history for the authenticated patient.
+
+### getResultDetails
+
+```ts
+const details = await safeCdx.getResultDetails(userTestResultId);
+```
+
+Returns detailed result data for a specific test attempt.
+
+This method returns a raw service result.
+
+### getResultPdf
+
+```ts
+const pdf = await safeCdx.getResultPdf({
+  UserTestResultId: userTestResultId,
+});
+```
+
+Generates or retrieves the PDF report for a specific test result.
+
+### getImageCaptureUrl
+
+```ts
+const imageUrl = await safeCdx.getImageCaptureUrl(userTestResultId);
+```
+
+Returns the image capture URL for a specific test result.
+
+This method returns a raw service result.
+
+### getAnalytics
+
+```ts
+const analytics = await safeCdx.getAnalytics();
+```
+
+Returns analytics data for test results.
+
+A custom payload may also be provided:
+
+```ts
+const analytics = await safeCdx.getAnalytics(payload);
+```
+
+### resumeFlow
+
+```ts
+const resumed = await safeCdx.resumeFlow(userTestResultId);
+```
+
+Marks a test attempt as resumed.
+
+The second argument can be used to explicitly set the resumed value:
+
+```ts
+const resumed = await safeCdx.resumeFlow(userTestResultId, true);
+```
+
+### submitAnswers
+
+```ts
+const result = await safeCdx.submitAnswers(payload);
+```
+
+Submits analyte answers for a test attempt.
+
+`Result` should contain at least one answer item. The connector does not generate analyte answers automatically.
+
+### finalizeTest
+
+```ts
+const result = await safeCdx.finalizeTest(payload);
+```
+
+Finalizes a test attempt with CTA, indication, and decision results.
+
+The payload should include:
+
+- `UserTestResultId`
+- `ctaResult`
+- `indicationResult`
+- `decisionResult`
+
+
+## Notes
+
+- The connector does not perform login.
+- The connector uses `HCLoginClient` for authenticated request headers.
+- The connector does not use `loginClient.getBaseUrl()` for Safe CDX API routes.
+- Safe CDX routes use the Safe CDX environment host from `SafeCDXConfig`.
+- 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.