@choiceapps/communityservices-sdk 0.1.0

package/docs/vendor-issues/enrollment-effective-date-column.md

@@ -0,0 +1,112 @@
+# Grouped enrollment reads fail in V2 and V3
+
+Status: reproduced in a sandbox tenant on October 24, 2026, with Client API V2 and V3. Other tenant deployments were not tested. The comparison used existing synthetic records and made no client, household, enrollment, assessment, or shelter writes.
+
+## Summary for WellSky
+
+Both versions return HTTP 400 with the same missing-column error for grouped enrollment reads. All 16 tested grouped complete-enrollment requests per version failed. None of the six individual enrollments produced this particular error, although one had a separate complete-read failure.
+
+The strongest comparison is within client 575: direct reads of its individual enrollments succeed, its grouped enrollment fails, and pagination can return the individual rows successfully. This points toward processing a grouped enrollment rather than the client simply belonging to a household. The underlying SQL/view defect remains unconfirmed.
+
+## Request contract and exact error
+
+```http
+GET /client-api-prod/enrollments/{clientId}?perPage=100&startPage=1&total_count=true
+GET /client-api-prod/enrollments/complete/{enrollmentId}
+Host: csclientapi.wellsky.com
+Accept: application/json
+x-tenant: your-tenant
+x-version: 2.0
+Authorization: Bearer <redacted>
+```
+
+Repeat each request with `x-version: 3.0`, keeping the other inputs unchanged. The server returned HTTP 400 and this JSON string value:
+
+```text
+42703: column v.entry_date_effective does not exist
+
+POSITION: 116
+```
+
+Response headers advertised `api-supported-versions: 3.0` and `api-deprecated-versions: 2.0`. V2 still accepted requests; switching to it did not avoid the defect. A provider-complete control request returned HTTP 200 in each version with the same credentials.
+
+## Method and results
+
+The main comparison ran at 15:56 UTC, 11:56 a.m. Eastern, on October 24. Follow-up pagination and filter checks ran through 15:57:01 UTC. Requests used raw HTTP, bypassing SDK response handling, with the same bearer token within each comparison run. Only `x-version` changed between each pair.
+
+Fresh, counted GWT reads established 22 active enrollment records across the synthetic cohort. Six had a null `groupId`; 16 had a non-null group ID across eight household groups. Here, “individual” describes the enrollment's grouping, not whether the client belongs to a household elsewhere.
+
+Results below are counts **per API version**. V2 and V3 had identical outcomes.
+
+| Read and cohort | Tested per version | V2 | V3 |
+| --- | ---: | --- | --- |
+| Client list, individual enrollments only | 4 clients | 4 HTTP 200 | 4 HTTP 200 |
+| Client list, grouped enrollments only | 13 clients | 13 HTTP 400, missing column | 13 HTTP 400, missing column |
+| Client list, individual and grouped enrollments mixed | 1 client | HTTP 400, missing column | HTTP 400, missing column |
+| Complete individual enrollment | 6 enrollments | 5 HTTP 200; 1 different HTTP 400 | 5 HTTP 200; 1 different HTTP 400 |
+| Complete grouped enrollment | 16 enrollments | 16 HTTP 400, missing column | 16 HTTP 400, missing column |
+| Client list, no active enrollments | 1 client | HTTP 404 | HTTP 404 |
+
+The grouped cohort included HUD and Basic enrollments, household heads and other members, open and exited records, and RRH, TH, and ES programs. Earlier capture established the error after ordinary UI saves and after RPC replay, including before interim creation. It is not confined to shelter-created enrollments or interims.
+
+## Concrete reproduction pairs
+
+These identifiers refer only to existing synthetic sandbox fixtures. They contain no client demographics.
+
+| Client | Enrollment | Group ID | Result in both versions |
+| --- | --- | --- | --- |
+| 577 | 679 | null | List and complete read succeed |
+| 581 | 682 | 682 | List and complete read fail with missing column |
+| 582 | 684 | 682 | Other household member also fails |
+| 575 | 677, 678 | null | Both direct complete reads succeed |
+| 575 | 725 | 725 | Direct complete read fails; full client list also fails |
+| 644, 645 | 729, 730 | 729 | Both exited TH enrollments fail |
+| 642, 643 | 731, 732 | 731 | Both open nightly ES enrollments fail |
+
+Enrollments 679 and 682 use the same provider, 16951, the same HUD type, and the same entry instant, `2026-10-18T16:00:00Z`. Their different grouping provides a closer comparison than records from unrelated programs. Both were confirmed present by fresh GWT reads.
+
+To reproduce without changing records:
+
+1. Call `/enrollments/577` and `/enrollments/complete/679` with `x-version: 2.0`, then `3.0`. Expect HTTP 200 for these fixtures.
+2. Call `/enrollments/581` and `/enrollments/complete/682` with each version. Observe HTTP 400 and the missing-column message.
+3. Compare `/enrollments/complete/678` and `/enrollments/complete/725`, both belonging to client 575. The individual enrollment succeeds; the grouped enrollment fails.
+4. Compare the client-575 pagination cases below. Preserve the response status, timestamp, version, and any support correlation ID. Do not include credentials in a ticket.
+
+## Pagination and query isolation
+
+These follow-up results were identical in V2 and V3:
+
+| Request | Result |
+| --- | --- |
+| `/enrollments/575?perPage=1&startPage=1&total_count=true` | HTTP 400, missing column |
+| Same request with `startPage=2` | HTTP 200, enrollment 678, null group, total count 3 |
+| Same request with `startPage=3` | HTTP 200, enrollment 677, null group, total count 3 |
+| `/enrollments/575?perPage=100&startPage=1&total_count=false` | HTTP 400, missing column |
+| `/enrollments/577` with no query parameters | HTTP 200 |
+| `/enrollments/581` with no query parameters | HTTP 400, missing column |
+| Client 575, normal counted request plus `$filter=groupId eq null` | HTTP 400, missing column |
+
+The only other active enrollment for client 575 was grouped enrollment 725. Successful individual pages can still report a total count of three, so the evidence points toward processing the returned grouped row rather than calculating the collection count. The failure does not require explicit pagination parameters.
+
+The filter did not produce a usable response. This test cannot establish whether the server ignored the filter, applied it after the failing query, or handled it another way. Neither filtering nor skipping failed pages is a verified workaround. Page order can change, and skipping a page would omit existing enrollments.
+
+## Separate observations
+
+- Individual enrollment 680 for client 579 returned HTTP 400, `Non-static method requires a target.`, in both versions. Its client enrollment list succeeded. This is a separate complete-read failure, not the missing-column error. The [follow-up investigation](enrollment-complete-target-error.md) isolated missing DOB information through four new synthetic enrollments: DOB alone or either tested unknown/declined quality response cleared the error. It also documents working alternate reads. A historical observation of that message on enrollment 677 did not reproduce in this run; 677 returned HTTP 200 in both versions.
+- Client 619 had zero active enrollments in the counted GWT read, and its REST enrollment collection returned HTTP 404 in both versions. This is an additional empty-collection behavior, separate from both errors above. It should not be interpreted as proof that the client is missing.
+
+## Impact and SDK workaround
+
+Applications cannot use these REST endpoints to read the affected household enrollments. A mixed client's full list can fail even when its individual enrollments are readable. V2 is not a fallback. Returning only successful pages would hide household participation and could undermine duplicate protection.
+
+The shelter and enrollment workflows use authenticated, current UI/GWT reads and verify complete row counts. A failed REST read must never trigger a replacement enrollment write. The records remained present in GWT and the UI; this test found a read failure, not evidence of failed enrollment creation.
+
+## Questions for WellSky
+
+- Which grouped-enrollment query or projection references `v.entry_date_effective` at SQL position 116? Is the alias or column incorrect, or is the deployed sandbox view/schema out of sync with the API?
+- Do V2 and V3 share this grouped-record query? The tested versions returned identical errors while individual records in the same client remained readable.
+- Why does the null-group filter fail to isolate readable individual records? Is `$filter` supported on this endpoint before grouped-record expansion?
+- Can a database schema failure return a server-error status with a support correlation ID rather than HTTP 400?
+- Can the separate complete-read target error and empty-enrollment 404 convention be tracked independently?
+
+Private evidence retains sanitized response statuses, timestamps, returned IDs, body hashes, and response-header metadata. No credentials, raw authenticated GWT payloads, or client demographics are included in this report. The comparison was observational; it did not add or remove household membership to prove causality, inspect the database, or test production.

package/docs/vendor-issues/household-head-validation.md

@@ -0,0 +1,26 @@
+# Clarify household head coverage validation
+
+[WellSky feedback](README.md) · [Enrollment contracts](../enrollments.md)
+
+Status: a validation-policy question based on writes reproduced in a sandbox tenant on October 23, 2026. This report does not establish a violation of WellSky's documented rules or a universal program requirement.
+
+## Observed behavior
+
+A grouped household enrollment accepted an exit for the original head while a child remained enrolled. A subsequent member addition also succeeded after the original adults had exited, using an enrolled child as the operation's anchor. Stored enrollment dates and membership were confirmed through UI/GWT readback.
+
+Those writes demonstrated transport behavior but produced invalid data under the SDK's required enrollment contract: the original head must remain enrolled through every member's exit. They are not supported workflow examples. The historical fixture was not repaired as part of the later validation change.
+
+## SDK handling and controls
+
+The SDK rejects a head exit that would leave another member enrolled afterward, rejects existing groups without the required head coverage, and does not implement retroactive head replacement. Choosing a non-head anchor does not relax those rules.
+
+A separate October 23 acceptance run confirmed that an early head-only exit was rejected before any REST or GWT mutation. Valid controls then exited other members on separate dates and the original head last. A second household exited all selected members together. Stored dates, original head identity, and selected exit subgroups were verified; fresh-helper retries produced zero additional record writes.
+
+## Questions for WellSky
+
+- Which rules govern head coverage across linked enrollment intervals, and do they vary by program or configuration?
+- Should the UI and server reject an exit or member addition that leaves members without an enrolled head? If that state is supported, what head-transfer workflow and history model should integrations use?
+- Is there a supported validation or repair endpoint for existing groups with inconsistent head coverage?
+- Can the public API expose the authoritative head identity and effective membership intervals needed to check these rules before a write?
+
+Discuss the intended policy before classifying this as a server defect. Any new reproduction should use explicitly authorized synthetic records and a planned cleanup; do not recreate the invalid historical sequence in an existing household.

package/docs/vendor-issues/write-contracts.md

@@ -0,0 +1,51 @@
+# Write outcomes and update contracts need clarification
+
+[WellSky feedback](README.md) · [Recovery](../troubleshooting.md)
+
+Status: reproduced observations from a sandbox tenant on October 22–24, 2026. Some indicate a failure; others need a contract clarification before they can be called defects. No vendor acknowledgement or resolution is recorded here.
+
+## A service persisted despite HTTP 400
+
+During the October 24 run, a fixture had veteran status `Yes` rather than the UI's accepted `Yes (HUD)`. The service create returned HTTP 400 with `Requested value 'ENHANCEDYESNO_YES_NONHUD' was not found.` A subsequent service list also failed with that error.
+
+After an explicit correction of the fixture's veteran status, a counted list showed the service already existed. There had been exactly one POST to `/services/create`. The SDK reconciled the original service key and journal, then completed the associated need without creating another service.
+
+The SDK's veteran-label validation was subsequently corrected. That client-side fix reduces exposure to the trigger but does not establish rollback semantics for server errors. The observation proves persistence despite the failed response; it does not establish the server's internal transaction sequence.
+
+**Ask WellSky:** Can validation occur before commit, or can an error after commit return the created identity and commit status? What recovery contract should callers use after a failed create? Is there a supported idempotency key or external-reference lookup?
+
+Treat this as a high-priority integration issue because retrying a failed create can duplicate records. The SDK retains the attempted stage and reconciles before any further mutation.
+
+## Omitting SSN from a client update cleared it
+
+A raw middle-name-only update cleared the existing synthetic SSN when `socSecNo` was omitted. Other observed fields remained. The profile helper now reads and preserves all nine supported REST Client Record fields when making a change, then verifies the stored result.
+
+The October 23 reproduction compared the existing Client Record with a raw REST update containing only the intended middle-name change. The later helper control preserved SSN and Sex while changing the middle name, with REST and UI readback. The observation is specific to the tested payload; it does not establish omission semantics for every field.
+
+**Ask WellSky:** Is this endpoint a replacement operation or a partial update? What do omission, null, and empty string mean for each field? If clearing on omission is intended, can the contract require or clearly document the preserved fields?
+
+This is an observed data-loss risk, but whether the server behavior violates the intended update contract remains a question. Do not assume PATCH semantics from a method named update.
+
+## Goal updates require a field marked optional
+
+The tested server rejected a goal update without `clientId`, although the pinned Swagger model marks that field optional. The SDK supplies and verifies the owning client.
+
+For a support reproduction, compare otherwise identical updates to an authorized synthetic goal with and without its owning `clientId`. Record the validation response and stored values after each attempt. Keep this schema mismatch separate from the nested relationship question below.
+
+**Ask WellSky:** Is `clientId` always required for updates? If so, can the schema and validation message reflect that requirement?
+
+Goal responses also included unrelated `households` rows when the inspected goal had no household association. This is a separate response-integrity question. **Ask:** What relationship does that nested collection represent, and should it be scoped to the requested goal or client? The SDK does not use it to select write targets. The observation does not establish cross-tenant exposure.
+
+## Filtering and response shapes vary by operation
+
+| Observation | Current handling | Question for WellSky |
+| --- | --- | --- |
+| Counted client candidate queries required `first_name`, `last_name`, and `soc_sec_no`; simplified camel-case forms could fail | Uses the verified field names and bounds candidate counts | Can accepted filter fields and endpoint-specific syntax be documented? |
+| Counted Client Notes accepted `query=client_id eq …`; `$filter` failed HTTP 400 | Uses the operation's native query form | Is this intentional, and can the contract distinguish it from other collection endpoints? |
+| ROI `$filter=client_id eq …` returned an empty success while the documented `query` form returned 404 in the checked case | Preserves operation-specific evidence; does not treat every 404 as empty | Which query form and no-results response are supported? |
+| Complete-service reads returned an array despite the documented object shape | Normalizes supported collection shapes while preserving HTTP errors | Can the schema or response be aligned? |
+| Follow-up fields were not available in the REST case-plan read model | Does not expose unverifiable follow-up writes through the durable helper | Which endpoint provides authoritative readback? |
+
+These observations should be submitted with the exact API version, endpoint, sanitized request, and response shape from an authorized reproduction. They are not evidence that every endpoint supports the same query syntax or update behavior.
+
+The mobile configuration routes are described by Swagger as internal WellSky endpoints. An HTTP 401 from a service account on those routes alone is not evidence of a public API authentication defect or a need for another SDK login flow.

package/examples/README.md

@@ -0,0 +1,41 @@
+# Packaged examples
+
+[Package overview](../README.md) · [Documentation index](../docs/README.md)
+
+Every file here ships with the package and imports the public `@choiceapps/communityservices-sdk` entry points. No example loads `.env`, credentials, or a live session on import.
+
+| File | Purpose | Execution |
+| --- | --- | --- |
+| [shelter-inventory.mts](shelter-inventory.mts) | Discover unit lists and report beds, occupants, holds, overflow, and known or unknown vacancies | Exported functions; caller supplies a dedicated authenticated application page; each list is a separate snapshot |
+| [shelters.mts](shelters.mts) | Shelter mode discovery, household check-in/checkout, durable source keys | Exported functions; caller supplies beds, dates, assessment preparation, UI, and store; exercised against installed package |
+| [quickstart.mjs](quickstart.mjs) | Read a synthetic client through the real SDK transport | Run directly; no network or credentials |
+| [durable-records.mts](durable-records.mts) | Client source mapping, household creation/later members, case plans, keyed goal notes, bulk recovery decisions | Exported functions; application supplies API, store, UI ports, and inputs |
+| [usage.ts](usage.ts) | REST clients, pagination, generic service operations | Exported functions; raw writes have no durable journal |
+| [verification-snapshot.ts](verification-snapshot.ts) | Read assessment records effective at enrollment | Exported function; caller supplies assessment context |
+| [program-discovery.ts](program-discovery.ts) | Program and VA-entry assessment discovery | Exported function; authenticated page required |
+| [enrollment-workflow.mts](enrollment-workflow.mts) | Single entry and interim assessment plans | Exported function; caller supplies plans and dependencies |
+| [household-enrollment-workflow.mts](household-enrollment-workflow.mts) | Per-member enrollment and review | Existing household and per-member answer plans required |
+| [household-lifecycle-workflow.mts](household-lifecycle-workflow.mts) | Selected exits and a later child entry | Household membership precedes program attachment |
+| [household-exit-workflow.mts](household-exit-workflow.mts) | Household exit with destination details | Explicit exit dates and per-member plans required |
+| [gwt-enrollment-session.ts](gwt-enrollment-session.ts) | Custom GWT session and journal integration | Caller supplies all target IDs and dates |
+| [gwt-file-store.mjs](gwt-file-store.mjs) | Compatibility re-export of the durable file store | Safe to import |
+
+After installation, run the offline example from your application directory:
+
+```sh
+node node_modules/@choiceapps/communityservices-sdk/examples/quickstart.mjs
+```
+
+To use a TypeScript integration example, copy it into your application's source tree and compile with TypeScript's NodeNext module resolution. Install `playwright-core` for the browser type contracts and `@types/node` as a development dependency when compiling them in your application. Keep ESM `.mts` examples as `.mts` or use an ESM package. The examples are ordinary packaged files, not additional package export paths.
+
+## What the package check proves
+
+`npm run package:check` in the SDK checkout packs and installs the tarball in a temporary consumer. It compares every installed example with the source file, copies the installed examples outside the package, compiles all TypeScript examples against installed declarations, and imports every compiled example with global network access blocked. The offline quickstart executes its assertions.
+
+The durable-record example also runs against the installed SDK's fake REST transport and a real temporary file journal. Checks cover stable source IDs, household head guards, later members, Client Notes/goals/actions, same-key retries, explicit source-key conflict, and structured service recovery decisions. Synthetic UI ports are used where needed. This verifies package behavior and example integration; it does not log in, click a real UI, or replace the separate live sandbox acceptance tests.
+
+Installed checks also run the client-creation, attachment-retry, session-authentication, independent-needs, and GWT mapped-reader regression suites against the tarball. Browser example compilation uses `skipLibCheck` for peer declarations while still checking example code against the installed SDK types. Separate consumer checks reject invalid veteran-status literals and verify the exported attachment-conflict contract.
+
+`independent-needs.mts` discovers tenant-wide service types and separate provider quicklists, records explicit PIT needs, and maps a chosen taxonomy type to the service recorder. Dependencies, event keys, provider, and selections are supplied by the application.
+
+[current-living-situation.mts](current-living-situation.mts) records application-supplied outreach or night-by-night shelter contact events with distinct durable keys and optional recording-program picklist selections. It compiles and imports against the installed package without opening a live session.

package/examples/current-living-situation.mts

@@ -0,0 +1,27 @@
+import type {WellSkyClient, PicklistSelector} from '@choiceapps/communityservices-sdk';
+import {createCurrentLivingSituationRecorder, type CurrentLivingSituationFields, type UiMutationStore} from '@choiceapps/communityservices-sdk/browser';
+
+/** Both outreach and night-by-night shelter callers supply actual contact events. */
+export async function recordMeaningfulContacts(
+    api: WellSkyClient,
+    store: UiMutationStore,
+    fields: CurrentLivingSituationFields,
+    target: {clientId: number; enrollmentId: number; assessmentCode: string},
+    contacts: readonly {eventKey: string; informationDate: string; livingSituation: PicklistSelector; recordingProgramOption?: PicklistSelector}[],
+) {
+    const recorder = createCurrentLivingSituationRecorder({api, store, fields});
+    const receipts = [];
+    for (const contact of contacts) {
+        receipts.push(await recorder.record({
+            ...target,
+            key: contact.eventKey,
+            informationDate: contact.informationDate,
+            livingSituation: {option: contact.livingSituation},
+            endDate: null,
+            ...(contact.recordingProgramOption ? {verifiedBy: {option: contact.recordingProgramOption}} : {}),
+        }));
+    }
+    // Each distinct event keeps its own row, even when date and answers match.
+    // Replay these same event keys with the same store to verify without another save.
+    return receipts;
+}

package/examples/durable-records.mts

@@ -0,0 +1,78 @@
+import type {WellSkyClient} from '@choiceapps/communityservices-sdk';
+import {
+	createClientCreator, createHouseholds, createCasePlans,
+	type UiMutationStore, type HouseholdUi, type CasePlanUi,
+	type ClientCreationInput, type HouseholdMemberInput,
+	type NoteValues, type GoalValues, type ActionValues,
+	type ClientWorkflows, type ServiceRecorder, type ServiceRecordInput,
+} from '@choiceapps/communityservices-sdk/browser';
+
+/** Application-owned dependencies. Use one persistent store across restarts and callers. */
+export function durableRecords(api:WellSkyClient, store:UiMutationStore, ui:{households:HouseholdUi;casePlans:CasePlanUi}) {
+	return {
+		clients:createClientCreator({api,store}),
+		households:createHouseholds({api,store,ui:ui.households}),
+		casePlans:createCasePlans({api,store,ui:ui.casePlans}),
+	};
+}
+export type DurableRecords = ReturnType<typeof durableRecords>;
+
+/** These source IDs belong to your upstream records. Never regenerate them for a retry. */
+export async function createPeopleAndHousehold(records:DurableRecords, input:{
+	householdSourceId:string;householdType:string;
+	head:ClientCreationInput;member:ClientCreationInput;
+	joinedAt:string;memberRelationship:string;
+}) {
+	const head=await records.clients.create(input.head);
+	const member=await records.clients.create(input.member);
+	const household=await records.households.create({
+		key:input.householdSourceId,headClientId:head.clientId,householdType:input.householdType,
+		members:[
+			{clientId:head.clientId,relationship:'Self',dateJoined:input.joinedAt},
+			{clientId:member.clientId,relationship:input.memberRelationship,dateJoined:input.joinedAt},
+		],
+	});
+	return {head,member,household};
+}
+
+/** This adds household membership. Attach the person to a program separately. */
+export function addLaterMember(records:DurableRecords, input:{
+	key:string;householdId:number;headClientId:number;householdType:string;member:HouseholdMemberInput;
+}) {
+	const {member,...context}=input;
+	return records.households.addMembers({...context,members:[member]});
+}
+
+/** No automatic recovery by name or DOB. Call only after verifying the create receipt externally. */
+export function resolveMissingClientReceipt(records:DurableRecords, original:ClientCreationInput, verifiedCreatedClientId:number) {
+	return records.clients.resolveCreated({...original,clientId:verifiedCreatedClientId});
+}
+
+/** Separate keys allow a partially completed sequence to resume. This is not atomic. */
+export async function createCasePlan(records:DurableRecords, input:{
+	clientId:number;sourceId:string;note:NoteValues;goal:GoalValues;action:ActionValues;
+}) {
+	const {clientId,sourceId}=input;
+	const note=await records.casePlans.createClientNote({key:`${sourceId}:note`,clientId,values:input.note});
+	const goal=await records.casePlans.createGoal({key:`${sourceId}:goal`,clientId,values:input.goal});
+	const action=await records.casePlans.createActionStep({key:`${sourceId}:action`,clientId,goalId:goal.recordId,values:input.action});
+	return {note,goal,action};
+}
+
+/** Require a source key even though the SDK keeps legacy unkeyed calls compatible. */
+export function writeGoalProgress(workflows:ClientWorkflows, input:Parameters<ClientWorkflows['createCaseNote']>[0]&{key:string}) {
+	return workflows.createCaseNote(input);
+}
+
+/** Return diagnostics to the application. This example never retries a raw write. */
+export async function recordServiceBatch(recorder:ServiceRecorder, rows:ServiceRecordInput[]) {
+	const batch=await recorder.recordBulk(rows);
+	const failures=batch.results.flatMap(row=>{
+		if(row.outcome!=='rejected')return [];
+		const nextAction=row.error.code==='SESSION_INTERRUPTED'
+			? row.error.reauthenticated?'reconcile-same-key':'authenticate-then-reconcile'
+			: 'review-saved-state';
+		return [{key:row.key,message:row.message,error:row.error,nextAction}];
+	});
+	return {...batch,failures};
+}

package/examples/enrollment-workflow.mts

@@ -0,0 +1,46 @@
+import {
+  createEnrollmentWorkflow,
+  type EnrollmentAssessmentPlan,
+  type EnrollmentWorkflowDiscovery,
+  type EnrollmentWorkflowResult,
+  type EnrollmentWorkflowOptions,
+} from '@choiceapps/communityservices-sdk/browser';
+
+/** Call with a REST client, authenticated discovery/enrollment adapters,
+ * a birthDates adapter for DOB plans, and the same durable store on every run. This example does not log in or run itself. */
+export async function enrollAndReview(
+  dependencies:EnrollmentWorkflowOptions,
+  input:{
+    clientId:number;
+    providerId:number;
+    type:'HUD'|'VA';
+    /** Stable application record ID, not a new UUID on each retry. */
+    sourceId:string;
+    entryDate:string;
+    reviewDate:string;
+    buildEntryPlan:(catalog:EnrollmentWorkflowDiscovery)=>EnrollmentAssessmentPlan;
+    buildInterimPlan:(entry:EnrollmentWorkflowResult,catalog:EnrollmentWorkflowDiscovery)=>EnrollmentAssessmentPlan;
+  },
+) {
+  const workflow=createEnrollmentWorkflow(dependencies);
+  const context={clientId:input.clientId,providerId:input.providerId,type:input.type,entryDate:input.entryDate};
+  const catalog=await workflow.discover(context);
+  // Render catalog.entry/interim.definition in the application's intake form.
+  // Plans must explicitly cover applicable fields and all required verification types.
+  const enrollmentKey=`${input.sourceId}:entry`;
+  const entry=await workflow.createEnrollment({
+    ...context,key:enrollmentKey,assessment:input.buildEntryPlan(catalog),
+  });
+  // Use entry.recordsetIds and the discovered startDateField/endDateField names
+  // when ending a changed verification row. Carry forward
+  // unchanged groups instead of adding copies. End the old row on the prior day.
+  // On a rejected operation, call workflow.getStatus({clientId, key}) with that
+  // operation's original key. Inspect the attempted steps before retrying the
+  // same intent. Never remove the journal or generate a fresh key to bypass it.
+  const interim=await workflow.createInterim({
+    key:`${input.sourceId}:interim:${input.reviewDate}`,enrollmentKey,
+    clientId:input.clientId,reviewDate:input.reviewDate,
+    assessment:input.buildInterimPlan(entry,catalog),
+  });
+  return {entry,interim};
+}

package/examples/gwt-enrollment-session.ts

@@ -0,0 +1,17 @@
+import { GwtEnrollmentHelpers, type GwtEnrollmentSession, type GwtMutationStore } from "@choiceapps/communityservices-sdk";
+
+/** Supply a trusted authenticated browser adapter and a shared durable journal.
+ * prepare() must capture/serialize inside this call and prevent the original UI request from being sent.
+ * readEnrollment() must return complete fresh GWT state, including every review and household member.
+ * See docs/browser-session.md for the adapter contract. */
+export async function updateSyntheticHousehold(session: GwtEnrollmentSession, store: GwtMutationStore, input: {tenant:string;moduleBaseUrl:string;clientId:number;enrollmentId:number;memberClientIds:number[];reviewDate:string}) {
+  const helpers = new GwtEnrollmentHelpers({
+    tenant: input.tenant,
+    moduleBaseUrl: input.moduleBaseUrl,
+    session,
+    store,
+  });
+  const membership = await helpers.addHouseholdMembers({ clientId: input.clientId, enrollmentId: input.enrollmentId, memberClientIds: input.memberClientIds });
+  const interim = await helpers.createInterimUpdate({ clientId: input.clientId, enrollmentId: input.enrollmentId, clientIds: [input.clientId, ...input.memberClientIds], reviewDate: input.reviewDate });
+  return { membership, interim }; // Reuse the same target, dates and journal when retrying.
+}

package/examples/gwt-file-store.mjs

@@ -0,0 +1,2 @@
+// Compatibility import for existing repository integrations.
+export {createFileGwtMutationStore} from '@choiceapps/communityservices-sdk/browser';

package/examples/household-enrollment-workflow.mts

@@ -0,0 +1,43 @@
+import type {WellSkyClient} from '@choiceapps/communityservices-sdk';
+import {
+  createDateOfBirth,createDateOfBirthUi,createEnrollmentWorkflow,createProgramDiscovery,
+  type EnrollmentAssessmentPlan,type EnrollmentWorkflowDiscovery,
+  type HouseholdEnrollmentResult,type EnrollmentReader,type UiMutationStore,
+} from '@choiceapps/communityservices-sdk/browser';
+import type {GwtEnrollmentHelpers} from '@choiceapps/communityservices-sdk';
+import type {Page} from 'playwright-core';
+
+/** The application owns answers and applicability for each person. Reuse the same
+ * source keys and durable store when resuming after an interruption. */
+export async function enrollHouseholdAndReview(options:{
+  api:WellSkyClient;
+  page:Page;
+  helpers:GwtEnrollmentHelpers;
+  enrollmentSession:EnrollmentReader;
+  store:UiMutationStore;
+  sourceEnrollmentId:string;
+  sourceReviewId:string;
+  householdId:number;
+  headClientId:number;
+  clientIds:number[];
+  providerId:number;
+  entryDate:string;
+  reviewDate:string;
+  buildEntryPlan:(clientId:number,definition:EnrollmentWorkflowDiscovery)=>EnrollmentAssessmentPlan;
+  buildInterimPlan:(clientId:number,definition:EnrollmentWorkflowDiscovery,entry:HouseholdEnrollmentResult)=>EnrollmentAssessmentPlan;
+}){
+  const workflow=createEnrollmentWorkflow({...options,birthDates:createDateOfBirth({api:options.api,ui:createDateOfBirthUi({page:options.page}),store:options.store}),discovery:createProgramDiscovery({page:options.page})});
+  const definitions=new Map<number,EnrollmentWorkflowDiscovery>();
+  for(const clientId of options.clientIds)definitions.set(clientId,await workflow.discover({clientId,providerId:options.providerId,type:'HUD',entryDate:options.entryDate}));
+  const definitionFor=(clientId:number)=>{const value=definitions.get(clientId);if(!value)throw Error('Member definition missing');return value;};
+  const entry=await workflow.createHouseholdEnrollment({
+    key:options.sourceEnrollmentId,householdId:options.householdId,headClientId:options.headClientId,
+    providerId:options.providerId,type:'HUD',entryDate:options.entryDate,
+    members:options.clientIds.map(clientId=>({clientId,assessment:options.buildEntryPlan(clientId,definitionFor(clientId))})),
+  });
+  const interim=await workflow.createHouseholdInterim({
+    key:options.sourceReviewId,enrollmentKey:options.sourceEnrollmentId,headClientId:options.headClientId,reviewDate:options.reviewDate,
+    members:options.clientIds.map(clientId=>({clientId,assessment:options.buildInterimPlan(clientId,definitionFor(clientId),entry)})),
+  });
+  return {entry,interim};
+}

package/examples/household-exit-workflow.mts

@@ -0,0 +1,35 @@
+import type {WellSkyClient,GwtEnrollmentHelpers} from '@choiceapps/communityservices-sdk';
+import type {Page} from 'playwright-core';
+import {
+  createDateOfBirth,createDateOfBirthUi,createEnrollmentWorkflow,createProgramDiscovery,createHouseholdExitUi,
+  type EnrollmentReader,type UiMutationStore,type ExitWorkflowDiscovery,
+  type EnrollmentAssessmentPlan,type HouseholdExitDetailInput,
+} from '@choiceapps/communityservices-sdk/browser';
+
+/** Continue a verified household enrollment in the same durable workflow store.
+ * Application policy chooses each member's answers and the records that changed. */
+export async function exitHousehold(options:HouseholdExitDetailInput&{
+  api:WellSkyClient;page:Page;helpers:GwtEnrollmentHelpers;
+  enrollmentSession:EnrollmentReader;store:UiMutationStore;
+  sourceExitId:string;sourceEnrollmentId:string;headClientId:number;
+  clientIds:number[];providerId:number;exitDate:string;
+  destination:string;reasonForLeaving:string;
+  buildExitPlan:(clientId:number,definition:ExitWorkflowDiscovery)=>EnrollmentAssessmentPlan;
+}){
+  const workflow=createEnrollmentWorkflow({
+    ...options,birthDates:createDateOfBirth({api:options.api,ui:createDateOfBirthUi({page:options.page}),store:options.store}),discovery:createProgramDiscovery({page:options.page}),
+    exitUi:createHouseholdExitUi({page:options.page}),
+  });
+  const members=[];
+  for(const clientId of options.clientIds){
+    const definition=await workflow.discoverExit({clientId,providerId:options.providerId,type:'HUD',entryDate:options.exitDate});
+    members.push({clientId,assessment:options.buildExitPlan(clientId,definition)});
+  }
+  return workflow.exitHousehold({
+    key:options.sourceExitId,enrollmentKey:options.sourceEnrollmentId,
+    headClientId:options.headClientId,exitDate:options.exitDate,
+    destination:options.destination,reasonForLeaving:options.reasonForLeaving,members,
+    ...(options.destinationDetails?{destinationDetails:options.destinationDetails}:{}),
+    ...(options.reasonForLeavingOther?{reasonForLeavingOther:options.reasonForLeavingOther}:{}),
+  });
+}

package/examples/household-lifecycle-workflow.mts

@@ -0,0 +1,34 @@
+import type {WellSkyClient,GwtEnrollmentHelpers} from '@choiceapps/communityservices-sdk';
+import type {Page} from 'playwright-core';
+import {
+ createDateOfBirth,createDateOfBirthUi,createEnrollmentWorkflow,createProgramDiscovery,createHouseholdExitUi,
+ createMemberEntryDatePort,
+ type EnrollmentReader,type UiMutationStore,type EnrollmentAssessmentPlan,
+} from '@choiceapps/communityservices-sdk/browser';
+
+/** All members must already belong to the household. The new child's joined date
+ * must be on or before their own entry. Application policy builds age-appropriate plans. */
+export async function householdLifecycle(options:{
+ api:WellSkyClient;page:Page;helpers:GwtEnrollmentHelpers;enrollmentSession:EnrollmentReader;store:UiMutationStore;
+ sourceEnrollmentKey:string;headClientId:number;departingMemberId:number;childClientId:number;
+ memberExitDate:string;childEntryDate:string;sourceExitKey:string;sourceChildEntryKey:string;
+ memberExitPlan:EnrollmentAssessmentPlan;childEntryPlan:EnrollmentAssessmentPlan;
+}){
+ const workflow=createEnrollmentWorkflow({
+  ...options,birthDates:createDateOfBirth({api:options.api,ui:createDateOfBirthUi({page:options.page}),store:options.store}),discovery:createProgramDiscovery({page:options.page}),
+  exitUi:createHouseholdExitUi({page:options.page}),
+  memberEntryDatePort:createMemberEntryDatePort(options),
+ });
+ const exit=await workflow.exitHousehold({
+  key:options.sourceExitKey,enrollmentKey:options.sourceEnrollmentKey,headClientId:options.headClientId,
+  exitDate:options.memberExitDate,destination:'Rental by client, no ongoing housing subsidy',reasonForLeaving:'Completed program',
+  members:[{clientId:options.departingMemberId,assessment:options.memberExitPlan}],
+ });
+ const child=await workflow.addHouseholdMembers({
+  key:options.sourceChildEntryKey,enrollmentKey:options.sourceEnrollmentKey,headClientId:options.headClientId,
+  entryDate:options.childEntryDate,members:[{clientId:options.childClientId,assessment:options.childEntryPlan}],
+ });
+ // Later child interims/exits still use sourceEnrollmentKey. The workflow resolves
+ // the child's own entry key and date from the durable household journal.
+ return {exit,child};
+}

package/examples/independent-needs.mts

@@ -0,0 +1,30 @@
+import {
+ createNeedRecorder, type IndependentNeedUi, type UiMutationStore,
+ type NeedUi, type IndependentNeedInput, type ServiceRecorder,
+ type ServiceRecordInput, type ServiceTypeOption,
+} from '@choiceapps/communityservices-sdk/browser';
+
+/** Pass createNeedUi({page: session.page}) from a managed browser session. */
+export function independentNeeds(ui:IndependentNeedUi,store:UiMutationStore,tenant:string){
+ return createNeedRecorder({ui,store,tenant});
+}
+
+/** Cache once per tenant, with expiry. clientId is only browser navigation context. */
+export function discoverServiceTypes(ui:NeedUi,context:{clientId:number}){
+ return ui.listServiceTypes(context);
+}
+
+/** Cache per tenant and provider. This does not reread the full taxonomy. */
+export function discoverServiceQuicklist(ui:NeedUi,context:{clientId:number;providerId:number}){
+ return ui.listServiceQuicklist(context);
+}
+
+/** Explicit status/outcome: a PIT need does not imply delivery of a service. */
+export function recordPointInTimeNeed(ui:IndependentNeedUi,store:UiMutationStore,input:IndependentNeedInput,tenant:string){
+ return independentNeeds(ui,store,tenant).record(input);
+}
+
+/** Services accept the discovered taxonomy string; independent needs accept serviceCodeId. */
+export function recordChosenService(recorder:ServiceRecorder,type:ServiceTypeOption,input:Omit<ServiceRecordInput,'body'>&{body:Omit<ServiceRecordInput['body'],'serviceCode'>}){
+ return recorder.record({...input,body:{...input.body,serviceCode:type.code}});
+}

package/examples/program-discovery.ts

@@ -0,0 +1,19 @@
+import {WellSkyClient, readProgramCatalog, flattenQuestions} from '@choiceapps/communityservices-sdk';
+import {createProgramDiscovery} from '@choiceapps/communityservices-sdk/browser';
+import type {Page} from 'playwright-core';
+
+/** Supply an authenticated server-side API client and a dedicated authenticated UI page.
+ * Keep browser credentials/session cookies on the server, never in a consuming web app. */
+export async function getProgramAssessmentChoices(api:WellSkyClient, page:Page, providerId:number, metadataClientId:number) {
+  const catalog=await readProgramCatalog(api);
+  const provider=catalog.providers.find(item=>item.providerId===providerId);
+  if(!provider)throw Error('Provider is not active and operational in the API catalog');
+  const discovery=createProgramDiscovery({page});
+  const configuration=await discovery.getProviderAssessments({providerId});
+  const entry=configuration.defaults.find(item=>item.location==='showVaEntry');
+  if(entry?.resolution!=='resolved'||!entry.assessment)throw Error('VA entry assessment is not uniquely resolved');
+  // REST metadata currently requires a permitted client context even for definitions.
+  // Its result strips answers/recordset IDs. It is not a patient/client export.
+  const definition=await api.assessments.getDefinition({clientId:metadataClientId,assessmentCode:entry.assessment.code});
+  return {provider,configuration,definition,questions:flattenQuestions(definition.questions)};
+}

package/examples/quickstart.mjs

@@ -0,0 +1,13 @@
+import assert from 'node:assert/strict';
+import {createFakeWellSkyClient} from '@choiceapps/communityservices-sdk/testing';
+import {toItems} from '@choiceapps/communityservices-sdk';
+
+const client = createFakeWellSkyClient();
+client.fake.set('GET /clients/{clientId}', {
+	kind: 'reply', body: [{clientId: 123, firstName: 'Synthetic'}],
+});
+const people = toItems(await client.clients.get({path: {clientId: 123}}));
+assert.equal(people.length, 1);
+assert.equal(people[0].clientId, 123);
+assert.equal(client.fake.calls.length, 1);
+console.log('Read synthetic client 123; no network requests.');

package/examples/shelter-inventory.mts

@@ -0,0 +1,30 @@
+import type { Page } from 'playwright-core';
+import { createShelterInventory, type ShelterInventorySnapshot, type ShelterStay } from '@choiceapps/communityservices-sdk/browser';
+
+/** Uses the caller's dedicated authenticated application page. No credential loading. */
+export async function reportShelterInventory(page: Page, providerId: number) {
+  const inventory = createShelterInventory({ page });
+  const catalog = await inventory.listUnitLists({ providerId });
+  // Each list has its own observation interval. The provider report is not atomic.
+  const snapshots: ShelterInventorySnapshot[] = [];
+  for (const { unitListId } of catalog.unitLists) {
+    snapshots.push(await inventory.getInventory({ providerId, unitListId }));
+  }
+  return { catalog, snapshots };
+}
+
+export function vacancyReport(snapshot: ShelterInventorySnapshot) {
+  if (snapshot.availability.status === 'unknown') {
+    return { status: 'unknown', reasons: snapshot.availability.reasons };
+  }
+  return {
+    status: 'known',
+    observedAt: snapshot.freshness.observedAt,
+    count: snapshot.availability.vacantCount,
+    beds: snapshot.beds.filter(bed => bed.status === 'vacant'),
+  };
+  // A later check-in must recheck availability. These keys are not server bed IDs.
+}
+
+// Null is a valid group for a single-person stay, including installed declarations.
+export const singlePersonGroup: ShelterStay['groupId'] = null;