@choiceapps/communityservices-sdk 0.5.0 → 0.7.0

package/docs/reference.md

@@ -8,13 +8,14 @@ Only the package export paths below are supported import entry points. Declarati
 
 Import from `@choiceapps/communityservices-sdk`, `@choiceapps/communityservices-sdk/v3`, or `@choiceapps/communityservices-sdk/v2`. The root selects V3 and also exports the testing helpers. Each version supplies its own generated HTTP models and fixed version header.
 
-Runtime exports at the root: `AmbiguousCommitError`, `AssessmentMetadata`, `AuthError`, `CooldownError`, `DefinitionDriftError`, `FakeControl`, `FakeWellSkyClient`, `GwtEnrollmentConflictError`, `GwtEnrollmentHelpers`, `SubassessmentEditor`, `TenantMismatchError`, `ThrottledError`, `UnknownPicklistValueError`, `UpstreamError`, `ValidationError`, `WellSkyClient`, `WellSkyError`, `apiVersion`, `buildAssessmentDefinition`, `compareDefinition`, `createFakeWellSkyClient`, `createInMemoryGwtMutationStore`, `createWellSkyClient`, `encodeAnswers`, `encodeNewSubassessmentRow`, `flattenQuestions`, `mapBulk`, `operationRoutes`, `parseRestInstant`, `readEnrollmentVerifications`, `readOutcome`, `readProgramCatalog`, `resolvePicklistOption`, `semanticHash`, `specSha256`, `toItems`, `verifyWrite`.
+Runtime exports at the root: `MobileAnswerPreflightError`, `writeMobileAnswersChecked`, `createReadBackWriteLabelResolver`, `AmbiguousCommitError`, `AssessmentMetadata`, `AuthError`, `CooldownError`, `DefinitionDriftError`, `FakeControl`, `FakeWellSkyClient`, `GwtEnrollmentConflictError`, `GwtEnrollmentHelpers`, `SubassessmentEditor`, `TenantMismatchError`, `ThrottledError`, `UnknownPicklistValueError`, `UpstreamError`, `ValidationError`, `WellSkyClient`, `WellSkyError`, `apiVersion`, `buildAssessmentDefinition`, `compareDefinition`, `createFakeWellSkyClient`, `createInMemoryGwtMutationStore`, `createWellSkyClient`, `encodeAnswers`, `encodeNewSubassessmentRow`, `flattenQuestions`, `mapBulk`, `operationRoutes`, `parseRestInstant`, `readEnrollmentVerifications`, `readOutcome`, `readProgramCatalog`, `resolvePicklistOption`, `semanticHash`, `specSha256`, `toItems`, `verifyWrite`.
 
 | Contract | Declaration | Guide |
 | --- | --- | --- |
 | HTTP clients and generated models | [V3](../dist/esm/generated/v3.d.ts), [V2](../dist/esm/generated/v2.d.ts) | [REST](rest-client.md), [API table](../API.md) |
 | Authentication, transport, responses and errors | [Runtime](../dist/esm/runtime.d.ts) | [Configuration](configuration.md), [recovery](troubleshooting.md) |
 | Metadata and picklists | [Metadata](../dist/esm/metadata.d.ts) | [Assessments](assessments.md) |
+| Checked mobile inserts and exact lookup labels | [Preflight](../dist/esm/mobile-preflight.d.ts), [labels](../dist/esm/write-labels.d.ts) | [Assessments](assessments.md) |
 | Answer encoding | [Encoding](../dist/esm/encoding.d.ts) | [Dates and answers](dates-and-answers.md) |
 | Write verification | [Verification](../dist/esm/verification.d.ts) | [REST](rest-client.md) |
 | Program catalog | [Program discovery](../dist/esm/program-discovery.d.ts) | [Enrollments](enrollments.md) |
@@ -36,7 +37,7 @@ Runtime exports: `AttachmentConflictError`, `CoordinatedEntryEventConflictError`
 | Profile fields and Sex | [Client profile](../browser/client-profile.d.mts) | `read`, `update` |
 | Calendar DOB | [Birth dates](../browser/date-of-birth.d.mts) | `read`, `validate`, `verify`, `update` |
 | Provider assessment defaults | [Discovery](../browser/program-discovery.d.mts) | `listAssessments`, `getProviderAssessments` |
-| Enrollment and household lifecycle | [Workflow](../browser/enrollment-workflow.d.mts) | Discovery, entry, `correctEntry`, `adoptEnrollment`, `adoptHouseholdEnrollment`, member additions, interim, `exitEnrollment`, `exitHousehold`, journal status; `EntryExitType` and per-type `assessmentLocations` in [enrollments](enrollments.md) |
+| Enrollment and household lifecycle | [Workflow](../browser/enrollment-workflow.d.mts) | Discovery, entry, `correctEntry`, `resolveEntryCorrection`, `adoptEnrollment`, `adoptHouseholdEnrollment`, `discoverHouseholdEnrollment`, `registerEntryRows`, member additions, interim, `exitEnrollment`, `exitHousehold`, journal status; `EntryExitType` and per-type `assessmentLocations` in [enrollments](enrollments.md) |
 | Entry-date and exit UI ports | [Member entry](../browser/member-entry-date.d.mts), [exit](../browser/household-exit.d.mts) | Fresh reads and targeted completion |
 | Services and recovery diagnostics | [Service recording](../browser/service-recording.d.mts) | `record`, `recordBulk`, Funding Sources, `RecoveryDiagnostic` |
 | SSVF conditional rules | [SSVF types](../browser/ssvf-rules.d.mts) | [Field rules](../SSVF.md) and dated option snapshots |

package/docs/troubleshooting.md

@@ -28,6 +28,9 @@ Successful adoption of an existing record also needs its journal. Retain it even
 | `DefinitionDriftError`, `UnknownPicklistValueError` | Metadata or lookup assumption changed | Refresh/review definitions and application mapping. Do not guess a numeric option |
 | `AmbiguousCommitError` | Mutation outcome not established | Keep journal pending; re-read through the workflow's authoritative path |
 | `GwtEnrollmentConflictError` | Duplicate/partial/conflicting enrollment or review | Inspect membership and review instant. Do not replay the captured request |
+| `UNSUPPORTED_YES_NO_CLEAR` | A correction attempted to blank a yes/no field | Fix the plan before any write; `No` and blank are different states |
+| `ENTRY_CORRECTION_UNCERTAIN` | An attempted correction is not verified | Inspect `status`, `cause`, and journal step diagnostics; use [explicit resolution](enrollments.md#resolve-a-rejected-correction) only with independent non-application evidence |
+| `ENTRY_CORRECTION_REJECTED` | The old correction key was resolved as not applied | Keep its audit record and use a new key for corrected intent |
 | `EnrollmentWorkflowError` | Invalid plan, missing head, schema drift, conflict, or unresolved stage | Inspect the specific reason and local status; fix application inputs only before reservation, otherwise reconcile original intent |
 | `SessionInterruptedError`, `SESSION_INTERRUPTED` | Managed page operation ended around session expiry | Check `reauthenticated`; retry the original workflow call, never its prepared RPC |
 | `LoginError`, `PASSWORD_EXPIRED` | Expiration detected with recovery disabled | Use the documented recovery option or resolve the password outside the helper |
@@ -43,6 +46,23 @@ Successful adoption of an existing record also needs its journal. Retain it even
 
 Not every browser helper error is a `WellSkyError`; some validation/UI failures are ordinary `Error` objects. `verifyWrite` returns a discriminated result rather than using a thrown error as its success contract. Its `unverified` result may already be committed.
 
+## Workflow error codes
+
+Enrollment workflow errors expose stable `code` values. Common actionable codes include:
+
+| Code | Meaning |
+| --- | --- |
+| `ADOPTION_HOUSEHOLD_HEAD_MISMATCH` | The supplied head does not match the verified enrollment cohort |
+| `INDEPENDENT_CONFIRMATION_REQUIRED` | Resolution lacks independent confirmation of non-application |
+| `UNSUPPORTED_YES_NO_CLEAR` | A correction requests blanking a yes/no answer; no supported route is verified |
+| `ENTRY_CORRECTION_UNCERTAIN` | An attempted correction needs reconciliation; never resend it blindly |
+| `MOBILE_ANSWER_EXISTS` | A scalar row already occupies the requested mobile effective instant |
+| `MOBILE_PREFLIGHT_UNAVAILABLE` | The read cannot establish whether a scalar insert is safe |
+
+The [workflow code table](../browser/workflow-error-codes.mjs) maps existing reasons to codes; new guards supply explicit codes. `committed: false` identifies a pre-write refusal for the named operation. `'unknown'` requires journal/readback reconciliation. Resolution errors separately retain `originalCommitted: 'unknown'` for the original correction. HTTP status and causes are exposed where captured; they are not proof of non-application.
+
+Pending 0.5.0 corrections may have no saved `failure` kind or status. Keep your own original failure evidence for the confirmation callback. Do not repeat the write to recover missing diagnostics.
+
 ## Inspect an upstream error privately
 
 By default the transport discards HTTP error bodies because they can contain client data or credentials. For a controlled diagnostic session, construct `WellSkyClient` with `captureErrorBody: true`. An `UpstreamError` then exposes `responseBody` and `responseBodyTruncated`. The body is capped at 16,384 characters, retained in memory, and excluded from the error's enumerable properties, JSON serialization, and transport hooks/logger events. HTTP 401, 403, 429 and SetAuthKey authentication responses are excluded even with capture enabled. Raw bodies can still contain private information; inspect them through an access-controlled debugger or application diagnostic sink, not ordinary logs.

package/examples/README.md

@@ -15,6 +15,8 @@ Every file here ships with the package and imports the public `@choiceapps/commu
 | [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 |
 | [individual-exit-workflow.mts](individual-exit-workflow.mts) | Standalone program enrollment exit and assessment | Verified entry key, enrollment reader, exit UI port and durable store required |
+| [checked-assessment-writes.mts](checked-assessment-writes.mts) | Exact readback lookup labels and checked mobile scalar inserts | Unobserved labels remain unresolved; preflight does not make writes atomic |
+| [enrollment-discovery-and-correction.mts](enrollment-discovery-and-correction.mts) | Discover/adopt from the head and bind existing correction rows | Explicit row IDs and unique verified household membership required |
 | [entry-correction-workflow.mts](entry-correction-workflow.mts) | Same-date scalar clears and existing row edits | Original entry/row keys, verified lookup labels and durable store required |
 | [existing-enrollment-exits.mts](existing-enrollment-exits.mts) | Adopt manual individual or household entries, then exit | Explicit enrollment identities and original household head required |
 | [household-enrollment-workflow.mts](household-enrollment-workflow.mts) | Per-member enrollment and review | Existing household and per-member answer plans required |

package/examples/checked-assessment-writes.mts

@@ -0,0 +1,14 @@
+import {
+ createReadBackWriteLabelResolver,writeMobileAnswersChecked,
+ type AssessmentDefinition,type WriteLabelObservation,type CheckedMobileWriteOptions,type WellSkyClient,
+} from '@choiceapps/communityservices-sdk';
+
+/** Observations must come from the definition's tenant. Unobserved options stay unresolved. */
+export function exactWriteLabels(definition:AssessmentDefinition,observations:WriteLabelObservation[]){
+ return createReadBackWriteLabelResolver(definition,observations);
+}
+
+/** Pass the original requested instant; the SDK transport owns any configured mobile date correction. */
+export async function insertMobileAnswers(api:WellSkyClient,input:CheckedMobileWriteOptions){
+ return writeMobileAnswersChecked(api,input);
+}

package/examples/enrollment-discovery-and-correction.mts

@@ -0,0 +1,19 @@
+import {createEnrollmentWorkflow,type EnrollmentWorkflowOptions,type EntryCorrectionInput} from '@choiceapps/communityservices-sdk/browser';
+
+/** The head's explicit target identifies a cohort; ambiguous household matches fail. */
+export async function adoptFromHead(dependencies:EnrollmentWorkflowOptions,input:{key:string;headClientId:number;headEnrollmentId:number}){
+ const workflow=createEnrollmentWorkflow(dependencies);
+ const discovery=await workflow.discoverHouseholdEnrollment({headClientId:input.headClientId,headEnrollmentId:input.headEnrollmentId});
+ const adopted=await workflow.adoptHouseholdEnrollment(input);
+ return {discovery,adopted};
+}
+
+/** Select IDs from an authorized assessment read. The SDK never guesses a row by date/value. */
+export async function bindAndCorrectManualRows(
+ dependencies:EnrollmentWorkflowOptions,
+ input:{registrationKey:string;correction:EntryCorrectionInput;rows:Array<{key:string;parentField:string;recordsetId:number}>},
+){
+ const workflow=createEnrollmentWorkflow(dependencies),{clientId,enrollmentKey}=input.correction;
+ await workflow.registerEntryRows({key:input.registrationKey,clientId,enrollmentKey,rows:input.rows});
+ return workflow.correctEntry(input.correction);
+}

package/examples/entry-correction-workflow.mts

@@ -2,6 +2,7 @@ import {
  createEnrollmentWorkflow,
  type EnrollmentWorkflowOptions,
  type EntryCorrectionInput,
+  type ResolveEntryCorrectionInput,
 } from '@choiceapps/communityservices-sdk/browser';
 
 /** The application supplies explicit answers, clears and original row keys.
@@ -12,3 +13,10 @@ export async function correctOriginalEntry(dependencies:EnrollmentWorkflowOption
  const workflow=createEnrollmentWorkflow(dependencies);
  return workflow.correctEntry(input);
 }
+
+/** The confirmation callback must use independent server or administrative evidence.
+ * The SDK also checks the complete pre-write state before and after that callback.
+ * Retain the rejected key; submit a corrected request under a new key afterward. */
+export async function resolveRejectedCorrection(dependencies:EnrollmentWorkflowOptions,input:ResolveEntryCorrectionInput){
+ return createEnrollmentWorkflow(dependencies).resolveEntryCorrection(input);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@choiceapps/communityservices-sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "SDK for WellSky Community Services (HMIS), formerly ServicePoint, Client API V2 and V3",
   "type": "module",
   "main": "./dist/cjs/index.js",