policyengine-household-wizard 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. package/README.md +50 -5
  2. package/dist/WizardReviewList-DhLx8Bla.cjs +1 -0
  3. package/dist/WizardReviewList-oY1HqmLw.js +354 -0
  4. package/dist/index-B_OXaS4a.cjs +1 -0
  5. package/dist/index-CIL8FXNR.cjs +1 -0
  6. package/dist/index-DWM0giHt.js +220 -0
  7. package/dist/index-fgLnXugs.js +225 -0
  8. package/dist/index.cjs +1 -1
  9. package/dist/index.d.ts +2 -2
  10. package/dist/index.js +34 -28
  11. package/dist/primitives/WizardReviewList.d.ts +3 -2
  12. package/dist/primitives/WizardReviewList.d.ts.map +1 -1
  13. package/dist/primitives/index.d.ts +12 -10
  14. package/dist/primitives/index.d.ts.map +1 -1
  15. package/dist/primitives/types.d.ts +18 -0
  16. package/dist/primitives/types.d.ts.map +1 -1
  17. package/dist/primitives/useWizardStepFocus.d.ts +13 -0
  18. package/dist/primitives/useWizardStepFocus.d.ts.map +1 -0
  19. package/dist/primitives/useWizardSteps.d.ts +2 -2
  20. package/dist/primitives/useWizardSteps.d.ts.map +1 -1
  21. package/dist/primitives.cjs +1 -1
  22. package/dist/primitives.d.ts +1 -1
  23. package/dist/primitives.js +5 -4
  24. package/dist/uk-household/adapters/householdImpactRequest.d.ts +91 -0
  25. package/dist/uk-household/adapters/householdImpactRequest.d.ts.map +1 -0
  26. package/dist/uk-household/adapters/index.d.ts +2 -0
  27. package/dist/uk-household/adapters/index.d.ts.map +1 -0
  28. package/dist/uk-household/children.d.ts +18 -0
  29. package/dist/uk-household/children.d.ts.map +1 -0
  30. package/dist/uk-household/codes.d.ts +22 -0
  31. package/dist/uk-household/codes.d.ts.map +1 -0
  32. package/dist/uk-household/defaults.d.ts +56 -0
  33. package/dist/uk-household/defaults.d.ts.map +1 -0
  34. package/dist/uk-household/draft.d.ts +37 -0
  35. package/dist/uk-household/draft.d.ts.map +1 -0
  36. package/dist/uk-household/index.d.ts +10 -0
  37. package/dist/uk-household/index.d.ts.map +1 -0
  38. package/dist/uk-household/serialize.d.ts +4 -0
  39. package/dist/uk-household/serialize.d.ts.map +1 -0
  40. package/dist/uk-household/statePension.d.ts +42 -0
  41. package/dist/uk-household/statePension.d.ts.map +1 -0
  42. package/dist/uk-household/types.d.ts +134 -0
  43. package/dist/uk-household/types.d.ts.map +1 -0
  44. package/dist/uk-household/validate.d.ts +59 -0
  45. package/dist/uk-household/validate.d.ts.map +1 -0
  46. package/dist/uk-household-adapters.cjs +1 -0
  47. package/dist/uk-household-adapters.d.ts +1 -0
  48. package/dist/uk-household-adapters.js +5 -0
  49. package/dist/uk-household.cjs +1 -0
  50. package/dist/uk-household.d.ts +1 -0
  51. package/dist/uk-household.js +220 -0
  52. package/dist/us-household/adapters/index.d.ts +1 -1
  53. package/dist/us-household/adapters/v1Payload.d.ts +119 -3
  54. package/dist/us-household/adapters/v1Payload.d.ts.map +1 -1
  55. package/dist/us-household/amount.d.ts +8 -0
  56. package/dist/us-household/amount.d.ts.map +1 -0
  57. package/dist/us-household/draft.d.ts +1 -1
  58. package/dist/us-household/index.d.ts +9 -8
  59. package/dist/us-household/index.d.ts.map +1 -1
  60. package/dist/us-household/normalize.d.ts +1 -1
  61. package/dist/us-household/normalize.d.ts.map +1 -1
  62. package/dist/us-household/serialize.d.ts +1 -1
  63. package/dist/us-household/serialize.d.ts.map +1 -1
  64. package/dist/us-household/tippedOccupations.d.ts +40 -0
  65. package/dist/us-household/tippedOccupations.d.ts.map +1 -0
  66. package/dist/us-household/types.d.ts +138 -18
  67. package/dist/us-household/types.d.ts.map +1 -1
  68. package/dist/us-household/validate.d.ts +1 -1
  69. package/dist/us-household/validate.d.ts.map +1 -1
  70. package/dist/us-household-adapters.cjs +1 -1
  71. package/dist/us-household-adapters.d.ts +1 -1
  72. package/dist/us-household-adapters.js +3 -90
  73. package/dist/us-household.cjs +1 -1
  74. package/dist/us-household.d.ts +1 -1
  75. package/dist/us-household.js +346 -246
  76. package/dist/validation.d.ts +16 -0
  77. package/dist/validation.d.ts.map +1 -0
  78. package/package.json +16 -2
  79. package/src/primitives/WizardReviewList.tsx +35 -18
  80. package/src/primitives/index.ts +3 -0
  81. package/src/primitives/types.ts +20 -0
  82. package/src/primitives/useWizardStepFocus.ts +42 -0
  83. package/src/primitives/useWizardSteps.ts +181 -84
  84. package/src/styles.css +9 -0
  85. package/src/uk-household/adapters/householdImpactRequest.ts +164 -0
  86. package/src/uk-household/adapters/index.ts +9 -0
  87. package/src/uk-household/children.ts +23 -0
  88. package/src/uk-household/codes.ts +67 -0
  89. package/src/uk-household/defaults.ts +101 -0
  90. package/src/uk-household/draft.ts +138 -0
  91. package/src/uk-household/index.ts +75 -0
  92. package/src/uk-household/serialize.ts +189 -0
  93. package/src/uk-household/statePension.ts +69 -0
  94. package/src/uk-household/types.ts +159 -0
  95. package/src/uk-household/validate.ts +190 -0
  96. package/src/us-household/adapters/v1Payload.ts +211 -18
  97. package/src/us-household/amount.ts +10 -0
  98. package/src/us-household/index.ts +11 -0
  99. package/src/us-household/normalize.ts +79 -4
  100. package/src/us-household/serialize.ts +5 -1
  101. package/src/us-household/tippedOccupations.ts +145 -0
  102. package/src/us-household/types.ts +144 -15
  103. package/src/us-household/validate.ts +101 -4
  104. package/src/validation.ts +12 -0
  105. package/dist/WizardReviewList-De9RTK_4.js +0 -245
  106. package/dist/WizardReviewList-tfP9LcqU.cjs +0 -1
@@ -1,6 +1,9 @@
1
+ import { toAmount } from '../amount';
2
+ import { toTippedOccupationCode } from '../tippedOccupations';
1
3
  import type {
2
4
  USHouseholdDraft,
3
5
  USPersonDraft,
6
+ USPersonExpenses,
4
7
  USPersonFlags,
5
8
  USPersonIncomes,
6
9
  } from '../types';
@@ -58,8 +61,10 @@ export interface ToV1PayloadOptions {
58
61
  */
59
62
  groupKeyStyle?: 'short' | 'verbose';
60
63
  /**
61
- * If true, attaches member ids to the marital unit. Off by default because
62
- * cliff-watch and other consumers send `marital_units: {}` and have it work.
64
+ * If true, puts the first two adults in one marital unit. Off by default for
65
+ * compatibility. With `marital_units: {}`, policyengine-core gives each
66
+ * person their own marital unit, so a married couple gets individual SSI
67
+ * rates instead of the couple rate; pass true for married drafts.
63
68
  */
64
69
  includeMaritalUnit?: boolean;
65
70
  /**
@@ -85,22 +90,121 @@ const VERBOSE_KEYS = {
85
90
  maritalUnit: 'your marital unit',
86
91
  } as const;
87
92
 
88
- const FLAG_TO_VARIABLE: Record<keyof USPersonFlags, string> = {
93
+ /*
94
+ * Variables PolicyEngine US computes must be sent for every person or for no
95
+ * one. policyengine-core stores one array per variable and period for a whole
96
+ * entity: the first person with an input allocates it, filled with the
97
+ * variable's default, so everyone without an input holds that default and the
98
+ * formula never runs for them. A `{year: null}` value does not help, because
99
+ * policyengine-core skips it. So each person gets input variables, which
100
+ * have no formula and whose stored default is what the model would use
101
+ * anyway, plus computed variables only when every person has an answer. The
102
+ * exceptions are `employment_income`, `self_employment_income` and
103
+ * `long_term_capital_gains`, computed totals that policyengine-us's Simulation
104
+ * moves onto the inputs `employment_income_before_lsr`,
105
+ * `self_employment_income_before_lsr` and
106
+ * `long_term_capital_gains_before_response` (reviewed in
107
+ * `REVIEWED_PARTIAL_COMPUTED` in the invariant tests).
108
+ *
109
+ * - `is_tax_unit_dependent` comes from `kind`, which every person has.
110
+ * - `isFullTimeStudent` is sent as the input `is_full_time_college_student`,
111
+ * not the computed `is_full_time_student`.
112
+ * - `ssi` is sent only when every person has an `ssiAmount`; an entered 0 is
113
+ * also sent as the input `takes_up_ssi_if_eligible: false`.
114
+ *
115
+ * `tests/us-household/v1PayloadInvariants.test.ts` checks this against the
116
+ * PolicyEngine US variable graph.
117
+ */
118
+
119
+ /**
120
+ * Person flags and the PolicyEngine US variables they set. Exported for tests
121
+ * and tooling; not part of the package entry points. Only true and false are
122
+ * sent; anything else (such as null in a JSON draft) counts as not answered.
123
+ *
124
+ * `is_full_time_student` is computed as `is_full_time_college_student` or
125
+ * `is_in_k12_school`, and the model counts everyone aged 5 to 17 as a K-12
126
+ * student. So `isFullTimeStudent` is sent as full-time college enrollment,
127
+ * and only from `COLLEGE_MIN_AGE`: sending it for a child would make them a
128
+ * college student (for example, for New Jersey's exemption for dependents
129
+ * attending college), and sending the computed total would take K-12 status
130
+ * away from every other child in the household.
131
+ */
132
+ export const FLAG_TO_VARIABLE: Readonly<Record<keyof USPersonFlags, string>> = {
89
133
  isDisabled: 'is_disabled',
90
134
  isBlind: 'is_blind',
91
- isFullTimeStudent: 'is_full_time_student',
135
+ isFullTimeStudent: 'is_full_time_college_student',
92
136
  isPregnant: 'is_pregnant',
93
137
  needsCare: 'is_incapable_of_self_care',
94
138
  };
95
139
 
96
- const INCOME_TO_VARIABLE: Record<keyof USPersonIncomes, string> = {
140
+ /**
141
+ * The youngest age at which `isFullTimeStudent` is sent. PolicyEngine US's
142
+ * `is_in_k12_school` covers ages 5 to 17, so a full-time student aged 18 or
143
+ * over is taken to be in college. A person with no age is sent the flag,
144
+ * because the model then assumes an adult age.
145
+ */
146
+ export const COLLEGE_MIN_AGE = 18;
147
+
148
+ /**
149
+ * An entered 0 in `ssiAmount` is sent as this variable, set to false. It is an
150
+ * input (default true), so it sets that person's SSI to 0 without affecting
151
+ * anyone else. In policyengine-us 1.764.6 only `ssi` reads it. In 2.49.2,
152
+ * the shared state-supplement helper and a county General Relief rule read it
153
+ * too, so a 0 also means no supplement from that helper. Some states compute
154
+ * their own supplement from federal SSI instead: California's is its payment
155
+ * standard less SSI and countable income, so a 0 raises it.
156
+ */
157
+ export const SSI_TAKE_UP_VARIABLE = 'takes_up_ssi_if_eligible';
158
+
159
+ /**
160
+ * Person income fields and the PolicyEngine US variables they set. Exported
161
+ * for tests and tooling; not part of the package entry points.
162
+ *
163
+ * Where PolicyEngine US defines a variable as the sum of components (`adds`),
164
+ * an input on the total replaces that sum: components sent alongside it are
165
+ * left out of the total and everything computed from it, and components not
166
+ * sent read as zero where rules use them directly. `social_security` adds
167
+ * retirement, disability, survivors, and dependents benefits, so
168
+ * `socialSecurityIncome` sets `social_security_retirement` and `ssdiAmount`
169
+ * sets `social_security_disability`; the model sums them.
170
+ *
171
+ * Likewise `taxable_pension_income` adds public and private pensions, and
172
+ * state rules read those components. `publicPensionIncome` and
173
+ * `privatePensionIncome` set them. A pension of unknown source
174
+ * (`pensionIncome`) is sent as private. Fields that share a variable are
175
+ * summed. Numeric strings are read as numbers and other amounts that are not
176
+ * finite numbers are skipped, so a bad value in one field cannot corrupt a
177
+ * shared sum.
178
+ *
179
+ * `ssi` is computed, so `ssiAmount` follows the household rule above: the
180
+ * amounts are sent as `ssi` for everyone when every person has one, and
181
+ * otherwise the model computes everyone's SSI. `validate()` asks for the
182
+ * missing amounts in that case.
183
+ *
184
+ * Three totals are set directly: `employment_income`, `self_employment_income`
185
+ * and `long_term_capital_gains`. Each adds an input and a behavioral response,
186
+ * and PolicyEngine US's Simulation moves an input on the total onto that
187
+ * component input (`employment_income_before_lsr`,
188
+ * `self_employment_income_before_lsr`, `long_term_capital_gains_before_response`).
189
+ *
190
+ * `tests/us-household/v1PayloadInvariants.test.ts` checks this mapping against
191
+ * the PolicyEngine US variable graph, including the few totals that are safe
192
+ * to set directly.
193
+ */
194
+ export const INCOME_TO_VARIABLE: Readonly<Record<keyof USPersonIncomes, string>> = {
97
195
  employmentIncome: 'employment_income',
196
+ tipIncome: 'tip_income',
98
197
  selfEmploymentIncome: 'self_employment_income',
99
- socialSecurityIncome: 'social_security',
198
+ socialSecurityIncome: 'social_security_retirement',
100
199
  ssiAmount: 'ssi',
101
200
  ssdiAmount: 'social_security_disability',
102
- pensionIncome: 'taxable_pension_income',
201
+ pensionIncome: 'taxable_private_pension_income',
202
+ publicPensionIncome: 'taxable_public_pension_income',
203
+ privatePensionIncome: 'taxable_private_pension_income',
103
204
  dividendIncome: 'qualified_dividend_income',
205
+ nonQualifiedDividendIncome: 'non_qualified_dividend_income',
206
+ shortTermCapitalGains: 'short_term_capital_gains',
207
+ longTermCapitalGains: 'long_term_capital_gains',
104
208
  taxableInterestIncome: 'taxable_interest_income',
105
209
  rentalIncome: 'rental_income',
106
210
  unemploymentCompensation: 'unemployment_compensation',
@@ -108,6 +212,58 @@ const INCOME_TO_VARIABLE: Record<keyof USPersonIncomes, string> = {
108
212
  miscellaneousIncome: 'miscellaneous_income',
109
213
  };
110
214
 
215
+ /**
216
+ * Income fields that PolicyEngine US also counts inside another variable, and
217
+ * that variable. Exported for tests and tooling; not part of the package entry
218
+ * points.
219
+ *
220
+ * PolicyEngine US counts tips as part of wages: `employment_income` is wages
221
+ * "including tips and commissions", and income and payroll taxes read it
222
+ * (through `irs_employment_income` and `payroll_tax_gross_wages`). A few rules
223
+ * read `tip_income` on its own: the qualified tips deduction, Georgia's cash
224
+ * tip exclusion, and Washington's long-term care premium (which subtracts it
225
+ * from wages). So `tipIncome` is sent as `tip_income` and also added to
226
+ * `employment_income`; without the second, tips would be deducted but never
227
+ * taxed. One rule departs from this convention: Florida School Readiness
228
+ * adds `tip_income` to `employment_income` and so counts tips twice
229
+ * (PolicyEngine/policyengine-us#10262).
230
+ */
231
+ export const INCOME_ALSO_ADDED_TO: Readonly<Partial<Record<keyof USPersonIncomes, string>>> = {
232
+ tipIncome: 'employment_income',
233
+ };
234
+
235
+ /**
236
+ * Person expense fields and the PolicyEngine US input variables they set.
237
+ * Exported for tests and tooling; not part of the package entry points.
238
+ *
239
+ * `mortgageInterest` sets `home_mortgage_interest`, the input. PolicyEngine US
240
+ * computes `mortgage_interest` as the sum of deductible and non-deductible
241
+ * interest, and its federal interest deduction reads the input, so an amount
242
+ * sent as `mortgage_interest` changes no federal deduction. (North Carolina,
243
+ * Hawaii and Alabama rules read the computed total, which includes the input.)
244
+ */
245
+ export const EXPENSE_TO_VARIABLE: Readonly<Record<keyof USPersonExpenses, string>> = {
246
+ charitableCashDonations: 'charitable_cash_donations',
247
+ mortgageInterest: 'home_mortgage_interest',
248
+ realEstateTaxes: 'real_estate_taxes',
249
+ };
250
+
251
+ /**
252
+ * `tippedOccupationCode` is sent as this variable, an integer input whose
253
+ * default 0 means no listed occupation. Only listed codes and 0 are sent.
254
+ * Amounts are sent as entered and checked by `validate()`, but an unlisted
255
+ * code is dropped: the model reads any code above 0 as a listed occupation,
256
+ * so a stray one would claim the deduction.
257
+ */
258
+ export const TIPPED_OCCUPATION_VARIABLE = 'treasury_tipped_occupation_code';
259
+
260
+ /** Every amount field, with each variable it is added to. */
261
+ const AMOUNT_TO_VARIABLES: ReadonlyArray<[string, string]> = [
262
+ ...Object.entries(INCOME_TO_VARIABLE),
263
+ ...(Object.entries(INCOME_ALSO_ADDED_TO) as Array<[string, string]>),
264
+ ...Object.entries(EXPENSE_TO_VARIABLE),
265
+ ];
266
+
111
267
  function yearMap(year: string, value: number | string | boolean): V1ValueMap {
112
268
  return { [year]: value };
113
269
  }
@@ -119,27 +275,50 @@ function buildPersonVariables(person: USPersonDraft, year: string): V1PersonReco
119
275
  record.age = yearMap(year, person.age);
120
276
  }
121
277
 
122
- if (person.kind === 'dependent') {
123
- record.is_tax_unit_dependent = yearMap(year, true);
124
- }
278
+ // Every person has a kind, so every person carries this computed variable.
279
+ record.is_tax_unit_dependent = yearMap(year, person.kind === 'dependent');
125
280
 
281
+ // Children's student status comes from the model's K-12 age rule.
282
+ const age = toAmount(person.age);
283
+ const belowCollegeAge = age !== undefined && age < COLLEGE_MIN_AGE;
126
284
  for (const [draftKey, variable] of Object.entries(FLAG_TO_VARIABLE)) {
127
285
  const value = (person as USPersonDraft)[draftKey as keyof USPersonFlags];
128
- if (value !== undefined) {
286
+ if (draftKey === 'isFullTimeStudent' && belowCollegeAge) {
287
+ continue;
288
+ }
289
+ if (typeof value === 'boolean') {
129
290
  record[variable] = yearMap(year, value);
130
291
  }
131
292
  }
132
293
 
133
- for (const [draftKey, variable] of Object.entries(INCOME_TO_VARIABLE)) {
134
- const value = (person as USPersonDraft)[draftKey as keyof USPersonIncomes];
135
- if (value !== undefined && value !== null) {
136
- record[variable] = yearMap(year, value);
294
+ for (const [draftKey, variable] of AMOUNT_TO_VARIABLES) {
295
+ const value = toAmount((person as unknown as Record<string, unknown>)[draftKey]);
296
+ if (value !== undefined && draftKey !== 'ssiAmount') {
297
+ const sharedWith = record[variable]?.[year];
298
+ const total = typeof sharedWith === 'number' ? sharedWith + value : value;
299
+ record[variable] = yearMap(year, total);
137
300
  }
138
301
  }
139
302
 
303
+ const occupationCode = toTippedOccupationCode(person.tippedOccupationCode);
304
+ if (occupationCode !== undefined) {
305
+ record[TIPPED_OCCUPATION_VARIABLE] = yearMap(year, occupationCode);
306
+ }
307
+
140
308
  return record;
141
309
  }
142
310
 
311
+ /**
312
+ * Build the PolicyEngine API V1 household payload for a draft. Everyone shares
313
+ * one family, tax unit, SPM unit and household. Check the draft with
314
+ * `validate()` first:
315
+ *
316
+ * - A person with no age is sent without one, and PolicyEngine US then uses
317
+ * its default age of 40 (`validate()` requires ages by default).
318
+ * - SSI amounts are sent only when every person has one. If some are
319
+ * missing, the entered amounts are dropped and the model computes
320
+ * everyone's SSI (`validate()` reports `person.ssiAmount.requiredWhenAnyReceives`).
321
+ */
143
322
  export function toV1HouseholdPayload(
144
323
  draft: USHouseholdDraft,
145
324
  options: ToV1PayloadOptions = {},
@@ -150,10 +329,24 @@ export function toV1HouseholdPayload(
150
329
 
151
330
  const memberIds = draft.people.map((person) => person.id);
152
331
 
332
+ // `ssi` goes to everyone or no one; see the note above FLAG_TO_VARIABLE.
333
+ const ssiAmounts = draft.people.map((person) => toAmount(person.ssiAmount));
334
+ const sendSsi =
335
+ ssiAmounts.every((amount) => amount !== undefined) &&
336
+ ssiAmounts.some((amount) => amount !== 0);
337
+
153
338
  const people: V1PersonCollection = {};
154
- for (const person of draft.people) {
155
- people[person.id] = buildPersonVariables(person, year);
156
- }
339
+ draft.people.forEach((person, index) => {
340
+ const record = buildPersonVariables(person, year);
341
+ const ssiAmount = ssiAmounts[index];
342
+ if (ssiAmount === 0) {
343
+ record[SSI_TAKE_UP_VARIABLE] = yearMap(year, false);
344
+ }
345
+ if (sendSsi && ssiAmount !== undefined) {
346
+ record[INCOME_TO_VARIABLE.ssiAmount] = yearMap(year, ssiAmount);
347
+ }
348
+ people[person.id] = record;
349
+ });
157
350
 
158
351
  const householdRecord: V1GroupRecord = {
159
352
  members: [...memberIds],
@@ -0,0 +1,10 @@
1
+ /**
2
+ * An entered amount as a finite number, or `undefined` when nothing usable was
3
+ * entered. Drafts parsed from JSON or forms can carry numeric strings, null,
4
+ * NaN, or Infinity. `validate()` and the V1 adapter both use this, so they
5
+ * agree on which amounts count as entered.
6
+ */
7
+ export function toAmount(value: unknown): number | undefined {
8
+ const amount = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
9
+ return typeof amount === 'number' && Number.isFinite(amount) ? amount : undefined;
10
+ }
@@ -2,9 +2,11 @@ export type {
2
2
  USHouseholdDraft,
3
3
  USMaritalStatus,
4
4
  USPersonDraft,
5
+ USPersonExpenses,
5
6
  USPersonFlags,
6
7
  USPersonIncomes,
7
8
  USPersonKind,
9
+ USPersonOccupation,
8
10
  ValidationIssue,
9
11
  ValidationResult,
10
12
  } from './types';
@@ -34,6 +36,15 @@ export {
34
36
  type USState,
35
37
  } from './states';
36
38
 
39
+ export {
40
+ NOT_A_TIPPED_OCCUPATION,
41
+ TIPPED_OCCUPATIONS,
42
+ getTippedOccupation,
43
+ isTippedOccupationCode,
44
+ toTippedOccupationCode,
45
+ type TippedOccupation,
46
+ } from './tippedOccupations';
47
+
37
48
  export {
38
49
  getCountiesByState,
39
50
  getCountyName,
@@ -1,5 +1,6 @@
1
1
  import { resolveCountyCode } from './counties';
2
2
  import { getStateFromZip, isUSStateCode } from './states';
3
+ import { toTippedOccupationCode } from './tippedOccupations';
3
4
  import { DEFAULT_HOUSEHOLD_YEAR, createBlankDraft } from './draft';
4
5
  import type {
5
6
  USHouseholdDraft,
@@ -68,6 +69,29 @@ interface LegacyPerson {
68
69
  ssiAmount?: number;
69
70
  ssdiAmount?: number;
70
71
  social_security_annual?: number;
72
+ pensionIncome?: number;
73
+ pension_income_annual?: number;
74
+ publicPensionIncome?: number;
75
+ public_pension_income_annual?: number;
76
+ privatePensionIncome?: number;
77
+ private_pension_income_annual?: number;
78
+ tipIncome?: number;
79
+ tip_income?: number;
80
+ nonQualifiedDividendIncome?: number;
81
+ non_qualified_dividend_income?: number;
82
+ shortTermCapitalGains?: number;
83
+ short_term_capital_gains?: number;
84
+ longTermCapitalGains?: number;
85
+ long_term_capital_gains?: number;
86
+ charitableCashDonations?: number;
87
+ charitable_cash_donations?: number;
88
+ mortgageInterest?: number;
89
+ home_mortgage_interest?: number;
90
+ mortgage_interest?: number;
91
+ realEstateTaxes?: number;
92
+ real_estate_taxes?: number;
93
+ tippedOccupationCode?: number | string;
94
+ treasury_tipped_occupation_code?: number | string;
71
95
  }
72
96
 
73
97
  interface LegacyDraftShape {
@@ -107,8 +131,13 @@ function coerceNumber(value: unknown): number | undefined {
107
131
  return Number.isFinite(parsed) ? parsed : undefined;
108
132
  }
109
133
 
134
+ function positiveOrUndefined(value: unknown): number | undefined {
135
+ const parsed = coerceNumber(value);
136
+ return parsed !== undefined && parsed > 0 ? parsed : undefined;
137
+ }
138
+
110
139
  function coerceBoolean(value: unknown): boolean | undefined {
111
- if (value === undefined) {
140
+ if (value === undefined || value === null) {
112
141
  return undefined;
113
142
  }
114
143
  return Boolean(value);
@@ -121,6 +150,16 @@ function normalizePerson(
121
150
  ): USPersonDraft {
122
151
  const id =
123
152
  kind === 'adult' ? `adult-${ordinal}` : `dependent-${ordinal}`;
153
+ const tips = coerceNumber(legacy.tipIncome) ?? coerceNumber(legacy.tip_income);
154
+ // Legacy `employment_income` and `earned_income` follow PolicyEngine US,
155
+ // where wages include tips; the draft's `employmentIncome` excludes them,
156
+ // because the V1 adapter adds `tipIncome` back. So tips come out of a
157
+ // legacy wage total, and the payload's `employment_income` equals the
158
+ // legacy figure. A camelCase `employmentIncome` is already the draft's.
159
+ // Tips above the legacy total leave negative wages, which `validate()`
160
+ // flags (`person.employmentIncome.negative`) so the app can ask.
161
+ const legacyWages =
162
+ coerceNumber(legacy.employment_income) ?? coerceNumber(legacy.earned_income);
124
163
  return {
125
164
  id,
126
165
  kind,
@@ -134,12 +173,48 @@ function normalizePerson(
134
173
  needsCare: coerceBoolean(legacy.needsCare ?? legacy.is_incapable_of_self_care),
135
174
  employmentIncome:
136
175
  coerceNumber(legacy.employmentIncome) ??
137
- coerceNumber(legacy.employment_income) ??
138
- coerceNumber(legacy.earned_income),
176
+ (legacyWages === undefined ? undefined : legacyWages - (tips ?? 0)),
139
177
  selfEmploymentIncome: coerceNumber(legacy.self_employment_income_annual),
140
- ssiAmount: coerceNumber(legacy.ssiAmount ?? legacy.ssi_amount),
178
+ // Legacy snake_case drafts (cliff-watch) default `ssi_amount` to 0 and
179
+ // send SSI only when it is positive, so their 0 means "not entered".
180
+ ssiAmount: coerceNumber(legacy.ssiAmount) ?? positiveOrUndefined(legacy.ssi_amount),
141
181
  ssdiAmount: coerceNumber(legacy.ssdiAmount ?? legacy.ssdi_amount),
182
+ // `socialSecurityIncome` excludes SSDI; a legacy total that includes it
183
+ // would count SSDI twice next to `ssdiAmount`.
142
184
  socialSecurityIncome: coerceNumber(legacy.social_security_annual),
185
+ // A legacy pension with no source stays in the unknown-source field
186
+ // rather than being guessed as public or private. The three fields are
187
+ // disjoint: a legacy total that already includes the public or private
188
+ // amount would count it twice.
189
+ pensionIncome: coerceNumber(legacy.pensionIncome ?? legacy.pension_income_annual),
190
+ publicPensionIncome: coerceNumber(
191
+ legacy.publicPensionIncome ?? legacy.public_pension_income_annual,
192
+ ),
193
+ privatePensionIncome: coerceNumber(
194
+ legacy.privatePensionIncome ?? legacy.private_pension_income_annual,
195
+ ),
196
+ tipIncome: tips,
197
+ nonQualifiedDividendIncome: coerceNumber(
198
+ legacy.nonQualifiedDividendIncome ?? legacy.non_qualified_dividend_income,
199
+ ),
200
+ shortTermCapitalGains: coerceNumber(
201
+ legacy.shortTermCapitalGains ?? legacy.short_term_capital_gains,
202
+ ),
203
+ longTermCapitalGains: coerceNumber(
204
+ legacy.longTermCapitalGains ?? legacy.long_term_capital_gains,
205
+ ),
206
+ charitableCashDonations: coerceNumber(
207
+ legacy.charitableCashDonations ?? legacy.charitable_cash_donations,
208
+ ),
209
+ // A legacy `mortgage_interest` is the interest the user paid, written to
210
+ // PolicyEngine US's computed total by mistake; it belongs in the input.
211
+ mortgageInterest: coerceNumber(
212
+ legacy.mortgageInterest ?? legacy.home_mortgage_interest ?? legacy.mortgage_interest,
213
+ ),
214
+ realEstateTaxes: coerceNumber(legacy.realEstateTaxes ?? legacy.real_estate_taxes),
215
+ tippedOccupationCode: toTippedOccupationCode(
216
+ legacy.tippedOccupationCode ?? legacy.treasury_tipped_occupation_code,
217
+ ),
143
218
  };
144
219
  }
145
220
 
@@ -10,6 +10,8 @@ import type { USHouseholdDraft, USPersonDraft } from './types';
10
10
  * &p=adult:35:e50000,adult:33:e20000,dep:6`
11
11
  *
12
12
  * Fields are pipe-separated within each person; people are comma-separated.
13
+ * Only the keys below are written: other person fields, such as tips,
14
+ * investment income and expenses, are dropped from links for now.
13
15
  * Income/flag keys are single letters to keep the URL short:
14
16
  * - `e` = employmentIncome
15
17
  * - `s` = ssiAmount
@@ -42,7 +44,9 @@ function serializePerson(person: USPersonDraft): string {
42
44
  ];
43
45
  for (const [key, letter] of INCOME_KEYS) {
44
46
  const value = person[key] as number | undefined;
45
- if (value !== undefined && value !== null && value !== 0) {
47
+ // An SSI amount of 0 is an answer ("receives none") that the V1 adapter
48
+ // sends; other zero amounts give the same results as a blank.
49
+ if (value !== undefined && value !== null && (value !== 0 || key === 'ssiAmount')) {
46
50
  segments.push(`${letter}${value}`);
47
51
  }
48
52
  }
@@ -0,0 +1,145 @@
1
+ /**
2
+ * Treasury Tipped Occupation Codes (TTOCs): the occupations whose tips can
3
+ * qualify for the federal deduction for qualified tips (26 U.S.C. 224) in tax
4
+ * years 2025 through 2028.
5
+ *
6
+ * Source: Table 1 to paragraph (h) of 26 CFR 1.224-1, "Occupations that
7
+ * Customarily and Regularly Received Tips on or Before December 31, 2024",
8
+ * final regulations T.D. 10044, Internal Revenue Bulletin 2026-18
9
+ * (April 27, 2026), https://www.irs.gov/pub/irs-irbs/irb26-18.pdf. The final
10
+ * table lists 71 occupations; it adds 509, 510 and 810 to the proposed
11
+ * regulations' list (IRB 2025-42) and renames 103, 506 and 606. Labels are the
12
+ * table's occupation titles in sentence case.
13
+ *
14
+ * PolicyEngine US reads the code as `treasury_tipped_occupation_code`, where 0
15
+ * means the person did not receive tips in a listed occupation. Its deduction
16
+ * checks only that the code is above 0, so the code itself does not change
17
+ * results; the list lets apps ask the question the law asks.
18
+ */
19
+
20
+ export interface TippedOccupation {
21
+ /** Treasury Tipped Occupation Code. */
22
+ code: number;
23
+ /** Occupation title, in sentence case. */
24
+ label: string;
25
+ /** The table's category heading, in sentence case. */
26
+ category: string;
27
+ }
28
+
29
+ /** The code for "no listed occupation", which PolicyEngine US also uses. */
30
+ export const NOT_A_TIPPED_OCCUPATION = 0;
31
+
32
+ const CATEGORIES: Record<number, string> = {
33
+ 1: 'Beverage and food service',
34
+ 2: 'Entertainment and events',
35
+ 3: 'Hospitality and guest services',
36
+ 4: 'Home services',
37
+ 5: 'Personal services',
38
+ 6: 'Personal appearance and wellness',
39
+ 7: 'Recreation and instruction',
40
+ 8: 'Transportation and delivery',
41
+ };
42
+
43
+ const TITLES: ReadonlyArray<[number, string]> = [
44
+ [101, 'Bartenders'],
45
+ [102, 'Wait staff'],
46
+ [103, 'Food or beverage servers, non-restaurant'],
47
+ [104, 'Dining room and cafeteria attendants and bartender helpers'],
48
+ [105, 'Chefs and cooks'],
49
+ [106, 'Food preparation workers'],
50
+ [107, 'Fast food and counter workers'],
51
+ [108, 'Dishwashers'],
52
+ [109, 'Host staff, restaurant, lounge, and coffee shop'],
53
+ [110, 'Bakers'],
54
+ [201, 'Gambling dealers'],
55
+ [202, 'Gambling change persons and booth cashiers'],
56
+ [203, 'Gambling cage workers'],
57
+ [204, 'Gambling and sports book writers and runners'],
58
+ [205, 'Dancers'],
59
+ [206, 'Musicians and singers'],
60
+ [207, 'Disc jockeys, except radio'],
61
+ [208, 'Entertainers and performers'],
62
+ [209, 'Digital content creators'],
63
+ [210, 'Ushers, lobby attendants, and ticket takers'],
64
+ [211, 'Locker room, coatroom, and dressing room attendants'],
65
+ [301, 'Baggage porters and bellhops'],
66
+ [302, 'Concierges'],
67
+ [303, 'Hotel, motel, and resort desk clerks'],
68
+ [304, 'Maids and housekeeping cleaners'],
69
+ [401, 'Home maintenance and repair workers'],
70
+ [402, 'Home landscaping and groundskeeping workers'],
71
+ [403, 'Home electricians'],
72
+ [404, 'Home plumbers'],
73
+ [405, 'Home heating and air conditioning mechanics and installers'],
74
+ [406, 'Home appliance installers and repairers'],
75
+ [407, 'Home cleaning service workers'],
76
+ [408, 'Locksmiths'],
77
+ [409, 'Roadside assistance workers'],
78
+ [501, 'Personal care and service workers'],
79
+ [502, 'Private event planners'],
80
+ [503, 'Private event and portrait photographers'],
81
+ [504, 'Private event videographers'],
82
+ [505, 'Event officiants'],
83
+ [506, 'Pet and show animal caretakers'],
84
+ [507, 'Tutors'],
85
+ [508, 'Nannies and babysitters'],
86
+ [509, 'Visual artists'],
87
+ [510, 'Floral designers'],
88
+ [601, 'Skincare specialists'],
89
+ [602, 'Massage therapists'],
90
+ [603, 'Barbers, hairdressers, hairstylists, and cosmetologists'],
91
+ [604, 'Shampooers'],
92
+ [605, 'Manicurists and pedicurists'],
93
+ [606, 'Eyebrow and eyelash technicians'],
94
+ [607, 'Makeup artists'],
95
+ [608, 'Exercise trainers and group fitness instructors'],
96
+ [609, 'Tattoo artists and piercers'],
97
+ [610, 'Tailors'],
98
+ [611, 'Shoe and leather workers and repairers'],
99
+ [701, 'Golf caddies'],
100
+ [702, 'Self-enrichment teachers'],
101
+ [703, 'Recreational and tour pilots'],
102
+ [704, 'Tour guides'],
103
+ [705, 'Travel guides'],
104
+ [706, 'Sports and recreation instructors'],
105
+ [801, 'Parking and valet attendants'],
106
+ [802, 'Taxi and rideshare drivers and chauffeurs'],
107
+ [803, 'Shuttle drivers'],
108
+ [804, 'Goods delivery people'],
109
+ [805, 'Personal vehicle and equipment cleaners'],
110
+ [806, 'Private and charter bus drivers'],
111
+ [807, 'Water taxi operators and charter boat workers'],
112
+ [808, 'Rickshaw, pedicab, and carriage drivers'],
113
+ [809, 'Home movers'],
114
+ [810, 'Gas pump attendant'],
115
+ ];
116
+
117
+ /** Every listed occupation, in code order. */
118
+ export const TIPPED_OCCUPATIONS: ReadonlyArray<TippedOccupation> = TITLES.map(
119
+ ([code, label]) => ({ code, label, category: CATEGORIES[Math.floor(code / 100)] }),
120
+ );
121
+
122
+ const BY_CODE = new Map(TIPPED_OCCUPATIONS.map((occupation) => [occupation.code, occupation]));
123
+
124
+ export function getTippedOccupation(code: number): TippedOccupation | undefined {
125
+ return BY_CODE.get(code);
126
+ }
127
+
128
+ export function isTippedOccupationCode(code: unknown): code is number {
129
+ return typeof code === 'number' && BY_CODE.has(code);
130
+ }
131
+
132
+ /**
133
+ * An entered occupation code as a number the V1 adapter sends: a listed code,
134
+ * or 0 for "not a listed occupation". Strings of decimal digits are read as
135
+ * numbers. Anything else, including codes the table does not list, reads as
136
+ * not answered, so a stray value cannot claim the deduction.
137
+ */
138
+ export function toTippedOccupationCode(value: unknown): number | undefined {
139
+ const code = typeof value === 'string' && /^\s*\d+\s*$/.test(value) ? Number(value) : value;
140
+ if (code === NOT_A_TIPPED_OCCUPATION) {
141
+ // Also reads -0 as 0.
142
+ return NOT_A_TIPPED_OCCUPATION;
143
+ }
144
+ return isTippedOccupationCode(code) ? code : undefined;
145
+ }