@choiceapps/communityservices-sdk 0.1.0

package/docs/browser-session.md

@@ -0,0 +1,129 @@
+# Use a browser session
+
+[Documentation index](README.md) · [Agent guide](../AGENTS.md)
+
+The examples below are integration fragments. Supply application-owned IDs and an authenticated session. The browser export runs in Node and controls a dedicated Playwright page; it is not frontend JavaScript.
+
+## Experimental GWT enrollment helpers
+
+`GwtEnrollmentHelpers` adds `addHouseholdMembers` and `createInterimUpdate` for the web application's GWT-RPC calls. This is an explicit browser-session integration, separate from `WellSkyClient` and REST authentication. Supply a trusted `GwtEnrollmentSession` adapter and a `GwtMutationStore`:
+
+```ts
+const helpers = new GwtEnrollmentHelpers({
+  tenant: "your-tenant",
+  moduleBaseUrl: "https://wscs.wellsky.com/your-tenant/com.bowmansystems.sp5.core.ServicePoint/",
+  session, // Fresh GWT/UI reads, fresh request preparation, authenticated same-origin POST.
+  store,   // Shared durable enrollment lock and attempt journal.
+});
+
+await helpers.addHouseholdMembers({ clientId, enrollmentId, memberClientIds: [memberClientId] });
+await helpers.createInterimUpdate({
+  clientId, enrollmentId, clientIds: [clientId, memberClientId],
+  reviewDate: "2026-10-22T12:00:00-04:00",
+});
+```
+
+Dates require an explicit offset and are compared as instants. No seven-hour correction is applied. The clients must already belong to the household before enrollment attachment. Interim clients must already be enrolled, and the target client must be included in `clientIds`.
+
+For a client without a household, the browser adapter supports the UI's `createEntryExitReview` call with its implicit single client. The core accepts this signature only when the requested clients, enrolled members and household snapshot all identify that sole head. Household reviews continue to use `createEntryExitReviewWithHouseholdMembers`. Creating a review does not populate its assessment answers; discover the program's interim instrument and write its applicable answers at the review date separately.
+
+The adapter must implement three operations:
+
+- `readEnrollment`: return a fresh, complete enrollment model, household membership, enrolled members, and all reviews with their included clients. Supply a revision/digest covering those reads and a non-secret session identifier. Failed, truncated, stale, or REST-derived empty results are not valid snapshots.
+- `prepare`: use current models to serialize the intended operation, or intercept a newly generated UI request and abort it **before** transmission. Return it with the matching intent, session, revision and capture timestamp. The SDK invokes preparation only when the requested state is missing; previously saved templates are not accepted. The adapter must verify the nested DTO identities and other stored values. The SDK validates the RPC envelope, known type signatures, endpoint, headers and freshness; it is not a general GWT object serializer.
+- `send`: issue exactly one authenticated same-origin POST. Do not retry, redirect, log payloads, or replay after authentication refresh. The SDK does not acquire browser credentials or export browser cookies.
+
+Before sending, the helper reads state again and checks session/revision stability, then persists an attempt. It verifies the result through another authoritative read even if the response is lost or contains an error. If the result cannot be established, it raises `AmbiguousCommitError` and leaves the attempt pending. A pending attempt blocks all subsequent writes to that enrollment until a fresh read proves it succeeded. An empty read alone never clears an uncertain attempt. A partially matching or duplicated Update at the same instant raises `GwtEnrollmentConflictError` instead of creating another review.
+
+All processes must share the store and enrollment lock. `createInMemoryGwtMutationStore()` is for development and protects only callers sharing that instance; it does not survive restarts. The packaged [file-store example](../examples/gwt-file-store.mjs) re-exports a single-host durable file journal with exclusive locks and atomic writes. A crash intentionally leaves its lock for operator reconciliation. Multi-host deployments need a shared durable implementation. The server has no proven idempotency key or conditional-write contract, so this cannot prevent an unrelated user or integration writing outside that lock between read and send.
+
+Sandbox acceptance through October 23, 2026 verified member attachment, interim creation, and same-key reconciliation across fresh helpers and browser logins without another mutation. See the [capability and evidence summary](capabilities.md).
+
+## Headless browser adapter
+
+The optional ESM export `@choiceapps/communityservices-sdk/browser` supplies the adapter, a configurable browser login, and a durable single-host file journal. Install `playwright-core` separately and provide an installed Chrome executable (or install Playwright's Chromium). Tested with Playwright Core 1.56.1. The REST entry points do not load Playwright.
+
+```js
+import { chromium } from 'playwright-core';
+import {
+  openEnrollmentSession,
+  createFileGwtMutationStore,
+} from '@choiceapps/communityservices-sdk/browser';
+
+const session = await openEnrollmentSession({
+  tenant: 'your-tenant',
+  chromium,
+  envFile: '.env', // HMIS_UI_USER and HMIS_UI_PASSWORD, distinct from REST credentials.
+  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  store: createFileGwtMutationStore('/private/path/hmis-journal'),
+});
+try {
+  await session.helpers.addHouseholdMembers({
+    clientId, enrollmentId, memberClientIds: [memberClientId],
+  });
+  await session.helpers.createInterimUpdate({
+    clientId, enrollmentId, clientIds: [clientId, memberClientId],
+    reviewDate: '2026-10-21T12:00:00-04:00',
+  });
+} finally {
+  await session.close();
+}
+```
+
+The login uses the required `tenant` option to build its URL, opens a fresh browser context, and never exports credentials or cookies. Use your application's configured tenant identifier. Supply `moduleBaseUrl` for another host; its path must match the tenant. Keep the page alive. Existing authenticated pages can use `createPlaywrightEnrollmentHelpers({page, store, tenant, moduleBaseUrl})`; all tenants use the same options and operations. The documented workflow was reproduced in a sandbox tenant. Each operation reads current GWT state, prepares through the current UI, intercepts and aborts Save, persists the attempt, sends the captured request once, and verifies it. Whole-second interim timestamps are required; ambiguous local daylight-saving times fail closed. Interim creation creates the review and its participant links, not additional assessment answers.
+
+Use the page exclusively for these helpers. They serialize their operations on a shared page; do not drive it simultaneously through unrelated scripts. Selectors and GWT signatures are experimental. Unexpected UI/schema changes, incomplete lists (over 1,000 records), authentication loss, or conflicting records stop the operation. A new login does not clear an uncertain attempt. The file journal supports one host; use a shared durable store across multiple hosts. Keep journals private and retain them across restarts. A crash can leave a lock that requires manual reconciliation.
+
+## Expired UI passwords
+
+Password recovery is enabled by default for `openUiSession` and `openEnrollmentSession`. It uses `!` and a private durable journal under `~/.wellsky-sdk/password-recovery`, shared by UI account across callers on that host. Set `HMIS_UI_PASSWORD_RECOVERY_DIR` in the selected credentials file to use a persistent directory of your choice. The directory must remain available across restarts. You can override the store or suffix:
+
+```js
+const session = await openEnrollmentSession({
+  tenant: 'your-tenant',
+  chromium,
+  envFile: '.env',
+  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  store: createFileGwtMutationStore('/private/path/enrollment-journal'),
+  passwordRecovery: {
+    store: createFileGwtMutationStore('/private/path/password-recovery-journal'),
+    appendCharacter: '!', // Exactly one printable, non-space ASCII character.
+  },
+});
+console.log(session.passwordRecovery); // 'not-needed' or 'restored-original'
+```
+
+On the expired-login form, the helper appends the character to the original `HMIS_UI_PASSWORD`, submits both reset fields, opens User Profile / Change Password, and restores the original. It then signs in with the original in a fresh browser context before returning success. The `.env` file stays unchanged. A normal login makes no password changes. Set `passwordRecovery: false` to disable password changes. With recovery disabled, expiration raises `LoginError` with code `PASSWORD_EXPIRED`.
+
+Use one shared, durable recovery store for every caller of the same UI account. Multi-host deployments must override the default with shared durable storage and locking. Keep using an existing custom recovery store if it has a pending recovery; changing stores does not reconcile it. The per-account lock covers the entire recovery. Its journal contains stages and the append character, never either password. The original must be 8–49 characters when a reset is needed so the temporary password fits the observed 50-character limit. A 50-character password can still log in normally. Keep the original credential and append character unchanged while a recovery is pending. The SDK sanitizes login errors; do not enable Playwright tracing, request-body capture, or debug logging containing credentials.
+
+A saved temporary-password attempt can resume with one authentication check of that temporary password. A saved restoration attempt can resume with one authentication check of the original. Neither uncertain password write is repeated. An interrupted or failed authentication check leaves a blocking journal stage and raises `RECOVERY_UNCERTAIN`; reconcile the account and journal before proceeding. A process crash may also leave the file store's exclusive lock. Do not delete journals or automatically expire locks to force retries. If server policy rejects restoring the original, the helper stops and the temporary password may remain active.
+
+Both UI actions use GWT-RPC: the shipped expired-login handler calls `AuthenticationService.changePasswordHeartbeat`, while the user-settings restoration was observed calling `UserService.updateUserPassword` with HTTP 200 / GWT OK. The former uses the limited session established by the expired login. The helper currently drives the live forms to generate fresh requests. A standalone RPC-only password adapter has not been implemented or tested; captured password payloads must not be stored or replayed. See [sandbox findings](capabilities.md).
+
+## Adopting existing enrollment records
+
+If requested membership or a review already exists, the GWT helper records a verified journal entry before returning `already-present`. Later calls return `reconciled`; if the observed state disappears, they raise `previously-verified-missing` without preparing or sending another write. Journal persistence must succeed even when the operation adopts existing records. Older versions did not journal these observations, so an existing journal cannot prove an observation that was never saved.
+
+## Reauthentication and interrupted writes
+
+Sessions returned by the headless helpers retain the same `page` and `context` across reauthentication. Enrollment helpers, service UI, program discovery, attachments and exit helpers built from that managed page check authentication under the shared page lock before each browser operation. A visible login form or an HTTP 401 from the configured tenant triggers reauthentication using the same credentials and recovery journal. WellSky can also return HTTP 500 while leaving an expired dashboard visible. After an unclassified operation failure, the helper opens a separate read-only page to check authentication; it reconnects only if that page shows the login form. An inconclusive probe leaves the original error intact. Authentication failures block further automatic attempts until explicitly resolved.
+
+```js
+await session.ensureAuthenticated(); // Reconnect only when expiry has been detected.
+await session.reauthenticate();      // Explicit reconnect, serialized with browser operations.
+```
+
+Confirmed attachment conflicts retain `AttachmentConflictError` and their `reason` without an authentication probe or reconnect. Authentication cannot resolve changed attachment identity, content, or intent. See [attachment recovery](files-and-notes.md). The next operation still performs normal authentication preflight.
+
+For other failures that coincide with confirmed session expiration, the helper reconnects after the operation unwinds and throws `SessionInterruptedError`, code `SESSION_INTERRUPTED`. Its `reauthenticated` property says whether reconnecting succeeded. It never reruns the interrupted callback, resends a captured payload, clears a mutation journal, or restarts a bulk batch. If a failed authentication attempt needs to be retried after correction, call `session.reauthenticate()` explicitly.
+
+Retry the enrollment or service operation with its original key, inputs and durable store. The existing journals reconcile confirmed commits and block unresolved writes. A changed key is not a recovery strategy. GWT snapshots and prepared requests from before reauthentication are invalidated, and the next operation reads fresh state. Bulk service recording still stops at the failed row; retry with the same row keys after resolving it.
+
+This behavior applies to SDK helpers using the managed page lock. A raw Playwright action or low-level GWT session does not gain automatic retries or authentication recovery. Unknown GWT errors and HTTP 403 are not, by themselves, treated as proof of expiration. Use explicit reauthentication when session loss is established but the UI does not display its login form. Reauthentication can reset UI navigation and provider/Enter Data As context; operations must select and validate their requested provider again.
+
+## Grouped-enrollment REST error
+
+Sandbox REST enrollment-list and complete-enrollment reads returned HTTP 400 with `42703: column v.entry_date_effective does not exist` after household attachment. This occurred after both an ordinary UI save and a direct RPC replay. The replay fixture reproduced it before its interim was created. Fresh UI/GWT reads confirmed the stored enrollment and reviews.
+
+This indicates a server query/schema problem in the observed grouped-enrollment read path. A schema/version mismatch is a possible explanation, not a confirmed root cause. It is distinct from the verification-date cutoff issue. The client cannot repair the server column/view, and changing record dates or repeating creation is not a workaround. Consumers relying on those REST reads need a verified GWT read path or an upstream WellSky fix; a failed REST read must never mean "record absent."

package/docs/capabilities.md

@@ -0,0 +1,75 @@
+# Capabilities and verified limits
+
+[Documentation index](README.md)
+
+See [integration methods](integration-methods.md) for the reasoning behind each REST, GWT-RPC, or browser path, and [WellSky feedback](vendor-issues/README.md) for actionable reports and contract questions.
+
+The generated client covers the pinned V2/V3 Swagger operations. The following findings were reproduced in a sandbox tenant through October 24, 2026. They are not production certification or proof of behavior at every provider. The evidence summaries below retain the tested scenarios and their limitations.
+
+| Task | Available path | Verified behavior and limit |
+| --- | --- | --- |
+| Typed REST requests | Root, `/v2`, `/v3` | Generated operation/model coverage with validation; server behavior still varies by endpoint |
+| Questions and picklists | `api.assessments.getDefinition`, `api.questions`, `api.picklists` | Client-scoped reads, nested definitions, current options; no complete conditional engine or historical option catalog |
+| Programs | `readProgramCatalog` | Counted active/operational providers; includes organizations, not just enrollable programs; no permission/eligibility guarantee |
+| Program assessment defaults | `createProgramDiscovery` | Read-only admin UI/GWT discovery of entry/interim/exit defaults; requires administrative access |
+| Enrollment and assessment answers | `createEnrollmentWorkflow` | Discovers defaults, saves per-client answers/rows, verifies and reconciles; existing clients required |
+| Client creation | `createClientCreator` | Durable source mapping; candidate detection without merging; lost receipt requires explicit verified ID |
+| Household creation and membership | `createHouseholds` | Stable keys, preserved history, later members, non-head departures and relationship changes; no head replacement or household closure |
+| Household enrollment | `createHouseholdEnrollment` | Existing household and at least two initial clients including head; per-member plans and IDs |
+| Later child or member | `addHouseholdMembers` | Must already belong to household; own later entry date, assessment, and DOB; existing dates preserved |
+| Interims | Workflow `createInterim`, `createHouseholdInterim` or low-level GWT `createInterimUpdate` | Workflow populates answers; low-level helper creates only review/participant links. Selected household members supported |
+| Household exit | `exitHousehold` with exit UI port | Selected members, staggered dates, subsidy/Other details, per-member exit assessments; all-member metadata uses one GWT save, assessments follow separately |
+| Head of household | Enrollment workflow guards | Missing or mid-enrollment replacement head rejected. Head cannot exit before remaining members. Retroactive replacement is not implemented |
+| Verification records at entry | `readEnrollmentVerifications` | Reads generic assessment and filters intervals; complete-enrollment entry arrays can omit valid UI rows |
+| Existing verification end dates | `api.subassessments.setEndDate` | Preserves row ID and other values, verifies result; no blind resend or delete/recreate |
+| Client Record fields | `createClientProfile` | Names, SSN, quality, veteran fields via preserved REST update; Sex via UI. Legacy Gender is not Sex |
+| DOB | `createDateOfBirth`, workflow `birthDates` | Calendar-date encoding, UI/API agreement, same-entry timestamp correction via UI; no arbitrary historical correction |
+| Independent needs | `createNeedRecorder`, `createNeedUi` | Add Need form, explicit status/outcome, durable key, no service/referral creation |
+| Service types and AIRS taxonomy | `createNeedUi().listServiceTypes` / `listServiceQuicklist` | Tenant-wide active assignable codes and separate program quicklists; not service eligibility |
+| Shelters and bed stays | `createShelters`, `createShelterUi`; [shelter guide](shelters.md) | Named-bed household check-in/checkout, same-program guards, durable retries; no overflow or inactivity scheduler |
+| Shelter inventory reads | `createShelterInventory`; [inventory guide](shelter-inventory.md) | Complete visible unit lists and named beds, occupants, holds, overflow reporting, and known/unknown vacancies; UI-derived bed keys, no server bed IDs, reservations, or future projections |
+| Services and bulk services | `createServiceRecorder` | Closed/Fully Met need, REST service plus UI completion; sequential stable-key bulk with stop-on-failure |
+| SSVF conditional fields | Recorder plus `getSsvfServiceRules` | Benefit choices and Other text via REST; assistance dates through UI. Rules are a dated sandbox snapshot |
+| Funding Sources | `createServiceUi().listFundingSources`, recorder allocations | Current provider/service/session lookup; existing permitted service context required. No universal funding catalog |
+| Attachment REST API | `fileAttachments.createForClient`, `getForClient` | Encoded multipart/body credentials supported, but supplied sandbox credentials still fail server authentication checks; not a verified upload solution |
+| Profile, Case Plans, goal uploads | `session.workflows.uploadAttachment` | Browser multipart, 10,000,000-byte cap, downloaded checksum verification, duplicate guard; visibility unchanged and public access unverified |
+| Client Notes, goals, action steps | `createCasePlans` plus raw REST methods | Journaled create/update and supported-field verification; helper supplies clientId on goal updates; unreadable follow-up fields excluded |
+| Goal case notes | `session.workflows.createCaseNote` | Optional source key rejects changed intent and verifies saved note ID; legacy unkeyed matching remains; single client only. REST goal response does not expose these notes |
+| Multi-client/multi-case notes | No packaged bulk helper | Do not infer note participants from unrelated `households` nested in a goal response |
+| Expired UI password | Headless login, enabled by default | Temporary suffix then restore original, durable recovery stages, fresh-login verification; policy rejection may leave temporary password active |
+| Session expiration | Managed session plus durable workflow journals | Reauthenticate and report interruption; caller retries original intent for reconciliation, not automatic callback replay |
+
+## Known server gaps
+
+Grouped REST enrollment reads can return `42703: column v.entry_date_effective does not exist` after both UI and RPC saves. This is not specific to replay. A broken read is not an absent enrollment. The browser enrollment reader uses current UI/GWT evidence.
+
+The October 24 [V2/V3 comparison](vendor-issues/enrollment-effective-date-column.md) reproduced the missing-column error for all 16 tested grouped complete enrollments in each version. Individual-only client lists succeeded, and individual pages within a mixed client also succeeded. Switching to V2 does not fix the issue. One individual complete read had a separate `Non-static method requires a target.` error.
+
+REST DOB updates at an existing effective timestamp can fail with an entity-tracking error. Changing the timestamp to evade that error changes history. The dedicated helper uses the matching entry UI instead.
+
+Attachment REST authentication failure reproduces outside the SDK. The token user-ID claim format is a possible contributor, not a confirmed root cause. Do not modify token claims or passwords to work around it.
+
+## Evidence and support boundary
+
+Local tests cover the generated routes, validation, journal recovery, and browser fixtures. Live acceptance tested new synthetic clients, UI readback, and repeated keys. The latest DOB workflow run verified one history row and one enrollment per new client after household interim changes, with zero additional mutations on retries.
+
+The SDK guides and vendor reports retain sanitized observations, dates, controls, and limitations. Raw authenticated captures, client data, and private journals do not belong in the repository or npm package. Recheck server-dependent behavior within an authorized scope before depending on a different deployment's UI or picklists.
+
+### Retained sandbox acceptance evidence
+
+These observations explain the current contracts. They are dated acceptance results, not a runnable live test suite or fresh verification of the server.
+
+| Scenario | Reproduced evidence | Limit and owning guide |
+| --- | --- | --- |
+| Fresh-helper retries and existing-record adoption, October 24, 2026 | Household membership/interims, attachments, and a service reconciled to the same saved identities. REST, GWT mutation, and upload counters had zero increase during retries and checks. | Missing-record and changed-identity faults were injected into readback or journal copies, not created by deleting live records. See [durable records](durable-records.md) and [recovery](troubleshooting.md). |
+| Session loss after committed writes, October 23, 2026 | Controlled cookie loss after household enrollment and service saves was followed by reauthentication and reconciliation under the original keys, without duplicate records. | This tests the observed stages, not every possible interruption. Authentication requests and read-only GWT POSTs are distinct from record writes. See [browser sessions](browser-session.md). |
+| Household exits and head coverage, October 23, 2026 | An invalid early head exit was blocked before writes. Valid staggered exits and an all-member exit preserved dates, original heads, and selected subgroups; retries made no extra record writes. | Earlier server-accepted orphaned groups were invalid under the current SDK contract. See [head validation feedback](vendor-issues/household-head-validation.md) and [enrollments](enrollments.md). |
+| Attachment identity and content, October 24, 2026 | Profile, Case Plans, and goal files retained their IDs across fresh helpers, and downloaded bytes matched the originals. | Does not establish anonymous access or sharing permissions. REST authentication remained a separate failure. See [files and notes](files-and-notes.md). |
+| SSVF conditional forms, October 23, 2026 | Form inspection checked conditional branches and required-date validation without saving; four REST-supported dependencies were then saved and read back, with zero duplicate writes on same-key retries. | This is a dated rules snapshot, not exhaustive financial assistance or funding-allocation acceptance. See [SSVF rules](../SSVF.md) and [services](services.md). |
+| Expired-password recovery, October 23, 2026 | An expired account completed temporary-password recovery, restored its original password, and authenticated in a fresh context. | Account policy can reject a recovery stage; retain the durable recovery journal. See [browser sessions](browser-session.md). |
+
+Independent needs and AIRS/service-type discovery use UI/GWT helpers. See [independent needs](independent-needs.md) for the creation, counted catalog, and retry contracts. The pinned Swagger exposes need reads but no independent-need creation.
+
+The [separate complete-enrollment target error](vendor-issues/enrollment-complete-target-error.md) was isolated to missing DOB information in controlled sandbox fixtures. Adding only `SVPPROFDOB`, or only `SVPPROFDOBTYPE` with `DOBTYPE_DONTKNOW` or `DOBTYPE_REFUSED`, changed HTTP 400 to success in V2 and V3. The quality-only fixtures retained empty DOB values, confirmed through REST and the UI. Never invent a DOB or recreate an enrollment to recover a read.
+
+Current Living Situation contact recording is available through `createCurrentLivingSituationRecorder`. It preserves distinct contacts with program-entry starts and optional recording-program verification. See the [contact guide](current-living-situation.md) for metadata mapping, date contracts, blocked server reads, and acceptance limits.

package/docs/configuration.md

@@ -0,0 +1,81 @@
+# Configuration reference
+
+[Documentation index](README.md) · [REST usage](rest-client.md)
+
+The root export selects V3. `/v2` and `/v3` fix their own `x-version` headers. Options are defined in [ClientOptions](../dist/esm/runtime.d.ts); response models and route parameters are version-specific.
+
+## REST client options
+
+| Option | Default | Contract |
+| --- | --- | --- |
+| `tenant` | Required | Explicit tenant identifier; read-only on the client |
+| `auth` | Required | One of the modes below |
+| `baseUrl` | `https://csclientapi.wellsky.com/client-api-prod` | The explicit tenant selects the system on this shared host |
+| `fetch` | Global `fetch` | Injectable transport for tests or routing |
+| `timeoutMs` | `30000` | Total request deadline, including authentication, queueing, backoff, and body reads |
+| `maxConcurrency` | `8` | Shared in-process scheduler for matching clients |
+| `maxReadRetries` | `2` | Additional GET attempts; writes are not replayed |
+| `retryBaseDelayMs` | `250` | Initial backoff setting |
+| `maxRetryDelayMs` | `30000` | Backoff/Retry-After bound |
+| `cooldown` | `{threshold:5, windowMs:10000, durationMs:30000}` | Shared failure-window cooldown |
+| `metadataCacheTtlMs` | `60000` | Definition cache lifetime |
+| `metadataCacheMaxEntries` | `100` | Per-client metadata cache bound |
+| `mobileAssessmentDateCorrectionMinutes` | Unset | Measured integer offset from -840 to 840, applied only to AddAssessmentAnswer's effective-date query |
+| `hooks`, `logger` | Unset | Allowlisted events without bodies, credentials, filters, or tokens |
+
+Matching tenant/base URL/transport clients share scheduling state and must use consistent scheduler settings. Coordination is within one process. Tenant consistency checks are described in [REST configuration](rest-client.md#configure-a-client).
+
+## Authentication modes
+
+| `auth.kind` | Required fields | Lifecycle |
+| --- | --- | --- |
+| `credentials` | `username`, `password` | Automatic `SetAuthKey`; matching credentials share cache and in-flight mint |
+| `token` | `token` | Caller owns expiry and replacement |
+| `provider` | `getToken({forceRefresh, signal})` | Caller returns a token; honors cancellation and refresh requests |
+| `none` | None | Only for deliberately unauthenticated operations or synthetic tests |
+
+REST authentication does not read `.env`. A GET can refresh authentication once after 401. A write is not replayed after 401. Mint failures return to the caller. Token minting can affect other processes using that account; keep token lifecycle coordinated in your application.
+
+## Per-request controls
+
+Every request accepts `signal`, `timeoutMs`, and `correlationId`. Use an opaque correlation ID. `WellSkyError` reports `kind`, operation template, and optional status/request ID/retry delay. Upstream bodies are discarded. See [error recovery](troubleshooting.md).
+
+## Browser session options
+
+`openUiSession` and `openEnrollmentSession` use [LoginOptions](../browser/index.d.mts):
+
+| Option | Meaning |
+| --- | --- |
+| `tenant` | Required tenant identifier, for example `your-tenant` |
+| `moduleBaseUrl` | Optional complete application module URL; must match `tenant` |
+| `chromium` | Required Playwright browser type supplied by the application |
+| `envFile` | Selected local credentials file; defaults to `.env` |
+| `executablePath` | Path to an installed compatible browser; needed when no Playwright browser is installed |
+| `timeoutMs` | Per-action login/bootstrap timeout; defaults to `90000` milliseconds. This is not a total workflow deadline |
+| `passwordRecovery` | Enabled by default; `false` disables password mutations, or supply `{store, appendCharacter}` |
+| `store` | Required by `openEnrollmentSession` for enrollment/client mutation journals |
+
+Only the selected file supplies UI credentials:
+
+```dotenv
+HMIS_UI_USER=your-browser-login
+HMIS_UI_PASSWORD=your-browser-password
+# Optional persistent recovery directory:
+HMIS_UI_PASSWORD_RECOVERY_DIR=/private/application/password-recovery
+```
+
+The recovery directory defaults to `~/.wellsky-sdk/password-recovery`. Its journal is separate from workflow mutation journals. The default temporary suffix is `!`. Read [password recovery](browser-session.md#expired-ui-passwords) before enabling an account: the helper changes an expired password and then attempts to restore the original. REST credentials can differ from these UI credentials.
+
+No browser binary is bundled. The browser helper uses a fresh context, configured tenant URL, and a dedicated page. Sessions expose `ensureAuthenticated`, `reauthenticate`, and `close`. Close the session in `finally`.
+
+## Tenant connections
+
+Use the neutral exports, such as `openUiSession`, `openEnrollmentSession`, `createServiceRecorder`, and `createCurrentLivingSituationRecorder`. Browser login requires an explicit tenant.
+
+Supply `tenant` when opening a browser session. For the default host, `tenant: 'your-tenant'` resolves to `https://wscs.wellsky.com/your-tenant/com.bowmansystems.sp5.core.ServicePoint/`. Changing the tenant selects another path; the SDK methods stay the same. `moduleBaseUrl` can select another HTTPS host, but its tenant path must match. REST and browser credentials remain separate.
+
+Pass `session.page` to UI adapters. Each adapter binds to that page's application URL and rejects later navigation into another tenant. REST/UI compositions reject mismatched tenant identifiers. Keep program, provider, client, assessment, and picklist IDs specific to the selected tenant.
+
+Browser sessions expose `session.connection`. A need recorder gets its tenant from `createNeedUi({page: session.page})`. When supplying a custom need adapter, pass `tenant` explicitly because there is no REST client from which to derive it.
+
+Keep durable journals separate for each tenant and deployment. Retain the same journal when resuming an operation so uncertain writes are reconciled. Password-recovery records include the connection scope and account identity.

package/docs/current-living-situation.md

@@ -0,0 +1,56 @@
+# Record Current Living Situation contacts
+
+[Documentation index](README.md) · [Assessment guide](assessments.md) · [Public contract](../browser/current-living-situation.d.mts) · [Example](../examples/current-living-situation.mts)
+
+Street outreach teams and night-by-night emergency shelter staff generally record Current Living Situation at each meaningful client contact. A contact is an event. An unchanged living situation does not make the next contact a duplicate.
+
+| Field | Meaning |
+| --- | --- |
+| Subassessment Start Date | The selected client's program entry date, for every contact in that enrollment |
+| Subassessment End Date | May be null or empty. A later contact does not close the previous contact row |
+| Information Date | The date that contact happened |
+| Current Living Situation | The client's actual living situation on that contact date, selected from this question's current picklist |
+| Living Situation Verified By | Optional unless the actual platform requires it. May identify the program recording the data |
+
+Do not use contact date as the row start, or replace the previous contact's information date or living-situation answer. Do not copy the income-verification close-and-replace pattern to these event records. Program entry, the contact's information date, and the assessment answer's effective timestamp have separate roles.
+
+## Discover the fields and choices
+
+Read `api.assessments.getDefinition({clientId, assessmentCode, refresh: true})` for the program's instrument. Supply its exact virtual fields to `createCurrentLivingSituationRecorder`. The SDK does not choose a program, assessment, project type, or living-situation answer from a shelter bed assignment.
+
+An October 24, 2026 sandbox metadata read exposed this mapping:
+
+| Role | Virtual field | Type |
+| --- | --- | --- |
+| Parent | `SVP_HUD_CURRENTLIVINGSITUATION` | sub_assessment |
+| Start | `SVP_HUD_CURRENTLIVINGSITUATIONSTART` | date |
+| End | `SVP_HUD_CURRENTLIVINGSITUATIONEND` | date |
+| Information date | `SVP_HUD_CLS_INFODATE` | date |
+| Living situation | `SVP_HUD_CLS_CURRENTLIVINGSIT` | lookup |
+| Verified By | `SVP_HUD_CLS_LIVINGSITVERIFIEDBY` | lookup |
+
+The form metadata explicitly labels Information Date as Date of Contact. Verified By had program options with separate **picklist option IDs**. Resolve the actual option from that question and use `{option: {code: discoveredCode}}`; do not send a numeric program ID or construct a code from it. A recording program is allowed, but it is not a required default. If another verified instrument exposes text instead, supply `{value: programDisplayName}`. Numeric values are rejected for text questions. Provider-valued questions are refused on the mobile path because the SDK cannot guarantee their persistence there.
+
+The helper requires information date and living situation, derives start from the stored enrollment, and sends an empty end. It leaves other answers absent unless supplied. `additionalAnswers` accepts actual extra platform questions and cannot override the mapped fields. Metadata-required additional answers must be provided explicitly. Conditional rules not represented in metadata still require application/form validation; do not invent defaults. A platform requirement for a nonempty end raises `platform-requires-end-date` instead of changing this workflow's rule.
+
+## Record and retry
+
+Use the [typed example](../examples/current-living-situation.mts) with an API client configured for the target tenant and durable `createFileGwtMutationStore` or equivalent shared store. No browser is launched and no credentials are loaded by this recorder.
+
+Each input specifies an existing client and enrollment, the instrument, a stable contact event key, information date, and the selected living-situation answer. It does not accept a caller-supplied start date. The helper reads the counted enrollment list and derives start from the selected enrollment's `projectStartDate`. This matters for a later-entering household member: use that person's enrollment, not another member's entry. Contacts before entry or after a recorded exit are refused. Failed, incomplete, or ambiguous enrollment/assessment reads block writes.
+
+As with the existing enrollment workflow, date inputs use timezone-qualified ISO instants with whole-second precision. Supply the contact's intended date and time in the program's timezone, for example `2026-10-24T09:00:00-04:00`. The information-date answer and assessment effective-date query use that instant; the row start uses program entry. The helper does not use the host timezone or shift body dates. Only a separately configured, measured mobile query correction affects the query; see [date contracts](dates-and-answers.md). Date-only input is rejected rather than interpreted in an unknown timezone.
+
+For outreach, record each meaningful outreach contact with its own upstream event key and the situation reported that day. For night-by-night shelter, record each meaningful contact with a separate key; do not assume a bed-night automatically supplies a contact or the client's answer. Two distinct contact keys create two rows even if the date and answers are identical. Same-key retries verify the original recordset ID and never submit again.
+
+The recorder snapshots all existing CLS rows, journals the attempt before submitting one new `recordset_id: 0`, then requires exactly one additional matching row and preservation of earlier rows. It does not adopt a preexisting row merely because its answers match. Lost responses reconcile through the journal and fresh reads. Missing, changed, multiple, or ambiguous new rows leave the attempt unresolved, blocking resubmission and later contact keys for that client. Restore the same journal and reconcile the original operation; never clear it or generate a replacement key to force a retry.
+
+All callers must share the durable store. The journal does not lock external writers or provide server-side idempotency. Coordinate other applications and manual edits during a save; one concurrent identical external row cannot be distinguished from the requested save by answer content alone. Journals contain contact snapshots and must remain private. Do not rebuild lost journals by guessing from date and living situation.
+
+## Verification limits
+
+The helper uses generic assessment reads for saved rows, not the complete-enrollment projection's scalar current-living-situation property. A scalar cannot represent contact history. It does not create an interim review, end an enrollment, overwrite a prior contact, or schedule contacts automatically.
+
+The regression suite covers multiple identical contacts, later contacts, optional program verification, metadata-required fields, date and identity drift, preservation failures, lost responses, and no replay. On October 24, 2026, a test in a sandbox tenant created three rows for an existing synthetic client: two contacts with identical dates and answers, plus a later contact with recording-program verification. Fresh assessment reads confirmed all three recordset IDs, program-entry starts, contact information dates, null ends, and selected lookup values. Same-key retries retained those IDs without additional writes. No extra answers were required by that instrument.
+
+That live test used a coordinated-entry instrument with an existing transitional-housing enrollment. It verifies the shared CLS storage and retry path, not every street outreach or night-by-night shelter form, conditional rule, role, or tenant deployment. If the counted enrollment read hits the documented grouped-enrollment server error, the recorder stops; it does not replace the entry date with the contact date or infer an empty enrollment list.

package/docs/dates-and-answers.md

@@ -0,0 +1,40 @@
+# Date and answer contracts
+
+[Documentation index](README.md) · [Assessment guide](assessments.md)
+
+The SDK deals with several kinds of dates. Applying one correction to all of them corrupts data.
+
+| Value | Input | Behavior |
+| --- | --- | --- |
+| Raw REST date field | String required by that operation | No general timezone conversion or business calendar validation |
+| Workflow entry, interim, exit, row start/end | Timezone-qualified ISO instant, whole-second precision | Validates dates and compares instants; does not shift stored dates |
+| Workflow `SVPPROFDOB` | `{value:'1984-02-29'}` | Strict calendar date through `birthDates`; timestamp input is rejected |
+| Standalone DOB helper | `dateOfBirth:'1984-02-29'`, separate `effectiveDate` instant | Encodes DOB at `07:00:00Z` for the tested fixed UTC-7 REST conversion; checks browser compatibility |
+| Mobile answer effective date | ISO instant when correction is configured | Optional measured minutes adjust only the outgoing AddAssessmentAnswer query |
+| Verification snapshot enrollment date | ISO instant with offset | Inclusive comparison against the original row start/end instants |
+| Goal case-note date | `YYYY-MM-DD` | Browser-local calendar date |
+| Service dates and financial-assistance period | Explicit timestamps | Separate fields; the period is not inferred from the service dates |
+
+The observed seven-hour mobile effective-date shift and DOB conversion are separate server behaviors. `mobileAssessmentDateCorrectionMinutes: 420` compensates for a measured subtraction in one mobile query. It does not fix DOB values or verification array filtering. Never pre-adjust a timestamp and also enable the correction. Revalidate measured offsets against saved effective dates after deployment/server changes.
+
+The DOB helper verifies client API, assessment effective date, and fresh UI values. At a new effective timestamp it uses REST. Correcting the latest existing timestamp requires the matching entry assessment context because the tested REST path returns an entity-tracking error. The helper does not move effective dates to avoid that error. Older history correction and same-timestamp interim/exit correction are not supported.
+
+The current mobile assessment projection may show a blank value for a UI-created DOB. That is not proof of missing data. The DOB helper requires agreement between client API and fresh UI before accepting the mobile row's effective date.
+
+## Verification intervals
+
+`readEnrollmentVerifications` selects rows with `start <= enrollment <= end`. Null or empty end means open. It reads the current generic assessment once and retains original IDs and date strings. It does not round an end date to the end of a day or reconstruct historical edits. Invalid or ambiguous dates cause an error rather than an empty result.
+
+The user workflow normally starts each applicable verification on or before entry. Unchanged records remain open. When a type changes, the application supplies the old row's end and a new row's start, normally on the next calendar day. The SDK does not select the program's day-boundary policy. An exit does not automatically end all verification records.
+
+## Answer states and identity
+
+`No`, client refusal, client uncertainty, data not collected, and an omitted value are different states. Use the discovered option or an explicit encoder state mapping. Never replace an unknown value with `No` to satisfy coverage.
+
+Use option codes from the current question's picklist, not cached labels from another provider. `HUD_RACEETHNICITY` needs the combination option even for a single category. The encoder handles this standard field; raw numeric IDs can display a label in REST while remaining blank in the UI.
+
+Question metadata supplies types and mandatory flags, but does not describe every conditional rule. The application decides applicability and child-specific questions. [SSVF rules](../SSVF.md) are an explicitly tested sandbox form snapshot, not a general branching engine.
+
+## Current Living Situation dates
+
+Every contact row starts at the selected client's program entry. Its information date is the contact date, and its end may remain null or empty. Later contacts retain earlier rows without closing or replacing them. This differs from changing income/benefit verification intervals. See [contact recording](current-living-situation.md) for date input, optional Verified By, and retry contracts.

package/docs/development.md

@@ -0,0 +1,81 @@
+# Develop and release the SDK
+
+[Documentation index](README.md) · [Agent guide](../AGENTS.md)
+
+Run commands in `packages/wellsky-sdk`. Node 22 or newer is required. Local tests use synthetic data and do not authenticate to HMIS. The repository contains the SDK and its supporting documentation and tests.
+
+## Fake client and validation
+
+```ts
+import { createFakeWellSkyClient } from '@choiceapps/communityservices-sdk/testing';
+const fake = createFakeWellSkyClient();
+fake.fake.set('GET /clients/{clientId}', {
+  kind: 'reply', body: [{ clientId }],
+});
+```
+
+The fake implements the same V3 client and runs through the real transport and validation. Script replies, network errors, custom handlers, and commit-then-error behavior. No request falls through to a real network. Use synthetic data only; the fake intentionally exposes its scripted calls/state to tests.
+
+```sh
+npm ci
+npm run generate
+npm run generate:check
+npm run docs:check
+npm test
+npm run package:check
+```
+
+`npm run generate` rewrites generated files from the pinned contracts. Use `generate:check` for a read-only consistency check. Run `npm run specs:check` separately when checking upstream drift: it contacts the public WellSky Swagger endpoints, compares them to the pinned snapshots, and does not update files or authenticate to HMIS. A mismatch requires review before regeneration.
+
+## Include browser fixtures
+
+Without `WELLSKY_TEST_CHROME`, the suite skips tests that require a real browser. Install a compatible Chrome or Chromium executable, then set its absolute path when running the package check. For example, on macOS:
+
+```sh
+WELLSKY_TEST_CHROME='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' npm run package:check
+```
+
+These browser tests use local synthetic forms and intercepted responses, not a live HMIS login. Check the test summary for skipped tests before describing a run as complete browser coverage. GitLab's `verify:browser` job installs Chromium and its system dependencies, sets `WELLSKY_TEST_CHROME`, and runs the package check. The separate Node 22 and 24 jobs still check the package without a browser.
+
+The local suite covers every versioned HTTP operation, metadata, tenant/auth controls, concurrency, bulk execution, cancellation, verification, and end-dating. Package checks install the tarball and its optional Playwright Core peer in a clean consumer, check shipped documentation links and runtime-export coverage, compare installed examples to source, compile every example against installed declarations, and execute offline example checks with network access blocked. Installed client-creation, attachment-retry, and session-authentication regressions run separately. ESM and CommonJS REST declarations and imports are also checked, along with ESM browser consumer types. Any live verification requires an explicitly authorized tenant and operation. Preserve sanitized conclusions, reproduction dates, and limitations in the relevant SDK guide or vendor report. Keep raw captures, credentials, and client data outside the repository and package; do not replay historical fixture setup.
+
+## GitLab CI releases
+
+The root `.gitlab-ci.yml` runs verification on Node 22 and 24 and a separate Chromium fixture job on Node 22. Publishing requires all three jobs and uses the tested Node 22 tarball, GitLab's `CI_JOB_TOKEN`, and the current project's npm registry. The publish job checks version agreement, verifies registry integrity, and installs the published package and optional browser peer in a clean directory. It runs the shared installed-consumer checks there, including every shipped example, public entry points, type checks, and retry regressions.
+
+Release either by pushing a matching version tag (for example, `v0.1.0`), or by running a pipeline on the default branch with the matching `RELEASE_VERSION` (for example, `0.1.0`). Change `package.json` and its lockfile first for future versions. Never reuse a published version. No long-lived publishing token is required.
+
+These are release procedures, not evidence that the current working tree has been published. A local `package:check` creates a tarball but does not upload it. Verify the actual release pipeline, registry version, and installed artifact before claiming registry availability.
+
+See [CHANGELOG.md](../CHANGELOG.md) for compatibility changes. This package is an independent integration and has no WellSky endorsement.
+
+## GitHub mirror and public npm releases
+
+GitLab is the source of truth. Its push mirror copies branches and tags to `nmbgeek/communityservices-sdk` on GitHub. Commit changes, including `.github/workflows/publish.yml`, in GitLab. Do not edit the mirror or push independent commits there.
+
+The GitHub workflow checks Node 22, Node 24, and Chromium using synthetic fixtures. A matching `v<version>` tag publishes the tested Chromium-job tarball as public `@choiceapps/communityservices-sdk`. Main pushes only verify. To recover an interrupted release, run `publish.yml` manually against the existing version tag. An identical existing artifact is verified without republishing; a different artifact under the same version fails. npm versions cannot be replaced.
+
+Configure the npm package's trusted publisher for GitHub owner `nmbgeek`, repository `communityservices-sdk`, workflow filename `publish.yml`, with publishing allowed and no environment name. The workflow runs on GitHub-hosted runners, grants `id-token: write` only to the publish job, and uses npm 11.19.1. It needs no `NPM_TOKEN` or `NODE_AUTH_TOKEN` secret. The package's repository URL points to this public mirror so npm can attach provenance. GitLab publication remains a separate job using `CI_JOB_TOKEN`.
+
+An npm owner with 2FA must complete the initial package setup before OIDC publishing can work. For an existing package, configure it in npm settings or with an authenticated npm CLI:
+
+```sh
+npm trust github @choiceapps/communityservices-sdk --repo nmbgeek/communityservices-sdk --file publish.yml --allow-publish --yes
+```
+
+See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) for initial setup requirements. This workflow does not bootstrap credentials or create a placeholder release. Verify the workflow result, registry integrity, provenance, and installed-consumer checks before calling a release available.
+
+## License
+
+The SDK is Apache-2.0, copyright 2026 Choice Technology Solutions, LLC. Keep the repository and package copies of `LICENSE` and `NOTICE` identical. Package verification checks that both files ship unchanged.
+
+## Tenant parity regression checks
+
+The synthetic workflow and browser fixtures accept `WELLSKY_TEST_TENANT` to select the fixture tenant. Run the same package checks with two distinct tenant values:
+
+```sh
+WELLSKY_TEST_TENANT=tenant-a npm run package:check
+WELLSKY_TEST_TENANT=tenant-b npm run package:check
+```
+
+Set `WELLSKY_TEST_CHROME` to the local Chrome executable to include the browser fixtures. These checks intercept browser traffic and use synthetic records; selecting another fixture tenant here does not access the live tenant. The suite also checks shared-journal isolation, neutral public exports, cross-tenant rejection, and explicit tenant types for login and custom need adapters.