@healthcloudai/hc-login-connector 0.2.0 → 0.3.0

package/README.md

@@ -19,7 +19,7 @@ below follow the current behavior implemented in `src/client.ts`.
 6. Password reset initiation and password reset confirmation
 7. Access token, ID token, tenant, and base URL helper methods
 8. Token refresh using the stored refresh token
-9. Authenticated patient header retrieval through `getUserInfo()`
+9. Authenticated patient header retrieval through `getPatientHeader()`
 10. Built on the shared Healthcheck HttpClient layer
 
 ---
@@ -114,7 +114,7 @@ The usage example above reads the value from local state.
 `getBaseUrl()` returns the currently configured base URL from local state.
 
 ```txt
-https://dev-api-healthcheck.healthcloud-services.com/api
+https://dev-api-healthcheck.healthcloud-services.com
 ```
 
 ---
@@ -242,10 +242,14 @@ strings. If a field needs to contain multiple values, serialize those values int
 one string value, such as a comma separated list or another separator-separated
 list expected by the integration.
 
-`verifyEmailCode` is a dedicated boolean option that controls whether `User.Attributes.VERIFY_EMAIL_CODE` is included in the registration payload, depending on whether email verification should be handled through an OTP code.
+`isOTP` is a dedicated boolean option that controls whether `User.Attributes.VERIFY_EMAIL_CODE` is included in the registration payload, depending on whether email verification should be handled through an OTP code.
 
-- If `verifyEmailCode` is `true`, the client sends `VERIFY_EMAIL_CODE: "true"`.
-- If `verifyEmailCode` is `false` or omitted, `VERIFY_EMAIL_CODE` is not sent.
+- If `isOTP` is `true`, the client sends `VERIFY_EMAIL_CODE: "true"`.
+- If `isOTP` is `false` or omitted, `VERIFY_EMAIL_CODE` is not sent.
+
+#### OTP-based registration
+
+Use this when email verification should be handled through an OTP code. In this case, `isOTP` should be `true`.
 
 ```ts
 await loginClient.register(
@@ -254,7 +258,7 @@ await loginClient.register(
   "John",
   "Smith",
   {
-    verifyEmailCode: true,
+    isOTP: true,
     attributes: {
       Specialty: "Cardiology",
       NPINumber: "1234567890",
@@ -268,7 +272,7 @@ await loginClient.register(
 ```
 
 #### Full API request
-Request sent for the usage example above:
+Request sent for the OTP example above:
 
 ```json
 {
@@ -295,6 +299,39 @@ Request sent for the usage example above:
 }
 ```
 
+#### Link-based registration
+
+Use this when email verification should be handled through an email link. In this case, `isOTP` should be omitted or `false`.
+
+```ts
+await loginClient.register(
+  "john.smith@example.com",
+  "ExamplePassword123!",
+  "John",
+  "Smith"
+);
+```
+
+Effective request body:
+
+```json
+{
+  "Data": {
+    "TenantID": "test-tenant",
+    "Credentials": {
+      "Email": "john.smith@example.com",
+      "Password": "ExamplePassword123!"
+    },
+    "User": {
+      "FirstName": "John",
+      "LastName": "Smith",
+      "Email": "john.smith@example.com",
+      "Attributes": {}
+    }
+  }
+}
+```
+
 #### API response
 
 Status:
@@ -317,7 +354,7 @@ Notes:
 - `attributes` is the extension point for arbitrary additional registration fields.
 - The module does not need to know custom attribute names in advance.
 - All `attributes` values should be strings. Multi-value attributes should be serialized into one string value, such as a comma separated list or another integration-specific separator-separated list.
-- `verifyEmailCode` takes precedence over any manually provided `VERIFY_EMAIL_CODE` inside `attributes`.
+- `isOTP` takes precedence over any manually provided `VERIFY_EMAIL_CODE` inside `attributes`.
 
 ---
 
@@ -329,9 +366,13 @@ Registers a patient for the configured tenant using the richer registration payl
 
 `TenantID` is injected internally from `configure(...)`.
 
-`verifyEmailCode` behaves the same way as in `register(...)`:
+`isOTP` behaves the same way as in `register(...)`:
 when enabled, the client injects `VERIFY_EMAIL_CODE: "true"` into `User.Attributes`.
 
+#### OTP-based registration
+
+Use this when email verification should be handled through an OTP code. In this case, `isOTP` should be `true`.
+
 ```ts
 await loginClient.registerFull({
   email: "john.smith@example.com",
@@ -348,7 +389,7 @@ await loginClient.registerFull({
   genderIdentity: "Male",
   status: 0,
   language: "en",
-  verifyEmailCode: true,
+  isOTP: true,
   attributes: {
     source: "sdk-test"
   },
@@ -406,6 +447,40 @@ Request sent for the usage example above:
 }
 ```
 
+#### Link-based registration
+
+Use this when email verification should be handled through an email link. In this case, `isOTP` should be omitted or `false`.
+
+```ts
+await loginClient.registerFull({
+  email: "john.smith@example.com",
+  password: "ExamplePassword123!",
+  firstName: "John",
+  lastName: "Smith"
+});
+```
+
+Effective request body:
+
+```json
+{
+  "Data": {
+    "TenantID": "test-tenant",
+    "Credentials": {
+      "Email": "john.smith@example.com",
+      "Password": "ExamplePassword123!",
+      "TenantID": "test-tenant"
+    },
+    "User": {
+      "FirstName": "John",
+      "LastName": "Smith",
+      "Email": "john.smith@example.com",
+      "Attributes": {}
+    }
+  }
+}
+```
+
 #### API response
 
 Status:
@@ -435,24 +510,28 @@ verification settings.
 when email verification should be handled through an OTP code, the client sends
 `VERIFY_EMAIL_CODE: "true"` inside `User.Attributes`.
 
-- If `options.verifyEmailCode` is `true`, the client sends `VERIFY_EMAIL_CODE: "true"`.
-- The value is sent as a string inside `User.Attributes`, matching the `register(...)` method behavior when `verifyEmailCode` is `true`.
-- If `options.verifyEmailCode` is `false` or omitted, `VERIFY_EMAIL_CODE` is not sent.
+- If `options.isOTP` is `true`, the client sends `VERIFY_EMAIL_CODE: "true"`.
+- The value is sent as a string inside `User.Attributes`, matching the `register(...)` method behavior when `isOTP` is `true`.
+- If `options.isOTP` is `false` or omitted, `VERIFY_EMAIL_CODE` is not sent.
 - Calling `verifyEmail(...)` without `options` keeps OTP email verification disabled by default.
 
+#### OTP-based email verification
+
+Use this when email verification should be handled through an OTP code. In this case, `options.isOTP` should be `true`.
+
 ```ts
 await loginClient.verifyEmail(
   "john.smith@example.com",
   "123456",
   "en",
   {
-    verifyEmailCode: true
+    isOTP: true
   }
 );
 ```
 
 #### Full API request
-Request sent for the usage example above:
+Request sent for the OTP example above:
 
 ```json
 {
@@ -471,6 +550,34 @@ Request sent for the usage example above:
 }
 ```
 
+#### Link-based email verification
+
+Use this when email verification should be handled through an email link. In this case, `options.isOTP` should be omitted or `false`.
+
+```ts
+await loginClient.verifyEmail(
+  "john.smith@example.com",
+  "123456",
+  "en"
+);
+```
+
+Effective request body:
+
+```json
+{
+  "Data": {
+    "Data": "123456",
+    "Step": "EMAIL_VERIFY",
+    "User": {
+      "Email": "john.smith@example.com",
+      "TenantID": "test-tenant"
+    },
+    "Language": "en"
+  }
+}
+```
+
 #### API response
 
 Status:
@@ -500,23 +607,27 @@ settings.
 when email verification should be handled through an OTP code, the client sends
 `VERIFY_EMAIL_CODE: "true"` inside `User.Attributes`.
 
-- If `options.verifyEmailCode` is `true`, the client sends `VERIFY_EMAIL_CODE: "true"`.
-- The value is sent as a string inside `User.Attributes`, matching the `register(...)` method behavior when `verifyEmailCode` is `true`.
-- If `options.verifyEmailCode` is `false` or omitted, `VERIFY_EMAIL_CODE` is not sent.
+- If `options.isOTP` is `true`, the client sends `VERIFY_EMAIL_CODE: "true"`.
+- The value is sent as a string inside `User.Attributes`, matching the `register(...)` method behavior when `isOTP` is `true`.
+- If `options.isOTP` is `false` or omitted, `VERIFY_EMAIL_CODE` is not sent.
 - Calling `resendEmailVerify(...)` without `options` keeps OTP email verification disabled by default.
 
+#### OTP-based resend
+
+Use this when email verification should be handled through an OTP code. In this case, `options.isOTP` should be `true`.
+
 ```ts
 await loginClient.resendEmailVerify(
   "john.smith@example.com",
   "en",
   {
-    verifyEmailCode: true
+    isOTP: true
   }
 );
 ```
 
 #### Full API request
-Request sent for the usage example above:
+Request sent for the OTP example above:
 
 ```json
 {
@@ -535,6 +646,33 @@ Request sent for the usage example above:
 }
 ```
 
+#### Link-based resend
+
+Use this when email verification should be handled through an email link. In this case, `options.isOTP` should be omitted or `false`.
+
+```ts
+await loginClient.resendEmailVerify(
+  "john.smith@example.com",
+  "en"
+);
+```
+
+Effective request body:
+
+```json
+{
+  "Data": {
+    "Data": "",
+    "Step": "RESEND_EMAIL_VERIFY",
+    "User": {
+      "Email": "john.smith@example.com",
+      "TenantID": "test-tenant"
+    },
+    "Language": "en"
+  }
+}
+```
+
 #### API response
 
 Status:
@@ -851,20 +989,20 @@ Status:
 
 ### Reset Password
 
-`resetPassword` supports both OTP-based and link-based reset initiation
+`requestPasswordReset` supports both OTP-based and link-based reset initiation
 flows.
 
-`IsPasswordResetWithOTP` is optional. It is included in the request body only
-when `isPasswordResetWithOTP` is `true`. When `false` or omitted, the field is
-not sent at all and `false` is not serialized into the payload.
+`isOTP` is optional. When it is `true`, the client includes
+`IsPasswordResetWithOTP: true` in the API request. When `false` or omitted, the
+backend field is not sent at all.
 
 #### OTP-based password reset initiation
 
 Use this when the password reset flow should be handled through an OTP code.
-In this case, `IsPasswordResetWithOTP` should be `true`.
+In this case, `isOTP` should be `true`.
 
 ```ts
-await loginClient.resetPassword("john.smith@example.com", true);
+await loginClient.requestPasswordReset("john.smith@example.com", true);
 ```
 
 #### Full API request
@@ -882,11 +1020,11 @@ await loginClient.resetPassword("john.smith@example.com", true);
 #### Link-based password reset initiation
 
 Use this when the password reset flow should be handled from an email link.
-In this case, `IsPasswordResetWithOTP` should be omitted by passing `false` or
+In this case, `isOTP` should be omitted by passing `false` or
 leaving the second argument out.
 
 ```ts
-await loginClient.resetPassword("john.smith@example.com", false);
+await loginClient.requestPasswordReset("john.smith@example.com", false);
 ```
 
 Effective request body:
@@ -923,28 +1061,27 @@ Status:
 
 ### Reset Password Confirm
 
-`resetPasswordConfirm` supports both OTP-based and link-based confirmation
+`confirmPasswordReset` supports both OTP-based and link-based confirmation
 flows.
 
-If `IsPasswordResetWithOTP` is `true`, `Code` is required. If
-`IsPasswordResetWithOTP` is not `true`, `Token` is required. For the
-link-based flow, the frontend is responsible for taking the token from the
-password reset email link and passing that token in the payload.
+If `isOTP` is `true`, `Code` is required. If `isOTP` is not `true`, `Token` is
+required. The client maps `isOTP: true` to `IsPasswordResetWithOTP: true` in the
+API request. For the link-based flow, the frontend is responsible for taking
+the token from the password reset email link and passing that token in the
+payload.
 
 #### OTP-based password reset confirmation
 
 Use this when the password reset flow was started with OTP. In this case,
-`IsPasswordResetWithOTP` should be `true` and `Code` should contain the final
+`isOTP` should be `true` and `Code` should contain the final
 reset code.
 
 ```ts
-await loginClient.resetPasswordConfirm({
-  Data: {
-    Email: "john.smith@example.com",
-    Password: "ExamplePassword123!",
-    IsPasswordResetWithOTP: true,
-    Code: "123456"
-  }
+await loginClient.confirmPasswordReset({
+  Email: "john.smith@example.com",
+  Password: "ExamplePassword123!",
+  isOTP: true,
+  Code: "123456"
 });
 ```
 
@@ -967,15 +1104,13 @@ Request body:
 Use this when the password reset flow was started from an email link. In this
 case, `Token` should be included in the payload, the frontend should read the
 token value from the password reset email link and send that token in the
-request payload, and `IsPasswordResetWithOTP` should be omitted or `false`.
+request payload, and `isOTP` should be omitted or `false`.
 
 ```ts
-await loginClient.resetPasswordConfirm({
-  Data: {
-    Email: "john.smith@example.com",
-    Password: "ExamplePassword123!",
-    Token: "token-from-email-link"
-  }
+await loginClient.confirmPasswordReset({
+  Email: "john.smith@example.com",
+  Password: "ExamplePassword123!",
+  Token: "token-from-email-link"
 });
 ```
 
@@ -1102,19 +1237,19 @@ If an API key has been configured through setApiKey(...), the returned header ob
 
 ---
 
-### Get User Info
+### Get Patient Header
 
-Public signature: `loginClient.getUserInfo()`
+Public signature: `loginClient.getPatientHeader()`
 
 Calls the patient header endpoint and returns the raw server response.
 It requires a stored ID token.
 
 ```ts
-const userInfo = await loginClient.getUserInfo();
+const header = await loginClient.getPatientHeader();
 ```
 
 #### Full API request
-`getUserInfo()` does not send a request body.
+`getPatientHeader()` does not send a request body.
 
 #### API response
 
@@ -1128,42 +1263,60 @@ Status:
 {
   "Data": {
     "Record": {
-      "ID": "record-id-example",
-      "TenantID": "test-tenant",
+      "Status": 1,
+      "Sex": "Male",
+      "GenderIdentity": "Male",
+      "HasInsurance": true,
+      "HasIDCard": true,
+      "HasSelfie": true,
+      "Flags": null,
       "FirstName": "John",
       "LastName": "Smith",
+      "MiddleName": null,
+      "BirthDate": "1990-01-01T00:00:00",
       "Email": "john.smith@example.com",
       "Phone": "+15555550123",
-      "BirthDate": "1990-01-01T00:00:00",
-      "Gender": "male",
-      "Sex": "Male",
+      "Gender": "Male",
       "Race": "White",
-      "Ethnicity": "Not Hispanic or Latino",
-      "HasInsurance": false,
-      "HasIDCard": false,
-      "HasSelfie": false,
+      "Ethnicity": "",
+      "CRMID": null,
+      "AppleUserId": null,
       "Address": {
-        "StreetAndNumber": "123 Test St",
+        "StreetAndNumber": "1 Main St",
         "Extension": null,
         "City": "Springfield",
-        "State": "CA",
-        "PostalCode": "90210",
+        "State": "IL",
+        "PostalCode": "62701",
         "Country": "US"
       },
       "Attributes": {
-        "FHIRPatientID": "patient-id-example",
-        "CompositeID": "composite-id-example",
-        "VERIFY_EMAIL_CODE": "true"
+        "AthenaPatientID": "patient-id-example",
+        "AthenaGuarantorFirstName": "John",
+        "AthenaGuarantorLastName": "Smith",
+        "AthenaGuarantorEmail": "john.smith@example.com",
+        "AthenaCountryCode": "USA",
+        "AthenaDepartmentId": "1",
+        "AthenaEmailExists": "True",
+        "AthenaTestPatient": "False",
+        "PatientImageURL": "https://storage.example.com/selfie_example.jpg",
+        "CompositeID": "tenant-id/john.smith@example.com",
+        "Insurance": "EXAMPLE INSURANCE"
       },
-      "CompositeID": "composite-id-example",
-      "FHIRID": "fhir-id-example"
+      "CompositeID": "tenant-id/john.smith@example.com",
+      "FHIRID": "fhir-id-example",
+      "AthenaID": "patient-id-example",
+      "Created": "0001-01-01T00:00:00",
+      "Modified": "0001-01-01T00:00:00",
+      "CreatedByID": null,
+      "ModifiedByID": null,
+      "IsDeactivated": false,
+      "TenantID": "test-tenant",
+      "ID": "record-uuid-example"
     },
     "Encounters": null,
-    "EHR": "fhir",
+    "EHR": "athena",
     "PendingActions": [
-      "ADD_INSURANCE",
-      "ADD_ID",
-      "IMPORT_VITALS"
+      "TAKE_TEST"
     ]
   },
   "ErrorMessage": null,
@@ -1231,10 +1384,47 @@ eyJ_id_token_example
 - Use `submitOnboardingStep(...)` or the onboarding helper methods to complete required onboarding steps.
 - Call `login(...)` to authenticate and store the returned access, refresh, and ID tokens in memory.
 - Use `refreshToken()` to replace the current token set when a stored refresh token is available.
-- Use `getAuthHeader()`, `getAccessToken()`, `getIDToken()`, and `getUserInfo()` for authenticated flows after login.
+- Use `getAuthHeader()`, `getAccessToken()`, `getIDToken()`, and `getPatientHeader()` for authenticated flows after login.
 - Other Healthcheck connectors can consume `getAuthHeader()` instead of managing auth tokens directly.
 
 
+## Token Expiry and Refresh
+
+The SDK does **not** auto-refresh tokens. Call `refreshToken()` proactively when the token is about to expire.
+
+`getTokens()` returns the current in-memory token set, including `expiresAt` — an absolute Unix millisecond timestamp parsed from the `Expiration` field the backend returns.
+
+`isTokenExpired()` is a helper that returns `true` when there is no stored token or when `Date.now() >= expiresAt`.
+
+Recommended pattern:
+
+```ts
+async function ensureFreshToken(loginClient: HCLoginClient): Promise<void> {
+  if (loginClient.isTokenExpired()) {
+    await loginClient.refreshToken();
+  }
+}
+
+// Call before any authenticated connector operation
+await ensureFreshToken(loginClient);
+const result = await otherConnector.someMethod();
+```
+
+`getTokens()` shape:
+
+```ts
+interface AuthTokens {
+  accessToken: string;
+  refreshToken: string;
+  idToken: string | null;
+  expiresAt: number; // absolute milliseconds since Unix epoch
+}
+```
+
+`refreshToken()` does not require a current ID token. It uses the stored refresh token from the previous successful `login()` call.
+
+---
+
 ## Notes
 
 - `configure()` stores tenant configuration locally and does not send an HTTP request.
@@ -1242,7 +1432,15 @@ eyJ_id_token_example
 - `register()`, `verifyEmail()`, and `resendEmailVerify()` all follow the same string-based `User.Attributes.VERIFY_EMAIL_CODE` pattern for OTP email verification flows.
 - `saveAddress()` accepts an `Address`.
 - `login()` stores the initial token set internally, and `refreshToken()` updates that stored token set when a refresh token is available.
-- `refreshToken()` does not require a current ID token. It uses the stored refresh token from the previous successful login.
-- `getUserInfo()` calls the patient header endpoint.
-- `getAuthHeader()`, `getAccessToken()`, `getIDToken()`, `getBaseUrl()`, and `getTenantId()` return local values and do not perform HTTP requests.
+- `getPatientHeader()` calls the patient header endpoint.
+- `getAuthHeader()` returns `Authorization: Bearer <idToken>` + `X-Tenant-ID`. It does **not** carry an API key — each connector adds its own key independently.
+- `getAuthHeader()`, `getAccessToken()`, `getIDToken()`, `getBaseUrl()`, `getTenantId()`, `getTokens()`, and `isTokenExpired()` return or evaluate local values and do not perform HTTP requests.
 - This connector is intended to be reused by other Healthcheck SDK connectors built on the same HTTP layer.
+
+---
+
+## getPatientHeader vs getDashboard
+
+`HCLoginClient.getPatientHeader()` calls `/api/patient/header` and returns a lightweight patient record plus pending actions. Typically called once after login to check patient state.
+
+`HCSettingsClient.getDashboard()` (in `hc-settings-connector`) calls `/api/patient/dashboard` and returns a richer dashboard including encounters. These are different endpoints with different response shapes — not duplicates.