@healthcloudai/hc-settings-connector 0.2.1 → 0.2.3

package/README.md

@@ -13,7 +13,8 @@ This connector gives authenticated patients access to account information and do
 3. Submit uploaded identification and insurance images for capture.
 4. Submit and retrieve insurance information.
 5. Update the patient profile image.
-6. Deactivate the authenticated patient account.
+6. Capture registration documents before the patient is authenticated.
+7. Deactivate the authenticated patient account.
 
 ---
 
@@ -59,7 +60,7 @@ const settingsClient = new HCSettingsClient(
 );
 ```
 
-`HCLoginClient` must be configured and authenticated before calling Settings methods.
+`HCLoginClient` must be configured before creating the Settings client. Most Settings methods require an authenticated patient session. `getRegistrationDocumentCannedUrl(...)` and `captureRegistrationDocument(...)` are intended for unauthenticated registration flows and do not send the auth token.
 
 ---
 
@@ -677,6 +678,161 @@ console.log(response);
 
 ---
 
+# Registration Document Capture
+
+Registration document capture is used during registration, before the user is authenticated. It sends the same capture request shape as patient capture, but it does not attach the patient authorization token.
+
+The full unauthenticated registration document flow is:
+
+1. `getRegistrationDocumentCannedUrl(documentType, extension)` — get a presigned upload URL and a `fileKey` (`FileName`), without an auth token.
+2. Upload the file directly to the returned `ImageURL` (`PUT`, with the **`x-amz-acl: public-read`** header — see warning below).
+3. `captureRegistrationDocument(fileKey, type)` — submit the uploaded file's `fileKey` for OCR capture, also without an auth token.
+
+## Get Registration Document Canned URL
+
+Public signature:
+
+```ts
+settingsClient.getRegistrationDocumentCannedUrl(
+  documentType,
+  extension
+)
+```
+
+`documentType` must be one of:
+
+```ts
+"identification" | "healthinsurance"
+```
+
+Returns a presigned upload URL (`ImageURL`) and a storage `FileName` (used as the `fileKey` for `captureRegistrationDocument`), without sending the patient auth token. Only `loginClient.configure(...)` is required.
+
+```ts
+const response =
+  await settingsClient.getRegistrationDocumentCannedUrl(
+    "identification",
+    "png"
+  );
+
+console.log(response.Data?.ImageURL, response.Data?.FileName);
+```
+
+> ⚠️ **You MUST send the `x-amz-acl: public-read` header on the upload PUT request.** The presigned `ImageURL` is signed *with* an `x-amz-acl: public-read` header included in the signature. If your upload request to that URL omits this exact header, S3 recalculates a different signature and rejects the upload with:
+>
+> ```xml
+> <Error>
+>   <Code>SignatureDoesNotMatch</Code>
+>   <Message>The request signature we calculated does not match the signature you provided. Check your key and signing method.</Message>
+>   ...
+> </Error>
+> ```
+>
+> Example upload (must include the header):
+>
+> ```ts
+> await fetch(response.Data!.ImageURL!, {
+>   method: "PUT",
+>   headers: {
+>     "Content-Type": "image/png",
+>     "x-amz-acl": "public-read",
+>   },
+>   body: fileBytes,
+> });
+> ```
+
+### API request
+
+```json
+{
+  "Data": {
+    "Extension": "png"
+  }
+}
+```
+
+### API response
+
+```json
+{
+  "Data": {
+    "ImageURL": "https://storage.example.com/idcard_example.png?X-Amz-Expires=300&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=example&X-Amz-Date=example&X-Amz-SignedHeaders=host%3Bx-amz-acl&X-Amz-Signature=example",
+    "FileName": "idcard_example.png",
+    "Extension": "png"
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
+
+
+## Capture Registration Document
+
+Public signature:
+
+```ts
+settingsClient.captureRegistrationDocument(
+  fileKey,
+  type
+)
+```
+
+`type` must be one of:
+
+```ts
+"identification" | "healthinsurance"
+```
+
+Only `loginClient.configure(...)` is required for this method so the connector can resolve the API base URL.
+
+```ts
+const response =
+  await settingsClient.captureRegistrationDocument(
+    "idcard_example.jpeg",
+    "identification"
+  );
+
+console.log(response);
+```
+
+### API request
+
+```json
+{
+  "Data": {
+    "Type": "identification",
+    "FileID": "idcard_example.jpeg"
+  }
+}
+```
+
+### API response
+
+```json
+{
+  "Data": {
+    "CapturedData": {
+      "FirstName": "John",
+      "LastName": "Doe",
+      "StreetAddress": "123 Main St",
+      "City": "Springfield",
+      "ZipCode": "90210",
+      "State": "California",
+      "IssuedDate": "01/01/2024",
+      "ExpiresDate": "01/01/2028",
+      "Dob": "01/01/1990",
+      "IDNumber": null
+    },
+    "IsCaptured": true,
+    "InsurancePackages": null
+  },
+  "ErrorMessage": null,
+  "IsOK": true
+}
+```
+
+---
+
 # Account
 
 ## Deactivate User
@@ -726,6 +882,8 @@ console.log(response);
 * `captureDrivingLicense(...)` internally sends `Type: "identification"`.
 * `captureInsurance(...)` internally sends `Type: "healthinsurance"`.
 * `captureUserPhoto(...)` internally sends `Type: "userphoto"`.
+* `getRegistrationDocumentCannedUrl(...)` and `captureRegistrationDocument(...)` do not send the patient auth token.
+* The `ImageURL` returned by `getRegistrationDocumentCannedUrl(...)` is signed with `x-amz-acl: public-read` — your upload PUT request **must** include that exact header or S3 rejects it with `SignatureDoesNotMatch`. See [Get Registration Document Canned URL](#get-registration-document-canned-url).
 
 ```
 ```
@@ -735,7 +893,7 @@ console.log(response);
 
 ## Prerequisites
 
-`HCLoginClient` must be configured and the patient must be logged in before calling any method on this connector.
+`HCLoginClient` must be configured before using this connector. Most methods require the patient to be logged in. `getRegistrationDocumentCannedUrl(...)` and `captureRegistrationDocument(...)` are the unauthenticated exceptions — they do not send the auth token.
 
 ```ts
 import { HCLoginClient } from "@healthcloudai/hc-login-connector";

package/dist/index.cjs

@@ -240,6 +240,54 @@ var HCSettingsClient = class extends import_hc_http.HCBaseConnector {
     );
   }
   // ===========================================================================
+  // Registration document capture
+  // ===========================================================================
+  /**
+   * Returns a canned URL for uploading a registration document image
+   * (driving licence or insurance card) before the user is authenticated.
+   * Does not send the patient auth token.
+   *
+   * The returned `ImageURL` is signed with an `x-amz-acl: public-read`
+   * header — the upload PUT request to that URL must include the exact
+   * same header (`x-amz-acl: public-read`) or S3 will reject it with
+   * `SignatureDoesNotMatch`.
+   */
+  async getRegistrationDocumentCannedUrl(documentType, extension) {
+    const resolvedDocumentType = this.requireValue(documentType, "Document type", "documentType");
+    const resolvedExtension = this.requireValue(extension, "Extension", "extension");
+    const requestPayload = {
+      Data: { Extension: resolvedExtension }
+    };
+    return this.execute(
+      "getRegistrationDocumentCannedUrl",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/registration/document/cannedurl/${resolvedDocumentType}`,
+        requestPayload,
+        this.getHeaders()
+      )
+    );
+  }
+  /**
+   * Submits an uploaded registration document for capture without sending
+   * an authenticated patient token.
+   * fileKey is the storage key of the uploaded image.
+   */
+  async captureRegistrationDocument(fileKey, type) {
+    const resolvedFileKey = this.requireValue(fileKey, "File key", "fileKey");
+    const resolvedType = this.requireValue(type, "Capture type", "type");
+    const requestPayload = {
+      Data: { Type: resolvedType, FileID: resolvedFileKey }
+    };
+    return this.execute(
+      "captureRegistrationDocument",
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/registrationdocument/capture`,
+        requestPayload,
+        this.getHeaders()
+      )
+    );
+  }
+  // ===========================================================================
   // Account
   // ===========================================================================
   /**

package/dist/index.d.cts

@@ -51,7 +51,7 @@ interface PatientDashboard {
     EHR: string | null;
     PendingActions: string[];
 }
-type CaptureType = "healthinsurance" | "identification" | "userphoto";
+type CaptureType = "healthinsurance" | "identification";
 interface InsuranceCaptureData {
     FirstName: string | null;
     LastName: string | null;
@@ -83,6 +83,7 @@ interface CaptureResult<T> {
     IsCaptured: boolean;
     InsurancePackages: object[] | null;
 }
+type RegistrationDocumentCaptureResult = CaptureResult<InsuranceCaptureData | IdentificationCaptureData>;
 interface InsuranceRecord {
     LastUpdatedBy: string | null;
     IrcName: string | null;
@@ -164,6 +165,23 @@ declare class HCSettingsClient extends HCBaseConnector {
      * fileKey is the storage key of the uploaded image.
      */
     captureUserPhoto(fileKey: string): Promise<APIResponse<CaptureResult<UserPhotoCaptureData>>>;
+    /**
+     * Returns a canned URL for uploading a registration document image
+     * (driving licence or insurance card) before the user is authenticated.
+     * Does not send the patient auth token.
+     *
+     * The returned `ImageURL` is signed with an `x-amz-acl: public-read`
+     * header — the upload PUT request to that URL must include the exact
+     * same header (`x-amz-acl: public-read`) or S3 will reject it with
+     * `SignatureDoesNotMatch`.
+     */
+    getRegistrationDocumentCannedUrl(documentType: CaptureType, extension: string): Promise<APIResponse<UserImage>>;
+    /**
+     * Submits an uploaded registration document for capture without sending
+     * an authenticated patient token.
+     * fileKey is the storage key of the uploaded image.
+     */
+    captureRegistrationDocument(fileKey: string, type: CaptureType): Promise<APIResponse<RegistrationDocumentCaptureResult>>;
     /**
      * Soft-deactivates the current patient account.
      * The patient record is not permanently deleted.
@@ -172,4 +190,4 @@ declare class HCSettingsClient extends HCBaseConnector {
     private getAuthHeaders;
 }
 
-export { type CaptureResult, type CaptureType, type CoverageData, type Encounter, HCSettingsClient, type IdentificationCaptureData, type InsuranceCaptureData, type InsuranceRecord, type PatientDashboard, type PatientRecord, type UserImage, type UserPhotoCaptureData, UserStatus };
+export { type CaptureResult, type CaptureType, type CoverageData, type Encounter, HCSettingsClient, type IdentificationCaptureData, type InsuranceCaptureData, type InsuranceRecord, type PatientDashboard, type PatientRecord, type RegistrationDocumentCaptureResult, type UserImage, type UserPhotoCaptureData, UserStatus };

package/dist/index.d.ts

@@ -51,7 +51,7 @@ interface PatientDashboard {
     EHR: string | null;
     PendingActions: string[];
 }
-type CaptureType = "healthinsurance" | "identification" | "userphoto";
+type CaptureType = "healthinsurance" | "identification";
 interface InsuranceCaptureData {
     FirstName: string | null;
     LastName: string | null;
@@ -83,6 +83,7 @@ interface CaptureResult<T> {
     IsCaptured: boolean;
     InsurancePackages: object[] | null;
 }
+type RegistrationDocumentCaptureResult = CaptureResult<InsuranceCaptureData | IdentificationCaptureData>;
 interface InsuranceRecord {
     LastUpdatedBy: string | null;
     IrcName: string | null;
@@ -164,6 +165,23 @@ declare class HCSettingsClient extends HCBaseConnector {
      * fileKey is the storage key of the uploaded image.
      */
     captureUserPhoto(fileKey: string): Promise<APIResponse<CaptureResult<UserPhotoCaptureData>>>;
+    /**
+     * Returns a canned URL for uploading a registration document image
+     * (driving licence or insurance card) before the user is authenticated.
+     * Does not send the patient auth token.
+     *
+     * The returned `ImageURL` is signed with an `x-amz-acl: public-read`
+     * header — the upload PUT request to that URL must include the exact
+     * same header (`x-amz-acl: public-read`) or S3 will reject it with
+     * `SignatureDoesNotMatch`.
+     */
+    getRegistrationDocumentCannedUrl(documentType: CaptureType, extension: string): Promise<APIResponse<UserImage>>;
+    /**
+     * Submits an uploaded registration document for capture without sending
+     * an authenticated patient token.
+     * fileKey is the storage key of the uploaded image.
+     */
+    captureRegistrationDocument(fileKey: string, type: CaptureType): Promise<APIResponse<RegistrationDocumentCaptureResult>>;
     /**
      * Soft-deactivates the current patient account.
      * The patient record is not permanently deleted.
@@ -172,4 +190,4 @@ declare class HCSettingsClient extends HCBaseConnector {
     private getAuthHeaders;
 }
 
-export { type CaptureResult, type CaptureType, type CoverageData, type Encounter, HCSettingsClient, type IdentificationCaptureData, type InsuranceCaptureData, type InsuranceRecord, type PatientDashboard, type PatientRecord, type UserImage, type UserPhotoCaptureData, UserStatus };
+export { type CaptureResult, type CaptureType, type CoverageData, type Encounter, HCSettingsClient, type IdentificationCaptureData, type InsuranceCaptureData, type InsuranceRecord, type PatientDashboard, type PatientRecord, type RegistrationDocumentCaptureResult, type UserImage, type UserPhotoCaptureData, UserStatus };

package/dist/index.js

@@ -208,6 +208,54 @@ var HCSettingsClient = class extends HCBaseConnector {
     );
   }
   // ===========================================================================
+  // Registration document capture
+  // ===========================================================================
+  /**
+   * Returns a canned URL for uploading a registration document image
+   * (driving licence or insurance card) before the user is authenticated.
+   * Does not send the patient auth token.
+   *
+   * The returned `ImageURL` is signed with an `x-amz-acl: public-read`
+   * header — the upload PUT request to that URL must include the exact
+   * same header (`x-amz-acl: public-read`) or S3 will reject it with
+   * `SignatureDoesNotMatch`.
+   */
+  async getRegistrationDocumentCannedUrl(documentType, extension) {
+    const resolvedDocumentType = this.requireValue(documentType, "Document type", "documentType");
+    const resolvedExtension = this.requireValue(extension, "Extension", "extension");
+    const requestPayload = {
+      Data: { Extension: resolvedExtension }
+    };
+    return this.execute(
+      "getRegistrationDocumentCannedUrl",
+      () => this.http.put(
+        `${this.auth.getBaseUrl()}/api/patient/registration/document/cannedurl/${resolvedDocumentType}`,
+        requestPayload,
+        this.getHeaders()
+      )
+    );
+  }
+  /**
+   * Submits an uploaded registration document for capture without sending
+   * an authenticated patient token.
+   * fileKey is the storage key of the uploaded image.
+   */
+  async captureRegistrationDocument(fileKey, type) {
+    const resolvedFileKey = this.requireValue(fileKey, "File key", "fileKey");
+    const resolvedType = this.requireValue(type, "Capture type", "type");
+    const requestPayload = {
+      Data: { Type: resolvedType, FileID: resolvedFileKey }
+    };
+    return this.execute(
+      "captureRegistrationDocument",
+      () => this.http.post(
+        `${this.auth.getBaseUrl()}/api/registrationdocument/capture`,
+        requestPayload,
+        this.getHeaders()
+      )
+    );
+  }
+  // ===========================================================================
   // Account
   // ===========================================================================
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@healthcloudai/hc-settings-connector",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Healthcheck Settings SDK with TypeScript",
   "author": "Healthcheck Systems Inc",
   "license": "MIT",