@choiceapps/communityservices-sdk 0.1.0

package/browser/gwt-mapped.mjs

@@ -0,0 +1,46 @@
+// Decode only the observed mapped-read wire types. Never evaluate server JavaScript.
+export function decodeMappedResponse(body, expectedOffset) {
+  if (!body.startsWith('//OK[') || body.length > 5_000_000) throw Error('GWT read failed');
+  // GWT emits long tokens in single quotes. Leave ordinary JSON strings untouched,
+  // including note text such as "selected 'No'" and escaped quotation marks.
+  const values = JSON.parse(body.slice(4).replace(/"(?:[^"\\]|\\.)*"|'([A-Za-z0-9$_]+)'/g, (token, long) => long === undefined ? token.replace(/\\(?:x([0-9a-fA-F]{2})|.)/g, (escape, hex) => hex === undefined ? escape : `\\u00${hex}`) : JSON.stringify(long)));
+  if (values.pop() !== 7 || values.pop() !== 0) throw Error('Unsupported GWT response');
+  const strings = values.pop(), refs = [];
+  if (!Array.isArray(strings) || strings.some(s => typeof s !== 'string')) throw Error('Invalid GWT strings');
+  const pop = () => { if (!values.length) throw Error('Truncated GWT response'); return values.pop(); };
+  const integer = () => { const n=pop(); if(!Number.isSafeInteger(n))throw Error('Invalid GWT integer');return n; };
+  const long = () => {
+    const s=pop(); if(typeof s!=='string'||!s.length)throw Error('Invalid GWT long');
+    let n=0n;for(const c of s){const digit='ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789$_'.indexOf(c);if(digit<0)throw Error('Invalid GWT long');n=n*64n+BigInt(digit);}
+    n=BigInt.asIntN(64,n);const number=Number(n);if(!Number.isSafeInteger(number))throw Error('GWT integer exceeds safe range');return number;
+  };
+  const object = () => {
+    const tag=integer();if(tag===0)return null;if(tag<0){if(-tag>refs.length)throw Error('Invalid GWT reference');return refs[-tag-1];}
+    const type=strings[tag-1],slot=refs.length;refs.push(null);
+    let result;
+    switch(type){
+      case 'java.lang.String/2004016611': result=strings[integer()-1];if(typeof result!=='string')throw Error('Invalid string reference');break;
+      case 'java.lang.Integer/3438268394': result=integer();break;
+      case 'java.lang.Double/858496421': result=pop();if(typeof result!=='number'||!Number.isFinite(result))throw Error('Invalid GWT double');break;
+      case 'java.lang.Long/4227064769': result=long();break;
+      case 'java.lang.Boolean/476441737': {const n=integer();if(n!==0&&n!==1)throw Error('Invalid boolean');result=!!n;break;}
+      case 'java.util.Date/3385151746': result=new Date(long()).toISOString();break;
+      case 'java.util.ArrayList/4159755760': {
+        result=[];refs[slot]=result;const count=integer();if(count<0||count>10000)throw Error('Invalid list size');for(let i=0;i<count;i++)result.push(object());break;
+      }
+      case 'java.util.HashMap/1797211028': {
+        result=Object.create(null);refs[slot]=result;const count=integer();if(count<0||count>1000)throw Error('Invalid map size');
+        for(let i=0;i<count;i++){const key=object();if(typeof key!=='string'||Object.hasOwn(result,key))throw Error('Invalid map key');result[key]=object();}break;
+      }
+      default: throw Error('Unsupported GWT mapped type');
+    }
+    refs[slot]=result;return result;
+  };
+  const root=integer();if(strings[root-1]!=='com.bowmansystems.sp5.core.client.ui.MappedQueryResults/340212582')throw Error('Not mapped results');
+  refs.push(null);
+  // MappedQueryResults serializes rows, firstRow and lastRow as primitive
+  // integers, then the boxed total. A zero firstRow is not a null object.
+  const rows=object(),offset=integer(),lastRow=integer(),total=object();
+  if(values.length||!Array.isArray(rows)||offset<0||lastRow < -1||expectedOffset!==undefined&&offset!==expectedOffset||!Number.isSafeInteger(total)||total<rows.length||offset+rows.length>total)throw Error('Incomplete mapped response');
+  return {rows,total};
+}

package/browser/household-exit.d.mts

@@ -0,0 +1,34 @@
+import type {Page} from 'playwright-core';
+export interface HouseholdExitTarget {clientId:number;enrollmentId:number;}
+export type HouseholdExitDestinationDetails =
+ | {kind:'rental-subsidy';rentalSubsidyType:string}
+ | {kind:'other';explanation:string};
+export interface HouseholdExitDetailInput {
+ /** Required for the corresponding destination; omitted for every other destination. */
+ destinationDetails?:HouseholdExitDestinationDetails;
+ /** Required only when the reason is Other. Explanations are 1..100 characters. */
+ reasonForLeavingOther?:string;
+}
+export interface HouseholdExitUiInput extends HouseholdExitTarget,HouseholdExitDetailInput {
+ /** Nonempty selected subset of the enrollment group. Includes target clientId, which need not be the head. */
+ clientIds:number[];exitDate:string;destination:string;reasonForLeaving:string;
+}
+export interface HouseholdExitOptions {
+ destinations:{value:string;name:string}[];reasons:{value:string;name:string}[];
+ rentalSubsidyTypes:{value:string;name:string}[];
+}
+export interface HouseholdExitStoredDetails {
+ destinationDetails:HouseholdExitDestinationDetails|null;
+ reasonForLeavingOther:string|null;
+}
+export interface HouseholdExitUi {
+ readonly connection?:import("./connection.mjs").UiConnection;
+ listOptions(target:HouseholdExitTarget):Promise<HouseholdExitOptions>;
+ /** Reopen the saved member exit and read the persisted conditional fields, then cancel. */
+ readExitDetails(target:HouseholdExitTarget):Promise<HouseholdExitStoredDetails>;
+ validateExit(input:HouseholdExitUiInput):Promise<void>;
+ /** One save attempt only. Use through the durable exitHousehold workflow. */
+ saveExit(input:HouseholdExitUiInput):Promise<void>;
+}
+/** UI port with fresh conditional choices and per-member readback. */
+export function createHouseholdExitUi(options:{page:Page}):HouseholdExitUi;

package/browser/household-exit.mjs

@@ -0,0 +1,102 @@
+import {pageConnection} from './connection.mjs';
+import {createPlaywrightGwtSession} from './playwright-session.mjs';
+import {withPageLock} from './page-lock.mjs';
+import {expectedExitDetails,rentalDestination} from './exit-details.mjs';
+
+const label=value=>value.replace(/\s*\(HUD\)\s*$/,'').trim();
+const id=value=>Number.isSafeInteger(value)&&value>0;
+/** Low-level UI port. Use through exitHousehold, which journals before save.
+ * This port makes at most one Save click and never retries an uncertain write. */
+export function createHouseholdExitUi({page}){
+ const connection=pageConnection(page),base=connection.moduleBaseUrl;
+ const reader=createPlaywrightGwtSession({page,tenant:connection.tenant,moduleBaseUrl:base});
+ const control=name=>page.locator(`[id="${name}"]:visible`);
+ const ready=()=>page.waitForFunction(()=>!document.body.innerText.includes('Processing...')&&!document.body.innerText.includes('Loading...'));
+ const cancel=async()=>{const button=control('ExitDataPopup.cancel-button');if(await button.count()){await button.click();await ready();}};
+ const validate=input=>{
+  if(!input||!id(input.clientId)||!id(input.enrollmentId))throw Error('Valid exit target required');
+  if(!Array.isArray(input.clientIds)||input.clientIds.length<1||input.clientIds.some(v=>!id(v))||new Set(input.clientIds).size!==input.clientIds.length||!input.clientIds.includes(input.clientId))throw Error('Exact household exit members required');
+  if(typeof input.exitDate!=='string'||!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.000)?(?:Z|[+-]\d{2}:\d{2})$/.test(input.exitDate)||!Number.isFinite(Date.parse(input.exitDate))||new Date(input.exitDate.slice(0,19)+'Z').toISOString().slice(0,19)!==input.exitDate.slice(0,19))throw Error('Timezone-qualified exit date required');
+  for(const field of ['destination','reasonForLeaving'])if(typeof input[field]!=='string'||!input[field].trim())throw Error('Exit choice required');
+  expectedExitDetails(input);
+ };
+ const options=async name=>(await page.getByLabel(name,{exact:true}).locator('option').evaluateAll(es=>es.filter(e=>!e.disabled&&e.value&&e.value!=='-Select-'&&!e.text.startsWith('-----')).map(e=>({value:e.value,name:e.text})))).map(o=>({...o,name:label(o.name)}));
+ const open=async target=>{
+  const url=new URL(page.url());if(url.origin!==new URL(base).origin||url.pathname!==new URL(base).pathname+'index.html')throw Error('Configured application page required');
+  await cancel();const snapshot=await reader.readEnrollment(target);
+  await control(`ClientEntryExitTab.editExit-imageLink_${target.enrollmentId}`).click();await control('ExitDataPopup.cancel-button').waitFor();await ready();
+  if(!(await page.locator('body').innerText()).includes(`Edit Exit Data - (${target.clientId})`))throw Error('Exit client mismatch');
+  return snapshot;
+ };
+ // Locate each explanation relative to its own labeled select, never by field order.
+ const otherField=name=>page.getByLabel(name,{exact:true}).locator('xpath=ancestor::tr[following-sibling::tr[1]//input[@maxlength="100"]][1]/following-sibling::tr[1]').getByRole('textbox');
+ const selected=async name=>page.getByLabel(name,{exact:true}).evaluate(e=>{
+  const o=e.selectedOptions;if(o.length!==1||!o[0].value||o[0].value==='-Select-')throw Error('Exit selection missing');return o[0].text;
+ });
+ const readDetails=async()=>{
+  const destination=label(await selected('Destination')),reasonForLeaving=label(await selected('Reason for Leaving'));
+  const destinationOther=await otherField('Destination').inputValue(),reasonOther=await otherField('Reason for Leaving').inputValue();
+  if(await page.getByLabel('Subsidy',{exact:true}).isVisible())throw Error('Unrecognized legacy subsidy form');
+  const rentalVisible=await page.getByLabel('Rental Subsidy Type',{exact:true}).isVisible();
+  if(rentalVisible!==(destination===rentalDestination))throw Error('Exit subsidy form mismatch');
+  if(destination!=='Other'&&destinationOther||reasonForLeaving!=='Other'&&reasonOther)throw Error('Unexpected stored Other explanation');
+  const destinationDetails=destination===rentalDestination?{kind:'rental-subsidy',rentalSubsidyType:label(await selected('Rental Subsidy Type'))}:destination==='Other'?{kind:'other',explanation:destinationOther}:undefined;
+  return expectedExitDetails({destination,reasonForLeaving,...(destinationDetails?{destinationDetails}:{}),...(reasonForLeaving==='Other'?{reasonForLeavingOther:reasonOther}:{})});
+ };
+ const configure=async input=>{
+  validate(input);const snapshot=await open({clientId:input.clientId,enrollmentId:input.enrollmentId});
+  const desired=[...input.clientIds].sort((a,b)=>a-b);
+  if(!Array.isArray(snapshot.members)||!Array.isArray(snapshot.exits))throw Error('Exit household read incomplete');
+  for(const clientId of desired){
+   const members=snapshot.members.filter(m=>m.clientId===clientId);
+   if(members.length!==1)throw Error('Selected exit member missing or ambiguous');
+   const exits=snapshot.exits.filter(e=>e.clientId===clientId);
+   if(exits.length!==1||exits[0].enrollmentId!==members[0].enrollmentId)throw Error('Selected exit metadata missing or ambiguous');
+   if(exits[0].projectExitDate!==null)throw Error('Selected household member already exited');
+  }
+  if(Date.parse(input.exitDate)<Date.parse(snapshot.projectStartDate)||snapshot.reviews.some(r=>Date.parse(r.reviewDate)>Date.parse(input.exitDate)))throw Error('Exit date precedes enrollment or review');
+  const choices={destinations:await options('Destination'),reasons:await options('Reason for Leaving')};
+  const chosen={};
+  for(const [field,name,items]of [['destination','Destination',choices.destinations],['reasonForLeaving','Reason for Leaving',choices.reasons]]){
+   const matching=items.filter(o=>o.name===label(input[field]));if(matching.length!==1)throw Error('Exit choice unavailable or ambiguous');chosen[field]=matching[0].value;await page.getByLabel(name,{exact:true}).selectOption(chosen[field]);
+  }
+  await ready();
+  if(await page.getByLabel('Subsidy',{exact:true}).isVisible())throw Error('Unrecognized legacy subsidy form');
+  if(input.destinationDetails?.kind==='rental-subsidy'){
+   const field=page.getByLabel('Rental Subsidy Type',{exact:true});
+   if(!await field.isVisible())throw Error('Rental subsidy field unavailable');
+   const matches=(await options('Rental Subsidy Type')).filter(o=>o.name===input.destinationDetails.rentalSubsidyType);
+   if(matches.length!==1)throw Error('Rental subsidy choice unavailable or ambiguous');
+   await field.selectOption(matches[0].value);if(await field.inputValue()!==matches[0].value)throw Error('Rental subsidy selection did not match');
+  }else if(await page.getByLabel('Rental Subsidy Type',{exact:true}).isVisible())throw Error('Unexpected rental subsidy field');
+  for(const [name,value]of [['Destination',input.destinationDetails?.kind==='other'?input.destinationDetails.explanation:''],['Reason for Leaving',input.reasonForLeavingOther??'']]){
+   const field=otherField(name);if(await field.count()!==1||!await field.isVisible()||await field.getAttribute('maxlength')!=='100')throw Error('Other explanation field unavailable');
+   await field.fill(value);if(await field.inputValue()!==value)throw Error('Other explanation did not match');
+  }
+  const boxes=page.locator('[id^="HouseholdsCheckboxTree.householdCheckbox."]:visible input');
+  for(let i=0;i<await boxes.count();i++){
+   const box=boxes.nth(i),clientId=await box.evaluate(e=>Number(e.parentElement.id.match(/\.client-(\d+)$/)?.[1]));
+   if(await box.isEnabled())await box.setChecked(desired.includes(clientId));
+   if((await box.isChecked())!==desired.includes(clientId))throw Error('Exit household selection mismatch');
+  }
+  const selected=await page.locator('[id^="HouseholdsCheckboxTree.householdCheckbox."]:visible input:checked').evaluateAll(es=>es.map(e=>Number(e.parentElement.id.match(/\.client-(\d+)$/)?.[1])).sort((a,b)=>a-b));
+  if(JSON.stringify(selected)!==JSON.stringify(desired))throw Error('Exit household selection incomplete');
+  const parts=await page.evaluate(value=>{const d=new Date(value),local=new Date(d.getFullYear(),d.getMonth(),d.getDate(),d.getHours(),d.getMinutes(),d.getSeconds());if(+d!==+local)throw Error('Ambiguous local exit time');return {Month:String(d.getMonth()+1).padStart(2,'0'),Day:String(d.getDate()).padStart(2,'0'),Year:String(d.getFullYear()),Hour:String(d.getHours()%12||12),Minute:String(d.getMinutes()).padStart(2,'0'),Second:String(d.getSeconds()).padStart(2,'0'),'AM/PM':d.getHours()<12?'AM':'PM'};},input.exitDate);
+  for(const [part,value]of Object.entries(parts)){const field=page.getByLabel(`Exit Date ${part}`,{exact:true});if(['Month','Day','Year'].includes(part))await field.fill(value);else await field.selectOption({label:value});if(await field.inputValue()!==value)throw Error('Exit date did not match');}
+  for(const [field,name]of [['destination','Destination'],['reasonForLeaving','Reason for Leaving']])if(await page.getByLabel(name,{exact:true}).inputValue()!==chosen[field])throw Error('Exit choice did not match');
+ };
+ return {connection,
+  listOptions:target=>withPageLock(page,async()=>{if(!id(target?.clientId)||!id(target?.enrollmentId))throw Error('Valid exit target required');try{await open(target);const result={destinations:await options('Destination'),reasons:await options('Reason for Leaving'),rentalSubsidyTypes:[]};const rental=result.destinations.filter(o=>o.name===rentalDestination);if(rental.length>1)throw Error('Ambiguous rental destination');if(rental.length){await page.getByLabel('Destination',{exact:true}).selectOption(rental[0].value);await ready();if(!await page.getByLabel('Rental Subsidy Type',{exact:true}).isVisible())throw Error('Rental subsidy field unavailable');result.rentalSubsidyTypes=await options('Rental Subsidy Type');}return result;}finally{await cancel();}}),
+  readExitDetails:target=>withPageLock(page,async()=>{if(!id(target?.clientId)||!id(target?.enrollmentId))throw Error('Valid exit target required');try{const snapshot=await open(target);if(!snapshot.exits.some(e=>e.clientId===target.clientId&&e.enrollmentId===target.enrollmentId&&e.projectExitDate))throw Error('Saved exit required');return await readDetails();}finally{await cancel();}}),
+  validateExit:input=>withPageLock(page,async()=>{try{await configure(input);}finally{await cancel();}}),
+  saveExit:input=>withPageLock(page,async()=>{
+   try{
+    await configure(input);
+    await control('ExitDataPopup.saveAndContinue-button').click();
+    await control('ExitDataPopup.cancel-button').waitFor({state:'hidden',timeout:30000});
+    await ready();
+    // A success screen is not proof of a committed household exit. The caller must read it back.
+   }finally{await cancel();}
+  }),
+ };
+}

package/browser/households-ui.mjs

@@ -0,0 +1,20 @@
+import {pageConnection} from './connection.mjs';
+import {withPageLock} from './page-lock.mjs';
+
+/** Read-only household absence check. Never clicks Continue, which creates a household. */
+export function createHouseholdUi({page}) {
+ const connection=pageConnection(page),base=connection.moduleBaseUrl;
+ const confirmNoHouseholds=clientId=>withPageLock(page,async()=>{
+  if(!Number.isSafeInteger(clientId)||clientId<1||new URL(page.url()).origin+new URL(page.url()).pathname!==base+'index.html')throw Error('Client and configured application page required');
+  if(await page.locator('[role=dialog]:visible').count())throw Error('Close dialogs before household workflow');
+  const ready=()=>page.waitForFunction(()=>!document.body.innerText.includes('Processing...')&&!document.body.innerText.includes('Loading...'),null,{timeout:30000});
+  if(/Client - \(\d+\)/.test(await page.locator('body').innerText())){
+   await page.getByRole('tab',{name:'Client Information',exact:true}).click();await page.getByRole('tab',{name:'Summary',exact:true}).click();await ready();await page.getByRole('button',{name:'Exit',exact:true}).click();await page.waitForURL(u=>u.hash==='#clientPointClientMain');await ready();
+  }
+  await page.goto(base+'index.html#loadClient;clientId='+clientId);
+  await page.waitForFunction(id=>document.body.innerText.includes(`Client - (${id})`)&&!document.body.innerText.includes('Processing...')&&!document.body.innerText.includes('Loading...'),clientId,{timeout:30000});
+  await page.getByRole('tab',{name:'Households',exact:true}).click();await ready();
+  return await page.getByText('This Client is not currently a member of any Households.',{exact:true}).isVisible();
+ });
+ return {connection,confirmNoHouseholds};
+}

package/browser/households.d.mts

@@ -0,0 +1,22 @@
+import type {Page} from 'playwright-core';
+import type {WellSkyClient} from '../dist/esm/index.js';
+import type {UiMutationStore} from './index.mjs';
+export interface HouseholdMemberInput {clientId:number;relationship:string;dateJoined:string;}
+export interface HouseholdMember extends HouseholdMemberInput {head:boolean;dateEnded:string|null;isActive:boolean;}
+export interface HouseholdSnapshot {householdId:number;householdType:string;members:HouseholdMember[];}
+export interface HouseholdResult {key:string;outcome:'verified'|'already-present';household:HouseholdSnapshot;}
+export interface HouseholdUi {
+ readonly connection?:import("./connection.mjs").UiConnection;confirmNoHouseholds(clientId:number):Promise<boolean>;}
+export interface HouseholdMutation {key:string;householdId:number;headClientId:number;}
+export interface Households {
+ read(householdId:number):Promise<HouseholdSnapshot>;
+ create(input:{key:string;headClientId:number;householdType:string;members:HouseholdMemberInput[]}):Promise<HouseholdResult>;
+ addMembers(input:HouseholdMutation&{householdType?:string;members:HouseholdMemberInput[]}):Promise<HouseholdResult>;
+ /** Ends household membership only. The head cannot leave an active household. */
+ endMembers(input:HouseholdMutation&{clientIds:number[];dateEnded:string}):Promise<HouseholdResult>;
+ /** Only non-head relationships may change. */
+ updateRelationships(input:HouseholdMutation&{members:{clientId:number;relationship:string}[]}):Promise<HouseholdResult>;
+}
+export function createHouseholds(options:{api:WellSkyClient;store:UiMutationStore;ui:HouseholdUi}):Households;
+export function getHouseholdOptions():{householdTypes:string[];relationships:string[];verifiedOn:string};
+export function createHouseholdUi(options:{page:Page}):HouseholdUi;

package/browser/households.mjs

@@ -0,0 +1,115 @@
+import {apiScope} from './connection.mjs';
+import {createHash} from 'node:crypto';
+import {toItems} from '../dist/esm/index.js';
+
+const hash=value=>createHash('sha256').update(JSON.stringify(value,(_,v)=>v&&typeof v==='object'&&!Array.isArray(v)?Object.fromEntries(Object.entries(v).sort(([a],[b])=>a.localeCompare(b))):v)).digest('hex');
+const id=n=>{if(!Number.isSafeInteger(n)||n<1||n>2147483647)throw Error('Positive household/client ID required');return n;};
+const fields=(v,keys)=>{if(!v||typeof v!=='object'||Array.isArray(v)||Object.keys(v).some(k=>!keys.includes(k)))throw Error('Unknown household field');};
+const instant=value=>{
+ if(typeof value!=='string'||!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.000)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)||!Number.isFinite(Date.parse(value))||new Date(value.slice(0,19)+'Z').toISOString().slice(0,19)!==value.slice(0,19))throw Error('Valid whole-second timezone-qualified membership date required');
+ return new Date(value).toISOString();
+};
+const serverDate=value=>instant(/(?:Z|[+-]\d\d:\d\d)$/.test(value)?value:value+'Z');
+const types=['Individual','Female Single Parent','Male Single Parent','Two Parent Family','Foster Parent(s)','Couple With No Children','Non-custodial Caregiver(s)','Grandparent(s) and Child','Children Only Household','Other'];
+const relationships=['Daughter','Father','Granddaughter','Grandfather','Grandmother','Grandson','Husband','Husband and Father','Mother','Other non-relative','Other relative','Self','Significant other','Son','Step-daughter','Step-son','Unknown','Wife','Wife and Mother'];
+/** Display labels observed in the training UI, October 24, 2026. Recheck for other tenants. */
+export const getHouseholdOptions=()=>({householdTypes:[...types],relationships:[...relationships],verifiedOn:'2026-10-24'});
+const sorted=members=>members.sort((a,b)=>a.clientId-b.clientId);
+const model=row=>{
+ id(row?.householdId);if(row.isActive!==true||!types.includes(row.householdType)||!Array.isArray(row.clients))throw Error('Active household readback unavailable');
+ const members=sorted(row.clients.map(m=>({clientId:id(m.clientId),head:m.headofhouseholdStatus,relationship:m.headofhouseholdRelationship,dateJoined:serverDate(m.dateJoined),dateEnded:m.dateLeft?serverDate(m.dateLeft):null,isActive:m.isActive})));
+ guard(members);return {householdId:row.householdId,householdType:row.householdType,members};
+};
+const guard=members=>{
+ if(!members.length||new Set(members.map(m=>m.clientId)).size!==members.length)throw Error('Unique household members required');
+ const heads=members.filter(m=>m.head);
+ if(heads.length!==1||heads[0].isActive!==true||heads[0].dateEnded||heads[0].relationship!=='Self')throw Error('Household data error: exactly one active head with relationship Self is required');
+ for(const m of members){
+  if(typeof m.head!=='boolean'||typeof m.isActive!=='boolean'||!relationships.includes(m.relationship)||(!m.head&&m.relationship==='Self'))throw Error('Invalid household relationship or head status');
+  if(m.dateJoined<heads[0].dateJoined||m.dateEnded&&m.dateEnded<m.dateJoined)throw Error('Head must cover every membership date');
+ }
+ return heads[0].clientId;
+};
+const member=m=>{fields(m,['clientId','relationship','dateJoined']);if(!relationships.includes(m.relationship))throw Error('Unavailable household relationship');return {clientId:id(m.clientId),relationship:m.relationship,dateJoined:instant(m.dateJoined),dateEnded:null,isActive:true};};
+const body=s=>({householdType:s.householdType,householdClients:s.members.map(m=>({clientId:m.clientId,headOfHouseholdStatus:m.head,headOfHouseholdRelationship:m.relationship,dateJoined:m.dateJoined,...(s.householdId?{dateEnded:m.dateEnded,isActive:m.isActive}:{})}))});
+const equal=(a,b)=>hash({householdType:a.householdType,members:a.members})===hash({householdType:b.householdType,members:b.members});
+
+/** Durable household management. Does not attach members to enrollments or exit them.
+ * Share one store across callers. Ambiguous writes never automatically repeat. */
+export function createHouseholds({api,store,ui}) {
+ const tenantScope=apiScope(api, ui);
+ if(!store?.withLock||!ui?.confirmNoHouseholds)throw Error('REST API, durable store and household UI reader required');
+ const read=async householdId=>{id(householdId);const rows=toItems(await api.households.get({path:{householdId}}));if(rows.length!==1||rows[0].householdId!==householdId)throw Error('Household readback ambiguous');return model(rows[0]);};
+ const list=async(clientId,allowEmpty)=>{
+  const rows=[],ids=new Set();let total;
+  for(let startPage=1;startPage<=100;startPage++){
+   let result;try{result=await api.households.listForClient({path:{clientId},query:{perPage:100,startPage,total_count:true}});}catch(e){if(e.status===404&&startPage===1&&allowEmpty&&await ui.confirmNoHouseholds(clientId))return [];throw e;}
+   if(!Number.isSafeInteger(result?.count)||result.count<0||!Array.isArray(result.values)||total!==undefined&&total!==result.count)throw Error('Household list count unavailable or changed');total=result.count;
+   for(const row of result.values){id(row.householdId);if(ids.has(row.householdId)||!row.clients?.some(c=>c.clientId===clientId))throw Error('Invalid household list');ids.add(row.householdId);rows.push(row);}
+   if(rows.length===total)return rows;if(!result.values.length||rows.length>total)throw Error('Incomplete household list');
+  }throw Error('Household list exceeds safety limit');
+ };
+ const run=async(kind,input)=>{
+  const keys={create:['key','headClientId','householdType','members'],addMembers:['key','householdId','headClientId','householdType','members'],endMembers:['key','householdId','headClientId','clientIds','dateEnded'],updateRelationships:['key','householdId','headClientId','members']};
+  fields(input,keys[kind]);id(input.headClientId);if(typeof input.key!=='string'||!input.key.trim()||input.key.length>200)throw Error('Stable household key required');
+  const intent={kind,headClientId:input.headClientId};
+  if(kind!=='create')intent.householdId=id(input.householdId);
+  if(kind==='create'||input.householdType!==undefined){if(!types.includes(input.householdType))throw Error('Unavailable household type');intent.householdType=input.householdType;}
+  if(kind==='create'||kind==='addMembers'){
+   if(!Array.isArray(input.members)||!input.members.length)throw Error('Members required');intent.members=sorted(input.members.map(member));
+   if(new Set(intent.members.map(m=>m.clientId)).size!==intent.members.length)throw Error('Duplicate client IDs');
+   for(const m of intent.members){m.head=m.clientId===input.headClientId;if(m.head?m.relationship!=='Self':m.relationship==='Self')throw Error('Head changes are not supported');}
+   if(kind==='create')guard(intent.members);else if(intent.members.some(m=>m.head))throw Error('Head changes are not supported');
+  }else if(kind==='endMembers'){
+   if(!Array.isArray(input.clientIds)||!input.clientIds.length)throw Error('Client IDs required');intent.clientIds=input.clientIds.map(id).sort((a,b)=>a-b);intent.dateEnded=instant(input.dateEnded);
+   if(new Set(intent.clientIds).size!==intent.clientIds.length)throw Error('Duplicate client IDs');
+   if(intent.clientIds.includes(input.headClientId))throw Error('Head cannot leave an active household; household closure is a separate workflow');
+  }else{
+   if(!Array.isArray(input.members)||!input.members.length)throw Error('Members required');intent.members=sorted(input.members.map(m=>{fields(m,['clientId','relationship']);id(m.clientId);if(m.clientId===input.headClientId||m.relationship==='Self')throw Error('Head changes are not supported');if(!relationships.includes(m.relationship))throw Error('Unavailable household relationship');return {clientId:m.clientId,relationship:m.relationship};}));
+   if(new Set(intent.members.map(m=>m.clientId)).size!==intent.members.length)throw Error('Duplicate client IDs');
+  }
+  const scope=JSON.stringify([tenantScope,'household-management']),keyHash=hash(input.key),intentHash=hash(intent);
+  return store.withLock(scope,async()=>{
+   const entries=await store.read(scope);if(!Array.isArray(entries)||entries.some(e=>e.version!==1||!['planned','attempted','verified'].includes(e.stage)))throw Error('Invalid household journal');
+   let entry=entries.find(e=>e.keyHash===keyHash);if(entries.filter(e=>e.keyHash===keyHash).length>1||entry&&entry.intentHash!==intentHash)throw Error('Household key conflicts with earlier intent');
+   if(entries.some(e=>e.keyHash!==keyHash&&e.stage!=='verified'))throw Error('Another household write is unresolved');
+   const persist=async stage=>{entry={...entry,version:1,keyHash,intentHash,stage};const i=entries.findIndex(e=>e.keyHash===keyHash);if(i<0)entries.push(entry);else entries[i]=entry;await store.write(scope,structuredClone(entries));};
+   if(entry?.stage==='verified'){
+    const current=await read(entry.householdId),latest=entries.filter(e=>e.householdId===entry.householdId&&e.stage==='verified').at(-1);
+    if(guard(current.members)!==input.headClientId||!equal(current,latest.target))throw Error('Household changed since verification; reconcile before continuing');
+    return {key:input.key,outcome:'already-present',household:current};
+   }
+   let current;
+   if(kind==='create'){
+    const existing=await list(input.headClientId,!entry);
+    if(!entry){entry={target:{householdType:intent.householdType,members:intent.members},baselineIds:existing.map(h=>h.householdId)};await persist('planned');}
+    const matches=existing.filter(h=>h.isActive===true).map(model).filter(h=>equal(h,entry.target));
+    if(matches.length>1)throw Error('Multiple matching households');current=matches[0];
+   }else{
+    current=await read(input.householdId);if(guard(current.members)!==input.headClientId)throw Error('Head changes are not supported');
+    if(!entry){
+     const target=structuredClone(current);if(intent.householdType)target.householdType=intent.householdType;
+     if(kind==='addMembers')for(const m of intent.members){if(target.members.some(v=>v.clientId===m.clientId))throw Error('Client already belongs to household; rejoining needs an explicit history workflow');target.members.push(m);}
+     else for(const change of kind==='endMembers'?intent.clientIds.map(clientId=>({clientId})):intent.members){
+      const m=target.members.find(v=>v.clientId===change.clientId);if(!m||!m.isActive||m.dateEnded)throw Error('Active household member required');if(kind==='endMembers')m.dateEnded=intent.dateEnded;else m.relationship=change.relationship;
+     }
+     sorted(target.members);guard(target.members);entry={householdId:current.householdId,baseline:current,target};await persist('planned');
+    }
+   }
+   if(!current||!equal(current,entry.target)){
+    if(entry.stage!=='planned')throw Error('Household write unresolved; refusing another mutation');
+    if(current&&!equal(current,entry.baseline))throw Error('Household changed before write');
+    for(const m of entry.target.members.filter(m=>!entry.baseline?.members.some(v=>v.clientId===m.clientId))){const rows=toItems(await api.clients.get({path:{clientId:m.clientId}}));if(rows.length!==1||rows[0].clientId!==m.clientId||rows[0].isActive!==true)throw Error('Active client required');}
+    await persist('attempted');let error;
+    try{if(kind==='create')await api.households.create({body:body(entry.target)});else await api.households.update({path:{householdId:input.householdId},body:body(entry.target)});}catch(e){error=e;}
+    if(kind==='create'){
+     const found=(await list(input.headClientId,false)).filter(h=>!entry.baselineIds.includes(h.householdId)&&h.isActive===true).map(model).filter(h=>equal(h,entry.target));
+     if(found.length!==1)throw error??Error('Created household not uniquely verified');current=found[0];
+    }else current=await read(input.householdId);
+    if(!equal(current,entry.target))throw error??Error('Household readback mismatch; refusing replay');
+   }
+   entry.householdId=current.householdId;await persist('verified');return {key:input.key,outcome:'verified',household:current};
+  });
+ };
+ return {read,create:input=>run('create',input),addMembers:input=>run('addMembers',input),endMembers:input=>run('endMembers',input),updateRelationships:input=>run('updateRelationships',input)};
+}

package/browser/index.d.mts

@@ -0,0 +1,78 @@
+import type {UiConnection,UiConnectionOptions} from './connection.mjs';
+import type {Browser, BrowserContext, BrowserType, Page} from 'playwright-core';
+import type {GwtEnrollmentExit,GwtEnrollmentHelpers,GwtEnrollmentSession,GwtEnrollmentSnapshot,GwtMutationStore} from '../dist/esm/index.js';
+export interface LoginOptions extends UiConnectionOptions {
+  chromium: BrowserType;
+  envFile?: string;
+  executablePath?: string;
+  timeoutMs?: number;
+  passwordRecovery?: false | PasswordRecoveryOptions;
+}
+/** Enabled by default with a private per-user file journal. Share a store across hosts. */
+export interface PasswordRecoveryOptions {store?:UiMutationStore;appendCharacter?:string;}
+export class LoginError extends Error {
+  readonly code:'PASSWORD_EXPIRED'|'RECOVERY_UNCERTAIN'|'RECOVERY_CONFIGURATION'|'LOGIN_FAILED';
+  readonly stage:string;
+  readonly recoveryStage?:string;
+}
+export interface UiSession {readonly connection:UiConnection;browser: Browser;context: BrowserContext;page: Page;passwordRecovery:'restored-original'|'not-needed';ensureAuthenticated():Promise<void>;reauthenticate():Promise<void>;close():Promise<void>;}
+export interface PlaywrightGwtOptions {page:Page;tenant:string;moduleBaseUrl:string;}
+export interface PlaywrightEnrollmentSnapshot extends GwtEnrollmentSnapshot {providerId:number;enrollmentType:string;exits:readonly GwtEnrollmentExit[];}
+export interface EnrollmentReader {
+  readonly connection?:UiConnection;
+  readEnrollment(target:{clientId:number;enrollmentId:number}):Promise<PlaywrightEnrollmentSnapshot>;
+}
+export function openUiSession(options:LoginOptions):Promise<UiSession>;
+/** The read-only enrollment session shares the page lock with mutation helpers. */
+export function openEnrollmentSession(options:LoginOptions&{store:GwtMutationStore & UiMutationStore}):Promise<UiSession&{helpers:GwtEnrollmentHelpers;enrollmentSession:EnrollmentReader;workflows:ClientWorkflows}>;
+export function createPlaywrightGwtSession(options:PlaywrightGwtOptions):Omit<GwtEnrollmentSession,'readEnrollment'>&EnrollmentReader;
+export function createPlaywrightEnrollmentHelpers(options:PlaywrightGwtOptions&{store:GwtMutationStore}):GwtEnrollmentHelpers;
+
+/** Durable JSON journal. Use a separate namespace from enrollment intents. */
+export interface UiMutationStore {
+  withLock<T>(scope:string,work:()=>Promise<T>):Promise<T>;
+  read(scope:string):Promise<readonly unknown[]>;
+  write(scope:string,records:readonly unknown[]):Promise<void>;
+}
+export interface BrowserAttachment {
+  attachmentId:number;entityId:number|null;entityType:string;entityName:string;
+  name:string;extension:string;description:string|null;
+}
+export type AttachmentConflictReason='intent-changed'|'duplicate-name'|'identity-changed'|'content-changed'|'unresolved';
+export class AttachmentConflictError extends Error {
+  constructor(reason:AttachmentConflictReason,message:string);
+  readonly code:'ATTACHMENT_CONFLICT';
+  readonly reason:AttachmentConflictReason;
+}
+export interface BrowserCaseNote {noteId:number;goalId:number;clientId:number;noteDate:string;note:string;providerId:number;}
+export interface ClientWorkflows {
+ readonly connection?:import("./connection.mjs").UiConnection;
+  listAttachments(clientId:number):Promise<BrowserAttachment[]>;
+  downloadAttachment(input:{clientId:number;attachmentId:number}):Promise<Uint8Array>;
+  uploadAttachment(input:{clientId:number;location:{kind:'profile'|'case-plans'}|{kind:'goal';goalId:number};file:{name:string;mimeType?:string;buffer:Uint8Array};description?:string}):Promise<{outcome:'written'|'reconciled'|'already-present';attachment:BrowserAttachment;checksum:string}>;
+  listCaseNotes(input:{clientId:number;goalId:number}):Promise<BrowserCaseNote[]>;
+  createCaseNote(input:{key?:string;clientId:number;goalId:number;providerId:number;noteDate:string;note:string}):Promise<{outcome:'written'|'reconciled'|'already-present';note:BrowserCaseNote}>;
+}
+export function createClientWorkflows(options:{page:Page;store:UiMutationStore}):ClientWorkflows;
+export function createFileGwtMutationStore(directory:string):GwtMutationStore & UiMutationStore;
+export * from './service-recording.mjs';
+export * from './ssvf-rules.mjs';
+export * from './program-discovery.mjs';
+export * from './enrollment-workflow.mjs';
+export * from './member-entry-date.mjs';
+export * from './household-exit.mjs';
+
+export class SessionInterruptedError extends Error {readonly code:'SESSION_INTERRUPTED';readonly reauthenticated:boolean;}
+export * from './client-profile.mjs';
+export * from './date-of-birth.mjs';
+export * from './households.mjs';
+export * from './client-creation.mjs';
+export * from './case-plans.mjs';
+export * from './need-recording.mjs';
+export * from './shelters.mjs';
+export * from './shelter-inventory.mjs';
+
+export * from './current-living-situation.mjs';
+
+export {resolveUiConnection} from './connection.mjs';
+export type {UiConnection,UiConnectionOptions} from './connection.mjs';

package/browser/index.mjs

@@ -0,0 +1,46 @@
+export {createPlaywrightEnrollmentHelpers,createPlaywrightGwtSession} from './playwright-session.mjs';
+export {openUiSession,LoginError} from './ui-login.mjs';
+import {openUiSession} from './ui-login.mjs';
+import {createPlaywrightEnrollmentHelpers,createPlaywrightGwtSession} from './playwright-session.mjs';
+import {createClientWorkflows} from './client-workflows.mjs';
+import {withPageLock} from './page-lock.mjs';
+/** Authenticate once, use the same page for all writes, and retain the caller's durable journal. */
+export async function openEnrollmentSession({store,...loginOptions}) {
+  const session=await openUiSession(loginOptions);
+  try {
+    const helpers=createPlaywrightEnrollmentHelpers({page:session.page,store,...session.connection});
+    const reader=createPlaywrightGwtSession({page:session.page,...session.connection});
+    const enrollmentSession={connection:session.connection,readEnrollment:target=>withPageLock(session.page,()=>reader.readEnrollment(target))};
+    return Object.assign(session,{helpers,enrollmentSession,workflows:createClientWorkflows({page:session.page,store})});
+  }catch(error){await session.close();throw error;}
+}
+export {createClientWorkflows} from './client-workflows.mjs';
+export {AttachmentConflictError} from './attachment-conflict.mjs';
+export {createFileGwtMutationStore} from './file-store.mjs';
+export {createServiceUi} from './service-ui.mjs';
+export {createServiceRecorder} from './service-recording.mjs';
+export {getSsvfServiceRules} from './ssvf-rules.mjs';
+export {createProgramDiscovery} from './program-discovery.mjs';
+export {createEnrollmentWorkflow,EnrollmentWorkflowError} from './enrollment-workflow.mjs';
+export {createMemberEntryDatePort} from './member-entry-date.mjs';
+export {createHouseholdExitUi} from './household-exit.mjs';
+
+export {SessionInterruptedError} from './session-authentication.mjs';
+export {createClientProfile} from './client-profile.mjs';
+export {createClientProfileUi} from './client-profile-ui.mjs';
+export {createDateOfBirth,validateBirthDate} from './date-of-birth.mjs';
+export {createDateOfBirthUi} from './date-of-birth-ui.mjs';
+export {createHouseholds,getHouseholdOptions} from './households.mjs';
+export {createHouseholdUi} from './households-ui.mjs';
+export {createClientCreator} from './client-creation.mjs';
+export {createCasePlans} from './case-plans.mjs';
+export {createCasePlanUi} from './case-plans-ui.mjs';
+export {createNeedRecorder,NeedConflictError} from './need-recording.mjs';
+export {createNeedUi} from './need-ui.mjs';
+export {createShelters,readShelterProgram,ShelterConflictError} from './shelters.mjs';
+export {createShelterUi} from './shelter-ui.mjs';
+export {createShelterInventory, ShelterInventoryError} from './shelter-inventory.mjs';
+
+export * from './current-living-situation.mjs';
+
+export {resolveUiConnection} from './connection.mjs';

package/browser/member-entry-date.d.mts

@@ -0,0 +1,30 @@
+import type {GwtEnrollmentExit,WellSkyClient} from '../dist/esm/index.js';
+import type {EnrollmentReader} from './index.mjs';
+
+export interface MemberEntryDateCohortMember {
+ clientId:number;
+ enrollmentId:number;
+ /** Original start date, retained for every member except the requested target. */
+ entryDate:string;
+ /** Complete authoritative exit metadata, which must remain unchanged. */
+ exit:GwtEnrollmentExit;
+}
+export interface MemberEntryDateInput {
+ clientId:number;
+ enrollmentId:number;
+ providerId:number;
+ type:'HUD'|'VA';
+ /** Requested later start date for this one open enrollment. */
+ entryDate:string;
+ /** Complete current linked cohort, including the target at its original start date. */
+ cohort:readonly MemberEntryDateCohortMember[];
+}
+export interface MemberEntryDatePort {
+ validateMemberEntryDate(input:MemberEntryDateInput):Promise<void>;
+ /** At most one date-only PUT. Caller journals before save and owns uncertain outcomes. */
+ saveMemberEntryDate(input:MemberEntryDateInput):Promise<void>;
+}
+export function createMemberEntryDatePort(options:{
+ api:Pick<WellSkyClient,'tenant'|'enrollments'>;
+ enrollmentSession:EnrollmentReader;
+}):MemberEntryDatePort;

package/browser/member-entry-date.mjs

@@ -0,0 +1,71 @@
+import {apiScope} from './connection.mjs';
+const object=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+const positive=value=>Number.isSafeInteger(value)&&value>0;
+const fail=message=>{throw Error(`Member entry date: ${message}`);};
+const equal=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+function instant(value){
+ if(typeof value!=='string'||!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.000)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)||!Number.isFinite(Date.parse(value))||new Date(value.slice(0,19)+'Z').toISOString().slice(0,19)!==value.slice(0,19))fail('timezone-qualified whole-second date required');
+ return new Date(value).toISOString();
+}
+function ids(values){
+ if(!Array.isArray(values)||!values.length||values.some(value=>!positive(value))||new Set(values).size!==values.length)fail('unique positive IDs required');
+ return [...values].sort((a,b)=>a-b);
+}
+function identity(value){
+ if(!object(value)||!positive(value.clientId)||!positive(value.enrollmentId))fail('member identity required');
+ return {clientId:value.clientId,enrollmentId:value.enrollmentId};
+}
+function exit(value){
+ const target=identity(value),clientIds=ids(value.clientIds),enrollmentIds=ids(value.enrollmentIds);
+ if(!clientIds.includes(target.clientId)||!enrollmentIds.includes(target.enrollmentId))fail('exit subgroup omits member');
+ const result={...target,projectExitDate:value.projectExitDate===null?null:instant(value.projectExitDate)};
+ for(const field of ['destination','destinationCode','reasonForLeaving','reasonForLeavingCode','exitSubgroupId']){
+  if(value[field]!==null&&(typeof value[field]!=='string'||!value[field]))fail('complete exit metadata required');
+  result[field]=value[field];
+ }
+ return {...result,clientIds,enrollmentIds};
+}
+function normalize(input){
+ const target=identity(input);
+ if(!positive(input.providerId)||!['HUD','VA'].includes(input.type)||!Array.isArray(input.cohort)||input.cohort.length<2)fail('program and complete household cohort required');
+ const entryDate=instant(input.entryDate),cohort=input.cohort.map(member=>({ ...identity(member),entryDate:instant(member.entryDate),exit:exit(member.exit)})).sort((a,b)=>a.clientId-b.clientId);
+ ids(cohort.map(m=>m.clientId));ids(cohort.map(m=>m.enrollmentId));
+ for(const member of cohort)if(member.exit.clientId!==member.clientId||member.exit.enrollmentId!==member.enrollmentId)fail('exit identity mismatch');
+ const member=cohort.find(m=>m.clientId===target.clientId&&m.enrollmentId===target.enrollmentId);
+ if(!member||member.exit.projectExitDate!==null||Date.parse(entryDate)<Date.parse(member.entryDate))fail('open target and non-decreasing entry date required');
+ return {...target,providerId:input.providerId,type:input.type,entryDate,cohort};
+}
+
+/** Date-only REST port, verified through fresh GWT reads. The caller must
+ * durably journal before save and reconcile uncertain responses. Never retries. */
+export function createMemberEntryDatePort({api,enrollmentSession}){
+ apiScope(api, enrollmentSession);
+ if(typeof api.enrollments?.updateEntryAssessment!=='function'||typeof enrollmentSession?.readEnrollment!=='function')fail('REST API and authoritative enrollment reader required');
+ const inspect=async(input,after=false)=>{
+  const wantedMembers=input.cohort.map(identity),wantedExits=input.cohort.map(m=>m.exit);let alreadyPresent=false;
+  for(const member of input.cohort){
+   const snapshot=await enrollmentSession.readEnrollment(identity(member));
+   if(snapshot?.source!=='gwt-rpc'||snapshot.tenant!==api.tenant||snapshot.clientId!==member.clientId||snapshot.enrollmentId!==member.enrollmentId||snapshot.providerId!==input.providerId||snapshot.enrollmentType!==input.type)fail('authoritative enrollment context mismatch');
+   if(!Array.isArray(snapshot.members)||!Array.isArray(snapshot.exits))fail('complete enrollment membership and exits required');
+   const members=snapshot.members.map(identity).sort((a,b)=>a.clientId-b.clientId),exits=snapshot.exits.map(exit).sort((a,b)=>a.clientId-b.clientId);
+   if(!equal(members,wantedMembers)||!equal(exits,wantedExits))fail('cohort membership or exit metadata changed');
+   const actual=instant(snapshot.projectStartDate),isTarget=member.clientId===input.clientId;
+   if(isTarget){
+    alreadyPresent=actual===input.entryDate;
+    if(!alreadyPresent&&(after||actual!==member.entryDate))fail('target entry date changed unexpectedly');
+    if(!Array.isArray(snapshot.reviews)||snapshot.reviews.some(r=>!positive(r.reviewId)||typeof r.type!=='string'||!r.type||Date.parse(instant(r.reviewDate))<Date.parse(input.entryDate)))fail('target review precedes requested entry or is incomplete');
+   }else if(actual!==member.entryDate)fail('existing member entry date changed');
+  }
+  return alreadyPresent;
+ };
+ return {
+  async validateMemberEntryDate(raw){await inspect(normalize(raw));},
+  async saveMemberEntryDate(raw){
+   const input=normalize(raw);if(await inspect(input))return;
+   // Swagger makes all other fields optional. Omitting them avoids provider,
+   // type, assessment answer and assessment effective-date updates.
+   await api.enrollments.updateEntryAssessment({query:{enrollment_id:input.enrollmentId},body:{projectStartDate:input.entryDate}});
+   await inspect(input,true);
+  },
+ };
+}