policyengine-household-wizard 0.1.0

package/src/us-household/draft.ts

@@ -0,0 +1,130 @@
+import type { USHouseholdDraft, USPersonDraft, USPersonKind } from './types';
+
+export const DEFAULT_HOUSEHOLD_YEAR = new Date().getUTCFullYear();
+
+const ADULT_PREFIX = 'adult';
+const DEPENDENT_PREFIX = 'dependent';
+
+function nextPersonId(people: USPersonDraft[], kind: USPersonKind): string {
+  const prefix = kind === 'adult' ? ADULT_PREFIX : DEPENDENT_PREFIX;
+  const ids = new Set(people.map((person) => person.id));
+  let candidate = `${prefix}-1`;
+  let counter = 1;
+  while (ids.has(candidate)) {
+    counter += 1;
+    candidate = `${prefix}-${counter}`;
+  }
+  return candidate;
+}
+
+/**
+ * Returns a draft with no defaults for state, ages, or marital status. The
+ * wizard must explicitly capture each of these before the household is valid.
+ *
+ * `year` defaults to the current UTC year so calculations have a target period;
+ * apps that want a fixed year can pass one in.
+ */
+export function createBlankDraft(year: number = DEFAULT_HOUSEHOLD_YEAR): USHouseholdDraft {
+  return {
+    state: null,
+    county: null,
+    zip: null,
+    maritalStatus: null,
+    people: [],
+    year,
+  };
+}
+
+/**
+ * Returns a deep clone of an existing draft. Used by apps that want to keep an
+ * "edit baseline" separate from the in-progress draft.
+ */
+export function cloneDraft(draft: USHouseholdDraft): USHouseholdDraft {
+  return {
+    state: draft.state,
+    county: draft.county,
+    zip: draft.zip,
+    maritalStatus: draft.maritalStatus,
+    year: draft.year,
+    extras: draft.extras ? structuredClone(draft.extras) : undefined,
+    people: draft.people.map((person) => ({
+      ...person,
+      extras: person.extras ? structuredClone(person.extras) : undefined,
+    })),
+  };
+}
+
+export function createPerson(
+  kind: USPersonKind,
+  existingPeople: USPersonDraft[] = [],
+  partial: Partial<USPersonDraft> = {},
+): USPersonDraft {
+  return {
+    id: partial.id ?? nextPersonId(existingPeople, kind),
+    kind,
+    age: partial.age ?? null,
+    ...partial,
+  };
+}
+
+export function addPerson(
+  draft: USHouseholdDraft,
+  kind: USPersonKind,
+  partial: Partial<USPersonDraft> = {},
+): USHouseholdDraft {
+  const newPerson = createPerson(kind, draft.people, partial);
+  return { ...draft, people: [...draft.people, newPerson] };
+}
+
+export function removePerson(draft: USHouseholdDraft, personId: string): USHouseholdDraft {
+  return { ...draft, people: draft.people.filter((person) => person.id !== personId) };
+}
+
+export function updatePerson(
+  draft: USHouseholdDraft,
+  personId: string,
+  changes: Partial<USPersonDraft>,
+): USHouseholdDraft {
+  return {
+    ...draft,
+    people: draft.people.map((person) =>
+      person.id === personId ? { ...person, ...changes } : person,
+    ),
+  };
+}
+
+export function getAdults(draft: USHouseholdDraft): USPersonDraft[] {
+  return draft.people.filter((person) => person.kind === 'adult');
+}
+
+export function getDependents(draft: USHouseholdDraft): USPersonDraft[] {
+  return draft.people.filter((person) => person.kind === 'dependent');
+}
+
+/**
+ * Reconcile the people array with the chosen marital status. Switching to
+ * "married" with one adult adds a partner; switching to "single" with two or
+ * more adults removes the trailing adults beyond the first.
+ */
+export function applyMaritalStatusChange(
+  draft: USHouseholdDraft,
+  maritalStatus: USHouseholdDraft['maritalStatus'],
+): USHouseholdDraft {
+  if (maritalStatus === draft.maritalStatus) {
+    return draft;
+  }
+
+  const adults = getAdults(draft);
+  let next: USHouseholdDraft = { ...draft, maritalStatus };
+
+  if (maritalStatus === 'married' && adults.length < 2) {
+    next = addPerson(next, 'adult');
+  } else if (maritalStatus === 'single' && adults.length > 1) {
+    const extras = adults.slice(1);
+    for (const extra of extras) {
+      next = removePerson(next, extra.id);
+    }
+  }
+
+  return next;
+}

package/src/us-household/index.ts

@@ -0,0 +1,59 @@
+export type {
+  USHouseholdDraft,
+  USMaritalStatus,
+  USPersonDraft,
+  USPersonFlags,
+  USPersonIncomes,
+  USPersonKind,
+  ValidationIssue,
+  ValidationResult,
+} from './types';
+
+export {
+  DEFAULT_HOUSEHOLD_YEAR,
+  createBlankDraft,
+  cloneDraft,
+  createPerson,
+  addPerson,
+  removePerson,
+  updatePerson,
+  getAdults,
+  getDependents,
+  applyMaritalStatusChange,
+} from './draft';
+
+export { normalizeLegacyDraft } from './normalize';
+export { validate, isComplete, type ValidateOptions } from './validate';
+export { serializeDraft, deserializeDraft } from './serialize';
+
+export {
+  US_STATES,
+  isUSStateCode,
+  getStateName,
+  getStateFromZip,
+  type USState,
+} from './states';
+
+export {
+  getCountiesByState,
+  getCountyName,
+  isCountyCode,
+  resolveCountyCode,
+  type County,
+} from './counties';
+
+export {
+  toV1HouseholdPayload,
+  toV1HouseholdSituation,
+  type V1HouseholdEnvelope,
+  type V1HouseholdSituation,
+  type V1ValueMap,
+  type V1FieldValue,
+  type V1PersonRecord,
+  type V1GroupRecord,
+  type V1PersonCollection,
+  type V1GroupCollection,
+  type V1EntityRecord,
+  type V1EntityCollection,
+  type ToV1PayloadOptions,
+} from './adapters/v1Payload';

package/src/us-household/normalize.ts

@@ -0,0 +1,251 @@
+import { resolveCountyCode } from './counties';
+import { getStateFromZip, isUSStateCode } from './states';
+import { DEFAULT_HOUSEHOLD_YEAR, createBlankDraft } from './draft';
+import type {
+  USHouseholdDraft,
+  USMaritalStatus,
+  USPersonDraft,
+  USPersonKind,
+} from './types';
+
+/**
+ * Map a legacy filing status to marital status. This is intentionally
+ * one-directional: the shared draft only carries marital status because the
+ * issue calls out asking users marital status (not filing status) in UI.
+ */
+function filingStatusToMaritalStatus(value: unknown): USMaritalStatus | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const normalized = value.toLowerCase();
+  if (normalized.includes('married') && !normalized.includes('separately')) {
+    return 'married';
+  }
+  if (normalized === 'married_jointly' || normalized === 'married_separately') {
+    return 'married';
+  }
+  if (
+    normalized === 'mfj' ||
+    normalized === 'mfs' ||
+    normalized === 'joint' ||
+    normalized === 'separate'
+  ) {
+    return 'married';
+  }
+  if (
+    normalized === 'single' ||
+    normalized === 'head_of_household' ||
+    normalized === 'hoh' ||
+    normalized === 'widowed' ||
+    normalized === 'qualifying_widower' ||
+    normalized === 'qualifying_widow_widower' ||
+    normalized === 'qualifying_surviving_spouse'
+  ) {
+    return 'single';
+  }
+  return null;
+}
+
+interface LegacyPerson {
+  age?: number | string | null;
+  kind?: USPersonKind | 'child';
+  isDisabled?: boolean;
+  is_disabled?: boolean;
+  isBlind?: boolean;
+  is_blind?: boolean;
+  isFullTimeStudent?: boolean;
+  is_full_time_student?: boolean;
+  isPregnant?: boolean;
+  is_pregnant?: boolean;
+  needsCare?: boolean;
+  is_incapable_of_self_care?: boolean;
+  earned_income?: number;
+  employment_income?: number;
+  employmentIncome?: number;
+  self_employment_income_annual?: number;
+  ssi_amount?: number;
+  ssdi_amount?: number;
+  ssiAmount?: number;
+  ssdiAmount?: number;
+  social_security_annual?: number;
+}
+
+interface LegacyDraftShape {
+  state?: string | null;
+  county?: string | null;
+  zip?: string | null;
+  zipCode?: string | null;
+  maritalStatus?: string | null;
+  marital_status?: string | null;
+  filingStatus?: string | null;
+  filing_status?: string | null;
+  people?: LegacyPerson[];
+  childAges?: Array<number | string | null>;
+  child_ages?: Array<number | string | null>;
+  age?: number | string | null;
+  partnerAge?: number | string | null;
+  spouseAge?: number | string | null;
+  year?: number;
+}
+
+function coerceAge(value: unknown): number | null {
+  if (value === null || value === undefined || value === '') {
+    return null;
+  }
+  const parsed = typeof value === 'number' ? value : parseInt(String(value), 10);
+  if (Number.isFinite(parsed)) {
+    return parsed;
+  }
+  return null;
+}
+
+function coerceNumber(value: unknown): number | undefined {
+  if (value === null || value === undefined || value === '') {
+    return undefined;
+  }
+  const parsed = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function coerceBoolean(value: unknown): boolean | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  return Boolean(value);
+}
+
+function normalizePerson(
+  legacy: LegacyPerson,
+  ordinal: number,
+  kind: USPersonKind,
+): USPersonDraft {
+  const id =
+    kind === 'adult' ? `adult-${ordinal}` : `dependent-${ordinal}`;
+  return {
+    id,
+    kind,
+    age: coerceAge(legacy.age),
+    isDisabled: coerceBoolean(legacy.isDisabled ?? legacy.is_disabled),
+    isBlind: coerceBoolean(legacy.isBlind ?? legacy.is_blind),
+    isFullTimeStudent: coerceBoolean(
+      legacy.isFullTimeStudent ?? legacy.is_full_time_student,
+    ),
+    isPregnant: coerceBoolean(legacy.isPregnant ?? legacy.is_pregnant),
+    needsCare: coerceBoolean(legacy.needsCare ?? legacy.is_incapable_of_self_care),
+    employmentIncome:
+      coerceNumber(legacy.employmentIncome) ??
+      coerceNumber(legacy.employment_income) ??
+      coerceNumber(legacy.earned_income),
+    selfEmploymentIncome: coerceNumber(legacy.self_employment_income_annual),
+    ssiAmount: coerceNumber(legacy.ssiAmount ?? legacy.ssi_amount),
+    ssdiAmount: coerceNumber(legacy.ssdiAmount ?? legacy.ssdi_amount),
+    socialSecurityIncome: coerceNumber(legacy.social_security_annual),
+  };
+}
+
+/**
+ * Best-effort normalization from legacy household shapes (cliff-watch's people
+ * array, Coverage Compass's flat fields, ad-hoc test fixtures) into the shared
+ * draft contract. Unknown fields are dropped silently; apps that need to keep
+ * extras should hand-edit the result.
+ */
+export function normalizeLegacyDraft(
+  raw: unknown,
+  options: { year?: number } = {},
+): USHouseholdDraft {
+  if (!raw || typeof raw !== 'object') {
+    return createBlankDraft(options.year);
+  }
+  const legacy = raw as LegacyDraftShape;
+  const draft = createBlankDraft(options.year ?? legacy.year ?? DEFAULT_HOUSEHOLD_YEAR);
+
+  // Location.
+  if (typeof legacy.state === 'string' && isUSStateCode(legacy.state)) {
+    draft.state = legacy.state;
+  } else if (legacy.zipCode || legacy.zip) {
+    const derived = getStateFromZip(legacy.zip ?? legacy.zipCode ?? null);
+    if (derived) {
+      draft.state = derived;
+    }
+  }
+  draft.zip = legacy.zip ?? legacy.zipCode ?? null;
+
+  if (legacy.county) {
+    draft.county = resolveCountyCode(draft.state, legacy.county);
+  }
+
+  // Marital status — prefer explicit, fall back to filing status mapping.
+  const explicit =
+    legacy.maritalStatus ?? legacy.marital_status ?? null;
+  if (typeof explicit === 'string') {
+    const lower = explicit.toLowerCase();
+    if (lower === 'married' || lower === 'unmarried' || lower === 'single') {
+      draft.maritalStatus = lower === 'married' ? 'married' : 'single';
+    } else {
+      draft.maritalStatus = filingStatusToMaritalStatus(explicit);
+    }
+  } else {
+    const filing = legacy.filingStatus ?? legacy.filing_status;
+    draft.maritalStatus = filingStatusToMaritalStatus(filing);
+  }
+
+  // People — accept either a people array or coverage-compass-style flat fields.
+  if (Array.isArray(legacy.people) && legacy.people.length > 0) {
+    let adultCount = 0;
+    let dependentCount = 0;
+    draft.people = legacy.people.map((legacyPerson) => {
+      const kind = legacyPerson.kind === 'child' ? 'dependent' : legacyPerson.kind ?? 'adult';
+      if (kind === 'adult') {
+        adultCount += 1;
+        return normalizePerson(legacyPerson, adultCount, 'adult');
+      }
+      dependentCount += 1;
+      return normalizePerson(legacyPerson, dependentCount, 'dependent');
+    });
+  } else {
+    const adults: USPersonDraft[] = [];
+    if (legacy.age !== undefined && legacy.age !== null) {
+      adults.push({
+        id: 'adult-1',
+        kind: 'adult',
+        age: coerceAge(legacy.age),
+      });
+    }
+    const partnerAge = legacy.partnerAge ?? legacy.spouseAge;
+    if (draft.maritalStatus === 'married' && partnerAge !== undefined && partnerAge !== null) {
+      adults.push({
+        id: 'adult-2',
+        kind: 'adult',
+        age: coerceAge(partnerAge),
+      });
+    }
+    const dependents: USPersonDraft[] = [];
+    const childAges = legacy.childAges ?? legacy.child_ages;
+    if (Array.isArray(childAges)) {
+      childAges.forEach((childAge, index) => {
+        dependents.push({
+          id: `dependent-${index + 1}`,
+          kind: 'dependent',
+          age: coerceAge(childAge),
+        });
+      });
+    }
+    draft.people = [...adults, ...dependents];
+  }
+
+  // If marital status is married but only one adult, add a partner with blank
+  // age so the wizard can prompt for it. If single but extra adults, trim.
+  const adults = draft.people.filter((person) => person.kind === 'adult');
+  if (draft.maritalStatus === 'married' && adults.length < 2) {
+    draft.people = [
+      ...draft.people,
+      { id: 'adult-2', kind: 'adult', age: null },
+    ];
+  } else if (draft.maritalStatus === 'single' && adults.length > 1) {
+    const [keep] = adults;
+    const dependents = draft.people.filter((person) => person.kind === 'dependent');
+    draft.people = [keep, ...dependents];
+  }
+
+  return draft;
+}

package/src/us-household/serialize.ts

@@ -0,0 +1,153 @@
+import { createBlankDraft } from './draft';
+import type { USHouseholdDraft, USPersonDraft } from './types';
+
+/**
+ * Compact URL-safe serialization for the household draft. The format is
+ * stable: each app gets the same query-string shape, which lets us deep-link
+ * across apps that share the wizard.
+ *
+ * Format example: `state=CA&county=ALAMEDA_COUNTY_CA&marital=married&year=2026
+ *                  &p=adult:35:e50000,adult:33:e20000,dep:6`
+ *
+ * Fields are pipe-separated within each person; people are comma-separated.
+ * Income/flag keys are single letters to keep the URL short:
+ *   - `e` = employmentIncome
+ *   - `s` = ssiAmount
+ *   - `d` = ssdiAmount
+ *   - `D` = isDisabled
+ *   - `B` = isBlind
+ *   - `S` = isFullTimeStudent
+ *   - `P` = isPregnant
+ *   - `C` = needsCare
+ */
+
+const FLAG_KEYS: Array<[keyof USPersonDraft, string]> = [
+  ['isDisabled', 'D'],
+  ['isBlind', 'B'],
+  ['isFullTimeStudent', 'S'],
+  ['isPregnant', 'P'],
+  ['needsCare', 'C'],
+];
+
+const INCOME_KEYS: Array<[keyof USPersonDraft, string]> = [
+  ['employmentIncome', 'e'],
+  ['ssiAmount', 's'],
+  ['ssdiAmount', 'd'],
+];
+
+function serializePerson(person: USPersonDraft): string {
+  const segments: string[] = [
+    person.kind === 'adult' ? 'adult' : 'dep',
+    person.age === null || person.age === undefined ? '' : String(person.age),
+  ];
+  for (const [key, letter] of INCOME_KEYS) {
+    const value = person[key] as number | undefined;
+    if (value !== undefined && value !== null && value !== 0) {
+      segments.push(`${letter}${value}`);
+    }
+  }
+  for (const [key, letter] of FLAG_KEYS) {
+    if (person[key]) {
+      segments.push(letter);
+    }
+  }
+  return segments.join(':');
+}
+
+function parsePerson(raw: string): USPersonDraft | null {
+  const parts = raw.split(':');
+  if (parts.length === 0) {
+    return null;
+  }
+  const kindToken = parts[0];
+  const kind = kindToken === 'adult' ? 'adult' : kindToken === 'dep' ? 'dependent' : null;
+  if (!kind) {
+    return null;
+  }
+  const ageRaw = parts[1] ?? '';
+  const age = ageRaw === '' ? null : Number.parseInt(ageRaw, 10);
+  const person: USPersonDraft = {
+    id: `${kind === 'adult' ? 'adult' : 'dependent'}-?`,
+    kind,
+    age: Number.isFinite(age) ? (age as number) : null,
+  };
+  for (let i = 2; i < parts.length; i += 1) {
+    const token = parts[i];
+    if (token.length === 0) continue;
+    const letter = token[0];
+    const rest = token.slice(1);
+    const incomeMatch = INCOME_KEYS.find(([, l]) => l === letter);
+    if (incomeMatch) {
+      const value = Number.parseInt(rest, 10);
+      if (Number.isFinite(value)) {
+        (person as unknown as Record<string, unknown>)[incomeMatch[0]] = value;
+      }
+      continue;
+    }
+    const flagMatch = FLAG_KEYS.find(([, l]) => l === letter);
+    if (flagMatch) {
+      (person as unknown as Record<string, unknown>)[flagMatch[0]] = true;
+    }
+  }
+  return person;
+}
+
+export function serializeDraft(draft: USHouseholdDraft): string {
+  const params = new URLSearchParams();
+  if (draft.state) params.set('state', draft.state);
+  if (draft.county) params.set('county', draft.county);
+  if (draft.zip) params.set('zip', draft.zip);
+  if (draft.maritalStatus) params.set('marital', draft.maritalStatus);
+  params.set('year', String(draft.year));
+  if (draft.people.length > 0) {
+    params.set('p', draft.people.map(serializePerson).join(','));
+  }
+  return params.toString();
+}
+
+export function deserializeDraft(query: string | URLSearchParams): USHouseholdDraft {
+  const params = typeof query === 'string' ? new URLSearchParams(query) : query;
+  const draft = createBlankDraft();
+
+  const state = params.get('state');
+  if (state) draft.state = state;
+
+  const county = params.get('county');
+  if (county) draft.county = county;
+
+  const zip = params.get('zip');
+  if (zip) draft.zip = zip;
+
+  const marital = params.get('marital');
+  if (marital === 'married' || marital === 'single') {
+    draft.maritalStatus = marital;
+  }
+
+  const yearRaw = params.get('year');
+  if (yearRaw) {
+    const year = Number.parseInt(yearRaw, 10);
+    if (Number.isFinite(year)) {
+      draft.year = year;
+    }
+  }
+
+  const peopleRaw = params.get('p');
+  if (peopleRaw) {
+    let adultCount = 0;
+    let dependentCount = 0;
+    draft.people = peopleRaw
+      .split(',')
+      .map(parsePerson)
+      .filter((person): person is USPersonDraft => person !== null)
+      .map((person) => {
+        if (person.kind === 'adult') {
+          adultCount += 1;
+          return { ...person, id: `adult-${adultCount}` };
+        }
+        dependentCount += 1;
+        return { ...person, id: `dependent-${dependentCount}` };
+      });
+  }
+
+  return draft;
+}