@healthcloudai/hc-settings-connector 0.2.2 → 0.2.4

package/README.md

@@ -60,7 +60,7 @@ const settingsClient = new HCSettingsClient(
 );
 ```
 
-`HCLoginClient` must be configured before creating the Settings client. Most Settings methods require an authenticated patient session. `captureRegistrationDocument(...)` is intended for unauthenticated registration flows and does not send the auth token.
+`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.
 
 ---
 
@@ -682,6 +682,90 @@ console.log(response);
 
 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:
@@ -798,7 +882,8 @@ console.log(response);
 * `captureDrivingLicense(...)` internally sends `Type: "identification"`.
 * `captureInsurance(...)` internally sends `Type: "healthinsurance"`.
 * `captureUserPhoto(...)` internally sends `Type: "userphoto"`.
-* `captureRegistrationDocument(...)` does not send the patient auth token.
+* `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).
 
 ```
 ```
@@ -808,7 +893,7 @@ console.log(response);
 
 ## Prerequisites
 
-`HCLoginClient` must be configured before using this connector. Most methods require the patient to be logged in. `captureRegistrationDocument(...)` is the unauthenticated exception and does not send the auth token.
+`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

@@ -242,6 +242,31 @@ 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.

package/dist/index.d.cts

@@ -165,6 +165,17 @@ 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.

package/dist/index.d.ts

@@ -165,6 +165,17 @@ 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.

package/dist/index.js

@@ -210,6 +210,31 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@healthcloudai/hc-settings-connector",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Healthcheck Settings SDK with TypeScript",
   "author": "Healthcheck Systems Inc",
   "license": "MIT",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "axios": "^1.13.4",
-    "@healthcloudai/hc-login-connector": "^0.3.1",
+    "@healthcloudai/hc-login-connector": "^0.4.0",
     "@healthcloudai/hc-http": "^0.2.1"
   },
   "peerDependencies": {