@healthcloudai/hc-safe-cdx 0.0.1 → 0.1.1

package/README.md

@@ -1,3 +1,561 @@
-# 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 is designed to work with the shared `HttpClient` from `@healthcloudai/hc-http`, the same way as other Health Cloud connector modules. It does not implement its own transport layer for standard API calls.
+
+Standard Safe CDX API calls are executed through the injected `HttpClient`.
+
+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
+```
+
+## Import
+
+```ts
+import { FetchClient } from "@healthcloudai/hc-http";
+import { SafeCDXClient } from "@healthcloudai/hc-safe-cdx";
+```
+
+## Basic Setup
+
+```ts
+const http = new FetchClient();
+
+const safeCdx = new SafeCDXClient(http, {
+  environment: "dev",
+  defaultLanguage: "en",
+  defaultImageType: "jpg",
+});
+
+safeCdx.setAccessToken(patientAccessToken);
+```
+
+The connector requires a logged-in patient token.
+
+The connector does not perform login. Login should be handled through the patient authentication flow first. After login, the patient token should be passed to Safe CDX by calling `setAccessToken()`.
+
+## How the Client Works
+
+The client follows the same structure as the other Health Cloud connector modules:
+
+```ts
+const http = new FetchClient();
+const safeCdx = new SafeCDXClient(http, config);
+```
+
+The shared `HttpClient` is responsible for executing HTTP requests.
+
+The Safe CDX client is responsible for:
+
+- building Safe CDX URLs
+- resolving the environment host
+- adding the authorization header
+- wrapping POST request payloads into `{ Data: payload }`
+- validating `ApiResponse` results where the backend returns `{ IsOK, Data, ErrorMessage }`
+- exposing one SDK method per API route
+
+The Safe CDX client does not create its own internal `fetch` helpers for standard API routes.
+
+## Environment Configuration
+
+The connector supports the following environments:
+
+```ts
+const safeCdx = new SafeCDXClient(http, {
+  environment: "dev",
+});
+```
+
+Available environments:
+
+```ts
+"dev" | "uat" | "prod"
+```
+
+Environment host mapping is handled internally by the client.
+
+## Authorization
+
+Safe CDX API calls require a Bearer token.
+
+```ts
+safeCdx.setAccessToken(patientAccessToken);
+```
+
+The token may be passed with or without the `Bearer` prefix.
+
+Both examples are valid:
+
+```ts
+safeCdx.setAccessToken("eyJ...");
+```
+
+```ts
+safeCdx.setAccessToken("Bearer eyJ...");
+```
+
+The client normalizes the value internally and sends it as:
+
+```ts
+Authorization: Bearer <token>
+```
+
+If no token is set before calling an API method, the client throws a `SafeCDXError`.
+
+## 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.scan2Ddm({
+  // scan payload
+});
+```
+
+Incorrect:
+
+```ts
+await safeCdx.scan2Ddm({
+  Data: {
+    // scan payload
+  }
+});
+```
+
+The caller should not manually add the `Data` wrapper unless a specific method type explicitly requires it.
+
+## 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`.
+
+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 safeCdx = new SafeCDXClient(http, {
+  environment: "dev",
+  defaultLanguage: "en",
+  defaultImageType: "jpg",
+});
+
+safeCdx.setAccessToken(patientAccessToken);
+```
+
+### 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.
+
+### 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.
+
+### finalizeTest
+
+```ts
+const result = await safeCdx.finalizeTest(payload);
+```
+
+Finalizes a test attempt with CTA, indication, and decision results.
+
+## Error Handling
+
+The connector throws `SafeCDXError` for connector-level errors.
+
+Examples:
+
+- invalid environment
+- missing access token
+- failed `ApiResponse` validation
+- failed image upload
+
+```ts
+try {
+  const profile = await safeCdx.getTestProfileByGTIN("850024942325");
+} catch (error) {
+  if (error instanceof SafeCDXError) {
+    console.error(error.message);
+    console.error(error.response);
+  }
+
+  throw error;
+}
+```
+
+HTTP-level errors from the shared `HttpClient` may also be thrown depending on the `HttpClient` implementation.
+
+For example, `FetchClient` from `@healthcloudai/hc-http` throws an HTTP error when the response status is not successful.
+
+## Notes
+
+- The connector does not perform login.
+- The connector expects a valid patient token to be set before API calls.
+- 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.